plan-governance-cli 0.1.0 → 0.2.0

package/README.md

@@ -166,7 +166,7 @@ plan-governance-cli . --strict-readiness
 也可以不全局安装，直接使用锁定版本：
 
 ```bash
-npx --yes plan-governance-cli@0.1.0 . --strict-readiness
+npx --yes --package plan-governance-cli@0.2.0 plan-governance-cli . --strict-readiness
 ```
 
 npm CLI 只是统一入口，实际检查逻辑仍由包内版本化的 Python 检查器执行；迁移期间项目原有 Python 命令仍可作为回滚路径。
@@ -181,6 +181,24 @@ npm CLI 只是统一入口，实际检查逻辑仍由包内版本化的 Python
 
 `--stale-days` 会检查活跃计划的 `最后更新` 日期是否超过阈值；省略数值时默认 10 天。停滞检测只输出 `WARNING`，不自动改变计划状态。
 
+安装后的资源管理：
+
+```bash
+plan-governance-cli setup --target codex --dry-run
+plan-governance-cli setup --target claude --dry-run
+plan-governance-cli setup --target all
+```
+
+`setup` 只同步 npm 包 manifest 指定的 skill、代理元数据和模板文件；默认先用 `--dry-run` 查看差异，目标文件有本地修改时不会静默覆盖。检查器、初始化器和 hook runtime 由 npm 包内部调用，不复制到项目或 skill 目录。当前版本不自动安装 hook 配置。
+
+初始化项目时使用包内初始化器：
+
+```bash
+plan-governance-cli init --root . --plan api-compat-migration --title "API 兼容性迁移" --goal "分阶段完成 API 兼容性迁移"
+```
+
+`init` 默认不复制项目本地 `scripts/check_plan_governance.py`；如确有兼容需要，才显式传递底层 `--copy-checker` 参数。
+
 ## Hook runtime
 
 本仓库提供只读 hook runtime，供 Codex、Claude Code 或其他 Agent 的项目级 hooks 手动接入。脚本只输出短提示和检查结果，不修改治理文档，不更新 `最后更新`，不安装或修改全局配置。

package/bin/plan-governance-cli.mjs

@@ -1,39 +1,179 @@
 #!/usr/bin/env node
 
-import { accessSync, constants } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const checker = resolve(packageRoot, "scripts", "check_plan_governance.py");
+const initializer = resolve(packageRoot, "scripts", "init_plan_governance.py");
+const hookRuntime = resolve(packageRoot, "scripts", "plan_governance_hook.py");
+const manifestPath = resolve(packageRoot, "resources", "manifest.json");
 
-try {
-  accessSync(checker, constants.R_OK);
-} catch (error) {
-  console.error(`plan-governance-cli: 找不到包内检查器：${checker}`);
-  process.exit(1);
+function fail(message) {
+  console.error(`plan-governance-cli: ${message}`);
+  return 1;
+}
+
+function runPython(script, args) {
+  try {
+    accessSync(script, constants.R_OK);
+  } catch {
+    return fail(`找不到包内脚本：${script}`);
+  }
+
+  const candidates = process.env.PYTHON ? [process.env.PYTHON] : ["python3", "python"];
+  let result;
+  for (const command of candidates) {
+    result = spawnSync(command, [script, ...args], { stdio: "inherit" });
+    if (!result.error || result.error.code !== "ENOENT") {
+      break;
+    }
+  }
+
+  if (result?.error) {
+    return fail(`无法启动 Python 脚本：${result.error.message}`);
+  }
+  if (result?.signal) {
+    console.error(`plan-governance-cli: 脚本被信号 ${result.signal} 终止`);
+    return 1;
+  }
+  return result?.status ?? 1;
 }
 
-const args = [checker, ...process.argv.slice(2)];
-const candidates = process.env.PYTHON ? [process.env.PYTHON] : ["python3", "python"];
+function loadManifest() {
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`无法读取包内资源清单：${error.message}`);
+  }
+}
+
+function parseSetupArgs(args) {
+  const options = { target: null, destination: null, dryRun: false, force: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--target") {
+      options.target = args[++index];
+    } else if (arg === "--destination") {
+      options.destination = args[++index];
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "-h" || arg === "--help") {
+      console.log("用法：plan-governance-cli setup --target codex|claude|all [--destination DIR] [--dry-run] [--force]");
+      return null;
+    } else {
+      throw new Error(`setup 不支持参数：${arg}`);
+    }
+  }
 
-let result;
-for (const command of candidates) {
-  result = spawnSync(command, args, { stdio: "inherit" });
-  if (!result.error || result.error.code !== "ENOENT") {
-    break;
+  if (!options.target || !["codex", "claude", "all"].includes(options.target)) {
+    throw new Error("setup 必须指定 --target codex、claude 或 all");
   }
+  if (options.destination && options.target === "all") {
+    throw new Error("--destination 只能与单个 setup target 一起使用");
+  }
+  return options;
+}
+
+function expandTarget(target) {
+  const home = process.env.HOME || homedir();
+  return target.replace(/^~(?=\/|$)/, home);
+}
+
+function targetRoots(manifest, options) {
+  const names = options.target === "all" ? ["codex", "claude"] : [options.target];
+  return names.map((name) => ({
+    name,
+    root: resolve(options.destination ? options.destination : expandTarget(manifest.skill.targets[name])),
+  }));
+}
+
+function resourceFiles(manifest) {
+  const skillPrefix = "resources/skill/";
+  return manifest.skill.files.map((source) => {
+    if (!source.startsWith(skillPrefix)) {
+      throw new Error(`skill 资源不在受支持的目录中：${source}`);
+    }
+    return {
+      source: resolve(packageRoot, source),
+      relative: source.slice(skillPrefix.length),
+    };
+  });
 }
 
-if (result?.error) {
-  console.error(`plan-governance-cli: 无法启动 Python 检查器：${result.error.message}`);
-  process.exit(1);
+function setup(args) {
+  const options = parseSetupArgs(args);
+  if (options === null) return 0;
+
+  let manifest;
+  let files;
+  try {
+    manifest = loadManifest();
+    files = resourceFiles(manifest);
+  } catch (error) {
+    return fail(error.message);
+  }
+
+  const plans = [];
+  try {
+    for (const target of targetRoots(manifest, options)) {
+      for (const file of files) {
+        accessSync(file.source, constants.R_OK);
+        const destination = resolve(target.root, file.relative);
+        const existing = existsSync(destination) ? readFileSync(destination, "utf8") : null;
+        const sourceContent = readFileSync(file.source, "utf8");
+        if (existing !== null && existing !== sourceContent && !options.force) {
+          throw new Error(`目标文件存在本地差异，未覆盖：${destination}（如确认覆盖请加 --force）`);
+        }
+        plans.push({ target: target.name, destination, existing, sourceContent });
+      }
+    }
+  } catch (error) {
+    return fail(error.message);
+  }
+
+  for (const plan of plans) {
+    if (plan.existing === plan.sourceContent) {
+      console.log(`已是最新：${plan.destination}`);
+    } else if (options.dryRun) {
+      console.log(`将写入：${plan.destination}`);
+    } else {
+      mkdirSync(dirname(plan.destination), { recursive: true });
+      const temporary = join(tmpdir(), `plan-governance-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+      writeFileSync(temporary, plan.sourceContent, "utf8");
+      renameSync(temporary, plan.destination);
+      console.log(`已同步：${plan.destination}`);
+    }
+  }
+  if (options.dryRun) console.log("setup dry-run 完成，未修改目标目录。");
+  return 0;
 }
 
-if (result?.signal) {
-  console.error(`plan-governance-cli: 检查器被信号 ${result.signal} 终止`);
-  process.exit(1);
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  if (command === "setup") return setup(args.slice(1));
+  if (command === "init") return runPython(initializer, args.slice(1));
+  if (command === "hook") return runPython(hookRuntime, args.slice(1));
+  if (command === "check") return runPython(checker, args.slice(1));
+  return runPython(checker, args);
 }
 
-process.exit(result?.status ?? 1);
+try {
+  process.exitCode = main();
+} catch (error) {
+  process.exitCode = fail(error.message);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "统一入口的计划治理检查 CLI",
   "private": false,
   "type": "module",
@@ -9,7 +9,11 @@
   },
   "files": [
     "bin/plan-governance-cli.mjs",
-    "scripts/check_plan_governance.py"
+    "resources/manifest.json",
+    "resources/skill",
+    "scripts/check_plan_governance.py",
+    "scripts/init_plan_governance.py",
+    "scripts/plan_governance_hook.py"
   ],
   "engines": {
     "node": ">=20"

package/resources/manifest.json

@@ -0,0 +1,24 @@
+{
+  "manifestVersion": 1,
+  "skill": {
+    "targets": {
+      "codex": "~/.codex/skills/plan-governance",
+      "claude": "~/.claude/skills/plan-governance"
+    },
+    "files": [
+      "resources/skill/SKILL.md",
+      "resources/skill/agents/openai.yaml",
+      "resources/skill/assets/PLAN_MAP.template.md",
+      "resources/skill/assets/adr.template.md",
+      "resources/skill/assets/migration.template.md",
+      "resources/skill/assets/plan.template.md"
+    ]
+  },
+  "runtime": [
+    "scripts/check_plan_governance.py",
+    "scripts/init_plan_governance.py",
+    "scripts/plan_governance_hook.py"
+  ],
+  "hooks": []
+}
+

package/resources/skill/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: plan-governance
+description: 轻量计划治理工作流。Use when 用户要求管理路线图、分阶段实施、迁移、架构变更、公共 API 或 Schema 变更、长期任务、计划漂移、ADR、Step 0 证据、PLAN_MAP.md、docs/plans 文件，或希望 Codex 协调多个相关计划，同时避免把普通小任务流程化。
+---
+
+# Plan Governance
+
+使用这个 skill 管理跨阶段、会漂移、需要证据闭环的工作。普通一次性 bugfix、小范围本地修改、互不依赖的待办列表，不要启用治理，除非用户明确要求。
+
+## 启用判定
+
+开始前先给任务打分：
+
+| 信号 | 分数 |
+|---|---:|
+| 跨阶段、里程碑或多轮会话 | 1 |
+| 涉及架构、公共 API、Schema、兼容性或迁移行为 | 1 |
+| 依赖真实运行报告、样本或反馈 | 1 |
+| 多个计划之间存在依赖、替代、重叠或冲突 | 1 |
+| 同一模块会被后续计划反复修改 | 1 |
+
+- `>=3`：初始化或更新持续计划治理。
+- `=2`：先检查已有治理文档，但不主动新建结构，除非确有必要。
+- `<=1`：按普通任务处理。
+- 大型公共契约迁移可以直接启用治理。
+
+## 仓库模型
+
+使用项目内这些文件作为事实来源：
+
+```text
+docs/
+  PLAN_MAP.md
+  plans/
+    <plan-name>.md
+  adr/
+    0001-<decision>.md
+  migrations/
+    <migration-name>.md
+```
+
+只创建有真实内容的文件。不要预建空的 `adr/` 或 `migrations/` 目录。
+
+文档权责：
+
+- `PLAN_MAP.md`：计划索引、状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、当前阻塞项、证据链接。
+- `docs/plans/*.md`：单个计划的目标、范围、阶段、当前阶段步骤、Step 0 证据、验证方式、完成条件、风险、回滚、未决问题。
+- `docs/adr/*.md`：持久架构决策及其后果。
+- `docs/migrations/*.md`：兼容策略、迁移步骤、回滚方式、旧行为保留窗口。
+- spec 或 Schema：精确、可机器校验的契约。
+
+同一事实只定义一次，其他地方通过链接引用。
+
+## 多文档同步规则
+
+- `docs/plans/*.md` 是专项计划的实施细节事实源，记录字段方案、Schema、枚举、Step 0 证据、验证方式和完成条件。
+- `PLAN_MAP.md` 是状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
+- 总路线图、优先级计划和索引只记录顺序、状态摘要和专项计划链接，不复制字段级方案、枚举、Step 0 细节或完成定义。
+- 当专项计划的状态、当前阶段、最后更新、字段方案、完成条件或验证结果变化时，必须同步 `PLAN_MAP.md` 和所有引用该计划的路线图、优先级计划或索引。
+- 验收治理文档时，必须用 `rg` 搜索同名计划、P 编号、状态名和关键字段，检查是否存在重复定义或漂移。
+- 如果同一事实在多个文档中重复，保留一个事实源，其他文档改为链接引用。
+- 实施者填写的计划状态、完成证据文字和文档格式只代表实施声明，不等于验收结论；验收者必须基于当前仓库内容、可复现验证命令和反向引用检查独立确认。
+
+## 草案和历史文档处理
+
+启用计划治理后，已有草案、历史设计、归档计划、superpowers 记录、临时分析文档等默认只作为背景材料，不再作为规范事实源。
+
+- 除非用户明确点名要求更新这些文档，否则不要继续修改它们来承载新规范。
+- 新发生的目标、范围、非目标、公共契约、字段、Schema、状态语义、阶段、验证方式、完成条件、风险和回滚，应写入 `docs/plans/*.md`、ADR、migration 或正式 spec。
+- 计划状态、当前阶段、最后更新、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接，应写入或同步 `docs/PLAN_MAP.md`。
+- 历史草案可以在治理文档中作为背景材料链接引用，但不应承载新的规范事实。
+- 如果治理文档出现“以草案为事实源”“详见草案中的字段定义”“草案为准”等表述，应改为由治理文档自身承载事实源，或链接到正式 spec/Schema。
+- 当用户说“补充一下”“记录一下”“把刚才的结论写进去”时，如果治理已启用，默认写入治理文档；不要写入草案、README 或历史设计文档，除非用户明确点名该文件。
+
+## 推荐状态
+
+统一使用中文状态：
+
+| 状态 | 含义 |
+|---|---|
+| `候选` | 记录了想法，但尚未承诺实施 |
+| `设计中` | 正在明确范围、契约和门禁 |
+| `待实施` | 当前阶段门禁已通过，但尚未开始 |
+| `实施中` | 当前阶段正在修改代码或文档 |
+| `已完成` | 实现、测试、证据和文档已同步 |
+| `已替代` | 被另一个计划取代 |
+| `已合并` | 并入另一个计划 |
+| `已废弃` | 明确不再推进 |
+
+### 阶段转换规则
+
+- 阶段 N 完成只关闭阶段 N，不自动改变阶段 N+1 的准入状态。
+- 阶段 N+1 默认保持 `设计中`，直到完成该阶段自己的 Step 0、验证方式、完成条件和独立准入复核。
+- 只有最新的独立准入复核明确写出“达到 `待实施` 标准”，阶段才可标记为 `待实施`。
+- 不得以阶段 N 的完成证据、全量测试通过、治理脚本通过或实施者声明替代阶段 N+1 的 Step 0。
+- `PLAN_MAP.md` 的 `状态` 是计划级生命周期，`当前阶段` 是阶段身份指针；专项计划只承载该阶段的实施细节和准入证据。
+
+### `待实施` 最低准入条件
+
+当前阶段进入 `待实施` 前，必须同时具备：
+
+1. 当前阶段目标、范围和非目标。
+2. 明确基线类型的 Step 0 证据。
+3. 样本/fixture 矩阵，包含输入或基线、可执行命令、预期结果、失败判定和输出位置；不适合固定样本时必须记录可观察的替代基线。
+4. 验证方式、完成条件、失败策略和回滚或安全边界。
+5. 没有未解决的当前阶段阻塞项，且 `PLAN_MAP.md` 已同步。
+6. 最新独立准入复核明确为“通过”。
+
+阶段准入摘要应使用固定字段：`准入状态`、`Step 0`、`样本矩阵`、`验证方式`、`失败/回滚边界`、`当前阻塞项`、`最新独立准入复核`。阶段身份以 `PLAN_MAP.md` 为准，不在计划正文中另定义阶段编号。
+
+### 独立复核记录
+
+专项计划应保留追加式的独立复核记录，并显式维护最新结论的日期、阶段、结论、证据和复核者。历史记录不得覆盖；新的“未通过”覆盖此前的“通过”，修复后的新“通过”必须追加新记录。`PLAN_MAP.md` 只链接最新有效结论，不复制历史表格。
+
+阶段准入检查命令为 `--strict-readiness`。默认治理检查保持兼容，面向历史文档的准入缺陷先以 `WARNING` 提示；严格模式才将机械准入缺陷提升为 `ERROR`。该检查只判断结构化准入条件，不替代业务验收。
+
+## 工作流
+
+1. 检查仓库是否已有 `docs/PLAN_MAP.md` 和相关计划。
+2. 按启用判定决定是否需要治理。
+3. 如果需要初始化，优先运行源仓库脚本 `/Users/jafish/Documents/work/plan-governance/scripts/init_plan_governance.py` 生成最小结构；只有需要特殊改写时才手动复制 `assets/` 模板。已有项目不要重新初始化计划文档，使用 `--update-agent-rules-only` 或 `--upgrade-existing`。升级其他项目时必须从这个源仓库运行脚本，不要调用目标项目里的旧 `scripts/init_plan_governance.py`。旧项目若 `PLAN_MAP.md` 还是五列表，使用 `--migrate-plan-map-last-updated` 显式迁移。
+4. 初始化治理文档后，立即执行事实源切换：识别已有 README、草案、旧计划、归档设计文档，将它们视为背景材料或历史记录；从此刻起，新规范只写入 `docs/plans/*.md`、`PLAN_MAP.md`、ADR、migration 或正式 spec，除非用户明确要求，不再编辑旧草案。
+5. 实施前让当前阶段可执行：
+   - 目标、范围、非目标明确
+   - 必要的不变量和信任边界明确
+   - 必要的公共契约和失败策略明确
+   - Step 0 证据存在
+   - 验证方式可运行
+   - 当前阶段没有未解决阻塞项
+6. 只实施当前阶段。后续阶段保持粗粒度。
+7. 新信息改变假设时，先更新 `PLAN_MAP.md` 和相关计划，再继续实施；计划被推进、恢复、暂停或复核时同步 `最后更新`。
+8. 完成时记录验证证据、测试覆盖率证据并更新状态。
+9. 验收治理文档时先做独立复核和反向引用检查：不得仅依据计划状态、完成证据文字或文档格式判定完成；必须核对当前仓库内容、可复现验证命令、测试或 CI 输出、覆盖率证据，以及用 `rg` 搜索同名计划、P 编号、状态名、关键字段和 `草案为准|以草案为事实源|详见草案|draft is source|source of truth.*draft|以.*draft.*为准`，确认所有路线图、优先级计划和索引已经同步，且旧草案没有重新成为事实源。
+10. 运行项目内检查脚本；如果项目没有脚本或怀疑项目内脚本过旧，可使用源仓库脚本 `/Users/jafish/Documents/work/plan-governance/scripts/check_plan_governance.py`。需要检查活跃计划停滞时运行 `--stale-days`，默认 10 天。
+
+## Step 0 证据
+
+实施前必须先固定可观察基线：
+
+| 任务类型 | Step 0 证据 |
+|---|---|
+| 缺陷修复 | 失败回归测试或最小复现 |
+| 行为迁移 | 现状快照、兼容样本或契约测试 |
+| 新项目 | 可执行验收 fixture、协议样本或提交图 |
+| 架构探索 | 最小原型、风险实验或关键假设验证 |
+
+如果 Step 0 不现实，记录原因，并定义替代基线后再改实现。
+
+## 漂移检查
+
+当决策、实现发现或运行报告改变以下内容时，暂停实施并更新治理文档：
+
+- 既有 ADR 或核心原则
+- 计划顺序、依赖、替代关系或有效性
+- 公共 API、Schema、状态语义、兼容承诺或失败模式
+- 多个计划共享的重复修改点
+- 用来证明完成的测试或完成条件
+- 专项计划与路线图、优先级计划或索引之间的状态、字段方案、完成条件或验证结果
+
+## 停滞检查
+
+`PLAN_MAP.md` 的计划索引应包含 `最后更新` 列，日期格式为 `YYYY-MM-DD`。
+
+推荐表头：
+
+```markdown
+| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
+```
+
+规则：
+
+- `最后更新` 是显式治理元数据，不从 Git 历史或文件 mtime 推断。
+- 当计划状态、当前阶段、阻塞项、依赖、完成条件、验证结果或实施范围变化时，同步 `最后更新`。
+- `--stale-days` 只对 `候选`、`设计中`、`待实施`、`实施中` 等活跃计划输出 `WARNING`，不自动改变状态。
+- `--stale-days` 省略数值时默认 10 天，可显式传入 N。
+
+## 初始化、模板和检查脚本
+
+- `assets/PLAN_MAP.template.md`：治理入口模板。
+- `assets/plan.template.md`：计划文档模板。
+- `assets/adr.template.md`：可选 ADR 模板。
+- `assets/migration.template.md`：可选迁移模板。
+- `scripts/init_plan_governance.py`：初始化 Git 仓库、`docs/PLAN_MAP.md` 和首个 `docs/plans/<plan>.md`；也可升级已有项目的代理规则和检查脚本。
+- `scripts/check_plan_governance.py`：检查状态、最后更新、计划链接、依赖、阻塞项、完成证据、测试覆盖率证据，并提供可选漂移、pre-commit 和停滞检查。
+- `scripts/plan_governance_hook.py`：只读 hook runtime，可由项目级 Agent hooks 手动调用；只输出短提示和检查结果，不修改治理文档、不更新状态、不安装 hooks。
+
+初始化一个项目：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --plan api-compat-migration \
+  --title "API 兼容性迁移" \
+  --goal "分阶段完成 API 兼容性迁移" \
+  --copy-checker \
+  --update-agent-rules
+```
+
+如果目标目录还不是 Git 仓库，初始化流程会先执行 `git init`；已有 `.git/` 时跳过。
+
+只更新已有项目的代理规则，不修改 `docs/`：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --update-agent-rules-only
+```
+
+升级已有项目的辅助文件，刷新 `scripts/check_plan_governance.py`、`CLAUDE.md` 和 `AGENTS.md`，但不覆盖 `docs/`：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --upgrade-existing
+```
+
+旧项目如果 `docs/PLAN_MAP.md` 仍是五列表，显式迁移为包含 `最后更新` 的六列表：
+
+```bash
+plan-governance-cli init \
+  --root . \
+  --migrate-plan-map-last-updated \
+  --last-updated-date 2026-07-05
+```
+
+不传 `--last-updated-date` 时使用当天日期。该迁移只修改 `docs/PLAN_MAP.md` 的计划索引表，不自动改变计划状态。
+
+在仓库根目录运行：
+
+```bash
+plan-governance-cli check .
+```
+
+可选检查：
+
+```bash
+plan-governance-cli check . --drift
+plan-governance-cli check . --pre-commit
+plan-governance-cli check . --stale-days
+plan-governance-cli check . --stale-days 10
+```
+
+- `--drift`：检查工作区变更是否被活跃计划的 `影响模块或文件` 覆盖。
+- `--pre-commit`：检查 staged 变更是否被活跃计划的 `影响模块或文件` 覆盖，可由用户手动接入 Git hook。
+- `--stale-days`：检查活跃计划是否超过阈值未更新；默认 10 天。
+- 这些可选检查输出 `WARNING`，不改变退出码。
+- `--attest <plan-name>`：为已登记计划创建或覆盖 `docs/attestations/<plan-name>.json` 完成快照。
+- `--check-attestations`：检查完成快照中的计划文件和 `PLAN_MAP.md` hash 是否漂移；漂移、缺失或 JSON 损坏只输出 `WARNING`，不改变退出码。
+
+`影响模块或文件` 的作用域匹配规则：
+
+- `--drift`、`--pre-commit` 和 `plan_governance_hook.py --event pre-write` 使用同一语义。
+- 优先提取列表项中的第一个反引号路径，例如 ``- `./scripts/`: 检查脚本``。
+- 没有反引号时提取第一个纯文本 token，例如 `- README.md`。
+- 匹配前归一化前导 `./`、尾随 `/` 和重复斜杠。
+- 支持文件精确匹配和目录前缀匹配。
+- 不支持 glob、正则、否定规则或自然语言推断。
+
+只读 hook runtime 可手动接入项目级 Agent hooks：
+
+```bash
+plan-governance-cli hook --event session-start
+plan-governance-cli hook --event pre-write --paths scripts/check_plan_governance.py
+plan-governance-cli hook --event post-write --paths docs/PLAN_MAP.md
+plan-governance-cli hook --event stop
+```
+
+该脚本不自动安装 `.codex/hooks.json` 或修改全局配置。`stop` 事件只做非阻塞提示，不实现强制 gate。
+

package/resources/skill/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Plan Governance"
+  short_description: "用计划、证据和检查管理分阶段工作"
+  default_prompt: "使用 $plan-governance 管理这个跨阶段变更，维护计划文档、Step 0 证据和完成检查。"
+

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

@@ -0,0 +1,48 @@
+# PLAN_MAP
+
+## 治理范围
+
+本文件只跟踪跨阶段、影响公共契约、依赖真实反馈，或会与其他计划发生关系的计划。普通一次性任务不要加入这里。
+
+## 文档权责
+
+- `PLAN_MAP.md` 的 `状态` 是计划级生命周期，`当前阶段` 是阶段身份指针。
+- 阶段 N 完成后，阶段 N+1 默认保持 `设计中`；专项计划自己的准入复核通过后才能进入 `待实施`。
+- 阶段准入摘要、样本矩阵和独立复核记录只写入专项计划，不复制到本索引。
+
+## 计划索引
+
+| 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
+|---|---|---|---|---|---|
+| [example-plan](plans/example-plan.md) | 候选 | 阶段 0 | <YYYY-MM-DD> | - | - |
+
+允许状态：`候选`、`设计中`、`待实施`、`实施中`、`已完成`、`已替代`、`已合并`、`已废弃`。
+
+## 推荐顺序
+
+1. `example-plan`
+
+## 依赖关系
+
+| 计划 | 依赖 | 原因 |
+|---|---|---|
+| example-plan | - | - |
+
+## 替代、合并和废弃
+
+| 计划 | 关系 | 目标 | 原因 |
+|---|---|---|---|
+| - | - | - | - |
+
+## 当前阻塞项
+
+| 问题 | 推荐方案 | 影响范围 | 是否阻塞当前阶段 | 状态 |
+|---|---|---|---|---|
+| - | - | - | 否 | 已延后 |
+
+## 完成证据
+
+| 计划 | 阶段 | 证据 |
+|---|---|---|
+| - | - | - |
+

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

@@ -0,0 +1,18 @@
+# ADR <number>：<decision>
+
+## 状态
+
+提议中
+
+## 背景
+
+## 决策
+
+## 备选方案
+
+## 后果
+
+## 关联计划
+
+- 
+

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

@@ -0,0 +1,20 @@
+# 迁移：<name>
+
+## 背景
+
+## 兼容策略
+
+## 迁移步骤
+
+1. 
+
+## 回滚方式
+
+## 旧行为保留窗口
+
+## 验证方式
+
+## 关联计划或 ADR
+
+- 
+