plan-governance-cli 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,9 +23,9 @@
23
23
 
24
24
  ## 需求探索与 grilling
25
25
 
26
- 对可能进入治理、但目标、边界、验收或关键取舍尚未收敛的任务,`plan-governance` 会优先使用可用的 `grill-me` 进行需求探索:高影响事项存在关键不明确内容时触发,或同时存在至少两项需求不确定性信号时触发。每次只推进一个问题;可从仓库和工具查证的事实先查证,决策由用户确认。
26
+ 先利用上下文和工具查证需求,在已有授权内推进。只有必须由用户决定、且会实质影响结果或授权边界的问题才询问,已有决定不重复确认。
27
27
 
28
- 结束时应由用户确认结构化总结:目标、范围和非目标、已确认事实、暂定假设、候选方案、未决问题和下一步验证。只有需要治理的任务才把该摘要写入专项计划的 `需求探索` 章节;它不替代 Step 0 或阶段准入,也不会自动生成 ADR。未安装 `grill-me` 时保持在澄清/设计边界,不伪造访谈完成。
28
+ `grill-me` 是深入探索时的可选方法,缺失不阻塞任务。需要治理时把重要决定和未决问题记录到当前计划;普通可逆细节自主处理,等待必要答案时继续无依赖的授权工作。
29
29
 
30
30
  ## 文档结构
31
31
 
@@ -205,9 +205,9 @@ plan-governance-cli graph code impact --repo modelpad --file Sources/ModelPadCor
205
205
 
206
206
  ## 持续推进
207
207
 
208
- 在已授权的跨轮任务中可使用 `goal`;skill 本身不定义整计划自主执行运行时。低风险改动由当前 AI 自验,高影响或有效独立失败保留必要独立复核;已有计划缺省独立门禁兼容保留。
208
+ 在已授权的跨轮任务中可使用 `goal`;skill 本身不定义整计划自主执行运行时。普通改动自验,高风险或高影响同范围只独立复核一次,修复后自验;旧计划显式采用新策略,保留历史。
209
209
 
210
- [验证规范](resources/skill/references/verification.md)统一维护风险分流、证据复用、失败重审与用户验收;其他会话从同一 skill 读取。需要独立复核且授权明确时自动安排只读 subagent,不为普通小改逐次派发;技术完成待用户验收的适用功能计划仍保持实施中。
210
+ [验证规范](resources/skill/references/verification.md)统一维护风险分流、证据复用、修复自验与用户验收;其他会话从同一 skill 读取。需要独立复核且授权明确时自动安排只读 subagent,不为普通小改逐次派发;技术完成待用户验收的适用功能计划仍保持实施中。
211
211
 
212
212
  1.0.1 起支持可选的最近记录窗口:
213
213
 
@@ -228,7 +228,7 @@ plan-governance-cli guide cli # CLI 操作
228
228
 
229
229
  读取当前包内正文,与 cwd 无关,不需要 Python,不下载或修改项目。未知主题、多余参数、缺失或空资源非零退出。项目受管入口依赖已安装 skill 或具备上述能力的 CLI;两者均不可用时明确说明前提,不自动安装。
230
230
 
231
- SKILL 保留任务分流和执行底线,三份 references 按需读取并随 manifest/setup/npm 分发。已有项目只刷新受管入口,不迁移旧计划、不改用户块外内容。选择同一版本的规范来源,安装副本与仓库同版本号也可能有不同内容。
231
+ SKILL 保留任务边界、自主执行原则和按需入口,三份 references 按需读取并随 manifest/setup/npm 分发。已有项目只刷新受管入口,不迁移旧计划、不改用户块外内容。选择同一版本的规范来源,安装副本与仓库同版本号也可能有不同内容。
232
232
 
233
233
  也可以不全局安装,直接使用锁定版本:
234
234
 
@@ -375,7 +375,7 @@ python3 -m pytest
375
375
 
376
376
  状态与当前阶段由 `docs/PLAN_MAP.md` 维护。每阶段必须具备自身 Step 0、验证/完成和失败边界、无有效阻塞及适用复核,不能凭上一阶段完成自动待实施。
377
377
 
378
- 旧计划缺省沿用独立准入;新模板显式采用风险分流,低风险自验与高影响独立分别如实记录,旧独立失败不能被自验遮蔽。固定字段、历史保护和严格检查语义以[阶段门规范](resources/skill/references/verification.md#step-0-与阶段门)为准。
378
+ 旧计划缺省沿用独立准入;新模板使用单次独立复核策略,普通改动自验,高风险或高影响独立检查一次后由实施者修复自验,原发现保留。固定字段、历史保护和严格检查语义以[阶段门规范](resources/skill/references/verification.md#step-0-与阶段门)为准。
379
379
 
380
380
  使用 `check --strict-readiness` 做准入/CI/发布机械检查;默认检查兼容告警,机械通过不代替真实风险判断、业务验收或用户接受。
381
381
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "plan-governance-cli",
3
- "version": "1.0.3",
3
+ "version": "1.1.0",
4
4
  "description": "统一入口的计划治理检查 CLI",
5
5
  "private": false,
6
6
  "type": "module",
@@ -1,43 +1,26 @@
1
1
  ---
2
2
  name: plan-governance
3
- description: 轻量计划治理工作流。Use when 用户要求管理路线图、分阶段实施、迁移、架构变更、公共 API 或 Schema 变更、长期任务、计划漂移、ADR、Step 0 证据、PLAN_MAP.md、docs/plans 文件,或希望 Codex 协调多个相关计划,同时避免把普通小任务流程化。
3
+ description: 维护已有项目计划,或为需要跨阶段、跨会话协调依赖与决策的工作建立轻量治理。用户要求 PLAN_MAP、专项计划或治理时使用;普通一次性修复、解释代码和零散待办不启用完整流程。
4
4
  ---
5
5
 
6
6
  # Plan Governance
7
7
 
8
- 用计划、证据和适用验证管理跨阶段、会漂移的工作。普通一次性 bugfix、小范围本地修改和互不依赖的待办,不启用完整治理,除非已有计划覆盖或用户明确要求。
8
+ 帮助用户完成需要持续协调的工作,维护足够的计划、决策与验证证据。已有相关计划时沿用;需要持久记录阶段和依赖时才新建。任务持续多轮或涉及 API,并不自动要求治理。
9
9
 
10
- ## 先分流
10
+ ## 执行原则
11
11
 
12
- | 信号 | 分数 |
13
- |---|---:|
14
- | 跨阶段、里程碑或多轮会话 | 1 |
15
- | 架构、公共 API、Schema、兼容性或迁移 | 1 |
16
- | 依赖真实运行报告、样本或反馈 | 1 |
17
- | 多计划依赖、替代、重叠或冲突 | 1 |
18
- | 同一模块后续反复修改 | 1 |
12
+ 根据当前请求、上下文和已有授权持续推进。用户指令优先于本 skill 的流程建议;保留用户明确的实现、外部操作和验收边界。能自行查证或作可逆决定的事项自主处理;只有缺失信息会实质改变结果或超出授权时才询问,并继续不依赖该答案的工作。
19
13
 
20
- >=3 启用/更新治理;=2 先检查已有治理再判断是否需要结构;<=1 按普通任务。大型公共契约迁移可直接启用。不为小修改强制建立计划、spec 或 ADR。
14
+ 首次接手读取地图、当前相关计划及必要契约;恢复只核对当前阶段、实际差异和最近证据。只实施已授权且准入的范围;实质边界变化时调整受影响计划,日常进展随工作同步。事实源与格式见 planning。
15
+
16
+ 先确定当前计划的有效复核策略,再按 verification 验证;单次策略下,高风险或高影响同范围独立检查一次,修复由实施者自验。适用检查通过后完成交付;未解决问题如实保留。交付说明完成结果、必要证据和剩余事项,明确约定的用户体验验收继续有效。
21
17
 
22
18
  ## 按需读取
23
19
 
24
- | 当前工作 | 读取 |
20
+ | 当前动作 | 参考 |
25
21
  |---|---|
26
- | 需求探索与 grilling、制定/更新计划、文档职责或同步 | [planning](references/planning.md) 的相关章节 |
27
- | 当前阶段准入、风险分流、自验/独立复核、验证、反馈或完成 | [verification](references/verification.md) 的相关章节 |
28
- | 初始化/升级、检查/workset、hook、快照、图谱或分发 | [cli](references/cli.md) 的对应操作 |
29
-
30
- 参考相对本 skill 实际安装位置读取,不相对项目 cwd。仅安装 CLI 时,`plan-governance-cli guide` 读取本入口,`guide planning|verification|cli` 读取相应正文;缺失资源明确报错,不猜路径或自动安装。选择同一版本来源,不能混读不同副本;旧 CLI 不支持 guide 或风险策略时,先说明能力缺失。
31
-
32
- ## 执行底线
33
-
34
- - 首次接手读取 PLAN_MAP、当前计划和确实相关的契约/ADR/migration;恢复先看当前工作集、当前阶段、最近证据和实际 diff,缺失或冲突再扩大读取,不每轮重读全部历史。
35
- - 复用已确认需求和授权。未明确且满足触发条件的高影响取舍才做 grilling;可验证的事实自己查。必需回答不能以沉默推定,清楚的普通细节自主决定。
36
- - 低风险且范围、实际后果、可逆性和验证充分的改动由当前 AI 自验,失败自主修复/复验;高影响、有效独立失败或实质疑点保留必要独立检查。风险规则及新/旧机器记录在 verification,不以行数或阶段事件一概判断。
37
- - 只实施当前获准且有授权的阶段。每阶段有自身 Step 0、样本、验证/完成与失败边界、无有效阻塞和适用复核;旧计划未显式选择风险策略时保留独立门禁,新策略不批准自身变更。
38
- - 独立复核失败、不可用、超时或证据冲突不自批或改分类放行。需要复核且授权清楚时自动安排独立只读 subagent;它不能代替新的外部授权。
39
- - 验证真实可观察结果,按变更范围补验;只有当前树、依赖/配置、环境和验收契约均被可信证据覆盖时才复用全量结果。纯落档做适用文档检查,不无理由全跑。
40
- - 适用功能计划技术完成待用户体验时保持实施中,明确待验收项;用户接受后关闭。原范围小问题自主闭环,沉默、提交和技术通过不代替用户接受;普通小改不增加逐次签收。
41
- - 状态、阶段、关系、阻塞和证据入口以 PLAN_MAP 为准;专项计划写本次差异及证据,现行契约优先复用已有 Schema/OpenAPI,按需才建 spec。新事实不写回旧草案。
22
+ | 明确需求、维护计划、同步决策 | [planning](references/planning.md) |
23
+ | 阶段准入、风险判断、验证或完成 | [verification](references/verification.md) |
24
+ | 查询工作集、运行检查、初始化或分发 | [cli](references/cli.md) |
42
25
 
43
- 已授权的 `goal` 可用于跨轮继续;本 skill 不另建整计划自主执行运行时,也不默认创建 goal、安装或发布。结束简报结果、适用验证、剩余阻塞及可访问证据,不堆完整日志。
26
+ 开发或审查本 skill 时使用仓库源及对应 CLI;其他项目使用实际发现的安装版,参考按所选 skill 目录解析。仅 CLI 可用时用 `guide` 和对应主题读取。来源一次选定后复用,只有内容变化或能力不符时重新核对;不要混读副本。缺少所需能力时说明具体缺口,继续不依赖它的工作,安装与升级按已有授权处理。
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "Plan Governance"
3
3
  short_description: "用计划、证据和检查管理分阶段工作"
4
- default_prompt: "使用 $plan-governance 管理这个跨阶段变更,维护计划文档、Step 0 证据和完成检查;按共享规范选择低风险自验或高影响独立复核,并保留用户验收闭环。"
4
+ default_prompt: "使用 $plan-governance 管理这个跨阶段变更,维护计划文档、Step 0 证据和完成检查;按当前有效策略验证,在已有授权内完成交付,保留适用用户验收。"
@@ -12,26 +12,16 @@
12
12
 
13
13
  - 待补充。
14
14
 
15
- <!-- 仅在触发 grilling 且用户确认结构化结论后保留本节;否则删除本节和本注释。 -->
15
+ <!-- 仅在存在需要保留的需求取舍时填写,否则删除本节。 -->
16
16
  ## 需求探索
17
17
 
18
- ### 已确认事实
19
-
20
- ### 暂定假设与验证方式
21
-
22
- ### 范围与非目标
23
-
24
- ### 候选方案与取舍
25
-
26
- ### 未决问题
27
-
28
- ### 用户确认的探索结论
18
+ 记录重要决定、假设及未决问题;已确认内容不重复签收。
29
19
 
30
20
  ## 不变量
31
21
 
32
22
  - 当前阶段写细,后续阶段写粗。
33
23
  - 完成时必须记录可验证证据。
34
- - 按共享 skill 的 verification 规范判断风险:低风险自验,高影响或有效独立失败保留独立复核;不按改动行数或阶段事件一概派发。
24
+ - 按共享 skill 的 verification 规范判断风险:普通改动自验,高风险或高影响同范围独立复核一次,修复后自验;不按改动行数或阶段事件一概派发。
35
25
 
36
26
  ## 影响模块或文件
37
27
 
@@ -60,7 +50,7 @@
60
50
  | 字段 | 内容 |
61
51
  |---|---|
62
52
  | 准入状态 | {{status}} |
63
- | 复核策略 | 风险分流 |
53
+ | 复核策略 | 单次独立复核 |
64
54
  | Step 0 | 当前阶段 Step 0 证据的链接或锚点 |
65
55
  | 样本矩阵 | 样本/fixture 或替代基线的链接或锚点 |
66
56
  | 验证方式 | 可执行命令和输出位置的链接或锚点 |
@@ -93,7 +83,7 @@
93
83
 
94
84
  ### Attestation 说明
95
85
 
96
- 默认完成快照保持 `docs/attestations/<plan>.json` 兼容格式。发布门禁或合规场景可显式使用 `purpose`、`snapshot_id`、`supersedes` 和 `review_status`;普通 hash 漂移仍需人工复核。
86
+ 仅采用快照时填写;格式和检查方式见所选 skill 的 CLI 参考。
97
87
 
98
88
  ### 验证方式
99
89
 
@@ -109,7 +99,7 @@
109
99
 
110
100
  ### 测试覆盖率
111
101
 
112
- 待补充。完成后需要记录测试覆盖率报告,例如 pytest-cov 输出、覆盖率百分比、关键模块覆盖情况等。
102
+ 按项目契约和实际改动提供覆盖率或适用验证证据;纯文档可注明“代码覆盖率不适用”,不为填表运行无关测试。
113
103
 
114
104
  ### 完成条件
115
105
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  只读规则入口:`plan-governance-cli guide [overview|planning|verification|cli]`。缺省 overview;`guide --help` 列用法。四主题从同一包根读取本入口及三参考,任意 cwd 可用且无需 Python。正文中的相对文档链接在 CLI 环境通过对应 guide 主题读取,不相对当前项目查找。
4
4
 
5
- 成功退出 0;未知主题、多余参数、缺失/不可读/空资源退出 1 并报错。不下载、安装、修改项目或回退别的版本。skill 环境按实际发现的安装目录读取同源资源,避免硬编码用户路径;存在 skill 与 CLI 多版本时选择一个规范来源并核对所需能力,版本号相同不证明资源一致。
5
+ 成功退出 0;未知主题、多余参数、缺失/不可读/空资源退出 1 并报错。不下载、安装、修改项目或回退别的版本。skill/CLI 来源按入口一次选定:开发本 skill 用仓库源与对应 CLI,其他项目用安装资源。出现内容变化或能力缺口时再核对,版本号相同不证明资源一致。
6
6
 
7
7
  已安装 skill 不等于 CLI 存在;既无 skill 也无 CLI 时说明治理前提缺失,仅阻塞依赖治理规则的工作,不自动安装。CLI 不支持新策略或 guide 时明确能力缺失,按授权更新。仅需阅读规则不调用 init/setup。
8
8
 
@@ -20,7 +20,7 @@
20
20
 
21
21
  SKILL、三个 references、agents 元数据与 assets 由同一 npm 包的 manifest 分发。`plan-governance-cli setup --target codex|claude|all --dry-run` 查看同步差异;实际覆盖需既有用户授权并按 setup 冲突提示处理,不自动清理用户目录残留。项目升级不迁移旧计划,受管块外内容必须保持。
22
22
 
23
- 仅更新计划格式不等于更新项目入口;更新 AGENTS/CLAUDE 入口也不等于当前阶段已采用风险分流。已有项目在任务交接、没有进行中的实施或复核时更新受管入口;阶段策略单独按 verification 兼容规则处理,不批量回写历史。安装副本与仓库开发规则有差异时说明本次选用来源,不能因版本号相同就混读正文。
23
+ 仅更新计划格式不等于更新项目入口;更新 AGENTS/CLAUDE 入口也不等于当前阶段已采用新复核策略。已有项目在任务交接、没有进行中的实施或复核时更新受管入口;阶段策略单独按 verification 兼容规则处理,不批量回写历史。安装副本与仓库开发规则有差异时说明本次选用来源,不能因版本号相同就混读正文。
24
24
 
25
25
  ## 初始化、模板和检查脚本
26
26
 
@@ -1,134 +1,61 @@
1
1
  # 计划与契约
2
2
 
3
- 从 [skill 入口](../SKILL.md) 判断任务是否需要治理;仅 CLI 环境用 `plan-governance-cli guide overview`。本页只维护文档、探索与同步规则;阶段证据和复核见 [verification](verification.md)。
3
+ 从 [skill 入口](../SKILL.md) 判断是否需要治理。本页维护计划与决策,验证和阶段完成见 [verification](verification.md);CLI 入口为 `guide planning`。
4
4
 
5
5
  ## 需求探索与 grilling
6
6
 
7
- 对可能进入治理的任务,如果运行环境声明 `grill-me` 可用,满足下列任一条件时自动调用它,在实施或冻结详细方案前先澄清需求:
7
+ 先利用上下文和可查证事实补齐需求。普通可逆细节自主决定;只有必须由用户决定、且会实质改变结果或授权边界的缺口才提问。问题聚焦当前取舍,不因某个字段未填完整就重做访谈或重复确认已有决定。
8
8
 
9
- 1. 涉及公共 API、Schema、迁移、兼容性或不可逆操作,且目标、边界、验收或关键取舍中至少一项未明确;
10
- 2. 下列不确定性信号中至少两项同时存在:目标/验收不清、范围/非目标不清、存在多个有实质取舍的方案、关键事实尚待查证、后续返工成本显著。
11
-
12
- 目标、影响范围和验收方式均明确的小范围任务,以及当前阶段已通过准入且已确认假设没有变化的工作,跳过自动 grilling;用户仍可显式调用它。已确认的范围、验收与授权直接复用,不为相同结论重新 grilling。仅影响可选细节的问题可在合理等待后声明假设继续;必需答案和授权不可由沉默推定。
13
-
14
- grilling 每次只问一个问题。可从仓库、环境或工具确认的事实必须先查证;产品取舍、外部承诺和不可逆选择由用户确认。结束前必须汇总并得到用户确认:目标、范围和非目标、已确认事实、暂定假设及验证方式、候选方案与取舍、未决问题及阻塞级别,以及验收口径或下一步动作。
15
-
16
- 用户确认后,只有在任务需要治理时,才把结构化结论写入专项计划的 `需求探索` 章节;不保存完整访谈逐字稿,不自动创建 ADR。探索结论不替代当前阶段的 Step 0、样本矩阵、验证方式、失败/回滚边界或适用阶段准入复核。`grill-me` 不可用时,说明依赖不可用并保持在澄清/设计边界,不得伪造已完成 grilling 或静默实施。
17
-
18
- 收敛时固定少量可观察场景:输入/前置、操作、可见结果;已有场景直接链接。涉及运行资源影响时明确环境、负载、采样窗口和相关 CPU/内存/磁盘等指标,不发明通用阈值。交互或方案明显不确定时安排关键流程原型/早期体验;目标明确的小修改不增加中途签收。反馈未到可继续不依赖它的已授权工作。
9
+ 需要深入探索或用户点名时可使用 `grill-me`;它是可选方法,缺失不阻塞任务,可直接澄清关键问题。需要治理时将已确认的范围、重要假设与未决取舍记入计划;只有新的必要决定等待回答,其余已授权工作继续。
19
10
 
20
11
  ## 仓库模型
21
12
 
22
- 使用项目内这些文件作为事实来源:
23
-
24
- ```text
25
- docs/
26
- PLAN_MAP.md
27
- plans/
28
- <plan-name>.md
29
- specs/
30
- <capability>.md # 按需,优先复用已有 Schema/OpenAPI
31
- adr/
32
- 0001-<decision>.md
33
- migrations/
34
- <migration-name>.md
35
- ```
36
-
37
- 只创建有真实内容的文件,不预建空目录或强制 PRD/design/tasks 组合。`docs/plans/*.md` 保持平铺。`docs/reviews/` 存独立复核,`docs/fixtures/` 存人工样本/回放说明,`tests/fixtures/` 存可执行输入,`docs/attestations/` 仅在使用快照时需要。
38
-
39
- 文档权责:
40
-
41
- - `PLAN_MAP.md`:计划索引、状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、当前阻塞项、证据链接。
42
- - `docs/plans/*.md`:本次变更的目标、范围、行为差异、阶段、Step 0、验证与完成条件;链接现行契约。没有独立契约来源时明确由计划哪个位置承载,不要求追溯提取旧内容。
43
- - `docs/adr/*.md`:持久架构决策及其后果。
44
- - `docs/migrations/*.md`:兼容策略、迁移步骤、回滚方式、旧行为保留窗口。
45
- - 现行契约优先复用已有 Schema/OpenAPI。需要跨迭代维护文字行为且无合适来源时,才按需建立 `docs/specs/<capability>.md`;可使用 [spec 模板](../assets/spec.template.md),补充输入/输出、不变量、失败语义与可观察场景,不复制已有字段定义或计划进度。
13
+ 只创建当前任务需要的文档,不预建完整目录或 PRD/spec/ADR 套装。
46
14
 
47
- 同一事实只定义一次,其他地方通过链接引用。独立 migration 承载迁移步骤、窗口和回滚后,计划改为引用;ADR 保留选择理由和后果,不复制契约字段或进度。
15
+ | 文档 | 职责 |
16
+ |---|---|
17
+ | `docs/PLAN_MAP.md` | 计划状态、阶段、关系、阻塞及证据入口 |
18
+ | `docs/plans/*.md` | 本次目标、范围、决策、差异与验证证据,计划文件平铺 |
19
+ | Schema/OpenAPI 或 `docs/specs/` | 现行公共契约,优先复用已有来源 |
20
+ | `docs/adr/`、`docs/migrations/` | 确有需要时记录长期架构决策或迁移步骤 |
21
+ | `docs/reviews/`、`docs/fixtures/` | 必要复核及可复验样本,代码 fixture 放 `tests/fixtures/` |
48
22
 
49
23
  ## 多文档同步规则
50
24
 
51
- - 专项计划按上述文档权责记录本次差异和证据,现行字段与行为从唯一契约来源读取。
52
- - `PLAN_MAP.md` 是状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
53
- - 总路线图、优先级计划和索引只记录顺序、状态摘要和专项计划链接,不复制字段级方案、枚举、Step 0 细节或完成定义。
54
- - 当专项计划的状态、当前阶段、最后更新、字段方案、完成条件或验证结果变化时,必须同步 `PLAN_MAP.md` 和所有引用该计划的路线图、优先级计划或索引。
55
- - 验收治理文档时,必须用 `rg` 搜索同名计划、P 编号、状态名和关键字段,检查是否存在重复定义或漂移。
56
- - 如果同一事实在多个文档中重复,保留一个事实源,其他文档改为链接引用。
57
- - 实施者填写的计划状态、完成证据文字和文档格式只代表实施声明,不等于验收结论;按适用复核方式基于当前仓库内容、可复现验证命令和反向引用确认。
25
+ 同一事实保留一个权威来源,其他文档引用。决策或结果改变后,同步地图及实际受影响的索引/引用;同一组已收敛变化可合并同步,不为每次保存增加流程。用 `rg` 定向检查相关计划名、关键字段和链接,不重扫无关历史。
58
26
 
59
27
  ## 草案和历史文档处理
60
28
 
61
- 启用计划治理后,已有草案、历史设计、归档计划、superpowers 记录、临时分析文档等默认只作为背景材料,不再作为规范事实源。
62
-
63
- - 除非用户明确点名要求更新这些文档,否则不要继续修改它们来承载新规范。
64
- - 新发生的目标、范围、非目标、公共契约、字段、Schema、状态语义、阶段、验证方式、完成条件、风险和回滚,应写入 `docs/plans/*.md`、ADR、migration 或正式 spec。
65
- - 计划状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接,应写入或同步 `docs/PLAN_MAP.md`。
66
- - 历史草案可以在治理文档中作为背景材料链接引用,但不应承载新的规范事实。
67
- - 如果治理文档出现“以草案为事实源”“详见草案中的字段定义”“草案为准”等表述,应改为由治理文档自身承载事实源,或链接到正式 spec/Schema。
68
- - 当用户说“补充一下”“记录一下”“把刚才的结论写进去”时,如果治理已启用,默认写入治理文档;不要写入草案、README 或历史设计文档,除非用户明确点名该文件。
69
-
70
- ## 推荐状态
71
-
72
- 统一使用中文状态:
73
-
74
- | 状态 | 含义 |
75
- |---|---|
76
- | `候选` | 记录了想法,但尚未承诺实施 |
77
- | `设计中` | 正在明确范围、契约和门禁 |
78
- | `待实施` | 当前阶段门禁已通过,但尚未开始 |
79
- | `实施中` | 当前阶段推进中;适用时包含技术完成待用户验收 |
80
- | `已完成` | 实现、验证、证据和文档齐全,并满足适用的用户验收 |
81
- | `已替代` | 被另一个计划取代 |
82
- | `已合并` | 并入另一个计划 |
83
- | `已废弃` | 明确不再推进 |
84
-
29
+ 历史草案、旧计划与临时分析保留为背景,不承载新规范。新事实写入当前计划或适用契约;用户明确指定的文档位置优先。已替代内容通过链接说明关系,避免重复改写历史。
85
30
 
86
31
  ## 漂移检查
87
32
 
88
- 当决策、实现发现或运行报告改变以下内容时,暂停实施并更新治理文档:
89
-
90
- - 既有 ADR 或核心原则
91
- - 计划顺序、依赖、替代关系或有效性
92
- - 公共 API、Schema、状态语义、兼容承诺或失败模式
93
- - 多个计划共享的重复修改点
94
- - 用来证明完成的测试或完成条件
95
- - 专项计划与路线图、优先级计划或索引之间的状态、字段方案、完成条件或验证结果
96
-
97
- ## 停滞检查
98
-
99
- `PLAN_MAP.md` 的计划索引应包含 `最后更新` 列,日期格式为 `YYYY-MM-DD`。
100
-
101
- 计划索引必须在同一个 `## 计划索引` 章节下,按固定顺序拆成三张六列表格:`### 未完成`、`### 已完成`、`### 已废弃`。状态归类规则如下:
102
-
103
- - `未完成`:`候选`、`设计中`、`待实施`、`实施中`。
104
- - `已完成`:`已完成`。
105
- - `已废弃`:`已废弃`、`已替代`、`已合并`等不再推进的终态;表格标题不改变行内真实状态。
106
-
107
- 每个计划只能出现一次;没有对应计划的分类保留表头但不添加占位行。必须使用三级标题,以便治理 CLI 将三张表作为同一个计划索引读取。
33
+ 目标、授权、关键契约或高影响后果变化时,重新判断受影响范围的准入与验证;等待必要取舍期间,可继续无依赖的已授权工作。普通反馈、测试结果和状态更新在当前任务内处理并同步,不自动暂停、重开阶段或再索取授权。范围调整不能移走真实阻塞。
108
34
 
109
- 推荐表头:
110
-
111
- ```markdown
112
- | 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
113
- ```
35
+ ## 执行与恢复
114
36
 
115
- 规则:
37
+ 沿用当前有效策略和已确认决定,只展开本次差异、证据缺口及直接依赖。跨阶段工作按 [阶段门](verification.md#step-0-与阶段门)判断,每阶段有自身基线与完成条件;上一阶段通过不自动放行下一阶段。未来事项需注明承接范围与依赖,不以未准入的后续工作阻断无关的当前交付。
116
38
 
117
- - `最后更新` 是显式治理元数据,不从 Git 历史或文件 mtime 推断。
118
- - 当计划状态、当前阶段、阻塞项、依赖、完成条件、验证结果或实施范围变化时,同步 `最后更新`。
119
- - `--stale-days` 只对 `候选`、`设计中`、`待实施`、`实施中` 等活跃计划输出 `WARNING`,不自动改变状态。
120
- - `--stale-days` 省略数值时默认 10 天,可显式传入 N。
39
+ 文档变更后做适用链接、结构和引用检查,运行所选版本的 `plan-governance-cli check .`;准入/发布使用 `--strict-readiness`。纯落档不重复代码测试。用户验收与证据真实性按 verification,不以文档格式通过替代。
121
40
 
122
- ## 执行与恢复
41
+ ## 格式附录:写入地图时读取
123
42
 
124
- 首次接手先区分项目仅更新了文档格式、已接入共享入口,还是当前阶段已显式选择风险策略;新会话或新版 skill 不替代项目策略接入,按 [verification 的旧计划兼容](verification.md#旧计划兼容)核对当前阶段并处理一次性显式迁移,已有策略直接复用。按任务读取 PLAN_MAP、当前计划和确实相关的契约;未启用治理的有限原型不为接入入口强建整套目录。
43
+ ### 推荐状态
125
44
 
126
- 恢复先用已有当前工作集、当前阶段、少量最近证据和实际 diff 定位进度;缺失、冲突或相关范围变化时再展开对应段落。规则参考按当前动作读取,不因拆成多个文件就每次全读。跨计划只展开直接相关对象,完整数据中发现的有效阻塞仍须保留。证据入口不可检索时补要点或可复验入口,不倾倒全部历史代替定位。
45
+ | 状态 | 含义 |
46
+ |---|---|
47
+ | 候选 | 尚未承诺实施 |
48
+ | 设计中 | 明确范围、契约与准入 |
49
+ | 待实施 | 当前阶段已准入 |
50
+ | 实施中 | 执行中,或技术完成等待适用用户验收 |
51
+ | 已完成 | 证据、验证及适用验收齐备 |
52
+ | 已替代、已合并、已废弃 | 终态,保留关系和原因 |
127
53
 
128
- 先确认当前阶段准入和授权,再实施。假设、公共契约、兼容、范围、完成条件或依赖变化时,先更新唯一事实源和地图,再评估准入;阶段内原范围反馈追加差异和验证,不自动新开计划或重开所有门。原验收预期从原场景读取,不因新边界输入自行发明业务规则。
54
+ ### 停滞检查
129
55
 
130
- 用户连续确认普通决定时,由当前 AI 同步相应文档并自查;一组决定收敛后,再按 verification 判断是否需要独立检查。不把每次回答、文档保存或同步操作当作一个复核点;应先判断的高影响取舍不能积压到实施后。
56
+ `## 计划索引` 下依次使用 `### 未完成`、`### 已完成`、`### 已废弃` 三张六列表;每个计划只出现一次。已替代/已合并归入已废弃分表,行内保留真实状态。无对应计划时保留表头。
131
57
 
132
- 验收涉及未来周期或新增工作时,尽早明确它与当前交付的关系。经用户确认范围后,将未来事项的职责、触发条件和证据要求放入适合的现有或独立计划。后续计划尚未准入本身不阻塞当前交付,但当前运行安全、恢复能力和已承诺验收仍须满足;不得仅靠拆计划移走有效阻塞。复核分别判断当前交付与后续承接,结论落档顺序见 verification。
58
+ | 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
59
+ |---|---|---|---|---|---|
133
60
 
134
- 治理文档变更后做适用链接、结构、反向引用和 `plan-governance-cli check .`;用 `rg` 搜索同名计划、P 编号、状态/关键字段,以及 `草案为准|以草案为事实源|详见草案|draft is source|source of truth.*draft|以.*draft.*为准`。纯落档不重跑已有效覆盖的全部代码测试;规范行为变化仍需验证受影响场景。
61
+ `最后更新` 使用 YYYY-MM-DD,在状态、阶段、依赖、范围、阻塞或验证结果变化时同步;不从文件时间或 Git 推断。`check --stale-days [N]` 可提示活跃计划停滞,默认 10 天,不自动改变状态。
@@ -1,91 +1,71 @@
1
1
  # 验证、复核与用户验收
2
2
 
3
- 本页是风险分流、阶段门和证据闭环的规范来源。[入口](../SKILL.md)先判断是否需要治理;仅 CLI 环境用 `plan-governance-cli guide verification`。
3
+ 本页维护有效策略、阶段门和交付证据;CLI 入口为 `guide verification`。执行方法按当前策略决定,写入记录时再读格式部分。
4
4
 
5
- ## 按风险复核
6
-
7
- | 情况 | 执行方式 |
8
- |---|---|
9
- | 目标、范围和实际后果明确,可撤销,适用验证充分的低风险改动 | 当前 AI 检查差异、验证实际行为,失败后自主修复/复验;简报证据,不为每次改动派独立 subagent 或新建报告 |
10
- | 安全/权限/隐私/公开暴露、数据完整性/迁移、核心公共契约/生命周期、广泛共享逻辑或难以撤销后果 | 保留独立复核,在关键设计或完成边界安排必要检查;一行代码或配置也可能高影响 |
11
- | 风险暂不明确、反复修复无效或证据冲突 | 先补事实及定向验证;实质疑点仍在则定向独立检查,不凭自信降为低风险 |
12
-
13
- 按实际变化及其后果判断风险,不因文件位于安全模块、补一个诊断字段、发现下一处错误或完成一次复测,就新设准入和完成双重检查。阶段转换或收尾本身也不决定独立复核。已有计划或用户明确要求的门禁仍须遵循,新风险策略不能自动降级;可逆性评估实际外部后果。执行中影响扩大时重新评估。
14
-
15
- 需要独立复核且范围/授权已明确时,自动启动未参与实施或测试编写的只读 subagent 或等价复核者,不结束任务等用户再次说“复核吧”。同一授权、已审设计范围和不变量内的增量可合并检查,普通决定的文档同步由当前 AI 自查;高影响实施前门禁仍须及时满足。新增接受路径、权限、外部影响或关键假设变化时,先补事实与范围并满足适用准入,不能积压到最终复核追认。
16
-
17
- 调试时沿已知处理链提前准备必要的固定失败分类和值域,并明确输出对象/渠道、留存与清理方式,避免逐字段反复改动。只采集当前失败路径已取得的必要诊断,不为补齐信息继续执行失败后的认证步骤,不默认保存原始材料或异常全文。适用策略允许、无有效独立失败且验证充分时,既定诊断边界内不改变接受条件、控制流、响应契约或外部操作的增量由当前 AI 自验;新增隐私暴露、输出范围或共享影响则按具体风险检查。“只是诊断”及最终仍拒绝都不足以证明安全边界未变。
18
-
19
- 输入只给计划/阶段、受审 revision 与实际范围、差异、风险、可访问证据、验证命令、完成条件和授权边界;简述已有结论未覆盖的变化,合并检查给出已审基线以来的累计差异。没有新变化或证据缺口时引用有效结论,不因一次操作另开复核。用不继承完整聊天的上下文派发,必要历史按证据入口补读;若宿主只能继承历史,不把该能力局限冒充盲测或另起复制全部历史的交接文档。
5
+ ## 记录与兼容
20
6
 
21
- 独立失败、入口不可用、超时或证据冲突保持阻塞,不由实施者自批,不靠改分类/换一条安全操作放行。授权范围内可补证据和修复,未解除前不越门;等价替代者仍须满足相同独立性与证据要求。独立复核不能代替外部授权;已有授权有效时不重复索取,新的公开暴露/凭证/破坏性/隐私/合规或产品取舍按实际边界确认。
7
+ 先读取当前阶段摘要的 `复核策略`,后续复用,不由新会话或新版 skill 自动改变:
22
8
 
23
- ## Step 0 与阶段门
24
-
25
- 阶段 N 完成只关闭 N,N+1 默认设计中。每个当前阶段自身必须有目标/范围/非目标、可观察 Step 0、输入与可执行命令/预期/失败判定/输出位置的样本矩阵、验证与完成条件、失败/回滚边界、无未解决阻塞,以及适用复核通过,才可待实施。机器检查只核对结构,不证明实现、风险分类、证据真实性或用户接受。
26
-
27
- | 任务 | Step 0 |
9
+ | 策略 | 行为 |
28
10
  |---|---|
29
- | 缺陷修复 | 失败回归或最小复现 |
30
- | 迁移 | 现状快照、兼容样本或契约测试 |
31
- | 新项目 | 可执行验收 fixture、协议样本或提交图 |
32
- | 架构探索 | 最小原型、风险实验或关键假设验证 |
11
+ | 单次独立复核 | 新模板默认;普通改动自验,高风险或高影响同范围独立检查一次,修复自验 |
12
+ | 风险分流 | 旧策略;低风险自验,高影响独立,独立失败须独立通过恢复 |
13
+ | 无字段 | 保留旧独立门禁及六列记录,见旧计划兼容 |
33
14
 
34
- 不适合固定样本时记录原因和可观察的替代基线。不要在开始实现后倒填通过证据。
15
+ 空值、未知值和重复声明不能放行。有迁移授权时可显式采用单次策略并保留历史,不为切换先重审,迁移也不解决实际问题。迁移旧格式时替换摘要引用,将适用原检查按真实日期、结论、证据和身份转写成八列基线,说明范围/风险,再追加实际修复自验。旧记录冲突、缺字段或比修复更新的失败保留;不批量改其他项目。CLI 能力不符时说明缺口,更新按授权处理。
35
16
 
36
- ### 旧计划兼容
17
+ ## 按风险复核
37
18
 
38
- 摘要没有 `复核策略` 字段时,保留原独立门禁:固定 `阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录` 标题;摘要字段是 `准入状态、Step 0、样本矩阵、验证方式、失败/回滚边界、当前阻塞项、最新独立准入复核`。最新表含日期、阶段、结论、证据、复核者,当前阶段最新结论须明确通过并达到待实施标准,历史追加记录保持一致。标题不带阶段编号;地图提供阶段身份。
19
+ 以下执行方式适用于单次策略;普通无计划任务也按实际风险选择检查,不建立阶段表。
39
20
 
40
- 新会话或安装了新版 skill 不改变项目已保存的策略。接手时只核对当前计划/阶段;未采用风险分流时,核对原独立约定、有效失败和当前证据,有迁移授权并满足原门禁后,一次显式更新下述当前阶段结构、保留旧独立历史。已有授权不重复索取,未获迁移授权不自动修改;旧有效独立失败与历史冲突必须先解除,小切片通过不解除完整阶段阻塞。后续会话复用落档策略,不重复迁移、不批量重写历史计划。旧 CLI 不支持新策略时明确能力缺口,更新另按授权,不把旧检查当新能力。
21
+ 普通改动由实施者自验。改变权限、安全、隐私、资金、数据完整性、核心契约或产生广泛/难以撤销后果时,按实际高风险或高影响安排独立检查;不按目录、行数或阶段事件触发。风险不清先查事实。
41
22
 
42
- ### 新计划风险策略
23
+ 同一交付范围只检查一次,通常在实现和自验收敛后、交付或高影响外部动作前;需要设计准入时将这一次前置,后续实施与完成自验。已审范围内的增量和修复合并处理,确有新增高风险范围才另行判断,不把每个修复拆成新范围。
43
24
 
44
- 新模板在当前阶段摘要声明 `复核策略:风险分流`。这个字段缺省是上面的旧策略,空值/未知/重复不能当低风险;启用后摘要以 `最新阶段复核` 链接替代旧最新独立字段,其余基础字段保持。
25
+ 授权明确时自动安排一名未参与实现或测试编写的只读复核者,提供范围、差异、风险和证据入口。冻结受审范围并告知变化。独立者给出发现后,实施者修复并验证原问题及受影响回归,不再送审,未解决则保持未完成。检查不可用/超时直接记录状态,不能伪填已完成结论;业务缺陷描述中的“超时”不代表检查未完成。复核不代替外部授权。
45
26
 
46
- `最新阶段复核` 固定键值表:
27
+ ## Step 0 与阶段门
47
28
 
48
- | 字段 | 要求 |
49
- |---|---|
50
- | 日期 / 阶段 | YYYY-MM-DD / 与地图当前阶段一致 |
51
- | 方式 | 自验或独立 |
52
- | 风险 | 低风险、高影响或待判断;待判断不能通过,自验仅限低风险 |
53
- | 风险依据 | 实际范围、后果/可逆性、验证充分性的具体依据;非占位 |
54
- | 结论 | 尚未进行或实际结果;有效通过必须明确通过,不能以空值、失败、不可用、超时、证据冲突代替 |
55
- | 证据 / 复核者 | 可复验命令/结果或其可访问链接,以及真实执行者身份;自验不假称独立 |
29
+ 当前阶段达到待实施,需要目标与范围、可观察 Step 0、可执行样本或替代基线、验证与完成条件、失败/回滚边界、无未解决阻塞及适用复核。样本说明输入、命令、预期结果、失败判定和输出位置。上阶段通过不替代本阶段准入;普通小改不新建整套治理。
56
30
 
57
- 以 `通过 / 未通过` 等尚未选择结果的模板候选开头时,其后无论是问号、其他标点或待选说明,都属于未知,不能成为独立失败的恢复证据。结论以明确前缀声明当前结果,支持 `通过。` 等常见句末符号;`通过:已修复证据冲突` 可以通过,不因提到历史问题重判失败。无明确通过的不可用/超时/证据冲突仍为失败。实际未解决事项必须留在结构化阻塞中,通过说明不能覆盖它;机器不验证自由说明的真实性。
31
+ Step 0 可采用缺陷复现、迁移快照/兼容样本、新功能验收 fixture 或关键假设实验;不适合固定样本时说明可观察替代方案,不在实施后倒填通过证据。
58
32
 
59
- `阶段复核记录` 使用 `日期、类型、阶段、方式、风险、结论、证据、复核者` 八列表追加记录。最新当前阶段记录与最新表的日期、方式、风险、结论、证据和身份一致。最近有效独立失败不得由后续自验遮蔽;修复后由适格独立者追加通过并更新最新结论。上一阶段历史不自动阻断当前阶段。
33
+ ## 验证、修复与证据复用
60
34
 
61
- 普通无计划小改不建立这些表。可将验证命令和结果放进现有记录,通过证据列链接,避免第二份事实源。未完成的设计模板不是准入证明;不生成已通过占位。
35
+ 验证用户可观察结果和受影响回归,完成项目要求的检查。纯文档做适用文档检查并注明覆盖率不适用。检查通过后,只有新变化、失败或未解疑点才扩大或重复验证。
62
36
 
63
- 默认 check 对新准入缺陷 WARNING;待实施/实施中在 `--strict-readiness` 下 ERROR。workset 沿用 JSON schema 1 和既有动作:待自验 `verify`、高影响待独立 `independent_review`、有效通过但地图仍设计中 `sync`;失败 `blocked/resolve_blocker`,结构歧义 `unknown/unknown`,不自动写状态。hook 只提示。
37
+ 复用证据须覆盖当前工作树、依赖/配置、环境和验收契约,内容可访问;仅 HEAD/版本相同不足以证明有效。缺口补受影响验证,未解决冲突如实保留。只有状态、证据或链接同步时,不重新跑代码全套;无关任务失败如实报告,不擅自接管。
64
38
 
65
- ## 验证、修复与证据复用
39
+ 自验失败自主修复/复验。单次策略下保留独立发现,按“发现 → 修复 → 验证”闭环并准确标记自验;旧策略的恢复要求见策略表。机械检查只证明结构,不能证明风险、范围、独立性或证据真实性。可选 attestation 的显式检查见 [CLI](cli.md#初始化模板和检查脚本)。
66
40
 
67
- 先验证用户可观察结果和受影响回归;验证范围依据变更及项目要求,不为字数、字段或与实现重复的断言新增无价值测试。纯文档做适用检查并注明代码覆盖率不适用;代码变更遵循项目要求和有意义的覆盖证据。
41
+ ## 用户可观察验收与交付
68
42
 
69
- 可信全量证据只有覆盖当前实际工作树、依赖、配置、环境和验证契约,且内容可访问时才可复用。HEAD/版本相同不充分;缺失、相关变化或冲突时补验。复核者核对身份并复验关键风险,不因复用报告省略独立判断。明确过时的证据记录为当前阻塞。
43
+ 用场景、输入/操作、可见结果与证据说明完成;CLI 输出、文件差异和调用方行为也可作为验收。性能结论要有可比实测,不能用字符数或工具次数推算 token、耗时或质量改善。
70
44
 
71
- 范围快照是可选补充;`workset` 不自动核对文件 hash 或环境变化。采用 attestation 时按 [CLI 说明](cli.md) 显式运行 `check --check-attestations --strict-readiness`,不能声称所有准入都已检查证据漂移。
45
+ 明确采用用户体验闭环的功能计划,技术完成待用户查看时保持 `实施中`,结构化 `下一动作` 填 `等待用户验收`;用户接受后才关闭,技术通过、提交或沉默不代替接受。普通小改、纯落档不增加逐次签收。原范围问题自主修复,新需求另行归属;等待用户才能提供的结果时可继续无依赖工作。
72
46
 
73
- 自验失败由实施 AI 自主修复、复验。独立失败后的重审聚焦原阻塞、修复差异及受影响回归,引用仍有效的证据;不因一处修复无理由重跑整套历史,也不把共享调用变化当成无影响。相同未修正阻塞不重复送审。
47
+ 交付简报完成结果、必要验证、剩余阻塞及证据入口,不复制完整日志。资料不可访问时补可复验要点;记录同步不再安排复核。
74
48
 
75
- 每个必要复核点默认一名主复核者,仅对具体且独立的专项风险增加协作者,不把文档生产助手全部算作独立复核。适用时合并同范围行为后测与完成复核:检查者未参与实现/测试编写,先给任务输入,完成后再给预期对照;行为判断和机械测试分别记录。受审范围冻结后,等待期间可做无依赖的已授权工作;相关变化需通知复核者,不以未完成结果推进依赖项。使用有界等待,避免密集轮询;并行工时不能相加冒充关键路径时长。
49
+ ## 格式附录:写入阶段记录时读取
76
50
 
77
- 送审时用简短说明区分当前交付、后续事项和通过后的记录同步。独立者依据当前已确认范围、实际证据及原失败原因先给出结论,不要求“本次通过记录已存在”才能完成本次判断。旧有效失败仍须由适格独立者明确判断是否解除;范围调整不自动消除失败,也不让未准入的后续事项自动阻断当前交付。
51
+ ### 新计划风险策略
78
52
 
79
- 执行者只准确转写独立结论、追加历史并同步地图,不预填通过或自行改判。涉及未来事项时按 planning 核对承接及当前安全边界;资料不足则具体指出哪个当前完成条件缺什么证据,不以“尚未落档本次结论”替代缺陷说明。
53
+ 显式策略在摘要以 `最新阶段复核` 引用替代旧 `最新独立准入复核`,其余阶段字段保留。最新表采用两列字段/内容:
80
54
 
81
- 验证后仅追加状态/证据或修正文档链接时,做适用文档检查即可;契约、源、依赖或环境又变则补受影响验证。区分仓库源与安装版本、旧缺陷与新回归、当前范围与其他并行任务失败;如实报告全仓失败,不能用局部通过掩盖,也不擅自接管无关任务。
55
+ | 字段 | 要求 |
56
+ |---|---|
57
+ | 日期 / 阶段 | YYYY-MM-DD / 与地图当前阶段一致 |
58
+ | 方式 / 风险 | 自验或独立;低风险、高影响或待判断,单次策略另支持高风险 |
59
+ | 风险依据 | 当前实际范围、后果与验证依据 |
60
+ | 结论 | 尚未进行或明确结果;待判断风险不能通过,候选、疑问或占位不算通过 |
61
+ | 证据 / 复核者 | 可复验记录或链接 / 真实执行者身份 |
82
62
 
83
- ## 用户可观察验收与交付
63
+ `阶段复核记录` 按 `日期、类型、阶段、方式、风险、结论、证据、复核者` 八列追加,日期顺序和最新表与当前阶段末条一致。完整结果须有有效日期、证据、身份及已判断风险;普通无计划任务无需建表。
84
64
 
85
- 验收关联到场景、输入/前置、操作、可观察结果和证据;CLI 输出/文件差异/调用方行为同样可观察,不强求界面或资源采样。需要性能验收时沿用探索确定的可比环境、负载和窗口;未实际测量不得宣称性能改善。
65
+ 单次策略的高风险/高影响自验须有本阶段同范围完整独立基线。独立发现修复后用类型 `修复自验`、方式 `自验` 追加,证据说明原发现与修复回归,不能以普通自验覆盖未修复发现。自验不伪称独立通过。旧风险分流自验仅限低风险;旧独立失败按原策略恢复。上一阶段历史不自动阻断当前阶段。
86
66
 
87
- 采用用户最终体验闭环的功能计划:AI 先技术和运行验证,提供可复验结果;技术完成但待用户查看/操作时保持 `实施中`,最近记录注明待验收项,结构化 `下一动作:等待用户验收`。workset 返回已有 `none` 并明确等待原因,不关闭计划。用户明确接受后才已完成;技术通过、提交请求或沉默都不是产品接受。普通小改、纯落档不增加逐次签收。
67
+ 结论以明确前缀记录:`通过`、`未通过`等;复核入口不可用/超时直接写其状态,实际查出的证据冲突可作为发现。通过说明不能覆盖结构化未解决事项。check 默认对新准入缺陷 WARNING,待实施/实施中在 `--strict-readiness` 下 ERROR。workset 保持 schema 1:待自验 `verify`、待独立 `independent_review`、通过待地图同步 `sync`、失败 `blocked/resolve_blocker`、歧义 `unknown/unknown`;不自动写状态,hook 只提示。
88
68
 
89
- 原验收未满足或原范围小问题自主修复/复验并交付结果;新需求或实质取舍另行归属,需用户才能提供的验收结果保持待答,可继续不依赖它的授权工作。
69
+ ### 旧计划兼容
90
70
 
91
- 交接简报结果、阻塞、验证命令及范围/环境、可访问证据入口和下一动作即可;不粘贴完整日志,不为每次动作新建报告。仅工具 ID 无法被接手者访问时,提供实际要点和复验命令。对减负效果用少量同完成条件任务比较必要读取、全量验证/复核次数和实耗;保留质量反例。没有可靠宿主统计不估算 token 占比,文件字节/行数或工具次数不代替 token 和耗时。
71
+ 没有策略字段时,保留固定标题 `阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录`。摘要字段为准入状态、Step 0、样本矩阵、验证方式、失败/回滚边界、当前阻塞项及最新独立准入复核。最新表含日期、阶段、结论、证据、复核者;历史使用日期、类型、阶段、结论、证据、复核者六列,当前阶段最新结论须独立通过且与历史一致。标题不加阶段编号,阶段身份以地图为准。
@@ -226,8 +226,10 @@ def risk_review_state(plan_text, phase):
226
226
  if not policies:
227
227
  return result
228
228
  issues, blockers = result["issues"], result["blockers"]
229
- if len(policies) != 1 or len(policies[0]) != 2 or policies[0][1] != "风险分流":
230
- issues.append("复核策略必须唯一且为 风险分流;空值、未知值或重复声明不能准入")
229
+ single_review = len(policies) == 1 and len(policies[0]) == 2 and policies[0][1] == "单次独立复核"
230
+ if len(policies) != 1 or len(policies[0]) != 2 or policies[0][1] not in {"风险分流", "单次独立复核"}:
231
+ issues.append("复核策略必须唯一且为 风险分流/单次独立复核;空值、未知值或重复声明不能准入")
232
+ risks = {"低风险", "高影响"} | ({"高风险"} if single_review else set())
231
233
  summary = key_value_table(summary_section)
232
234
  if "最新独立准入复核" in summary:
233
235
  issues.append("风险分流的阶段准入摘要应以 最新阶段复核 替代 最新独立准入复核")
@@ -245,11 +247,11 @@ def risk_review_state(plan_text, phase):
245
247
  issues.append(f"最新阶段复核阶段与 PLAN_MAP 当前阶段 {phase} 不一致")
246
248
  if review.get("方式") not in {"自验", "独立"}:
247
249
  issues.append("最新阶段复核方式必须为 自验/独立")
248
- if review.get("风险") not in {"低风险", "高影响", "待判断"}:
249
- issues.append("最新阶段复核风险必须为 低风险/高影响/待判断")
250
+ if review.get("风险") not in risks | {"待判断"}:
251
+ issues.append("最新阶段复核风险必须为 " + "/".join(sorted(risks)) + "/待判断")
250
252
  if review.get("风险") == "待判断":
251
253
  issues.append("最新阶段复核风险待判断,不能准入")
252
- if review.get("方式") == "自验" and review.get("风险") != "低风险":
254
+ if not single_review and review.get("方式") == "自验" and review.get("风险") != "低风险":
253
255
  issues.append("自验只适用于低风险,不能代替高影响独立复核")
254
256
  if is_placeholder(review.get("风险依据")):
255
257
  issues.append("最新阶段复核风险依据为空或占位")
@@ -267,10 +269,19 @@ def risk_review_state(plan_text, phase):
267
269
  return None
268
270
 
269
271
  def qualified(row, legacy=False):
270
- # 仅完整的独立通过可以解除先前独立失败;失败记录即使材料残缺也保留。
272
+ # 独立基线须有完整身份和证据;记录的结论另行判断。
271
273
  return (len(row) == (6 if legacy else 8) and not any(is_placeholder(value) for value in row)
272
274
  and valid_date(row[0]) is not None
273
- and (legacy or (row[3] == "独立" and row[4] in {"低风险", "高影响"})))
275
+ and (legacy or (row[3] == "独立" and row[4] in risks)))
276
+
277
+ def completed(row):
278
+ # 明确的通过/缺陷结论代表已完成检查;不扫描业务发现中的状态词。
279
+ conclusion = row[5].strip()
280
+ return qualified(row) and (
281
+ review_outcome(conclusion) == "passed" or
282
+ conclusion.startswith(("未通过", "不通过", "失败", "不满足", "拒绝", "证据冲突"))
283
+ and review_outcome(conclusion) == "failed"
284
+ )
274
285
 
275
286
  known_phases = {row[0] for row in phase_roadmap_rows(plan_text)}
276
287
 
@@ -312,11 +323,38 @@ def risk_review_state(plan_text, phase):
312
323
  return current
313
324
 
314
325
  history = current_history("阶段复核记录", 8)
326
+ reviewed = False
327
+ reviewed_high = False
328
+ repair_date = None
329
+ unresolved_single = None
315
330
  for row in history:
316
- if row[3] not in {"自验", "独立"} or row[4] not in {"低风险", "高影响", "待判断"}:
331
+ if row[3] not in {"自验", "独立"} or row[4] not in risks | {"待判断"}:
317
332
  issues.append("阶段复核记录方式或风险未知")
318
- if row[3] == "自验" and row[4] != "低风险":
333
+ if not single_review and row[3] == "自验" and row[4] != "低风险":
319
334
  issues.append("阶段复核记录自验只适用于低风险")
335
+ if single_review:
336
+ if row[3] == "独立":
337
+ if completed(row):
338
+ reviewed = True
339
+ reviewed_high = row[4] in {"高风险", "高影响"}
340
+ else:
341
+ reviewed = reviewed_high = False
342
+ if review_outcome(row[5]) == "failed":
343
+ unresolved_single = row[5]
344
+ elif review_outcome(row[5]) == "passed" and completed(row):
345
+ unresolved_single = None
346
+ repair_date = valid_date(row[0])
347
+ elif row[3] == "自验":
348
+ if row[4] in {"高风险", "高影响"} and not reviewed_high:
349
+ issues.append("高风险/高影响自验缺少本阶段已完成的独立复核基线")
350
+ if row[1] == "修复自验":
351
+ if not reviewed:
352
+ issues.append("修复自验缺少已完成的独立复核基线")
353
+ elif (review_outcome(row[5]) == "passed" and row[4] in risks
354
+ and not any(is_placeholder(value) for value in row)
355
+ and valid_date(row[0]) is not None):
356
+ unresolved_single = None
357
+ repair_date = valid_date(row[0])
320
358
  if review_outcome(row[5]) == "unknown":
321
359
  issues.append("阶段复核记录结论为空或未知")
322
360
  if review_outcome(row[5]) == "passed" and (
@@ -339,7 +377,7 @@ def risk_review_state(plan_text, phase):
339
377
  if (outcome == "passed" or not is_placeholder(review.get("日期"))) and valid_date(review.get("日期", "")) is None:
340
378
  issues.append("最新阶段复核日期不合法")
341
379
 
342
- independent = [row for row in history if row[3] == "独立"]
380
+ independent = [row for row in history if row[3] == "独立"] if not single_review else []
343
381
  unresolved = None
344
382
  for row in independent:
345
383
  row_outcome = review_outcome(row[5])
@@ -349,6 +387,8 @@ def risk_review_state(plan_text, phase):
349
387
  unresolved = None
350
388
  if unresolved:
351
389
  blockers.append("阶段复核记录存在未解除的独立失败:" + unresolved)
390
+ if single_review and unresolved_single:
391
+ blockers.append("阶段复核记录存在未修复的独立发现:" + unresolved_single)
352
392
 
353
393
  # 旧独立记录仍是独立事实源;完成失败也不能被新自验覆盖。
354
394
  legacy_history = current_history("独立复核记录", 6)
@@ -370,6 +410,8 @@ def risk_review_state(plan_text, phase):
370
410
  unresolved = None
371
411
  for row in legacy_history:
372
412
  row_outcome = review_outcome(row[3])
413
+ if single_review and not qualified(row, legacy=True):
414
+ issues.append("旧独立复核记录缺少有效日期、类型、证据或身份,迁移不能掩盖")
373
415
  if row_outcome == "failed":
374
416
  unresolved = row[3]
375
417
  elif row_outcome == "passed" and qualified(row, legacy=True):
@@ -378,10 +420,15 @@ def risk_review_state(plan_text, phase):
378
420
  issues.append("旧独立通过记录缺少有效日期、类型、证据或身份")
379
421
  elif row_outcome == "unknown":
380
422
  issues.append("旧独立复核记录结论为空或未知")
381
- if unresolved:
423
+ # 显式迁移后保留旧结论;新记录中的有效修复自验可解除旧发现。
424
+ legacy_dates = [valid_date(row[0]) for row in legacy_history]
425
+ legacy_repaired = (single_review and repair_date is not None and bool(legacy_dates)
426
+ and all(date is not None and date <= repair_date for date in legacy_dates)
427
+ and not unresolved_single)
428
+ if unresolved and not legacy_repaired:
382
429
  blockers.append("旧独立复核记录存在未解除的失败:" + unresolved)
383
430
  if legacy_current:
384
- if review_outcome(legacy.get("结论", "")) == "failed":
431
+ if review_outcome(legacy.get("结论", "")) == "failed" and not legacy_repaired:
385
432
  blockers.append("最新独立准入复核:" + legacy["结论"])
386
433
  elif not legacy_history or any(is_placeholder(legacy.get(field))
387
434
  for field in ["日期", "阶段", "结论", "证据", "复核者"]) or valid_date(legacy.get("日期", "")) is None:
@@ -54,14 +54,14 @@ def init_git(root):
54
54
  def agent_rules_body():
55
55
  return """## 计划治理
56
56
 
57
- 本项目使用轻量计划治理。处理治理任务前,先读取当前环境发现的已安装 `plan-governance` skill 的 SKILL.md,并按任务读取其同源 references;不要假定用户安装目录。
57
+ 本项目使用轻量计划治理。处理已有计划或需要持续协调的工作时,读取实际发现的 `plan-governance` skill;开发或审查该 skill 自身时使用仓库源及对应 CLI。规范来源一次选定后复用,按当前动作读取同源 references。
58
58
 
59
59
  只有 CLI 可用时,运行 `plan-governance-cli guide` 读取入口,再按需运行 `guide planning`、`guide verification` 或 `guide cli`。两者均不可用或所需能力缺失时说明前提,不自动安装,也不猜测/拼接不同版本的规则。
60
60
 
61
61
  最小执行边界:
62
62
 
63
- - 普通无计划覆盖的小改不强制治理;低风险且范围、后果与验证明确时由当前 AI 自验,高影响及有效独立失败按共享 verification 规范处理。已有计划未显式选择风险策略时保持原独立门禁。
64
- - 只实施已授权、已准入的当前阶段。每个阶段有自身 Step 0、验证/完成和失败边界;失败、不可用或证据冲突不能自批。已有授权不重复索取,新增高影响外部动作按实际授权处理。
63
+ - 普通一次性任务直接处理;已有计划先确定当前有效策略,再按共享 verification 验证。单次策略下高风险或高影响同范围独立复核一次,修复后自验。
64
+ - 只实施已授权、已准入的当前阶段。每个阶段有自身 Step 0、验证/完成和失败边界;未解决问题不能记为完成,不可用或超时不能冒充已检查。已有授权不重复索取,新增高影响外部动作按实际授权处理。
65
65
  - 首次读取 `docs/PLAN_MAP.md`、当前相关 `docs/plans/*.md` 及适用契约/ADR/migration;恢复先核对当前工作集、最近证据和实际 diff,缺失或冲突再展开。
66
66
  - 地图维护状态、阶段、关系、阻塞与证据入口;计划记录本次差异及验证,现行契约优先复用 Schema/OpenAPI。新事实不写回历史草案,变化同步地图及相关引用。
67
67
  - 完成时按共享规范记录实际验证与适用用户验收,运行 `plan-governance-cli check .`;准入/CI/发布显式使用 `--strict-readiness`,机械通过不等于业务验收。