| name | managing-requirement-lifecycle |
| description | 需求全生命周期管理伞形 Skill，被 8 个 /requirement:* 命令共用。负责状态持久化、PR 提交、归档；阶段切换在 F-012 落地前仍由本 Skill 承载，落地后将统一到 /workflow:next |
什么时候用
用户通过 /requirement:* 命令，或口头说"新建需求 / 继续需求 / 保存进度 / 查看状态 / 回退 / 列出需求 / 提交 PR / 归档"时。
F-012 现状（hotfix 后修订）：/workflow:next 命令尚未落地（workflow main loop 仍是 stub）。
在 F-012 落地之前，阶段切换 + PHASE_REQUIREMENTS 校验链仍由本 Skill 承担（用户在主对话中
说明意图 → 本 Skill 写 meta.yaml.phase + 跑 scripts/gates/run.py --trigger=phase-transition）。
F-012 落地后将统一到 standard-8phase yaml workflow 的 phase-transition 节点；下文凡出现
/workflow:next [F-012 待落地] 的描述均按此规则解读。
核心流程
-
识别意图：映射到 8 个子动作之一
- 新建 → bootstrap（创建分支+目录+meta.yaml，委托
requirement-bootstrapper）
- 继续 → 委托
requirement-session-restorer
- 保存 → 委托
requirement-progress-logger
- 查看状态 → 读 meta.yaml 输出阶段+最近动作
- 回退 → 归档当前 artifacts + 改 phase + 写 notes.md
- 列出 → 扫
requirements/*/meta.yaml，输出需求索引
- 提交 PR → 按
reference/submit-rules.md 做前置门禁、推分支、开 PR、回写 pr_url / pr_number。默认走 codex review-loop（2026-05-21 翻转，详 reference/submit-rules.md §7.5）；用户显式传 --no-codex 才跳过。包装层负责向底层 submit_codex.py 追加 --codex flag，底层 CLI 默认值仍 opt-in。
- 归档 → archive（phase=testing|completed → completed + archived_at；委托
archive_runner.archive_requirement）
-
状态持久化：每次状态变更必须更新 meta.yaml 字段；submit 动作只回写 PR 字段，不改 phase
-
门禁校验：submit 走 reference/gate-checklist.md 中的"submit 前置门禁"小节。逐条执行：
bash scripts/... 形式的命令型检查项必须用 Bash 工具真跑（看退出码），文件/字段/标记类
检查项必须 Read/Grep 真验证——禁止"读清单自答通过"
门禁校验补充：派发链强制结构 4 gate
REQ-2026-008 新增以下 4 个 gate，已注册在 scripts/gates/registry.yaml，在对应触发点自动运行：
| Gate | 触发点 | 核心校验 | severity |
|---|
GATE-POST-DEV-RECEIPT | phase-transition（development→testing）/ submit | features.json 中每个 done feature 必须有 artifacts/tasks/<fid>.receipt.json，且 status ∈ {DONE, DONE_WITH_CONCERNS} | error |
GATE-TOUCHES-VIOLATION | phase-transition / submit | 所有 artifacts/tasks/<fid>.receipt.json 的 touches_violations[] 必须为空 | error |
GATE-FEATURES-SCHEMA | pre-commit / phase-transition / submit / ci（changed_files: requirements/*/artifacts/features.json） | features.json 结构符合 features-schema.yaml | error |
GATE-TASK-FRONTMATTER | pre-commit / phase-transition / submit / ci（changed_files: requirements/*/artifacts/tasks/*.md） | task.md frontmatter 符合 task-frontmatter-schema.yaml（含 touches 字段必填） | error |
豁免约束：4 个 gate 均不带 legacy-bypass tag，meta.yaml legacy: true 无法豁免它们。
历史 completed REQ 通过 trigger / changed_files 路径自然隔离，不依赖 legacy 短路（D-005 #2 / D-006 V-07 修订）。
阶段切换：F-012 待落地阶段的过渡处理
设计目标：阶段切换（如 definition → tech-research）统一走 standard-8phase yaml workflow
的 phase-transition 节点；用户入口 /workflow:next [F-012 待落地]。
现状（F-012 落地前）：/workflow:next 命令尚不可用；用户在主对话中说明"切到下一阶段"
后，本 Skill 直接：
- 跑
python3 scripts/gates/run.py --trigger=phase-transition --req=<REQ-ID> --from=<X> --to=<Y>
- error 全过后写
meta.yaml.gates_passed + 切 meta.yaml.phase
- 调
requirement-progress-logger 写 [phase-transition] 事件
如需手动跑某 trigger 的全套门禁（落地前/后通用），仍可用 CLI 直入：
python3 scripts/gates/run.py \
--trigger=phase-transition \
--req=<REQ-ID> \
--from=<from-phase> \
--to=<to-phase>
退出码 0 = 全门禁过；非 0 = 有 error；详见 scripts/gates/registry.yaml。
硬约束
- ❌ 禁止跳过门禁（例：从
definition 直接跳 detail-design，相邻校验由 runner _validate_phase_args 拦下）
- ❌ 禁止在非功能分支上 bootstrap（会被 Hook 拦截）
- ❌ 禁止 submit 推进 phase（PR 合并不代表测试完成，不能跳过 testing 阶段）
- ❌ 禁止"读清单自答通过"——
bash scripts/... 形式的门禁项必须用 Bash 工具真跑；缺退出码或缺 stderr 关键行 = 没跑
- ✅
meta.yaml 更新必须原子：先写临时文件再 mv（避免中间状态）
- ✅ 未知意图必须向用户澄清，不得"猜测"后擅自推进
参考资源
phase-rules.md（8 阶段定义 + 切换规则）已移除——canonical phase 枚举单一事实源在
context/team/engineering-spec/meta-schema.yaml enums.phase；切换规则由 runner
_validate_phase_args + canonical_phases.load_adjacent_phases() 强制实施。
