plan-governance-cli 1.0.0 → 1.0.1

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.1",
   "description": "统一入口的计划治理检查 CLI",
   "private": false,
   "type": "module",

package/resources/skill/references/cli.md

@@ -10,6 +10,10 @@
 
 `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）不支持限量时，继续用完整输出，按已获授权更新版本。
+
 ## 分发与资源
 
 SKILL、三个 references、agents 元数据与 assets 由同一 npm 包的 manifest 分发。`plan-governance-cli setup --target codex|claude|all --dry-run` 查看同步差异；实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理用户目录残留。项目升级不迁移旧计划，受管块外内容必须保持。

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"