Harden delivery gates and reframe checkpoint recovery

.gitignore

@@ -25,6 +25,7 @@ docs/*
 !docs/platform-adapters.md
 !docs/engineering.md
 !docs/12-lifecycle.md
+!docs/man-module-delivery-plan.md
 
 # Node.js
 node_modules/

docs/platform-adapters.md

@@ -57,6 +57,10 @@ adapter upgrade 先在 staging 中生成预览，用户确认后再通过 journa
 
 ## Legacy hooks
 
+初始化生成的 `AGENTS.md` / `CLAUDE.md` 现在包含限定于新 `/man` 模块交付策略的文档交接和执行效率规则。项目计划目录优先沿用明确约定，默认 `doc/`；不强制其他模式建计划、审核或提交。规则不保存任务状态，也不授权修改未批准的业务代码。
+
+新 man 入口显式使用 `workflow create man --delivery`，引导一次模块总审、真实验证、文档回写和提交/发布分离。`manba`、`manteam`、`manps`、`mansolo` 的入口流程不变。详细数据格式与限制见 [新 man 模块交付](./workflows.md#新-man一次模块审核与文档交付)。仅更新源码不会改写已安装文件；现有项目仍走上文的 adapter upgrade 预览和确认流程。
+
 只有 `mancode init --legacy` 安装读取 `.mancode/state.json` 的旧 Claude Code hooks。Continuity adapter 不应创建、读取或刷新 legacy authority。
 
 Continuity 的 Claude Code bootstrap 位于根目录 `CLAUDE.md` 的 `mancode:continuity:claude` 托管区，确保普通 Solo 请求也会加载；原有 mode skills 仍位于 `.claude/skills/`。Cursor bootstrap 位于 `.cursor/rules/mancode-continuity.mdc`，其他嵌入式托管区同样使用 `mancode:continuity:*` 标记。升级时只自动移除带 mancode 旧管理标记的 `mancode-v3`/旧 Continuity bootstrap 或托管区；用户在 `CLAUDE.md` 和同名旧文件中的自写内容会保留。

docs/workflows.md

@@ -46,10 +46,107 @@ draft 的 `blockingUnknowns` 必须列出开放决定；scope、coverage、techn
 6. 运行验证并确定 targeted/full 审查范围。
 7. 质量审查。
 8. 仅在 full 深度执行安全与边界审查。
-9. 最多一轮 blocker 修复、复验、summary 和完成。
+9. 必要问题修复、复验、交付记录和完成。新模块交付策略按下节收敛复核，不叠加审核流水线；旧任务仍遵循原策略。
 
 需求未 ready、计划未确认、执行任务缺少非空 implementation scope、验证失败、审查 blocker 未清零、存在活动子任务或未完成 repair 时，任务不能完成。升级前已进入执行阶段的本地 Man 任务可在用户确认完整边界后，用内容不变的当前 plan 和 `--scope-file` 执行一次兼容 plan revision；它只补绑 scope，并使旧 review/verification 失效。
 
+### 新 `/man`：一次模块审核与文档交付
+
+新入口创建任务时传 `--delivery`，显式选用 planning policy 3。省略该选项仍沿用项目默认策略。只有 `man` 可启用；旧任务不能静默升级或降级，其他模式及 Solo handoff 不受影响。更新运行时后，还需按 adapter upgrade 协议更新宿主入口，不能只手改 skill。
+
+policy 3 的每个必需验收项还要按证据槽位声明精确的期望观察面。例如自动化真实 HTTP 验收使用 `{"id":"AC-1","description":"真实 HTTP 返回约定结果","required":true,"method":"automated","verificationSurfaces":{"automated":"real_http"}}`；manual 使用 `manual`，hybrid 同时声明 `automated` 和 `manual`。历史 requirements 和非 delivery 任务仍可读取缺少该字段的记录。
+
+默认路径：一份模块计划 → 实现与相关验证 → 回写待审 → 一次总审 → 必要修复与定向复核 → 提交与完成。只讨论/规划不授权实现。模块以可独立验收的结果划分，不以文件或函数划分。审核既检查“目标到实现”的缺漏，也检查“改动到目标”的偏离，并检查具体缺陷和不必要的复杂度。允许零 finding；可选改进不阻止交付。
+
+#### 绑定一份计划
+
+优先用用户指定或项目已有的计划目录，新项目默认 `doc/`。本项目使用 `docs/`。选定路径随计划权威保存，远程接续不需要再猜目录；没有新增全局目录配置或第二份计划。文件须可正常版本化，不能强制添加被忽略的私有资料。架构资料不可用时，只为会改变实现且无法从计划/现有契约得出的细节请求确认。
+
+```markdown
+<!-- mancode:plan-baseline:start -->
+# 导出模块
+目标、包含/排除范围、相关架构依据、阶段、验收 ID 与验证方法、未决问题。
+<!-- mancode:progress-task export -->
+<!-- mancode:plan-baseline:end -->
+<!-- mancode:delivery-record:start -->
+尚未实现。
+<!-- mancode:delivery-record:end -->
+```
+
+四个区块标记必须独占一行且唯一、有序；代码围栏内示例不参与解析。进度任务标记可省略。基线变化需重新确认；交付区回写不增加计划版本、不改变批准目标。运行时只更新交付区，不覆盖外部手写内容。
+
+```bash
+mancode workflow create man "导出模块" --delivery --session <SESSION_ID> --client <CLIENT> --json
+# 按已有 requirements 协议完成澄清和 finalize 后：
+mancode workflow plan <TASK_REF> revise --file docs/export.md --scope-file scope.json --expected-revision <N> --session <SESSION_ID> --client <CLIENT> --json
+mancode workflow plan <TASK_REF> confirm --plan-decision governed_execution --expected-revision <N> --session <SESSION_ID> --client <CLIENT> --json
+```
+
+每步使用上一结果的新 revision。`scope.json` 的 include 要覆盖计划文件及获授权的进度页面；exclude 仍优先。无 Git 仍能规划和绑定文档，但不能声称版本化交付完成。
+
+#### 验证与总审
+
+JSON 临时输入放在 `.mancode/local/drafts/`，避免把审核输入本身计入被测源码。自动化输入示例为 `{"argv":["npm","test"],"surface":"component"}`；`surface` 必须是实际观察面并与该验收槽位的 `verificationSurfaces` 精确一致。实际选择与验收相称的命令，不为同一事实反复全量测试。
+
+```bash
+mancode workflow delivery <TASK_REF> sync --expected-revision <N> --session <SESSION_ID> --client <CLIENT> --json
+mancode workflow delivery <TASK_REF> verify --acceptance AC-1 --file .mancode/local/drafts/check.json --expected-revision <N> --session <SESSION_ID> --client <CLIENT> --json
+mancode workflow delivery <TASK_REF> inspect --json
+```
+
+`verify` 无 shell 地执行 argv，返回实际 stdout、stderr 和 exitCode，并通过原 journal 写证据。一个命令确实覆盖多个验收项时，可用 `--acceptance AC-1,AC-2` 一次运行并关联多个槽位，不能为逐项登记重复执行同一套测试。CLI 返回 0 表示录入成功，不表示测试通过；查看 `commandResult.exitCode` 和 finalization 状态。命令运行期间源码改变时不记录“通过”。手动/hybrid 验收使用 `confirm` 替代 `verify`，输入 `{"confirmed":true,"surface":"manual_observation","summary":"真实观察或用户确认的来源、结果与非敏感环境"}`；返回 manualConfirmation、记录当前 actor，不能把自述冒充独立认证。实际 surface 缺失或与 requirements 不一致时，即使底层 verification ledger 已记录 passed，最终门禁仍保持 `verification_incomplete`。
+
+实现完整模块后，一名 reviewer 尽可能在获授权的独立上下文审核；无法独立时明确自审。使用批准计划、相关架构、`inspect.source.baseHead` 以来完整 diff、入口调用链与验证证据，不只阅读实现者总结。审核输入：
+
+```json
+{
+  "subject": { "contentDigest": "从 inspect.subject 原样复制", "environment": "从 inspect.subject 原样复制" },
+  "reviewer": "self",
+  "direction": "各验收如何落到入口/调用链；全部改动为何属于计划",
+  "correctness": "主链路和相关失败路径的实际证据、具体风险",
+  "proportionality": "抽象和防御对应哪些真实约束，有无冗余",
+  "nextAction": "仅继续已经授权的下一模块，否则结束",
+  "coverage": [{ "acceptanceId": "AC-1", "status": "met", "evidence": "实现入口与真实验证结果" }],
+  "findings": [],
+  "resolved": []
+}
+```
+
+subject 占位文字不是有效摘要，须替换为 `inspect` 结果。`reviewer` 可为 `self` 或 `independent`，但它只是调用者自述的审核元数据，不绑定另一 actor/session，不能单独证明独立身份；coverage 状态为 `met`、`missing` 或 `unverified`。必修 finding 形如 `{"id":"R-1","domain":"quality","severity":"p1","summary":"因果证据及影响"}`；domain 为 quality/security，severity 为 p0/p1/p2。修复后在 resolved 列出原 finding ID，不通过删掉问题记录来放行。
+
+```bash
+mancode workflow delivery <TASK_REF> review --file .mancode/local/drafts/review.json --review-depth targeted --expected-revision <N> --session <SESSION_ID> --client <CLIENT> --json
+```
+
+涉及实质安全风险时使用 full；同一次总审可给出 quality/security 结论，不拆成三轮审核。复核只覆盖修复及直接回归，无新诊断依据时停止重复操作。每次 verify、confirm、review 自动回写交付记录；投影失败会返回 `deliveryRecord.status=pending` 及原始原因，已成功的账本写入不回滚，用 sync 重试即可。
+
+内容摘要用于证据适用性，不证明功能正确。当前实现保守覆盖 Git 索引、工作区、非忽略未追踪文件，排除 `.mancode/` 和进度页；计划只计批准基线。仅提交或回写记录不废弃测试；源码改变会让旧证据过期，重新验证时清空不适用的其他槽位。外部依赖/环境变化不能仅靠本机 Node/平台标识检测，需主动重新验证。仓库内子模块及外部符号链接尚不支持自动证明，错误必须明确处理，不能猜测适用性。
+
+#### 完成、发布与本地视图
+
+先 sync，再提交本任务的源码、计划和必要页面变更。不要全库 add，不混入他人改动。
+
+```bash
+mancode workflow delivery <TASK_REF> check --json
+mancode workflow complete <TASK_REF> --expected-revision <N> --session <SESSION_ID> --client <CLIENT> --json
+# 若已获授权且当前分支已有上游，正常推送后，可只读核实真实上游：
+mancode workflow delivery <TASK_REF> publication --json
+```
+
+check 检查证据、计划回写、任务文件提交及范围，complete 仍重新执行原有 authority/子任务/repair/claim 门禁。范围外未提交文件不要求加入本任务提交，但必须先移出当前 checkout、stash 或单独提交，因为它可能参与本次验证；同一文件内的他人改动仍需人工区分。基线之后的范围外提交会被拒绝，需处理或重新确认范围，不能静默归为本任务。后置读取失败返回 `inspection_failed` 及原始 diagnostic，不再误报为 delivery record stale。
+
+`publication` 只查询现有 upstream，不 fetch、push 或设置 remote；结果为 published、unpublished 或 unverified。没有 remote/上游或 push 失败不属于业务阻塞，报告“交付未发布”；查询失败不能冒称已发布。shared 的业务分支发布不等同于 Continuity transport 同步，保留既有显式同步和 fence 协议。
+
+可选 `项目进度.html` 只识别以下精确数据契约，不解析/猜测 UI：
+
+```html
+<script type="application/json" id="mancode-progress-data">
+{"schemaVersion":1,"tasks":[{"taskId":"export","status":"未完成","reason":null}]}
+</script>
+```
+
+taskId 来自基线中的显式 progress-task 标记，未提供时为完整 TaskRef。sync 只更新唯一匹配记录的 status/reason；保留其他内容并转义 script 终止符。页面不存在、契约损坏/缺失、ID 不唯一或不在写入范围时返回 absent/manual_sync，不阻止开发。普通修复为“进行中”，已验证待审为“待审核”，审核和验收通过为“已完成”；只有业务状态 blocked 且存在未决外部确认时显示“阻塞”。未开发任务不更新。页面状态不是发布状态，也不替代运行时权威。
+
 ## 状态与 revision
 
 工作流状态为 `in_progress`、`planned`、`blocked`、`completed` 或 `abandoned`。终态不可恢复；`blocked` 只能在阻塞条件被显式处理后回到 `in_progress`。
@@ -113,6 +210,17 @@ mancode workflow checkpoint local:<ULID> show <CHECKPOINT_ULID> --json
 
 archive 输出会校验归档摘要，并返回 reframe 前的 requirements 与 plan；checkpoint 输出返回该次 reframe 的完整 checkpoint。这两个命令不修改 workflow，也不需要 `--session`。
 
+新版本会在 reframe 创建 journal 或修改业务 authority 前拒绝已存在的 checkpoint ID。仅当旧版本已经留下一个 `repair_required` reframe，且普通 `operation repair` 明确因为该 ID 被另一 operation 的 checkpoint 占用而无法前向恢复时，才使用定向替换：
+
+```bash
+mancode operation show <REFRAME_OPERATION_ULID> --json
+mancode operation repair <REFRAME_OPERATION_ULID> \
+  --replacement-checkpoint-id <FRESH_CHECKPOINT_ULID> \
+  --session <ORIGINAL_SESSION_ID> --client <CLIENT> --json
+```
+
+该命令只重绑定原 reframe 的 checkpoint、最终 metadata、aggregate 与 task-head fence 目标，然后继续原 operation；它不会删除或覆盖占用旧 ID 的 checkpoint。非 reframe、非 `repair_required`、存在 secondary reservation、资源已漂移或 replacement ID 已占用时都会拒绝。若换绑后再次中断，非终态恢复必须携带同一个 replacement ID 精确重试；终态 operation 不带替换参数时仍返回通用终态结果，携带替换参数时只接受原 replacement ID。其他中断仍使用不带该参数的 `operation repair`；不得通过删除 operation journal、recovery payload、checkpoint 或任务状态解除 adapter upgrade 门禁。
+
 ## Session 与 Context Pack
 
 session 是 checkout-local 的调用身份，不决定任务是否完成。没有真实宿主传播证据时，mutating command 必须显式传 `--session`。

package.json

@@ -37,7 +37,7 @@
     "zcode"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.5.0"
   },
   "bin": {
     "mancode": "dist/cli.js"

src/cli.ts

@@ -276,6 +276,10 @@ export function createCliProgram(): Command {
       'Policy v2: clarification only; use workflow review skip for review',
     )
     .option('--review-depth <depth>', 'Review depth: targeted or full')
+    .option(
+      '--delivery',
+      'Opt in a new man task to document-bound module delivery',
+    )
     .option('--review-domain <domain>', 'Review domain: quality or security')
     .option(
       '--report <path>',
@@ -577,6 +581,10 @@ export function createCliProgram(): Command {
   operationProgram
     .command('repair <operationId>')
     .description('Repair an operation using its original actor and session')
+    .option(
+      '--replacement-checkpoint-id <id>',
+      'Replace only a conflicted reframe checkpoint target',
+    )
     .option('--session <id>', 'Session ID (otherwise MANCODE_SESSION_ID)')
     .option('--client <name>', 'Client identity (default: mancode-cli)')
     .option('--json', 'Output as JSON (for scripts)')