plan-governance-cli 0.2.4 → 0.3.0

package/README.md

@@ -173,10 +173,25 @@ npm install -g plan-governance-cli
 plan-governance-cli check . --strict-readiness
 ```
 
+功能图谱校验和影响分析：
+
+```bash
+plan-governance-cli graph validate .
+plan-governance-cli graph impact --from feature.model-lifecycle --depth 2 --format text .
+plan-governance-cli graph impact --from feature.model-lifecycle --depth 2 --format json .
+plan-governance-cli plan impact --input docs/graph/fixtures/plan-impact/model-lifecycle-api.json --format json .
+plan-governance-cli graph code candidates --symbol APIHandler --kind class --format json .
+plan-governance-cli graph code impact --repo modelpad --file Sources/ModelPadCore/API/APIServer.swift --symbol APIHandler --kind class --depth 2 --format json .
+```
+
+项目图谱固定放在 `docs/graph/functional.yaml`。CLI 只读，不修改 YAML、计划状态、计划正文或业务代码；图谱节点使用稳定 ID，证据使用 `kind/ref/locator`，代码对象使用带文件回退的 `code_refs`。影响分析默认两跳，按 `contains`、`orchestrates`、`exposes`、`implements`、`consumes`、`depends_on` 的契约方向传播，并输出最短路径、直接/间接分类和证据引用。代码候选命令根据 `file/symbol/kind` 搜索稳定锚点；多候选输出 `resolution: ask_user`，不自动写回。
+
+`plan impact` 是计划治理的前置只读查询：输入文件声明 `graph_scope`、`change_kind`，默认只查询功能层；API 契约、数据、安全、外部边界或明确代码定位才升级到架构层或代码候选。输出查询层级、升级原因、行动分级、测试映射和未查询层级；失败不伪装成“无影响”，也不会触发 `gitnexus analyze`。
+
 也可以不全局安装，直接使用锁定版本：
 
 ```bash
-npx --yes --package plan-governance-cli@0.2.3 plan-governance-cli check . --strict-readiness
+npx --yes --package plan-governance-cli@0.3.0 plan-governance-cli check . --strict-readiness
 ```
 
 npm 包内部仍使用版本化的 Python 检查器，但用户不需要直接调用或复制该脚本。旧项目已有本地脚本时仍可保留作为兼容或回滚路径。
@@ -307,6 +322,8 @@ python3 -m pytest
 
 进入 `待实施` 前，当前阶段必须有明确目标/范围、Step 0 基线、样本或替代基线矩阵、可执行验证方式、失败与回滚边界、无未解决阻塞项，以及最新独立准入复核“通过”。复核记录追加保留，`PLAN_MAP.md` 只链接最新有效结论。
 
+机器识别的结构化章节标题固定为 `阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录`，不要在这些标题中插入或添加 `阶段 1` 等编号；阶段编号由 `PLAN_MAP.md` 的当前阶段提供。严格检查发现常见编号变体时，会在输出中给出直接修正提示。
+
 阶段准入严格检查命令为 `--strict-readiness`。默认检查先以 `WARNING` 提示历史文档中的机械缺陷；严格模式才返回非零退出码。该检查只判断结构化准入条件，不替代业务验收。
 
 ## Codex 使用方式

package/bin/plan-governance-cli.mjs

@@ -18,6 +18,7 @@ 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 graphRuntime = resolve(packageRoot, "scripts", "graph_governance.mjs");
 const manifestPath = resolve(packageRoot, "resources", "manifest.json");
 
 function fail(message) {
@@ -51,6 +52,24 @@ function runPython(script, args) {
   return result?.status ?? 1;
 }
 
+function runNode(script, args) {
+  try {
+    accessSync(script, constants.R_OK);
+  } catch {
+    return fail(`找不到包内脚本：${script}`);
+  }
+
+  const result = spawnSync(process.execPath, [script, ...args], { stdio: "inherit" });
+  if (result.error) {
+    return fail(`无法启动 Node.js 脚本：${result.error.message}`);
+  }
+  if (result.signal) {
+    console.error(`plan-governance-cli: 脚本被信号 ${result.signal} 终止`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
 function loadManifest() {
   try {
     return JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -168,6 +187,8 @@ function main() {
   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 === "graph") return runNode(graphRuntime, args.slice(1));
+  if (command === "plan") return runNode(graphRuntime, args);
   if (command === "check") return runPython(checker, args.slice(1));
   return runPython(checker, args);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-governance-cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "统一入口的计划治理检查 CLI",
   "private": false,
   "type": "module",
@@ -13,7 +13,8 @@
     "resources/skill",
     "scripts/check_plan_governance.py",
     "scripts/init_plan_governance.py",
-    "scripts/plan_governance_hook.py"
+    "scripts/plan_governance_hook.py",
+    "scripts/graph_governance.mjs"
   ],
   "engines": {
     "node": ">=20"
@@ -22,6 +23,9 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test tests/npm_cli.test.mjs"
+    "test": "node --test tests/npm_cli.test.mjs tests/graph_cli.test.mjs tests/architecture_graph_cli.test.mjs tests/plan_impact_step0.test.mjs tests/plan_impact_cli.test.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }

package/resources/manifest.json

@@ -17,7 +17,8 @@
   "runtime": [
     "scripts/check_plan_governance.py",
     "scripts/init_plan_governance.py",
-    "scripts/plan_governance_hook.py"
+    "scripts/plan_governance_hook.py",
+    "scripts/graph_governance.mjs"
   ],
   "hooks": []
 }

package/resources/skill/SKILL.md

@@ -119,7 +119,7 @@ docs/
 5. 没有未解决的当前阶段阻塞项，且 `PLAN_MAP.md` 已同步。
 6. 最新独立准入复核明确为“通过”。
 
-阶段准入摘要应使用固定字段：`准入状态`、`Step 0`、`样本矩阵`、`验证方式`、`失败/回滚边界`、`当前阻塞项`、`最新独立准入复核`。阶段身份以 `PLAN_MAP.md` 为准，不在计划正文中另定义阶段编号。
+机器识别的结构化章节标题必须保持固定名称：`阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录`。不要在这些标题前添加阶段编号（例如不要写成 `阶段 1 准入摘要` 或 `阶段 1 最新独立准入复核`）；阶段身份以 `PLAN_MAP.md` 为准，不在计划正文中另定义阶段编号。若严格检查提示标题问题，优先按提示恢复固定标题。阶段准入摘要还必须使用固定字段：`准入状态`、`Step 0`、`样本矩阵`、`验证方式`、`失败/回滚边界`、`当前阻塞项`、`最新独立准入复核`。
 
 ### 独立复核记录
 
@@ -261,6 +261,34 @@ plan-governance-cli check . --stale-days 10
 - `--attest <plan-name>`：为已登记计划创建或覆盖 `docs/attestations/<plan-name>.json` 完成快照。
 - `--check-attestations`：检查完成快照中的计划文件和 `PLAN_MAP.md` hash 是否漂移；漂移、缺失或 JSON 损坏只输出 `WARNING`，不改变退出码。
 
+## 图谱与计划前置影响分析
+
+当项目声明了功能图谱或架构图谱时，使用 npm CLI 的只读命令查询影响范围：
+
+```bash
+plan-governance-cli graph validate .
+plan-governance-cli graph impact --from feature.model-lifecycle --depth 2 --format json .
+plan-governance-cli graph code candidates --symbol APIHandler --kind class --format json .
+plan-governance-cli graph code impact \
+  --repo modelpad \
+  --file Sources/ModelPadCore/API/APIServer.swift \
+  --symbol APIHandler \
+  --kind class \
+  --format json .
+```
+
+计划前置分析使用计划输入文件：
+
+```bash
+plan-governance-cli plan impact \
+  --input docs/graph/fixtures/plan-impact/model-lifecycle-api.json \
+  --format json .
+```
+
+`plan impact` 默认只查询功能层；API 契约、数据迁移、安全、外部边界或明确要求代码定位时，才升级到架构层或代码层。输出包含查询层级、升级原因、影响节点、行动分级、测试映射和未查询层级。`graph validate`、`graph impact`、代码查询和 `plan impact` 全部只读，不修改 YAML、计划、代码或 GitNexus 索引；失败也不能被解释为“无影响”。
+
+GitNexus 只在需要代码定位时使用。CLI 不自动执行 `gitnexus analyze`，也不自动写回 UID 或 YAML；候选映射由 LLM 依据文件、符号、类型和测试等证据确认，证据不足或存在多个合理候选时再请求用户确认。
+
 `影响模块或文件` 的作用域匹配规则：
 
 - `--drift`、`--pre-commit` 和 `plan_governance_hook.py --event pre-write` 使用同一语义。

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

@@ -40,6 +40,7 @@
 
 待确认。若涉及 API、Schema、兼容性或迁移行为，需要在这里明确。
 
+<!-- 机器识别的结构化章节标题必须保持固定名称，不要在标题前添加“阶段 1”等编号。 -->
 ## 阶段路线图
 
 | 阶段 | 目标 | 进入条件 | 验证方向 | 状态 |
@@ -52,6 +53,7 @@
 
 待补充。
 
+<!-- 标题必须保持为“阶段准入摘要”，不要改成“阶段 1 准入摘要”等带编号变体；阶段身份以 PLAN_MAP.md 为准。 -->
 ### 阶段准入摘要
 
 | 字段 | 内容 |

package/scripts/check_plan_governance.py

@@ -116,6 +116,32 @@ def key_value_table(section):
     return values
 
 
+def numbered_structural_heading(plan_text, heading_names):
+    """查找误把阶段编号写入结构化章节标题的常见形式。"""
+    phase_number = r"[0-9一二三四五六七八九十百]+"
+    variants = []
+    for name in heading_names:
+        variants.append(rf"阶段\s*{phase_number}\s+{re.escape(name)}")
+        if name.startswith("阶段"):
+            variants.append(rf"阶段\s*{phase_number}\s*{re.escape(name[2:])}")
+    pattern = re.compile(
+        rf"^#+\s+((?:{'|'.join(variants)}))\s*$",
+        re.MULTILINE,
+    )
+    match = pattern.search(mask_fenced_code(plan_text))
+    return match.group(1) if match else None
+
+
+def structural_heading_hint(plan_text, heading_name):
+    numbered_heading = numbered_structural_heading(plan_text, [heading_name])
+    if not numbered_heading:
+        return ""
+    return (
+        f"；检测到标题 `{numbered_heading}`，请改为固定标题 "
+        f"`{heading_name}`，阶段编号以 `PLAN_MAP.md` 的当前阶段为准"
+    )
+
+
 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] != "阶段"]
@@ -160,11 +186,12 @@ def check_phase_readiness(plan_map_text, plan_name, data, plan_text, strict, war
     roadmap = phase_roadmap_rows(plan_text)
     matching_rows = [row for row in roadmap if row and row[0] == current_phase]
     if not matching_rows:
+        roadmap_hint = structural_heading_hint(plan_text, "阶段路线图")
         readiness_issue(
             warnings,
             errors,
             strict,
-            f"{plan_name}: PLAN_MAP 当前阶段 {current_phase} 未在计划阶段路线图中找到",
+            f"{plan_name}: PLAN_MAP 当前阶段 {current_phase} 未在计划阶段路线图中找到{roadmap_hint}",
         )
     else:
         roadmap_status = matching_rows[-1][4] if len(matching_rows[-1]) > 4 else ""
@@ -177,16 +204,21 @@ def check_phase_readiness(plan_map_text, plan_name, data, plan_text, strict, war
             )
 
     if markdown_section(plan_text, ["当前阶段"]) is None:
-        readiness_issue(warnings, errors, strict, f"{plan_name}: 缺少 `## 当前阶段` 章节")
+        section_hint = structural_heading_hint(plan_text, "当前阶段")
+        readiness_issue(warnings, errors, strict, f"{plan_name}: 缺少 `## 当前阶段` 章节{section_hint}")
 
-    summary = key_value_table(markdown_section(plan_text, ["阶段准入摘要"]))
+    summary_section = markdown_section(plan_text, ["阶段准入摘要"])
+    summary = key_value_table(summary_section)
     missing_fields = sorted(READINESS_FIELDS - set(summary))
     if missing_fields:
+        title_hint = ""
+        if summary_section is None:
+            title_hint = structural_heading_hint(plan_text, "阶段准入摘要")
         readiness_issue(
             warnings,
             errors,
             strict,
-            f"{plan_name}: 阶段准入摘要缺少字段：{', '.join(missing_fields)}",
+            f"{plan_name}: 阶段准入摘要缺少字段：{', '.join(missing_fields)}{title_hint}",
         )
     for field in sorted(READINESS_FIELDS - {"当前阻塞项"}):
         if field in summary and is_placeholder(summary[field]):
@@ -215,11 +247,12 @@ def check_phase_readiness(plan_map_text, plan_name, data, plan_text, strict, war
     review_fields = {"日期", "阶段", "结论", "证据", "复核者"}
     missing_review = sorted(review_fields - set(review))
     if missing_review:
+        review_hint = structural_heading_hint(plan_text, "最新独立准入复核")
         readiness_issue(
             warnings,
             errors,
             strict,
-            f"{plan_name}: 最新独立准入复核缺少字段：{', '.join(missing_review)}",
+            f"{plan_name}: 最新独立准入复核缺少字段：{', '.join(missing_review)}{review_hint}",
         )
     if review.get("日期"):
         try:
@@ -243,7 +276,13 @@ def check_phase_readiness(plan_map_text, plan_name, data, plan_text, strict, war
 
     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} 的记录")
+        history_hint = structural_heading_hint(plan_text, "独立复核记录")
+        readiness_issue(
+            warnings,
+            errors,
+            strict,
+            f"{plan_name}: 独立复核记录缺少当前阶段 {current_phase} 的记录{history_hint}",
+        )
     else:
         latest_history = history[-1]
         if review.get("日期") and latest_history[0] != review["日期"]:

package/scripts/graph_governance.mjs

@@ -0,0 +1,988 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
+
+const RELATION_TYPES = new Set([
+  "contains",
+  "orchestrates",
+  "exposes",
+  "implements",
+  "consumes",
+  "depends_on",
+]);
+const ARCHITECTURE_RELATION_TYPES = new Set([
+  "contains",
+  "exposes",
+  "crosses",
+  "anchors_to",
+  "realized_by",
+]);
+const NODE_TYPES = new Set([
+  "business",
+  "function",
+  "process",
+  "api",
+  "external_workflow",
+]);
+const ARCHITECTURE_NODE_TYPES = new Set([
+  "system",
+  "module",
+  "component",
+  "service",
+  "interface",
+  "data_boundary",
+  "trust_boundary",
+]);
+const EVIDENCE_KINDS = new Set(["document", "code", "test", "api", "gitnexus"]);
+const FORWARD_RELATIONS = new Set(["exposes", "implements"]);
+const REVERSE_RELATIONS = new Set(["contains", "orchestrates", "consumes", "depends_on"]);
+const PLAN_CHANGE_KINDS = new Set([
+  "behavior_change",
+  "api_contract_change",
+  "internal_refactor",
+  "data_migration",
+  "security_change",
+]);
+const PLAN_UPGRADE_SIGNALS = new Set(["external_boundary"]);
+const LEGACY_NON_FUNCTIONAL_PREFIXES = ["api.", "code.", "test.", "document."];
+
+function usage() {
+  console.log(`用法：
+  plan-governance-cli graph validate [--layer functional|architecture] [root]
+  plan-governance-cli graph impact --from <graph-node-id> [--depth 2] [--format text|json] [root]
+  plan-governance-cli plan impact --input <plan-impact-request.json> [--format text|json] [root]
+  plan-governance-cli graph code candidates [--file <relative-path>] --symbol <symbol> --kind class|function [--format text|json] [root]
+  plan-governance-cli graph code impact --repo <gitnexus-repo> --file <relative-path> --symbol <symbol> --kind <kind> [--depth 3] [--format text|json] [root]
+
+功能图谱文件：<root>/docs/graph/functional.yaml
+架构图谱入口：<root>/docs/graph/architecture/index.yaml`);
+}
+
+function error(message) {
+  console.error(`graph: ERROR: ${message}`);
+  return 1;
+}
+
+function graphPath(root) {
+  return resolve(root, "docs", "graph", "functional.yaml");
+}
+
+function functionalIndexPath(root) {
+  return resolve(root, "docs", "graph", "functional", "index.yaml");
+}
+
+function architectureIndexPath(root) {
+  return resolve(root, "docs", "graph", "architecture", "index.yaml");
+}
+
+function readYamlFile(path, label) {
+  if (!existsSync(path)) throw new Error(`缺少${label}：${path}`);
+  try {
+    return parseYaml(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`${label} YAML 解析失败：${cause.message}`);
+  }
+}
+
+function loadGraph(root) {
+  const indexPath = functionalIndexPath(root);
+  if (!existsSync(indexPath)) {
+    const path = graphPath(root);
+    const graph = readYamlFile(path, "图谱文件");
+    return { graph, path };
+  }
+  const index = readYamlFile(indexPath, "功能图谱入口");
+  const issues = [];
+  if (!index || typeof index !== "object" || Array.isArray(index)) throw new Error("功能图谱入口必须是 YAML 对象");
+  if (index.schema_version !== 1) issues.push(`功能图谱 schema_version 必须为 1，实际为 ${index.schema_version ?? "<missing>"}`);
+  if (index.layer !== "functional") issues.push(`功能图谱 layer 必须为 functional，实际为 ${index.layer ?? "<missing>"}`);
+  const files = asPathList(index.files, "功能图谱 files", issues);
+  if (issues.length > 0) throw new Error(issues.join("；"));
+  const documents = files.map((relativePath) => readYamlFile(resolve(indexPath, "..", relativePath), "功能图谱领域文件"));
+  const graph = mergeGraphDocuments(documents);
+  return {
+    graph: {
+      schema_version: 1,
+      project: index.project,
+      gitnexus: index.gitnexus,
+      nodes: graph.nodes,
+      relations: graph.relations,
+      code_refs: graph.codeRefs,
+    },
+    path: indexPath,
+  };
+}
+
+function asPathList(value, label, issues) {
+  if (!Array.isArray(value) || value.length === 0) {
+    issues.push(`${label} 必须是非空数组`);
+    return [];
+  }
+  return value.map((entry, index) => {
+    if (typeof entry === "string" && entry.length > 0) return entry;
+    if (entry && typeof entry.path === "string" && entry.path.length > 0) return entry.path;
+    issues.push(`${label}[${index}] 必须是路径字符串或包含 path 的对象`);
+    return null;
+  }).filter(Boolean);
+}
+
+function mergeGraphDocuments(documents) {
+  return documents.reduce((merged, document) => ({
+    nodes: [...merged.nodes, ...asArray(document.nodes)],
+    relations: [...merged.relations, ...asArray(document.relations)],
+    codeMappings: [...merged.codeMappings, ...asArray(document.code_mappings)],
+  }), { nodes: [], relations: [], codeMappings: [] });
+}
+
+function loadReferencedNodeIds(path, label) {
+  const document = readYamlFile(path, label);
+  const ids = new Set(asArray(document.nodes)
+    .map((node) => node?.id)
+    .filter((id) => typeof id === "string"));
+  if (document.files !== undefined) {
+    const issues = [];
+    const files = asPathList(document.files, `${label} files`, issues);
+    if (issues.length > 0) throw new Error(issues.join("；"));
+    files.forEach((relativePath) => {
+      const childPath = resolve(path, "..", relativePath);
+      loadReferencedNodeIds(childPath, `${label}领域文件`).forEach((id) => ids.add(id));
+    });
+  }
+  return ids;
+}
+
+function loadArchitectureGraph(root) {
+  const indexPath = architectureIndexPath(root);
+  const index = readYamlFile(indexPath, "架构图谱入口");
+  const indexIssues = [];
+  if (!index || typeof index !== "object" || Array.isArray(index)) {
+    throw new Error("架构图谱入口必须是 YAML 对象");
+  }
+  if (index.schema_version !== 1) indexIssues.push(`架构图谱 schema_version 必须为 1，实际为 ${index.schema_version ?? "<missing>"}`);
+  if (index.layer !== "architecture") indexIssues.push(`架构图谱 layer 必须为 architecture，实际为 ${index.layer ?? "<missing>"}`);
+  const files = asPathList(index.files, "架构图谱 files", indexIssues);
+  const documents = files.map((relativePath) => readYamlFile(resolve(indexPath, "..", relativePath), "架构图谱领域文件"));
+  const graph = mergeGraphDocuments(documents);
+  const externalIds = new Set();
+  const functionalReference = index.references?.functional;
+  if (functionalReference !== undefined) {
+    const referencePath = typeof functionalReference === "string"
+      ? functionalReference
+      : functionalReference?.path;
+    if (typeof referencePath !== "string" || referencePath.length === 0) {
+      indexIssues.push("架构图谱 references.functional 必须包含 path");
+    } else {
+      loadReferencedNodeIds(resolve(indexPath, "..", referencePath), "功能图谱引用")
+        .forEach((id) => externalIds.add(id));
+    }
+  }
+  if (indexIssues.length > 0) throw new Error(indexIssues.join("；"));
+  return {
+    graph: {
+      schema_version: 1,
+      nodes: graph.nodes,
+      relations: graph.relations,
+      code_mappings: graph.codeMappings,
+    },
+    path: indexPath,
+    externalIds,
+  };
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function validateEvidence(evidence, label, root, issues) {
+  if (!Array.isArray(evidence) || evidence.length === 0) {
+    issues.push(`${label} 缺少 evidence`);
+    return;
+  }
+  evidence.forEach((item, index) => {
+    const prefix = `${label}.evidence[${index}]`;
+    if (!item || typeof item !== "object") {
+      issues.push(`${prefix} 必须是对象`);
+      return;
+    }
+    if (!EVIDENCE_KINDS.has(item.kind)) issues.push(`${prefix}.kind 不受支持：${item.kind ?? "<missing>"}`);
+    if (typeof item.ref !== "string" || item.ref.length === 0) issues.push(`${prefix}.ref 缺失`);
+    if (typeof item.locator !== "string" || item.locator.length === 0) issues.push(`${prefix}.locator 缺失`);
+    if (typeof item.ref === "string" && item.ref.length > 0 && item.kind !== "gitnexus") {
+      const target = isAbsolute(item.ref) ? item.ref : resolve(root, item.ref);
+      if (!existsSync(target)) issues.push(`${prefix}.ref 不存在：${item.ref}`);
+    }
+  });
+}
+
+function detectCycles(nodes, relations) {
+  const edges = new Map(nodes.map((node) => [node.id, []]));
+  relations.forEach((relation) => edges.get(relation.from)?.push(relation.to));
+  const visiting = new Set();
+  const visited = new Set();
+  const cycles = [];
+
+  function visit(node, path) {
+    if (visiting.has(node)) {
+      const start = path.indexOf(node);
+      cycles.push([...path.slice(start), node].join(" -> "));
+      return;
+    }
+    if (visited.has(node)) return;
+    visiting.add(node);
+    for (const next of edges.get(node) ?? []) visit(next, [...path, node]);
+    visiting.delete(node);
+    visited.add(node);
+  }
+
+  for (const node of edges.keys()) visit(node, []);
+  return cycles;
+}
+
+function normalizeGraph(raw, root, options = {}) {
+  const issues = [];
+  const nodeTypes = options.layer === "architecture" ? ARCHITECTURE_NODE_TYPES : NODE_TYPES;
+  const relationTypes = options.layer === "architecture" ? ARCHITECTURE_RELATION_TYPES : RELATION_TYPES;
+  const externalIds = options.externalIds ?? new Set();
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { issues: ["根文档必须是 YAML 对象"], nodes: [], relations: [] };
+  }
+  if (raw.schema_version !== 1) issues.push(`schema_version 必须为 1，实际为 ${raw.schema_version ?? "<missing>"}`);
+  if (raw.project !== undefined && (!raw.project || typeof raw.project.id !== "string" || typeof raw.project.name !== "string")) {
+    issues.push("project.id 和 project.name 必须同时存在且为字符串");
+  }
+  const nodes = asArray(raw.nodes);
+  const relations = asArray(raw.relations);
+  const codeMappings = asArray(raw.code_mappings);
+  if (nodes.length === 0) issues.push("nodes 不能为空");
+  if (!Array.isArray(raw.nodes)) issues.push("nodes 必须是数组");
+  if (!Array.isArray(raw.relations)) issues.push("relations 必须是数组");
+
+  const ids = new Set();
+  nodes.forEach((node, index) => {
+    const label = `nodes[${index}]`;
+    if (!node || typeof node !== "object") {
+      issues.push(`${label} 必须是对象`);
+      return;
+    }
+    if (typeof node.id !== "string" || node.id.length === 0) issues.push(`${label}.id 缺失`);
+    else if (!/^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$/.test(node.id)) issues.push(`${label}.id 必须是由 . 分隔、段内仅含小写字母数字和连字符的标识`);
+    else if (ids.has(node.id)) issues.push(`节点 ID 重复：${node.id}`);
+    else ids.add(node.id);
+    if (!nodeTypes.has(node.type)) issues.push(`${label}.type 不受支持：${node.type ?? "<missing>"}`);
+    if (typeof node.name !== "string" || node.name.length === 0) issues.push(`${label}.name 缺失`);
+    validateEvidence(node.evidence, label, root, issues);
+    asArray(node.code_refs).forEach((ref, refIndex) => {
+      const prefix = `${label}.code_refs[${refIndex}]`;
+      if (!ref || typeof ref !== "object") issues.push(`${prefix} 必须是对象`);
+      else {
+        if (ref.kind !== "gitnexus_uid") issues.push(`${prefix}.kind 必须为 gitnexus_uid`);
+        if (typeof ref.ref !== "string" || ref.ref.length === 0) issues.push(`${prefix}.ref 缺失`);
+        if (typeof ref.fallback !== "string" || ref.fallback.length === 0) issues.push(`${prefix}.fallback 缺失`);
+        const fallbackIsRoute = typeof ref.fallback === "string" && ref.fallback.startsWith("/");
+        if (typeof ref.fallback === "string" && !fallbackIsRoute && !existsSync(resolve(root, ref.fallback))) {
+          issues.push(`${prefix}.fallback 不存在：${ref.fallback}`);
+        }
+      }
+    });
+  });
+
+  const seenRelations = new Set();
+  relations.forEach((relation, index) => {
+    const label = `relations[${index}]`;
+    if (!relation || typeof relation !== "object") {
+      issues.push(`${label} 必须是对象`);
+      return;
+    }
+    const externalFrom = externalIds.has(relation.from);
+    const externalTo = externalIds.has(relation.to);
+    const allowsExternalFrom = options.layer === "architecture" && relation.type === "realized_by";
+    if (!ids.has(relation.from) && !(allowsExternalFrom && externalFrom)) issues.push(`${label}.from 指向悬空节点：${relation.from ?? "<missing>"}`);
+    if (!ids.has(relation.to)) issues.push(`${label}.to 指向悬空节点：${relation.to ?? "<missing>"}`);
+    if (!relationTypes.has(relation.type)) issues.push(`${label}.type 不受支持：${relation.type ?? "<missing>"}`);
+    if (options.layer === "architecture" && relation.type === "realized_by" && !externalFrom) {
+      issues.push(`${label}.realized_by.from 必须指向功能图谱引用中的节点：${relation.from ?? "<missing>"}`);
+    }
+    if (options.layer === "architecture" && relation.type === "realized_by" && externalTo) {
+      issues.push(`${label}.realized_by.to 必须指向架构层节点：${relation.to}`);
+    }
+    if (relation.from === relation.to) issues.push(`${label} 不允许自环：${relation.from}`);
+    const key = `${relation.from}|${relation.type}|${relation.to}`;
+    if (seenRelations.has(key)) issues.push(`关系重复：${key}`);
+    seenRelations.add(key);
+    validateEvidence(relation.evidence, label, root, issues);
+  });
+
+  if (options.layer === "architecture") {
+    if (raw.code_mappings !== undefined && !Array.isArray(raw.code_mappings)) {
+      issues.push("code_mappings 必须是数组");
+    }
+    const seenCodeAnchors = new Set();
+    codeMappings.forEach((mapping, index) => {
+      const label = `code_mappings[${index}]`;
+      if (!mapping || typeof mapping !== "object") {
+        issues.push(`${label} 必须是对象`);
+        return;
+      }
+      if (typeof mapping.architecture_id !== "string" || mapping.architecture_id.length === 0) {
+        issues.push(`${label}.architecture_id 缺失`);
+      } else if (!ids.has(mapping.architecture_id)) {
+        issues.push(`${label}.architecture_id 指向悬空架构节点：${mapping.architecture_id}`);
+      }
+      const anchor = mapping.code_anchor;
+      if (!anchor || typeof anchor !== "object") {
+        issues.push(`${label}.code_anchor 必须是对象`);
+        return;
+      }
+      if (typeof anchor.file !== "string" || anchor.file.length === 0) {
+        issues.push(`${label}.code_anchor.file 缺失`);
+      } else {
+        const absoluteFile = isAbsolute(anchor.file) ? anchor.file : resolve(root, anchor.file);
+        if (!existsSync(absoluteFile)) issues.push(`${label}.code_anchor.file 不存在：${anchor.file}`);
+      }
+      if (typeof anchor.symbol !== "string" || anchor.symbol.length === 0) issues.push(`${label}.code_anchor.symbol 缺失`);
+      if (typeof anchor.kind !== "string" || anchor.kind.length === 0) issues.push(`${label}.code_anchor.kind 缺失`);
+      if (anchor.gitnexus_uid !== undefined && (typeof anchor.gitnexus_uid !== "string" || anchor.gitnexus_uid.length === 0)) {
+        issues.push(`${label}.code_anchor.gitnexus_uid 必须是非空字符串`);
+      }
+      if (typeof mapping.architecture_id === "string" && typeof anchor.file === "string"
+        && typeof anchor.symbol === "string" && typeof anchor.kind === "string") {
+        const key = `${mapping.architecture_id}|${anchor.file}|${anchor.symbol}|${anchor.kind}`;
+        if (seenCodeAnchors.has(key)) issues.push(`代码锚点重复：${key}`);
+        seenCodeAnchors.add(key);
+      }
+    });
+  }
+
+  return { issues, nodes, relations, codeMappings, meta: raw };
+}
+
+function validate(root, layer = "functional") {
+  const loaded = layer === "architecture" ? loadArchitectureGraph(root) : loadGraph(root);
+  const result = normalizeGraph(loaded.graph, root, { layer, externalIds: loaded.externalIds });
+  if (result.issues.length > 0) {
+    result.issues.forEach((issue) => console.error(`graph: ERROR: ${issue}`));
+    return 1;
+  }
+  const warnings = [];
+  const gitnexusRefs = result.nodes.flatMap((node) => asArray(node.code_refs)
+    .filter((ref) => ref.kind === "gitnexus_uid")
+    .map((ref) => ({ node, ref })));
+  const gitnexusRepo = result.meta.gitnexus?.repo;
+  if (gitnexusRefs.length > 0 && existsSync(resolve(root, ".gitnexus")) && gitnexusRepo) {
+    for (const { node, ref } of gitnexusRefs) {
+      const check = spawnSync("gitnexus", ["context", "-r", gitnexusRepo, "--uid", ref.ref], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (check.error?.code === "ENOENT") {
+        warnings.push("GitNexus CLI 不在 PATH 中，已跳过 UID 实体验证；保留 code_refs.fallback");
+        break;
+      }
+      let contextResult;
+      try {
+        contextResult = JSON.parse(check.stdout ?? "");
+      } catch {
+        contextResult = null;
+      }
+      if (check.status !== 0 || !contextResult || contextResult.status !== "found") {
+        const detail = contextResult?.error ?? (check.stderr || `退出码 ${check.status}`);
+        result.issues.push(`${node.id}.code_refs GitNexus UID 失配：${ref.ref}；回退：${ref.fallback}`);
+        if (detail) result.issues.push(`${node.id}.code_refs GitNexus 响应：${String(detail).trim()}`);
+      }
+    }
+  } else if (gitnexusRefs.length > 0) {
+    warnings.push("当前项目没有可用的 .gitnexus 索引，GitNexus UID 标记为待解析；将使用 fallback");
+  }
+  if (result.issues.length > 0) {
+    result.issues.forEach((issue) => console.error(`graph: ERROR: ${issue}`));
+    return 1;
+  }
+  console.log(`${layer === "architecture" ? "架构图谱" : "图谱"}校验通过：${loaded.path}`);
+  warnings.forEach((warning) => console.log(`graph: WARNING: ${warning}`));
+  const mappingText = layer === "architecture" ? `，代码锚点 ${result.codeMappings.length} 个` : "";
+  console.log(`schema_version=1，节点 ${result.nodes.length} 个，关系 ${result.relations.length} 条，GitNexus 引用 ${gitnexusRefs.length} 个${mappingText}`);
+  return 0;
+}
+
+function parseValidateArgs(args) {
+  const options = { layer: "functional", root: process.cwd() };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--layer") options.layer = args[++index];
+    else if (arg === "-h" || arg === "--help") return null;
+    else positional.push(arg);
+  }
+  if (!["functional", "architecture"].includes(options.layer)) {
+    throw new Error("validate --layer 只能是 functional 或 architecture");
+  }
+  if (positional.length > 1) throw new Error("validate 只能接收一个 root 路径");
+  if (positional.length === 1) options.root = resolve(positional[0]);
+  return options;
+}
+
+function parseImpactArgs(args) {
+  const options = { from: null, depth: 2, format: "text", root: process.cwd() };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--from") options.from = args[++index];
+    else if (arg === "--depth") options.depth = Number(args[++index]);
+    else if (arg === "--format") options.format = args[++index];
+    else if (arg === "-h" || arg === "--help") return null;
+    else positional.push(arg);
+  }
+  if (positional.length > 0) options.root = resolve(positional.at(-1));
+  if (!options.from) throw new Error("impact 必须指定 --from <graph-node-id>");
+  if (!Number.isInteger(options.depth) || options.depth < 1 || options.depth > 10) throw new Error("--depth 必须是 1 到 10 的整数");
+  if (!["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
+  return options;
+}
+
+function parsePlanImpactArgs(args) {
+  const options = { input: null, format: "text", root: process.cwd() };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--input") options.input = args[++index];
+    else if (arg === "--format") options.format = args[++index];
+    else if (arg === "-h" || arg === "--help") return null;
+    else positional.push(arg);
+  }
+  if (positional.length > 1) throw new Error("plan impact 只能接收一个 root 路径");
+  if (positional.length === 1) options.root = resolve(positional[0]);
+  if (!options.input) throw new Error("plan impact 必须指定 --input <plan-impact-request.json>");
+  if (!options.format || !["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
+  if (!existsSync(options.root)) throw new Error(`root 不存在：${options.root}`);
+  return options;
+}
+
+function loadPlanImpactRequest(root, input) {
+  const path = isAbsolute(input) ? input : resolve(root, input);
+  const request = readYamlFile(path, "计划影响输入");
+  if (!request || typeof request !== "object" || Array.isArray(request)) throw new Error("计划影响输入必须是 JSON/YAML 对象");
+  if (typeof request.graph_scope !== "string" || !request.graph_scope.startsWith("feature.")) {
+    throw new Error("计划影响输入 graph_scope 必须是功能节点");
+  }
+  if (!PLAN_CHANGE_KINDS.has(request.change_kind)) {
+    throw new Error(`计划影响输入 change_kind 不受支持：${request.change_kind ?? "<missing>"}`);
+  }
+  const upgradeSignals = request.upgrade_signals ?? [];
+  if (!Array.isArray(upgradeSignals) || upgradeSignals.some((signal) => !PLAN_UPGRADE_SIGNALS.has(signal))) {
+    throw new Error("计划影响输入 upgrade_signals 只支持 external_boundary");
+  }
+  if (request.code_locator_requested !== undefined && typeof request.code_locator_requested !== "boolean") {
+    throw new Error("计划影响输入 code_locator_requested 必须是布尔值");
+  }
+  if (request.code_locator_requested) {
+    const anchor = request.code_anchor;
+    if (!anchor || typeof anchor !== "object") throw new Error("code_locator_requested=true 时必须提供 code_anchor");
+    for (const field of ["file", "symbol", "kind"]) {
+      if (typeof anchor[field] !== "string" || anchor[field].length === 0) throw new Error(`code_anchor.${field} 缺失`);
+    }
+  } else if (request.code_anchor !== undefined) {
+    throw new Error("未请求代码定位时不得提供 code_anchor");
+  }
+  return { request, path };
+}
+
+const CODE_FILE_GLOBS = [
+  "*.c", "*.cc", "*.cpp", "*.cs", "*.go", "*.h", "*.java", "*.js", "*.jsx",
+  "*.kt", "*.m", "*.mm", "*.mjs", "*.php", "*.py", "*.rb", "*.rs", "*.swift",
+  "*.ts", "*.tsx",
+];
+
+function codeCandidatePattern(kind, symbol) {
+  const escaped = symbol.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+  const modifiers = "(?:(?:public|private|fileprivate|internal|open|final|static|abstract|sealed|override|async)\\s+)*";
+  if (kind === "class") return `^\\s*${modifiers}(?:class|struct|enum|actor|protocol)\\s+${escaped}\\b`;
+  if (kind === "function") return `^\\s*${modifiers}(?:func|def|function)\\s+${escaped}\\s*\\(`;
+  throw new Error("--kind 首期只能是 class 或 function");
+}
+
+function listCodeFiles(root) {
+  const args = ["--files", "--hidden", "-g", "!.git", "-g", "!node_modules", "-g", "!.build", "-g", "!dist"];
+  CODE_FILE_GLOBS.forEach((glob) => args.push("-g", glob));
+  const result = spawnSync("rg", args, { cwd: root, encoding: "utf8" });
+  if (result.error?.code === "ENOENT") throw new Error("候选报告需要 rg，但当前 PATH 中找不到 rg");
+  if (result.status === 1) return [];
+  if (result.status !== 0) throw new Error(`候选报告无法列出代码文件：${(result.stderr || `退出码 ${result.status}`).trim()}`);
+  return (result.stdout ?? "").split("\n").filter(Boolean);
+}
+
+function runCodeCandidateSearch(root, options) {
+  let files;
+  if (options.file && existsSync(resolve(root, options.file))) {
+    files = [options.file];
+  } else {
+    files = listCodeFiles(root);
+  }
+  if (files.length === 0) return [];
+
+  const args = ["--with-filename", "--no-heading", "--color", "never", "-n", "-e", codeCandidatePattern(options.kind, options.symbol), "--", ...files];
+  const result = spawnSync("rg", args, { cwd: root, encoding: "utf8" });
+  if (result.error?.code === "ENOENT") throw new Error("候选报告需要 rg，但当前 PATH 中找不到 rg");
+  if (result.status > 1) throw new Error(`候选报告搜索失败：${(result.stderr || `退出码 ${result.status}`).trim()}`);
+  return (result.stdout ?? "").split("\n").filter(Boolean).map((line) => {
+    const firstColon = line.indexOf(":");
+    const secondColon = line.indexOf(":", firstColon + 1);
+    return {
+      file: line.slice(0, firstColon),
+      line: Number(line.slice(firstColon + 1, secondColon)),
+      symbol: options.symbol,
+      kind: options.kind,
+    };
+  }).sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line);
+}
+
+function parseCodeCandidatesArgs(args) {
+  const options = { file: null, symbol: null, kind: null, format: "text", root: process.cwd() };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--file") options.file = args[++index];
+    else if (arg === "--symbol") options.symbol = args[++index];
+    else if (arg === "--kind") options.kind = args[++index];
+    else if (arg === "--format") options.format = args[++index];
+    else if (arg === "-h" || arg === "--help") return null;
+    else positional.push(arg);
+  }
+  if (positional.length > 1) throw new Error("code candidates 只能接收一个 root 路径");
+  if (positional.length === 1) options.root = resolve(positional[0]);
+  if (!options.symbol) throw new Error("code candidates 必须指定 --symbol <symbol>");
+  if (!options.kind) throw new Error("code candidates 必须指定 --kind <kind>");
+  if (!options.file && options.file !== null) throw new Error("--file 必须指定路径");
+  if (!options.format || !["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
+  if (!existsSync(options.root)) throw new Error(`root 不存在：${options.root}`);
+  return options;
+}
+
+function codeCandidates(root, options) {
+  const candidates = runCodeCandidateSearch(root, options);
+  const resolution = candidates.length === 1
+    ? "unique_candidate"
+    : candidates.length > 1 ? "ask_user" : "no_candidate";
+  return {
+    schema_version: 1,
+    query: { file: options.file, symbol: options.symbol, kind: options.kind },
+    resolution,
+    candidates,
+  };
+}
+
+function printCodeCandidatesText(result) {
+  console.log(`代码候选报告：${result.query.symbol}（${result.query.kind}）`);
+  console.log(`目标文件：${result.query.file ?? "未限定"}`);
+  console.log(`resolution: ${result.resolution}`);
+  if (result.candidates.length === 0) {
+    console.log("候选：\n- 无");
+    return;
+  }
+  console.log("候选：");
+  result.candidates.forEach((candidate) => {
+    console.log(`- ${candidate.file}:${candidate.line} ${candidate.symbol}（${candidate.kind}）`);
+  });
+}
+
+function parseCodeImpactArgs(args) {
+  const options = { repo: null, file: null, symbol: null, kind: null, depth: 3, format: "text", root: process.cwd() };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--repo") options.repo = args[++index];
+    else if (arg === "--file") options.file = args[++index];
+    else if (arg === "--symbol") options.symbol = args[++index];
+    else if (arg === "--kind") options.kind = args[++index];
+    else if (arg === "--depth") options.depth = Number(args[++index]);
+    else if (arg === "--format") options.format = args[++index];
+    else if (arg === "-h" || arg === "--help") return null;
+    else positional.push(arg);
+  }
+  if (positional.length > 1) throw new Error("code impact 只能接收一个 root 路径");
+  if (positional.length === 1) options.root = resolve(positional[0]);
+  ["repo", "file", "symbol", "kind"].forEach((field) => {
+    if (!options[field]) throw new Error(`code impact 必须指定 --${field} <value>`);
+  });
+  if (!Number.isInteger(options.depth) || options.depth < 1 || options.depth > 10) throw new Error("--depth 必须是 1 到 10 的整数");
+  if (!options.format || !["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
+  if (!existsSync(options.root)) throw new Error(`root 不存在：${options.root}`);
+  return options;
+}
+
+function gitnexusKind(kind) {
+  return kind.length > 0 ? `${kind[0].toUpperCase()}${kind.slice(1)}` : kind;
+}
+
+function codeImpact(root, options) {
+  const args = [
+    "impact",
+    "--repo", options.repo,
+    "--file", options.file,
+    "--kind", gitnexusKind(options.kind),
+    "--depth", String(options.depth),
+    options.symbol,
+  ];
+  const result = spawnSync("gitnexus", args, { cwd: root, encoding: "utf8" });
+  if (result.error?.code === "ENOENT") throw new Error("代码级影响查询需要 GitNexus CLI，但当前 PATH 中找不到 gitnexus");
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || `退出码 ${result.status}`).trim();
+    throw new Error(`GitNexus 代码级影响查询失败：${detail}`);
+  }
+  let gitnexusResult;
+  try {
+    gitnexusResult = JSON.parse(result.stdout ?? "");
+  } catch (cause) {
+    throw new Error(`GitNexus 代码级影响查询返回了无法解析的结果：${cause.message}`);
+  }
+  if (gitnexusResult?.error) {
+    throw new Error(`GitNexus 代码级影响查询失败：${String(gitnexusResult.error)}`);
+  }
+  return {
+    schema_version: 1,
+    query: {
+      repo: options.repo,
+      file: options.file,
+      symbol: options.symbol,
+      kind: options.kind,
+      depth: options.depth,
+    },
+    source: "gitnexus",
+    result: gitnexusResult,
+  };
+}
+
+function printCodeImpactText(report) {
+  const result = report.result;
+  console.log(`代码影响分析：${report.query.file} / ${report.query.symbol}（${report.query.kind}）`);
+  console.log(`GitNexus repo：${report.query.repo}，最大 ${report.query.depth} 跳`);
+  console.log(`风险：${result.risk ?? "未知"}；影响符号：${result.impactedCount ?? "未知"}`);
+  if (result.summary) {
+    console.log(`直接：${result.summary.direct ?? 0}；间接：${result.summary.indirect ?? 0}；流程：${result.summary.processes_affected ?? 0}；模块：${result.summary.modules_affected ?? 0}`);
+  }
+  const processes = (result.affected_processes ?? []).map((item) => item.name).join("、") || "无";
+  const modules = (result.affected_modules ?? []).map((item) => item.name).join("、") || "无";
+  console.log(`受影响流程：${processes}`);
+  console.log(`受影响模块：${modules}`);
+}
+
+function impact(root, options) {
+  const loaded = loadGraph(root);
+  const graph = normalizeGraph(loaded.graph, root);
+  if (graph.issues.length > 0) throw new Error(`图谱校验失败，无法分析：${graph.issues.join("；")}`);
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  if (!byId.has(options.from)) throw new Error(`未知图谱节点：${options.from}`);
+  const edges = new Map(graph.nodes.map((node) => [node.id, []]));
+  for (const relation of graph.relations) {
+    if (options.relationFilter && !options.relationFilter(relation)) continue;
+    if (FORWARD_RELATIONS.has(relation.type)) edges.get(relation.from)?.push({ relation, target: relation.to });
+    if (REVERSE_RELATIONS.has(relation.type)) edges.get(relation.to)?.push({ relation, target: relation.from });
+  }
+
+  const queue = [{ id: options.from, depth: 0, path: [] }];
+  const bestDepth = new Map([[options.from, 0]]);
+  const results = [];
+  while (queue.length) {
+    const current = queue.shift();
+    if (current.depth >= options.depth) continue;
+    for (const edge of edges.get(current.id) ?? []) {
+      if (options.nodeFilter && !options.nodeFilter(byId.get(edge.target), edge.target)) continue;
+      const nextDepth = current.depth + 1;
+      const nextPath = [...current.path, {
+        from: current.id,
+        type: edge.relation.type,
+        to: edge.target,
+        evidence: edge.relation.evidence,
+      }];
+      if (bestDepth.has(edge.target) && bestDepth.get(edge.target) <= nextDepth) continue;
+      bestDepth.set(edge.target, nextDepth);
+      queue.push({ id: edge.target, depth: nextDepth, path: nextPath });
+      results.push({ id: edge.target, depth: nextDepth, node: byId.get(edge.target), evidence: byId.get(edge.target).evidence, path: nextPath });
+    }
+  }
+
+  return {
+    schema_version: 1,
+    source: { id: options.from, node: byId.get(options.from) },
+    depth: options.depth,
+    direct: results.filter((item) => item.depth === 1),
+    indirect: results.filter((item) => item.depth > 1),
+  };
+}
+
+function isFunctionalImpactNode(item) {
+  if (!item?.node || !functionalNodeId(item.id)) return false;
+  return ["business", "function", "process", "external_workflow"].includes(item.node.type);
+}
+
+function functionalNodeId(id) {
+  return typeof id === "string" && !LEGACY_NON_FUNCTIONAL_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+
+function filterFunctionalImpact(result) {
+  return {
+    direct: result.direct.filter(isFunctionalImpactNode),
+    indirect: result.indirect.filter(isFunctionalImpactNode),
+  };
+}
+
+function planLayerDecision(request) {
+  const queriedLayers = ["functional"];
+  const upgradeReasons = {};
+  const architectureRequired = ["api_contract_change", "data_migration", "security_change"].includes(request.change_kind)
+    || (request.upgrade_signals ?? []).includes("external_boundary");
+  if (architectureRequired) {
+    queriedLayers.push("architecture");
+    upgradeReasons.architecture = request.change_kind === "behavior_change"
+      ? "upgrade_signal=external_boundary"
+      : `change_kind=${request.change_kind}`;
+  }
+  if (request.code_locator_requested === true) {
+    queriedLayers.push("code");
+    upgradeReasons.code = "code_locator_requested=true";
+  }
+  const unqueriedLayers = {};
+  if (!queriedLayers.includes("architecture")) unqueriedLayers.architecture = "未命中架构升级信号";
+  if (!queriedLayers.includes("code")) unqueriedLayers.code = "未要求具体代码定位";
+  return { queriedLayers, upgradeReasons, unqueriedLayers };
+}
+
+function architectureImpact(root, request) {
+  const loaded = loadArchitectureGraph(root);
+  const graph = normalizeGraph(loaded.graph, root, { layer: "architecture", externalIds: loaded.externalIds });
+  if (graph.issues.length > 0) throw new Error(`架构图谱校验失败，无法分析：${graph.issues.join("；")}`);
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+  const mappingRelations = graph.relations.filter((relation) => relation.type === "realized_by");
+  const seedRelations = mappingRelations.filter((relation) => relation.from === request.graph_scope);
+  if (seedRelations.length === 0) throw new Error(`功能节点没有可验证的架构映射：${request.graph_scope}`);
+
+  const selected = new Set(seedRelations.map((relation) => relation.to));
+  const selectedRelations = [...seedRelations];
+  if (request.change_kind === "api_contract_change") {
+    graph.relations
+      .filter((relation) => relation.type === "exposes" && selected.has(relation.from))
+      .forEach((relation) => {
+        selected.add(relation.to);
+        selectedRelations.push(relation);
+      });
+  }
+  if (["data_migration", "security_change"].includes(request.change_kind)) {
+    graph.relations
+      .filter((relation) => relation.type === "crosses" && (selected.has(relation.from) || selected.has(relation.to)))
+      .forEach((relation) => {
+        selected.add(relation.from);
+        selected.add(relation.to);
+        selectedRelations.push(relation);
+      });
+  }
+
+  return {
+    nodes: [...selected].sort().map((id) => ({
+      id,
+      node: byId.get(id),
+      evidence: byId.get(id)?.evidence ?? [],
+      paths: selectedRelations
+        .filter((relation) => relation.to === id || relation.from === id)
+        .map((relation) => ({
+          from: relation.from,
+          type: relation.type,
+          to: relation.to,
+          evidence: relation.evidence,
+        })),
+    })),
+  };
+}
+
+function uniqueEvidence(items) {
+  const seen = new Set();
+  return items.flatMap((item) => item?.evidence ?? [])
+    .filter((evidence) => evidence.kind === "test")
+    .filter((evidence) => {
+      const key = `${evidence.ref}#${evidence.locator}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+function planImpact(root, options) {
+  const { request, path: inputPath } = loadPlanImpactRequest(root, options.input);
+  const decision = planLayerDecision(request);
+  const loaded = loadGraph(root);
+  const graph = normalizeGraph(loaded.graph, root);
+  if (graph.issues.length > 0) throw new Error(`功能图谱校验失败，无法分析：${graph.issues.join("；")}`);
+  const sourceNode = graph.nodes.find((node) => node.id === request.graph_scope);
+  if (!sourceNode) throw new Error(`未知功能图谱节点：${request.graph_scope}`);
+  const legacyImpact = impact(root, {
+    from: request.graph_scope,
+    depth: 2,
+    nodeFilter: (node, id) => functionalNodeId(id) && ["business", "function", "process", "external_workflow"].includes(node?.type),
+    relationFilter: (relation) => relation.type !== "exposes"
+      && (relation.type !== "implements" || functionalNodeId(relation.to)),
+  });
+  const functionalImpact = filterFunctionalImpact(legacyImpact);
+  const testImpact = impact(root, {
+    from: request.graph_scope,
+    depth: 2,
+    nodeFilter: (node, id) => (functionalNodeId(id)
+      && ["business", "function", "process", "external_workflow"].includes(node?.type)) || id.startsWith("test."),
+    relationFilter: (relation) => relation.type !== "exposes"
+      && (relation.type !== "implements" || functionalNodeId(relation.to) || relation.to.startsWith("test.")),
+  });
+  const architecture = decision.queriedLayers.includes("architecture")
+    ? architectureImpact(root, request)
+    : null;
+
+  let code = null;
+  if (decision.queriedLayers.includes("code")) {
+    const candidate = codeCandidates(root, {
+      file: request.code_anchor.file,
+      symbol: request.code_anchor.symbol,
+      kind: request.code_anchor.kind,
+    });
+    if (candidate.resolution !== "unique_candidate") {
+      throw new Error(`代码定位未唯一确认：resolution=${candidate.resolution}；请使用 graph code candidates 获取候选并上升确认`);
+    }
+    code = candidate;
+  }
+
+  const testEvidence = uniqueEvidence([
+    ...testImpact.direct,
+    ...testImpact.indirect,
+    ...(architecture?.nodes ?? []),
+  ]);
+  const actions = ["必须评估", testEvidence.length > 0 ? "必须测试" : "建议检查"];
+  return {
+    schema_version: 1,
+    source: {
+      input: inputPath,
+      graph_scope: request.graph_scope,
+      change_kind: request.change_kind,
+      node: sourceNode,
+    },
+    queried_layers: decision.queriedLayers,
+    upgrade_reasons: decision.upgradeReasons,
+    unqueried_layers: decision.unqueriedLayers,
+    functional: functionalImpact,
+    architecture,
+    code,
+    actions,
+    tests: testEvidence.length > 0
+      ? { status: "available", evidence: testEvidence }
+      : { status: "unavailable", message: "无可用测试映射", evidence: [] },
+    writes: false,
+    analyze_triggered: false,
+  };
+}
+
+function printPlanImpactText(result) {
+  console.log(`计划前置影响分析：${result.source.graph_scope}（${result.source.change_kind}）`);
+  console.log(`查询层级：${result.queried_layers.join(" → ")}`);
+  console.log(`升级原因：${Object.entries(result.upgrade_reasons).map(([layer, reason]) => `${layer}: ${reason}`).join("；") || "无"}`);
+  console.log("功能影响：");
+  for (const item of [...result.functional.direct, ...result.functional.indirect]) {
+    console.log(`- ${item.id}：${item.node.name}`);
+  }
+  if (result.architecture) {
+    console.log("架构影响：");
+    for (const item of result.architecture.nodes) console.log(`- ${item.id}：${item.node.name}`);
+  }
+  if (result.code) console.log(`代码定位：${result.code.resolution}；${result.code.candidates[0].file}:${result.code.candidates[0].line}`);
+  console.log(`行动建议：${result.actions.join("、")}`);
+  console.log(`测试映射：${result.tests.status === "available" ? result.tests.evidence.map((item) => item.ref).join("、") : result.tests.message}`);
+  console.log(`未查询层级：${Object.entries(result.unqueried_layers).map(([layer, reason]) => `${layer}（${reason}）`).join("；") || "无"}`);
+}
+
+function printText(result) {
+  console.log(`影响分析：${result.source.id}（最大 ${result.depth} 跳）`);
+  const printGroup = (title, items) => {
+    console.log(`${title}：`);
+    if (items.length === 0) console.log("- 无");
+    for (const item of items) {
+      const path = item.path.map((edge) => `${edge.from} -[${edge.type}]-> ${edge.to}`).join("；");
+      const pathEvidence = item.path
+        .flatMap((edge) => edge.evidence ?? [])
+        .map((entry) => `${entry.ref}#${entry.locator}`)
+        .join("；");
+      console.log(`- ${item.id}（${item.node.type}）：${item.node.name}`);
+      console.log(`  路径：${path}`);
+      console.log(`  关系证据：${pathEvidence || "-"}`);
+      console.log(`  证据：${item.evidence.map((entry) => `${entry.ref}#${entry.locator}`).join("；")}`);
+    }
+  };
+  printGroup("直接影响", result.direct);
+  printGroup("间接影响", result.indirect);
+}
+
+function main(args) {
+  const command = args[0];
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    return command ? 0 : 1;
+  }
+  try {
+    if (command === "validate") {
+      const options = parseValidateArgs(args.slice(1));
+      if (options === null) {
+        usage();
+        return 0;
+      }
+      return validate(options.root, options.layer);
+    }
+    if (command === "impact") {
+      const options = parseImpactArgs(args.slice(1));
+      if (options === null) {
+        usage();
+        return 0;
+      }
+      const result = impact(options.root, options);
+      if (options.format === "json") console.log(JSON.stringify(result, null, 2));
+      else printText(result);
+      return 0;
+    }
+    if (command === "plan") {
+      if (args[1] !== "impact") return error(`plan 不支持子命令：${args[1] ?? "<missing>"}`);
+      const options = parsePlanImpactArgs(args.slice(2));
+      if (options === null) {
+        usage();
+        return 0;
+      }
+      const result = planImpact(options.root, options);
+      if (options.format === "json") console.log(JSON.stringify(result, null, 2));
+      else printPlanImpactText(result);
+      return 0;
+    }
+    if (command === "code") {
+      if (args[1] === "candidates") {
+        const options = parseCodeCandidatesArgs(args.slice(2));
+        if (options === null) {
+          usage();
+          return 0;
+        }
+        const result = codeCandidates(options.root, options);
+        if (options.format === "json") console.log(JSON.stringify(result, null, 2));
+        else printCodeCandidatesText(result);
+        return 0;
+      }
+      if (args[1] === "impact") {
+        const options = parseCodeImpactArgs(args.slice(2));
+        if (options === null) {
+          usage();
+          return 0;
+        }
+        const result = codeImpact(options.root, options);
+        if (options.format === "json") console.log(JSON.stringify(result, null, 2));
+        else printCodeImpactText(result);
+        return 0;
+      }
+      return error(`code 不支持子命令：${args[1] ?? "<missing>"}`);
+    }
+    return error(`不支持子命令：${command}`);
+  } catch (cause) {
+    return error(cause.message);
+  }
+}
+
+process.exitCode = main(process.argv.slice(2));

package/scripts/init_plan_governance.py

@@ -92,6 +92,7 @@ def agent_rules_body():
 - 验证方式、完成条件、失败策略和回滚或安全边界明确。
 - 没有未解决的当前阶段阻塞项，且 `PLAN_MAP.md` 已同步。
 - 最新独立准入复核明确为“通过”。
+- 机器识别的结构化章节标题固定为 `阶段路线图`、`当前阶段`、`阶段准入摘要`、`最新独立准入复核`、`独立复核记录`；不要写成 `阶段 1 准入摘要` 等带编号变体，阶段编号以 `PLAN_MAP.md` 的当前阶段为准。
 
 专项计划应保留追加式独立复核记录，并显式维护最新结论的日期、阶段、结论、证据和复核者。历史记录不得覆盖；`PLAN_MAP.md` 只链接最新有效结论。