plan-governance-cli 1.0.0 → 1.0.2

package/README.md

@@ -209,6 +209,14 @@ plan-governance-cli graph code impact --repo modelpad --file Sources/ModelPadCor
 
 [验证规范](resources/skill/references/verification.md)统一维护风险分流、证据复用、失败重审与用户验收；其他会话从同一 skill 读取。需要独立复核且授权明确时自动安排只读 subagent，不为普通小改逐次派发；技术完成待用户验收的适用功能计划仍保持实施中。
 
+1.0.1 起支持可选的最近记录窗口：
+
+```bash
+plan-governance-cli workset . --json --evidence-limit 3
+```
+
+每个计划保留末尾三条记录，并给出省略数量和原文位置；默认完整输出和门禁判断保持。窗口用于恢复阅读，必要时去掉参数回查完整记录，详见 [CLI 参考](resources/skill/references/cli.md#当前工作集)。已发布的 1.0.0 尚不支持此参数。
+
 ## 按需读取规则
 
 ```bash
@@ -225,7 +233,7 @@ SKILL 保留任务分流和执行底线，三份 references 按需读取并随 m
 也可以不全局安装，直接使用锁定版本：
 
 ```bash
-npx --yes --package plan-governance-cli@1.0.0 plan-governance-cli check . --strict-readiness
+npx --yes --package plan-governance-cli@1.0.1 plan-governance-cli check . --strict-readiness
 ```
 
 npm 包内部仍使用版本化的 Python 检查器，但用户不需要直接调用或复制该脚本。旧项目已有本地脚本时仍可保留作为兼容或回滚路径。

package/package.json

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

package/resources/skill/references/cli.md

@@ -10,10 +10,18 @@
 
 `plan-governance-cli workset . --json` 派生当前计划、阶段、阻塞、下一动作、并行提示和最近证据；加 `--strict-readiness` 对活跃计划的机械缺陷返回非零。它不写计划、不自动执行动作、不替代授权或业务验收，也不自动核对快照和环境漂移。恢复先读工作集与相关当前记录，必要时再展开原计划。
 
+1.0.1 起，恢复阅读可显式用 `workset . --json --evidence-limit 3`，按原追加顺序显示每个计划末尾三条记录。N 必须为正整数且仅适用于 workset JSON；默认仍返回完整记录。限量模式的 `recent_evidence_window` 提供 `total`、`omitted` 和原文 `source`（实际 `path`/`section`；无法确认时为 null），不改变完整数据派生的阻塞、动作、诊断或退出码。没有记录章节时 section 为 null。
+
+限量窗口不等于完整验收证据；有阻塞、缺关键上下文或需要复核结论时，按 source 回查，或去掉 `--evidence-limit` 读取完整记录。`--include-history` 仍只控制是否纳入历史计划。普通文本不显示记录表，不需要此参数；旧 CLI（包括 1.0.0）不支持限量时，继续用完整输出，按已获授权更新版本。
+
+面向当前任务读取时，可在工具内解析完整 JSON 后只展示目标计划的状态、阶段、下一动作、有效阻塞和少量证据。跨计划检查仍保留直接依赖和不能归属的诊断；展示限量不裁剪底层门禁或清除阻塞。先选取相关字段再回传，不先以过小输出预算截断、随后又打印全部正文。按来源展开缺口，不为已知无关的警告反复倾倒所有计划。
+
 ## 分发与资源
 
 SKILL、三个 references、agents 元数据与 assets 由同一 npm 包的 manifest 分发。`plan-governance-cli setup --target codex|claude|all --dry-run` 查看同步差异；实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理用户目录残留。项目升级不迁移旧计划，受管块外内容必须保持。
 
+仅更新计划格式不等于更新项目入口；更新 AGENTS/CLAUDE 入口也不等于当前阶段已采用风险分流。已有项目在任务交接、没有进行中的实施或复核时更新受管入口；阶段策略单独按 verification 兼容规则处理，不批量回写历史。安装副本与仓库开发规则有差异时说明本次选用来源，不能因版本号相同就混读正文。
+
 ## 初始化、模板和检查脚本
 
 - `../assets/PLAN_MAP.template.md`：治理入口模板。

package/resources/skill/references/planning.md

@@ -121,8 +121,14 @@ docs/
 
 ## 执行与恢复
 
-首次接手读取 PLAN_MAP、当前计划和确实相关的 ADR/migration/spec。恢复时先用已有当前工作集、当前阶段、最近实施/验证记录和实际 diff 定位进度；只有缺失、冲突或相关范围变化时再展开旧资料。历史会话和全部计划不是每轮必读材料。规则与当前证据入口应可访问；只有不可检索的输出 ID 时先补真实内容或可复验入口。
+首次接手先区分项目仅更新了文档格式、已接入共享入口，还是当前阶段已显式选择风险策略；三者不互相替代，旧计划兼容按 verification 处理。按任务读取 PLAN_MAP、当前计划和确实相关的契约；未启用治理的有限原型不为接入入口强建整套目录。
+
+恢复先用已有当前工作集、当前阶段、少量最近证据和实际 diff 定位进度；缺失、冲突或相关范围变化时再展开对应段落。规则参考按当前动作读取，不因拆成多个文件就每次全读。跨计划只展开直接相关对象，完整数据中发现的有效阻塞仍须保留。证据入口不可检索时补要点或可复验入口，不倾倒全部历史代替定位。
 
 先确认当前阶段准入和授权，再实施。假设、公共契约、兼容、范围、完成条件或依赖变化时，先更新唯一事实源和地图，再评估准入；阶段内原范围反馈追加差异和验证，不自动新开计划或重开所有门。原验收预期从原场景读取，不因新边界输入自行发明业务规则。
 
+用户连续确认普通决定时，由当前 AI 同步相应文档并自查；一组决定收敛后，再按 verification 判断是否需要独立检查。不把每次回答、文档保存或同步操作当作一个复核点；应先判断的高影响取舍不能积压到实施后。
+
+验收涉及未来周期或新增工作时，尽早明确它与当前交付的关系。经用户确认范围后，将未来事项的职责、触发条件和证据要求放入适合的现有或独立计划。后续计划尚未准入本身不阻塞当前交付，但当前运行安全、恢复能力和已承诺验收仍须满足；不得仅靠拆计划移走有效阻塞。复核分别判断当前交付与后续承接，结论落档顺序见 verification。
+
 治理文档变更后做适用链接、结构、反向引用和 `plan-governance-cli check .`；用 `rg` 搜索同名计划、P 编号、状态/关键字段，以及 `草案为准|以草案为事实源|详见草案|draft is source|source of truth.*draft|以.*draft.*为准`。纯落档不重跑已有效覆盖的全部代码测试；规范行为变化仍需验证受影响场景。

package/resources/skill/references/verification.md

@@ -12,7 +12,9 @@
 
 是否进入计划、发生阶段转换或计划收尾，本身不决定独立复核。已有计划或用户明确要求独立复核时仍须遵循；新风险策略不能替旧计划的既有门禁自动降级。可逆性评估实际外部后果，不能只看代码能否回滚。执行中影响扩大时立即重新评估。
 
-需要独立复核且范围/授权已明确时，自动启动未参与实施或测试编写的只读 subagent 或等价复核者，不等待用户逐项安排。输入只给计划/阶段、受审 revision 与实际范围、必要证据、验证命令、完成条件、安全边界；使用新上下文，不倾倒全量聊天。
+需要独立复核且范围/授权已明确时，自动启动未参与实施或测试编写的只读 subagent 或等价复核者，不结束任务等用户再次说“复核吧”。只合并同一授权和审查范围内可合并的检查；普通已确认决定的文档同步由当前 AI 自查，一组决定收敛后再安排适用独立检查。高影响实施前门禁、有效失败及当前交付的安全条件仍须及时满足。
+
+输入只给计划/阶段、受审 revision 与实际范围、差异、风险、可访问证据、验证命令、完成条件和授权边界。用不继承完整聊天的上下文派发，必要历史按证据入口补读；若宿主只能继承历史，不把该能力局限冒充盲测或另起复制全部历史的交接文档。
 
 独立失败、入口不可用、超时或证据冲突保持阻塞，不由实施者自批，不靠改分类/换一条安全操作放行。授权范围内可补证据和修复，未解除前不越门；等价替代者仍须满足相同独立性与证据要求。独立复核不能代替外部授权；已有授权有效时不重复索取，新的公开暴露/凭证/破坏性/隐私/合规或产品取舍按实际边界确认。
 
@@ -68,7 +70,11 @@
 
 自验失败由实施 AI 自主修复、复验。独立失败后的重审聚焦原阻塞、修复差异及受影响回归，引用仍有效的证据；不因一处修复无理由重跑整套历史，也不把共享调用变化当成无影响。相同未修正阻塞不重复送审。
 
-每个必要复核点默认一名主复核者，仅对具体且独立的专项风险增加协作者。适用时合并同范围行为后测与完成复核：检查者未参与实现/测试编写，先给任务输入，完成后再给预期对照；行为判断和机械测试分别记录。受审范围冻结后，等待期间可做无依赖的已授权工作；相关变化需通知复核者，不以未完成结果推进依赖项。使用有界等待，避免密集轮询；并行工时不能相加冒充关键路径时长。
+每个必要复核点默认一名主复核者，仅对具体且独立的专项风险增加协作者，不把文档生产助手全部算作独立复核。适用时合并同范围行为后测与完成复核：检查者未参与实现/测试编写，先给任务输入，完成后再给预期对照；行为判断和机械测试分别记录。受审范围冻结后，等待期间可做无依赖的已授权工作；相关变化需通知复核者，不以未完成结果推进依赖项。使用有界等待，避免密集轮询；并行工时不能相加冒充关键路径时长。
+
+送审时用简短说明区分当前交付、后续事项和通过后的记录同步。独立者依据当前已确认范围、实际证据及原失败原因先给出结论，不要求“本次通过记录已存在”才能完成本次判断。旧有效失败仍须由适格独立者明确判断是否解除；范围调整不自动消除失败，也不让未准入的后续事项自动阻断当前交付。
+
+执行者只准确转写独立结论、追加历史并同步地图，不预填通过或自行改判。涉及未来事项时按 planning 核对承接及当前安全边界；资料不足则具体指出哪个当前完成条件缺什么证据，不以“尚未落档本次结论”替代缺陷说明。
 
 验证后仅追加状态/证据或修正文档链接时，做适用文档检查即可；契约、源、依赖或环境又变则补受影响验证。区分仓库源与安装版本、旧缺陷与新回归、当前范围与其他并行任务失败；如实报告全仓失败，不能用局部通过掩盖，也不擅自接管无关任务。
 

package/scripts/check_plan_governance.py

@@ -2208,9 +2208,50 @@ def print_workset_text(payload, strict=False):
         print(f"{level}: {warning}")
 
 
-def run_workset(root, as_json=False, include_history=False, strict=False):
+def limit_workset_evidence(root, payload, limit):
+    """裁剪 JSON 阅读窗口；完整 payload 和门禁结果保持不变。"""
+    result = {**payload, "plans": []}
+    if not payload["plans"]:
+        return result
+    source_errors = []
+    _, _, records = load_plan_records(root, source_errors)
+    if source_errors:
+        records = {}
+    for item in payload["plans"]:
+        rows = item["recent_evidence"]
+        source = None
+        record = records.get(item["plan"])
+        if record and record["phase"] == item["phase"]:
+            errors = []
+            text = read_utf8(record["path"], errors)
+            # 来源只辅助回查；再次读取失败或内容变化不能伪造定位。
+            if not errors and recent_evidence(text, item["phase"]) == rows:
+                current = top_level_section(text, "当前阶段") or ""
+                titles = ["最近实施/验证记录"]
+                if item["phase"]:
+                    titles.extend([f"{item['phase']} 最近验证记录", f"{item['phase']} 最近实施/验证记录"])
+                section = next((title for title in titles if fixed_section(current, title) is not None), None)
+                try:
+                    path = record["path"].relative_to(root).as_posix()
+                except ValueError:
+                    path = record["path"].as_posix()
+                source = {"path": path, "section": section}
+        shown = rows[-limit:]
+        result["plans"].append({
+            **item,
+            "recent_evidence": shown,
+            "recent_evidence_window": {
+                "total": len(rows), "omitted": len(rows) - len(shown), "source": source,
+            },
+        })
+    return result
+
+
+def run_workset(root, as_json=False, include_history=False, strict=False, evidence_limit=None):
     payload, status = workset_payload(root, include_history=include_history, strict=strict)
     if as_json:
+        if evidence_limit is not None:
+            payload = limit_workset_evidence(root, payload, evidence_limit)
         print(json.dumps(payload, ensure_ascii=False, indent=2))
     else:
         print_workset_text(payload, strict=strict)
@@ -2223,6 +2264,8 @@ def parse_args(argv):
     parser.add_argument("--workset", action="store_true", help="输出只读当前工作集。")
     parser.add_argument("--json", action="store_true", help="以 JSON 输出工作集。")
     parser.add_argument("--include-history", action="store_true", help="工作集包含历史计划。")
+    parser.add_argument("--evidence-limit", type=int, metavar="N",
+                        help="仅工作集 JSON：每个计划显示末尾 N 条记录（正整数），省略时返回全部。")
     parser.add_argument("--root", dest="mode_root", help="工作集的仓库根目录。")
     parser.add_argument("--drift", action="store_true", help="检查工作区变更是否被活跃计划影响范围覆盖。")
     parser.add_argument("--pre-commit", action="store_true", help="检查 staged 变更是否被活跃计划影响范围覆盖。")
@@ -2255,7 +2298,13 @@ def parse_args(argv):
         default=None,
         help="检查活跃计划是否超过 N 天未更新；省略 N 时默认 10 天。",
     )
-    return parser.parse_args(argv)
+    args = parser.parse_args(argv)
+    if args.evidence_limit is not None:
+        if args.evidence_limit <= 0:
+            parser.error("--evidence-limit 必须为正整数")
+        if not args.workset or not args.json:
+            parser.error("--evidence-limit 只能与 --workset 和 --json 一起使用")
+    return args
 
 
 def main(argv=None):
@@ -2269,6 +2318,7 @@ def main(argv=None):
             as_json=args.json,
             include_history=args.include_history,
             strict=args.strict_readiness,
+            evidence_limit=args.evidence_limit,
         )
     root = Path(args.root)
     docs = root / "docs"