# 当前会话作为 JS workflow 工具宿主

## 单步驾驶员

仓库自带 `../../../scripts/cm-ai-drive.mjs`，一次启动宿主、发送一个 operation、回答这一轮的反问并打印结果：

```bash
node "{CM_WORKFLOW_ROOT}/scripts/cm-ai-drive.mjs" --plan "{PLAN.json}" advance
```

`PLAN.json` 与 cm-fix 驾驶员一样，以自身目录解析相对路径；填写 `config`（已批准的运行定义）、
`mode`、当前真实 `hostContext`、`runtime`、原样传给宿主的 `permissions`、`answers` 和
`checks: [{"id":"syntax","command":["node","--check","target.mjs"]}]`。换会话恢复还要填
`originalHostContext`，且运行存档必须已存在。人工写好的开发结果放 `answers/develop.json`，
其中 `edits` 把批准 scope 内路径映射到答案目录里的 UTF-8 内容文件。其余人工文件为
`qa-assess.json`、`documentation-inspect.json`、`documentation-sync.json`；QA 修复子运行沿用
cm-fix 的 `learning.json`、`diagnosis.json`、`test-edits.json`、`repair-edits.json` 和
`retrospective.json`。缺答案、结构错误、路径或存档无效会在启动宿主前退出 2。

`check` 只运行计划里的真实命令；原始输出打印到驾驶员 stderr，宿主只保存实际退出码和精简证据；静态 `check.json` 不会被读取。
`qa_logic`、`qa_browser`、`verification_precheck` 没有可信本地 runner，涉及这些反问的步骤会在发送前拒绝。
受保护执行由原宿主处理检查；驾驶员不把人工填写的结果冒充执行证据。一次 `advance` 可能走过多个阶段，
驾驶员会按该宿主的请求路径提前检查本次可能用到的全部答案；只读 `status` 不需要答案。

批次使用 `../../../scripts/cm-ai-batch-drive.mjs`，调用方式同为 `--plan PLAN.json advance|status|cancel`。
`config` 指向批次宿主的 `{batch,workflows}` 定义；`answers` 下按 `feature/taskId/` 放每个任务的
`develop.json`、`qa-assess.json`、`documentation-sync.json`、`documentation-inspect.json`，
`checks` 按 `feature/taskId` 映射真实命令数组。驾驶员在发批次指令前检查所有任务的答案、
scope、命令及恢复存档。批次宿主没有 `--original-host-context`，恢复必须沿用原 `hostContext`；
不能用它接管另一会话。批次的 `qa_logic`、`qa_browser`、`verification_precheck` 与 bootstrap
`init_verify` 需要驾驶员尚无的真实执行 runner，命中时启动前退出 2。受保护配置里的检查由宿主执行。

本参考只负责接入已有 runner，不复制 N1–N8 状态机。相对路径从本文件解析；
插件根是 `../../..`，不得硬编码安装缓存。先读
`../../../docs/js-workflow-control.md` 的当前支持、会话入口、QA/文档、审查授权与批次章节，
使用其中真实 CLI、配置和结果合同，不发明字段或动态加载执行模块。

普通 `cm-ai` 新任务默认进入本入口，无需用户指定 JS；恢复已有运行先遵守主 Skill 的路由优先级。
进入前检查下列环境、目录与权限条件，缺口明确阻断；不得因启动失败转回兼容流程或创建替代运行。

## 启动前

1. 读取代码项目根与目标路径适用的 AGENTS、`N1-init.md`、`N2-enter-feature.md`。
   保留原批准 manifest、完整 feature 清单、task/AC、依赖、Learning 和形态确认要求。
   只提取输入与业务约束；不要执行旧节点中的手工日志/状态、Git、安装或任务标记。
2. 当前执行 CLI 支持 Codex 或 Claude 当前会话，要求Node 24.14+；macOS有本地证据，Linux实现已接但尚缺目标环境验证，原生Windows未支持。支持单根或显式多根，与
   分离或显式受保护的同仓 specs 根。由当前真实宿主确定 runtime：Codex 用 `--runtime codex`（也是默认），
   Claude 必须显式传 `--runtime claude`；单任务和批次入口相同。模型输出不得选择或更改
   runtime，恢复不得换端或冒用旧会话。Codex单任务同仓specs可显式选择下文受保护模式；
   当前Codex/Claude及批次同仓用下文文本提案模式；未选择保护的同仓仍阻断。不搬动specs或删除保护检查；工具会话不是OS沙箱。
3. 从已批准任务确定 scope、requirements 和顺序；不跳过未解决的 bootstrap 确认或依赖。
   单代码根用 `cm-ai-admission.mjs --print-run-definition --scope ...` 生成运行定义，不要手写；`--scope` 必填（相对代码根、逗号分隔），`--requirements` 可选；完整命令见产品文档。
   单任务用 `cm-ai-host.mjs`；多任务用 `cm-ai-batch-host.mjs` 的原 batch/workflows 配置。
   任务列表只包含该运行计划内的任务；恢复必须使用原身份、配置和真实当前会话身份，
   单任务换会话恢复用 `--mode resume --host-context {当前真实会话ID} --original-host-context {创建运行的会话ID}`；
   两个 ID 相同等同未传新参数，create 传它报 `original_host_context_unavailable`。不能冒用旧 host-context。
   原配置指纹和 init 元数据仍绑定创建会话，旧记录不改；开发结果和审查授权使用当前真实会话。
   新会话首次签审查授权前追加 `host-joined`，仅打开或 status 不写；创建会话、已加入会话和当前会话
   都排除为审查员，当过审查员的线程不能回来当宿主。最多记录 16 个接手会话。
   支持 V3 会话父运行及其 QA-fix 子运行；旧 protected 兼容分支、batch 不支持此跨会话入口，原授权仍须逐项提供。
   QA-fix 新建子运行的配置 hostContextId 只能是当前会话或父运行的持久创建会话；已有子运行沿用原配置并校验指纹。
   子运行打开（含 fix_status）和审查授权使用当前真实会话；首次签授权前由 cm-fix 记录 fix-host-joined-N，
   只读打开不写接手记录，causeReview.contextId 不能是当前会话。子 runtime 仍须匹配宿主。
3.1 多任务批次可提议并行组，写进 batch 配置的可选 `parallel`（任务 key 的数组的数组）。
   只提议同时满足以下全部条件的任务，任一不满足就不进组；一个组都成立不了就**不写该字段**，正常串行：
   - **纯新建文件**：该任务 scope 的每个路径在 `HEAD` 上都不存在（`git cat-file -e HEAD:{path}`
     判定，不看工作区——成员工作树从 HEAD 创建，未跟踪文件不算数）。任务若需改动现有文件
     来注册新模块（路由表、index 导出等），那些文件会出现在 scope 里，本条自动将其排除。
   - **scope 两两不交集**：候选之间不得有重复路径。
   - **无依赖路径**：按 `tasks.md` 依赖图计算**传递闭包**，组内任意两任务之间不得存在依赖路径。
     runner 也按传递闭包校验并以 `parallel_dependency_conflict` 拒绝，此处自行判定是为了
     提出合法的组而不是被拒后返工。
   - **同一 feature**，且排除该 feature 最后一个未 DROPPED 的任务（它承担合并后的统一 QA）。
   - **每组 2–4 个**，不足 2 个不成组。
   能并行才并行，不为组而组；判定不确定时按串行处理。成员在各自 Git 工作树开发、串行合并回
   主分支，成员 QA 自动延后到末任务；当前会话模式下开发请求仍逐个应答，重叠的是审查与流程开销，
   不是写代码本身，不得据此承诺成倍提速。

4. 核对任务所需能力后才启动。QA 使用原测试合同与已授权命令/环境；无 QA 配置不能宣称
   已完成必需 QA。文档路径预先纳入任务批准 scope；需要 AGENTS/CLAUDE 等保护指令同步、
   bootstrap规范用下文受信入口；其他未满足的必需能力记录具体缺口，不降格成可选项。
5. reviewer 配置在首次运行前绑定；本机 preflight 不是实际模型审查或调用许可。
   只有当前真实用户已授权本任务本轮、模型与发送包时，才传审查授权选项；无许可可以
   不带选项运行至待审，但不能完成。批次按 feature/task:attempt 授权，不授权整个未来批次。
   不把开发批准转换为网络、安装、Git、发布或真实 provider 调用批准。

## 同一引擎的双端启动

从当前活动 Skill 的本参考文件所在目录解析 `../../../scripts/`，调用对应脚本而不是依赖全局同名命令。
单任务使用 `cm-ai-host.mjs serve`；多任务使用 `cm-ai-batch-host.mjs serve`，都显式传递
上述 runtime，并使用真实宿主提供的 `--host-context`。不要为了使用 Claude 改写规格、
Review 头或完成记录；provider 身份由原 adapter/V3 绑定，失败不切到另一端兜底。

需配置审查时，按文档运行单任务脚本的
`preflight --config {该代码根的单任务配置} --review-model {已选择模型} --runtime {当前端}`。
即使后续执行批次，诊断仍用同一代码根的单任务配置，不把 batch/workflows 配置传给该命令。
诊断输出直接作为 review-config 输入，不手造或修补 `passed`/指纹；失败则保留原因。
Claude 诊断只做回环请求捕获，`stopped_by_probe` 表示诊断自身终止，不发送工作流 cancel。
本机配置诊断通过不证明模型可用、Review 协议成功或用户已批准外发；真实审查仍须第5项授权。
不带对应 `--allow-review-attempt`（单任务）或 `--allow-review feature/task:attempt`（批次）
可以准备并停在原待审点，不能自行追加这些选项推进。后续授权也不得改变原 scope 或身份。

## Codex 单任务：显式受保护执行

不新增模型调用的方案：单任务和批次均可传`--protected-conversation-config {文件}`，配置固定为
`{checkCommands,timeoutMs}`，命令须已获准；`timeoutMs` 同时约束检查命令与 Codex/Claude 审查进程。
审查传输超时且没有结果事件时，记录 `pending_review/review_transport_timeout`，可用 `--mode resume` 后 advance，
同一 attempt 最多重派一次，重新取得 Review 授权、grant 与 invocation；第二次超时为 `blocked/review_transport_timeout`。
已有最终消息（即使截断）的超时仍需 reconcile，旧 unknown 历史不自动改类。兼容Codex/Claude当前会话，保留原runtime与Review授权。
develop若有`editMode:"protected-text-v1"`，只读并返回`{status:"succeeded",value:{原开发/Learning结果},edits:[{path,beforeSha256,content}]}`；
使用scope内expected摘要，正文完整UTF-8，null删除；不得先自行写文件或执行命令。失败返回原status/code，blocked不能带改动。
固定沙箱负责应用提案和原检查，不再请求宿主check；文档同步包含在同次develop提案。原64KiB通道不变，二进制/超限明确阻断。
本机Codex sandbox不调用模型，也不改变Claude身份。其余QA/文档核验/子fix权限不变，不与下述protected-config混用。

开发结果先通过完整 value/Learning 合同校验，再由沙箱落盘；本地校验失败记录 `failed` / `invalid_result`，原校验码保留在 `result.reason`。
当前会话返回 `blocked` / `developer_result_invalid` 时，修正回复后用原配置、身份和 runId 以 `--mode resume` 启动并 `advance`，同一 attempt 重新 develop，不消耗 provider 轮次。
`no_new_lesson` 必须 `candidates:[]` 且 `reason:null`（实跑事故：非空 reason 曾在文件落盘后抛错，被误记为 unknown，原 runId 无法恢复）。
重送已落盘提案时核对新的 expected 哈希：提案内容与磁盘一致才作为同一次实现继续；不一致返回 `protected_edit_stale`，保留文件并报告冲突，不能强制覆盖。
worker 异常、超时或传输歧义仍是 `unknown`，旧 unknown 历史不自动重分类；其他 blocked 原因也不能使用此重试入口。

用户已授权本任务该轮真实 Codex 开发调用及发送范围时，可选普通单任务入口的
`--protected-config {文件} --allow-provider-development-attempt 1`。这是原生受保护子进程，
不是当前会话直接改文件，不会因同仓布局自动切换；普通“开始开发”或`--allow-development`本身不授权外发。
读取产品文档“普通单任务入口选择受保护模式”的配置和命令示例；配置只含model/checkCommands/timeoutMs，
固定代码根/specs根、scope和实际宿主身份仍来自原run配置及host-context。命令也须事先获准。

启动须提供原`--review-config`诊断，但诊断不是审查许可；没有`--allow-review-attempt`时只到待审。
初次create只能授权开发attempt 1；修正轮resume须按真实审批改为attempt 2，不重置原轮次或身份。
R1要求修改但尚未授权第2轮时保留changes_requested，不登记开发或当作unknown；补授权后再resume。
收到host_ready后仍按原协议advance/status/cancel/host_close；开发和检查由适配器执行，
当前会话不重复处理develop/check或手写凭证。补授权后沿原mode resume，不换runId。

首次create可同时提供原`--workflow-config`；有QA配置须另带`--allow-qa`，恢复保持原配置与授权。
原无workflow或`qa:null`且任务已为`fixture_completed`时，可在`--mode resume`显式提供
含QA的`--workflow-config`与`--allow-qa`，一次性附加N6；原definition/scope/requirements/identity、
创建运行的 host-context（换会话时由 `--original-host-context` 声明）、开发/审查配置仍须匹配。journal追加不可重复/修改的`qa-attached`，运行日志写
`decision/qa_attach`；后续恢复须保持已绑定配置及重新授权，`qa`仍要求`qa_assess`等原宿主请求。
不重跑开发/审查，不将任务完成当作QA通过（事故：create漏配workflow曾使feature强制QA无法补做）。
QA 的 `qa_assess/qa_logic/qa_browser` 请求独立计时，workflow 的 `qa.timeoutMs` 可设 1–60000 毫秒，
省略为 60000；超时记 `host_request_timeout` 并阻断，不把已有命令 PASS 用来覆盖超时。
宿主读取 JSONL 时必须处理当前缓冲区内的全部完整行，再等下一个数据块；处理单行后不能
提前 return（事故：确认和 TC-007 请求合并到一个数据块，旧驱动只读确认而悬空等待）。
无 complete 的 N6 中断只能由用户显式重跑：保留原配置，`--mode resume --allow-qa --rerun-unknown-qa`，
之后 `advance`；运行日志先记 `test_run/abandoned`，新 testRunId 保持原 qaRound，不重跑开发/审查。
已记录 case_complete 必须全为 PASS（允许零条），且无 case_blocked；abandoned 的 partial_pass_cases 记录旧 PASS 用例。
所有用例仍全部重跑，旧 PASS 证据文件只作历史保留。任一 FAIL/BLOCKED、固定报告
`{testRunId}-execution.md` 或未清理资源都不满足恢复条件；保留 unknown/阻断供人工核对，
不删报告或日志来获得重跑资格，不伪造 complete。仅写了 abandoned 后再中断可沿同一授权入口恢复。
已 complete 的宿主证据阻断可用单任务 `--mode resume --workflow-config {原配置} --allow-qa --rerun-blocked-qa`，
再 `advance`：仅最新结果为 BLOCKED、failed=0、qaRound<3，且每条 BLOCKED 都是 browser 的 evidenceProblem、
cleanup=failed、环境摘要不一致或 hostRequestTimeout，或 logic 的 INSUFFICIENT_EVIDENCE 时允许。
commands 阻断（含 commands-unavailable/no-applicable-cases）、产品 FAIL、源码漂移和未 complete 不适用；配置填错应使用下述“QA 配置修订”。
先写 `test_run/superseded`（previous_test_run_id、reason=host_evidence_problem、blocked_cases），再以新 testRunId、
qaRound+1 写带 previous_test_run_id 的 start，全部用例重跑；旧 PASS 仅保留历史，最多三轮，不重做 QA 决策、
开发或审查，不改 tasks。开关一次性消费且不持久化，不与 --rerun-unknown-qa 合用；仅写 superseded 后中断，
须重新显式授权恢复。complete 同步 N6 状态镜像为 qa_passed/qa_failed/qa_blocked，并显示本轮通过/失败/阻断数量。
（事故：宿主把非文件说明混入 browser evidence，导致已完成任务的收尾 QA 无法恢复。）

### QA 配置修订

开发、独立审查和 N5 已完成，最新 QA 已产生完整结果，但命令、环境或 QA 预算填错时，先保留上一版 workflow JSON，再修改新文件。用户明确同意本次配置改动后，用单任务宿主恢复：

```bash
node scripts/cm-ai-host.mjs serve --config run.json --mode resume \
  --host-context {原宿主身份} --allow-development \
  --workflow-config workflow-new.json --allow-qa \
  --revise-qa-config workflow-old.json \
  --qa-config-revision-reason "补齐此前漏配的项目测试命令"
```

原运行需要的审查、保护配置和跨会话身份参数仍须照原值提供，然后发送 `advance`。旧运行只保存完整配置摘要，没有可逆的配置副本，所以必须提供上一版文件核对；不能凭一个新摘要接受任意漂移。旧文件仅用于验证，不执行其命令。

- 修订仅接受 `resume`、`--allow-qa`、非空原因和相符的上一版配置；不能与两个 QA 重跑开关合用。只允许 QA 命令、环境、QA 预算及其派生执行计划变化，任务身份、规格、开发、审查、项目策略、文档与能力配置均保持原绑定。reviewer 的纯传输超时本来就不参与授权摘要，无需本入口。
- 先追加 `qa-config-revised`，绑定前后指纹、QA 配置摘要、原因、原审查包及旧 QA 轮次；再追加 `test_run/superseded`，原因是 `qa_configuration_revision`。旧结果留在历史，不再作为当前通过或修复依据；原开发、审查、N5、任务勾选和历史字节不改写。
- 新 QA 使用新 testRunId，全部用例重跑，轮次加一且最多三轮；另行绑定实际完成的开发 attempt，第二次开发审查通过后也能恢复。未完成或结果未知的 QA 必须先核对原执行；本入口不证明资源已清理，不放宽源码漂移检查，不重置轮次，也不自动批准产品修复。
- 配置链验证成功后，后续恢复只需当前配置与原授权参数，不再需要旧文件。重复同一修订命令不会重复登记；若中断发生在 journal 写入之后，会补齐旧 QA 的作废日志，再运行下一轮。未使用此入口时，改配置仍报 `fingerprint_mismatch`。

本次仅支持单任务宿主；批量宿主未接入该选项。临时夹具覆盖漏命令死锁、正常续跑、连续修订与三轮上限、旧证据拒绝及中断回放；不代表真实模型或浏览器验收。

### 已审交接后的任务重跑

同名 handoff 已被审查回执消费时，宿主保留 `handoff_exists`，blocked 结果的 `reason` 与 `[host]` 诊断会提示两个出口：QA 配置错误用上述 `--revise-qa-config` 恢复原运行；宿主或环境证据不足用 `--rerun-blocked-qa` 恢复原运行。确需重新开发同一任务时，使用新的 runId 和下列显式授权：

```bash
node scripts/cm-ai-host.mjs serve --config run-new.json --mode create \
  --host-context {本次宿主身份} --allow-development \
  --supersede-reviewed-evidence --supersede-reason "说明为什么要重跑任务"
```

原因必须为单行、非空、最多 500 UTF-8 字节。N5 会在 N6 前把任务勾为 `[x]`：若 QA BLOCKED 后确需重新开发，先在 `tasks.md` 将该任务改回 `- [ ]`，再用新 runId 和上述两个旗标创建运行；仍可恢复原 QA 时优先走原运行。只接受同 feature、task 的新运行：`tasks.md` 未勾选该任务，且每个旧运行的 V3 journal 已是无在途操作的 blocked、cancelled、unknown，或 fixture_completed 且 QA 为 BLOCKED／尚未结束；旧 writer 仍被进程持有也拒绝。已完成或仍可继续的旧运行、没有旧运行或可归档文件同样拒绝。旧运行的 journal 不改写、不以新运行身份重开。

使用 `cm-ai-drive.mjs` 时，将这两个参数放入新运行 PLAN 的 `permissions`；缺少其中一个或 `mode: "resume"` 时，驾驶员在启动宿主前拒绝。

新运行先在自己的 journal 追加 `evidence-superseded`，绑定原因、旧 runId、文件名和 SHA-256，然后用先硬链接再解除原链接的方式把该任务同名 handoff、review 及具名 correction／QA 文件移至 `.reviews/.superseded/{原文件名}.{摘要前16位}`，并写 `supersede` 运行日志。归档中断后以同一新 runId 执行 `resume` 会按记录补齐；未用此旗标的运行不增加记录或改动旧证据。历史 QA 的 UUID 报告仍由旧 runId 日志引用，保持原位。新 handoff 和 review 使用原文件名，旧证据只在归档中留史。

QA命令复用同一specs只读沙箱。最终任务的documentationPaths必须已在批准scope内，
在同一次受保护开发调用中同步，随后进入原检查/handoff/Review；不派发宿主documentation_sync，也不增加模型轮次。
宿主仍处理qa_assess/qa_logic/qa_browser及只读documentation_inspect；不得借这些请求改代码、规格或指令。
浏览器仍遵循原工具、目标、证据与清理约束；此模式只对开发及命令子进程提供OS保护，不把宿主语义报告冒充沙箱证明。
只有原QA/文档核验/完成门禁通过才返回run_done；缺能力或核验blocked仍阻断，不手工补状态。
该模式仅单任务Codex；可接原QA-fix参数，但子owner/template的configuration必须显式protectSpecs:true，
否则在父运行建store前拒绝。仍按原每项权限、auto_fix策略和最多三轮QA执行，不因父开发/审查许可获得子权限。
子修复的文本提案合同见`../../cm-fix/references/js-host.md`“同仓specs的受保护修复”；收到对应editMode时宿主不直接落盘。
不适用于Claude/批次，不改变Git、安装和发布权限；恢复不得在受保护模式与默认会话模式之间切换。

## 执行当前请求，而非手工跳节点

多代码目录使用原run/batch可选codeProjects与共同工作区codeProject，scope/requirements加各根相对前缀。
只用已声明真实根；protected-conversation-config的每条检查及workflow QA命令增加codeProject绑定实际cwd，
每根至少一条检查。读取develop的codeProjects/projectInstructions，返回前缀路径提案；原同一任务统一审查和完成，不自行拆任务。

0.bootstrap按原骨架→规范任务顺序。单任务bootstrap-config为`{selection:null}`或原cm-init选择；
批次bootstraps映射到具体feature/task，另传allow-bootstrap-write。原任务批准和逐轮独立Review不能省略。
先按产品文档配置完整固定规范scope；requirements可为空数组；bootstrap原有批准specs需求/设计纳入逻辑保持不变。
init_generate复用原cm-init生成合同；init_verify五组检查加constraintChanges/application/retrospective，详情以产品文档为准。
宿主不自行落指令文件：JS固定写入、读回、同次handoff/Review、N7重载。原规则冲突、未知或漂移保留证据，不覆盖或重派。

用当前会话可交互的进程工具启动 CLI 并保留会话句柄。收到 `host_ready` 后按文档发送
`advance`；批次控制消息不带子任务 identity，单任务按原合同携带 identity。
持续读取响应，按 requestId 关联控制结果。不要等待 `advance` 结束才处理途中 host_request。

每项 host_request 必须核对实际任务、路径、scope 与当前授权，再执行对应工作：

| 请求 | 当前会话实际执行 |
| --- | --- |
| develop | 读取 N3 的业务约束、适用项目指令与请求中的 Learning；按 N3 的技能匹配读取并使用真实工程 Skill，只修改固定业务 scope，返回原开发/Learning 结果。不要执行 N3 的手工交接/标记流程。 |
| check | 按原任务测试合同实际运行适量检查，返回实际退出码及证据；不把自审或静态推断写成测试通过。 |
| documentation_sync | 使用 cm-doc-syncer 的文档判断，只同步请求列明且获准的普通文档；这是 Review 前写入，不新增完成后写入。 |
| qa_assess / qa_logic / qa_browser | 使用 N6 与 cm-qa-engineer 的业务判断或获准工具；评分不替代 JS 的强制 QA 政策，静态判断不替代真实运行，不能改变载体或伪造浏览器证据。 |
| documentation_inspect | 按 N8 只读核对必需文档及收尾证据；缺文档、度量或必需能力返回 blocked，不为了 run_done 宣称 completed。 |

进入匹配角色前读取该 Skill 完整指令，但 JS 所有权不让渡给角色。实际模型路由、资源
及逐例日志由已有实现覆盖到哪里就报告到哪里；读取角色 Skill 不证明配置声明的模型已调用。
若角色要求 JS 尚未支持的控制动作，停止并报告，不在旁路手写日志/状态弥补。

回复沿用该次 sessionId/callId/requestDigest，result 严格符合该 kind 原合同；开发结果不是
check 数组，也不是 QA/文档结果。只回报已实际执行的事实，不能从项目文件自动接受回复。
工具失败返回原失败结构；超出权限不能执行。Learning 候选交由原 runner 写回与 Review，
会话不自行修改保护指令。不要制作自报 approved、grant、Review receipt 或完成凭证。

JS 返回阻断、待授权、失败、取消、unknown 或补正要求时，报告原因并保留磁盘证据；
不重试未知调用、换 runId 绕过历史、手工勾 tasks 或启动旧兼容流程。允许 status 查询；
只有用户明确取消才发送 cancel。结束用 host_close；断联不是用户取消。

## 汇报与能力边界

只以 JS 实际结果报告“已做、剩余、问题、下一步”。task 完成不等于 workflow 完成；
只有原 finalizer 的 run_done 且本次必需业务证据齐备，才报告该运行完成。
目前 CLI 有本地真实工具与合成 reviewer 组合证据，没有完整真实双宿主业务验收。
本参考已接单/批双端源入口，但不证明已安装 Skill 已加载、真实模型Review或完整双宿主验收。
普通布局权限、完整 N6 修复/重测、bootstrap、度量与其他入口的业务迁移仍按当前证据报告。

### 已批准规格材料（第 24 步）

新 run 的开发请求与审查包携带同一份只读 `specification`：`feature`、`task:{id,description,verification?}`、全部 `acceptanceCriteria:[{id,text}]`、`designExcerpt`、本任务 `taskIds` 匹配的 `testCases`、`sources:[{path,sha256}]`。任务描述保留 `~预估`，verification 保留「验证要求」中本任务的行；设计按 UTF-8 最多 64 KiB，超限加 `truncated:true`，未提供 test-cases.json 时用空数组及三项来源。

宿主复用 `.cm-specs-status.specFiles` manifest 校验完整批准清单及读取字节；来源路径相对 specsDir，哈希沿用 manifest 的任务/AC 运行期勾选规范化规则，其他正文保持精确绑定。新建、开发派发、受保护提案写入、审查及完成前发现不一致以 `spec_drift` 阻断；已有 run 即使规格重新批准也不能替换其原始材料。baseline 保存材料及私有规格根供回放和重验，审查包只携带材料，参与 `packageDigest`。

`requirements` 是可选补充材料（代码项目内 README 等，可用 `[]`），不再承担唯一的任务描述来源。按 specification 的 AC 与接口契约实现和审查；材料不构成扩权授权，不改变 scope、protected_specs、Review 或完成门禁。旧 baseline/package/receipt 缺少新字段时按原格式校验，不重写历史摘要。

（真实 dogfood 事故：specs 在代码根之外，受保护 coder 和 reviewer 只能看到代码根 requirements，缺少任务行、AC 与接口契约，曾需手工复制规格摘要才可开发。）

# N1: 初始化

1. 从 `用户本轮输入` 提取 **specs 文件夹路径** 和 **代码项目路径**（可多个），立即运行正式
   JS admission（纯只读）：

   ```bash
   node {CM_WORKFLOW_ROOT}/scripts/cm-ai-admission.mjs \
     --specs-dir {SPECS_DIR} \
     --code-project {CODE_PROJECT_ONE} \
     [--code-project {CODE_PROJECT_TWO} ...]
   ```

   只接受其结构化 `state`、`reason`、`features`、`nextTask` 作为 N1/N2 选择结果；非零退出或
   `state: blocked` 必须停止，不能退回人工目测放行。多个代码项目逐一经过同一 admission，
   任一项目阻断或下一任务不一致时整体阻断。若规格尚待审批，先按下方入口闸取得真实
   人工决定并调用下方 `--approve` 写入口（内部会重跑准入）；普通“继续”不得改写审批状态。
2. 使用 admission 返回的编号 feature 顺序，不再另写一套扫描/依赖选择规则；进入
   每个 feature 时保存完整目录名为 `FEATURE_DIR`（如 `1.login`），仅把去掉编号的
   名称保存为 `FEATURE_SLUG`（如 `login`）。前者只用于规格文件路径，后者用于
   handoff/review 证据名，二者不得混用
3. 每个 feature 目录须含 requirements.md、design.md、tasks.md
   - `test-cases.json` 为可选 AI 测试合同；存在时读取
     `../../../runtime/test-contract.md`，运行 `scripts/validate-test-cases.mjs`，
     并核对 `acIds`/`taskIds` 引用在本 feature 三件套中真实存在
4. 按 `runtime/project-context.md` 加载项目上下文：Codex 的 `AGENTS.md` 指令链优先，再读兼容的 `.claude/CLAUDE.md` 与相关 `.claude/rules/`（0→1 项目可能都不存在，跳过不报错）
5. 加载 `{SPECS_DIR}/LESSONS.md`（架构决策和踩坑记录，开发时必须参考）；**文件不存在（全新 specs 首次运行的常态）→ 按 0 条处理，不报错不中断**，首个任务的 N5 会创建它
6. 验证各代码项目路径存在，**空目录按信号处理**：
   - 空目录 + specs 含 `0.bootstrap` → 0→1 已在规格期人工确认，直接执行
   - **空目录 + specs 无 `0.bootstrap` → 矛盾信号，必须暂停询问**：specs 是按存量项目生成的，但目录是空的——"需要先 clone 项目？（clone 完成后回复继续）还是这就是新项目？（specs 上下文有毒，需重跑 $cm-prd 走 0→1 分支）"两种回答都不得跳过：clone 场景等用户，重跑场景中止
   - **非空目录 + `0.bootstrap` 存在且其脚手架任务（T-001）未完成 → 矛盾信号，必须暂停询问**：规格期确认的是 0→1，但目录里已有项目（用户事后 clone 了？）——"继续 0→1 会在现有项目上覆盖生成脚手架。是改用现有项目？（需重跑 $cm-prd 按存量项目生成规格）还是目录内容可弃、继续 0→1？"不确认不得执行 T-001

路径验证通过后立即按 `../../../runtime/logging.md` 写 `run_start`；断点恢复会复用
`{SPECS_DIR}/.cm-run.json` 中仍为 running 的 run id，不另开重复运行记录。

随后从代码项目根读取 `{CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs` 的有效配置，
至少解析本轮会用到的角色、`route_state`、workflow profile 与 `policies`。配置缺失
使用内置默认值；配置错误阻断本次运行并报告字段路径。这里只记录请求路由，不把模型
别名当成已观测的后端模型。Profile 只决定测试优先级，不改变 N1–N8：
`java-backend` 优先命令/API/数据库回归，`web-frontend` 优先构建/交互/browser，
`cm-default` 按通用顺序。

## 规格审批入口闸（先于一切预检）

以 JS admission 的结果为准；模型不得自行拼写或修改 `.cm-specs-status`：

- `ready` / `complete` → 沿用现有准入结果；旧版无 `specFiles` 的文件仍可读取，不在本节点自行补造批准证据。
- `awaiting_spec_approval` → 展示规格摘要卡（无卡时可现场汇总，但不得据此生成或替换 `summaryDigest`），等用户明确回复“开始”。泛化授权语（“继续”“按最优解处理”“你看着办”）不构成审批，须回问“规格摘要卡确认开始吗？”（实跑失守：泛化授权曾被误视为审批通过）。
- 取得明确回复后运行以下写入口，`--approval-response` 传用户原话；多个代码项目全部传入：

  ```bash
  node "{CM_WORKFLOW_ROOT}/scripts/cm-ai-admission.mjs" \
    --specs-dir "{SPECS_DIR}" --code-project "{CODE_PROJECT_ONE}" \
    [--code-project "{CODE_PROJECT_TWO}" ...] \
    --approve --approval-response "{用户原话}"
  ```

- `--approve` 不接受 `--yes`；只读调用的 `--yes` 也不写审批位。
- 只有 `awaiting_spec_approval` + `explicit` 且 reason 为 `approval_write_required`、`spec_features_changed` 或 `test_cases_changed` 才写；其余返回原准入结果及 `approveRefused`，不得手改 JSON 绕过。
- `blocked/spec_drift` → 保留原状态，要求用 `$cm-prd --change` 说明变更并重新发布摘要；不得自动改成 `awaiting_review` 或刷新 manifest。manifest 先于测试合同校验，测试合同修改也可能先触发 `spec_drift`。

共享 JS writer 生成 `features`、`specFiles`、`testCases` 和审批记录，原样沿用旧 `summaryDigest`，缺失时写 `null`。
写完返回重跑准入的结果；只有 `ready` 才进入开发，写成 approved 不代表其他检查已通过。
只有本次审批写入成功才记录 `spec_lifecycle/approved`；拒绝或只读查询不伪造审批事件。
需要单独核验批准 manifest 时，可只读运行 `python3 {CM_WORKFLOW_ROOT}/scripts/cm-spec-manifest.py {SPECS_DIR} --status-file {SPECS_DIR}/.cm-specs-status`；失败不授权改写。
N5/N6 的任务与 AC checkbox 变化仍由现有 manifest 规范化处理，文案、ID、设计和测试合同变化继续受准入保护。

多任务批次的并行组提议规则见 `js-host.md` 第 3.1 条；本兼容流程不自行发明并行判定。

> 这是**入口授权门**（人把关方案端），不属于"暂停仅灾难级"约束的中途暂停，也不计入 METRICS 人工介入。实跑教训：没有这道闸，prd 生成完会被一句"继续"顺势带进开发，人审形同虚设。

## 独立审查通道预检

开工前按 `runtime/review.md` 探测能否建立**与实现者不同上下文**的审查通道，而不是检查当前进程是否叫 Codex：

- 可创建 fresh Codex 子代理/独立线程 → 作为主通道
- 子代理不可用，但可以安全启动隔离的 `codex` CLI 审查会话 → 作为备用通道
- 两者都不可用 → 暂停新开发，已有实现保持待审并说明通道失败原因；不论任务风险高低，都不能用 `self-degraded` 诊断代替独立审查或进入成功收尾

当前 gate 支持的是上述 Codex 通道；未来 Claude-native 适配须单独验证，不能把
Claude 结果标成 Codex 通过门禁。通道不可用不算代码 finding，不消耗实现审查轮次。

## Git 前置检查（字段优先，询问兜底）

从有效配置保存 `DELIVERY_MODE=diff|branch|draft-mr`，其分支优先于历史默认行为：

- `diff` → 串行执行，不安装提交 hook，不自动 commit/push/MR；N8 交付最终 diff。
- `branch` / `draft-mr` → 使用任务级 commit。当前在 `main`/`master` 等保护分支时，
  基于当前 HEAD 创建 `cm/{首个feature}-{run短id}` 本地分支；已在非保护分支则沿用，
  不覆盖或切走用户已有改动。`draft-mr` 的远端动作留到 N8 再取得明确授权。

**先按项目上下文合同读「版本控制」字段**（优先 `AGENTS.md`，兼容 `.claude/CLAUDE.md`；$cm-init 或 bootstrap 已确认并落盘）：

- `remote` / `local` → 按 `DELIVERY_MODE` 执行；仅 branch/draft-mr **顺手装双保险 hook**：`{CM_WORKFLOW_ROOT}/templates/hooks/pre-commit-cm-task-check` 存在且代码仓库 `.git/hooks/pre-commit` 未装 → 复制安装（默认警告模式，不阻断），输出一行 `🪝 任务标记双保险已装(警告模式)`
- `none` → `delivery: diff` 时进入 **NO_GIT 降级模式**：N5 跳过 git、doc-syncer 用文件扫描、审计链降级为 METRICS + tasks 勾选；配置为 branch/draft-mr 时直接 `BLOCKED`，不得声称能交付分支或 MR

**字段不存在时**（项目未经 init 的兜底路径）：

- 有 git 仓库 → 继续，并建议补跑 $cm-init
- 无仓库但存在 `0.bootstrap/` 且任务含脚手架/git init → 跳过询问，交给 T-001
- 无仓库且非上述 → 问一次"git init？（推荐）/ 不使用版本控制"，**答案由主流程回写 CLAUDE.md 版本控制字段**（决策落盘，任何后续运行不再询问）

## 可视化入口提示（N1 输出末尾，一次性）

N1 完成、进入 N2 之前，在输出末尾打印一行可视化入口（存在 `{CM_WORKFLOW_ROOT}/templates/pixel/` 时才打印）：

```text
🎮 想看像素流水线？另开终端: {CM_WORKFLOW_ROOT}/templates/pixel/cm-pixel.sh
   浏览器版: {CM_WORKFLOW_ROOT}/templates/pixel/serve.sh {SPECS_DIR} （地址加 ?demo 可先看演示）
```

只在 N1 打印一次，不重复——入口可发现性问题的修复（实测反馈：用户不知道要手动启动）。

## 0.bootstrap 优先规则

存在 `0.bootstrap/` 且其中有未完成任务 → **无条件最优先执行**，完成前不进入任何业务 feature。它落地项目骨架、`AGENTS.md` 与 `.claude/` 兼容规范；完成后 N7 从磁盘重载新上下文。

# N2: 进入 Feature

1. 读取该 feature 的 requirements.md、design.md、tasks.md；存在
   `test-cases.json` 时按 `../../../runtime/test-contract.md` 一并加载，并把
   `taskIds` 命中当前任务的用例加入执行计划
2. 断点恢复：`[x]` 已完成 → 跳过，`[DROPPED]` → 跳过，`[CHANGED]` → 按更新后描述执行。**恢复时凭证对账**：每个已 `[x]` 任务 ↔ `{SPECS_DIR}/.reviews/*-{任务号}-r*.md` 配对，缺失项输出一行 `⚠ 凭证缺失: T-xxx,...（存量欠账,如实留档,恢复起严格执行）`——不阻塞恢复，但缺失不许无声混过（实跑失守：json-keeper 7 任务全无凭证,中断前无人发现）
3. 如该 feature 所有任务已完成 → 跳过，进入下一个 feature

## 教训定向注入（防复发，两个动作）

- **筛相关教训**：按本 feature 的领域/模块/技术栈关键词从 `LESSONS.md` 筛出相关条目（文件不存在或无匹配 → 注入 0 条照常继续,执行计划中输出一行说明）（`[仅记忆]` 级优先——`[已结构化]` 的已有代码防线兜底），把要点列进执行计划输出；并行派发时相关教训随 specs 摘录一并写进 agent 指令。全量加载靠注意力,定向注入才可靠（实跑教训：Infinity 防线教训在库仍复发）
- **必扫「待触发备忘」段**：逐条判断触发条件是否与本 feature 相关——命中 → 升级为任务或在执行计划中显式认领；未命中 → 不动。扫过即在执行计划输出一行 `📌 备忘扫描: 命中 {N} 条 / 共 {N} 条`，零条也要输出（可见性纪律）

## 执行计划

分析 tasks.md 的依赖关系，自行决定串行或并行：

| 串行 | 并行 |
| ---- | ---- |
| 有显式依赖 | 无依赖 |
| 会修改同一文件/模块 | 分属不同代码项目 |
| 涉及共享状态定义（schema、API、design token） | 天然隔离 |

并行执行完全遵守 `runtime/orchestration.md`。Codex 中只在运行时确实支持子代理、边界不重叠且主执行者仍保留 specs/度量/git 单写权时派发。指令必须包含：任务编号、specs 摘录、接口契约、文件范围、应用的 `cm-*-engineer` skill 及显式验证命令。任何条件不满足就串行。

**分工原则**：子代理只实现指定任务，不碰界外文件、不写 specs、不提交、不自行标记。主执行者回收产出后逐个验证并走 N4 → N5；QA 与 doc-sync 保持串行。

不依赖任何 Claude 实验开关或固定 agent 文件名；Codex 的具体并行能力由当前会话工具决定。

输出：

```text
📂 Feature {N}/{总数} — {feature名}
📋 执行计划：
  串行 1: T-001 → T-002
  并行 2: T-003 + T-004
  串行 3: T-005 ← 依赖 T-003, T-004
```

# N3: 执行 Task

## 开始标记

按 `../../../runtime/project-learning.md` 从磁盘重读各目标项目的 `AGENTS.md`，
在本任务计划中写明适用教训与验证动作；子 agent 只接收摘录、返回候选教训。

改文件前先记录每个目标仓库的 `git status --short`、本任务预期文件集与已存 dirty 文件的 diff 指纹。这份快照供 N4 排除用户改动、N5 精确 stage；未记录就不得使用自动提交。

```text
🔨 Task {T-编号}: {任务描述} ~{预估时间}
   Feature {F}/{总F} | 任务 {N}/{总数}
```

本节点解析 `coder` 角色的有效路由，并把 `adapter`、`model`、`source`、`route_state`
写入任务摘要和 `decision`/`phase: route` 事件。`route_state: declared-adapter` 只表示
请求了当前运行时未观察到的适配器；不得虚构该模型已运行，必要时写
`warning`/`degrade`，仍由本地执行者保持代码修改和验收边界。

## Skill 匹配

根据任务涉及的工种，查看可用的 `cm-*` skills：

- 前端 → `cm-frontend-engineer`
- UI 还原（有 design-baseline） → `cm-ui-engineer`
- 微信小程序 → `cm-miniprogram-engineer`
- 后端 API → `cm-backend-engineer`
- 数据库 → `cm-database-engineer`
- 合约 → `cm-contract-engineer`
- QA/测试 → `cm-qa-engineer`
- 部署/发布 → `cm-devops-engineer`
- 没有匹配 → AI 直接执行

有匹配的 skill → 调用该 skill 执行。

**串行 / 并行的执行方式**：串行任务由主执行者直接按 skill 执行；并行任务按 `runtime/orchestration.md` 为子代理注入对应工种 skill 的角色约束。两种产出都必须由主执行者回收验证，再进入 N4。

并行只读任务无需 worktree；两个及以上任务并行写代码前，主执行者必须按
`runtime/orchestration.md` 执行 `cm-task-gate.mjs check-parallel-write`。非零结果立即
降级串行，不得让多个执行者共享 checkout、分支或 detached worktree。

## 开发

- 参考 design.md 技术设计和 `runtime/project-context.md` 解析出的项目规范
- 技术选型自行选最优解，不暂停
- 业务逻辑歧义按需求最合理解释执行并显式记录假设；**仅灾难级**（不可逆破坏/资金密钥合规/形态级错向）暂停——见 $cm-ai 全局规则
- **依赖与工具链纪律**：新引入的依赖/构建工具必须**钉版本写进 manifest**（dependencies/devDependencies），禁止在脚本里临时 `npx` 拉 latest（不可复现，锁网 CI 直接挂）；工具链改动在提交信息中单独说明，不静默混入功能变更（实跑教训：防护网脚本裸 npx esbuild 被复审抓出）
- **二开范围纪律：只改任务范围内的代码，禁止顺手重构**——顺手"优化"老代码是存量项目的事故之源；想重构的记入 LESSONS 待触发备忘，事后走 `$cm-refactor` 单独立项、单独审查，不许夹带。改老文件跟老文件风格走，新文件才按新规范写
- **平台专属 API 首次引入必查社区已知问题**：用当前运行时的网络搜索能力查「{API 名} 已知问题/踩坑」。微信小程序、Taro、RN/Expo 这类平台 API 的不可靠组合官方文档未必覆盖；查证结论一行留在任务汇报里

## 长步骤与临时资源留痕

- 启动可能长时间占用的外部命令、桌面应用、浏览器用例或模型回合前，按
  `../../../runtime/logging.md` 写 `progress/start`；只在真实观察到的启动完成、
  Runtime Ready、页面到达或用例阶段变化时写 `progress/checkpoint`，结束写
  `progress/complete`。**不启动后台定时心跳**。
- 每个 blocking browser case 写 `test_run/case_start`，随后只允许一个
  `case_complete` 或 `case_blocked`；同一步同步更新 `.cm-status.json` 的大白话
  detail，避免进程仍运行但日志和状态长时间停住。
- 临时 profile、进程、模型别名、worktree 或 fixture 在使用前写
  `resource/acquired`，清理后用同一 `resource_id` 写 `resource/released`。
  每次新获取使用新的 `resource_id`，释放后的 ID 不复用；`cleanup_failed`
  立即把任务标为 BLOCKED，不得进入 N4。
- 模型发生别名或路由时同时记录 `requested_model`、`effective_model`、`provider`、
  `purpose` 与 `model_equivalent`；不得用别名冒充实际模型。

## 项目安全检查

- 开发前读取项目已声明的安全检查命令（项目规则、CI 或现有脚本），确认适用于本次任务；优先复用上线扫描口径，不自行安装扫描器或外发源码。
- 已适用的安全检查与任务测试一起在交接前执行。JS 受保护宿主把命令加入现有 `checkCommands`，保留原测试；普通宿主按原 check 协议回报真实执行结果，不新增安全节点。
- 扫描命令只有完成检查且无项目定义的阻断问题时才能退出 0。非零、工具缺失或超时均阻止交接；不得用 `|| true`、删除检查或忽略规则来换取通过。
- 有问题先在已批准范围内修复并重跑；修复超范围或无法执行则按原 blocked/恢复流程处理，不重置 attempt 或覆盖已有 handoff。
- 未配置时如实说明“未执行安全扫描”；项目或本次任务要求扫描却缺命令时保持阻塞，不用 AI Review 代替。无扫描要求的项目沿用原流程，不自动宣称安全通过。

接入示例和退出码约定见 [项目安全检查接入](../../../docs/js-workflow-control.md#项目安全检查接入)。扫描结果进入已有 verification；原始敏感输出不复制进 Review。

## 单测覆盖缺口

开发期间同步补本任务已授权的单测；在最终 handoff 前按
`../../cm-test/references/unit-coverage.md` 检查本 task working-tree scope 的增量覆盖率，
补关键正常/异常/边界场景并重跑，测试与代码一起交 N4。复用现有框架/命令；
工具或分支证据缺失如实记未测得，不估算、不为 100% 弱化断言，保留既有项目门禁。

## 结构化交接门禁

若这是全部 feature 的最后一个待完成任务，在定稿 handoff 前调用 `cm-doc-syncer`
同步项目文档，并按 `../../codebase-context/references/writeback.md` 增量更新业务地图
（不存在时建最小局部地图，项目指定文档优先）；仅修改本任务事先批准的文档范围，
缺范围先走规格变更批准，不自动扩 scope。文档与代码一起检查、定稿并交给 N4 审查。
项目指令仍由主执行者按原权限及 Learning 合同处理，不向开发子 agent 开放受保护目录。
JS 宿主可通过 `execution.documentationSync` 接入此步骤，写入处于原持久开发调用内；
重启中的未知调用不得重发。最后任务是否成立必须核对所有 feature，不能只看当前 feature。
同步输入汇总本 specs 批次所有 feature/task 的变更证据（包括前面任务仍未提交的修改），
不只看最后任务；只读汇总不扩大最后任务的文档写 scope。JS 启动前按共享回写合同把参考的
现有地图加入 run definition 的 `requirements`；新建/删除/改名改由 diff 携带，未改地图仍须正文可见。

写 handoff 前按 `../../../runtime/project-learning.md` 完成本任务复盘与必要的
AGENTS.md 增量写回；将学习结果、文件摘要记入已有交接字段，变更文件进入
`changed_files` 和 N4 审查范围。无新增明确记录，不把复盘推迟到整批任务结束。

实现和任务内验证结束后，主执行者依据真实 diff、命令输出和子代理汇报，写入：

`{SPECS_DIR}/.reviews/{feature}-{任务号}-a{attempt}-handoff.json`

格式严格遵守 `../../../runtime/task-handoff.schema.json` 与
`../../../runtime/task-gates.md`。子代理只能返回候选字段；由主执行者核对并落盘，
不得让子代理写 `.reviews/`。`ready_for_review` 必须所有 verification 都是 `passed`，
且 blockers/scope_deviation 为空；`changed_files` 使用正斜杠分隔的项目相对路径。

**交付前逐条核对任务的 `verification`**：开发请求的 `specification.task.verification`
来自 `tasks.md` 的「验证要求」段（由 `runtime/js/cm-ai/specification-material.mjs` 提取）。
把它当检查清单，**逐条**写出满足它的证据位置——哪个文件哪一行、哪次命令的哪段输出。
有一条对不上就补做，补不了就写 `blocked` 说明缺口，不得交付。要求里写「分别记录
A、B、C 三种状态」就必须三种都在，写「在 X 路径上走查」就必须是 X 而不是等价替代；
用了替身（命令桩、脚本派发事件、非指定服务器）时，在证据里显式标注边界，不要让
结论读起来像端到端验证过。这一步不是形式：本仓库实跑统计显示末任务
（承担 feature 级走查与证据文档的那个）第一轮审查通过率仅 1/5，被打回的 P2 全部是
「证据没满足任务里已写明的验证要求」——不是代码缺陷，是本可在此自查掉的遗漏。
否则写 `blocked` 并停止，不进入 N4。写 handoff 前，必须以完全相同的
`changed_files` 计算实现内容摘要：

```bash
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py hash-implementation \
  --project-root {CODE_PROJECT} \
  --file path/to/changed-file \
  --file path/to/another-file
```

把 JSON 返回的 `implementation_sha256` 原样写入 handoff；不得用 handoff 文件自身的
SHA 替代它。后续若任一已审文件内容变化，必须生成下一 attempt 并重新审查。

进入 N4 前必须真跑：

```bash
node {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.mjs check-n4 --require-learning \
  --handoff {HANDOFF_PATH} \
  --reviews-dir {SPECS_DIR}/.reviews \
  --feature {FEATURE_SLUG} \
  --task {T-xxx} \
  --project-root {CODE_PROJECT}
```

attempt 2 只有在第 1 轮凭证为 `changes_requested` 时才会通过。不得创建 attempt 3。
保留命令 JSON 返回的 `handoff_sha256`，N4 写 Review 凭证时必须原样使用。

# N4: Review

每个 task 完成后必须执行，按**单个 task 粒度**审查。完整通道与凭证格式见 `../../../runtime/review.md`，入口 handoff 与状态转换见 `../../../runtime/task-gates.md`。N3 的 `check-n4` 未通过时不得开始审查。

进入审查前解析 `reviewer` 角色并记录 `decision`/`phase: route`；角色配置只能描述请求
的审查适配器和模型别名，不能替代本节要求的独立上下文。若 `route_state` 是
`declared-adapter`，如实记录未观察到适配器，仍不得把作者模型或外部专家当作独立审查。
版本 1 不接受 `reviewer.adapter: openai-compatible`：该文本调用不能生成 N4 认可的
独立凭证，配置校验会在调用前拒绝，避免白白消耗 API Token。

开始审查前确认 N3 的 `check-n4` JSON 返回 `content_bound: true`。这表示 handoff 的
`implementation_sha256` 已按项目根复算，审查结论不仅绑定文件名，也绑定被审文件内容。
历史无摘要 handoff 只能在明确披露降级时用 `--allow-legacy-unbound` 恢复，不能作为新任务凭证。

## 1. 主执行者自审

检查本 task 变更的：

- 代码质量：命名、结构、可读性、是否符合项目上下文约束
- 逻辑正确性：边界条件、错误处理、并发安全
- 安全性：密钥、环境文件、注入与权限绕过
- 性能：N+1 查询、重复计算、资源泄漏
- 测试质量：断言是否验证行为，是否存在怎么改都会通过的安慰剂测试

发现问题先形成自审 finding；不要在 N4 修改实现文件。有效问题按本节第 3 步返回
N3 生成下一次 handoff，避免已校验的证据与实际代码失配。

## 2. 独立审查（强制）

自审通过后，按以下顺序选择一个**新上下文**的审查者：

1. `codex-subagent`：用当前运行时的 no-history/fresh-context 选项（如 `fork_turns: none`）新建独立 Codex 子代理/线程，只接收任务范围、验收标准、diff 和验证结果
2. `codex-cli`：子代理不可用时，启动隔离的非交互 Codex CLI 审查会话；禁止它修改文件
3. `claude-cli`：按项目声明选中 Claude 时，使用 protected host 的全新 CLI 审查进程，匹配诊断并逐轮授权；双家声明要求 coder 与 reviewer 不同家，单家使用同家的全新上下文
4. 所选独立通道不可用：保持待审，记录通道失败原因，不进入 N5；`self-degraded` 只作诊断，不能批准完成

通道故障不伪造代码 finding，也不消耗实现审查轮次；有效阻塞 finding 不能靠换
审查者洗掉。`claude-cli` 只有在 protected host 实际启动独立审查进程，并经 V3 登记、回收匹配凭证后，才可写 `independent: true`；声明、诊断或文本自报均不得冒充。真实模型实跑仍待验收。

审查输入只包含**本 task 的 diff**，不得将整个未分类 working tree 当作任务 diff。审查者必须：

- 假设这个 diff 有害，优先寻找可复现的失败场景
- 对照 requirements/design/task 验收，检查超范围变更
- 按严重度排序；每条必须说明「输入/状态 → 错误结果」
- 找不到真实问题时明确写「零发现」，不凑数

该 feature 存在 `test-cases.json` 时，把 `taskIds` 命中当前 task 的 logic cases
加入 review package。逐例按 `runtime/test-contract.md` 输出
`SUPPORTED | CONTRADICTED | INSUFFICIENT_EVIDENCE`；`SUPPORTED` 只是静态代码
证据，**不得冒充单测或运行时 PASS**。`CONTRADICTED` 作为有效 finding 处置，
`INSUFFICIENT_EVIDENCE` 转交 N6 的正式命令或运行时验证。

核验类任务（脚手架、依赖、模板配置）也要过独立审查；输入改为关键产物、预期模板与构建/类型检查结果。

## 3. 处置与轮次上限

- 独立审查完成且无阻塞发现 → 本轮写 `verdict: approved`、`independent: true`，交给 N5 机械校验
- 有效发现且当前为第 1 轮 → 写 `verdict: changes_requested`，返回 N3 生成 attempt 2 handoff，再用同一级别的新鲜上下文复审
- 第 2 轮仍有阻塞发现 → 写 `verdict: blocked`，停止并进入人工处置，不得创建 attempt 3
- 误报 → 记录理由后忽略
- 最多 2 轮；偏好分歧若不阻塞，必须明确写 `approved` 并将双方理由写入 LESSONS.md
- 分歧涉及安全、资金或数据正确性 → 暂停等人裁决；只涉及风格/偏好 → 保留当前实现并记录放行

## 4. 审查凭证（强制）

每轮原始结果立即写入：

`{SPECS_DIR}/.reviews/{feature}-{task}-r{轮次}.md`

显式重跑会先把旧运行同名 handoff／回执按 SHA-256 归档到 `.reviews/.superseded/`，再让新 runId 使用这些原文件名。审查时只消费当前运行新发布的 handoff，不把归档文件或旧 journal 当作本轮批准。

文件顶部必须包含：

```yaml
---
reviewer: codex-subagent | codex-cli | claude-cli | self-degraded
independent: true | false
task: T-xxx
attempt: 1
round: 1
verdict: approved | changes_requested | blocked
blocking_findings: 0
handoff: {feature}-T-xxx-a1-handoff.json
handoff_sha256: <check-n4 JSON 返回值>
at: 2026-07-22T10:00:00+08:00
scope:
  - path/to/reviewed-file
---
```

`attempt` 必须等于 `round`，`handoff` 必须指向本轮 N3 的执行证据，
`handoff_sha256` 必须逐字使用 `check-n4` 的输出。`scope` 必须逐项覆盖 handoff
里的全部 `changed_files`；正文必须写实际 findings 或明确的「零发现」。
`approved` 必须写 `blocking_findings: 0`；其他 verdict 至少为 1。
`self-degraded` 必须写 `independent: false`，并用非空 `degraded_reason` 记录所选独立
通道为何不可用。
历史自审凭证可审计，但 `independent: false` 即使写了 approved 也不能授权新完成。
**无有效独立凭证或 verdict 不是 approved = 不得完成**，N5 必须执行 `mark-done`，
不能只检查文件存在或先校验再手工勾选。

任何阶段修改被审代码、测试或执行指令后，原批准不覆盖新内容；按
`runtime/review.md` 重新形成证据。已标记完成后的补正不得自动重开任务或重置轮次。

## 5. 度量

供 N5 使用的结果：审查通道、轮次、被采纳的拦截数、忽略数及一句话理由。METRICS 保持原列顺序，将原「Codex拦截」语义升级为「独立审查拦截」。

# N5: 标记完成

**强制，不可跳过。** 遗漏会导致断点恢复时重复执行任务。

## 步骤

先按 `../../../runtime/project-learning.md` 核对本 task 已复盘：有新增时须确认
AGENTS.md 已写入、被本次独立审查覆盖且磁盘摘要未变化；无新增须有明确记录。
缺记录、写入失败或批准后变化均不得执行下面的标记命令；回到 N3/N4，保留轮次。

0. **审查结论与标记原子卡点（必须真跑命令不许目测或手改）**：执行下列命令并保留 JSON 输出：

   ```bash
   python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py mark-done --require-learning \
     --handoff {SPECS_DIR}/.reviews/{feature}-{任务号}-a{attempt}-handoff.json \
     --reviews-dir {SPECS_DIR}/.reviews \
     --feature {FEATURE_SLUG} \
     --task {T-xxx} \
     --tasks {SPECS_DIR}/{FEATURE_DIR}/tasks.md \
     --project-root {CODE_PROJECT}
   ```

   `{FEATURE_DIR}` 是实际 feature 目录（例如 `2.bulk-clear-completed`），`{FEATURE_SLUG}`
   是审查文件使用的不带序号 slug；二者不得混用。门禁只接受当前 feature 目录中的
   权威 `tasks.md`，specs 根目录、其他 feature 或别名路径均拒绝。

   非零退出、当前 Review 不是 `verdict: approved` 或不是 `independent: true` = **不许标记**；成功 JSON 必须是
   当前 attempt 且 `outcome` 为 `marked_done` 或幂等恢复时的 `already_done`，并且
   `content_bound: true`。
   `changes_requested` 回 N3；第 2 轮 `blocked` 停止等人工。门禁在同一进程重新校验
   证据并原子替换当前 feature 自己的 `tasks.md`，只改精确匹配的任务 checkbox；
   specs 根目录或其他 feature 的同名任务文件会被拒绝。不得先跑 `check-n5`
   再手工勾选，也不得只执行 `ls`。
1. **立即验证**：命令成功后重新读取 tasks.md，确认该任务确实已标记为 `[x]`

```diff
- - [ ] T-007: 安装依赖 ~5min
+ - [x] T-007: 安装依赖 ~5min
```

## 关键约束

- 每完成一个 task **立即标记**，不批量、不延后
- 文件编辑失败则重试，不得在未落盘时继续
- 进入 N7 从磁盘重载上下文前，必须确认标记已写入
- 自审凭证只用于历史审计/诊断，不能授权新完成；无独立通道保持待审，不绕过门禁
- 任意阶段变更被审代码、测试或执行指令，旧批准不覆盖新内容；已完成后的补正保留旧记录，按 `runtime/review.md` 暂停等明确授权，不自动另建任务重置轮次

## Git 提交（每任务一次）

标记验证通过后按 N1 保存的 `DELIVERY_MODE` 分支：

- `branch` / `draft-mr`：提交本任务全部变更（代码 + tasks.md 标记）。
- `diff`：不 stage、不 commit，METRICS 备注 `delivery-diff`，回读行写
  `commit 跳过(diff)`；所有任务保持串行，避免未提交 diff 相互覆盖。

```bash
git -C {CODE_PROJECT} add -- {该仓库内本任务新增/修改且开工前干净的相对路径}
git -C {CODE_PROJECT} diff --cached --check
git -C {CODE_PROJECT} commit -m "T-{编号} {feature名}: {任务标题}

审查: 自审通过 | 独立审查({channel}) {N}轮 采纳{N}条 忽略{N}条({一句话理由})"
```

- **禁止 `git add -A` / `git add .`**：必须使用 N3 开工前记录的 dirty 清单与本任务文件集显式 stage，并用 `git diff --cached --name-only` 回读。不得把用户的先存改动带入任务提交
- specs 与代码项目可以是不同目录/仓库：每个代码仓库只 stage 自己根目录下的任务文件；
  feature `tasks.md`、`.reviews/`、METRICS 在代码仓库外时不得传给该仓库的 `git add`。
  specs 自身另有 Git 仓库时可用单独审计提交，否则由 specs 落盘物保持审计，不能因
  跨仓库路径导致代码提交失败（实跑结构：`$cm-ai {specs} {code}` 默认就是两条路径）。
- 本任务必须修改一个开工前已 dirty 的文件时，不得按整文件 stage。只有能构造并回读「本任务新增 hunks」时才提交；否则跳过自动提交，METRICS 备注 `dirty-overlap`，保留用户工作区
- **commit message 必须含任务编号**——"任何一行代码回溯到任务"靠这一步实现（`git log --grep "T-003"` 即可验证）
- **一次实现天然覆盖多个任务时**（拆分过细的兜底）：message 必须列出全部编号（如 `T-005/T-006 ...`），各任务分别标记、METRICS 各记一行并备注"并入 T-xxx"——禁止只写其一导致审计链断点
- 审查摘要来自 N4 的度量记录
- **任务产物已在既有提交中**（典型：T-001 的产物就是脚手架自带的 initial commit）→ 用 `git commit --allow-empty` 打一条核验提交，message 照常规格式并指认产物所在的 commit sha——审计链"每任务一提交"不留空洞
- **项目上下文的版本控制字段 = `none`**（或 N1 兜底设定 NO_GIT）→ 仅 delivery=diff 可继续并跳过本步，METRICS 行备注 `no-git`，进度输出的 🔁 回读行中提交项写 `跳过(none)`

每个代码仓库提交成功并回读 SHA 后，按 `../../../runtime/logging.md` 分别写
`delivery/commit`，只记录 project、task、branch、commit SHA 和证据路径；提交失败或
跳过时不得伪造 delivery 事件。

## 度量落盘（METRICS.md）

标记完成后，向 `{SPECS_DIR}/METRICS.md` 追加本任务一行（文件不存在则先创建表头）：

```markdown
| 任务 | Feature | 开始 | 结束 | 审查轮次 | 独立审查拦截 | QA | 人工介入(次:原因) | 执行方式 |
| T-003 | 1.user-auth | 10:02 | 10:41 | 2 | 1 | — | 1:业务歧义 | 串行 |
| T-004 | 1.user-auth | 10:41 | 11:03 | 1 | 0 | — | 0 | 并行:组内2个 |
```

- 审查轮次 / 独立审查拦截数来自 N4；QA 列先写 `—`，N6 触发时回填
- 人工介入：本任务执行期间每次暂停问人计 1 次并注明原因（技术选型自主决策不计）
- 执行方式：本任务串行执行写 `串行`；作为批次并行组成员执行写 `并行:组内{N}个`（N 为该组成员数）。
  这一列是判断并行是否真的省时间的唯一依据——没有它，无法区分耗时变化来自并行还是任务本身
- 这张表是试点/灰度门槛（人工介入 ≤2 次/任务、一次通过率等）的**唯一数据源，不可跳过**

## LESSONS.md

如有值得记录的内容追加到 `{SPECS_DIR}/LESSONS.md`：

- 架构决策及理由、踩坑记录、跨 feature 影响、环境/依赖特殊处理

不记录常规开发、显而易见的事情。格式：`## {日期} — {Feature名} / {Task标题}`

**条目分级（实跑教训：Infinity 防线进了 LESSONS 仍复发——纪律靠记忆不可靠）**：

- 每条教训标注 `[已结构化]`（已落为测试用例/校验代码/lint 规则，防线不靠记忆）或 `[仅记忆]`（只有文字）
- **`[仅记忆]` 是欠账**：此处只记录结构化建议，供后续获准的任务处理；不得在标记完成后顺手新增测试、校验代码或执行指令。`[已结构化]` 仅描述已有且已验证的防线，不能把建议当成已实现
- **备忘/已知限制类**（"V1.x 需要……""等真实反馈再定"）不混入正文，写入文件顶部的 **`## 待触发备忘`** 段，格式：`- [挂起] {触发条件} → {事项}（来源 T-xxx）`——否则埋进只写不读的正文里，到期无人认领（实跑教训：warnings 无 UI 出口备忘无回流出口）

## 输出进度

```text
✅ Feature {F}/{总F} | 任务 {N}/{总数} — {标题}
🔍 主执行者自审: {结果} | 🤖 独立审查({channel}): {结果}
🔁 回读: tasks.md T-{编号}[x]已确认 | commit {短sha}含T-{编号} | METRICS 行已写 | 门禁 {mark-done JSON 输出中的 review} | 学习 {AGENTS.md已写回并回读/已复盘，无新增}
📊 Feature {done}/{total} | 总体 {done_f}/{total_f}
```

**🔁 回读行是强制字段**——五项分别重新读取文件/执行命令确认后才能输出；本行缺失即视为 N5 未完成，不得进入 N6。学习项回读 N3 的复盘记录与相应 AGENTS.md，不在此时追加新指令。不可见的纪律等于没有纪律（实跑事故教训：静默失败只有回读能发现）。

# N6: QA 评估

AI 动态决策是否触发 `cm-qa-engineer`，不按固定间隔。

QA 开始前解析 `tester` 角色并记录 `decision`/`phase: route`；浏览器走查另外解析
`browser_qa`。路由元数据只说明请求的工具/模型别名，正式命令、逻辑核验和浏览器
证据仍必须由本地 QA 合同实际产生。

同时读取有效配置的 workflow profile 与 `policies.tests`：`java-backend` 优先
commands/logic 及 API、数据库回归；`web-frontend` 优先 commands/browser；
`cm-default` 按 logic→commands→browser。`policies.tests` 只关闭未被规格要求的可选
类型；`test-cases.json` 中 blocking case 即使类型未列出也必须执行，环境不可用则
`BLOCKED`，不得把配置当作跳过已审批验收的许可。

feature 未完成时，只执行 taskIds 全部已完成且未 dropped 的用例，其余记入 `deferred_cases`，延后到 feature 收尾；延后用例不计入执行数量，也不派发宿主请求。feature 中途无可执行项时产生一条显式 `BLOCKED` 行，id 为 `no-applicable-cases`，不得以零测试宣称通过。

最新已 complete 的 QA 若为纯宿主/环境证据 BLOCKED、failed=0 且 qaRound<3，可按 [JS 宿主入口](js-host.md) 显式 `--rerun-blocked-qa --allow-qa` 恢复，以 superseded 关联下一轮全量重跑；产品 FAIL、commands 阻断与未 complete 不适用，完成后同步 N6 状态镜像。

## 评分（1-5 分，总分 ≥ 8 触发）

| 维度     | 1 分                 | 5 分                  |
| -------- | -------------------- | --------------------- |
| 变更范围 | 单文件小改动         | 跨多模块/多项目       |
| 风险等级 | 纯 UI 文案           | 数据库/支付/认证      |
| 累积变更 | 上次 QA 后 1 个 task | 上次 QA 后 5+ 个 task |
| 功能边界 | 模块内部实现         | 完整用户可感知功能    |

## 必须触发（无需打分）

- 当前 feature 所有 task 完成
- API 接口变更（**收尾合并豁免**：下一个任务就是本 feature 最后一个任务时，可合并至 feature 级 QA 一次执行——避免背靠背双跑全量；合并决策记运行日志 `decision` 事件。实跑教训：后端 feature 几乎每任务都改 API,逐任务触发 QA 成本失衡）
- 数据库 migration
- 认证/授权/支付逻辑
- 连续 5 个 task 未触发过 QA（缺少 N6 历史行的计数仅含尚未完成 feature 的已完成任务；自上次 triggered 以来的 skipped 任务语义不变）

## 跳过

- 纯文档/注释/配置格式
- 仅新增类型定义（未实现）
- 上一个 task 刚触发过 QA 且当前变更极小

**跳过也必须留痕**：无论触发还是跳过，每个任务的 N6 结论都写一条 `qa` 事件进运行日志（`触发:原因` / `跳过:评分{N}` / `合并至feature级`）——cm:ai 必记事件本就含 qa，此处重申是因为实跑失守：json-keeper 7 个任务 0 条 qa 事件，N6 被整场静默绕过，连"连续 5 个 task 未触发"的必触发条款命中了都无人知晓。**不可见的跳过等于没有 N6**

## 触发格式

```text
🧪 触发 QA — 原因: {理由}
   累积变更: {N} 个 task | 风险评估: {总分}
```

QA 通过 → 继续。发现问题时，**不得在 N6 直接修改**已由 N4 绑定并在 N5 提交的
代码或测试；先保存失败报告，再按有效配置的 `policies.auto_fix` 走唯一分支：

- auto_fix: `never` → 写 `BLOCKED` 并报告，不修改。
- auto_fix: `explicit` → 展示缺陷摘要，取得本次修复授权后调用 `$cm-fix`。
- auto_fix: `auto` → 直接调用 `$cm-fix`，不额外停车。

`$cm-fix` 必须生成自己的结构化 handoff、通过独立审查门禁并按 delivery 策略落盘；
QA 新增或修正测试也属于该 fix diff，不能在旁路写入。修复闭环后重新 QA，总计最多
3 轮；仍失败则 `BLOCKED`。这样原 task 的审批 SHA 不被事后覆盖，QA 修复拥有独立
审查、提交与日志证据。

实际触发 QA 时按 `../../../runtime/logging.md` 写 `test_run/start` 与
`test_run/complete`，记录模式、用例/通过/失败/阻塞数量、结论和报告路径；start 与固定执行报告另列 `deferred_cases`（id 与未完成 taskIds）；
测试输出、截图和浏览器日志仍留在 `.reviews/`。

feature 存在 `test-cases.json` 时按 `runtime/test-contract.md` 消费：中途 QA 的命令按
选中 logic 用例映射，无用例映射的独立命令沿用配置策略；browser cases 由
`cm-qa-engineer` 逐条模拟并保存截图/日志；
N4 中的 `INSUFFICIENT_EVIDENCE` 必须在本节点补运行时证据或保持 `BLOCKED`。
任一 blocking case 为 `FAIL`/`BLOCKED` 时不得宣称 QA 通过。

交付形态为微信小程序时读取
`../../cm-miniprogram-engineer/references/release-checklist.md`，按 feature 实际能力补
开发者工具模拟器与真机专项。Web/H5 截图不计小程序证据；授权、设备差异或平台 API
缺真机证据时保持 `BLOCKED`/待人工，不能用静态核验或模拟器推断通过。

**QA 新补的测试须变异自证**(机械,非审查轮):种 1-2 处行为变异必须变红,不红的测试修到红再入库——QA 测试是未来所有回归的安全网,安慰剂 QA 测试 = 永久性假安心(实跑先例:dogfood 中 QA agent 自发做过「5 个变异全被抓」,本条把自觉变成规则)。

触发 QA 后，回填 METRICS.md 中对应任务行的 QA 列：`通过(覆盖率{x}%)` / `{N}轮通过(覆盖率{x}%)` / `失败上报`——覆盖率随列落盘，不留在会话里。

## 形态确认卡点（仅 0.bootstrap 完成时，一次性）

`0.bootstrap` 完成触发的 QA 中，**必须**执行形态确认：启动 dev server / 模拟器 / 开发者工具，截取首屏发给用户——

```text
📸 形态确认：这是项目当前的形态（{Web 页面 / App 模拟器 / 小程序}），与你要的交付形态一致吗？
```

**截图来源按 CLAUDE.md 交付形态写死**（防"替代形态截图糊弄卡点"）：

- Web → 浏览器访问 dev server
- **App → iOS/Android 模拟器或 Expo Go 真机截图；react-native-web / `expo start --web` 的浏览器截图不作数**——浏览器里渲染出"长得像 App 的网页"恰恰是本卡点要拦的形态错配
- 小程序 → 微信开发者工具模拟器

模拟器环境不可用 → 如实上报，请用户在本机/真机启动确认；**不得用替代形态的截图过卡点**。

**用户确认后才进入业务 feature**。成本是一张截图 + 3 秒确认；收益是架构错配的发现时点从"任务过半"提前到"零行业务代码"（历史事故：要 App 画成了 HTML，跑到一半才发现）。

## 业务验收走查（feature 完成时）

触发原因为「当前 feature 所有 task 完成」且 QA 通过后，调用 `cm-product-manager` skill 做**业务验收走查**（用户视角流程闭环 + AC 逐条对照，非技术测试）：

- 小偏差 → 记录进走查报告，继续
- 涉及需求本意的偏差 → 暂停问人，不自行认定"也可以"

金融/营销类 feature 的走查协同 `cm-finance-expert` 追加金融视角（数字口径抽查 + 营销红线扫描）；**涉合规的偏差一律上报，不适用"小偏差放行"**。

# N7: 上下文管理

## task 完成后

**重读落盘文件即是"重载",不需要清上下文,更不需要停车**:

- 当前 feature 的 specs(requirements.md、design.md、tasks.md)
- `{SPECS_DIR}/LESSONS.md`
- `runtime/project-context.md` 解析出的 `AGENTS.md` 指令链与 `.claude/` 兼容规则

重读完成后**直接继续下一个 task,不停车、不等用户、不以问句收尾**。

> 以磁盘为准重读 specs 才是防漂移的有效动作；不依赖 Claude 的 `/clear` 或 Codex 的会话压缩细节。压缩摘要可能丢数字，落盘文件不会。

## task 执行中

察觉上下文被自动压缩过(前文变成摘要)→ 继续当前 task 前,重读本 feature 的 specs 与当前任务相关的 design 章节,以落盘文件校准记忆,不信摘要里的细节数字。

## feature 完成后

同上重读,直接进入下一个 feature。

全程自动继续。**唯一合法停车点**：$cm-ai 全局规则的灾难级清单 + 各节点显式卡点（入口闸/高风险审查降级/形态确认/涉合规走查）。

# N8: 完成

所有 feature 的所有任务完成后：

## 1. 核验文档同步

项目文档已在最后任务的 N3、定稿 handoff 和 N4 Review 前通过 `cm-doc-syncer`
同步。此处只核验，不在已完成任务后改写项目文件：

- README 精炼更新（架构 + 业务 + 快速开始）
- `AGENTS.md` 与 `.claude/CLAUDE.md` / rules 兼容文档同步
- specs CHANGELOG 等收口元数据按日期生成，不改 requirements/design/tasks
- 文档一致性验证

文档仍需修改时保持 BLOCKED，经规格变更批准回到正常任务路径；不重开旧任务、
不扩大已批准范围、不覆盖旧 Review。生产发布和 Git 交付权限不由同步结果产生。

## 1.5 核验业务地图回写

按 `../../codebase-context/references/writeback.md` 核验本次全部 feature 的地图评估及
必要回写已在 N3、Review 前完成；无地图不能静默跳过，局部地图不能声称全仓覆盖。
允许有依据的“无需更新”或项目规则豁免；标准目录实际更新时核验 `dev回写` 条目。
缺评估、待同步或审后漂移保持 BLOCKED，不在此处绕过已审查的项目文件快照补写。

## 1.7 最终工作树与交付策略

对每个代码项目分别回读有效 `DELIVERY_MODE`，执行 `git diff --check` 并核对 N8 新变更：doc-syncer 只能
产生 specs 收口元数据；若出现新的项目文档、源码、配置或依赖变更，说明有修改绕过任务审查，立即
`BLOCKED`。然后按唯一分支收口：

- `diff`：不 commit、不 push、不创建 MR；输出基线 SHA、`git diff --stat` 和完整
  diff 位置。工作树 dirty 是预期交付，但不得含开工前用户改动之外的范围外文件。
- `branch`：显式 stage N8 生成的文档/specs 文件，`git diff --cached --check` 后补一条
  `docs: sync CM workflow artifacts` 提交；确认工作树只剩开工前用户改动。停在本地分支。
- `draft-mr`：先完成 branch 收口，再逐仓库展示 remote、branch、目标分支和将执行的 push/MR
  命令，**取得本次明确授权**后才执行。GitHub 使用 `gh pr create --draft`，GitLab 使用
  `glab mr create --draft`；CLI/remote/权限缺失则 `BLOCKED` 并保留本地分支。push 与
  MR 各自成功后才写 `delivery/push`、`delivery/pull_request`，不得以配置代替授权或
  伪造远端结果。

branch/draft-mr 在写 `run_done` 前必须确认每个代码仓库的 CM 变更已全部进入可回溯
commit；diff 模式则逐仓库确认没有新 commit。specs 位于代码仓库外时单独报告其落盘
路径，不尝试从代码仓库 stage 跨仓库文件。该门禁防止 doc-syncer 在“全部完成”之后
留下未交付变更。

## 2. 生产发布待决清单

**前置**：项目存在部署或平台发布形态才执行本步。信号包括 Dockerfile / CI 配置 /
部署脚本、`{SPECS_DIR}/RELEASES.md`，以及已确认的 App/微信小程序交付形态（小程序可
由 `project.config.json` + `app.json` 或跨端微信构建目标识别）。**纯本地工具、库等
无发布形态的项目 → 跳过**，总结中输出一行 `🚀 发布清单: 跳过(无发布形态)`。

调用 `cm-devops-engineer` skill **编制**（只编制，不执行生产发布）。**staging 验证状态的数据源是 `{SPECS_DIR}/RELEASES.md`**，不凭记忆：

- 已通过 staging 验证的 feature 清单及版本（读 RELEASES.md）
- 生产迁移清单与执行顺序（含备份点）
- 新增环境变量清单（值由人在生产环境配置）
- 回滚预案位置

微信小程序另外读取 `../../cm-miniprogram-engineer/references/release-checklist.md`：
即使尚未上传体验版，也要编制主体/类目、隐私权限、域名环境、L1–L3 证据和提审材料
待决项；`RELEASES.md` 不存在时明确写“体验版未上传”，不得把 N6 模拟器结果伪装成
staging/体验版验证。

**生产发布由人决策触发**，不属于本流程的自动动作。

## 3. 度量汇总

读取 `{SPECS_DIR}/METRICS.md`，**只统计本次执行涉及的 feature 的行**（按 Feature 列过滤——防止历史批次数据混入本次门槛对照），全量历史另起一行标注"累计"。输出：

```text
📊 度量汇总
任务: {N} 个 | 人工介入均值: {x} 次/任务 | 一次通过率(复审仅1轮): {x}%
独立审查拦截: 共 {N} 条 | QA: 触发 {N} 次/通过 {N} | 总耗时: {x}
💰 成本: 从当前运行时的 usage/成本面板取得；不可用则记「未采集」
```

**审查凭证对账**：tasks.md 全部 `[x]` 任务 ↔ `{SPECS_DIR}/.reviews/` 凭证一一对账，缺失项列入度量汇总（`⚠ 审查凭证缺失: T-xxx,...`，全齐则 `审查凭证: {N}/{N} 齐`）——中途漏网的审查，收尾必须暴露，不许无声混过。
显式重跑后的旧凭证位于 `.reviews/.superseded/`，仅作历史；对账只认当前文件名下的新凭证，不能用归档回执补齐当前任务。

**临时资源对账**：读取当前 run 的项目权威日志，按 `resource_id` 对账
`resource/acquired`、`resource/released` 与 `resource/cleanup_failed`。只有同一
资源最后状态为 `released` 才算闭环；存在未释放或清理失败资源时输出清单、将状态
改为 BLOCKED，并且**不得写 `run_done`**。没有 resource 事件的历史运行保持兼容。

**运行日志收口**：按 `../../../runtime/logging.md` 写 `run_done` 终态事件，使项目日志与
全局索引同时收口；然后报告 `运行日志.jsonl`、全局 run 文件路径与项目日志行数。
提醒用户反馈问题时连同 METRICS.md 一起带回，只报告，不清理不截断。

**成本落盘（灰度门槛「单任务成本 < 人工工时」的数据源）**：如果当前 Codex/Claude 界面提供 usage 或会话费用，将总费用与总耗时写入 `{SPECS_DIR}/度量汇总.md`（`成本: ${x} / {N} 任务 ≈ ${x/N} 每任务`）；无法获得就标注 `成本: 未采集`，不许编造。

## 4. 输出总结

```text
🎉 全部完成

📂 Features: {完成数}/{总数}
📋 总任务: {完成数}/{总数}
📝 文档同步: 已完成
🚀 生产发布待决清单: 已编制，等待人工决策

各 Feature 摘要:
- 1.{name}: {N} 个任务 ✅ (发布验证: {staging/体验版已验证 | 未执行/待人工 | 不适用})
- 2.{name}: {N} 个任务 ✅ (发布验证: {staging/体验版已验证 | 未执行/待人工 | 不适用})
```