plan-governance-cli 1.1.2 → 1.1.3

package/README.md

@@ -55,12 +55,12 @@ docs/
 | 文档 | 权威内容 |
 |---|---|
 | `docs/PLAN_MAP.md` | 计划索引、状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项、证据链接 |
-| `docs/plans/*.md` | 本次目标、范围、行为差异、阶段、Step 0、验证与完成条件；链接现行契约 |
+| `docs/plans/YYYYMMDD/*.md` | 新计划的目标、范围、行为差异、阶段、Step 0、验证与完成条件；旧式 `docs/plans/*.md` 继续兼容 |
 | 已有 Schema/OpenAPI 或按需的 `docs/specs/*.md` | 跨迭代的现行契约；优先复用已有来源，文字 spec 补充行为/失败语义，不重复字段定义 |
 | `docs/adr/*.md` | 关键架构决策、备选方案和后果 |
 | `docs/migrations/*.md` | 兼容策略、迁移步骤、回滚方式和旧行为保留窗口 |
 
-`docs/plans/*.md` 保持平铺。目录按真实内容增加：`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-migration` skill。其他目录按真实内容增加：`docs/reviews/` 放独立复核，`docs/fixtures/` 放人工样本/回放说明，`tests/fixtures/` 放可执行输入，`docs/attestations/` 放按需快照。init 只创建最小结构；可选 [spec 模板](resources/skill/assets/spec.template.md) 随 skill 分发，不自动创建目标项目 spec 或空目录。
 
 ## 任务分流与验收
 
@@ -85,7 +85,7 @@ docs/
 
 启用治理后，已有草案、历史设计、归档计划、临时分析文档等默认只作为背景材料，不再作为规范事实源。
 
-- 新发生的目标、范围、公共契约、字段、Schema、状态语义、阶段、验证方式、完成条件、风险和回滚，应写入 `docs/plans/*.md`、ADR、migration 或正式 spec。
+- 新发生的目标、范围、公共契约、字段、Schema、状态语义、阶段、验证方式、完成条件、风险和回滚，应写入 `docs/plans/YYYYMMDD/*.md`、ADR、migration 或正式 spec。
 - 计划状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接，应写入或同步 `docs/PLAN_MAP.md`。
 - 不要为了“保持一致”而修改草案或历史文档；除非用户明确点名该文件，否则草案只在治理文档中作为背景材料引用。
 - 验收时应搜索并修正“草案为准”“以草案为事实源”“详见草案”等表达。
@@ -110,7 +110,7 @@ plan-governance-cli init \
 ```text
 .git/
 docs/PLAN_MAP.md
-docs/plans/api-compat-migration.md
+docs/plans/20260926/api-compat-migration.md
 AGENTS.md
 ```
 
@@ -118,7 +118,7 @@ AGENTS.md
 
 如果目标目录还不是 Git 仓库，初始化流程会先执行 `git init`；已有 `.git/` 时会跳过，不重复初始化。
 
-`--update-agent-rules` 会创建或更新 `AGENTS.md` 中带标记的计划治理章节，只写稳定执行规则，不写具体计划内容。具体计划仍以 `docs/PLAN_MAP.md` 和 `docs/plans/*.md` 为准。
+`--update-agent-rules` 会创建或更新 `AGENTS.md` 中带标记的计划治理章节，只写稳定执行规则，不写具体计划内容。具体计划仍以 `docs/PLAN_MAP.md` 中的真实链接为准，新计划默认位于 `docs/plans/YYYYMMDD/`。
 
 也可以使用含义更直接的别名：
 
@@ -134,7 +134,7 @@ AGENTS.md
 
 ## 更新已有项目
 
-如果项目已经有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`，不要重新初始化计划文档。只更新代理执行规则时运行：
+如果项目已经有 `docs/PLAN_MAP.md` 和计划文件，不要重新初始化计划文档。只更新代理执行规则时运行：
 
 ```bash
 plan-governance-cli init \
@@ -156,7 +156,7 @@ plan-governance-cli init \
 
 - 按兼容模式覆盖更新项目中的 `scripts/check_plan_governance.py`
 - 创建或更新 `AGENTS.md` 中带标记的计划治理章节，既有其他代理入口保持原样
-- 保留已有 `docs/PLAN_MAP.md` 和 `docs/plans/*.md`
+- 保留已有 `docs/PLAN_MAP.md` 和所有现存计划文件；兼容读取平铺和日期目录计划
 - 提示缺失的治理文档
 
 新项目和日常升级不需要使用该兼容模式；优先使用全局 npm CLI。
@@ -260,7 +260,7 @@ plan-governance-cli setup --target codex --dry-run
 plan-governance-cli setup --target codex --force
 ```
 
-`setup` 只向 Codex 同步 npm 包 manifest 指定的 skill、代理元数据和模板文件，必须恰好指定一次 `--target codex`。旧版或重复 target、混合 help、缺失 target 都会在写入前失败；目标之外的用户目录不会被读取、修改或删除。默认先用 `--dry-run` 查看差异，目标文件有本地修改时不会静默覆盖。检查器、初始化器和 hook runtime 由 npm 包内部调用，不复制到项目或 skill 目录；项目初始化器只维护 `AGENTS.md`，当前实现不自动安装 hook 配置。
+`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 配置。
 
 初始化项目时使用包内初始化器：
 
@@ -299,7 +299,7 @@ plan-governance-cli init --root . --migrate-plan-map-last-updated --last-updated
 当前检查项包括：
 
 - `PLAN_MAP.md` 引用的计划文件是否存在。
-- `docs/plans/*.md` 是否存在未登记到 `PLAN_MAP.md` 的孤立计划；孤立计划以 `WARNING` 提示，不阻断检查。
+- 根目录平铺计划及 `docs/plans/YYYYMMDD/*.md` 是否存在未登记到 `PLAN_MAP.md` 的孤立计划；孤立计划以 `WARNING` 提示，不阻断检查。
 - 计划状态是否合法。
 - 计划依赖是否存在环。
 - 活跃计划正文中的计划引用是否与 `PLAN_MAP.md` 依赖列一致；不一致以 `WARNING` 提示。
@@ -336,7 +336,7 @@ plan-governance-cli check . --check-attestations --strict-readiness
 
 这是可选模式：快照绑定显式文件、目标与必要上游计划的实际内容，以及相关地图行。无关计划日期、地图注释或 HEAD 变化不触发复核；相关内容变化、删除或绑定无效会显示 `needs_review`，默认警告，显式严格检查失败。旧快照继续按原有全文 hash 规则检查，不自动回填；CI/发布不会自动开启证据检查。
 
-文件须为仓库内普通文件，拒绝重复、目录、glob、越界或 symlink。它记录工作树字节，HEAD 只作定位；未列出的新文件不会自动被发现，hash 不代表独立验收。完成新的复核后，用带绑定的新快照和 `--supersedes <旧快照相对路径>` 替代；旧格式后继不能解除绑定快照的复核责任。具体投影、兼容和失败边界见[范围绑定契约](docs/plans/iterative-governance-reliability.md#阶段-4-行为契约)。
+文件须为仓库内普通文件，拒绝重复、目录、glob、越界或 symlink。它记录工作树字节，HEAD 只作定位；未列出的新文件不会自动被发现，hash 不代表独立验收。完成新的复核后，用带绑定的新快照和 `--supersedes <旧快照相对路径>` 替代；旧格式后继不能解除绑定快照的复核责任。具体投影、兼容和失败边界见[范围绑定契约](docs/plans/20260906/iterative-governance-reliability.md#阶段-4-行为契约)。
 
 ## 测试覆盖率
 
@@ -396,7 +396,7 @@ $plan-governance 为这个项目初始化计划治理，计划名是 api-compat-
 或继续推进已有计划：
 
 ```text
-$plan-governance 继续推进 docs/plans/api-compat-migration.md 的当前阶段，完成后记录验证证据。
+$plan-governance 继续推进 docs/plans/20260926/api-compat-migration.md 的当前阶段，完成后记录验证证据。
 ```
 
 skill 只负责让 Codex 按流程工作；真实计划状态仍然保存在项目仓库的 `docs/` 中。

package/bin/plan-governance-cli.mjs

@@ -10,7 +10,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -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]");
+    console.log("用法：plan-governance-cli setup --target codex [--destination DIR] [--dry-run] [--force]\n同步主治理 skill 和独立计划迁移 skill；自定义 destination 时，其他 skill 写入同一 skills 目录。");
     return null;
   }
 
@@ -127,9 +127,8 @@ function targetRoot(manifest, options) {
   };
 }
 
-function resourceFiles(manifest) {
-  const skillPrefix = "resources/skill/";
-  return manifest.skill.files.map((source) => {
+function resourceFiles(skill, skillPrefix) {
+  return skill.files.map((source) => {
     if (!source.startsWith(skillPrefix)) {
       throw new Error(`skill 资源不在受支持的目录中：${source}`);
     }
@@ -140,31 +139,69 @@ function resourceFiles(manifest) {
   });
 }
 
+function pathsOverlap(left, right) {
+  const contains = (parent, child) => {
+    const childRelative = relative(parent, child);
+    return childRelative === ""
+      || (childRelative !== ".." && !childRelative.startsWith(`..${sep}`) && !isAbsolute(childRelative));
+  };
+  return contains(left, right) || contains(right, left);
+}
+
 function setup(args) {
   const options = parseSetupArgs(args);
   if (options === null) return 0;
 
   let manifest;
-  let files;
+  let skills;
   try {
     manifest = loadManifest();
-    files = resourceFiles(manifest);
+    skills = [
+      { name: "plan-governance", definition: manifest.skill, prefix: "resources/skill/" },
+      ...(manifest.additionalSkills ?? []).map((definition) => ({
+        name: definition.name,
+        definition,
+        prefix: definition.prefix,
+      })),
+    ];
   } catch (error) {
     return fail(error.message);
   }
 
   const plans = [];
   try {
-    const target = targetRoot(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）`);
+    const primaryTarget = targetRoot(manifest, options);
+    const targets = skills.map((skill) => {
+      const configuredTarget = skill.definition.targets.codex;
+      return skill.name === "plan-governance"
+        ? primaryTarget
+        : {
+            name: skill.name,
+            root: resolve(options.destination
+              ? join(dirname(primaryTarget.root), basename(expandTarget(configuredTarget)))
+              : expandTarget(configuredTarget)),
+          };
+    });
+    for (let index = 0; index < targets.length; index += 1) {
+      for (let other = index + 1; other < targets.length; other += 1) {
+        if (pathsOverlap(targets[index].root, targets[other].root)) {
+          throw new Error(`setup 的 skill 目标目录重叠：${targets[index].root} 与 ${targets[other].root}`);
+        }
+      }
+    }
+    for (let index = 0; index < skills.length; index += 1) {
+      const skill = skills[index];
+      const target = targets[index];
+      for (const file of resourceFiles(skill.definition, skill.prefix)) {
+        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 });
       }
-      plans.push({ target: target.name, destination, existing, sourceContent });
     }
   } catch (error) {
     return fail(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "统一入口的计划治理检查 CLI",
   "private": false,
   "type": "module",
@@ -11,6 +11,7 @@
     "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

@@ -17,6 +17,19 @@
       "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/migration-skill/SKILL.md

@@ -0,0 +1,14 @@
+---
+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

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

package/resources/skill/SKILL.md

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

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

@@ -20,7 +20,7 @@
 
 | 计划 | 状态 | 当前阶段 | 最后更新 | 依赖 | 证据 |
 |---|---|---|---|---|---|
-| [example-plan](plans/example-plan.md) | 候选 | 阶段 0 | <YYYY-MM-DD> | - | - |
+| [example-plan](plans/YYYYMMDD/example-plan.md) | 候选 | 阶段 0 | <YYYY-MM-DD> | - | - |
 
 ### 已完成
 

package/resources/skill/references/cli.md

@@ -18,7 +18,7 @@
 
 ## 分发与资源
 
-SKILL、三个 references、agents 元数据与 assets 由同一 npm 包的 manifest 分发。`plan-governance-cli setup --target codex --dry-run` 查看 Codex 同步差异；实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理目标之外的用户目录。setup 只支持 Codex 单目标同步；项目初始化器只维护 `AGENTS.md`。项目升级不迁移旧计划，受管块外内容必须保持。
+主治理 skill 和独立 migration skill 由同一 npm 包的 manifest 分别分发。`plan-governance-cli setup --target codex --dry-run` 查看两个 skill 的同步差异；`--destination DIR` 将主 skill 放入指定目录，并将迁移 skill 放在其同级目录。实际覆盖需既有用户授权并按 setup 冲突提示处理，不自动清理目标之外的用户目录。setup 只支持 Codex 单目标同步；项目初始化器只维护 `AGENTS.md`。项目升级不迁移旧计划，受管块外内容必须保持。
 
 仅更新计划格式不等于更新项目入口。已有项目在任务交接、没有进行中的实施或复核时更新受管入口；升级不批量回写历史，旧策略名和六列格式按 verification 解释为统一单次行为。安装副本与仓库开发规则有差异时说明本次选用来源，不能因版本号相同就混读正文。
 
@@ -28,7 +28,7 @@ SKILL、三个 references、agents 元数据与 assets 由同一 npm 包的 mani
 - `../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/init_plan_governance.py`：初始化 Git 仓库、`docs/PLAN_MAP.md` 和首个 `docs/plans/YYYYMMDD/<plan>.md`；检查器仍读取旧式根目录计划。也可升级已有项目的代理规则和检查脚本。
 - `scripts/check_plan_governance.py`：检查状态、最后更新、计划链接、依赖、阻塞项、完成证据、测试覆盖率证据，并提供可选漂移、pre-commit、停滞和 attestation 生命周期检查。
 - `scripts/plan_governance_hook.py`：只读 hook runtime，可由项目级 Agent hooks 手动调用；只输出短提示和检查结果，不修改治理文档、不更新状态、不安装 hooks。
 

package/resources/skill/references/planning.md

@@ -15,11 +15,13 @@
 | 文档 | 职责 |
 |---|---|
 | `docs/PLAN_MAP.md` | 计划状态、阶段、关系、阻塞及证据入口 |
-| `docs/plans/*.md` | 本次目标、范围、决策、差异与验证证据，计划文件平铺 |
+| `docs/plans/YYYYMMDD/*.md` | 新计划的目标、范围、决策、差异与验证证据；旧式 `docs/plans/*.md` 计划继续兼容读取 |
 | Schema/OpenAPI 或 `docs/specs/` | 现行公共契约，优先复用已有来源 |
 | `docs/adr/`、`docs/migrations/` | 确有需要时记录长期架构决策或迁移步骤 |
 | `docs/reviews/`、`docs/fixtures/` | 必要复核及可复验样本，代码 fixture 放 `tests/fixtures/` |
 
+新建计划使用 `docs/plans/YYYYMMDD/<plan>.md`，日期是创建时的本地日期，之后更新不改变目录日期。`PLAN_MAP.md` 链接真实路径。根目录中的旧式 `docs/plans/<plan>.md` 仍受支持；工具升级不会自动迁移它们。已有计划要批量迁移时，只有用户明确要求才调用独立 `plan-governance-migration` skill。
+
 ## 多文档同步规则
 
 同一事实保留一个权威来源，其他文档引用。决策或结果改变后，同步地图及实际受影响的索引/引用；同一组已收敛变化可合并同步，不为每次保存增加流程。用 `rg` 定向检查相关计划名、关键字段和链接，不重扫无关历史。

package/scripts/check_plan_governance.py

@@ -793,6 +793,27 @@ def extract_plan_link(cell):
     return None
 
 
+def plan_link_issue(link):
+    """Validate the canonical YYYYMMDD bucket while preserving legacy/custom paths."""
+    parts = Path(link).parts
+    if len(parts) < 2 or parts[0] != "plans":
+        return f"计划路径必须位于 docs/plans 下：{link}"
+    bucket = parts[1]
+    if len(parts) == 2 and bucket.endswith(".md"):
+        return None
+    if not bucket[:1].isdigit():
+        return None
+    if not re.fullmatch(r"\d{8}", bucket):
+        return f"计划日期目录必须为 YYYYMMDD：{link}"
+    try:
+        datetime.strptime(bucket, "%Y%m%d")
+    except ValueError:
+        return f"计划日期目录不是有效日期：{link}"
+    if len(parts) != 3 or not parts[2].endswith(".md"):
+        return f"计划日期目录必须直接包含 Markdown 文件：{link}"
+    return None
+
+
 def extract_declared_dependencies(depends_cell):
     return [d.strip("` ") for d in re.split(r",|<br>|、", depends_cell) if d.strip("` -")]
 
@@ -846,13 +867,19 @@ def extract_plan_references(plan_text, known_plans, current_name):
         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):
+    for match in re.finditer(
+        r"(?:docs/)?plans/(?:\d{8}/)?([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
+    for match in re.finditer(r"\]\(([^)#]+\.md)(?:#[^)]+)?\)", plan_text):
+        target = match.group(1).strip()
+        if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*://", target):
+            continue
+        name = Path(target).stem
         if name in known_plans and name != current_name:
             references.add(name)
 
@@ -918,9 +945,16 @@ def find_orphan_plans(docs, plans):
     if not plans_dir.exists():
         return []
     indexed_paths = {data["path"].resolve() for data in plans.values()}
+    candidates = set(plans_dir.glob("*.md"))
+    for bucket in plans_dir.iterdir():
+        if not bucket.is_dir() or not bucket.name[:1].isdigit():
+            continue
+        # Numeric buckets are reserved for dated plans. Include malformed buckets
+        # and deeper files so they cannot disappear from orphan diagnostics.
+        candidates.update(bucket.rglob("*.md"))
     return sorted(
         plan_file
-        for plan_file in plans_dir.glob("*.md")
+        for plan_file in candidates
         if plan_file.resolve() not in indexed_paths
     )
 
@@ -1630,32 +1664,33 @@ def warn_attestation_drift(warnings, root, plans, errors=None, strict=False, rep
         plan_map_path = root / plan_map_path_rel
         if scoped_checks:
             try:
-                binding_file(root, plan_path_rel)
+                binding_file(root, plan_path_rel, require_file=plan_path.exists())
                 binding_file(root, plan_map_path_rel)
             except (ValueError, OSError) as exc:
                 attestation_issue(warnings, errors, strict, f"{path}: 混合快照路径读取预检失败：{exc}")
                 continue
-        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
 
-        drifted = False
+        # A moved plan leaves the historical snapshot's recorded path behind.
+        # Keep that legacy record in the supersedes graph; an explicit valid
+        # successor can retire it, while an unretired record remains needs_review.
+        missing_plan = not plan_path.exists()
+        drift_reasons = []
+        if missing_plan:
+            drift_reasons.append(f"快照引用的计划文件不存在：{plan_path}")
         try:
-            if sha256_file(plan_path) != attestation.get("plan_sha256"):
-                warn(warnings, f"{path}: {plan_name} 计划文件 hash 已变化，需要人工复核")
-                drifted = True
+            if not missing_plan and sha256_file(plan_path) != attestation.get("plan_sha256"):
+                drift_reasons.append(f"{plan_name} 计划文件 hash 已变化，需要人工复核")
             if sha256_file(plan_map_path) != attestation.get("plan_map_sha256"):
-                warn(warnings, f"{path}: PLAN_MAP.md hash 已变化，需要人工复核")
-                drifted = True
+                drift_reasons.append("PLAN_MAP.md hash 已变化，需要人工复核")
         except OSError as exc:
             if not scoped_checks:
                 raise
             # 内容不可读不使已存在的替代目标消失，也不阻止后续绑定报告。
             attestation_issue(warnings, errors, strict, f"{path}: 混合快照内容读取失败：{exc}")
-            drifted = True
+            drift_reasons.append(f"快照内容读取失败：{exc}")
         records.append(
             {
                 "path": path,
@@ -1664,10 +1699,12 @@ def warn_attestation_drift(warnings, root, plans, errors=None, strict=False, rep
                 "purpose": purpose,
                 "review_status": review_status,
                 "supersedes": normalized_supersedes,
-                "drifted": drifted,
+                "drifted": bool(drift_reasons),
                 "legacy": legacy,
                 "invalid_structure": invalid_structure,
                 "bound": False,
+                "plan_path": plan_path,
+                "drift_reasons": drift_reasons,
             }
         )
 
@@ -1739,6 +1776,9 @@ def warn_attestation_drift(warnings, root, plans, errors=None, strict=False, rep
             key = (record["plan"], record["purpose"])
             current_by_key.setdefault(key, []).append(record["relative_path"])
         record["effective_status"] = effective
+        if effective != "superseded":
+            for reason in record.get("drift_reasons", []):
+                warn(warnings, f"{record['path']}: {reason}")
 
     for key, paths in current_by_key.items():
         if len(paths) > 1:
@@ -1835,6 +1875,9 @@ def plan_index_issues(plan_map_text):
         if not link:
             issues.append(f"计划索引第 {row_index} 行缺少计划链接，无法安全派生工作集")
             continue
+        path_issue = plan_link_issue(link)
+        if path_issue:
+            issues.append(f"计划索引第 {row_index} 行路径无效：{path_issue}")
         name = Path(link).stem
         if name in seen:
             issues.append(f"计划索引存在重复计划 ID：{name}")
@@ -2128,7 +2171,9 @@ def validate_relation_evidence(evidence, plans, row_label):
     """仅校验 Markdown 链接形式的相对证据路径；纯文本运行记录保持兼容。"""
     if not evidence or not plans:
         return []
-    docs_root = next(iter(plans.values()))["path"].parent.parent
+    first_path = next(iter(plans.values()))["path"]
+    plans_dir = next((parent for parent in first_path.parents if parent.name == "plans"), None)
+    docs_root = plans_dir.parent if plans_dir else first_path.parent.parent
     errors = []
     for match in re.finditer(r"\]\(([^)#]+)(?:#[^)]+)?\)", evidence):
         target = match.group(1).strip()

package/scripts/init_plan_governance.py

@@ -4,7 +4,7 @@ import re
 import shutil
 import subprocess
 import sys
-from datetime import date
+from datetime import date, datetime
 from pathlib import Path
 
 
@@ -60,7 +60,7 @@ def agent_rules_body():
 
 - 普通一次性任务直接处理；已有计划按共享 verification 验证。新旧计划均为普通改动自验，高风险或高影响同范围独立复核一次，修复后自验。
 - 只实施已授权、已准入的当前阶段。每个阶段有自身 Step 0、验证/完成和失败边界；未解决问题不能记为完成，不可用或超时不能冒充已检查。已有授权不重复索取，新增高影响外部动作按实际授权处理。
-- 首次读取 `docs/PLAN_MAP.md`、当前相关 `docs/plans/*.md` 及适用契约/ADR/migration；恢复先核对当前工作集、最近证据和实际 diff，缺失或冲突再展开。
+- 首次读取 `docs/PLAN_MAP.md`、索引登记的相关 `docs/plans/` 计划及适用契约/ADR/migration；恢复先核对当前工作集、最近证据和实际 diff，缺失或冲突再展开。
 - 地图维护状态、阶段、关系、阻塞与证据入口；计划记录本次差异及验证，现行契约优先复用 Schema/OpenAPI。新事实不写回历史草案，变化同步地图及相关引用。
 - 完成时按共享规范记录实际验证与适用用户验收，运行 `plan-governance-cli check .`；准入/CI/发布显式使用 `--strict-readiness`，机械通过不等于业务验收。
 """
@@ -113,9 +113,11 @@ def update_agent_rules(root):
     return [update_agents_md(root)]
 
 
-def plan_map_content(plan_slug, title, status, phase):
-    today = date.today().isoformat()
-    row = f"| [{title}](plans/{plan_slug}.md) | {status} | {phase} | {today} | - | - |"
+def plan_map_content(plan_slug, title, status, phase, created_on=None):
+    created_on = created_on or date.today()
+    today = created_on.isoformat()
+    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 ""
@@ -128,13 +130,13 @@ def plan_map_content(plan_slug, title, status, phase):
 ## 文档权责
 
 - `docs/PLAN_MAP.md` 是状态、依赖、替代/合并/废弃关系、推荐顺序、阻塞项和证据链接的事实源。
-- `docs/plans/*.md` 记录本次行为差异、阶段、Step 0 和验收；现行契约优先引用已有 Schema/OpenAPI，无合适来源且需长期维护时才按需建立 `docs/specs/*.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/*.md`、ADR、migration、正式 spec 或 `docs/PLAN_MAP.md`。
+- 启用治理后，已有草案、历史设计、归档计划和临时分析文档默认只作为背景材料，不再作为规范事实源；后续新规范默认进入 `docs/plans/YYYYMMDD/*.md`、ADR、migration、正式 spec 或 `docs/PLAN_MAP.md`。
 - 计划索引固定分为 `未完成`、`已完成`、`已废弃` 三张表；`已替代`、`已合并`等不再推进的终态归入 `已废弃` 表，但保留真实状态值。
 
 ## 计划索引
@@ -223,8 +225,20 @@ def docs_warnings(root):
     if not (root / "docs" / "PLAN_MAP.md").exists():
         warnings.append("缺少 docs/PLAN_MAP.md")
     plans_dir = root / "docs" / "plans"
-    if not plans_dir.exists() or not any(plans_dir.glob("*.md")):
-        warnings.append("缺少 docs/plans/*.md")
+    dated_plans = False
+    if plans_dir.exists():
+        for child in plans_dir.iterdir():
+            if not (child.is_dir() and re.fullmatch(r"\d{8}", child.name)):
+                continue
+            try:
+                datetime.strptime(child.name, "%Y%m%d")
+            except ValueError:
+                continue
+            if any(child.glob("*.md")):
+                dated_plans = True
+                break
+    if not plans_dir.exists() or (not any(plans_dir.glob("*.md")) and not dated_plans):
+        warnings.append("缺少 docs/plans 下的平铺或 YYYYMMDD 日期目录计划")
     return warnings
 
 
@@ -349,14 +363,15 @@ def main(argv=None):
 
     docs = root / "docs"
     plan_map = docs / "PLAN_MAP.md"
-    plan_file = docs / "plans" / f"{plan_slug}.md"
+    created_on = date.today()
+    plan_file = docs / "plans" / created_on.strftime("%Y%m%d") / f"{plan_slug}.md"
 
     created = []
     git_dir = init_git(root)
     if git_dir is not None:
         created.append(git_dir)
 
-    write_file(plan_map, plan_map_content(plan_slug, title, args.status, args.phase), args.force)
+    write_file(plan_map, plan_map_content(plan_slug, title, args.status, args.phase, created_on), args.force)
     created.append(plan_map)
     write_file(plan_file, plan_content(plan_slug, title, args.status, args.phase, args.goal), args.force)
     created.append(plan_file)