plan-governance-cli 3.0.1 → 3.0.2

package/README.md

@@ -140,6 +140,8 @@ AGENTS.md
 
 ## 更新已有项目
 
+全局 npm 安装、`setup` 同步 skill、项目入口刷新是三个独立步骤。前两步不更新各项目的 `AGENTS.md`；`check` 会对已有地图项目的治理受管块提示差异、损坏或不可读取，严格模式也仅告警，不自动覆盖。差异可能来自定制，先核对再更新；规则来源与诊断边界见 [CLI 参考](resources/skill/references/cli.md#分发与资源)。
+
 如果项目已经有 `docs/PLAN_MAP.md` 和计划文件，不要重新初始化计划文档。只更新代理执行规则时运行：
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "统一入口的计划治理检查 CLI",
   "repository": {
     "type": "git",

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

@@ -10,17 +10,19 @@
 
 | 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
 |---|---|---|---|---|---|
-| [example-plan](plans/YYYYMMDD/example-plan.md) | 候选 | 阶段 0 | <YYYY-MM-DD> | - | - |
+{{unfinished_row}}
 
 ### 已完成
 
 | 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
 |---|---|---|---|---|---|
+{{completed_row}}
 
 ### 已废弃
 
 | 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
 |---|---|---|---|---|---|
+{{deprecated_row}}
 
 允许状态：`候选`、`设计中`、`待实施`、`实施中`、`已完成`、`已替代`、`已合并`、`已废弃`。
 
@@ -34,6 +36,7 @@
 - 阶段 N 完成后，阶段 N+1 默认保持 `设计中`；专项计划自己的准入复核通过后才能进入 `待实施`。
 - 地图只更新当前摘要和有效证据入口；实施、部署、测试和反馈详情写入所属计划或报告，不在页首、索引或单元格内追加日志。
 - 阶段准入摘要、样本矩阵和复核记录只写入专项计划，不复制到本索引。
+- 已有草案、历史设计和临时分析不再作为规范事实源；后续新规范默认进入当前计划或适用契约，旧记录保留为背景。
 - 专项计划记录本次行为差异和验收；现行契约优先引用已有 Schema/OpenAPI，无合适来源且需长期维护时才按需建立 `docs/specs/*.md`。同一事实不重复维护。
 - 专项计划可在当前阶段声明阶段证据和追加式实施/验证记录；完成快照默认保持旧 JSON 兼容格式，发布/合规场景再显式使用 purpose 关系。
 - `--drift`/`--pre-commit` 的关闭窗口只在已完成计划自身也发生变更时覆盖该计划自身和显式阶段证据，不复用已完成计划的完整影响范围。
@@ -45,13 +48,13 @@
 
 只列仍需推进的事项及下一步依据，完成过程留在所属计划。
 
-1. `example-plan`
+1. `{{plan_slug}}`
 
 ## 依赖关系
 
 | 计划 | 依赖 | 原因 |
 |---|---|---|
-| example-plan | - | - |
+| {{plan_slug}} | - | - |
 
 ## 替代、合并和废弃
 

package/resources/skill/references/cli.md

@@ -26,6 +26,12 @@
 
 仅更新计划格式不等于更新项目入口。已有项目在任务交接、没有进行中的实施或复核时更新受管入口；升级不批量回写历史，旧策略名和六列格式按 verification 解释为默认自验，保留真实历史发现。安装副本与仓库开发规则有差异时说明本次选用来源，不能因版本号相同就混读正文。
 
+项目受管入口只保留规范发现、授权、计划定位和必要CLI约束；复核策略、阶段门及记录细节引用同源 verification/planning/cli，不在入口重复维护。
+
+升级分三层：npm 安装更新 CLI 与包内资源，`setup` 更新用户目录 skill，项目的 `AGENTS.md` 则由 `init --update-agent-rules-only` 单独刷新。前两步不会自动更新各项目。已有地图的 `check`（含聚焦/严格模式）会只读对比 AGENTS 受管块与所用工具自带规则：`AGENT_RULES_DRIFT` 表示内容不同，可能过期或含定制，核对后可执行诊断给出的刷新命令；仅忽略换行方式和行尾空白，受管块外自定义内容不参与比较。无文件/无受管标记时跳过，代码围栏中的示例标记不算入口。
+
+受管标记缺失配对、重复或倒序报告 `AGENT_RULES_INVALID`，先人工核对；显式入口刷新也在写入前拒绝这些损坏标记，并保留围栏中的示例及受管块外原文。读取失败、非 UTF-8、非普通文件或符号链接报告 `AGENT_RULES_UNAVAILABLE`，明确未完成核对。三类诊断均为项目级 advisory/WARNING，严格模式也不提升为业务错误，不改变 workset 的阶段判断或自动覆盖文件；原有业务错误照常失败。复制到项目的单文件 checker 只能比较其自身版本规则，不能发现线上最新版本。
+
 ## 初始化、模板和检查脚本
 
 - `../assets/PLAN_MAP.template.md`：治理入口模板。
@@ -50,6 +56,8 @@ plan-governance-cli init \
 
 新计划仅允许 候选/设计中，phase 必须是阶段身份。初始化先预检全部可预测目标冲突和模式参数，再执行 `git init` 和写入；已有 `.git/` 时跳过。升级/入口-only/迁移模式拒绝无关参数。
 
+地图正文只维护在同包 `assets/PLAN_MAP.template.md`，初始化器渲染日期路径、计划行和分类占位符；模板缺失、空、占位符错误或基本索引结构损坏时，在任何项目写入前失败，不回退内嵌旧模板。该能力不重排已有地图，入口-only/升级模式也不依赖地图模板。
+
 只更新已有项目的代理规则，不修改 `docs/`：
 
 ```bash

package/scripts/check_plan_governance.py

@@ -5,6 +5,8 @@ import json
 import posixpath
 import re
 import secrets
+import shlex
+import stat
 import subprocess
 import sys
 from datetime import date, datetime, timezone
@@ -33,6 +35,21 @@ ATTESTATION_REVIEW_STATUSES = {"current", "superseded", "needs_review"}
 ATTESTATION_SNAPSHOT_RE = re.compile(r"^\d{8}T\d{6}Z-[0-9a-f]{8}$")
 
 
+# 与初始化器共用正文；单文件复制的检查器也能核对同版本入口。
+def agent_rules_body():
+    return """## 计划治理
+
+处理已有计划或需要持续协调的工作时，读取实际发现的 `plan-governance` skill；开发或审查该 skill 自身时使用仓库源及对应 CLI。规范来源一次选定后复用，按当前动作读取同源 references。
+
+只有 CLI 可用时，以 `plan-governance-cli guide` 为入口，再按需读取 `guide planning`、`guide verification` 或 `guide cli`。所需规则或能力不可用时说明缺口，不自动安装，不拼接不同版本。
+
+- 按用户授权和当前计划范围推进；未解决问题如实保留，流程建议不扩大实施或外部操作授权。阶段准入、复核方式、验证与适用用户验收统一按所选规范的 verification 执行。
+- 从 `docs/PLAN_MAP.md` 定位相关计划、当前阶段、依赖和证据，再按索引读取必要文档；恢复先核对当前事实与实际差异。文档职责、记录格式和状态同步统一按 planning 执行。
+- 多计划/多会话并行时，在 check/workset/hook 中显式传入本会话的 `--plan ID`；必要前置、共享写入及写入前复核按 cli 执行，不设置全项目可变焦点。
+- 完成时运行 `plan-governance-cli check .`；准入/发布使用 `--strict-readiness`。机械检查不替代实际验证和用户验收。
+"""
+
+
 def fail(errors, message):
     errors.append(message)
 
@@ -41,6 +58,51 @@ def warn(warnings, message):
     warnings.append(message)
 
 
+def agent_rules_markers(text, begin="<!-- plan-governance:start -->", end="<!-- plan-governance:end -->"):
+    """读取与更新共用边界；位置保留原换行字节，忽略代码围栏示例。"""
+    visible = mask_fenced_code(text)
+    starts = list(re.finditer(rf"^{re.escape(begin)}(?=[ \t]*\r?$)", visible, re.MULTILINE))
+    ends = list(re.finditer(rf"^{re.escape(end)}(?=[ \t]*\r?$)", visible, re.MULTILINE))
+    if not starts and not ends:
+        return None
+    if len(starts) != 1 or len(ends) != 1 or starts[0].end() >= ends[0].start():
+        raise ValueError("AGENTS.md 治理受管标记缺失配对、重复或倒序；请先人工核对")
+    return starts[0], ends[0]
+
+
+def agent_rules_issue(root):
+    """仅核对受管入口；返回项目级建议，不推断业务准入或自动覆盖。"""
+    path = root / "AGENTS.md"
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return "AGENT_RULES_UNAVAILABLE", "AGENTS.md 无法读取，未完成治理入口核对"
+    if not stat.S_ISREG(info.st_mode):
+        return "AGENT_RULES_UNAVAILABLE", "AGENTS.md 不是普通文件（含符号链接），未完成治理入口核对"
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return "AGENT_RULES_UNAVAILABLE", "AGENTS.md 无法读取为 UTF-8，未完成治理入口核对"
+    try:
+        markers = agent_rules_markers(text)
+    except ValueError as exc:
+        return "AGENT_RULES_INVALID", f"{exc}，未比较规则内容"
+    if not markers:
+        return None
+
+    def normalized(value):
+        return "\n".join(line.rstrip() for line in value.strip().splitlines())
+
+    start, end = markers
+    actual = text[start.end():end.start()]
+    if normalized(actual) != normalized(agent_rules_body()):
+        command = f"plan-governance-cli init --root {shlex.quote(str(root))} --update-agent-rules-only"
+        return "AGENT_RULES_DRIFT", f"AGENTS.md 治理受管块与当前工具不同，可能过期或含定制；核对差异后可执行 `{command}`。不会自动覆盖"
+    return None
+
+
 def read_utf8(path, errors):
     try:
         return path.read_text(encoding="utf-8")
@@ -2998,6 +3060,12 @@ def main(argv=None):
         readiness_issue(warnings, errors, args.strict_readiness or bool(args.plan), "未找到 docs/PLAN_MAP.md；当前仓库尚未初始化计划治理")
         return finish_check(args, records, reports=reports, not_applicable=not errors)
 
+    issue = agent_rules_issue(root)
+    if issue:
+        code, message = issue
+        warnings.context(category="advisory", code=code, path="AGENTS.md", section="计划治理")
+        warnings.append(message)
+        warnings.context()
     text = read_utf8(plan_map, errors)
     _, blocker_index_issues = map_blockers(text)
     for issue in plan_index_issues(text):

package/scripts/init_plan_governance.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import argparse
+import html
 import importlib.util
 import re
 import shutil
@@ -59,21 +60,7 @@ def init_git(root):
 
 
 def agent_rules_body():
-    return """## 计划治理
-
-本项目使用轻量计划治理。处理已有计划或需要持续协调的工作时，读取实际发现的 `plan-governance` skill；开发或审查该 skill 自身时使用仓库源及对应 CLI。规范来源一次选定后复用，按当前动作读取同源 references。
-
-只有 CLI 可用时，运行 `plan-governance-cli guide` 读取入口，再按需运行 `guide planning`、`guide verification` 或 `guide cli`。两者均不可用或所需能力缺失时说明前提，不自动安装，也不猜测/拼接不同版本的规则。
-
-最小执行边界：
-
-- 普通一次性任务直接处理；已有计划按共享 verification 验证。新旧计划均默认自验，仅在用户明确要求时独立复核；未解决问题继续阻塞。
-- 只实施已授权、已准入的当前阶段。每个阶段有自身 Step 0、验证/完成和失败边界；未解决问题不能记为完成，不可用或超时不能冒充已检查。已有授权不重复索取，新增高影响外部动作按实际授权处理。
-- 首次读取 `docs/PLAN_MAP.md`、索引登记的相关 `docs/plans/` 计划及适用契约/ADR/migration；恢复先核对当前工作集、最近证据和实际 diff，缺失或冲突再展开。
-- 多计划/多会话并行时，每个会话在 check/workset/hook 中显式传入自己的 `--plan ID`；必要前置与共享写入约束仍需读取，写入前重读相关事实，不设置全项目可变焦点。
-- 地图维护状态、阶段、关系、阻塞与证据入口；计划记录本次差异及验证，现行契约优先复用 Schema/OpenAPI。新事实不写回历史草案，变化同步地图及相关引用。
-- 完成时按共享规范记录实际验证与适用用户验收，运行 `plan-governance-cli check .`；准入/CI/发布显式使用 `--strict-readiness`，机械通过不等于业务验收。
-"""
+    return checker.agent_rules_body()
 
 
 def managed_section(begin, end):
@@ -92,12 +79,10 @@ def update_managed_file(root, filename, section, begin, end):
 
     # Keep line endings and trailing whitespace outside the managed block intact.
     current = target.read_bytes().decode("utf-8")
-    pattern = re.compile(
-        rf"{re.escape(begin)}.*?{re.escape(end)}",
-        re.DOTALL,
-    )
-    if pattern.search(current):
-        updated = pattern.sub(lambda match: section.rstrip(), current)
+    markers = checker.agent_rules_markers(current, begin, end)
+    if markers:
+        start, finish = markers
+        updated = current[:start.start()] + section.rstrip() + current[finish.end():]
     else:
         newline = "\r\n" if "\r\n" in current else "\n"
         if not current or current.endswith(newline * 2):
@@ -124,82 +109,54 @@ def update_agent_rules(root):
     return [update_agents_md(root)]
 
 
+def plan_map_template_path():
+    return Path(__file__).resolve().parents[1] / "resources" / "skill" / "assets" / "PLAN_MAP.template.md"
+
+
 def plan_map_content(plan_slug, title, status, phase, created_on=None):
     created_on = created_on or date.today()
-    today = created_on.isoformat()
+    template = plan_map_template_path().read_text(encoding="utf-8")
+    if not template.startswith("# PLAN_MAP\n") or len(re.findall(r"^# ", template, re.MULTILINE)) != 1:
+        raise ValueError("地图模板须以唯一一级标题开始")
+    required = {"plan_slug", "unfinished_row", "completed_row", "deprecated_row"}
+    tokens = re.findall(r"{{(.*?)}}", template)
+    if set(tokens) != required or any(tokens.count(key) != 1 for key in required - {"plan_slug"}):
+        raise ValueError("地图模板缺失、重复或包含未知占位符")
+    headings = ["## 计划索引", "### 未完成", "### 已完成", "### 已废弃", "## 治理范围"]
+    positions = []
+    for heading in headings:
+        matches = list(re.finditer(rf"^{re.escape(heading)}$", template, re.MULTILINE))
+        if len(matches) != 1:
+            raise ValueError("地图模板缺少或重复索引分类章节")
+        positions.append(matches[0].start())
+    if positions != sorted(positions):
+        raise ValueError("地图模板索引必须位于治理说明前，分类顺序固定")
+
+    # 标签不能注入新表格列、换行或 Markdown 链接。
+    label = html.escape(" ".join(title.splitlines()), quote=False)
+    for char, entity in [("\\", "\"), ("|", "|"), ("[", "["), ("]", "]")]:
+        label = label.replace(char, entity)
     plan_relative = f"plans/{created_on:%Y%m%d}/{plan_slug}.md"
-    row = f"| [{title}]({plan_relative}) | {status} | {phase} | {today} | - | - |"
-    unfinished_row = row if status in {"候选", "设计中", "待实施", "实施中"} else ""
-    completed_row = row if status == "已完成" else ""
-    deprecated_row = row if status in {"已废弃", "已替代", "已合并"} else ""
-    return f"""# PLAN_MAP
-
-## 治理范围
-
-本文件只跟踪跨阶段、影响公共契约、依赖真实反馈，或会与其他计划发生关系的计划。普通一次性任务不要加入这里。
-
-## 文档权责
-
-- `docs/PLAN_MAP.md` 是状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
-- `docs/plans/YYYYMMDD/*.md` 默认记录新计划的行为差异、阶段、Step 0 和验收；旧式 `docs/plans/*.md` 计划继续兼容读取。现行契约优先引用已有 Schema/OpenAPI，无合适来源且需长期维护时才按需建立 `docs/specs/*.md`。同一事实不重复维护。
-- 总路线图、优先级计划和索引只记录顺序、状态摘要和专项计划链接，不复制字段级方案、枚举、Step 0 细节或完成定义。
-- 当专项计划变化时，必须同步所有引用该计划的路线图、优先级计划或索引。
-- 如果同一事实在多个文档中重复，保留一个事实源，其他文档改为链接引用。
-- `PLAN_MAP.md` 的 `状态` 是计划级生命周期，`当前阶段` 是阶段身份指针；阶段 N 完成后，阶段 N+1 默认保持 `设计中`。
-- 阶段准入摘要、样本矩阵和独立复核记录只写入专项计划，不复制到本索引。
-- 启用治理后，已有草案、历史设计、归档计划和临时分析文档默认只作为背景材料，不再作为规范事实源；后续新规范默认进入 `docs/plans/YYYYMMDD/*.md`、ADR、migration、正式 spec 或 `docs/PLAN_MAP.md`。
-- 计划索引固定分为 `未完成`、`已完成`、`已废弃` 三张表；`已替代`、`已合并`等不再推进的终态归入 `已废弃` 表，但保留真实状态值。
-
-## 计划索引
-
-### 未完成
-
-| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
-|---|---|---|---|---|---|
-{unfinished_row}
-
-### 已完成
-
-| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
-|---|---|---|---|---|---|
-{completed_row}
-
-### 已废弃
-
-| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
-|---|---|---|---|---|---|
-{deprecated_row}
-
-允许状态：`候选`、`设计中`、`待实施`、`实施中`、`已完成`、`已替代`、`已合并`、`已废弃`。
-
-## 推荐顺序
-
-1. `{plan_slug}`
-
-## 依赖关系
-
-| 计划 | 依赖 | 原因 |
-|---|---|---|
-| {plan_slug} | - | - |
-
-## 替代、合并和废弃
-
-| 计划 | 关系 | 目标 | 原因 |
-|---|---|---|---|
-| - | - | - | - |
-
-## 当前阻塞项
-
-| 问题 | 推荐方案 | 影响范围 | 是否阻塞当前阶段 | 状态 |
-|---|---|---|---|---|
-| - | - | - | 否 | 已延后 |
-
-## 完成证据
-
-| 计划 | 阶段 | 证据 |
-|---|---|---|
-| - | - | - |
-"""
+    row = f"| [{label}]({plan_relative}) | {status} | {phase} | {created_on.isoformat()} | - | - |"
+    groups = {"unfinished_row": {"候选", "设计中", "待实施", "实施中"},
+              "completed_row": {"已完成"}, "deprecated_row": {"已替代", "已合并", "已废弃"}}
+    if status not in VALID_STATUSES:
+        raise ValueError(f"计划状态不合法：{status}")
+    values = {key: row if status in states else "" for key, states in groups.items()}
+    values["plan_slug"] = plan_slug
+    rendered = re.sub(r"{{(.*?)}}", lambda match: values[match.group(1)], template)
+    header = ["计划", "状态", "当前阶段", "最后更新", "依赖", "证据"]
+    for heading, key in zip(headings[1:4], groups):
+        section = rendered.split(heading + "\n", 1)[1].split("\n#", 1)[0]
+        rows = checker.markdown_table_rows(section)
+        expected = 2 if status in groups[key] else 1
+        lines = section.strip().splitlines()
+        valid_separator = len(lines) >= 2 and re.fullmatch(r"\|(?:\s*:?-{3,}:?\s*\|){6}", lines[1])
+        valid_data_row = expected == 1 or (len(lines) >= 3 and lines[2] == row)
+        if (not valid_separator or not valid_data_row or len(rows) != expected
+                or rows[0] != header or any(len(item) != 6 for item in rows)):
+            raise ValueError("地图模板分类表必须保持六列且每个计划仅出现一次")
+    return rendered
 
 
 def plan_template_path():
@@ -369,7 +326,7 @@ def main(argv=None):
             args.update_agents_md, args.update_agent_rules)):
         target = root / "AGENTS.md"
         if target.exists():
-            target.read_text(encoding="utf-8")
+            checker.agent_rules_markers(target.read_text(encoding="utf-8"))
     if args.upgrade_existing:
         target = root / "scripts/check_plan_governance.py"
         if target.exists() and not target.is_file():