plan-governance-cli 0.2.2 → 0.2.3

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.
Files changed (3) hide show
  1. package/README.md +27 -23
  2. package/package.json +1 -1
  3. package/scripts/init_plan_governance.py +4 -4
package/README.md CHANGED
@@ -74,26 +74,28 @@ docs/
74
74
  在目标项目根目录运行：
75
75
 
76
76
  ```bash
77
- python3 scripts/init_plan_governance.py \
77
+ plan-governance-cli init \
78
78
  --root . \
79
79
  --plan api-compat-migration \
80
80
  --title "API 兼容性迁移" \
81
81
  --goal "分阶段完成 API 兼容性迁移" \
82
- --copy-checker \
83
82
  --update-agent-rules
84
83
  ```
85
84
 
85
+ 如尚未安装 CLI，先运行 `npm install -g plan-governance-cli`。初始化默认只创建治理文档和代理规则，不复制项目本地检查器。
86
+
86
87
  这会创建：
87
88
 
88
89
  ```text
89
90
  .git/
90
91
  docs/PLAN_MAP.md
91
92
  docs/plans/api-compat-migration.md
92
- scripts/check_plan_governance.py
93
93
  CLAUDE.md
94
94
  AGENTS.md
95
95
  ```
96
96
 
97
+ 其中检查器是 npm 包的内部运行资源；正常使用不需要在目标项目中创建 `scripts/check_plan_governance.py`。
98
+
97
99
  如果目标目录还不是 Git 仓库，初始化流程会先执行 `git init`；已有 `.git/` 时会跳过，不重复初始化。
98
100
 
99
101
  `--update-agent-rules` 会创建或更新 `CLAUDE.md` 和 `AGENTS.md` 中带标记的计划治理章节，只写稳定执行规则，不写具体计划内容。具体计划仍以 `docs/PLAN_MAP.md` 和 `docs/plans/*.md` 为准。
@@ -116,7 +118,7 @@ AGENTS.md
116
118
  如果项目已经有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`，不要重新初始化计划文档。只更新代理执行规则时运行：
117
119
 
118
120
  ```bash
119
- python3 scripts/init_plan_governance.py \
121
+ plan-governance-cli init \
120
122
  --root . \
121
123
  --update-agent-rules-only
122
124
  ```
@@ -126,52 +128,54 @@ python3 scripts/init_plan_governance.py \
126
128
  如果要升级已有项目的辅助文件，刷新检查脚本并更新代理规则，但不覆盖 `docs/`，运行：
127
129
 
128
130
  ```bash
129
- python3 scripts/init_plan_governance.py \
131
+ plan-governance-cli init \
130
132
  --root . \
131
133
  --upgrade-existing
132
134
  ```
133
135
 
134
136
  `--upgrade-existing` 会：
135
137
 
136
- - 覆盖更新 `scripts/check_plan_governance.py`
138
+ - 按兼容模式覆盖更新项目中的 `scripts/check_plan_governance.py`
137
139
  - 创建或更新 `CLAUDE.md` 和 `AGENTS.md` 中带标记的计划治理章节
138
140
  - 保留已有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`
139
141
  - 提示缺失的治理文档
140
142
 
143
+ 新项目和日常升级不需要使用该兼容模式；优先使用全局 npm CLI。
144
+
141
145
  ## 检查
142
146
 
143
147
  在仓库根目录运行：
144
148
 
145
149
  ```bash
146
- python3 scripts/check_plan_governance.py .
150
+ plan-governance-cli check .
147
151
  ```
148
152
 
149
153
  可选检查：
150
154
 
151
155
  ```bash
152
- python3 scripts/check_plan_governance.py . --drift
153
- python3 scripts/check_plan_governance.py . --pre-commit
154
- python3 scripts/check_plan_governance.py . --stale-days 10
156
+ plan-governance-cli check . --drift
157
+ plan-governance-cli check . --pre-commit
158
+ plan-governance-cli check . --stale-days 10
155
159
  ```
156
160
 
157
161
  `--drift` 会检查工作区变更是否被活跃计划的 `影响模块或文件` 覆盖；`--pre-commit` 会检查 staged 变更，便于用户手动接入 Git hook。两者只输出 `WARNING`，不改变退出码。
158
162
 
159
- 如果已安装统一 npm CLI，可用全局入口运行同一套检查器：
163
+ 全局 CLI 是推荐入口：
160
164
 
161
165
  ```bash
162
166
  npm install -g plan-governance-cli
163
- plan-governance-cli . --strict-readiness
167
+ plan-governance-cli check . --strict-readiness
164
168
  ```
165
169
 
166
170
  也可以不全局安装，直接使用锁定版本：
167
171
 
168
172
  ```bash
169
- npx --yes --package plan-governance-cli@0.2.2 plan-governance-cli . --strict-readiness
173
+ npx --yes --package plan-governance-cli@0.2.3 plan-governance-cli check . --strict-readiness
170
174
  ```
171
175
 
172
- npm CLI 只是统一入口，实际检查逻辑仍由包内版本化的 Python 检查器执行；迁移期间项目原有 Python 命令仍可作为回滚路径。
176
+ npm 包内部仍使用版本化的 Python 检查器，但用户不需要直接调用或复制该脚本。旧项目已有本地脚本时仍可保留作为兼容或回滚路径。
173
177
 
174
- 作用域匹配规则同样用于 `plan_governance_hook.py --event pre-write`：
178
+ 作用域匹配规则同样用于 `plan-governance-cli hook --event pre-write`：
175
179
 
176
180
  - 优先提取列表项中的第一个反引号路径，例如 ``- `./scripts/`: 检查脚本``。
177
181
  - 没有反引号时提取列表项的第一个纯文本 token，例如 `- README.md`。
@@ -204,10 +208,10 @@ plan-governance-cli init --root . --plan api-compat-migration --title "API 兼
204
208
  本仓库提供只读 hook runtime，供 Codex、Claude Code 或其他 Agent 的项目级 hooks 手动接入。脚本只输出短提示和检查结果，不修改治理文档，不更新 `最后更新`，不安装或修改全局配置。
205
209
 
206
210
  ```bash
207
- python3 scripts/plan_governance_hook.py --event session-start
208
- python3 scripts/plan_governance_hook.py --event pre-write --paths scripts/check_plan_governance.py
209
- python3 scripts/plan_governance_hook.py --event post-write --paths docs/PLAN_MAP.md
210
- python3 scripts/plan_governance_hook.py --event stop
211
+ plan-governance-cli hook --event session-start
212
+ plan-governance-cli hook --event pre-write --paths scripts/check_plan_governance.py
213
+ plan-governance-cli hook --event post-write --paths docs/PLAN_MAP.md
214
+ plan-governance-cli hook --event stop
211
215
  ```
212
216
 
213
217
  事件语义：
@@ -215,12 +219,12 @@ python3 scripts/plan_governance_hook.py --event stop
215
219
  - `session-start`：摘要活跃计划、当前阶段、最后更新、阻塞项和证据链接。
216
220
  - `pre-write`：按活跃计划的 `影响模块或文件` 匹配路径，提示当前阶段门禁。
217
221
  - `post-write`：写入 `PLAN_MAP.md` 或计划文档后，提示同步状态、证据、覆盖率和反向引用检查。
218
- - `stop`：运行 `python3 scripts/check_plan_governance.py .` 并转发结果；该事件是非阻塞提示，不实现强制 gate。
222
+ - `stop`：运行 `plan-governance-cli check .` 并转发结果；该事件是非阻塞提示，不实现强制 gate。
219
223
 
220
224
  旧项目如果仍使用五列 `PLAN_MAP.md`，先显式迁移：
221
225
 
222
226
  ```bash
223
- python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated --last-updated-date 2026-07-05
227
+ plan-governance-cli init --root . --migrate-plan-map-last-updated --last-updated-date 2026-07-05
224
228
  ```
225
229
 
226
230
  不传 `--last-updated-date` 时使用当天日期。该迁移只修改 `docs/PLAN_MAP.md` 的计划索引表，不会自动改变计划状态。
@@ -249,8 +253,8 @@ python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated
249
253
  已完成计划可以显式创建完成快照，用于后续发现未复核修改。快照文件写入 `docs/attestations/<plan-name>.json`，包含计划文件和 `docs/PLAN_MAP.md` 的 SHA-256。
250
254
 
251
255
  ```bash
252
- python3 scripts/check_plan_governance.py . --attest agent-runtime-integration
253
- python3 scripts/check_plan_governance.py . --check-attestations
256
+ plan-governance-cli check . --attest agent-runtime-integration
257
+ plan-governance-cli check . --check-attestations
254
258
  ```
255
259
 
256
260
  `--attest <plan-name>` 只接受已登记到 `docs/PLAN_MAP.md` 的计划。`--check-attestations` 对计划文件 hash 变化、`PLAN_MAP.md` hash 变化、JSON 损坏、文件缺失或快照引用未登记计划输出 `WARNING`，不改变退出码。人工确认文档修正合理后，可以重新运行 `--attest <plan-name>` 覆盖快照。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "plan-governance-cli",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "统一入口的计划治理检查 CLI",
5
5
  "private": false,
6
6
  "type": "module",
package/scripts/init_plan_governance.py CHANGED
@@ -110,11 +110,11 @@ def agent_rules_body():
110
110
  8. 完成后运行：
111
111
 
112
112
  ```bash
113
- python3 scripts/check_plan_governance.py .
113
+ plan-governance-cli check .
114
114
  ```
115
115
 
116
- 9. 如需检查活跃计划停滞，运行 `python3 scripts/check_plan_governance.py . --stale-days`；默认阈值为 10 天。
117
- 10. 旧项目如果 `PLAN_MAP.md` 仍是五列表，先运行 `python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated` 显式迁移。
116
+ 9. 如需检查活跃计划停滞，运行 `plan-governance-cli check . --stale-days`；默认阈值为 10 天。
117
+ 10. 旧项目如果 `PLAN_MAP.md` 仍是五列表，先运行 `plan-governance-cli init --root . --migrate-plan-map-last-updated` 显式迁移。
118
118
  11. 普通小范围 bugfix 或一次性修改不需要强制新建治理文档，除非已有计划覆盖它。
119
119
 
120
120
  验收独立性：
@@ -487,7 +487,7 @@ def main(argv=None):
487
487
  print(f"已写入：{path}")
488
488
  for warning in warnings:
489
489
  print(f"WARNING: {warning}")
490
- print("已有项目升级完成；未覆盖 docs/。下一步请运行 python3 scripts/check_plan_governance.py .")
490
+ print("已有项目升级完成；未覆盖 docs/。下一步请运行 plan-governance-cli check .")
491
491
  return 0
492
492
 
493
493
  if args.migrate_plan_map_last_updated: