plan-governance-cli 0.2.3 → 0.2.4

package/README.md

@@ -21,6 +21,12 @@
 - 互不依赖的待办列表。
 - 不影响公共契约的普通实现任务。
 
+## 需求探索与 grilling
+
+对可能进入治理、但目标、边界、验收或关键取舍尚未收敛的任务，`plan-governance` 会优先使用可用的 `grill-me` 进行需求探索：高影响事项存在关键不明确内容时触发，或同时存在至少两项需求不确定性信号时触发。每次只推进一个问题；可从仓库和工具查证的事实先查证，决策由用户确认。
+
+结束时应由用户确认结构化总结：目标、范围和非目标、已确认事实、暂定假设、候选方案、未决问题和下一步验证。只有需要治理的任务才把该摘要写入专项计划的 `需求探索` 章节；它不替代 Step 0 或阶段准入，也不会自动生成 ADR。未安装 `grill-me` 时保持在澄清/设计边界，不伪造访谈完成。
+
 ## 文档结构
 
 最小结构：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "统一入口的计划治理检查 CLI",
   "private": false,
   "type": "module",

package/resources/skill/SKILL.md

@@ -24,6 +24,19 @@ description: 轻量计划治理工作流。Use when 用户要求管理路线图
 - `<=1`：按普通任务处理。
 - 大型公共契约迁移可以直接启用治理。
 
+## 需求探索与 grilling
+
+对可能进入治理的任务，如果运行环境声明 `grill-me` 可用，满足下列任一条件时自动调用它，在实施或冻结详细方案前先澄清需求：
+
+1. 涉及公共 API、Schema、迁移、兼容性或不可逆操作，且目标、边界、验收或关键取舍中至少一项未明确；
+2. 下列不确定性信号中至少两项同时存在：目标/验收不清、范围/非目标不清、存在多个有实质取舍的方案、关键事实尚待查证、后续返工成本显著。
+
+目标、影响范围和验收方式均明确的小范围任务，以及当前阶段已通过准入且已确认假设没有变化的工作，跳过自动 grilling；用户仍可显式调用它。
+
+grilling 每次只问一个问题。可从仓库、环境或工具确认的事实必须先查证；产品取舍、外部承诺和不可逆选择由用户确认。结束前必须汇总并得到用户确认：目标、范围和非目标、已确认事实、暂定假设及验证方式、候选方案与取舍、未决问题及阻塞级别，以及验收口径或下一步动作。
+
+用户确认后，只有在任务需要治理时，才把结构化结论写入专项计划的 `需求探索` 章节；不保存完整访谈逐字稿，不自动创建 ADR。探索结论不替代当前阶段的 Step 0、样本矩阵、验证方式、失败/回滚边界或独立准入复核。`grill-me` 不可用时，说明依赖不可用并保持在澄清/设计边界，不得伪造已完成 grilling 或静默实施。
+
 ## 仓库模型
 
 使用项目内这些文件作为事实来源：
@@ -120,18 +133,19 @@ docs/
 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. 实施前让当前阶段可执行：
+5. 对需求尚未收敛且满足触发条件的任务，先执行 grilling；在用户确认结构化总结前，不实施也不把暂定内容写成规范事实。
+6. 实施前让当前阶段可执行：
    - 目标、范围、非目标明确
    - 必要的不变量和信任边界明确
    - 必要的公共契约和失败策略明确
    - Step 0 证据存在
    - 验证方式可运行
    - 当前阶段没有未解决阻塞项
-6. 只实施当前阶段。后续阶段保持粗粒度。
-7. 新信息改变假设时，先更新 `PLAN_MAP.md` 和相关计划，再继续实施；计划被推进、恢复、暂停或复核时同步 `最后更新`。
-8. 完成时记录验证证据、测试覆盖率证据并更新状态。
-9. 验收治理文档时先做独立复核和反向引用检查：不得仅依据计划状态、完成证据文字或文档格式判定完成；必须核对当前仓库内容、可复现验证命令、测试或 CI 输出、覆盖率证据，以及用 `rg` 搜索同名计划、P 编号、状态名、关键字段和 `草案为准|以草案为事实源|详见草案|draft is source|source of truth.*draft|以.*draft.*为准`，确认所有路线图、优先级计划和索引已经同步，且旧草案没有重新成为事实源。
-10. 运行 `plan-governance-cli check`；如果项目仍保留旧脚本，只把它作为回滚或对照，不作为新的分发源。需要检查活跃计划停滞时运行 `--stale-days`，默认 10 天。
+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 天。
 
 ## Step 0 证据
 

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

@@ -1,32 +1,62 @@
-# 计划：<name>
+# 计划：{{title}}
 
 ## 背景
 
+待补充。
+
 ## 目标
 
+{{goal}}
+
 ## 非目标
 
+- 待补充。
+
+<!-- 仅在触发 grilling 且用户确认结构化结论后保留本节；否则删除本节和本注释。 -->
+## 需求探索
+
+### 已确认事实
+
+### 暂定假设与验证方式
+
+### 范围与非目标
+
+### 候选方案与取舍
+
+### 未决问题
+
+### 用户确认的探索结论
+
 ## 不变量
 
+- 当前阶段写细，后续阶段写粗。
+- 完成时必须记录可验证证据。
+
 ## 影响模块或文件
 
+- 待补充。
+
 ## 公共契约变化
 
+待确认。若涉及 API、Schema、兼容性或迁移行为，需要在这里明确。
+
 ## 阶段路线图
 
 | 阶段 | 目标 | 进入条件 | 验证方向 | 状态 |
 |---|---|---|---|---|
-| 阶段 0 | 建立基线 | - | Step 0 证据存在 | 设计中 |
+| {{phase}} | 建立当前阶段基线 | 治理文档已初始化 | Step 0 证据存在 | {{status}} |
 
 ## 当前阶段
 
 ### 范围
 
+待补充。
+
 ### 阶段准入摘要
 
 | 字段 | 内容 |
 |---|---|
-| 准入状态 | 设计中 |
+| 准入状态 | {{status}} |
 | Step 0 | 当前阶段 Step 0 证据的链接或锚点 |
 | 样本矩阵 | 样本/fixture 或替代基线的链接或锚点 |
 | 验证方式 | 可执行命令和输出位置的链接或锚点 |
@@ -36,21 +66,29 @@
 
 ### 实施步骤
 
-1.
+1. 补充 Step 0 证据。
+2. 明确当前阶段完成条件。
+3. 实施当前阶段。
+4. 运行验证并记录证据。
 
 ### Step 0 证据
 
+待补充。实施前需要记录失败测试、最小复现、现状快照、兼容样本、fixture 或关键假设验证。
+
 ### 验证方式
 
+待补充。
 ### 测试覆盖率
 
 待补充。完成后需要记录测试覆盖率报告，例如 pytest-cov 输出、覆盖率百分比、关键模块覆盖情况等。
 
 ### 完成条件
 
-## 独立复核记录
+- Step 0 证据已记录。
+- 当前阶段验证通过。
+- `docs/PLAN_MAP.md` 状态和证据已同步。
 
-### 最新独立准入复核
+## 最新独立准入复核
 
 | 字段 | 内容 |
 |---|---|
@@ -60,7 +98,7 @@
 | 证据 | 命令、样本或 CI 链接 |
 | 复核者 | 姓名或 Agent |
 
-### 历史记录
+## 独立复核记录
 
 | 日期 | 类型 | 阶段 | 结论 | 证据 | 复核者 |
 |---|---|---|---|---|---|
@@ -70,10 +108,12 @@
 
 | 问题 | 推荐方案 | 是否阻塞当前阶段 | 状态 |
 |---|---|---|---|
-| - | - | 否 | 已延后 |
+| 当前阶段 Step 0 证据是什么？ | 在实施前补充最小可观察基线。 | 是 | 待确认 |
 
 ## 风险和回滚
 
+待补充。
+
 ## 关联 ADR、迁移、spec 或 issue
 
 -

package/scripts/init_plan_governance.py

@@ -63,6 +63,13 @@ def agent_rules_body():
 - 相关 `docs/adr/*.md`
 - 相关 `docs/migrations/*.md`
 
+需求探索与 grilling：
+
+- 对可能进入治理的任务，若 `grill-me` 可用，遇到高影响事项且目标/边界/验收/取舍未明确，或同时存在至少两项需求不确定性信号时，先执行 grilling。
+- grilling 每次只问一个问题；可由仓库、环境或工具确认的事实先自行查证，产品取舍和不可逆选择由用户确认。
+- 在用户确认结构化总结前不得实施或把暂定内容写成规范事实。确认后，只把已确认事实、暂定假设、范围/非目标、候选方案、未决问题和探索结论写入专项计划的 `需求探索` 章节。
+- grilling 不替代 Step 0、样本矩阵、验证、失败/回滚边界或独立准入复核；`grill-me` 不可用时说明依赖不可用并保持在澄清/设计边界，不得伪造已完成 grilling。
+
 事实源规则：
 
 - 专项计划是实施细节事实源，记录字段方案、Schema、枚举、Step 0 证据、验证方式和完成条件。
@@ -239,116 +246,19 @@ def plan_map_content(plan_slug, title, status, phase):
 """
 
 
-def plan_content(plan_slug, title, status, phase, goal):
-    goal_text = goal or "待补充。"
-    return f"""# 计划：{title}
-
-## 背景
-
-待补充。
-
-## 目标
-
-{goal_text}
-
-## 非目标
-
-- 待补充。
-
-## 不变量
-
-- 当前阶段写细，后续阶段写粗。
-- 完成时必须记录可验证证据。
-
-## 影响模块或文件
-
-- 待补充。
-
-## 公共契约变化
-
-待确认。若涉及 API、Schema、兼容性或迁移行为，需要在这里明确。
-
-## 阶段路线图
-
-| 阶段 | 目标 | 进入条件 | 验证方向 | 状态 |
-|---|---|---|---|---|
-| {phase} | 建立当前阶段基线 | 治理文档已初始化 | Step 0 证据存在 | {status} |
-
-## 当前阶段
-
-### 范围
-
-待补充。
-
-### 阶段准入摘要
-
-| 字段 | 内容 |
-|---|---|
-| 准入状态 | {status} |
-| Step 0 | 当前阶段 Step 0 证据的链接或锚点 |
-| 样本矩阵 | 样本/fixture 或替代基线的链接或锚点 |
-| 验证方式 | 可执行命令和输出位置的链接或锚点 |
-| 失败/回滚边界 | 失败判定和安全边界的链接或锚点 |
-| 当前阻塞项 | 无，或指向未决问题表中的具体行 |
-| 最新独立准入复核 | 尚未进行 |
-
-### 实施步骤
+def plan_template_path():
+    return Path(__file__).resolve().parents[1] / "resources" / "skill" / "assets" / "plan.template.md"
 
-1. 补充 Step 0 证据。
-2. 明确当前阶段完成条件。
-3. 实施当前阶段。
-4. 运行验证并记录证据。
 
-### Step 0 证据
-
-待补充。实施前需要记录失败测试、最小复现、现状快照、兼容样本、fixture 或关键假设验证。
-
-### 验证方式
-
-待补充。
-
-### 测试覆盖率
-
-待补充。完成后需要记录测试覆盖率报告，例如 pytest-cov 输出、覆盖率百分比、关键模块覆盖情况等。
-
-### 完成条件
-
-- Step 0 证据已记录。
-- 当前阶段验证通过。
-- `docs/PLAN_MAP.md` 状态和证据已同步。
-
-## 独立复核记录
-
-### 最新独立准入复核
-
-| 字段 | 内容 |
-|---|---|
-| 日期 | 待补充 |
-| 阶段 | 由 `PLAN_MAP.md` 当前阶段确定 |
-| 结论 | 通过 / 未通过 |
-| 证据 | 命令、样本或 CI 链接 |
-| 复核者 | 姓名或 Agent |
-
-### 历史记录
-
-| 日期 | 类型 | 阶段 | 结论 | 证据 | 复核者 |
-|---|---|---|---|---|---|
-| - | - | - | - | - | - |
-
-## 未决问题
-
-| 问题 | 推荐方案 | 是否阻塞当前阶段 | 状态 |
-|---|---|---|---|
-| 当前阶段 Step 0 证据是什么？ | 在实施前补充最小可观察基线。 | 是 | 待确认 |
-
-## 风险和回滚
-
-待补充。
-
-## 关联 ADR、迁移、spec 或 issue
-
-- 
-"""
+def plan_content(plan_slug, title, status, phase, goal):
+    goal_text = goal or "待补充。"
+    template = plan_template_path().read_text(encoding="utf-8")
+    return (
+        template.replace("{{title}}", title)
+        .replace("{{goal}}", goal_text)
+        .replace("{{status}}", status)
+        .replace("{{phase}}", phase)
+    )
 
 
 def copy_checker(root, force):