---
name: requirement-lifecycle-manager
description: Guide the emoon-backend team through its Docs as Code and Git branch lifecycle. Use when starting or advancing a requirement, assigning or checking a feature_id, auditing document gaps, deciding whether work may enter development or merge, creating or checking docs/feature/hotfix/closeout branches, or coordinating requirement documents, reviews, tests, acceptance, and archive records with Git gates.
---

# Requirement Lifecycle Manager

Act as the project-manager layer for requirements. Keep documents, lifecycle state, and Git branches aligned without imposing detailed commit conventions.

## Required Context

Always read:

1. `docs/文档中心.md`
2. `docs/governance/文档分类.md`
3. `docs/governance/元数据规范.md`
4. `docs/governance/生命周期流程.md`

When explaining or operating the team workflow, also read `开发协作说明.md` in this skill directory.

When a `feature_id` is known, read `docs/initiatives/<feature_id>/专题索引.md` and every existing document it references.

Before any Git action, inspect the current branch, worktree, remotes, and divergence from `origin/master`. Do not treat a locally-ahead `master` as the stable baseline.

## Document Lifecycle

Inspect stages in this order:

1. `需求录入.md`
2. `需求文档.md`
3. `概要设计.md`
4. `详细设计.md`
5. ADR when triggered
6. API contract when triggered
7. implementation plan and `开发进度.md`
8. `测试计划.md`
9. `测试结果.md`
10. closeout in `专题索引.md`

Allow a stage to be skipped only when the initiative index records the reason, risk, replacement record, and follow-up requirement.

## Branch Lifecycle

Use one shared feature branch per requirement:

```text
docs/FEAT-YYYYMM-NNN-short-name
  -> master
  -> feature/FEAT-YYYYMM-NNN-short-name
  -> master
  -> docs/FEAT-YYYYMM-NNN-short-name-closeout
  -> master
```

- Protect `master`: never commit directly to it.
- Prepare and review initial requirement documents on `docs/<feature_id>`.
- Merge approved documents to `master` before development.
- Create the shared `feature/<feature_id>` only after `ready_for_development` passes, from the recorded `origin/master` commit.
- Let team members commit directly to the shared feature branch. Do not require task branches or detailed commit-message conventions.
- Never rebase or force-push a published shared feature branch. Merge `master` into it when synchronization is needed.
- Before final review, merge the latest `origin/master` into the feature branch and rerun required verification.
- Merge `feature/<feature_id>` to `master` through a reviewed PR using a merge commit; do not squash or rebase.
- After merge, use `docs/<feature_id>-closeout` to record the merge SHA, final status, test conclusion, and remaining issues. Then the remote feature branch may be deleted with explicit authorization.

Feature branches must not merge into each other. Record cross-feature dependencies by `feature_id`; normally wait for the dependency to reach `master`. For necessary parallel verification, use a disposable `integration/<feature-a>-<feature-b>` branch that never merges directly to `master`.

## Development Gate

Treat `ready_for_development` as a hard gate. Require:

- approved intake and PRD with acceptance criteria and non-goals;
- all triggered outline design, detailed design, ADR, API, and security documents approved;
- approved test plan and an actionable implementation plan;
- no blocking unresolved question in the initiative index;
- clean worktree and confirmed synchronization with `origin/master`;
- proposed branch name and exact baseline commit SHA recorded in the initiative index.

If the gate fails, do not create or push the feature branch. Report the missing prerequisites and offer to complete them, formally record a permitted skip, or keep the work exploratory.

## Merge Gate

Treat `ready_for_merge` as a hard gate. Require:

- latest `origin/master` merged into the feature branch with no unresolved conflict;
- requirements, acceptance criteria, implementation, and required documents aligned;
- planned tests executed and `测试结果.md` records passes, failures, residual risks, and conclusion;
- required Maven compile, module tests, and applicable `AiPlatformArchitectureTest` passed;
- no blocking defect, security issue, or unresolved interface-contract difference;
- human review of the feature-to-master PR.

Do not use commit style, commit count, or history tidiness as merge gates.

## Change, Pause, and Exception Rules

- Keep minor implementation-time document corrections on the feature branch.
- For material scope, acceptance, API, data, security, or architecture changes, pause affected implementation, update documents on the feature branch, and rerun the applicable gate.
- Create a new `feature_id` when a change becomes an independent requirement.
- Use initiative state `paused` for resumable work and keep its remote feature branch. On resume, synchronize `master` and revalidate documents and gates.
- Use initiative state `cancelled` for abandoned work. Never merge incomplete code to `master`; normally delete its feature branch after preserving any explicitly required record.
- For production emergencies, allow `hotfix/<short-name>` from `master` with a lightweight gate: incident description, fix scope, and verification result. Merge through PR, then backfill or link the appropriate `feature_id` records.

## Git Authorization

Read-only inspection and gate evaluation need no extra confirmation. Generating names and commands is also safe.

Require explicit user authorization before creating a branch, committing, pushing, creating or merging a PR, deleting a branch, or otherwise changing remote state. Never automatically merge `master`, force-push, or delete a remote branch. A general instruction to advance the lifecycle authorizes ordinary safe steps, but obtain confirmation again for push, PR merge, and remote branch deletion.

## Triage and Output

When asked what to do next:

1. Identify the `feature_id` and initiative.
2. Inventory document types, statuses, required triggered artifacts, branch state, and recorded SHAs.
3. Evaluate the current document stage and the applicable Git gate.
4. Report the smallest next action and any prohibited transition.

Use this response shape:

```text
当前阶段：...
当前分支：...
已有文档：...
Gate 状态：...
缺口：...
下一步：...
建议动作：...
警示：...
```

## Document Creation

Use templates under `docs/templates/`. Keep Chinese human-readable filenames; keep identifiers and lifecycle state in Front Matter. Fill `doc_id`, `feature_id`, `type`, `title`, `status`, `owner`, `created_at`, `updated_at`, related documents, and affected modules, then update `专题索引.md`.

Never silently skip a document or Git gate.