refactor(planning-docs): 统一迁移索引与变更图输出契约

Author: sincerely90

plugins/aisee-plugin/references/planning-doc-frontmatter.md

@@ -12,6 +12,7 @@
 - Design Spec
 - Design Assets 索引 / brief
 - Implementation Brief
+- Spec Migration 索引 / 草案
 - Reflect
 
 不适用于：
@@ -28,7 +29,7 @@
 
 ```yaml
 title: "文档标题"
-doc_type: "srs | ui-content | architecture | design-spec | design-assets | implementation-brief | reflect"
+doc_type: "srs | ui-content | architecture | design-spec | design-assets | implementation-brief | spec-migration | reflect"
 status: "draft | active | superseded | archived"
 date: "YYYY-MM-DD"
 scope: "项目 / 模块 / 功能 / change"

plugins/aisee-plugin/skills/aisee-change-plan/SKILL.md

@@ -14,6 +14,7 @@ description: 将已确认需求、轻量修复、技术调研或项目事实映
 - 选择每个 change 的 schema。
 - 在输出 `/opsx:new` 前做 schema availability preflight：优先读取 `aisee schemas list/check --json` 或项目内 `openspec/schemas/<schema>/schema.yaml` 状态。
 - 规划 change 边界、依赖顺序和并行关系。
+- 使用 Mermaid 语法块输出依赖顺序和并行关系，作为长期可读性 contract。
 - 输出 source-map seed，仅当所选 schema 生成 `source-map.md`。
 - 输出可复制的 `/opsx:new "<change>" --schema <schema>` 命令，并把它视为后续 author / implementation 的 schema metadata 合同。
 - 保存 change plan 到 `aisee/docs/change-plan/`。

plugins/aisee-plugin/skills/aisee-change-plan/evals/evals.json

@@ -19,9 +19,10 @@
           "邀请链接过期规则仍是待确认业务规则。"
         ]
       },
-      "expected_output": "输出 change 边界、依赖、复杂度、In Scope/Out of Scope 和执行顺序。所有命令必须使用 /opsx:new \"<change>\" --schema <schema>，不得输出 /opsx:propose。应保留 architecture 中的 RBAC 复用事实和邀请链接规则待确认项，并说明后续通过 aisee:change-author（必要时配合 /opsx:continue）按 schema 补齐 artifacts；不得建议使用旧的 change design skill 作为固定后续步骤。",
+      "expected_output": "输出 change 边界、依赖、复杂度、In Scope/Out of Scope 和执行顺序。依赖顺序和并行关系必须使用 Mermaid 语法块表达。所有命令必须使用 /opsx:new \"<change>\" --schema <schema>，不得输出 /opsx:propose。应保留 architecture 中的 RBAC 复用事实和邀请链接规则待确认项，并说明后续通过 aisee:change-author（必要时配合 /opsx:continue）按 schema 补齐 artifacts；不得建议使用旧的 change design skill 作为固定后续步骤。",
       "expected_outputs": [
         "输出可独立交付的 change 边界、依赖、复杂度、In Scope/Out of Scope 和执行顺序。",
+        "使用 Mermaid 语法块表达依赖顺序和并行关系。",
         "使用 /opsx:new \"<change>\" --schema <schema>。",
         "保留 RBAC 复用事实和邀请链接过期规则待确认项。",
         "说明后续通过 aisee:change-author 或 /opsx:continue 补齐 artifacts。"
@@ -32,6 +33,7 @@
       ],
       "must_include": [
         "change 边界",
+        "Mermaid 依赖图",
         "依赖顺序",
         "source-map seed",
         "/opsx:new 命令"
@@ -61,17 +63,18 @@
           "已有项目、权限和列表页存在。"
         ]
       },
-      "expected_output": "判断这是单个小 change，不为了流程而规划多个 change。输出一个 change 详情块和单条 /opsx:new 命令，不得输出 /opsx:propose，也不得新增未确认的后端、数据库或 UI 需求。",
+      "expected_output": "判断这是单个小 change，不为了流程而规划多个 change。输出一个 change 详情块、单节点 Mermaid 依赖图和单条 /opsx:new 命令，不得输出 /opsx:propose，也不得新增未确认的后端、数据库或 UI 需求。",
       "expected_outputs": [
         "判断为单个小 change。",
-        "输出一个 change 详情块和单条 /opsx:new 命令。",
+        "输出一个 change 详情块、单节点 Mermaid 依赖图和单条 /opsx:new 命令。",
         "说明不需要为了流程拆成多个 change。"
       ],
       "must_ask": [
         "状态枚举是否已有并可复用？"
       ],
       "must_include": [
         "单 change 判断",
+        "Mermaid 依赖图",
         "Out of Scope",
         "/opsx:new 命令"
       ],
@@ -100,18 +103,19 @@
           "输入章节混合了非需求内容。"
         ]
       },
-      "expected_output": "不得把背景、UI 页面、API 设计、数据库设计、测试计划或上线计划规划成同名 change。应围绕退款处理、退款报表、退款状态查看等可独立交付能力规划 change，并在整体理由中说明输入章节被拒绝或合并为边界提示。每个 change 必须包含 FR 引用、Out of Scope 和 source-map seed。",
+      "expected_output": "不得把背景、UI 页面、API 设计、数据库设计、测试计划或上线计划规划成同名 change。应围绕退款处理、退款报表、退款状态查看等可独立交付能力规划 change，并在整体理由中说明输入章节被拒绝或合并为边界提示。每个 change 必须包含 FR 引用、Out of Scope、source-map seed 和 Mermaid 依赖图。",
       "expected_outputs": [
         "拒绝把背景、UI 页面、API 设计、数据库设计、测试计划或上线计划作为 change 边界。",
         "围绕退款处理、退款报表、退款状态查看规划 change。",
-        "每个 change 包含 FR 引用、Out of Scope 和 source-map seed。"
+        "每个 change 包含 FR 引用、Out of Scope、source-map seed 和 Mermaid 依赖图。"
       ],
       "must_ask": [
         "退款处理、报表和状态查看是否需要同批交付？",
         "客服、财务、用户权限边界是否已确认？"
       ],
       "must_include": [
         "FR 引用",
+        "Mermaid 依赖图",
         "Out of Scope",
         "source-map seed",
         "拒绝源章节直接作为边界的说明"
@@ -140,7 +144,7 @@
           "库存一致性策略影响 change 边界和实现路径。"
         ]
       },
-      "expected_output": "必须保留 [ARCHITECTURE-DECISION-REQUIRED]，不得替用户选择库存一致性方案。若该决策影响独立交付边界，应输出需要先补 Architecture 决策的 blocker 或将其作为首个风险验证/决策 change，而不是直接规划具体实现边界。",
+      "expected_output": "必须保留 [ARCHITECTURE-DECISION-REQUIRED]，不得替用户选择库存一致性方案。若该决策影响独立交付边界，应输出需要先补 Architecture 决策的 blocker 或将其作为首个风险验证/决策 change，而不是直接规划具体实现边界。依赖关系如需展示，必须使用 Mermaid 语法块。",
       "expected_outputs": [
         "保留 [ARCHITECTURE-DECISION-REQUIRED]。",
         "把库存一致性策略作为 blocker 或首个风险验证/决策 change。",
@@ -152,6 +156,7 @@
       ],
       "must_include": [
         "[ARCHITECTURE-DECISION-REQUIRED]",
+        "Mermaid 依赖图",
         "blocker 或决策 change",
         "受影响 FR"
       ],
@@ -179,7 +184,7 @@
           "硬件/嵌入式体系暂未完整纳入软件主线，但 schema pack 已有 device schema。"
         ]
       },
-      "expected_output": "应选择或建议 aisee-device-spec-driven，输出设备类 source-map seed，包含 HW/FW/RT/VER 或 TBD in 对应 contract。不得输出 Web/API/DB 字段或把 I2C/UART/RTOS 等技术资源直接作为 change 边界；板级引脚和传感器型号未确认应作为 blocker 或 Open Question。",
+      "expected_output": "应选择或建议 aisee-device-spec-driven，输出设备类 source-map seed，包含 HW/FW/RT/VER 或 TBD in 对应 contract。依赖顺序和并行关系如需展示，必须使用 Mermaid 语法块。不得输出 Web/API/DB 字段或把 I2C/UART/RTOS 等技术资源直接作为 change 边界；板级引脚和传感器型号未确认应作为 blocker 或 Open Question。",
       "expected_outputs": [
         "选择或建议 aisee-device-spec-driven。",
         "输出设备类 source-map seed，包含 HW/FW/RT/VER 或 TBD in 对应 contract。",

plugins/aisee-plugin/skills/aisee-change-plan/references/change-boundary-algorithm.md

@@ -50,7 +50,7 @@ Out of Scope:
 
 - 如需共享 contract、事件类型、数据模型、设备协议或配置约定，优先规划一个 S 级前置 change。
 - 对每个并行 change 复查可独立交付。
-- 在依赖图中明确标记并行组。
+- 在 Mermaid 依赖图中用同一 phase 的 `subgraph` 明确标记并行组。
 
 ## 4. 粒度与数量
 

plugins/aisee-plugin/skills/aisee-change-plan/references/output-template.md

@@ -5,7 +5,7 @@
 ## 输出顺序
 
 1. 摘要
-2. 依赖图
+2. Mermaid 依赖图
 3. Change 详情
 4. 全部命令
 5. 整体理由
@@ -18,24 +18,31 @@ N 个 changes · M 个 phases · 预计总计 X 周 · Y 个可并行
 
 任何估计为 XL（>14 天）的 change 都要标记风险。
 
-## 依赖图
+## Mermaid 依赖图
 
-简单依赖链使用 ASCII：
+依赖顺序和并行关系统一使用 Mermaid 语法块表达：
 
-```text
-Phase 1（顺序执行）:
-  [change-name-1] -> [change-name-2]
+```mermaid
+flowchart TD
+  subgraph "Phase 1"
+    change_1["change-name-1"]
+  end
+
+  subgraph "Phase 2"
+    change_2["change-name-2"]
+    change_3["change-name-3"]
+  end
 
-Phase 2（Phase 1 后可并行）:
-  [change-name-3]
-  [change-name-4]
+  change_1 --> change_2
+  change_1 --> change_3
 ```
 
-复杂依赖追加表格：
+规则：
 
-| Change | 依赖 | 可并行 |
-|---|---|---|
-| change-name-3 | change-name-2 | change-name-4 |
+- 节点标签使用 change 名称。
+- phase 使用 `subgraph "Phase N"` 标记。
+- 并行 change 放在同一个 phase subgraph 中，不额外用表格重复表达。
+- 如果只有单个 change，仍保留 Mermaid 语法块，并只画一个节点。
 
 ## Change 详情模板
 

plugins/aisee-plugin/skills/aisee-spec-migrate/assets/migration-index-template.md

@@ -3,12 +3,23 @@
 用于生成 `aisee/docs/spec-migration/<YYYY-MM-DD>-<slug>/00-index.md`。
 
 ```markdown
+---
+title: "OpenSpec Baseline Migration：{project/module}"
+doc_type: "spec-migration"
+status: "draft"
+date: "{date}"
+scope: "{project/module/path}"
+owner: "{作者或团队}"
+source_refs:
+  - "{repo-relative source path or source ref}"
+change_refs: []
+---
+
 # OpenSpec Baseline Migration：{project/module}
 
 **文档编号**：SM-{YYYY-MM-DD}-{slug}
-**状态**：草稿 / 已写入 baseline / 待确认
-**范围**：{project/module/path}
-**创建日期**：{date}
+**版本**：v1.0
+**迁移范围**：{project/module/path}
 
 ---
 

src/aisee_cli/planning_docs.py

@@ -18,6 +18,7 @@
     "design-spec",
     "design-assets",
     "implementation-brief",
+    "spec-migration",
     "reflect",
 }
 VALID_STATUSES = {"draft", "active", "superseded", "archived"}
@@ -32,6 +33,8 @@
     "docs/design-spec/": "design-spec",
     "aisee/docs/design-assets/": "design-assets",
     "docs/design-assets/": "design-assets",
+    "aisee/docs/spec-migration/": "spec-migration",
+    "docs/spec-migration/": "spec-migration",
     "aisee/docs/reflect/": "reflect",
     "docs/reflect/": "reflect",
     "aisee/cache/implementation-bridge/": "implementation-brief",

tests/test_change_plan_mermaid_contract.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_change_plan_uses_mermaid_for_dependency_graph_contract() -> None:
+    output_template = (ROOT / "plugins/aisee-plugin/skills/aisee-change-plan/references/output-template.md").read_text(encoding="utf-8")
+    skill_text = (ROOT / "plugins/aisee-plugin/skills/aisee-change-plan/SKILL.md").read_text(encoding="utf-8")
+    algorithm_text = (ROOT / "plugins/aisee-plugin/skills/aisee-change-plan/references/change-boundary-algorithm.md").read_text(encoding="utf-8")
+
+    assert "## Mermaid 依赖图" in output_template
+    assert "```mermaid" in output_template
+    assert "flowchart TD" in output_template
+    assert "简单依赖链使用 ASCII" not in output_template
+    assert "| Change | 依赖 | 可并行 |" not in output_template
+    assert "使用 Mermaid 语法块输出依赖顺序和并行关系" in skill_text
+    assert "在 Mermaid 依赖图中用同一 phase 的 `subgraph` 明确标记并行组" in algorithm_text

tests/test_doctor_flow_schema.py

@@ -317,6 +317,36 @@ def test_doctor_reports_invalid_change_refs_in_planning_docs(tmp_path: Path) ->
     assert any(item["code"] == "PLANNING_DOC_STALE_ACTIVE" for item in data["issues"])
 
 
+def test_doctor_recognizes_spec_migration_docs_as_planning_docs(tmp_path: Path) -> None:
+    create_open_project(tmp_path)
+    write(
+        tmp_path / "aisee" / "docs" / "spec-migration" / "2026-06-12-auth" / "00-index.md",
+        """---
+title: "OpenSpec Baseline Migration：Auth"
+doc_type: "spec-migration"
+status: "draft"
+date: "2026-06-12"
+scope: "auth"
+owner: "Aisee"
+source_refs:
+  - "README.md"
+change_refs: []
+---
+
+# OpenSpec Baseline Migration：Auth
+""",
+    )
+
+    data = run_json(tmp_path, "doctor", "--json")
+
+    assert any(item["path"].endswith("aisee/docs/spec-migration/2026-06-12-auth/00-index.md") for item in data["aisee"]["planning_docs"]["items"])
+    assert not any(
+        item["code"] == "PLANNING_DOC_TYPE_INVALID"
+        and item["path"].endswith("aisee/docs/spec-migration/2026-06-12-auth/00-index.md")
+        for item in data["issues"]
+    )
+
+
 def test_bootstrap_plan_is_read_only(tmp_path: Path) -> None:
     data = run_json(tmp_path, "bootstrap", "--plan", "--json")
 

tests/test_skill_cli_preflight.py

@@ -35,6 +35,7 @@ def test_planning_doc_frontmatter_contract_exists_and_representative_templates_r
         "plugins/aisee-plugin/skills/aisee-design-spec/assets/design-spec-template-standard.md": 'doc_type: "design-spec"',
         "plugins/aisee-plugin/skills/aisee-design-assets/assets/design-assets-index-template.md": 'doc_type: "design-assets"',
         "plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-template.md": 'doc_type: "implementation-brief"',
+        "plugins/aisee-plugin/skills/aisee-spec-migrate/assets/migration-index-template.md": 'doc_type: "spec-migration"',
         "plugins/aisee-plugin/skills/aisee-reflect/references/output-templates.md": 'doc_type: "reflect"',
     }
     for relative_path, marker in expected.items():
@@ -158,6 +159,16 @@ def test_architecture_skill_keeps_change_plan_hints_fact_based() -> None:
             assert marker not in text
 
 
+def test_spec_migrate_template_uses_frontmatter_without_duplicate_header_metadata() -> None:
+    text = (ROOT / "plugins/aisee-plugin/skills/aisee-spec-migrate/assets/migration-index-template.md").read_text(encoding="utf-8")
+
+    assert 'doc_type: "spec-migration"' in text
+    assert "source_refs:" in text
+    assert "change_refs:" in text
+    assert "**状态**：" not in text
+    assert "**创建日期**：" not in text
+
+
 def test_cli_outputs_keep_marketplace_recovery_hints() -> None:
     import sys