代码评审

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ IRON LAW · 不可违反的硬门禁

以下规则为不可协商的执行约束：

1. 文件必须落盘：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。
2. 阶段必须落章：每个阶段完成后必须在状态机 docs/.pdlc-state/<feature-id>.json 追加 history，不可跳过。
3. 测试必须存在：进入 /pdlc-implement 前，对应测试必须存在且处于红灯状态。违反则中止。
4. 自检必须执行：段二自检为强制步骤，不得以"已经很好了"为由跳过。
5. 防循环：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。
6. 状态必推进：成功执行某 phase 后 current_stage 必须变更。收尾时若发现 current_stage 未推进，视为失败并报错，不得静默返回（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，current_stage 保持不变但必须写 last_phase_result.ok=false + blocked_reason。

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。 <!-- @include-end templates/prompts/iron-law.md --> <!-- @include templates/prompts/noninteractive.md（已内联于下方，无需另读） -->

非交互模式（--autonomous）

若本命令的参数含 --autonomous，本命令进入无人值守模式，按以下规则处理原本需要人应答的交互点。参数是唯一真源：不带 --autonomous 即为交互模式，一切照旧正常询问用户；绝不回读状态机 run_mode 兜底（「掉出 autonomous」是安全的失败方向）。

1. 流程性确认（如「测试已绿是否继续」「是否覆盖已有文件」）→ 不询问，按预设默认前进，并把决策追加到状态机 history[].auto_decisions[]

（写状态机的命令：推进时给状态推进脚本传 --decision "<确认点描述>=<所选默认>"，可重复；脚本写成下面的样子）：

   { "point": "<确认点描述>", "chose": "<所选默认>", "at": "<ISO 8601>" }

1. 真需人判断（PRD 关键取舍、评审「需人工确认」项、真实循环依赖、测试与设计 / PRD 矛盾等无法安全默认的点）→ 不猜。

改测试、改检查命令让它变绿，永远不是「流程性默认」，不能记成 --decision：

• current_stage 保持不变（不推进）
• 写 last_phase_result.ok = false 且 blocked_reason = "<原因>"（写状态机的命令：给状态推进脚本传 --blocked "<原因>"）
• 末行输出哨兵：<<<PDLC blocked reason="<原因>">>>
• 立即结束命令，交还人类
• 守卫拦截也走这一条：前置守卫（缺设计文档、缺测试、测试没红等）在 --autonomous 下拦住本命令时，

不能只输出 ⛔ 就停——同样写 ok=false + blocked_reason（写明哪条守卫、缺什么）并输出哨兵。 否则状态机里仍是上一阶段的 ok=true，循环驱动只看到 current_stage 没动，会把「被拦」误报成「卡住」，真实原因丢失。

1. 破坏性操作（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ --autonomous 无效，仍必须人工显式确认。
2. 顺手的 sidecar 产物（如缺失时创建 CHANGELOG.md、补全文档 PDLC-TRACE 的创建时间等本阶段职责内、可安全默认的辅助改动）→ 视为流程性默认，直接做并记入 `auto_decisions[]`；这类改动不新增外部副作用，不属破坏性操作。

进入 autonomous 模式时，在状态机顶层写 run_mode: "autonomous" 仅供留痕（复盘区分人工 vs 循环产出）。

<!-- @include-end templates/prompts/noninteractive.md -->

对指定的服务或应用进行全面的代码评审。

先分流：代码评审还是文档评审

• 评审对象是文档（参数是 .md 等文档路径，或明说评审 PRD / 设计 / 测试计划 / 部署手册）→ 直接跳到下文「文档评审」一节。

文档评审不写状态机：它是阶段内的质量关卡，不是主链路上的一个阶段——写了会把功能的 current_stage 改成 review、next_step 改成 pdlc-ship，等于宣称代码已评审。下文的代码评审守卫也不适用

• 其余（功能ID、缺陷ID、服务 / 模块名）→ 代码评审，从下面的前置检查开始

PDLC 前置检查（必须执行，不可跳过）

1. 从用户输入中提取功能 ID 或功能名称关键词。输入是缺陷 ID（B 开头，/pdlc-fix 的下一跳）时，

读 docs/.pdlc-state/<缺陷ID>.json 与 docs/04_testing/defects/ 下对应的缺陷报告，评审对象是这次修复改动的代码

1. 检查实现代码是否存在：在项目的源码目录下搜索与该功能相关的源代码文件（非测试文件）。源码目录按项目实际布局确定

（如 src/、app/、lib/、backend/、frontend/、packages/*/ 等），不要只看某一种布局； 已有状态机时，优先看其 history 里 impl / fix 阶段记下的 produced 路径

1. 检查测试是否通过：找到对应的测试代码并运行，确认测试处于绿灯状态（全部通过）
2. 未找到实现代码 → 输出以下信息后立即停止，不继续执行：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的实现代码。
   评审必须基于已有的代码实现。请先运行：
   👉 /pdlc-implement <目标>

1. 测试未通过 → 输出以下信息后立即停止，不继续执行：

   ⛔ PDLC 守卫：「<功能名>」的测试未全部通过，无法进行评审。
   请先确保所有测试通过后再提交评审：
   👉 /pdlc-implement <目标>（修复失败的测试）

1. 检查通过 → 确定功能ID（输入即 ID 时直接用；否则从相关设计文档或 PRD 中提取；缺陷修复用缺陷ID），继续执行

评审流程

1. 阅读设计文档: 先阅读 docs/02_design/ 对应子目录下的相关设计文档

• 有分批评审记录（docs/07_reviews/code/<功能ID>-*-batch-review.md，实现阶段按任务分批时写的）→ 一并读：

「已修复」的不重复报；「待最终评审」的每一项都要在本次评审里处理——修掉，或写进报告的需人工处理表，不能悄悄漏掉

1. 阅读编码规范: 阅读 docs/00_standards/coding/ 目录了解编码规范（未命中 → 报告里提示 consider /pdlc-standard add coding/<topic>）
2. 检查代码实现: 对照设计文档逐一检查实现是否符合
3. 检查测试覆盖: 确认测试是否充分覆盖
4. 代码质量自动检查与修复（必须执行）：

• 按 /pdlc-lint check 逻辑运行项目 lint 工具
• 若存在可自动修复的问题，按 /pdlc-lint fix 逻辑自动修复
• 记录修复前后的问题数变化

评审检查项（逐项检查，发现问题立即修复）

先判断适用性：下面的清单按 Web 服务写成，不是每个项目都有接口、数据库或页面。 开始前按项目类型（Web 服务 / CLI 工具 / 库 / 桌面应用 / 数据脚本等）与本次改动范围，逐项判断是否适用：

• 适用 → 正常检查，勾选 [x] 或记为问题
• 不适用 → 标 [—] 不适用：<一句话理由>（如「无 HTTP 接口」「本次改动不涉及数据库」）。不适用项不算未通过，也不进自动修复
• 拿不准是否适用 → 按适用检查

设计一致性（对照设计文档）

• [ ] 每个 API 接口的 URL、方法、参数是否与设计文档一致
• [ ] 数据库表结构、字段名、类型是否与 DB 设计一致
• [ ] 响应格式是否符合项目约定的统一格式（以设计文档 / 编码规范为准，如 { code, message, data }）

代码质量

• [ ] 命名是否规范（变量/函数/类遵循项目命名约定）
• [ ] 是否有重复代码可提取为公共方法
• [ ] 错误处理是否合理（不吞异常、不用空 catch、有意义的错误信息）
• [ ] 日志是否充分（关键操作有日志、不打印敏感信息）

安全检查

• [ ] SQL 注入：是否使用参数化查询/ORM，无字符串拼接 SQL
• [ ] XSS：用户输入是否转义后再输出
• [ ] 权限控制：接口是否有鉴权，敏感操作是否有权限校验
• [ ] 敏感数据：密码是否加密存储、Token 是否有过期机制、日志不含敏感字段

性能检查

• [ ] 数据库查询是否有 N+1 问题
• [ ] 列表接口是否有分页
• [ ] 是否有不必要的全表扫描（缺失索引）
• [ ] 大数据量操作是否有批处理

测试完备性

• [ ] 单元测试覆盖率是否达标（覆盖率达标线以项目配置为准：优先取 docs/00_standards/test-commands.yml 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 quality-targets.yml；两者都没有时按 >= 80% 兜底。）
• [ ] 核心业务路径是否有完整的测试
• [ ] CHANGELOG 是否已更新

自动修复（评审中发现的问题，能修则修）

对以下类型的问题直接修复代码，不仅仅记录（只修适用项里发现的问题——标为不适用的检查项，一律不据此改代码； 例如项目没有列表接口，就不会去「补分页」）：

1. lint 问题：运行 lint fix 自动修复格式、规范问题
2. 命名不规范：自动重命名为符合项目约定的名称
3. 缺失错误处理：自动补充 try-catch / 错误码返回
4. 缺失日志：在关键操作处自动添加日志语句
5. SQL 注入风险：自动改写为参数化查询
6. XSS 风险：自动添加输出转义
7. 缺失分页：自动为列表接口补充分页逻辑
8. 缺失 CHANGELOG：自动追加变更条目。条目格式 - <简要描述>（<功能ID 或缺陷ID>）；[未发布] 里已有同一 ID 的条目就不再追加（/pdlc-ship 按 ID 去重）

不可自动修复的问题（记录到评审报告，标记为需人工处理）：

• 架构层面的设计问题
• 业务逻辑的正确性争议
• 需要重大重构的性能问题

评审报告生成

⚠️ 必须创建文件，不可仅在对话中输出。

【必须创建文件】 在 docs/07_reviews/code/ 下创建评审记录：

• 文件名格式: <功能ID>-<功能名>-review.md（如 F20260326-090000-user-auth-review.md）
• 文档顶部必须包含 PDLC 追溯头：

  <!-- PDLC-TRACE -->
  <!-- 功能ID: F20260326-090000 -->
  <!-- 功能名称: user-auth -->
  <!-- 阶段: 评审 -->
  <!-- 前置文档: docs/02_design/api/F20260326-090000-user-auth-api.md -->
  <!-- 创建时间: 2026-03-26T10:30:00 -->

• 报告内容格式：

  ## 评审总结
  - 评审时间：<ISO 8601>
  - 评审范围：<涉及的文件数和代码行数>
  - 问题总数：X 项（阻塞: X / 严重: X / 一般: X / 建议: X）
  - 自动修复：X 项
  - 需人工处理：X 项

  ## 自动修复记录
  | # | 问题类型 | 文件 | 修复内容 |
  |---|---------|------|---------|
  | 1 | lint | src/xxx.ts | 修复 XX 规则违规 |

  ## 需人工处理
  | # | 严重程度 | 问题描述 | 建议方案 |
  |---|---------|---------|---------|
  | 1 | 阻塞 | XXX | 建议 XXX |

  ## 评审检查项结论
  - [x] 设计一致性：通过
  - [x] 代码质量：通过（X 项已自动修复）
  - [ ] 安全检查：X 项需人工确认
  - [—] 性能检查：不适用（<理由>）

1. 修复后验证：自动修复完成后，重新运行全部测试（命令取自 docs/00_standards/test-commands.yml），确认修复未引入新问题

• 测试通过 → 评审完成
• 测试失败 → 回滚修复，将问题标记为需人工处理
• `checks` 不手写：收尾的 scripts/pdlc-advance.sh 会跑 unit、coverage、lint、e2e 并写入（e2e 没配置时为 null，不影响 ok）；

退出码三态语义与「命令跑不了 = yml 过期信号」见下方 check 命令规则

1. 收尾判定（交互与 --autonomous 一致——「评审通过」只有一个定义）：

• 「需人工处理/需人工确认」表中存在阻塞级项 → 不推进：bash scripts/pdlc-advance.sh <功能ID> --stage review --next pdlc-ship --blocked "评审存在阻塞级待人工项" <项目根>；

--autonomous 下另输出 blocked 哨兵交还人类。交互模式下可以把阻塞项列给用户：用户当场明确放行的，在评审报告里记「人工放行：<项> · <理由>」后不再算阻塞

• 仅有非阻塞级人工项 → 记录在案，bash scripts/pdlc-advance.sh <功能ID> --stage review --next pdlc-ship --produced <评审报告> <项目根>：

检查全过才推进到 review → pdlc-ship（评审通过即此状态，不写任何 _done）；检查红了脚本不推进，按阻塞收尾

要求

<!-- @include templates/prompts/output-language.md（已内联于下方，无需另读） --> 🌐 Output language for generated artifacts

All generated artifacts (PRDs, design docs, code comments, review reports, test plans, deployment manuals, changelog entries, etc.) follow this policy:

1. Default — match the conversation language exactly:

• 用户用中文与 Claude 对话 → 产中文文档、中文代码注释、中文报告
• User talks to Claude in English → produce English artifacts
• User talks in another language → produce artifacts in that language
• Never silently default to a fixed language regardless of the user's input.

1. Explicit override always wins: when the user specifies a language for

an artifact (e.g. "write the PRD in English", "用英文写 API 设计文档", "output the deploy doc in Japanese"), use that language for that artifact, regardless of conversation language.

1. Mixed-language requirements: if the user wants some artifacts in one

language and others in a different language (common: Chinese PRD + English API docs for partners), honour each per-artifact instruction.

1. Uncertain: if you cannot reliably detect the conversation language,

ask once before producing the first artifact.

This policy applies to content (prose, comments, headings). It does not override technical conventions like English variable names, English git commit subjects, or English error codes when the project's conventions require them. <!-- @include-end templates/prompts/output-language.md -->

• 问题按严重程度分级：阻塞 / 严重 / 一般 / 建议
• 能修的问题直接修复，不仅仅指出问题
• 修复后必须验证测试仍然通过

评审目标: $ARGUMENTS

文档评审

对指定的文档进行质量评审，检查完整性、一致性和可操作性。发现问题直接修复，而非仅列出建议。

文档评审检查项

#### 完整性

• [ ] 是否覆盖了所有必要章节（对照下方「加载对照物」里对应类型的模板检查）
• [ ] 是否有遗漏的功能点或接口
• [ ] 非功能需求是否有说明
• [ ] 是否有明确的验收标准
• [ ] PDLC 追溯头是否完整（功能ID、功能名称、阶段、前置文档、创建时间）

#### 一致性

• [ ] 术语命名是否前后一致（同一概念不用不同名称）
• [ ] 数据模型是否与 API 设计一致（字段名、类型）
• [ ] 接口参数是否与 PRD 需求对应
• [ ] 版本号和日期是否准确
• [ ] 文档间交叉引用路径是否正确

#### 可操作性

• [ ] 操作步骤是否具体可执行（无模糊表述如「适当配置」「按需调整」）
• [ ] 是否有示例代码或示例数据
• [ ] 错误码是否有清晰的处理建议
• [ ] 部署步骤是否可复现

#### 规范性

• [ ] 是否符合对应模板格式
• [ ] 表格是否完整（无空列、无缺失表头）
• [ ] Markdown 语法是否正确（标题层级、列表缩进、代码块语言标注）
• [ ] 输出语言是否符合用户对话语言（或用户显式指定的语言）

文档自动修复规则（发现即修，不仅记录）

1. 缺失章节：对照模板自动补充，内容根据文档已有信息合理推断
2. PDLC 追溯头缺失或不完整：自动补全缺失字段
3. 术语不一致：统一为文档中首次出现的术语，全文替换
4. 模糊表述：自动改写为具体、可度量的描述
5. 表格格式问题：自动修复空列、对齐问题
6. Markdown 语法错误：自动修复标题层级、列表缩进
7. 交叉引用路径错误：检查引用的文件是否存在，不存在则标注警告
8. 缺失示例：为 API 接口自动补充请求/响应示例

不可自动修复的问题（记录到评审报告）：

• 业务逻辑的正确性争议
• 需要与产品确认的需求歧义
• 涉及跨文档架构调整的问题

文档评审工作流程

1. 识别文档类型：判断文档属于 PRD / API 设计 / DB 设计 / 架构设计 / 测试计划 / 部署手册
2. 加载对照物：

• 加载对应类型的模板（均在本 skill 目录下）：PRD → assets/prd-template.md、API 设计 → assets/api-design-template.md、DB 设计 → assets/db-design-template.md、架构设计 → assets/arch-design-template.md、测试计划 → assets/test-plan-template.md、部署手册 → assets/deploy-doc-template.md
• 加载前置文档（从 PDLC-TRACE 中获取路径）
• 如是设计文档，同时加载 PRD 进行交叉比对

1. 逐项检查：按上方检查项逐一执行
2. 自动修复：发现问题直接修改原文档
3. 【必须创建文件】生成评审记录：在 docs/07_reviews/doc/ 下创建评审记录

• 文件名格式: <功能ID>-<功能名>-<文档类型>-doc-review.md
• 报告格式：

     ## 文档评审报告
     - 评审时间：<ISO 8601>
     - 目标文档：<文档路径>
     - 文档类型：<PRD/API设计/DB设计/...>
     - 问题总数：X 项（必须修改: X / 建议修改: X / 可选: X）
     - 自动修复：X 项
     - 需人工确认：X 项

     ## 自动修复记录
     | # | 问题类型 | 修复内容 |
     |---|---------|---------|
     | 1 | 缺失章节 | 补充了「非功能需求」章节 |

     ## 需人工确认
     | # | 严重程度 | 问题描述 | 建议 |
     |---|---------|---------|------|
     | 1 | 必须修改 | XXX 需求存在歧义 | 建议与产品确认 |

     ## 检查项结论
     - [x] 完整性：通过
     - [x] 一致性：通过（X 项已修复）
     - [x] 可操作性：通过
     - [x] 规范性：通过

• 修复后仅复查一次（确认修复未引入新问题），不再递归修复。若复查仍发现问题，记录到评审报告的「需人工确认」中

<!-- @include templates/prompts/check-commands.md（已内联于下方，无需另读） -->

跑 check 命令：退出码的三态语义

用脚本跑，不要手写 `checks`：

bash scripts/pdlc-checks.sh --only <本阶段要的项，如 unit,lint> <项目根>

脚本是本 skill 自带的 scripts/pdlc-checks.sh。它读 docs/00_standards/test-commands.yml（唯一真源），逐条真跑，按下表映射，stdout 只有一行 JSON—— 原样写进 last_phase_result.checks，不改键名、不改值、不补不删。每条命令的退出码与输出末尾回显在 stderr，报告里引用那几行即可。脚本退出码 2（没有 yml 等）= 没有可跑的 check → checks: {}。

为什么不手写：键名、布尔类型、三态这几件事是确定性的，交给模型写，真机上同一份项目轮与轮之间就换一种错法 （键名照抄 yml 的 unit、值写成 "4 passed, 1 failed"、127 写成 false）。 环境里没有 bash 时才按下表手工映射。

脚本按退出码分三态——不是两态。这是 IRON LAW「checks 只认客观事实」在执行层的落法：

⛔ 唯一的红线是不许写 `false`：那是会误导人的虚报——它说的是"检查失败了"， 于是有人去查代码，但真正的问题是配置过期，代码可能完全没毛病。

>

省略键与 `null` 等价，两种都可以：对消费方而言无法区分（jq '.checks.lint_clean' 在两种情况下都返回 null）。null 甚至更明确——省略是歧义的（"没看"还是"看了判不出"）， null 明说"看了，判不出"。别在这上面纠结，力气花在不写 `false` 上。

>

这与「没有检查命令可跑的阶段 → checks: {}」同源。

「跑不了」＝ test-commands.yml 过期信号（顺带检测，零额外成本）

命令跑不起来，几乎总意味着这份 yml 已经跟不上项目了——脚本改名、runner 换了、 工具从依赖里移除、子项目路径调整。真实项目里这类漂移是常态（例如某前端框架升级后 移除了内置 lint 子命令，而 yml 里那条命令还在）。

由于各阶段本来就在跑这些命令，这个信号是白捡的。检测到时：

1. 在本阶段的报告里单列一条：「`test-commands.yml` 疑似过期」，写明是哪一项、

观察到什么（退出码 / 报错原文）、以及为什么判定为"跑不了"而非"没通过"。

1. 提示补救：/pdlc-test-setup --refresh（重新探测并给出 diff）。
2. 不要自作主张改 yml——本阶段的职责是干活，不是改配置；只报告，不动手。

变更方向决定自动化程度（--refresh 时适用）

更新这份 yml 等于改变"通过"的定义，所以按方向区别对待：

⚠️ 这条方向规则是防「自动修复把闸门修没了」：lint 命令坏掉时，把它留空是最省事的 "修法"，结果闸门悄悄松了、报告还是绿的——比不更新更危险。 变严可以自动，变松必须由人签字。

<!-- @include-end templates/prompts/check-commands.md --> <!-- pdlc:meta 由 frontmatter 生成（adapters/sync_skills.py），勿手改 -->

本命令的状态机取值：阶段短名 review（写进 history[].stage 与 last_phase_result.stage）；下一跳 pdlc-ship（写进 next_step，交接时提示）。

<!-- pdlc:meta-end --> <!-- @include templates/prompts/state-update.md（已内联于下方，无需另读） -->

状态机更新（段四必须执行）

本命令完成主产出后，必须推进状态机文件 docs/.pdlc-state/<feature-id>.json。

用脚本推进，不要手写状态 JSON

bash scripts/pdlc-advance.sh <功能ID> --stage <本阶段短名> --next <下一跳命令名|null> \
  [--produced <产物路径，逗号分隔>] [--autonomous] [--decision "<确认点>=<所选默认>"]... \
  [--name <kebab-case>（状态文件还不存在时）] <项目根>

• 脚本是本 skill 自带的 scripts/pdlc-advance.sh。阶段短名与下一跳就是本命令正文里「本命令的状态机取值」那两个值；带了 --autonomous 就照传
• 检查由脚本自己跑：它按阶段调用同目录的 scripts/pdlc-checks.sh（tdd 验红灯；impl / fix / refactor 跑 unit、coverage、lint；

review 再加 e2e；e2e 只跑 e2e；文档类阶段不跑），据此判 ok、整段写入 history 与 last_phase_result， 写完调用 scripts/pdlc-state-lint.sh 体检。不要自己先写 checks，也不要挑检查项

• tdd 阶段的 --produced 必须列出写的测试文件：脚本记下它们的指纹，之后 impl / refactor / review 推进时比对
• 主动交还人类（命中人工点、评审有阻塞项、测试本身有矛盾等）→ 加 --blocked "<原因>"：脚本照跑检查、如实记录，但不推进，原因写进 blocked_reason
• /pdlc-ship 写 ship_done、/pdlc-deploy 写 deploy_done → 加 --done（只有这两个命令能用）

脚本的退出码决定怎么收尾：

退出码 3 且原因是「tdd 阶段写的测试被改动」：实现阶段不改测试。测试是否真的写错了（与设计 / PRD 矛盾），只有人能判断： - 交互模式：先把矛盾讲清楚、问人；人同意后再带 --tests-changed "<理由>" 重跑，理由记进 auto_decisions - --autonomous：没有人可问，不要改测试，带 --blocked "<矛盾在哪>" 收尾。自主模式下带 --tests-changed 脚本也不推进

>

项目开了 PDLC 护栏（docs/00_standards/pdlc-hooks.yml）时，用 Write / Edit 直接写状态文件会被拦下。

状态文件格式（读状态时参考；只有脚本跑不了时才照它手写）

{
  "feature_id": "<F/B ID>",
  "feature_name": "<kebab-case>",
  "created_at": "<首次创建时间 ISO 8601>",
  "current_stage": "<当前阶段名>",
  "run_mode": "interactive | autonomous",
  "history": [
    {
      "stage": "<阶段名>",
      "done_at": "<ISO 8601>",
      "produced": ["<相对路径 1>", "<相对路径 2>"],
      "self_audit": { "passed": <N>, "failed": <N>, "manual": <N> },
      "auto_decisions": [
        { "point": "<autonomous 下自动前进的确认点>", "chose": "<所选默认>", "at": "<ISO 8601>" }
      ]
    }
  ],
  "last_phase_result": {
    "stage": "<本次阶段名>",
    "ok": true,
    "advanced_to": "<推进到的下一阶段 | null>",
    "checks": {},
    "self_audit": { "failed": 0 },
    "blocked_reason": null,
    "run_mode": "interactive | autonomous",
    "at": "<ISO 8601>"
  },
  "relations": {
    "extends": [],
    "depends_on": [],
    "supersedes": [],
    "resolves": [],
    "conflicts_with": [],
    "relates_to": [],
    "_updated_at": "<ISO 8601 | 省略>"
  },
  "next_step": "<下一跳命令名，如 pdlc-design；若流程结束则为 null>"
}

⛔ 示例里的 "checks": {} 是「本阶段没有命令可跑」的样子，不是键名示范——键名与取值见下方 §1。

`relations` 块（RFC#6，Phase 1 可选，Phase 2 推荐）：6 个 key 对应 6 种关系类型，各为 ID 数组，存出边。其中 conflicts_with / relates_to 是对称类型，两端都要写；其余四种有向，只写在源 feature 上。拿不准时用 /pdlc-relate set 写入，它会按规则校验。旧状态文件无此块时视为全空，向后兼容。入边由 /pdlc-relate rebuild 派生到 _relations.json，不在此块手维护。

⛔ 写状态机的四条硬约束——读侧（/pdlc-status、/pdlc-retro、/pdlc-relate）会逐条体检， 违反的每一处都会出现在它们输出的最前面：

>

1. 实例里不写 `terminal_state`。skill frontmatter 的 terminal_state: 是「这个命令走完后应到达的终态名」， 不是状态字段。判终态只看 current_stage 是否以 _done 结尾。 2. `history[].stage` 写本命令的阶段短名（见本命令正文里「本命令的状态机取值」）——pdlc-implement 写 impl， 不写 implement / implementation；pdlc-prd 写 requirements，不写 prd。 3. 时间戳必须带时刻：created_at / done_at / at 一律写完整 ISO 8601（如 2026-07-28T10:40:00+08:00）。 只写日期，同一天内的阶段耗时就全部算成 0——读侧只能记「不可测」。 4. `next_step` 只写命令名或 `null`，不附说明文字（如「pdlc-ship（等评审通过）」）。 要说明原因，阻塞时写进 last_phase_result.blocked_reason。

⛔ `_done` 的含义是「已发布」，只由 `/pdlc-ship`（写 `ship_done`）与 `/pdlc-deploy`（写 `deploy_done`）写入。 其它命令的 current_stage 一律写本命令的阶段短名，走完整条链路的编排命令（/pdlc-feature）也一样—— 它收尾时 current_stage 是最后一个阶段的短名，next_step 是 pdlc-ship。

>

- 「评审通过、等待发布」就是 current_stage 为 review 且 next_step 为 pdlc-ship（/pdlc-e2e 在评审之前，它的下一跳是 pdlc-review）。 循环相关文档里说的 review_done 指的就是这个状态，不是要写进 current_stage 的值。 - 为什么：读侧判「已抵达终态」只看 current_stage 是否以 _done 结尾。评审通过就写 _done， /pdlc-ship 就分不清哪些功能已经发布过，发布说明会重复或漏收。 - 旧版本写入的 feature_done / fix_done / review_done 分不清是否已发布，/pdlc-ship 会列出来请人确认。

手写回退（仅脚本退出码 2 且无法修正时）

1. 文件不存在 → 创建文件，写入初始结构（history 为含当前阶段的数组）
2. 文件存在 → 读取 JSON，追加当前阶段到 history，更新 current_stage 和 next_step
3. 写回文件：用 jq 或等效工具保持格式化
4. 写完体检：运行 bash scripts/pdlc-state-lint.sh <项目根>，属于本功能状态文件的偏差当场改正。退出码 2（缺 jq 等）= 没体检，报告里写明「未体检」，不得当作通过。

⚠️ 若更新失败（文件损坏/权限问题），必须中止命令并在最终报告中报错。状态机不可跳过。

last_phase_result（机器可读阶段结果；脚本按下面的规则写，手写回退时照做）

顶层 last_phase_result 是循环判停的唯一真源，外层只需 jq '.last_phase_result.ok' 即可决定 继续 / 停止 / 交还人类。规则：

1. `checks` 只放真跑命令的退出码结果（scripts/pdlc-checks.sh 的 stdout 原样），键名只能是 tests_pass / coverage_pass /

lint_clean / e2e_pass（tdd 段 red_verified），值只能是布尔或 null（无法判定）。不照抄 test-commands.yml 的 unit / lint， 不写 "4 passed, 1 failed" 这类摘要。没有检查可跑的阶段（文档类阶段、项目无 test-commands.yml）→ checks: {}， 绝不因为「本阶段成功」就填 true——schema 示例里 checks 是空的，正是这个意思。

1. `self_audit` 单列：只放自检未通过数，仅供参考，不作循环判停依据。
2. `ok` 的定义：没有命中 blocked_reason，且 tdd 段 red_verified 为 true、其它阶段没有任何检查为 false（null 不拦）→ true；否则 false。
3. 命名空间：advanced_to = 下一阶段的短名，不是命令名、也不是本阶段的 `current_stage`。三者关系：stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。

⛔ 短名不是「命令名去掉 `pdlc-` 前缀」——pdlc-implement 的短名是 `impl`，不是 implement。别推导，查下表：

<!-- stage-map:start -->

<!-- stage-map:end -->

next_step 为 null（终态或无后续）时 advanced_to 也是 null。

📌 本表是唯一真源，且是被断言钉住的：每行的短名必须等于该 skill 自己 frontmatter 里声明的 stage:，且任何 skill 的非 null next_step 都必须在表里有行——两个方向 都由 tests/frontmatter-check.sh 检查，所以表不会和实现各自漂移。

>

写错短名的后果与键名写错同类：消费方按契约名匹配，认不出就当没这个阶段。

1. 推进一致：ok=true 时本阶段必须真的推进了 current_stage（与第 6 条 IRON LAW 呼应）；到达终态或无后续时 advanced_to=null。ok=false（含 blocked）时 current_stage 不变、advanced_to=null、blocked_reason 写明原因。
2. `run_mode`：镜像本次调用是否带 --autonomous（带了写 autonomous，没带写 interactive）。

<!-- @include-end templates/prompts/state-update.md --> <!-- @include templates/prompts/handoff.md（已内联于下方，无需另读） -->

段四：交接（Handoff）

命令完成后必须输出以下格式的最终消息：

✅ <阶段名> 完成：<主要产出物路径>
📊 自检：<通过数>/<总数> 通过（若有未通过，附要点）
📦 状态快照：docs/.pdlc-state/<feature-id>.json
👉 下一步：/pdlc-<next_step>
   （如果有分叉）或 /pdlc-<alt>（条件：<选择依据>）

规则：

• 主流程命令（写状态机的命令；下一跳见正文里「本命令的状态机取值」）必须显式输出"下一步"，不可省略
• 工具型命令（Layer 3）可以没有 next_step，此时输出 👉 下一步：（本次流程结束，无后续）
• 分叉场景必须说明选择条件，例如"若需补充测试用例 → /pdlc-tdd；若测试已齐 → /pdlc-review"

<!-- @include-end templates/prompts/handoff.md -->