plan-governance-cli 0.2.2 → 0.2.4

package/README.md

@@ -21,6 +21,12 @@
 - 互不依赖的待办列表。
 - 不影响公共契约的普通实现任务。
 
+## 需求探索与 grilling
+
+对可能进入治理、但目标、边界、验收或关键取舍尚未收敛的任务，`plan-governance` 会优先使用可用的 `grill-me` 进行需求探索：高影响事项存在关键不明确内容时触发，或同时存在至少两项需求不确定性信号时触发。每次只推进一个问题；可从仓库和工具查证的事实先查证，决策由用户确认。
+
+结束时应由用户确认结构化总结：目标、范围和非目标、已确认事实、暂定假设、候选方案、未决问题和下一步验证。只有需要治理的任务才把该摘要写入专项计划的 `需求探索` 章节；它不替代 Step 0 或阶段准入，也不会自动生成 ADR。未安装 `grill-me` 时保持在澄清/设计边界，不伪造访谈完成。
+
 ## 文档结构
 
 最小结构：
@@ -74,26 +80,28 @@ docs/
 在目标项目根目录运行：
 
 ```bash
-python3 scripts/init_plan_governance.py \
+plan-governance-cli init \
   --root . \
   --plan api-compat-migration \
   --title "API 兼容性迁移" \
   --goal "分阶段完成 API 兼容性迁移" \
-  --copy-checker \
   --update-agent-rules
 ```
 
+如尚未安装 CLI，先运行 `npm install -g plan-governance-cli`。初始化默认只创建治理文档和代理规则，不复制项目本地检查器。
+
 这会创建：
 
 ```text
 .git/
 docs/PLAN_MAP.md
 docs/plans/api-compat-migration.md
-scripts/check_plan_governance.py
 CLAUDE.md
 AGENTS.md
 ```
 
+其中检查器是 npm 包的内部运行资源；正常使用不需要在目标项目中创建 `scripts/check_plan_governance.py`。
+
 如果目标目录还不是 Git 仓库，初始化流程会先执行 `git init`；已有 `.git/` 时会跳过，不重复初始化。
 
 `--update-agent-rules` 会创建或更新 `CLAUDE.md` 和 `AGENTS.md` 中带标记的计划治理章节，只写稳定执行规则，不写具体计划内容。具体计划仍以 `docs/PLAN_MAP.md` 和 `docs/plans/*.md` 为准。
@@ -116,7 +124,7 @@ AGENTS.md
 如果项目已经有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`，不要重新初始化计划文档。只更新代理执行规则时运行：
 
 ```bash
-python3 scripts/init_plan_governance.py \
+plan-governance-cli init \
   --root . \
   --update-agent-rules-only
 ```
@@ -126,52 +134,54 @@ python3 scripts/init_plan_governance.py \
 如果要升级已有项目的辅助文件，刷新检查脚本并更新代理规则，但不覆盖 `docs/`，运行：
 
 ```bash
-python3 scripts/init_plan_governance.py \
+plan-governance-cli init \
   --root . \
   --upgrade-existing
 ```
 
 `--upgrade-existing` 会：
 
-- 覆盖更新 `scripts/check_plan_governance.py`
+- 按兼容模式覆盖更新项目中的 `scripts/check_plan_governance.py`
 - 创建或更新 `CLAUDE.md` 和 `AGENTS.md` 中带标记的计划治理章节
 - 保留已有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`
 - 提示缺失的治理文档
 
+新项目和日常升级不需要使用该兼容模式；优先使用全局 npm CLI。
+
 ## 检查
 
 在仓库根目录运行：
 
 ```bash
-python3 scripts/check_plan_governance.py .
+plan-governance-cli check .
 ```
 
 可选检查：
 
 ```bash
-python3 scripts/check_plan_governance.py . --drift
-python3 scripts/check_plan_governance.py . --pre-commit
-python3 scripts/check_plan_governance.py . --stale-days 10
+plan-governance-cli check . --drift
+plan-governance-cli check . --pre-commit
+plan-governance-cli check . --stale-days 10
 ```
 
 `--drift` 会检查工作区变更是否被活跃计划的 `影响模块或文件` 覆盖；`--pre-commit` 会检查 staged 变更，便于用户手动接入 Git hook。两者只输出 `WARNING`，不改变退出码。
 
-如果已安装统一 npm CLI，可用全局入口运行同一套检查器：
+全局 CLI 是推荐入口：
 
 ```bash
 npm install -g plan-governance-cli
-plan-governance-cli . --strict-readiness
+plan-governance-cli check . --strict-readiness
 ```
 
 也可以不全局安装，直接使用锁定版本：
 
 ```bash
-npx --yes --package plan-governance-cli@0.2.2 plan-governance-cli . --strict-readiness
+npx --yes --package plan-governance-cli@0.2.3 plan-governance-cli check . --strict-readiness
 ```
 
-npm CLI 只是统一入口，实际检查逻辑仍由包内版本化的 Python 检查器执行；迁移期间项目原有 Python 命令仍可作为回滚路径。
+npm 包内部仍使用版本化的 Python 检查器，但用户不需要直接调用或复制该脚本。旧项目已有本地脚本时仍可保留作为兼容或回滚路径。
 
-作用域匹配规则同样用于 `plan_governance_hook.py --event pre-write`：
+作用域匹配规则同样用于 `plan-governance-cli hook --event pre-write`：
 
 - 优先提取列表项中的第一个反引号路径，例如 ``- `./scripts/`: 检查脚本``。
 - 没有反引号时提取列表项的第一个纯文本 token，例如 `- README.md`。
@@ -204,10 +214,10 @@ plan-governance-cli init --root . --plan api-compat-migration --title "API 兼
 本仓库提供只读 hook runtime，供 Codex、Claude Code 或其他 Agent 的项目级 hooks 手动接入。脚本只输出短提示和检查结果，不修改治理文档，不更新 `最后更新`，不安装或修改全局配置。
 
 ```bash
-python3 scripts/plan_governance_hook.py --event session-start
-python3 scripts/plan_governance_hook.py --event pre-write --paths scripts/check_plan_governance.py
-python3 scripts/plan_governance_hook.py --event post-write --paths docs/PLAN_MAP.md
-python3 scripts/plan_governance_hook.py --event stop
+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
 ```
 
 事件语义：
@@ -215,12 +225,12 @@ python3 scripts/plan_governance_hook.py --event stop
 - `session-start`：摘要活跃计划、当前阶段、最后更新、阻塞项和证据链接。
 - `pre-write`：按活跃计划的 `影响模块或文件` 匹配路径，提示当前阶段门禁。
 - `post-write`：写入 `PLAN_MAP.md` 或计划文档后，提示同步状态、证据、覆盖率和反向引用检查。
-- `stop`：运行 `python3 scripts/check_plan_governance.py .` 并转发结果；该事件是非阻塞提示，不实现强制 gate。
+- `stop`：运行 `plan-governance-cli check .` 并转发结果；该事件是非阻塞提示，不实现强制 gate。
 
 旧项目如果仍使用五列 `PLAN_MAP.md`，先显式迁移：
 
 ```bash
-python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated --last-updated-date 2026-07-05
+plan-governance-cli init --root . --migrate-plan-map-last-updated --last-updated-date 2026-07-05
 ```
 
 不传 `--last-updated-date` 时使用当天日期。该迁移只修改 `docs/PLAN_MAP.md` 的计划索引表，不会自动改变计划状态。
@@ -249,8 +259,8 @@ python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated
 已完成计划可以显式创建完成快照，用于后续发现未复核修改。快照文件写入 `docs/attestations/<plan-name>.json`，包含计划文件和 `docs/PLAN_MAP.md` 的 SHA-256。
 
 ```bash
-python3 scripts/check_plan_governance.py . --attest agent-runtime-integration
-python3 scripts/check_plan_governance.py . --check-attestations
+plan-governance-cli check . --attest agent-runtime-integration
+plan-governance-cli check . --check-attestations
 ```
 
 `--attest <plan-name>` 只接受已登记到 `docs/PLAN_MAP.md` 的计划。`--check-attestations` 对计划文件 hash 变化、`PLAN_MAP.md` hash 变化、JSON 损坏、文件缺失或快照引用未登记计划输出 `WARNING`，不改变退出码。人工确认文档修正合理后，可以重新运行 `--attest <plan-name>` 覆盖快照。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "0.2.2",
+  "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 证据、验证方式和完成条件。
@@ -110,11 +117,11 @@ def agent_rules_body():
 8. 完成后运行：
 
    ```bash
-   python3 scripts/check_plan_governance.py .
+   plan-governance-cli check .
    ```
 
-9. 如需检查活跃计划停滞，运行 `python3 scripts/check_plan_governance.py . --stale-days`；默认阈值为 10 天。
-10. 旧项目如果 `PLAN_MAP.md` 仍是五列表，先运行 `python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated` 显式迁移。
+9. 如需检查活跃计划停滞，运行 `plan-governance-cli check . --stale-days`；默认阈值为 10 天。
+10. 旧项目如果 `PLAN_MAP.md` 仍是五列表，先运行 `plan-governance-cli init --root . --migrate-plan-map-last-updated` 显式迁移。
 11. 普通小范围 bugfix 或一次性修改不需要强制新建治理文档，除非已有计划覆盖它。
 
 验收独立性：
@@ -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):
@@ -487,7 +397,7 @@ def main(argv=None):
             print(f"已写入：{path}")
         for warning in warnings:
             print(f"WARNING: {warning}")
-        print("已有项目升级完成；未覆盖 docs/。下一步请运行 python3 scripts/check_plan_governance.py .")
+        print("已有项目升级完成；未覆盖 docs/。下一步请运行 plan-governance-cli check .")
         return 0
 
     if args.migrate_plan_map_last_updated: