plan-governance-cli 0.3.5 → 1.0.1

package/README.md

@@ -42,6 +42,8 @@ docs/
 
 ```text
 docs/
+  specs/
+    <capability>.md        # 无合适现行契约来源时按需建立
   adr/
     0001-<decision>.md
   migrations/
@@ -53,13 +55,26 @@ docs/
 | 文档 | 权威内容 |
 |---|---|
 | `docs/PLAN_MAP.md` | 计划索引、状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项、证据链接 |
-| `docs/plans/*.md` | 单个计划的目标、阶段、当前步骤、字段方案、Schema、枚举、Step 0 证据、验证方式、完成条件 |
+| `docs/plans/*.md` | 本次目标、范围、行为差异、阶段、Step 0、验证与完成条件；链接现行契约 |
+| 已有 Schema/OpenAPI 或按需的 `docs/specs/*.md` | 跨迭代的现行契约；优先复用已有来源，文字 spec 补充行为/失败语义，不重复字段定义 |
 | `docs/adr/*.md` | 关键架构决策、备选方案和后果 |
 | `docs/migrations/*.md` | 兼容策略、迁移步骤、回滚方式和旧行为保留窗口 |
 
+`docs/plans/*.md` 保持平铺。目录按真实内容增加：`docs/reviews/` 放独立复核，`docs/fixtures/` 放人工样本/回放说明，`tests/fixtures/` 放可执行输入，`docs/attestations/` 放按需快照。init 只创建最小结构；可选 [spec 模板](resources/skill/assets/spec.template.md) 随 skill 分发，不自动创建目标项目 spec 或空目录。
+
+## 任务分流与验收
+
+| 任务 | 最少必要文档与动作 |
+|---|---|
+| 无既有计划覆盖的小修改 | 不新增治理文档，验证实际变化 |
+| 准入仍有效且范围、契约、完成条件、授权未变的阶段内反馈 | 复用原计划和场景，追加差异/结果，按实际元数据同步地图 |
+| 公共契约、迁移或实质范围变化 | 先核对与澄清，再更新相应计划并重新评估准入；契约来源保持唯一 |
+
+验收写清场景、输入/前置、操作、可观察结果和验证证据，已有场景直接链接。CLI 输出、文件差异和调用方行为同样可作观察；不额外要求每次用户签收。原验收未满足、原范围改进和新需求分别记录在现有实施/验证区；分流不覆盖失败复核或高影响授权边界，测试/治理通过不能代替场景结果。
+
 ## 多文档同步
 
-- 专项计划是实施细节事实源，记录字段方案、Schema、枚举、Step 0 证据、验证方式和完成条件。
+- 按上述文档权责记录本次差异与证据；没有独立契约源时明确由计划哪个位置承载，不要求迁移旧文档。独立 migration 承载步骤/窗口/回滚后，计划改为引用。
 - `docs/PLAN_MAP.md` 是状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
 - 总路线图、优先级计划和索引只记录顺序、状态摘要和专项计划链接，不复制字段级方案、枚举、Step 0 细节或完成定义。
 - 当专项计划的状态、字段方案、完成条件或验证结果变化时，必须同步 `docs/PLAN_MAP.md` 和所有引用该计划的路线图、优先级计划或索引。
@@ -190,14 +205,35 @@ plan-governance-cli graph code impact --repo modelpad --file Sources/ModelPadCor
 
 ## 持续推进
 
-在 Codex 中需要跨轮持续推进时使用 `goal`。阶段内独立复核只绑定阶段准入、阶段转换或明确的高影响边界，不为每个微小动作单独复核。
+在已授权的跨轮任务中可使用 `goal`；skill 本身不定义整计划自主执行运行时。低风险改动由当前 AI 自验，高影响或有效独立失败保留必要独立复核；已有计划缺省独立门禁兼容保留。
+
+[验证规范](resources/skill/references/verification.md)统一维护风险分流、证据复用、失败重审与用户验收；其他会话从同一 skill 读取。需要独立复核且授权明确时自动安排只读 subagent，不为普通小改逐次派发；技术完成待用户验收的适用功能计划仍保持实施中。
 
-对目标、范围和授权边界清楚、且不涉及高影响外部动作的普通阶段门，执行者应自动启动独立只读 subagent 或等价独立复核者；复核通过后记录证据并继续当前阶段，不等待用户逐项确认。复核失败、入口不可用、超时或证据冲突时保留阻塞并报告，不能自行放行；涉及外部授权、凭证、公开暴露、破坏性或不可逆操作、安全、隐私、合规或产品取舍时，仍须请求用户确认。`plan-governance` skill 和 CLI 负责计划、证据、阶段准入与检查，不提供整计划自主执行模式、执行清单或步骤级下一步查询。
+1.0.1 起支持可选的最近记录窗口：
+
+```bash
+plan-governance-cli workset . --json --evidence-limit 3
+```
+
+每个计划保留末尾三条记录，并给出省略数量和原文位置；默认完整输出和门禁判断保持。窗口用于恢复阅读，必要时去掉参数回查完整记录，详见 [CLI 参考](resources/skill/references/cli.md#当前工作集)。已发布的 1.0.0 尚不支持此参数。
+
+## 按需读取规则
+
+```bash
+plan-governance-cli guide                 # 入口
+plan-governance-cli guide planning        # 计划/契约/探索
+plan-governance-cli guide verification    # 阶段门/复核/验证/用户验收
+plan-governance-cli guide cli             # CLI 操作
+```
+
+读取当前包内正文，与 cwd 无关，不需要 Python，不下载或修改项目。未知主题、多余参数、缺失或空资源非零退出。项目受管入口依赖已安装 skill 或具备上述能力的 CLI；两者均不可用时明确说明前提，不自动安装。
+
+SKILL 保留任务分流和执行底线，三份 references 按需读取并随 manifest/setup/npm 分发。已有项目只刷新受管入口，不迁移旧计划、不改用户块外内容。选择同一版本的规范来源，安装副本与仓库同版本号也可能有不同内容。
 
 也可以不全局安装，直接使用锁定版本：
 
 ```bash
-npx --yes --package plan-governance-cli@0.3.4 plan-governance-cli check . --strict-readiness
+npx --yes --package plan-governance-cli@1.0.1 plan-governance-cli check . --strict-readiness
 ```
 
 npm 包内部仍使用版本化的 Python 检查器，但用户不需要直接调用或复制该脚本。旧项目已有本地脚本时仍可保留作为兼容或回滚路径。
@@ -286,6 +322,18 @@ plan-governance-cli check . --check-attestations
 
 `--attest <plan-name>` 只接受已登记到 `docs/PLAN_MAP.md` 的计划。`--attest-purpose <purpose>` 可与它一起创建带 `purpose`、`snapshot_id`、`supersedes` 和 `review_status` 的关系快照，支持 `phase_completion`、`release_gate`、`compliance`；不传时保持旧 `docs/attestations/<plan-name>.json` 格式。`--supersedes <path>` 和 `--review-status <status>` 可声明替代目标和初始复核状态。`--check-attestations` 会检查 hash 漂移并派生 `current`、`superseded` 或 `needs_review`；旧 JSON 缺少 `purpose` 时按 `phase_completion` 兼容读取。漂移、缺失或 JSON 损坏默认输出 `WARNING`，严格模式才将新增结构错误提升为 `ERROR`。人工确认文档修正合理后，可以重新创建旧快照或用 `--attest-purpose` 创建带替代关系的新快照。
 
+需要把证据绑定到实际文件时，重复传入 `--attest-file`，并同时指定计划和 purpose：
+
+```bash
+plan-governance-cli check . --attest api-change --attest-purpose release_gate \
+  --attest-file src/api.py --attest-file tests/test_api.py
+plan-governance-cli check . --check-attestations --strict-readiness
+```
+
+这是可选模式：快照绑定显式文件、目标与必要上游计划的实际内容，以及相关地图行。无关计划日期、地图注释或 HEAD 变化不触发复核；相关内容变化、删除或绑定无效会显示 `needs_review`，默认警告，显式严格检查失败。旧快照继续按原有全文 hash 规则检查，不自动回填；CI/发布不会自动开启证据检查。
+
+文件须为仓库内普通文件，拒绝重复、目录、glob、越界或 symlink。它记录工作树字节，HEAD 只作定位；未列出的新文件不会自动被发现，hash 不代表独立验收。完成新的复核后，用带绑定的新快照和 `--supersedes <旧快照相对路径>` 替代；旧格式后继不能解除绑定快照的复核责任。具体投影、兼容和失败边界见[范围绑定契约](docs/plans/iterative-governance-reliability.md#阶段-4-行为契约)。
+
 ## 测试覆盖率
 
 本项目使用 `pytest` 和 `pytest-cov` 作为测试与覆盖率门禁。首次运行前安装开发依赖：
@@ -324,13 +372,11 @@ python3 -m pytest
 
 ### 阶段准入
 
-计划级 `状态` 和 `当前阶段` 由 `docs/PLAN_MAP.md` 维护；专项计划维护当前阶段的准入摘要和独立复核证据。阶段 N 完成后，阶段 N+1 默认保持 `设计中`，不能直接标记为 `待实施`。
-
-进入 `待实施` 前，当前阶段必须有明确目标/范围、Step 0 基线、样本或替代基线矩阵、可执行验证方式、失败与回滚边界、无未解决阻塞项，以及最新独立准入复核“通过”。复核记录追加保留，`PLAN_MAP.md` 只链接最新有效结论。
+状态与当前阶段由 `docs/PLAN_MAP.md` 维护。每阶段必须具备自身 Step 0、验证/完成和失败边界、无有效阻塞及适用复核，不能凭上一阶段完成自动待实施。
 
-机器识别的结构化章节标题固定为 `阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录`，不要在这些标题中插入或添加 `阶段 1` 等编号；阶段编号由 `PLAN_MAP.md` 的当前阶段提供。严格检查发现常见编号变体时，会在输出中给出直接修正提示。
+旧计划缺省沿用独立准入；新模板显式采用风险分流，低风险自验与高影响独立分别如实记录，旧独立失败不能被自验遮蔽。固定字段、历史保护和严格检查语义以[阶段门规范](resources/skill/references/verification.md#step-0-与阶段门)为准。
 
-阶段准入严格检查命令为 `--strict-readiness`。默认检查先以 `WARNING` 提示历史文档中的机械缺陷；严格模式才返回非零退出码。该检查只判断结构化准入条件，不替代业务验收。
+使用 `check --strict-readiness` 做准入/CI/发布机械检查；默认检查兼容告警，机械通过不代替真实风险判断、业务验收或用户接受。
 
 ## Codex 使用方式
 
@@ -356,8 +402,8 @@ skill 只负责让 Codex 按流程工作；真实计划状态仍然保存在项
 - 决策、计划、契约和证据各有权威位置，不重复定义同一事实。
 - 路线图和优先级计划只保留排序、状态摘要和链接，不复制专项计划细节。
 - 验收治理文档时必须做反向引用检查。
-- 验收者不得仅依据计划状态、完成证据文字或文档格式判定完成；必须基于当前仓库内容、可复现验证命令和反向引用检查独立确认。
+- 按适用风险复核规范核对当前内容、可复验结果和反向引用；状态文字不是验收证据。
 - 启用治理后，旧草案停止承载新规范；后续需求默认进入治理文档。
 - 如果新信息改变计划顺序、公共契约、兼容承诺或完成条件，先更新治理文档，再继续实施。
 
-完整设计见 [plan-governance-design.md](plan-governance-design.md)。
+现行规则从 [skill 入口](resources/skill/SKILL.md)按需读取；[原始设计](plan-governance-design.md)仅作历史背景。

package/bin/plan-governance-cli.mjs

@@ -181,9 +181,36 @@ function setup(args) {
   return 0;
 }
 
+function guide(args) {
+  const topics = new Map([
+    ["overview", "SKILL.md"],
+    ["planning", "references/planning.md"],
+    ["verification", "references/verification.md"],
+    ["cli", "references/cli.md"],
+  ]);
+  if (args.length === 1 && args[0] === "--help") {
+    console.log("用法：plan-governance-cli guide [overview|planning|verification|cli]\n缺省 overview；只读当前包内规则，不依赖 cwd 或 Python。");
+    return 0;
+  }
+  const topic = args[0] ?? "overview";
+  if (args.length > 1 || !topics.has(topic)) {
+    return fail("guide 仅接受一个主题：overview、planning、verification、cli；用 guide --help 查看用法。");
+  }
+  const path = resolve(packageRoot, "resources", "skill", topics.get(topic));
+  try {
+    const content = readFileSync(path, "utf8");
+    if (!content.trim()) return fail(`规则资源为空：${path}`);
+    process.stdout.write(content);
+    return 0;
+  } catch (error) {
+    return fail(`无法读取规则资源 ${path}：${error.message}`);
+  }
+}
+
 function main() {
   const args = process.argv.slice(2);
   const command = args[0];
+  if (command === "guide") return guide(args.slice(1));
   if (command === "setup") return setup(args.slice(1));
   if (command === "workset") return runPython(checker, ["--workset", ...args.slice(1)]);
   if (command === "init") return runPython(initializer, args.slice(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "0.3.5",
+  "version": "1.0.1",
   "description": "统一入口的计划治理检查 CLI",
   "private": false,
   "type": "module",
@@ -23,7 +23,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test tests/npm_cli.test.mjs tests/graph_cli.test.mjs tests/architecture_graph_cli.test.mjs tests/plan_impact_step0.test.mjs tests/plan_impact_cli.test.mjs",
+    "test": "node --test tests/npm_cli.test.mjs tests/graph_cli.test.mjs tests/architecture_graph_cli.test.mjs tests/plan_impact_step0.test.mjs tests/plan_impact_cli.test.mjs tests/verification_release.test.mjs",
+    "verify": "node scripts/verify.mjs",
     "release:npm": "node scripts/release_npm.mjs"
   },
   "dependencies": {

package/resources/manifest.json

@@ -11,7 +11,11 @@
       "resources/skill/assets/PLAN_MAP.template.md",
       "resources/skill/assets/adr.template.md",
       "resources/skill/assets/migration.template.md",
-      "resources/skill/assets/plan.template.md"
+      "resources/skill/assets/plan.template.md",
+      "resources/skill/assets/spec.template.md",
+      "resources/skill/references/planning.md",
+      "resources/skill/references/verification.md",
+      "resources/skill/references/cli.md"
     ]
   },
   "runtime": [

package/resources/skill/SKILL.md

@@ -5,328 +5,39 @@ description: 轻量计划治理工作流。Use when 用户要求管理路线图
 
 # Plan Governance
 
-使用这个 skill 管理跨阶段、会漂移、需要证据闭环的工作。普通一次性 bugfix、小范围本地修改、互不依赖的待办列表，不要启用治理，除非用户明确要求。
+用计划、证据和适用验证管理跨阶段、会漂移的工作。普通一次性 bugfix、小范围本地修改和互不依赖的待办，不启用完整治理，除非已有计划覆盖或用户明确要求。
 
-跨轮持续推进由 Codex 的 `goal` 机制管理；阶段内独立准入复核按“阶段内独立复核调度”契约处理。本 skill 不定义整计划自主执行模式、执行清单或步骤级下一步骤查询。
-
-## 启用判定
-
-开始前先给任务打分：
+## 先分流
 
 | 信号 | 分数 |
 |---|---:|
 | 跨阶段、里程碑或多轮会话 | 1 |
-| 涉及架构、公共 API、Schema、兼容性或迁移行为 | 1 |
+| 架构、公共 API、Schema、兼容性或迁移 | 1 |
 | 依赖真实运行报告、样本或反馈 | 1 |
-| 多个计划之间存在依赖、替代、重叠或冲突 | 1 |
-| 同一模块会被后续计划反复修改 | 1 |
-
-- `>=3`：初始化或更新持续计划治理。
-- `=2`：先检查已有治理文档，但不主动新建结构，除非确有必要。
-- `<=1`：按普通任务处理。
-- 大型公共契约迁移可以直接启用治理。
-
-## 需求探索与 grilling
-
-对可能进入治理的任务，如果运行环境声明 `grill-me` 可用，满足下列任一条件时自动调用它，在实施或冻结详细方案前先澄清需求：
-
-1. 涉及公共 API、Schema、迁移、兼容性或不可逆操作，且目标、边界、验收或关键取舍中至少一项未明确；
-2. 下列不确定性信号中至少两项同时存在：目标/验收不清、范围/非目标不清、存在多个有实质取舍的方案、关键事实尚待查证、后续返工成本显著。
-
-目标、影响范围和验收方式均明确的小范围任务，以及当前阶段已通过准入且已确认假设没有变化的工作，跳过自动 grilling；用户仍可显式调用它。
-
-grilling 每次只问一个问题。可从仓库、环境或工具确认的事实必须先查证；产品取舍、外部承诺和不可逆选择由用户确认。结束前必须汇总并得到用户确认：目标、范围和非目标、已确认事实、暂定假设及验证方式、候选方案与取舍、未决问题及阻塞级别，以及验收口径或下一步动作。
-
-用户确认后，只有在任务需要治理时，才把结构化结论写入专项计划的 `需求探索` 章节；不保存完整访谈逐字稿，不自动创建 ADR。探索结论不替代当前阶段的 Step 0、样本矩阵、验证方式、失败/回滚边界或独立准入复核。`grill-me` 不可用时，说明依赖不可用并保持在澄清/设计边界，不得伪造已完成 grilling 或静默实施。
-
-## 仓库模型
-
-使用项目内这些文件作为事实来源：
-
-```text
-docs/
-  PLAN_MAP.md
-  plans/
-    <plan-name>.md
-  adr/
-    0001-<decision>.md
-  migrations/
-    <migration-name>.md
-```
-
-只创建有真实内容的文件。不要预建空的 `adr/` 或 `migrations/` 目录。
-
-文档权责：
-
-- `PLAN_MAP.md`：计划索引、状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、当前阻塞项、证据链接。
-- `docs/plans/*.md`：单个计划的目标、范围、阶段、当前阶段步骤、Step 0 证据、验证方式、完成条件、风险、回滚、未决问题。
-- `docs/adr/*.md`：持久架构决策及其后果。
-- `docs/migrations/*.md`：兼容策略、迁移步骤、回滚方式、旧行为保留窗口。
-- spec 或 Schema：精确、可机器校验的契约。
-
-同一事实只定义一次，其他地方通过链接引用。
-
-## 多文档同步规则
-
-- `docs/plans/*.md` 是专项计划的实施细节事实源，记录字段方案、Schema、枚举、Step 0 证据、验证方式和完成条件。
-- `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 或历史设计文档，除非用户明确点名该文件。
-
-## 推荐状态
-
-统一使用中文状态：
-
-| 状态 | 含义 |
-|---|---|
-| `候选` | 记录了想法，但尚未承诺实施 |
-| `设计中` | 正在明确范围、契约和门禁 |
-| `待实施` | 当前阶段门禁已通过，但尚未开始 |
-| `实施中` | 当前阶段正在修改代码或文档 |
-| `已完成` | 实现、测试、证据和文档已同步 |
-| `已替代` | 被另一个计划取代 |
-| `已合并` | 并入另一个计划 |
-| `已废弃` | 明确不再推进 |
-
-### 阶段转换规则
-
-- 阶段 N 完成只关闭阶段 N，不自动改变阶段 N+1 的准入状态。
-- 阶段 N+1 默认保持 `设计中`，直到完成该阶段自己的 Step 0、验证方式、完成条件和独立准入复核。
-- 只有最新的独立准入复核明确写出“达到 `待实施` 标准”，阶段才可标记为 `待实施`。
-- 不得以阶段 N 的完成证据、全量测试通过、治理脚本通过或实施者声明替代阶段 N+1 的 Step 0。
-- `PLAN_MAP.md` 的 `状态` 是计划级生命周期，`当前阶段` 是阶段身份指针；专项计划只承载该阶段的实施细节和准入证据。
-
-### `待实施` 最低准入条件
-
-当前阶段进入 `待实施` 前，必须同时具备：
-
-1. 当前阶段目标、范围和非目标。
-2. 明确基线类型的 Step 0 证据。
-3. 样本/fixture 矩阵，包含输入或基线、可执行命令、预期结果、失败判定和输出位置；不适合固定样本时必须记录可观察的替代基线。
-4. 验证方式、完成条件、失败策略和回滚或安全边界。
-5. 没有未解决的当前阶段阻塞项，且 `PLAN_MAP.md` 已同步。
-6. 最新独立准入复核明确为“通过”。
-
-机器识别的结构化章节标题必须保持固定名称：`阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录`。不要在这些标题前添加阶段编号（例如不要写成 `阶段 1 准入摘要` 或 `阶段 1 最新独立准入复核`）；阶段身份以 `PLAN_MAP.md` 为准，不在计划正文中另定义阶段编号。若严格检查提示标题问题，优先按提示恢复固定标题。阶段准入摘要还必须使用固定字段：`准入状态`、`Step 0`、`样本矩阵`、`验证方式`、`失败/回滚边界`、`当前阻塞项`、`最新独立准入复核`。
-
-### 独立复核记录
-
-专项计划应保留追加式的独立复核记录，并显式维护最新结论的日期、阶段、结论、证据和复核者。历史记录不得覆盖；新的“未通过”覆盖此前的“通过”，修复后的新“通过”必须追加新记录。`PLAN_MAP.md` 只链接最新有效结论，不复制历史表格。
-
-### 阶段内独立复核调度
-
-- 阶段门复核只在阶段准入、阶段转换或计划明确的高影响边界触发；不为每个微小动作单独复核。
-- 对目标、范围和授权边界已清楚且不涉及高影响外部动作的普通阶段门，执行者应自动启动独立只读 subagent 或等价独立复核者，不等待用户逐项确认。复核任务使用新上下文，不参与当前阶段实施，不修改工作区；输入至少包括计划、阶段、被审查 revision、范围、验证命令、完成条件和安全边界。
-- 复核通过后，记录复核者、命令和证据位置，并继续当前计划/阶段推进；跨轮继续由 `goal` 保持上下文。
-- 复核失败、复核入口不可用、超时或证据冲突时，保留阻塞并报告，不得自我批准或以安全替代动作单独放行。只有满足同等独立性和证据要求的等价复核者可以替代；没有复核者时必须停止并报告。
-- 涉及外部授权、凭证、公开暴露、破坏性或不可逆操作、安全、隐私、合规或产品取舍的事项，必须请求用户确认；独立复核不能代替用户授权。
-- 复核结果至少记录：计划、阶段、被审查 revision、复核范围、实际执行命令、证据位置、结论、阻塞项和复核者标识。
-
-阶段准入检查命令为 `--strict-readiness`。默认治理检查保持兼容，面向历史文档的准入缺陷先以 `WARNING` 提示；严格模式才将机械准入缺陷提升为 `ERROR`。该检查只判断结构化准入条件，不替代业务验收。
-
-## 工作流
-
-1. 检查仓库是否已有 `docs/PLAN_MAP.md` 和相关计划。
-2. 按启用判定决定是否需要治理。
-3. 如果需要初始化，运行 npm 包内的 `plan-governance-cli init` 生成最小结构；只有需要特殊改写时才手动复制 `assets/` 模板。已有项目不要重新初始化计划文档，使用 `--update-agent-rules-only` 或 `--upgrade-existing`。升级其他项目时也使用当前 npm 包提供的 `plan-governance-cli init`，不要调用目标项目里的旧脚本。旧项目若 `PLAN_MAP.md` 还是五列表，使用 `--migrate-plan-map-last-updated` 显式迁移。
-4. 初始化治理文档后，立即执行事实源切换：识别已有 README、草案、旧计划、归档设计文档，将它们视为背景材料或历史记录；从此刻起，新规范只写入 `docs/plans/*.md`、`PLAN_MAP.md`、ADR、migration 或正式 spec，除非用户明确要求，不再编辑旧草案。
-5. 对需求尚未收敛且满足触发条件的任务，先执行 grilling；在用户确认结构化总结前，不实施也不把暂定内容写成规范事实。
-6. 实施前让当前阶段可执行：
-   - 目标、范围、非目标明确
-   - 必要的不变量和信任边界明确
-   - 必要的公共契约和失败策略明确
-   - Step 0 证据存在
-   - 验证方式可运行
-   - 当前阶段没有未解决阻塞项
-7. 只实施当前阶段。后续阶段保持粗粒度。
-8. 新信息改变假设时，先更新 `PLAN_MAP.md` 和相关计划，再继续实施；计划被推进、恢复、暂停或复核时同步 `最后更新`。
-9. 完成时记录验证证据、测试覆盖率证据并更新状态。
-10. 验收治理文档时先做独立复核和反向引用检查：不得仅依据计划状态、完成证据文字或文档格式判定完成；必须核对当前仓库内容、可复现验证命令、测试或 CI 输出、覆盖率证据，以及用 `rg` 搜索同名计划、P 编号、状态名、关键字段和 `草案为准|以草案为事实源|详见草案|draft is source|source of truth.*draft|以.*draft.*为准`，确认所有路线图、优先级计划和索引已经同步，且旧草案没有重新成为事实源。
-11. 运行 `plan-governance-cli check`；如果项目仍保留旧脚本，只把它作为回滚或对照，不作为新的分发源。需要检查活跃计划停滞时运行 `--stale-days`，默认 10 天。
+| 多计划依赖、替代、重叠或冲突 | 1 |
+| 同一模块后续反复修改 | 1 |
 
-## Step 0 证据
+>=3 启用/更新治理；=2 先检查已有治理再判断是否需要结构；<=1 按普通任务。大型公共契约迁移可直接启用。不为小修改强制建立计划、spec 或 ADR。
 
-实施前必须先固定可观察基线：
+## 按需读取
 
-| 任务类型 | Step 0 证据 |
+| 当前工作 | 读取 |
 |---|---|
-| 缺陷修复 | 失败回归测试或最小复现 |
-| 行为迁移 | 现状快照、兼容样本或契约测试 |
-| 新项目 | 可执行验收 fixture、协议样本或提交图 |
-| 架构探索 | 最小原型、风险实验或关键假设验证 |
-
-如果 Step 0 不现实，记录原因，并定义替代基线后再改实现。
-
-## 漂移检查
-
-当决策、实现发现或运行报告改变以下内容时，暂停实施并更新治理文档：
-
-- 既有 ADR 或核心原则
-- 计划顺序、依赖、替代关系或有效性
-- 公共 API、Schema、状态语义、兼容承诺或失败模式
-- 多个计划共享的重复修改点
-- 用来证明完成的测试或完成条件
-- 专项计划与路线图、优先级计划或索引之间的状态、字段方案、完成条件或验证结果
-
-## 停滞检查
-
-`PLAN_MAP.md` 的计划索引应包含 `最后更新` 列，日期格式为 `YYYY-MM-DD`。
-
-计划索引必须在同一个 `## 计划索引` 章节下，按固定顺序拆成三张六列表格：`### 未完成`、`### 已完成`、`### 已废弃`。状态归类规则如下：
-
-- `未完成`：`候选`、`设计中`、`待实施`、`实施中`。
-- `已完成`：`已完成`。
-- `已废弃`：`已废弃`、`已替代`、`已合并`等不再推进的终态；表格标题不改变行内真实状态。
-
-每个计划只能出现一次；没有对应计划的分类保留表头但不添加占位行。必须使用三级标题，以便治理 CLI 将三张表作为同一个计划索引读取。
-
-推荐表头：
-
-```markdown
-| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
-```
-
-规则：
-
-- `最后更新` 是显式治理元数据，不从 Git 历史或文件 mtime 推断。
-- 当计划状态、当前阶段、阻塞项、依赖、完成条件、验证结果或实施范围变化时，同步 `最后更新`。
-- `--stale-days` 只对 `候选`、`设计中`、`待实施`、`实施中` 等活跃计划输出 `WARNING`，不自动改变状态。
-- `--stale-days` 省略数值时默认 10 天，可显式传入 N。
-
-## 初始化、模板和检查脚本
-
-- `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`。
-
-## 图谱与计划前置影响分析
-
-当项目声明了功能图谱或架构图谱时，使用 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 依据文件、符号、类型和测试等证据确认，证据不足或存在多个合理候选时再请求用户确认。
-
-`影响模块或文件` 的作用域匹配规则：
+| 需求探索与 grilling、制定/更新计划、文档职责或同步 | [planning](references/planning.md) 的相关章节 |
+| 当前阶段准入、风险分流、自验/独立复核、验证、反馈或完成 | [verification](references/verification.md) 的相关章节 |
+| 初始化/升级、检查/workset、hook、快照、图谱或分发 | [cli](references/cli.md) 的对应操作 |
 
-- `--drift`、`--pre-commit` 和 `plan_governance_hook.py --event pre-write` 使用同一语义；已完成计划的关闭窗口只适用于 drift/pre-commit，不扩大 pre-write 的活跃计划门禁。
-- 优先提取列表项中的第一个反引号路径，例如 ``- `./scripts/`: 检查脚本``。
-- 没有反引号时提取第一个纯文本 token，例如 `- README.md`。
-- 匹配前归一化前导 `./`、尾随 `/` 和重复斜杠。
-- 支持文件精确匹配和目录前缀匹配。
-- 不支持 glob、正则、否定规则或自然语言推断。
+参考相对本 skill 实际安装位置读取，不相对项目 cwd。仅安装 CLI 时，`plan-governance-cli guide` 读取本入口，`guide planning|verification|cli` 读取相应正文；缺失资源明确报错，不猜路径或自动安装。选择同一版本来源，不能混读不同副本；旧 CLI 不支持 guide 或风险策略时，先说明能力缺失。
 
-只读 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
-```
+- 首次接手读取 PLAN_MAP、当前计划和确实相关的契约/ADR/migration；恢复先看当前工作集、当前阶段、最近证据和实际 diff，缺失或冲突再扩大读取，不每轮重读全部历史。
+- 复用已确认需求和授权。未明确且满足触发条件的高影响取舍才做 grilling；可验证的事实自己查。必需回答不能以沉默推定，清楚的普通细节自主决定。
+- 低风险且范围、实际后果、可逆性和验证充分的改动由当前 AI 自验，失败自主修复/复验；高影响、有效独立失败或实质疑点保留必要独立检查。风险规则及新/旧机器记录在 verification，不以行数或阶段事件一概判断。
+- 只实施当前获准且有授权的阶段。每阶段有自身 Step 0、样本、验证/完成与失败边界、无有效阻塞和适用复核；旧计划未显式选择风险策略时保留独立门禁，新策略不批准自身变更。
+- 独立复核失败、不可用、超时或证据冲突不自批或改分类放行。需要复核且授权清楚时自动安排独立只读 subagent；它不能代替新的外部授权。
+- 验证真实可观察结果，按变更范围补验；只有当前树、依赖/配置、环境和验收契约均被可信证据覆盖时才复用全量结果。纯落档做适用文档检查，不无理由全跑。
+- 适用功能计划技术完成待用户体验时保持实施中，明确待验收项；用户接受后关闭。原范围小问题自主闭环，沉默、提交和技术通过不代替用户接受；普通小改不增加逐次签收。
+- 状态、阶段、关系、阻塞和证据入口以 PLAN_MAP 为准；专项计划写本次差异及证据，现行契约优先复用已有 Schema/OpenAPI，按需才建 spec。新事实不写回旧草案。
 
-该脚本不自动安装 `.codex/hooks.json` 或修改全局配置。`stop` 事件只做非阻塞提示，不实现强制 gate。
+已授权的 `goal` 可用于跨轮继续；本 skill 不另建整计划自主执行运行时，也不默认创建 goal、安装或发布。结束简报结果、适用验证、剩余阻塞及可访问证据，不堆完整日志。

package/resources/skill/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Plan Governance"
   short_description: "用计划、证据和检查管理分阶段工作"
-  default_prompt: "使用 $plan-governance 管理这个跨阶段变更，维护计划文档、Step 0 证据和完成检查；阶段门仅在必要时自动启动独立只读 subagent，不为每个微小动作单独复核。"
+  default_prompt: "使用 $plan-governance 管理这个跨阶段变更，维护计划文档、Step 0 证据和完成检查；按共享规范选择低风险自验或高影响独立复核，并保留用户验收闭环。"

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

@@ -9,6 +9,7 @@
 - `PLAN_MAP.md` 的 `状态` 是计划级生命周期，`当前阶段` 是阶段身份指针。
 - 阶段 N 完成后，阶段 N+1 默认保持 `设计中`；专项计划自己的准入复核通过后才能进入 `待实施`。
 - 阶段准入摘要、样本矩阵和独立复核记录只写入专项计划，不复制到本索引。
+- 专项计划记录本次行为差异和验收；现行契约优先引用已有 Schema/OpenAPI，无合适来源且需长期维护时才按需建立 `docs/specs/*.md`。同一事实不重复维护。
 - 专项计划可在当前阶段声明阶段证据和追加式实施/验证记录；完成快照默认保持旧 JSON 兼容格式，发布/合规场景再显式使用 purpose 关系。
 - `--drift`/`--pre-commit` 的关闭窗口只在已完成计划自身也发生变更时覆盖该计划自身和显式阶段证据，不复用已完成计划的完整影响范围。
 - 计划索引固定分为 `未完成`、`已完成`、`已废弃` 三张表；`已替代`、`已合并`等不再推进的终态归入 `已废弃` 表，但保留真实状态值。