plan-governance-cli 0.1.0

package/README.md

@@ -0,0 +1,312 @@
+# plan-governance
+
+`plan-governance` 是一套面向个人或小团队的轻量计划治理机制。
+
+它不是任务清单，也不是完整项目管理系统。它解决的问题是：当一个任务跨阶段推进、影响公共契约、依赖真实反馈，或会和已有计划发生依赖/替代/冲突时，如何避免计划漂移、旧决策被覆盖、阶段边界失控和完成证据缺失。
+
+## 什么时候使用
+
+适合启用治理的信号：
+
+- 跨阶段、里程碑或多轮会话。
+- 涉及架构、公共 API、Schema、兼容性或迁移行为。
+- 后续需要真实运行报告、样本或反馈。
+- 多个计划之间存在依赖、替代、重叠或冲突。
+- 同一模块会被多个后续计划反复修改。
+
+不适合启用治理的场景：
+
+- 一次性 bugfix。
+- 小范围本地修改。
+- 互不依赖的待办列表。
+- 不影响公共契约的普通实现任务。
+
+## 文档结构
+
+最小结构：
+
+```text
+docs/
+  PLAN_MAP.md
+  plans/
+    <plan-name>.md
+```
+
+按需增加：
+
+```text
+docs/
+  adr/
+    0001-<decision>.md
+  migrations/
+    <migration-name>.md
+```
+
+文档权责：
+
+| 文档 | 权威内容 |
+|---|---|
+| `docs/PLAN_MAP.md` | 计划索引、状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项、证据链接 |
+| `docs/plans/*.md` | 单个计划的目标、阶段、当前步骤、字段方案、Schema、枚举、Step 0 证据、验证方式、完成条件 |
+| `docs/adr/*.md` | 关键架构决策、备选方案和后果 |
+| `docs/migrations/*.md` | 兼容策略、迁移步骤、回滚方式和旧行为保留窗口 |
+
+## 多文档同步
+
+- 专项计划是实施细节事实源，记录字段方案、Schema、枚举、Step 0 证据、验证方式和完成条件。
+- `docs/PLAN_MAP.md` 是状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
+- 总路线图、优先级计划和索引只记录顺序、状态摘要和专项计划链接，不复制字段级方案、枚举、Step 0 细节或完成定义。
+- 当专项计划的状态、字段方案、完成条件或验证结果变化时，必须同步 `docs/PLAN_MAP.md` 和所有引用该计划的路线图、优先级计划或索引。
+- 验收治理文档时，必须用 `rg` 搜索同名计划、P 编号、状态名和关键字段，检查是否存在重复定义或漂移。
+- 如果同一事实在多个文档中重复，保留一个事实源，其他文档改为链接引用。
+
+## 草案和历史文档
+
+启用治理后，已有草案、历史设计、归档计划、临时分析文档等默认只作为背景材料，不再作为规范事实源。
+
+- 新发生的目标、范围、公共契约、字段、Schema、状态语义、阶段、验证方式、完成条件、风险和回滚，应写入 `docs/plans/*.md`、ADR、migration 或正式 spec。
+- 计划状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接，应写入或同步 `docs/PLAN_MAP.md`。
+- 不要为了“保持一致”而修改草案或历史文档；除非用户明确点名该文件，否则草案只在治理文档中作为背景材料引用。
+- 验收时应搜索并修正“草案为准”“以草案为事实源”“详见草案”等表达。
+
+## 初始化
+
+在目标项目根目录运行：
+
+```bash
+python3 scripts/init_plan_governance.py \
+  --root . \
+  --plan api-compat-migration \
+  --title "API 兼容性迁移" \
+  --goal "分阶段完成 API 兼容性迁移" \
+  --copy-checker \
+  --update-agent-rules
+```
+
+这会创建：
+
+```text
+.git/
+docs/PLAN_MAP.md
+docs/plans/api-compat-migration.md
+scripts/check_plan_governance.py
+CLAUDE.md
+AGENTS.md
+```
+
+如果目标目录还不是 Git 仓库，初始化流程会先执行 `git init`；已有 `.git/` 时会跳过，不重复初始化。
+
+`--update-agent-rules` 会创建或更新 `CLAUDE.md` 和 `AGENTS.md` 中带标记的计划治理章节，只写稳定执行规则，不写具体计划内容。具体计划仍以 `docs/PLAN_MAP.md` 和 `docs/plans/*.md` 为准。
+
+如果只需要更新单个入口，也可以使用：
+
+```bash
+--update-claude-md
+--update-agents-md
+```
+
+默认不会覆盖已有文件。需要覆盖时显式加：
+
+```bash
+--force
+```
+
+## 更新已有项目
+
+如果项目已经有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`，不要重新初始化计划文档。只更新代理执行规则时运行：
+
+```bash
+python3 scripts/init_plan_governance.py \
+  --root . \
+  --update-agent-rules-only
+```
+
+如果只更新单个入口，可以使用 `--update-claude-md-only` 或 `--update-agents-md-only`。
+
+如果要升级已有项目的辅助文件，刷新检查脚本并更新代理规则，但不覆盖 `docs/`，运行：
+
+```bash
+python3 scripts/init_plan_governance.py \
+  --root . \
+  --upgrade-existing
+```
+
+`--upgrade-existing` 会：
+
+- 覆盖更新 `scripts/check_plan_governance.py`
+- 创建或更新 `CLAUDE.md` 和 `AGENTS.md` 中带标记的计划治理章节
+- 保留已有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`
+- 提示缺失的治理文档
+
+## 检查
+
+在仓库根目录运行：
+
+```bash
+python3 scripts/check_plan_governance.py .
+```
+
+可选检查：
+
+```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
+```
+
+`--drift` 会检查工作区变更是否被活跃计划的 `影响模块或文件` 覆盖；`--pre-commit` 会检查 staged 变更，便于用户手动接入 Git hook。两者只输出 `WARNING`，不改变退出码。
+
+如果已安装统一 npm CLI，可用全局入口运行同一套检查器：
+
+```bash
+npm install -g plan-governance-cli
+plan-governance-cli . --strict-readiness
+```
+
+也可以不全局安装，直接使用锁定版本：
+
+```bash
+npx --yes plan-governance-cli@0.1.0 . --strict-readiness
+```
+
+npm CLI 只是统一入口，实际检查逻辑仍由包内版本化的 Python 检查器执行；迁移期间项目原有 Python 命令仍可作为回滚路径。
+
+作用域匹配规则同样用于 `plan_governance_hook.py --event pre-write`：
+
+- 优先提取列表项中的第一个反引号路径，例如 ``- `./scripts/`: 检查脚本``。
+- 没有反引号时提取列表项的第一个纯文本 token，例如 `- README.md`。
+- 匹配前会归一化前导 `./`、尾随 `/` 和重复斜杠。
+- 支持文件精确匹配和目录前缀匹配。
+- 不支持 glob、正则、否定规则或自然语言推断。
+
+`--stale-days` 会检查活跃计划的 `最后更新` 日期是否超过阈值；省略数值时默认 10 天。停滞检测只输出 `WARNING`，不自动改变计划状态。
+
+## Hook runtime
+
+本仓库提供只读 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
+```
+
+事件语义：
+
+- `session-start`：摘要活跃计划、当前阶段、最后更新、阻塞项和证据链接。
+- `pre-write`：按活跃计划的 `影响模块或文件` 匹配路径，提示当前阶段门禁。
+- `post-write`：写入 `PLAN_MAP.md` 或计划文档后，提示同步状态、证据、覆盖率和反向引用检查。
+- `stop`：运行 `python3 scripts/check_plan_governance.py .` 并转发结果；该事件是非阻塞提示，不实现强制 gate。
+
+旧项目如果仍使用五列 `PLAN_MAP.md`，先显式迁移：
+
+```bash
+python3 scripts/init_plan_governance.py --root . --migrate-plan-map-last-updated --last-updated-date 2026-07-05
+```
+
+不传 `--last-updated-date` 时使用当天日期。该迁移只修改 `docs/PLAN_MAP.md` 的计划索引表，不会自动改变计划状态。
+
+当前检查项包括：
+
+- `PLAN_MAP.md` 引用的计划文件是否存在。
+- `docs/plans/*.md` 是否存在未登记到 `PLAN_MAP.md` 的孤立计划；孤立计划以 `WARNING` 提示，不阻断检查。
+- 计划状态是否合法。
+- 计划依赖是否存在环。
+- 活跃计划正文中的计划引用是否与 `PLAN_MAP.md` 依赖列一致；不一致以 `WARNING` 提示。
+- 多个活跃计划是否声明了相同的影响模块或文件；重叠以 `WARNING` 提示。
+- 已完成计划是否有有效 Step 0 证据和验证方式；空章节或纯占位符不视为有效证据。
+- 实施中计划是否依赖已替代、已合并或已废弃计划。
+- 待实施或实施中计划是否仍有未解决的当前阶段阻塞项。
+- 已完成计划是否有测试覆盖率证据。
+- 计划索引是否包含合法的 `最后更新` 日期。
+- `ERROR` 会导致检查失败；`WARNING` 用于提示需要人工复核但不改变退出码的风险。
+
+计划停滞检测使用计划索引中的 `最后更新`，不推断文件修改时间。
+
+已完成计划修改检测需要完成快照或 hash 等独立元数据；当前版本不锁定已完成计划文件，避免修正文档错误时产生误报。公共契约变化关联验证需要计划文档提供结构化目标文件声明；当前版本不做 spec diff 强校验。
+
+## 完成快照
+
+已完成计划可以显式创建完成快照，用于后续发现未复核修改。快照文件写入 `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
+```
+
+`--attest <plan-name>` 只接受已登记到 `docs/PLAN_MAP.md` 的计划。`--check-attestations` 对计划文件 hash 变化、`PLAN_MAP.md` hash 变化、JSON 损坏、文件缺失或快照引用未登记计划输出 `WARNING`，不改变退出码。人工确认文档修正合理后，可以重新运行 `--attest <plan-name>` 覆盖快照。
+
+## 测试覆盖率
+
+本项目使用 `pytest` 和 `pytest-cov` 作为测试与覆盖率门禁。首次运行前安装开发依赖：
+
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
+
+运行测试：
+
+```bash
+python3 -m pytest
+```
+
+覆盖率规则定义在 `pyproject.toml`：
+
+- 统计 `scripts/` 下的 Python 代码。
+- 开启分支覆盖率。
+- 总覆盖率低于 85% 时测试失败。
+- CI 会同时运行测试覆盖率检查和计划治理检查。
+
+## 状态
+
+统一使用中文状态：
+
+| 状态 | 含义 |
+|---|---|
+| `候选` | 记录了想法，但尚未承诺实施 |
+| `设计中` | 正在明确范围、契约和门禁 |
+| `待实施` | 当前阶段门禁已通过，但尚未开始 |
+| `实施中` | 当前阶段正在修改代码或文档 |
+| `已完成` | 实现、测试、证据和文档已同步 |
+| `已替代` | 被另一个计划取代 |
+| `已合并` | 并入另一个计划 |
+| `已废弃` | 明确不再推进 |
+
+### 阶段准入
+
+计划级 `状态` 和 `当前阶段` 由 `docs/PLAN_MAP.md` 维护；专项计划维护当前阶段的准入摘要和独立复核证据。阶段 N 完成后，阶段 N+1 默认保持 `设计中`，不能直接标记为 `待实施`。
+
+进入 `待实施` 前，当前阶段必须有明确目标/范围、Step 0 基线、样本或替代基线矩阵、可执行验证方式、失败与回滚边界、无未解决阻塞项，以及最新独立准入复核“通过”。复核记录追加保留，`PLAN_MAP.md` 只链接最新有效结论。
+
+阶段准入严格检查命令为 `--strict-readiness`。默认检查先以 `WARNING` 提示历史文档中的机械缺陷；严格模式才返回非零退出码。该检查只判断结构化准入条件，不替代业务验收。
+
+## Codex 使用方式
+
+如果已经安装本地 Codex skill，可以在对话中触发：
+
+```text
+$plan-governance 为这个项目初始化计划治理，计划名是 api-compat-migration，标题是 API 兼容性迁移。
+```
+
+或继续推进已有计划：
+
+```text
+$plan-governance 继续推进 docs/plans/api-compat-migration.md 的当前阶段，完成后记录验证证据。
+```
+
+skill 只负责让 Codex 按流程工作；真实计划状态仍然保存在项目仓库的 `docs/` 中。
+
+## 核心规则
+
+- 普通任务直接做，不引入治理。
+- 当前阶段写细，后续阶段写粗。
+- 实施前先固定 Step 0 证据。
+- 决策、计划、契约和证据各有权威位置，不重复定义同一事实。
+- 路线图和优先级计划只保留排序、状态摘要和链接，不复制专项计划细节。
+- 验收治理文档时必须做反向引用检查。
+- 验收者不得仅依据计划状态、完成证据文字或文档格式判定完成；必须基于当前仓库内容、可复现验证命令和反向引用检查独立确认。
+- 启用治理后，旧草案停止承载新规范；后续需求默认进入治理文档。
+- 如果新信息改变计划顺序、公共契约、兼容承诺或完成条件，先更新治理文档，再继续实施。
+
+完整设计见 [plan-governance-design.md](plan-governance-design.md)。

package/bin/plan-governance-cli.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { accessSync, constants } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const checker = resolve(packageRoot, "scripts", "check_plan_governance.py");
+
+try {
+  accessSync(checker, constants.R_OK);
+} catch (error) {
+  console.error(`plan-governance-cli: 找不到包内检查器：${checker}`);
+  process.exit(1);
+}
+
+const args = [checker, ...process.argv.slice(2)];
+const candidates = process.env.PYTHON ? [process.env.PYTHON] : ["python3", "python"];
+
+let result;
+for (const command of candidates) {
+  result = spawnSync(command, args, { stdio: "inherit" });
+  if (!result.error || result.error.code !== "ENOENT") {
+    break;
+  }
+}
+
+if (result?.error) {
+  console.error(`plan-governance-cli: 无法启动 Python 检查器：${result.error.message}`);
+  process.exit(1);
+}
+
+if (result?.signal) {
+  console.error(`plan-governance-cli: 检查器被信号 ${result.signal} 终止`);
+  process.exit(1);
+}
+
+process.exit(result?.status ?? 1);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "plan-governance-cli",
+  "version": "0.1.0",
+  "description": "统一入口的计划治理检查 CLI",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "plan-governance-cli": "bin/plan-governance-cli.mjs"
+  },
+  "files": [
+    "bin/plan-governance-cli.mjs",
+    "scripts/check_plan_governance.py"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test tests/npm_cli.test.mjs"
+  }
+}

package/scripts/check_plan_governance.py

@@ -0,0 +1,748 @@
+#!/usr/bin/env python3
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+VALID_STATUSES = {
+    "候选",
+    "设计中",
+    "待实施",
+    "实施中",
+    "已完成",
+    "已替代",
+    "已合并",
+    "已废弃",
+}
+
+PLACEHOLDER_VALUES = {"-", "待补充", "待补充。", "待确认", "无", "N/A"}
+
+COMPLETED = {"已完成"}
+ACTIVE = {"待实施", "实施中"}
+WARNING_ACTIVE = {"候选", "设计中", "待实施", "实施中"}
+IMPLEMENTING = {"实施中"}
+INACTIVE = {"已替代", "已合并", "已废弃"}
+
+
+def fail(errors, message):
+    errors.append(message)
+
+
+def warn(warnings, message):
+    warnings.append(message)
+
+
+def read_utf8(path, errors):
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        fail(errors, f"{path}: not valid UTF-8")
+    except FileNotFoundError:
+        fail(errors, f"{path}: file not found")
+    return ""
+
+
+def table_rows(text, heading):
+    pattern = re.compile(rf"^##\s+{re.escape(heading)}\s*$", re.MULTILINE)
+    match = pattern.search(text)
+    if not match:
+        return []
+    tail = text[match.end():]
+    next_heading = re.search(r"^##\s+", tail, re.MULTILINE)
+    section = tail[: next_heading.start()] if next_heading else tail
+    rows = []
+    for line in section.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|") or "---" in stripped:
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if cells and cells[0] not in {"计划", "问题"}:
+            rows.append(cells)
+    return rows
+
+
+def mask_fenced_code(text):
+    """用等长空格屏蔽 fenced code 中的伪 Markdown 标题，保留偏移量。"""
+    masked = []
+    in_fence = False
+    for line in text.splitlines(keepends=True):
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            masked.append("".join("\n" if char == "\n" else "\r" if char == "\r" else " " for char in line))
+            continue
+        if in_fence:
+            masked.append("".join("\n" if char == "\n" else "\r" if char == "\r" else " " for char in line))
+        else:
+            masked.append(line)
+    return "".join(masked)
+
+
+def markdown_section(text, heading_names):
+    heading_pattern = "|".join(re.escape(name) for name in heading_names)
+    pattern = re.compile(rf"^#+\s+({heading_pattern})\b.*$", re.MULTILINE)
+    match = pattern.search(mask_fenced_code(text))
+    if not match:
+        return None
+    tail = text[match.end():]
+    next_heading = re.search(r"^#+\s+", tail, re.MULTILINE)
+    return tail[: next_heading.start()] if next_heading else tail
+
+
+def markdown_table_rows(section):
+    if section is None:
+        return []
+    rows = []
+    for line in section.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|") or "---" in stripped:
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if cells:
+            rows.append(cells)
+    return rows
+
+
+def key_value_table(section):
+    values = {}
+    for row in markdown_table_rows(section):
+        if len(row) < 2 or row[0] in {"字段", "问题"}:
+            continue
+        values[row[0]] = row[1]
+    return values
+
+
+def phase_roadmap_rows(plan_text):
+    section = markdown_section(plan_text, ["阶段路线图"])
+    return [row for row in markdown_table_rows(section) if row and row[0] != "阶段"]
+
+
+def review_history_rows(plan_text):
+    section = markdown_section(plan_text, ["独立复核记录"])
+    return [row for row in markdown_table_rows(section) if row and row[0] != "日期"]
+
+
+def is_placeholder(value, allow_empty=False):
+    normalized = re.sub(r"\s+", "", value or "")
+    if not normalized:
+        return allow_empty
+    return normalized in {re.sub(r"\s+", "", item) for item in PLACEHOLDER_VALUES}
+
+
+READINESS_FIELDS = {
+    "准入状态",
+    "Step 0",
+    "样本矩阵",
+    "验证方式",
+    "失败/回滚边界",
+    "当前阻塞项",
+    "最新独立准入复核",
+}
+
+
+def readiness_issue(warnings, errors, strict, message):
+    if strict:
+        fail(errors, message)
+    else:
+        warn(warnings, message)
+
+
+def check_phase_readiness(plan_map_text, plan_name, data, plan_text, strict, warnings, errors):
+    """检查待实施/实施中计划的阶段准入结构，不判断业务证据真实性。"""
+    if data["status"] not in ACTIVE:
+        return
+
+    current_phase = data["phase"]
+    roadmap = phase_roadmap_rows(plan_text)
+    matching_rows = [row for row in roadmap if row and row[0] == current_phase]
+    if not matching_rows:
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: PLAN_MAP 当前阶段 {current_phase} 未在计划阶段路线图中找到",
+        )
+    else:
+        roadmap_status = matching_rows[-1][4] if len(matching_rows[-1]) > 4 else ""
+        if roadmap_status and roadmap_status != data["status"]:
+            readiness_issue(
+                warnings,
+                errors,
+                strict,
+                f"{plan_name}: 当前阶段 {current_phase} 的路线图状态 {roadmap_status} 与 PLAN_MAP 状态 {data['status']} 不一致",
+            )
+
+    if markdown_section(plan_text, ["当前阶段"]) is None:
+        readiness_issue(warnings, errors, strict, f"{plan_name}: 缺少 `## 当前阶段` 章节")
+
+    summary = key_value_table(markdown_section(plan_text, ["阶段准入摘要"]))
+    missing_fields = sorted(READINESS_FIELDS - set(summary))
+    if missing_fields:
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 阶段准入摘要缺少字段：{', '.join(missing_fields)}",
+        )
+    for field in sorted(READINESS_FIELDS - {"当前阻塞项"}):
+        if field in summary and is_placeholder(summary[field]):
+            readiness_issue(
+                warnings,
+                errors,
+                strict,
+                f"{plan_name}: 阶段准入摘要字段 {field} 仍是占位内容",
+            )
+    if summary.get("当前阻塞项") and is_placeholder(summary["当前阻塞项"]) and summary["当前阻塞项"].strip() != "无":
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 阶段准入摘要的当前阻塞项不可使用占位内容",
+        )
+    if summary.get("准入状态") and summary["准入状态"] != data["status"]:
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 阶段准入摘要状态 {summary['准入状态']} 与 PLAN_MAP 状态 {data['status']} 不一致",
+        )
+
+    review = key_value_table(markdown_section(plan_text, ["最新独立准入复核"]))
+    review_fields = {"日期", "阶段", "结论", "证据", "复核者"}
+    missing_review = sorted(review_fields - set(review))
+    if missing_review:
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 最新独立准入复核缺少字段：{', '.join(missing_review)}",
+        )
+    if review.get("日期"):
+        try:
+            parse_plan_date(review["日期"])
+        except ValueError:
+            readiness_issue(warnings, errors, strict, f"{plan_name}: 最新独立准入复核日期不合法：{review['日期']}")
+    if review.get("阶段") and review["阶段"] != current_phase:
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 最新独立准入复核阶段 {review['阶段']} 与 PLAN_MAP 当前阶段 {current_phase} 不一致",
+        )
+    if review.get("结论") and not review["结论"].startswith("通过"):
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 最新独立准入复核结论不是通过：{review['结论']}",
+        )
+
+    history = [row for row in review_history_rows(plan_text) if len(row) >= 4 and row[2] == current_phase]
+    if not history:
+        readiness_issue(warnings, errors, strict, f"{plan_name}: 独立复核记录缺少当前阶段 {current_phase} 的记录")
+    else:
+        latest_history = history[-1]
+        if review.get("日期") and latest_history[0] != review["日期"]:
+            readiness_issue(
+                warnings,
+                errors,
+                strict,
+                f"{plan_name}: 最新独立准入复核日期与历史记录最后一条不一致",
+            )
+        if review.get("结论") and latest_history[3] not in review["结论"]:
+            readiness_issue(
+                warnings,
+                errors,
+                strict,
+                f"{plan_name}: 最新独立准入复核与历史记录最后一条结论冲突",
+            )
+
+
+def markdown_list_items(section):
+    if section is None:
+        return []
+    items = []
+    for line in section.splitlines():
+        match = re.match(r"\s*[-*]\s+(.+?)\s*$", line)
+        if not match:
+            continue
+        item = match.group(1).strip()
+        item = item.strip("` ")
+        if item and item not in PLACEHOLDER_VALUES:
+            items.append(item)
+    return items
+
+
+def normalize_scope_path(value):
+    normalized = value.strip().strip("`").strip()
+    normalized = re.sub(r"/+", "/", normalized)
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    normalized = normalized.strip("/")
+    return normalized
+
+
+def extract_scope_token(item):
+    backtick = re.search(r"`([^`]+)`", item)
+    if backtick:
+        return normalize_scope_path(backtick.group(1))
+    token = item.strip().split(None, 1)[0] if item.strip() else ""
+    return normalize_scope_path(token.rstrip(":："))
+
+
+def extract_plan_link(cell):
+    match = re.search(r"\((plans/[^)]+\.md)\)", cell)
+    if match:
+        return match.group(1)
+    if cell.endswith(".md") and cell.startswith("plans/"):
+        return cell
+    return None
+
+
+def extract_declared_dependencies(depends_cell):
+    return [d.strip("` ") for d in re.split(r",|<br>|、", depends_cell) if d.strip("` -")]
+
+
+def parse_plan_date(value):
+    return datetime.strptime(value.strip(), "%Y-%m-%d").date()
+
+
+def extract_affected_targets(plan_text):
+    section = markdown_section(plan_text, ["影响模块或文件"])
+    targets = []
+    for item in markdown_list_items(section):
+        target = extract_scope_token(item)
+        if target and target not in PLACEHOLDER_VALUES:
+            targets.append(target)
+    return targets
+
+
+def extract_plan_references(plan_text, known_plans, current_name):
+    references = set()
+    for match in re.finditer(r"\[\[([^\]]+)\]\]", plan_text):
+        name = Path(match.group(1).strip()).stem
+        if name in known_plans and name != current_name:
+            references.add(name)
+
+    for match in re.finditer(r"(?:docs/)?plans/([A-Za-z0-9\u4e00-\u9fff._-]+)\.md", plan_text):
+        name = Path(match.group(1).strip()).stem
+        if name in known_plans and name != current_name:
+            references.add(name)
+
+    for match in re.finditer(r"\]\(([A-Za-z0-9\u4e00-\u9fff._-]+)\.md(?:#[^)]+)?\)", plan_text):
+        name = Path(match.group(1).strip()).stem
+        if name in known_plans and name != current_name:
+            references.add(name)
+
+    return references
+
+
+def has_substantive_evidence(content):
+    if content is None:
+        return False
+
+    stripped = content.strip()
+    if not stripped:
+        return False
+    if re.search(r"^(待补充|TODO|TBD|待确认)[。.\s]*$", stripped, re.IGNORECASE):
+        return False
+
+    evidence_patterns = [
+        r"```",
+        r"\b(python3|python|pytest|bash|sh|rg|npm|make|curl|git)\b",
+        r"[\w./-]+/(?:[\w./-]+)",
+        r"\b(?:commit|hash)\s+[0-9a-f]{6,40}\b",
+        r"\bv?\d+\.\d+(?:\.\d+)?\b",
+        r"\d+(?:\.\d+)?%",
+        r"(基线|复现|样本|fixture|测试|验证|运行|失败案例|现状|快照|报告|覆盖率|命令|搜索)",
+    ]
+    if any(re.search(pattern, stripped, re.IGNORECASE) for pattern in evidence_patterns):
+        return True
+
+    normalized = re.sub(r"\s+", "", stripped)
+    return len(normalized) >= 40
+
+
+def has_completion_evidence(plan_text):
+    evidence = markdown_section(plan_text, ["Step 0 Evidence", "Step 0 证据", "完成证据", "验证证据"])
+    validation = markdown_section(plan_text, ["验证方式", "验证"])
+    return has_substantive_evidence(evidence) and has_substantive_evidence(validation)
+
+
+def has_coverage_evidence(plan_text):
+    """已完成计划是否包含非占位的测试覆盖率证据章节。"""
+    section = markdown_section(plan_text, ["测试覆盖率", "测试覆盖", "覆盖率报告", "Coverage", "Test Coverage"])
+    if section is None:
+        return False
+    content = section.strip()
+    if not content or re.search(r"^(待补充|TODO|TBD)[。.\s]*$", content, re.IGNORECASE):
+        return False
+
+    return bool(re.search(r"(\d+(?:\.\d+)?%|pytest|coverage|覆盖率|测试通过|passed)", content, re.IGNORECASE))
+
+
+def has_current_blocker(plan_text):
+    for row in table_rows(plan_text, "未决问题"):
+        joined = "|".join(row)
+        if re.search(r"\b(Yes|是)\b", joined) and re.search(r"(Open|待确认|未解决|待处理|未决定)", joined, re.IGNORECASE):
+            return True
+    return False
+
+
+def find_orphan_plans(docs, plans):
+    plans_dir = docs / "plans"
+    if not plans_dir.exists():
+        return []
+    indexed_paths = {data["path"].resolve() for data in plans.values()}
+    return sorted(
+        plan_file
+        for plan_file in plans_dir.glob("*.md")
+        if plan_file.resolve() not in indexed_paths
+    )
+
+
+def detect_overlapping_targets(active_plan_targets):
+    target_to_plans = {}
+    for plan_name, targets in active_plan_targets.items():
+        for target in targets:
+            target_to_plans.setdefault(target, []).append(plan_name)
+    return {
+        target: sorted(plan_names)
+        for target, plan_names in target_to_plans.items()
+        if len(plan_names) > 1
+    }
+
+
+def target_matches_path(target, changed_file):
+    normalized_target = normalize_scope_path(target)
+    normalized_file = normalize_scope_path(changed_file)
+    if not normalized_target or not normalized_file:
+        return False
+    if normalized_target == normalized_file:
+        return True
+    return normalized_file.startswith(f"{normalized_target}/")
+
+
+def uncovered_changed_files(changed_files, active_plan_targets):
+    targets = [
+        target
+        for targets_for_plan in active_plan_targets.values()
+        for target in targets_for_plan
+    ]
+    return sorted(
+        changed_file
+        for changed_file in changed_files
+        if not any(target_matches_path(target, changed_file) for target in targets)
+    )
+
+
+def git_name_only(root, git_args):
+    result = subprocess.run(
+        ["git", *git_args],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return {
+        line.strip()
+        for line in result.stdout.splitlines()
+        if line.strip()
+    }
+
+
+def changed_files(root, staged=False):
+    if staged:
+        return git_name_only(root, ["diff", "--cached", "--name-only", "--diff-filter=ACMR"])
+
+    files = set()
+    files.update(git_name_only(root, ["diff", "--name-only", "--diff-filter=ACMR"]))
+    files.update(git_name_only(root, ["diff", "--cached", "--name-only", "--diff-filter=ACMR"]))
+    files.update(git_name_only(root, ["ls-files", "--others", "--exclude-standard"]))
+    return files
+
+
+def warn_uncovered_changes(warnings, mode, files, active_plan_targets):
+    if not files:
+        return
+    if not active_plan_targets:
+        warn(warnings, f"{mode}: 存在变更文件，但没有活跃计划声明影响范围")
+        return
+    for changed_file in uncovered_changed_files(files, active_plan_targets):
+        warn(warnings, f"{mode}: 变更文件未被活跃计划影响范围覆盖：{changed_file}")
+
+
+def warn_stale_plans(warnings, plans, stale_days, today=None):
+    today = today or date.today()
+    for name, data in plans.items():
+        if data["status"] not in WARNING_ACTIVE:
+            continue
+        age = (today - data["last_updated_date"]).days
+        if age > stale_days:
+            warn(
+                warnings,
+                f"{name}: 活跃计划已 {age} 天未更新，超过 --stale-days {stale_days} 阈值",
+            )
+
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def relative_to_root(path, root):
+    return path.relative_to(root).as_posix()
+
+
+def create_attestation(root, plan_map, plans, plan_name, errors):
+    data = plans.get(plan_name)
+    if data is None:
+        fail(errors, f"{plan_name}: 未登记计划，无法创建完成快照")
+        return None
+    if not data["path"].exists():
+        fail(errors, f"{plan_name}: 计划文件不存在，无法创建完成快照")
+        return None
+
+    attestation = {
+        "plan": plan_name,
+        "phase": data["phase"],
+        "status": data["status"],
+        "plan_path": relative_to_root(data["path"], root),
+        "plan_map_path": relative_to_root(plan_map, root),
+        "plan_sha256": sha256_file(data["path"]),
+        "plan_map_sha256": sha256_file(plan_map),
+        "created_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "created_by": "plan-governance",
+        "reason": "阶段完成快照",
+    }
+    target = root / "docs" / "attestations" / f"{plan_name}.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(attestation, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return target
+
+
+def warn_attestation_drift(warnings, root, plans):
+    attestations_dir = root / "docs" / "attestations"
+    if not attestations_dir.exists():
+        return
+
+    for path in sorted(attestations_dir.glob("*.json")):
+        try:
+            attestation = json.loads(path.read_text(encoding="utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            warn(warnings, f"{path}: attestation JSON 无法解析：{exc}")
+            continue
+
+        plan_name = str(attestation.get("plan", "")).strip()
+        if not plan_name or plan_name not in plans:
+            warn(warnings, f"{path}: 快照引用了未登记计划：{plan_name or '<missing>'}")
+            continue
+
+        plan_path = root / str(attestation.get("plan_path", ""))
+        plan_map_path = root / str(attestation.get("plan_map_path", "docs/PLAN_MAP.md"))
+        if not plan_path.exists():
+            warn(warnings, f"{path}: 快照引用的计划文件不存在：{plan_path}")
+            continue
+        if not plan_map_path.exists():
+            warn(warnings, f"{path}: 快照引用的 PLAN_MAP.md 不存在：{plan_map_path}")
+            continue
+
+        if sha256_file(plan_path) != attestation.get("plan_sha256"):
+            warn(warnings, f"{path}: {plan_name} 计划文件 hash 已变化，需要人工复核")
+        if sha256_file(plan_map_path) != attestation.get("plan_map_sha256"):
+            warn(warnings, f"{path}: PLAN_MAP.md hash 已变化，需要人工复核")
+
+
+def detect_dependency_cycles(edges):
+    visited = set()
+    stack = set()
+    cycles = []
+
+    def visit(node, path):
+        if node in stack:
+            cycles.append(" -> ".join(path + [node]))
+            return
+        if node in visited:
+            return
+        visited.add(node)
+        stack.add(node)
+        for dep in edges.get(node, []):
+            visit(dep, path + [node])
+        stack.remove(node)
+
+    for node in edges:
+        visit(node, [])
+    return cycles
+
+
+def parse_args(argv):
+    parser = argparse.ArgumentParser(description="检查计划治理文档的一致性。")
+    parser.add_argument("root", nargs="?", default=".", help="仓库根目录，默认当前目录。")
+    parser.add_argument("--drift", action="store_true", help="检查工作区变更是否被活跃计划影响范围覆盖。")
+    parser.add_argument("--pre-commit", action="store_true", help="检查 staged 变更是否被活跃计划影响范围覆盖。")
+    parser.add_argument(
+        "--strict-readiness",
+        action="store_true",
+        help="将待实施/实施中计划的阶段准入结构缺陷从 WARNING 提升为 ERROR。",
+    )
+    parser.add_argument("--attest", metavar="PLAN", help="为已登记计划创建或覆盖完成快照。")
+    parser.add_argument("--check-attestations", action="store_true", help="检查完成快照 hash 是否漂移。")
+    parser.add_argument(
+        "--stale-days",
+        nargs="?",
+        const=10,
+        type=int,
+        default=None,
+        help="检查活跃计划是否超过 N 天未更新；省略 N 时默认 10 天。",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv=None):
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+    root = Path(args.root)
+    docs = root / "docs"
+    plan_map = docs / "PLAN_MAP.md"
+    errors = []
+    warnings = []
+
+    if not plan_map.exists():
+        print("未找到 docs/PLAN_MAP.md；当前仓库尚未初始化计划治理。")
+        return 0
+
+    text = read_utf8(plan_map, errors)
+    plan_rows = table_rows(text, "计划索引")
+    if not plan_rows:
+        fail(errors, "docs/PLAN_MAP.md: 缺少计划索引表")
+
+    plans = {}
+    for row in plan_rows:
+        if len(row) < 2:
+            continue
+        if len(row) < 6:
+            fail(errors, "docs/PLAN_MAP.md: 计划索引表必须包含 `最后更新` 列")
+            continue
+        link = extract_plan_link(row[0])
+        name = Path(link).stem if link else row[0].strip("` ")
+        status = row[1].strip("` ")
+        last_updated = row[3].strip("` ")
+        if status not in VALID_STATUSES:
+            fail(errors, f"docs/PLAN_MAP.md: {name} 的状态不合法：{status}")
+        try:
+            last_updated_date = parse_plan_date(last_updated)
+        except ValueError:
+            fail(errors, f"docs/PLAN_MAP.md: {name} 的最后更新日期不合法：{last_updated}")
+            last_updated_date = date.min
+        if link:
+            path = docs / link
+            if not path.exists():
+                fail(errors, f"docs/PLAN_MAP.md: 引用的计划文件不存在：{link}")
+            plans[name] = {
+                "path": path,
+                "status": status,
+                "phase": row[2].strip("` "),
+                "last_updated_date": last_updated_date,
+                "depends": row[4],
+            }
+        else:
+            fail(errors, f"docs/PLAN_MAP.md: 计划行缺少 docs/plans 链接：{row[0]}")
+
+    edges = {}
+    inactive = {name for name, data in plans.items() if data["status"] in INACTIVE}
+    for name, data in plans.items():
+        deps = extract_declared_dependencies(data["depends"])
+        edges[name] = [dep for dep in deps if dep in plans]
+        if data["status"] in IMPLEMENTING:
+            for dep in edges[name]:
+                if dep in inactive:
+                    fail(errors, f"{name}: 实施中计划依赖了非活跃计划 {dep}")
+
+    for cycle in detect_dependency_cycles(edges):
+        fail(errors, f"计划依赖存在环：{cycle}")
+
+    for orphan in find_orphan_plans(docs, plans):
+        warn(warnings, f"{orphan}: docs/plans 中存在未登记到 PLAN_MAP.md 的孤立计划")
+
+    active_plan_targets = {}
+    plan_texts = {}
+    for name, data in plans.items():
+        plan_text = read_utf8(data["path"], errors)
+        plan_texts[name] = plan_text
+        if data["status"] in COMPLETED and not has_completion_evidence(plan_text):
+            fail(errors, f"{data['path']}: 已完成计划缺少有效 Step 0 证据或验证方式")
+        if data["status"] in COMPLETED and not has_coverage_evidence(plan_text):
+            fail(errors, f"{data['path']}: 已完成计划缺少测试覆盖率证据")
+        if data["status"] in ACTIVE and has_current_blocker(plan_text):
+            fail(errors, f"{data['path']}: 活跃计划仍有未解决的当前阶段阻塞项")
+        if data["status"] in WARNING_ACTIVE:
+            active_plan_targets[name] = extract_affected_targets(plan_text)
+
+        check_phase_readiness(
+            text,
+            name,
+            data,
+            plan_text,
+            args.strict_readiness,
+            warnings,
+            errors,
+        )
+
+    for target, plan_names in detect_overlapping_targets(active_plan_targets).items():
+        warn(warnings, f"{target}: 多个活跃计划声明相同影响目标：{', '.join(plan_names)}")
+
+    known_plans = set(plans)
+    for name, data in plans.items():
+        if data["status"] not in WARNING_ACTIVE:
+            continue
+        declared = set(edges.get(name, []))
+        referenced = extract_plan_references(plan_texts.get(name, ""), known_plans, name)
+        for missing in sorted(referenced - declared):
+            warn(warnings, f"{name}: 正文引用了计划 {missing}，但 PLAN_MAP.md 依赖列未声明")
+        for unreferenced in sorted(declared - referenced):
+            warn(warnings, f"{name}: PLAN_MAP.md 声明依赖 {unreferenced}，但计划正文未引用")
+
+    try:
+        if args.drift:
+            warn_uncovered_changes(warnings, "--drift", changed_files(root), active_plan_targets)
+        if args.pre_commit:
+            warn_uncovered_changes(warnings, "--pre-commit", changed_files(root, staged=True), active_plan_targets)
+    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+        warn(warnings, f"Git 变更检查不可用：{exc}")
+
+    if args.stale_days is not None:
+        if args.stale_days < 0:
+            fail(errors, f"--stale-days 必须是非负整数：{args.stale_days}")
+        else:
+            warn_stale_plans(warnings, plans, args.stale_days)
+
+    if args.check_attestations:
+        warn_attestation_drift(warnings, root, plans)
+
+    attested_path = None
+    if args.attest:
+        attested_path = create_attestation(root, plan_map, plans, args.attest, errors)
+
+    for warning in warnings:
+        print(f"WARNING: {warning}")
+
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}")
+        return 1
+
+    if attested_path is not None:
+        print(f"已创建完成快照：{attested_path}")
+
+    print("计划治理检查通过。")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())