plan-governance-cli 1.2.0 → 2.0.1

package/README.md

@@ -39,7 +39,7 @@ docs/
       <plan-name>.md
 ```
 
-`docs/plans/*.md` 是兼容读取的旧式平铺位置；新计划一律放在日期目录中。需要整理其他项目的存量计划时，用户明确提出迁移后再单独使用 `plan-governance-migration` skill。
+`docs/plans/*.md` 是兼容读取的旧式平铺位置；新计划一律放在日期目录中。存量计划只有在用户明确要求时才迁移；迁移规则由 `plan-governance` 按需读取，不单独注册 migration skill。
 
 按需增加：
 
@@ -59,11 +59,14 @@ docs/
 |---|---|
 | `docs/PLAN_MAP.md` | 计划索引、状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项、证据链接 |
 | `docs/plans/YYYYMMDD/*.md` | 新计划的目标、范围、行为差异、阶段、Step 0、验证与完成条件；旧式 `docs/plans/*.md` 继续兼容 |
+| `docs/reviews/`、`docs/data-quality/` | 复核及数据质量历史记录；建议使用日期前置文件名 |
+| `docs/fixtures/`、`tests/fixtures/` | 可复用样本说明或可执行测试输入 |
+| `docs/attestations/` | CLI 管理的完成快照 |
 | 已有 Schema/OpenAPI 或按需的 `docs/specs/*.md` | 跨迭代的现行契约；优先复用已有来源，文字 spec 补充行为/失败语义，不重复字段定义 |
 | `docs/adr/*.md` | 关键架构决策、备选方案和后果 |
 | `docs/migrations/*.md` | 兼容策略、迁移步骤、回滚方式和旧行为保留窗口 |
 
-新计划按创建时的本地日期存放在 `docs/plans/YYYYMMDD/<plan>.md`；修改时不改变日期目录。根目录旧计划继续可读，工具升级不会自动迁移。用户明确要求迁移存量计划时，单独调用 `plan-governance-migration` skill。其他目录按真实内容增加：`docs/reviews/` 放独立复核，`docs/fixtures/` 放人工样本/回放说明，`tests/fixtures/` 放可执行输入，`docs/attestations/` 放按需快照。init 只创建最小结构；可选 [spec 模板](resources/skill/assets/spec.template.md) 随 skill 分发，不自动创建目标项目 spec 或空目录。
+新计划按创建时的本地日期存放在 `docs/plans/YYYYMMDD/<plan>.md`；修改时不改变日期目录。根目录旧计划继续可读，工具升级不会自动迁移。用户明确要求迁移存量计划时，由 `plan-governance` 按需读取迁移参考。复核记录建议命名为 `YYYYMMDD-<subject>[-stageN]-<review-type>[-rN].md`，数据质量记录建议命名为 `YYYYMMDD-<subject>-<record-type>[-rN].<ext>`；日期放在最前，checker 不强制这些文件名。可复用 fixture 按场景/版本命名，attestation 由 CLI 管理。init 只创建最小结构；可选 [spec 模板](resources/skill/assets/spec.template.md) 随 skill 分发，不自动创建目标项目 spec 或空目录。
 
 ## 任务分流与验收
 
@@ -263,7 +266,7 @@ plan-governance-cli setup --target codex --dry-run
 plan-governance-cli setup --target codex --force
 ```
 
-`setup` 只向 Codex 同步 npm 包 manifest 指定的主治理 skill、独立迁移 skill、代理元数据和模板文件，必须恰好指定一次 `--target codex`。旧版或重复 target、混合 help、缺失 target 都会在写入前失败；目标之外的用户目录不会被读取、修改或删除。默认先用 `--dry-run` 查看差异，目标文件有本地修改时不会静默覆盖。使用 `--destination DIR` 指定主 skill 临时目标时，迁移 skill 会写到同一 skills 目录下的 `plan-governance-migration`。检查器、初始化器和 hook runtime 由 npm 包内部调用，不复制到项目或 skill 目录；项目初始化器只维护 `AGENTS.md`，当前实现不自动安装 hook 配置。
+`setup` 只向 Codex 同步 npm 包 manifest 指定的主治理 skill、代理元数据和模板文件，必须恰好指定一次 `--target codex`。旧版或重复 target、混合 help、缺失 target 都会在写入前失败；目标之外的用户目录不会被读取、修改或删除。默认先用 `--dry-run` 查看差异，目标文件有本地修改时不会静默覆盖。迁移规则作为主 skill 的按需参考分发，`plan-governance-cli guide migration` 可单独读取。检查器、初始化器和 hook runtime 由 npm 包内部调用，不复制到项目或 skill 目录；项目初始化器只维护 `AGENTS.md`，当前实现不自动安装 hook 配置。
 
 初始化项目时使用包内初始化器：
 

package/bin/plan-governance-cli.mjs

@@ -80,7 +80,7 @@ function loadManifest() {
 
 function parseSetupArgs(args) {
   if (args.length === 1 && ["-h", "--help"].includes(args[0])) {
-    console.log("用法：plan-governance-cli setup --target codex [--destination DIR] [--dry-run] [--force]\n同步主治理 skill 和独立计划迁移 skill；自定义 destination 时，其他 skill 写入同一 skills 目录。");
+    console.log("用法：plan-governance-cli setup --target codex [--destination DIR] [--dry-run] [--force]\n同步主治理 skill 及其按需参考和模板。");
     return null;
   }
 
@@ -228,16 +228,17 @@ function guide(args) {
   const topics = new Map([
     ["overview", "SKILL.md"],
     ["planning", "references/planning.md"],
+    ["migration", "references/migration.md"],
     ["verification", "references/verification.md"],
     ["cli", "references/cli.md"],
   ]);
   if (args.length === 1 && args[0] === "--help") {
-    console.log("用法：plan-governance-cli guide [overview|planning|verification|cli]\n缺省 overview；只读当前包内规则，不依赖 cwd 或 Python。");
+    console.log("用法：plan-governance-cli guide [overview|planning|migration|verification|cli]\n缺省 overview；只读当前包内规则，不依赖 cwd 或 Python。");
     return 0;
   }
   const topic = args[0] ?? "overview";
   if (args.length > 1 || !topics.has(topic)) {
-    return fail("guide 仅接受一个主题：overview、planning、verification、cli；用 guide --help 查看用法。");
+    return fail("guide 仅接受一个主题：overview、planning、migration、verification、cli；用 guide --help 查看用法。");
   }
   const path = resolve(packageRoot, "resources", "skill", topics.get(topic));
   try {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "plan-governance-cli",
-  "version": "1.2.0",
+  "version": "2.0.1",
   "description": "统一入口的计划治理检查 CLI",
   "repository": {
     "type": "git",
-    "url": "https://github.com/a526800921/plan-governance.git"
+    "url": "git+https://github.com/a526800921/plan-governance.git"
   },
   "private": false,
   "type": "module",
@@ -15,7 +15,6 @@
     "bin/plan-governance-cli.mjs",
     "resources/manifest.json",
     "resources/skill",
-    "resources/migration-skill",
     "scripts/check_plan_governance.py",
     "scripts/init_plan_governance.py",
     "scripts/plan_governance_hook.py",

package/resources/manifest.json

@@ -13,23 +13,11 @@
       "resources/skill/assets/plan.template.md",
       "resources/skill/assets/spec.template.md",
       "resources/skill/references/planning.md",
+      "resources/skill/references/migration.md",
       "resources/skill/references/verification.md",
       "resources/skill/references/cli.md"
     ]
   },
-  "additionalSkills": [
-    {
-      "name": "plan-governance-migration",
-      "targets": {
-        "codex": "~/.agents/skills/plan-governance-migration"
-      },
-      "prefix": "resources/migration-skill/",
-      "files": [
-        "resources/migration-skill/SKILL.md",
-        "resources/migration-skill/agents/openai.yaml"
-      ]
-    }
-  ],
   "runtime": [
     "scripts/check_plan_governance.py",
     "scripts/init_plan_governance.py",

package/resources/skill/SKILL.md

@@ -22,5 +22,6 @@ description: 维护已有项目计划，或为需要跨阶段、跨会话协调
 | 明确需求、维护计划、同步决策 | [planning](references/planning.md) |
 | 阶段准入、风险判断、验证或完成 | [verification](references/verification.md) |
 | 查询工作集、运行检查、初始化或分发 | [cli](references/cli.md) |
+| 用户明确要求迁移存量计划 | [migration](references/migration.md)；CLI 可用时也可运行 `plan-governance-cli guide migration` |
 
-开发或审查本 skill 时使用仓库源及对应 CLI；其他项目使用实际发现的安装版，参考按所选 skill 目录解析。仅 CLI 可用时用 `guide` 和对应主题读取。来源一次选定后复用，只有内容变化或能力不符时重新核对；不要混读副本。缺少所需能力时说明具体缺口，继续不依赖它的工作，安装与升级按已有授权处理。已有计划批量迁移由独立 `plan-governance-migration` skill 在用户明确要求时执行，日常治理不会自动搬迁计划。
+开发或审查本 skill 时使用仓库源及对应 CLI；其他项目使用实际发现的安装版，参考按所选 skill 目录解析。仅 CLI 可用时用 `guide` 和对应主题读取。来源一次选定后复用，只有内容变化或能力不符时重新核对；不要混读副本。缺少所需能力时说明具体缺口，继续不依赖它的工作，安装与升级按已有授权处理。存量计划迁移规则是主 skill 的按需参考：只有用户明确要求迁移时才读取并执行，日常治理不会自动搬迁计划。

package/resources/skill/references/cli.md

@@ -1,6 +1,6 @@
 # CLI 操作
 
-只读规则入口：`plan-governance-cli guide [overview|planning|verification|cli]`。缺省 overview；`guide --help` 列用法。四主题从同一包根读取本入口及三参考，任意 cwd 可用且无需 Python。正文中的相对文档链接在 CLI 环境通过对应 guide 主题读取，不相对当前项目查找。
+只读规则入口：`plan-governance-cli guide [overview|planning|migration|verification|cli]`。缺省 overview；`guide --help` 列用法。五主题从同一包根读取本入口及参考，任意 cwd 可用且无需 Python。正文中的相对文档链接在 CLI 环境通过对应 guide 主题读取，不相对当前项目查找。
 
 成功退出 0；未知主题、多余参数、缺失/不可读/空资源退出 1 并报错。不下载、安装、修改项目或回退别的版本。skill/CLI 来源按入口一次选定：开发本 skill 用仓库源与对应 CLI，其他项目用安装资源。出现内容变化或能力缺口时再核对，版本号相同不证明资源一致。
 
@@ -18,7 +18,7 @@
 
 ## 分发与资源
 
-主治理 skill 和独立 migration skill 由同一 npm 包的 manifest 分别分发。`plan-governance-cli setup --target codex --dry-run` 查看两个 skill 的同步差异；`--destination DIR` 将主 skill 放入指定目录，并将迁移 skill 放在其同级目录。实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理目标之外的用户目录。setup 只支持 Codex 单目标同步；项目初始化器只维护 `AGENTS.md`。项目升级不迁移旧计划，受管块外内容必须保持。
+`plan-governance-cli setup --target codex --dry-run` 预览主治理 skill 的同步差异，manifest 包含入口、按需参考、代理元数据和模板。迁移规则位于主 skill 的 `references/migration.md`，可通过 `plan-governance-cli guide migration` 按需读取；不会注册第二个 migration skill。`--destination DIR` 指定主 skill 目标目录。实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理目标之外的用户目录。setup 只支持 Codex 单目标同步；项目初始化器只维护 `AGENTS.md`。项目升级不迁移旧计划，受管块外内容必须保持。
 
 仅更新计划格式不等于更新项目入口。已有项目在任务交接、没有进行中的实施或复核时更新受管入口；升级不批量回写历史，旧策略名和六列格式按 verification 解释为统一单次行为。安装副本与仓库开发规则有差异时说明本次选用来源，不能因版本号相同就混读正文。
 

package/resources/skill/references/migration.md

@@ -0,0 +1,22 @@
+# 存量计划迁移
+
+仅当用户明确要求迁移存量计划时使用本参考。计划目录存在、工具升级或主 skill 更新都不构成迁移授权。日常治理只读取计划索引，不主动移动或重命名文件。
+
+本流程处理 `docs/plans/*.md` 等存量计划搬入 `docs/plans/YYYYMMDD/`，并修复由计划路径变化造成的引用。迁移 `reviews`、`data-quality` 或其他文档必须属于用户明确授权的范围；一般命名建议不会触发这些目录的批量重命名。
+
+## 迁移前核对
+
+1. 读取项目 `AGENTS.md`、`docs/PLAN_MAP.md`、所有受影响计划及适用的 [verification](verification.md) 规则。
+2. 核对工作区差异、地图登记、所有候选平铺计划、日期目录目标占用、Markdown 引用和 attestation。
+3. 建立源路径、目标路径、创建日期、日期来源和引用影响清单。先处理日期无法确认、目标冲突、未登记文件或本地修改不清等问题；未解决前不要移动文件。
+4. 创建日期优先取 Git 首次添加记录。仅当正文明确记载创建日期时，才可回退使用正文日期。不得用文件修改时间或最后更新日期推断创建日期。
+
+## 执行与验证
+
+按确认后的映射移动文件，保留原文件名、计划身份、内容、状态、阶段和历史证据。同步更新 `PLAN_MAP.md` 和指向这些计划的文档链接；源文件层级变化导致相对 Markdown 链接失效时，重算其相对路径并保留锚点。代码块中的示例路径不视为引用。
+
+不要改写旧 attestation。检查快照记录的计划路径、地图 hash 和替代关系；如果不能通过项目 CLI 建立可信的后继快照，保留旧快照并报告 `needs_review`，不要手工编辑 JSON 制造通过状态。
+
+完成后确认源路径已清空、每个目标文件只出现一次、索引指向真实路径、所有受影响的本地链接可达，并按项目规则检查 checker、workset 和 attestation。若检查失败，依据源/目标映射恢复文件和引用，报告实际恢复范围及尚未解决的问题。
+
+只处理用户授权的仓库和文档范围。不要顺便迁移其他项目、安装依赖或发布 npm 包。

package/resources/skill/references/planning.md

@@ -18,9 +18,23 @@
 | `docs/plans/YYYYMMDD/*.md` | 新计划的目标、范围、决策、差异与验证证据；旧式 `docs/plans/*.md` 计划继续兼容读取 |
 | Schema/OpenAPI 或 `docs/specs/` | 现行公共契约，优先复用已有来源 |
 | `docs/adr/`、`docs/migrations/` | 确有需要时记录长期架构决策或迁移步骤 |
-| `docs/reviews/`、`docs/fixtures/` | 必要复核及可复验样本，代码 fixture 放 `tests/fixtures/` |
+| `docs/reviews/` | 独立复核记录；建议文件名以记录日期开头 |
+| `docs/data-quality/` | 数据质量审查、结果或回放记录；建议文件名以记录日期开头 |
+| `docs/fixtures/`、`tests/fixtures/` | 前者放可复用说明或样本，后者放可执行测试输入 |
+| `docs/attestations/` | CLI 管理的按需完成快照 |
 
-新建计划使用 `docs/plans/YYYYMMDD/<plan>.md`，日期是创建时的本地日期，之后更新不改变目录日期。`PLAN_MAP.md` 链接真实路径。根目录中的旧式 `docs/plans/<plan>.md` 仍受支持；工具升级不会自动迁移它们。已有计划要批量迁移时，只有用户明确要求才调用独立 `plan-governance-migration` skill。
+新建计划使用 `docs/plans/YYYYMMDD/<plan>.md`，日期是创建时的本地日期，之后更新不改变目录日期。`PLAN_MAP.md` 链接真实路径。根目录中的旧式 `docs/plans/<plan>.md` 仍受支持；工具升级不会自动迁移它们。只有用户明确要求批量迁移时，才按[迁移参考](migration.md)执行；它是主 skill 内的按需规则，不是另一个注册的 skill。
+
+## 历史记录命名建议
+
+复核和数据质量文件主要是带日期的历史记录，建议将记录形成日期放在文件名最前面，方便按时间排序与长期追踪：
+
+- `docs/reviews/YYYYMMDD-<subject>[-stageN]-<review-type>[-rN].md`，例如 `20260926-plan-governance-stage1-completion-review.md`。
+- `docs/data-quality/YYYYMMDD-<subject>-<record-type>[-rN].<ext>`，例如 `20260926-product-catalog-audit.md`。
+
+阶段号和修订序号按需要添加；同一事项同一天产生多份同类型记录时，可用 `-r2`、`-r3` 区分。日期表示这份记录的形成日期，不用最后修改日替代。该格式是新文件的建议，既有文件不会因工具升级而自动重命名。当前 checker 主要检查计划索引、计划结构和相关证据；它不会强制校验 `reviews` 或 `data-quality` 的命名格式。
+
+可复用的 `docs/fixtures/` 样本建议按场景和版本命名，例如 `missing-source-date-v1.json`，不加日期前缀；它们用于重复复验，不是单次历史记录。`docs/attestations/` 由 CLI 按既定名称和格式管理，不手工改名或重命名。
 
 ## 多文档同步规则
 

package/scripts/check_plan_governance.py

@@ -1940,8 +1940,11 @@ def map_blockers(plan_map_text):
         label = row[0] or "未命名阻塞项"
         if not blocker_is_open(row[3], row[4], f"PLAN_MAP {label}", issues):
             continue
-        scope = re.sub(r"\[[^\]]+\]\((?:\./)?plans/([^/)]+)\.md(?:#[^)]*)?\)",
-                       r"\1", row[2]).replace("`", "")
+        scope = re.sub(
+            r"\[[^\]]+\]\(((?:\./)?plans/[^)#]+\.md)(?:#[^)]*)?\)",
+            lambda match: Path(match.group(1)).stem,
+            row[2],
+        ).replace("`", "")
         targets = set(filter(None, re.split(r"[,，、/;；\s]+", scope.strip())))
         if not targets or targets - names:
             issues.append(f"PLAN_MAP 当前阻塞项 {label} 的影响范围无法归属：{row[2]}")

package/resources/migration-skill/SKILL.md

@@ -1,14 +0,0 @@
----
-name: plan-governance-migration
-description: Migrate existing flat docs/plans/*.md files into date directories when the user explicitly requests migration, preserving plan history and repairing references.
----
-
-# 计划日期目录迁移
-
-仅在用户明确要求迁移存量计划时使用。计划目录存在或主治理 skill 已升级，都不构成迁移授权。日常治理只读取索引路径，不主动搬动计划。
-
-迁移前读取项目 `AGENTS.md`、`docs/PLAN_MAP.md`、受影响计划和适用的 plan-governance verification 规则。先检查工作区差异、地图登记、所有平铺计划、目标路径占用、Markdown 引用和 attestation；建立源路径、目标路径、创建日期及引用影响清单，并先报告无法确定的日期或歧义。日期优先取 Git 首次添加记录；仅当正文明确记录创建日期时才可回退使用该日期。不得用修改时间或最后更新日期猜测。路径冲突、未登记文件、无法解析的日期或会丢失的本地修改未解决前，不移动文件。
-
-迁移时保留计划内容、文件名、身份、状态、阶段和历史证据。按核对后的清单移动到 `docs/plans/YYYYMMDD/<slug>.md`，同步 `PLAN_MAP.md`、指向这些计划的文档链接，以及因源文件层级变化而失效的相对 Markdown 链接。保留锚点；计划链接按原目标重新计算相对路径。代码块中的示例路径不视为引用。不要改写旧 attestation；检查其计划路径、地图 hash 和替代关系。若不能用项目 CLI 建立可信后继快照，保留旧快照并报告 `needs_review`，不要手改 JSON 来制造通过状态。
-
-每批迁移都先保存可逆的源/目标映射。完成后确认源路径已清空、目标文件各出现一次、索引路径准确、所有受影响本地链接可达，且 checker、workset 和 attestation 检查符合项目规则。任一检查失败时停止，并依据映射恢复文件和引用；报告实际恢复范围及仍未解决的项目。只处理用户授权的仓库与计划范围，不安装依赖、不发布、不触碰其他项目。

package/resources/migration-skill/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Plan Governance Migration"
-  short_description: "按创建日期迁移存量计划并修复文档引用"
-  default_prompt: "使用 $plan-governance-migration 将这些存量计划迁入日期目录，先核对迁移清单和日期来源，再按授权执行并验证引用。"