plan-governance-cli 0.3.4 → 1.0.0

package/resources/skill/assets/spec.template.md

@@ -0,0 +1,32 @@
+# 规范：{{capability}}
+
+<!-- 仅在需要跨迭代维护现行行为且没有合适契约来源时使用。已有 Schema/OpenAPI 的字段定义直接引用，不复制到这里。不自动创建 spec 或空目录。 -->
+
+## 适用范围
+
+说明本规范描述的现行能力及边界；待定方案应先进入变更计划，不写成已经生效的行为。
+
+## 契约来源
+
+- 已有 Schema/OpenAPI 或其他正式来源的位置，以及本规范补充的文字行为范围。
+- 若本文件就是唯一契约源，明确承载范围；字段和行为只在各自唯一来源维护。
+
+## 现行行为
+
+描述调用方可观察的输入、输出、不变量及失败语义；可以引用可执行契约或验证，不复制实现细节。
+
+## 兼容边界
+
+记录现行兼容承诺。真实迁移的步骤、窗口和回滚有独立 migration 时只链接，不重复维护。
+
+## 用户可观察验收
+
+| 场景 | 输入/前置 | 操作 | 可观察结果 | 验证证据 |
+|---|---|---|---|---|
+| 待补充 | 待补充 | 待补充 | 待补充 | 待补充 |
+
+技术能力可观察 CLI 输出、文件差异或调用方行为；不要求界面或额外逐次用户签收。
+
+## 关联变更与决策
+
+链接相关计划、ADR 或 migration。计划状态、当前阶段和实施进度从 PLAN_MAP 与专项计划读取，不复制到本规范。

package/resources/skill/references/cli.md

@@ -0,0 +1,141 @@
+# CLI 操作
+
+只读规则入口：`plan-governance-cli guide [overview|planning|verification|cli]`。缺省 overview；`guide --help` 列用法。四主题从同一包根读取本入口及三参考，任意 cwd 可用且无需 Python。正文中的相对文档链接在 CLI 环境通过对应 guide 主题读取，不相对当前项目查找。
+
+成功退出 0；未知主题、多余参数、缺失/不可读/空资源退出 1 并报错。不下载、安装、修改项目或回退别的版本。skill 环境按实际发现的安装目录读取同源资源，避免硬编码用户路径；存在 skill 与 CLI 多版本时选择一个规范来源并核对所需能力，版本号相同不证明资源一致。
+
+已安装 skill 不等于 CLI 存在；既无 skill 也无 CLI 时说明治理前提缺失，仅阻塞依赖治理规则的工作，不自动安装。CLI 不支持新策略或 guide 时明确能力缺失，按授权更新。仅需阅读规则不调用 init/setup。
+
+## 当前工作集
+
+`plan-governance-cli workset . --json` 派生当前计划、阶段、阻塞、下一动作、并行提示和最近证据；加 `--strict-readiness` 对活跃计划的机械缺陷返回非零。它不写计划、不自动执行动作、不替代授权或业务验收，也不自动核对快照和环境漂移。恢复先读工作集与相关当前记录，必要时再展开原计划。
+
+## 分发与资源
+
+SKILL、三个 references、agents 元数据与 assets 由同一 npm 包的 manifest 分发。`plan-governance-cli setup --target codex|claude|all --dry-run` 查看同步差异；实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理用户目录残留。项目升级不迁移旧计划，受管块外内容必须保持。
+
+## 初始化、模板和检查脚本
+
+- `../assets/PLAN_MAP.template.md`：治理入口模板。
+- `../assets/plan.template.md`：计划文档模板。
+- `../assets/adr.template.md`：可选 ADR 模板。
+- `../assets/migration.template.md`：可选迁移模板。
+- `scripts/init_plan_governance.py`：初始化 Git 仓库、`docs/PLAN_MAP.md` 和首个 `docs/plans/<plan>.md`；也可升级已有项目的代理规则和检查脚本。
+- `scripts/check_plan_governance.py`：检查状态、最后更新、计划链接、依赖、阻塞项、完成证据、测试覆盖率证据，并提供可选漂移、pre-commit、停滞和 attestation 生命周期检查。
+- `scripts/plan_governance_hook.py`：只读 hook runtime，可由项目级 Agent hooks 手动调用；只输出短提示和检查结果，不修改治理文档、不更新状态、不安装 hooks。
+
+初始化一个项目：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --plan api-compat-migration \
+  --title "API 兼容性迁移" \
+  --goal "分阶段完成 API 兼容性迁移" \
+  --copy-checker \
+  --update-agent-rules
+```
+
+如果目标目录还不是 Git 仓库，初始化流程会先执行 `git init`；已有 `.git/` 时跳过。
+
+只更新已有项目的代理规则，不修改 `docs/`：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --update-agent-rules-only
+```
+
+升级已有项目的辅助文件，刷新 `scripts/check_plan_governance.py`、`CLAUDE.md` 和 `AGENTS.md`，但不覆盖 `docs/`：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --upgrade-existing
+```
+
+旧项目如果 `docs/PLAN_MAP.md` 仍是五列表，显式迁移为包含 `最后更新` 的六列表：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --migrate-plan-map-last-updated \
+  --last-updated-date 2026-07-05
+```
+
+不传 `--last-updated-date` 时使用当天日期。该迁移只修改 `docs/PLAN_MAP.md` 的计划索引表，不自动改变计划状态。
+
+在仓库根目录运行：
+
+```bash
+plan-governance-cli check .
+```
+
+可选检查：
+
+```bash
+plan-governance-cli check . --drift
+plan-governance-cli check . --pre-commit
+plan-governance-cli check . --stale-days
+plan-governance-cli check . --stale-days 10
+```
+
+- `--drift`：检查工作区变更是否被活跃计划的 `影响模块或文件` 覆盖；关闭窗口内，若已完成计划自身也在本次变更中，则额外覆盖该计划自身和 `阶段证据` 中的显式路径。
+- `--pre-commit`：检查 staged 变更是否被活跃计划的 `影响模块或文件` 覆盖，可由用户手动接入 Git hook。
+- drift 会自动覆盖活跃计划自身文件、`PLAN_MAP.md` 中可唯一归属的变更行和当前阶段 `### 阶段证据` 中声明的合法相对路径；关闭窗口内，已完成计划自身也在本次变更中时，仅额外覆盖该计划自身和显式阶段证据。跨计划、非法路径或无法归属的变更继续输出 `WARNING`。
+- `--stale-days`：检查活跃计划是否超过阈值未更新；默认 10 天。
+- 这些可选检查输出 `WARNING`，不改变退出码。
+- `--attest <plan-name>`：为已登记计划创建或覆盖 `docs/attestations/<plan-name>.json` 完成快照。
+- `--attest-purpose <purpose>`：与 `--attest` 一起创建带 `purpose`、`snapshot_id`、`supersedes` 和 `review_status` 的关系快照；支持 `phase_completion`、`release_gate`、`compliance`。不传时保持旧 JSON 路径和格式。
+- `--supersedes <path>`、`--review-status <status>`：创建关系快照时声明替代目标和初始复核状态。
+- `--check-attestations`：检查完成快照中的计划文件和 `PLAN_MAP.md` hash 是否漂移，并派生 `current`、`superseded` 或 `needs_review`；旧 JSON 缺少 `purpose` 时按 `phase_completion` 兼容读取。漂移、缺失或 JSON 损坏默认只输出 `WARNING`，严格模式才将新增结构错误提升为 `ERROR`。
+- `--attest-file <path>`：可重复，仅与 `--attest`、`--attest-purpose` 组合启用范围绑定；记录显式文件、目标及必要上游计划的实际内容和相关地图行。文件须为仓库内普通文件，不接受重复、目录、glob、越界或 symlink。无关地图更新不失效；相关内容改变/删除或绑定无效会要求复核，`--check-attestations --strict-readiness` 显式阻断。旧快照不回填、旧默认行为保持，CI/发布不自动开启此检查。
+- 范围绑定取工作树字节，HEAD 只定位；未列新文件不自动发现，hash 不证明清单完整或独立验收。相关证据先定稿，再显式创建；复核后使用带绑定的新快照与 `--supersedes` 替代。无 binding 后继不能解除 binding 前驱的范围复核责任，后继漂移也不恢复前驱 current。
+
+## 图谱与计划前置影响分析
+
+当项目声明了功能图谱或架构图谱时，使用 npm CLI 的只读命令查询影响范围：
+
+```bash
+plan-governance-cli graph validate .
+plan-governance-cli graph impact --from feature.model-lifecycle --depth 2 --format json .
+plan-governance-cli graph code candidates --symbol APIHandler --kind class --format json .
+plan-governance-cli graph code impact \
+  --repo modelpad \
+  --file Sources/ModelPadCore/API/APIServer.swift \
+  --symbol APIHandler \
+  --kind class \
+  --format json .
+```
+
+计划前置分析使用计划输入文件：
+
+```bash
+plan-governance-cli plan impact \
+  --input docs/graph/fixtures/plan-impact/model-lifecycle-api.json \
+  --format json .
+```
+
+`plan impact` 默认只查询功能层；API 契约、数据迁移、安全、外部边界或明确要求代码定位时，才升级到架构层或代码层。输出包含查询层级、升级原因、影响节点、行动分级、测试映射和未查询层级。`graph validate`、`graph impact`、代码查询和 `plan impact` 全部只读，不修改 YAML、计划、代码或 GitNexus 索引；失败也不能被解释为“无影响”。
+
+GitNexus 只在需要代码定位时使用。CLI 不自动执行 `gitnexus analyze`，也不自动写回 UID 或 YAML；候选映射由 LLM 依据文件、符号、类型和测试等证据确认，证据不足或存在多个合理候选时再请求用户确认。
+
+`影响模块或文件` 的作用域匹配规则：
+
+- `--drift`、`--pre-commit` 和 `plan_governance_hook.py --event pre-write` 使用同一语义；已完成计划的关闭窗口只适用于 drift/pre-commit，不扩大 pre-write 的活跃计划门禁。
+- 优先提取列表项中的第一个反引号路径，例如 ``- `./scripts/`: 检查脚本``。
+- 没有反引号时提取第一个纯文本 token，例如 `- README.md`。
+- 匹配前归一化前导 `./`、尾随 `/` 和重复斜杠。
+- 支持文件精确匹配和目录前缀匹配。
+- 不支持 glob、正则、否定规则或自然语言推断。
+
+只读 hook runtime 可手动接入项目级 Agent hooks：
+
+```bash
+plan-governance-cli hook --event session-start
+plan-governance-cli hook --event pre-write --paths scripts/check_plan_governance.py
+plan-governance-cli hook --event post-write --paths docs/PLAN_MAP.md
+plan-governance-cli hook --event stop
+```
+
+该脚本不自动安装 `.codex/hooks.json` 或修改全局配置。`stop` 事件只做非阻塞提示，不实现强制 gate。

package/resources/skill/references/planning.md

@@ -0,0 +1,128 @@
+# 计划与契约
+
+从 [skill 入口](../SKILL.md) 判断任务是否需要治理；仅 CLI 环境用 `plan-governance-cli guide overview`。本页只维护文档、探索与同步规则；阶段证据和复核见 [verification](verification.md)。
+
+## 需求探索与 grilling
+
+对可能进入治理的任务，如果运行环境声明 `grill-me` 可用，满足下列任一条件时自动调用它，在实施或冻结详细方案前先澄清需求：
+
+1. 涉及公共 API、Schema、迁移、兼容性或不可逆操作，且目标、边界、验收或关键取舍中至少一项未明确；
+2. 下列不确定性信号中至少两项同时存在：目标/验收不清、范围/非目标不清、存在多个有实质取舍的方案、关键事实尚待查证、后续返工成本显著。
+
+目标、影响范围和验收方式均明确的小范围任务，以及当前阶段已通过准入且已确认假设没有变化的工作，跳过自动 grilling；用户仍可显式调用它。已确认的范围、验收与授权直接复用，不为相同结论重新 grilling。仅影响可选细节的问题可在合理等待后声明假设继续；必需答案和授权不可由沉默推定。
+
+grilling 每次只问一个问题。可从仓库、环境或工具确认的事实必须先查证；产品取舍、外部承诺和不可逆选择由用户确认。结束前必须汇总并得到用户确认：目标、范围和非目标、已确认事实、暂定假设及验证方式、候选方案与取舍、未决问题及阻塞级别，以及验收口径或下一步动作。
+
+用户确认后，只有在任务需要治理时，才把结构化结论写入专项计划的 `需求探索` 章节；不保存完整访谈逐字稿，不自动创建 ADR。探索结论不替代当前阶段的 Step 0、样本矩阵、验证方式、失败/回滚边界或适用阶段准入复核。`grill-me` 不可用时，说明依赖不可用并保持在澄清/设计边界，不得伪造已完成 grilling 或静默实施。
+
+收敛时固定少量可观察场景：输入/前置、操作、可见结果；已有场景直接链接。涉及运行资源影响时明确环境、负载、采样窗口和相关 CPU/内存/磁盘等指标，不发明通用阈值。交互或方案明显不确定时安排关键流程原型/早期体验；目标明确的小修改不增加中途签收。反馈未到可继续不依赖它的已授权工作。
+
+## 仓库模型
+
+使用项目内这些文件作为事实来源：
+
+```text
+docs/
+  PLAN_MAP.md
+  plans/
+    <plan-name>.md
+  specs/
+    <capability>.md        # 按需，优先复用已有 Schema/OpenAPI
+  adr/
+    0001-<decision>.md
+  migrations/
+    <migration-name>.md
+```
+
+只创建有真实内容的文件，不预建空目录或强制 PRD/design/tasks 组合。`docs/plans/*.md` 保持平铺。`docs/reviews/` 存独立复核，`docs/fixtures/` 存人工样本/回放说明，`tests/fixtures/` 存可执行输入，`docs/attestations/` 仅在使用快照时需要。
+
+文档权责：
+
+- `PLAN_MAP.md`：计划索引、状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、当前阻塞项、证据链接。
+- `docs/plans/*.md`：本次变更的目标、范围、行为差异、阶段、Step 0、验证与完成条件；链接现行契约。没有独立契约来源时明确由计划哪个位置承载，不要求追溯提取旧内容。
+- `docs/adr/*.md`：持久架构决策及其后果。
+- `docs/migrations/*.md`：兼容策略、迁移步骤、回滚方式、旧行为保留窗口。
+- 现行契约优先复用已有 Schema/OpenAPI。需要跨迭代维护文字行为且无合适来源时，才按需建立 `docs/specs/<capability>.md`；可使用 [spec 模板](../assets/spec.template.md)，补充输入/输出、不变量、失败语义与可观察场景，不复制已有字段定义或计划进度。
+
+同一事实只定义一次，其他地方通过链接引用。独立 migration 承载迁移步骤、窗口和回滚后，计划改为引用；ADR 保留选择理由和后果，不复制契约字段或进度。
+
+## 多文档同步规则
+
+- 专项计划按上述文档权责记录本次差异和证据，现行字段与行为从唯一契约来源读取。
+- `PLAN_MAP.md` 是状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
+- 总路线图、优先级计划和索引只记录顺序、状态摘要和专项计划链接，不复制字段级方案、枚举、Step 0 细节或完成定义。
+- 当专项计划的状态、当前阶段、最后更新、字段方案、完成条件或验证结果变化时，必须同步 `PLAN_MAP.md` 和所有引用该计划的路线图、优先级计划或索引。
+- 验收治理文档时，必须用 `rg` 搜索同名计划、P 编号、状态名和关键字段，检查是否存在重复定义或漂移。
+- 如果同一事实在多个文档中重复，保留一个事实源，其他文档改为链接引用。
+- 实施者填写的计划状态、完成证据文字和文档格式只代表实施声明，不等于验收结论；按适用复核方式基于当前仓库内容、可复现验证命令和反向引用确认。
+
+## 草案和历史文档处理
+
+启用计划治理后，已有草案、历史设计、归档计划、superpowers 记录、临时分析文档等默认只作为背景材料，不再作为规范事实源。
+
+- 除非用户明确点名要求更新这些文档，否则不要继续修改它们来承载新规范。
+- 新发生的目标、范围、非目标、公共契约、字段、Schema、状态语义、阶段、验证方式、完成条件、风险和回滚，应写入 `docs/plans/*.md`、ADR、migration 或正式 spec。
+- 计划状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接，应写入或同步 `docs/PLAN_MAP.md`。
+- 历史草案可以在治理文档中作为背景材料链接引用，但不应承载新的规范事实。
+- 如果治理文档出现“以草案为事实源”“详见草案中的字段定义”“草案为准”等表述，应改为由治理文档自身承载事实源，或链接到正式 spec/Schema。
+- 当用户说“补充一下”“记录一下”“把刚才的结论写进去”时，如果治理已启用，默认写入治理文档；不要写入草案、README 或历史设计文档，除非用户明确点名该文件。
+
+## 推荐状态
+
+统一使用中文状态：
+
+| 状态 | 含义 |
+|---|---|
+| `候选` | 记录了想法，但尚未承诺实施 |
+| `设计中` | 正在明确范围、契约和门禁 |
+| `待实施` | 当前阶段门禁已通过，但尚未开始 |
+| `实施中` | 当前阶段推进中；适用时包含技术完成待用户验收 |
+| `已完成` | 实现、验证、证据和文档齐全，并满足适用的用户验收 |
+| `已替代` | 被另一个计划取代 |
+| `已合并` | 并入另一个计划 |
+| `已废弃` | 明确不再推进 |
+
+
+## 漂移检查
+
+当决策、实现发现或运行报告改变以下内容时，暂停实施并更新治理文档：
+
+- 既有 ADR 或核心原则
+- 计划顺序、依赖、替代关系或有效性
+- 公共 API、Schema、状态语义、兼容承诺或失败模式
+- 多个计划共享的重复修改点
+- 用来证明完成的测试或完成条件
+- 专项计划与路线图、优先级计划或索引之间的状态、字段方案、完成条件或验证结果
+
+## 停滞检查
+
+`PLAN_MAP.md` 的计划索引应包含 `最后更新` 列，日期格式为 `YYYY-MM-DD`。
+
+计划索引必须在同一个 `## 计划索引` 章节下，按固定顺序拆成三张六列表格：`### 未完成`、`### 已完成`、`### 已废弃`。状态归类规则如下：
+
+- `未完成`：`候选`、`设计中`、`待实施`、`实施中`。
+- `已完成`：`已完成`。
+- `已废弃`：`已废弃`、`已替代`、`已合并`等不再推进的终态；表格标题不改变行内真实状态。
+
+每个计划只能出现一次；没有对应计划的分类保留表头但不添加占位行。必须使用三级标题，以便治理 CLI 将三张表作为同一个计划索引读取。
+
+推荐表头：
+
+```markdown
+| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
+```
+
+规则：
+
+- `最后更新` 是显式治理元数据，不从 Git 历史或文件 mtime 推断。
+- 当计划状态、当前阶段、阻塞项、依赖、完成条件、验证结果或实施范围变化时，同步 `最后更新`。
+- `--stale-days` 只对 `候选`、`设计中`、`待实施`、`实施中` 等活跃计划输出 `WARNING`，不自动改变状态。
+- `--stale-days` 省略数值时默认 10 天，可显式传入 N。
+
+## 执行与恢复
+
+首次接手读取 PLAN_MAP、当前计划和确实相关的 ADR/migration/spec。恢复时先用已有当前工作集、当前阶段、最近实施/验证记录和实际 diff 定位进度；只有缺失、冲突或相关范围变化时再展开旧资料。历史会话和全部计划不是每轮必读材料。规则与当前证据入口应可访问；只有不可检索的输出 ID 时先补真实内容或可复验入口。
+
+先确认当前阶段准入和授权，再实施。假设、公共契约、兼容、范围、完成条件或依赖变化时，先更新唯一事实源和地图，再评估准入；阶段内原范围反馈追加差异和验证，不自动新开计划或重开所有门。原验收预期从原场景读取，不因新边界输入自行发明业务规则。
+
+治理文档变更后做适用链接、结构、反向引用和 `plan-governance-cli check .`；用 `rg` 搜索同名计划、P 编号、状态/关键字段，以及 `草案为准|以草案为事实源|详见草案|draft is source|source of truth.*draft|以.*draft.*为准`。纯落档不重跑已有效覆盖的全部代码测试；规范行为变化仍需验证受影响场景。

package/resources/skill/references/verification.md

@@ -0,0 +1,83 @@
+# 验证、复核与用户验收
+
+本页是风险分流、阶段门和证据闭环的规范来源。[入口](../SKILL.md)先判断是否需要治理；仅 CLI 环境用 `plan-governance-cli guide verification`。
+
+## 按风险复核
+
+| 情况 | 执行方式 |
+|---|---|
+| 目标、范围和实际后果明确，可撤销，适用验证充分的低风险改动 | 当前 AI 检查差异、验证实际行为，失败后自主修复/复验；简报证据，不为每次改动派独立 subagent 或新建报告 |
+| 安全/权限/隐私/公开暴露、数据完整性/迁移、核心公共契约/生命周期、广泛共享逻辑或难以撤销后果 | 保留独立复核，在关键设计或完成边界安排必要检查；一行代码或配置也可能高影响 |
+| 风险暂不明确、反复修复无效或证据冲突 | 先补事实及定向验证；实质疑点仍在则定向独立检查，不凭自信降为低风险 |
+
+是否进入计划、发生阶段转换或计划收尾，本身不决定独立复核。已有计划或用户明确要求独立复核时仍须遵循；新风险策略不能替旧计划的既有门禁自动降级。可逆性评估实际外部后果，不能只看代码能否回滚。执行中影响扩大时立即重新评估。
+
+需要独立复核且范围/授权已明确时，自动启动未参与实施或测试编写的只读 subagent 或等价复核者，不等待用户逐项安排。输入只给计划/阶段、受审 revision 与实际范围、必要证据、验证命令、完成条件、安全边界；使用新上下文，不倾倒全量聊天。
+
+独立失败、入口不可用、超时或证据冲突保持阻塞，不由实施者自批，不靠改分类/换一条安全操作放行。授权范围内可补证据和修复，未解除前不越门；等价替代者仍须满足相同独立性与证据要求。独立复核不能代替外部授权；已有授权有效时不重复索取，新的公开暴露/凭证/破坏性/隐私/合规或产品取舍按实际边界确认。
+
+## Step 0 与阶段门
+
+阶段 N 完成只关闭 N，N+1 默认设计中。每个当前阶段自身必须有目标/范围/非目标、可观察 Step 0、输入与可执行命令/预期/失败判定/输出位置的样本矩阵、验证与完成条件、失败/回滚边界、无未解决阻塞，以及适用复核通过，才可待实施。机器检查只核对结构，不证明实现、风险分类、证据真实性或用户接受。
+
+| 任务 | Step 0 |
+|---|---|
+| 缺陷修复 | 失败回归或最小复现 |
+| 迁移 | 现状快照、兼容样本或契约测试 |
+| 新项目 | 可执行验收 fixture、协议样本或提交图 |
+| 架构探索 | 最小原型、风险实验或关键假设验证 |
+
+不适合固定样本时记录原因和可观察的替代基线。不要在开始实现后倒填通过证据。
+
+### 旧计划兼容
+
+摘要没有 `复核策略` 字段时，保留原独立门禁：固定 `阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录` 标题；摘要字段是 `准入状态、Step 0、样本矩阵、验证方式、失败/回滚边界、当前阻塞项、最新独立准入复核`。最新表含日期、阶段、结论、证据、复核者，当前阶段最新结论须明确通过并达到待实施标准，历史追加记录保持一致。标题不带阶段编号；地图提供阶段身份。
+
+不自动改旧计划。采用下面的新策略时显式更新当前阶段结构，保留旧独立历史；必须先解除旧有效独立失败及历史冲突，再进入新策略。旧 CLI 可能拒绝新计划的严格准入，应显式更新选用的 CLI，不能把旧检查结果当新能力。
+
+### 新计划风险策略
+
+新模板在当前阶段摘要声明 `复核策略：风险分流`。这个字段缺省是上面的旧策略，空值/未知/重复不能当低风险；启用后摘要以 `最新阶段复核` 链接替代旧最新独立字段，其余基础字段保持。
+
+`最新阶段复核` 固定键值表：
+
+| 字段 | 要求 |
+|---|---|
+| 日期 / 阶段 | YYYY-MM-DD / 与地图当前阶段一致 |
+| 方式 | 自验或独立 |
+| 风险 | 低风险、高影响或待判断；待判断不能通过，自验仅限低风险 |
+| 风险依据 | 实际范围、后果/可逆性、验证充分性的具体依据；非占位 |
+| 结论 | 尚未进行或实际结果；有效通过必须明确通过，不能以空值、失败、不可用、超时、证据冲突代替 |
+| 证据 / 复核者 | 可复验命令/结果或其可访问链接，以及真实执行者身份；自验不假称独立 |
+
+以 `通过 / 未通过` 等尚未选择结果的模板候选开头时，其后无论是问号、其他标点或待选说明，都属于未知，不能成为独立失败的恢复证据。结论以明确前缀声明当前结果，支持 `通过。` 等常见句末符号；`通过：已修复证据冲突` 可以通过，不因提到历史问题重判失败。无明确通过的不可用/超时/证据冲突仍为失败。实际未解决事项必须留在结构化阻塞中，通过说明不能覆盖它；机器不验证自由说明的真实性。
+
+`阶段复核记录` 使用 `日期、类型、阶段、方式、风险、结论、证据、复核者` 八列表追加记录。最新当前阶段记录与最新表的日期、方式、风险、结论、证据和身份一致。最近有效独立失败不得由后续自验遮蔽；修复后由适格独立者追加通过并更新最新结论。上一阶段历史不自动阻断当前阶段。
+
+普通无计划小改不建立这些表。可将验证命令和结果放进现有记录，通过证据列链接，避免第二份事实源。未完成的设计模板不是准入证明；不生成已通过占位。
+
+默认 check 对新准入缺陷 WARNING；待实施/实施中在 `--strict-readiness` 下 ERROR。workset 沿用 JSON schema 1 和既有动作：待自验 `verify`、高影响待独立 `independent_review`、有效通过但地图仍设计中 `sync`；失败 `blocked/resolve_blocker`，结构歧义 `unknown/unknown`，不自动写状态。hook 只提示。
+
+## 验证、修复与证据复用
+
+先验证用户可观察结果和受影响回归；验证范围依据变更及项目要求，不为字数、字段或与实现重复的断言新增无价值测试。纯文档做适用检查并注明代码覆盖率不适用；代码变更遵循项目要求和有意义的覆盖证据。
+
+可信全量证据只有覆盖当前实际工作树、依赖、配置、环境和验证契约，且内容可访问时才可复用。HEAD/版本相同不充分；缺失、相关变化或冲突时补验。复核者核对身份并复验关键风险，不因复用报告省略独立判断。明确过时的证据记录为当前阻塞。
+
+范围快照是可选补充；`workset` 不自动核对文件 hash 或环境变化。采用 attestation 时按 [CLI 说明](cli.md) 显式运行 `check --check-attestations --strict-readiness`，不能声称所有准入都已检查证据漂移。
+
+自验失败由实施 AI 自主修复、复验。独立失败后的重审聚焦原阻塞、修复差异及受影响回归，引用仍有效的证据；不因一处修复无理由重跑整套历史，也不把共享调用变化当成无影响。相同未修正阻塞不重复送审。
+
+每个必要复核点默认一名主复核者，仅对具体且独立的专项风险增加协作者。适用时合并同范围行为后测与完成复核：检查者未参与实现/测试编写，先给任务输入，完成后再给预期对照；行为判断和机械测试分别记录。受审范围冻结后，等待期间可做无依赖的已授权工作；相关变化需通知复核者，不以未完成结果推进依赖项。使用有界等待，避免密集轮询；并行工时不能相加冒充关键路径时长。
+
+验证后仅追加状态/证据或修正文档链接时，做适用文档检查即可；契约、源、依赖或环境又变则补受影响验证。区分仓库源与安装版本、旧缺陷与新回归、当前范围与其他并行任务失败；如实报告全仓失败，不能用局部通过掩盖，也不擅自接管无关任务。
+
+## 用户可观察验收与交付
+
+验收关联到场景、输入/前置、操作、可观察结果和证据；CLI 输出/文件差异/调用方行为同样可观察，不强求界面或资源采样。需要性能验收时沿用探索确定的可比环境、负载和窗口；未实际测量不得宣称性能改善。
+
+采用用户最终体验闭环的功能计划：AI 先技术和运行验证，提供可复验结果；技术完成但待用户查看/操作时保持 `实施中`，最近记录注明待验收项，结构化 `下一动作：等待用户验收`。workset 返回已有 `none` 并明确等待原因，不关闭计划。用户明确接受后才已完成；技术通过、提交请求或沉默都不是产品接受。普通小改、纯落档不增加逐次签收。
+
+原验收未满足或原范围小问题自主修复/复验并交付结果；新需求或实质取舍另行归属，需用户才能提供的验收结果保持待答，可继续不依赖它的授权工作。
+
+交接简报结果、阻塞、验证命令及范围/环境、可访问证据入口和下一动作即可；不粘贴完整日志，不为每次动作新建报告。仅工具 ID 无法被接手者访问时，提供实际要点和复验命令。对减负效果用少量同完成条件任务比较必要读取、全量验证/复核次数和实耗；保留质量反例。没有可靠宿主统计不估算 token 占比，文件字节/行数或工具次数不代替 token 和耗时。