spectra-cli 4.1.1 → 4.2.0

package/plugins/spec-driver/docs/spectra-mcp-integration.md

@@ -0,0 +1,165 @@
+# Spectra MCP 集成指引
+
+本文档说明如何将 **Spectra** 和 **Spec Driver** 两个 Claude Code plugin 协同部署，让 spec-driver 的 sub-agent 能够调用 spectra 的 MCP 工具（`impact` / `context` / `detect_changes`）。
+
+---
+
+## 一、为什么需要协同部署
+
+Spec Driver 的核心 sub-agent（`plan` / `implement` / `verify` / `spec-review` / `quality-review`）在工作时需要感知代码库的符号依赖关系。这些能力由 Spectra 的 MCP 工具提供：
+
+| Spectra MCP 工具 | 用途 |
+|-----------------|------|
+| `mcp__plugin_spectra_spectra__context` | 获取指定符号的 360° 上下文（定义 + 调用方 + 被调用方 + 相关 spec） |
+| `mcp__plugin_spectra_spectra__impact` | blast radius 分析 — 反向 BFS 找受影响的所有符号 |
+| `mcp__plugin_spectra_spectra__detect_changes` | git diff → changedSymbols → impact 链 |
+
+---
+
+## 二、为什么 namespace 是 `mcp__plugin_spectra_spectra__*`
+
+Claude Code plugin 系统会根据以下规则自动生成 MCP 工具的命名空间：
+
+```
+mcp__plugin_{plugin-name}_{mcp-server-name}__{tool-name}
+```
+
+对于 spectra plugin：
+- **plugin-name**: `spectra`（`plugin.json` 中的 `name` 字段）
+- **mcp-server-name**: `spectra`（`.mcp.json` 中的 server key）
+- **tool-name**: `context` / `impact` / `detect_changes`
+
+因此完整 namespace 为 `mcp__plugin_spectra_spectra__context` 等。
+
+> **长期 follow-up**: Anthropic 正在讨论 plugin `namespaceStrategy` RFC，未来可能允许插件声明简洁 namespace（如 `mcp__spectra__*`）。RFC 落地后可将 sub-agent frontmatter 改回简洁版本。
+
+---
+
+## 三、2 步开箱即用部署
+
+### Step 1: 安装两个 plugin
+
+```bash
+claude plugin install spectra
+claude plugin install spec-driver
+```
+
+或从本仓库本地安装：
+
+```bash
+claude plugin install ./plugins/spectra
+claude plugin install ./plugins/spec-driver
+```
+
+### Step 2: 验证安装
+
+在 Claude Code 中运行：
+
+```
+/spec-driver:spec-driver-feature 描述一个简单需求
+```
+
+如果 `plan` sub-agent 能够在分析时调用 `mcp__plugin_spectra_spectra__context`，则集成成功。
+
+无需任何额外配置——sub-agent 的 frontmatter 已预置正确 plugin namespace。
+
+---
+
+## 四、故障排查
+
+### 问题 1: `plugin:spectra:spectra:failed` 或 MCP server 启动失败
+
+**可能原因**：
+- spectra-cli 版本过旧（< 4.2.0），缺少 Feature 155 agent-context tools
+- volta / node 版本不兼容
+
+**排查步骤**：
+
+```bash
+# 检查当前安装版本
+spectra --version
+
+# 应为 4.2.0+，否则更新
+npm install -g spectra-cli@latest
+
+# 验证 agent-context-tools 已包含
+ls $(npm root -g)/spectra-cli/dist/mcp/agent-context-tools.js
+```
+
+### 问题 2: sub-agent 提示"工具 mcp__plugin_spectra_spectra__context 不可用"
+
+**可能原因**：
+1. spectra plugin 未安装 → 执行 Step 1 安装
+2. spectra MCP server 启动失败 → 查看 `claude plugin status spectra`
+3. 当前项目没有 spectra graph 缓存 → 先运行 `spectra run .` 生成 graph
+
+**快速验证**：
+
+```bash
+# 确认 spectra plugin 正常
+claude plugin status spectra
+
+# 手动生成 graph（首次使用需要）
+spectra run .
+```
+
+### 问题 3: fork 了 spectra plugin，namespace 不一致
+
+如果你 fork 了 spectra plugin 并改名（如 `my-spectra-fork`），sub-agent 需要使用不同的 namespace。
+
+详见 [customization.md](./customization.md)。
+
+---
+
+## 五、验证矩阵
+
+| 验证项 | 命令 | 预期结果 |
+|--------|------|----------|
+| spectra 版本 | `spectra --version` | `4.2.0` |
+| agent-context-tools 存在 | `ls $(npm root -g)/spectra-cli/dist/mcp/` | 含 `agent-context-tools.js` |
+| spectra plugin 状态 | `claude plugin status spectra` | `active` |
+| spec-driver sub-agent namespace | grep frontmatter | 含 `mcp__plugin_spectra_spectra__` |
+
+---
+
+## 七、Driver 偏好引导设计（F170d）
+
+### 为什么需要这层引导
+
+F170c 实测（host shell N=10×4 轮）发现：driver（Claude Sonnet 4.6）在「评估 symbol 改动影响」类任务上 **0/10 主动调用** spectra `impact`，而是默认 1 Read + 6 Grep。即使把 tool description 升级到 100-500 字 + 4 要素 + 显式 chained usage，主动调用率仍是 **0%**。
+
+**业务洞察**：tool description 只提供「理论可用性」（这个工具能做什么），不能改变 driver 的工具选择**偏好**。Grep 是 Anthropic 训练数据中 caller-analysis 的默认工具，cognitive overhead 更低。要改变偏好，必须在 **prompt level** 提供「任务匹配性」引导——明确告诉 driver「什么任务该用什么工具」。
+
+F170d 因此在两处注入引导：
+1. **5 个 sub-agent**（plan / implement / verify / spec-review / quality-review）的 prompt body 内嵌「工具优先使用规则」表（按各 agent frontmatter `tools` 过滤）。agent body 即 Claude Code 子代理的 system prompt，故引导随子代理上下文抵达 driver。
+2. **5 个主编排器 SKILL.md** 的「子代理调度时的工具优先级提示」块，要求编排器 dispatch 时在 `Task()` prompt 中显式带上工具优先级提示。
+
+### 单一事实源与一致性守护
+
+引导文案的 canonical source 是 [`templates/preference-rules.md`](../templates/preference-rules.md)（R1-R4 规则 + 关键原则，anchor 标记）。三处消费方（agent 文件 / SKILL 提示 / F170d harness 注入）都从它派生：
+
+- **生成**：`node plugins/spec-driver/scripts/sync-preference-rules.mjs --write` 按各 agent `tools` 过滤渲染并写入 `<!-- BEGIN/END preference-rules -->` 之间。
+- **守护**：`npm run repo:check` 的 `preference-rules:agent-block-sync` 检测漂移（同 `--check`），保证 5 个 agent 块永不与单一源脱节。
+
+### 度量诚实声明（guided vs spontaneous）
+
+F170d 的 SC-002 度量命名为 **guided active-call rate**：它测的是「引导送达 driver 后，driver 是否遵循引导改用 MCP」，**不等于** F170c 测的「spontaneous preference（内在偏好）」。0%（无引导）→ ≥50%（有引导）的对比意义是 **「prompt 层引导能驱动 driver 改用 MCP」**，不宣称「模型内在偏好被改变」。
+
+### fork 用户自定义（override 机制）
+
+fork 用户想调整引导文案（增删规则行、改语气 SHOULD↔MUST、换工具优先级）：
+
+1. 编辑 `plugins/spec-driver/templates/preference-rules.md` 的 `block-start`/`block-end` 之间内容（保持 anchor 契约 `<!-- preference-rules:R# tool=xxx -->`）。
+2. 跑 `node plugins/spec-driver/scripts/sync-preference-rules.mjs --write` 重新生成 5 个 agent 块（按各自 tools 自动过滤）。
+3. 跑 `npm run repo:check` 确认 `preference-rules:agent-block-sync` 通过。
+
+无需改任何脚本逻辑——template 是唯一需要编辑的文件。
+
+---
+
+## 八、相关资源
+
+- [Spectra MCP Server 源码](../../src/mcp/server.ts)
+- [fork 用户定制指引](./customization.md)
+- [Milestone M7 设计文档](../../docs/design/milestone-M7-spectra-mcp-productization.md)
+- [F170d spec](../../specs/170d-driver-preference-shaping/spec.md) · [preference-rules 单一源](../templates/preference-rules.md)

package/plugins/spec-driver/lib/preference-rules.mjs

@@ -0,0 +1,96 @@
+/**
+ * preference-rules — 「工具优先使用规则」渲染核心（plugin-owned，自包含，无 root 依赖）
+ *
+ * canonical 渲染逻辑：从 templates/preference-rules.md 的 canonical 块按 agent frontmatter
+ * tools 过滤规则行。被三处消费：
+ *   - plugins/spec-driver/scripts/sync-preference-rules.mjs（生成 agent 块）
+ *   - scripts/feature-170d-driver-preference.mjs（harness 注入，经 driver-eval-core 复用）
+ *   - tests（经 driver-eval-core re-export）
+ *
+ * 设计意图：plugin 必须自包含（发布后不依赖仓库 root scripts/），故渲染逻辑落在 plugin lib。
+ */
+
+export const NS = 'mcp__plugin_spectra_spectra__';
+export const BEGIN_MARKER = '<!-- BEGIN preference-rules (generated from templates/preference-rules.md; do not edit) -->';
+export const END_MARKER = '<!-- END preference-rules -->';
+
+const ROW_ANCHOR_RE = /<!--\s*preference-rules:(R\d)\s+tool=([a-z_]+)\s*-->/;
+const ROWS_END_RE = /<!--\s*\/preference-rules:rows\s*-->/;
+const SKIP_MARKER_RE = /<!--\s*preference-rules:(block-start|block-end|meta\b[^>]*)\s*-->/;
+const BLOCK_START_RE = /<!--\s*preference-rules:block-start\s*-->/;
+const BLOCK_END_RE = /<!--\s*preference-rules:block-end\s*-->/;
+
+/**
+ * 提取 canonical 块文本：若含 block-start/block-end marker 则取其间内容；
+ * 否则原样返回（兼容仅传 block 内容的调用，如单测合成 TPL）。
+ */
+export function extractCanonicalBlock(templateText) {
+  const lines = String(templateText ?? '').split('\n');
+  const start = lines.findIndex((l) => BLOCK_START_RE.test(l));
+  if (start < 0) return String(templateText ?? '');
+  let end = -1;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (BLOCK_END_RE.test(lines[i])) { end = i; break; }
+  }
+  // fail-loud（codex C3）：有 block-start 却无 block-end → template 损坏，禁止静默截断到 EOF
+  if (end < 0) {
+    throw new Error('[preference-rules] template 含 block-start 但缺 block-end，拒绝静默截断');
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+/** 从 fully-qualified agentTools 提取 toolKey 集合（impact/context/detect_changes）。 */
+export function toolKeysFromAgentTools(agentTools) {
+  const keys = new Set();
+  for (const t of agentTools || []) {
+    if (typeof t === 'string' && t.startsWith(NS)) keys.add(t.slice(NS.length));
+  }
+  return keys;
+}
+
+/** 解析 agent .md frontmatter 的 tools: 行，返回 fully-qualified spectra MCP 工具数组。 */
+export function parseFrontmatterTools(agentText) {
+  const m = String(agentText ?? '').match(/^tools:\s*\[(.*)\]/m);
+  if (!m) return [];
+  const re = new RegExp(`${NS}\\w+`, 'g');
+  return m[1].match(re) ?? [];
+}
+
+/**
+ * 纯函数：按 agentTools 过滤 canonical 块的规则行，渲染「工具优先使用规则」块。
+ * 入参可为完整 template 文本（含 block-start/block-end）或仅 block 内容；二者皆可。
+ * 输出不含任何 anchor / block 注释。
+ * @param {string} templateText
+ * @param {string[]} agentTools 形如 ['mcp__plugin_spectra_spectra__impact', ...]
+ * @returns {string}
+ */
+export function renderInjectionBlock(templateText, agentTools) {
+  const keys = toolKeysFromAgentTools(agentTools);
+  // 先抽取 canonical 块（丢弃 template 文件的人类文档头），再过滤规则行
+  const lines = extractCanonicalBlock(templateText).split('\n');
+  const out = [];
+  let inRows = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (SKIP_MARKER_RE.test(line)) continue;
+    const anchor = line.match(ROW_ANCHOR_RE);
+    if (anchor) {
+      inRows = true;
+      const tool = anchor[2];
+      const rowLine = lines[i + 1] ?? '';
+      if (keys.has(tool)) out.push(rowLine);
+      i++;
+      continue;
+    }
+    if (ROWS_END_RE.test(line)) { inRows = false; continue; }
+    if (inRows) continue;
+    out.push(line);
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}
+
+/** 将渲染块包裹 BEGIN/END marker（供 agent 文件嵌入）。 */
+export function wrapWithMarkers(renderedBlock) {
+  return `${BEGIN_MARKER}\n${renderedBlock.trimEnd()}\n${END_MARKER}`;
+}

package/plugins/spec-driver/scripts/postinstall.sh

@@ -14,7 +14,7 @@ BOLD='\033[1m'
 
 # Plugin 信息
 PLUGIN_NAME="Spec Driver"
-PLUGIN_VERSION="4.0.0"
+PLUGIN_VERSION="4.2.0"
 MIN_CLAUDE_VERSION="1.0.0"
 
 # 推算插件根目录

package/plugins/spec-driver/scripts/sync-preference-rules.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * sync-preference-rules — 从 templates/preference-rules.md 单一事实源，按各 agent frontmatter
+ * tools 过滤渲染「工具优先使用规则」块，写入 5 个 agent 文件的 BEGIN/END marker 之间。
+ *
+ * 用法：
+ *   node plugins/spec-driver/scripts/sync-preference-rules.mjs --write   # 生成/更新（默认）
+ *   node plugins/spec-driver/scripts/sync-preference-rules.mjs --check   # 漂移检测（CI/repo:check）
+ *
+ * 插入锚点（首次）：`## 角色` 段之后、下一个 `## ` 标题之前；无 `## 角色` 则首个 `## ` 前。
+ * 已有 marker：仅替换 marker 之间内容（锚点不移动）。
+ *
+ * 退出码：0 = 无漂移 / 写入完成；1 = --check 检测到漂移。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  renderInjectionBlock,
+  parseFrontmatterTools,
+  wrapWithMarkers,
+  BEGIN_MARKER,
+  END_MARKER,
+} from '../lib/preference-rules.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_DIR = path.resolve(__dirname, '..');
+const TEMPLATE_PATH = path.join(PLUGIN_DIR, 'templates/preference-rules.md');
+const AGENTS = ['plan', 'implement', 'verify', 'spec-review', 'quality-review'];
+
+/** 计算 agent 文件应有的内容（插入或替换 marker 块）。 */
+export function computeExpectedAgentContent(agentText, templateText) {
+  const tools = parseFrontmatterTools(agentText);
+  const rendered = renderInjectionBlock(templateText, tools);
+  const wrapped = wrapWithMarkers(rendered);
+
+  const beginIdx = agentText.indexOf(BEGIN_MARKER);
+  // 在 BEGIN 之后查找 END，避免匹配到文档引用里的字面 marker
+  const endIdx = beginIdx >= 0 ? agentText.indexOf(END_MARKER, beginIdx + BEGIN_MARKER.length) : -1;
+  if (beginIdx >= 0 && endIdx > beginIdx) {
+    // 替换现有 marker 区（含 marker 本身）
+    const before = agentText.slice(0, beginIdx);
+    const after = agentText.slice(endIdx + END_MARKER.length);
+    return before + wrapped + after;
+  }
+
+  // 首次插入：定位锚点
+  const lines = agentText.split('\n');
+  const roleIdx = lines.findIndex((l) => /^##\s+角色/.test(l));
+  let insertAt;
+  if (roleIdx >= 0) {
+    insertAt = lines.findIndex((l, i) => i > roleIdx && /^##\s/.test(l));
+    if (insertAt < 0) insertAt = lines.length; // 角色 是最后一段
+  } else {
+    insertAt = lines.findIndex((l) => /^##\s/.test(l));
+    if (insertAt < 0) insertAt = lines.length;
+  }
+  const head = lines.slice(0, insertAt).join('\n').replace(/\n+$/, '');
+  const tail = lines.slice(insertAt).join('\n').replace(/^\n+/, '');
+  return `${head}\n\n${wrapped}\n\n${tail}`;
+}
+
+function agentPath(name, pluginDir = PLUGIN_DIR) {
+  return path.join(pluginDir, 'agents', `${name}.md`);
+}
+
+/**
+ * 供 repo:check（repo-maintenance-core）复用的漂移校验：
+ * 返回 { checks, warnings, errors }，与 aggregateValidation 契约一致。
+ */
+export function validatePreferenceRules({ projectRoot } = {}) {
+  const root = projectRoot ? path.resolve(projectRoot) : path.resolve(PLUGIN_DIR, '../..');
+  const pluginDir = path.join(root, 'plugins/spec-driver');
+  const templatePath = path.join(pluginDir, 'templates/preference-rules.md');
+  const errors = [];
+  const drifted = [];
+
+  if (!fs.existsSync(templatePath)) {
+    return { checks: [{ id: 'agent-block-sync', title: 'preference-rules 单一源同步', status: 'fail', evidence: { reason: 'template 缺失' } }], warnings: [], errors: ['template 缺失: templates/preference-rules.md'] };
+  }
+  const templateText = fs.readFileSync(templatePath, 'utf-8');
+  for (const agent of AGENTS) {
+    const p = agentPath(agent, pluginDir);
+    if (!fs.existsSync(p)) { drifted.push(`${agent}(缺失)`); errors.push(`agent 文件缺失: ${agent}.md`); continue; }
+    const actual = fs.readFileSync(p, 'utf-8');
+    if (actual !== computeExpectedAgentContent(actual, templateText)) {
+      drifted.push(agent);
+      errors.push(`${agent}.md preference-rules 块与 template 漂移；运行 sync-preference-rules.mjs --write`);
+    }
+  }
+  const status = drifted.length > 0 ? 'fail' : 'pass';
+  return {
+    checks: [{ id: 'agent-block-sync', title: '5 agent preference-rules 块与单一源一致', status, evidence: { drifted } }],
+    warnings: [],
+    errors,
+  };
+}
+
+/** 计算 plugin/template/agent 路径（projectRoot 可选，默认 module-relative）。 */
+function resolvePaths(projectRoot) {
+  const root = projectRoot ? path.resolve(projectRoot) : path.resolve(PLUGIN_DIR, '../..');
+  const pluginDir = path.join(root, 'plugins/spec-driver');
+  return { pluginDir, templatePath: path.join(pluginDir, 'templates/preference-rules.md') };
+}
+
+/**
+ * 程序化写入（repo:sync 复用）：按 template 重新生成 5 agent 的 preference-rules 块。
+ * 返回 { written: string[] }。
+ */
+export function syncPreferenceRules({ projectRoot } = {}) {
+  const { pluginDir, templatePath } = resolvePaths(projectRoot);
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`[sync-preference-rules] template 不存在: ${templatePath}`);
+  }
+  const templateText = fs.readFileSync(templatePath, 'utf-8');
+  const written = [];
+  for (const agent of AGENTS) {
+    const p = agentPath(agent, pluginDir);
+    if (!fs.existsSync(p)) throw new Error(`[sync-preference-rules] agent 文件不存在: ${p}`);
+    const actual = fs.readFileSync(p, 'utf-8');
+    const expected = computeExpectedAgentContent(actual, templateText);
+    if (actual !== expected) { fs.writeFileSync(p, expected, 'utf-8'); written.push(agent); }
+  }
+  return { written };
+}
+
+function run(mode) {
+  if (mode === 'check') {
+    const result = validatePreferenceRules({});
+    if (result.errors.length > 0) {
+      result.errors.forEach((e) => console.error(`[sync-preference-rules] ${e}`));
+      console.error('  运行 `node plugins/spec-driver/scripts/sync-preference-rules.mjs --write` 重新同步');
+      process.exit(1);
+    }
+    console.log('[sync-preference-rules] 无漂移 ✅');
+    return;
+  }
+  const { written } = syncPreferenceRules({});
+  written.forEach((a) => console.log(`[sync-preference-rules] 已更新 ${a}.md`));
+  console.log(`[sync-preference-rules] 完成（更新 ${written.length} 个 agent 文件）`);
+}
+
+const isCliEntry = process.argv[1] != null
+  && path.resolve(process.argv[1]).endsWith('sync-preference-rules.mjs');
+if (isCliEntry) {
+  const mode = process.argv.includes('--check') ? 'check' : 'write';
+  run(mode);
+}

package/plugins/spec-driver/skills/spec-driver-feature/SKILL.md

@@ -122,6 +122,16 @@ done
 
 ---
 
+## 子代理调度时的工具优先级提示
+
+主编排器在 dispatch 子代理时，**显式在 `Task()` prompt 中包含**以下提示（理由见各 sub-agent frontmatter 的「工具优先使用规则」章节，单一事实源：`plugins/spec-driver/templates/preference-rules.md`）：
+
+> 提示：本任务可能涉及 caller analysis / impact 评估 / git diff 影响分析。
+> **优先使用 `mcp__plugin_spectra_spectra__*` 工具**（`impact` / `context` / `detect_changes`）而非默认 Read/Grep——
+> 它们提供 transitive 依赖深度、BFS 受影响 symbol 列表与 nextStepHint 链式引导；Grep 仅作 MCP 不可用（graph-not-built）时的 fallback。
+
+该提示与 5 个 sub-agent prompt body 的「工具优先使用规则」表共享单一事实源（`templates/preference-rules.md`），由 `scripts/sync-preference-rules.mjs` 守护一致性。
+
 ## 并行执行策略
 
 本编排流程使用以下并行组（通过 `orchestration.yaml` 定义）：

package/plugins/spec-driver/skills/spec-driver-fix/SKILL.md

@@ -139,6 +139,16 @@ Gate 行为表由 `orchestration.yaml` + `spec-driver.config.yaml` 联合决定
 
 ---
 
+## 子代理调度时的工具优先级提示
+
+主编排器在 dispatch 子代理时，**显式在 `Task()` prompt 中包含**以下提示（理由见各 sub-agent frontmatter 的「工具优先使用规则」章节，单一事实源：`plugins/spec-driver/templates/preference-rules.md`）：
+
+> 提示：本任务可能涉及 caller analysis / impact 评估 / git diff 影响分析。
+> **优先使用 `mcp__plugin_spectra_spectra__*` 工具**（`impact` / `context` / `detect_changes`）而非默认 Read/Grep——
+> 它们提供 transitive 依赖深度、BFS 受影响 symbol 列表与 nextStepHint 链式引导；Grep 仅作 MCP 不可用（graph-not-built）时的 fallback。
+
+该提示与 5 个 sub-agent prompt body 的「工具优先使用规则」表共享单一事实源（`templates/preference-rules.md`），由 `scripts/sync-preference-rules.mjs` 守护一致性。
+
 ## 并行执行策略
 
 本编排流程在以下阶段使用并行调度以缩短总耗时：

package/plugins/spec-driver/skills/spec-driver-implement/SKILL.md

@@ -241,6 +241,16 @@ implement:
 
 ---
 
+## 子代理调度时的工具优先级提示
+
+主编排器在 dispatch 子代理时，**显式在 `Task()` prompt 中包含**以下提示（理由见各 sub-agent frontmatter 的「工具优先使用规则」章节，单一事实源：`plugins/spec-driver/templates/preference-rules.md`）：
+
+> 提示：本任务可能涉及 caller analysis / impact 评估 / git diff 影响分析。
+> **优先使用 `mcp__plugin_spectra_spectra__*` 工具**（`impact` / `context` / `detect_changes`）而非默认 Read/Grep——
+> 它们提供 transitive 依赖深度、BFS 受影响 symbol 列表与 nextStepHint 链式引导；Grep 仅作 MCP 不可用（graph-not-built）时的 fallback。
+
+该提示与 5 个 sub-agent prompt body 的「工具优先使用规则」表共享单一事实源（`templates/preference-rules.md`），由 `scripts/sync-preference-rules.mjs` 守护一致性。
+
 ## 工作流定义
 
 ### 6 阶段聚焦实施流程

package/plugins/spec-driver/skills/spec-driver-refactor/SKILL.md

@@ -93,6 +93,16 @@ done
 
 ---
 
+## 子代理调度时的工具优先级提示
+
+主编排器在 dispatch 子代理时，**显式在 `Task()` prompt 中包含**以下提示（理由见各 sub-agent frontmatter 的「工具优先使用规则」章节，单一事实源：`plugins/spec-driver/templates/preference-rules.md`）：
+
+> 提示：本任务可能涉及 caller analysis / impact 评估 / git diff 影响分析。
+> **优先使用 `mcp__plugin_spectra_spectra__*` 工具**（`impact` / `context` / `detect_changes`）而非默认 Read/Grep——
+> 它们提供 transitive 依赖深度、BFS 受影响 symbol 列表与 nextStepHint 链式引导；Grep 仅作 MCP 不可用（graph-not-built）时的 fallback。
+
+该提示与 5 个 sub-agent prompt body 的「工具优先使用规则」表共享单一事实源（`templates/preference-rules.md`），由 `scripts/sync-preference-rules.mjs` 守护一致性。
+
 ## 工作流定义（5 阶段）
 
 ### Phase 1: 影响分析 [1/5]

package/plugins/spec-driver/skills/spec-driver-story/SKILL.md

@@ -211,6 +211,16 @@ prompt_source[verify] = "$PLUGIN_DIR/agents/verify.md"
 
 ---
 
+## 子代理调度时的工具优先级提示
+
+主编排器在 dispatch 子代理时，**显式在 `Task()` prompt 中包含**以下提示（理由见各 sub-agent frontmatter 的「工具优先使用规则」章节，单一事实源：`plugins/spec-driver/templates/preference-rules.md`）：
+
+> 提示：本任务可能涉及 caller analysis / impact 评估 / git diff 影响分析。
+> **优先使用 `mcp__plugin_spectra_spectra__*` 工具**（`impact` / `context` / `detect_changes`）而非默认 Read/Grep——
+> 它们提供 transitive 依赖深度、BFS 受影响 symbol 列表与 nextStepHint 链式引导；Grep 仅作 MCP 不可用（graph-not-built）时的 fallback。
+
+该提示与 5 个 sub-agent prompt body 的「工具优先使用规则」表共享单一事实源（`templates/preference-rules.md`），由 `scripts/sync-preference-rules.mjs` 守护一致性。
+
 ## 并行执行策略
 
 本编排流程在以下阶段使用并行调度以缩短总耗时：

package/plugins/spec-driver/templates/preference-rules.md

@@ -0,0 +1,39 @@
+# Preference Rules — 工具优先使用规则（单一事实源，M7 F170d）
+
+> **本文件是 spec-driver「工具优先使用规则」引导文案的 canonical source。**
+>
+> 消费方（三处，禁止各自手写漂移）：
+> 1. **5 个 sub-agent**（`agents/{plan,implement,verify,spec-review,quality-review}.md`）——由 `scripts/sync-preference-rules.mjs --write` 按各 agent frontmatter `tools` **过滤渲染**后嵌入 `<!-- BEGIN preference-rules -->` / `<!-- END preference-rules -->` 之间。
+> 2. **5 个主编排器 SKILL.md**——「子代理调度时的工具优先级提示」块引用本文件路径。
+> 3. **F170d harness**（`scripts/feature-170d-driver-preference.mjs`）——`--append-system-prompt` 注入时读取本块并按目标 agent 的 tools 过滤。
+>
+> **修改流程**：改下方 `block-start`/`block-end` 之间的内容 → 跑 `node plugins/spec-driver/scripts/sync-preference-rules.mjs --write` → 跑 `npm run repo:check`（含 `preference-rules:agent-block-sync` 漂移检测）。
+>
+> **anchor 契约**：`<!-- preference-rules:<ruleId> tool=<toolKey> -->`，`ruleId ∈ {R1..R4}`（身份），`toolKey ∈ {impact,context,detect_changes}`（按 agent tools 过滤的键）。R1、R2 同为 `tool=impact`。
+>
+> **背景**：F170c SC-002 实测 driver（Claude Sonnet 4.6）在 caller-analysis 任务上 0/10 主动调用 spectra MCP；仅靠 tool description 升级无法改变。本引导在 prompt level 提供「任务→工具」匹配性引导。详见 `docs/spectra-mcp-integration.md` §七。
+
+<!-- preference-rules:block-start -->
+## 工具优先使用规则（M7 F170d）
+
+当面对以下类任务时，**优先调用 spectra MCP 工具而非 Read/Grep**：
+
+| 任务关键词 | 优先工具 | 理由 |
+|----------|---------|------|
+<!-- preference-rules:R1 tool=impact -->
+| "找 caller" / "谁调用了 X" / "caller analysis" | `mcp__plugin_spectra_spectra__impact` (direction=upstream) | 提供 transitive caller chain + confidence score，Grep 仅文本匹配无依赖深度 |
+<!-- preference-rules:R2 tool=impact -->
+| "评估改动影响" / "blast radius" / "影响面" | `mcp__plugin_spectra_spectra__impact` | 提供 BFS 受影响 symbol 列表 + summary |
+<!-- preference-rules:R3 tool=context -->
+| "找 callee" / "X 调用了什么" / "依赖什么" | `mcp__plugin_spectra_spectra__context` | 提供 symbol 360° 上下文 (definition + callers + callees + imports) |
+<!-- preference-rules:R4 tool=detect_changes -->
+| "git diff 影响" / "改了哪些 symbol" / "PR review 范围" | `mcp__plugin_spectra_spectra__detect_changes` | 从 diff 派生 changedSymbols + impact 链 |
+<!-- /preference-rules:rows -->
+
+### 关键原则
+
+- **Grep 仍是 fallback**：当 Spectra MCP 工具返回 graph-not-built / 不可用时退回 Grep
+- **不能省略调用**：不要因为"觉得 Grep 够用"跳过 MCP — 即使任务可以用 Grep 解决，MCP 提供的 transitive 数据更可信
+- **chained 使用**：detect_changes → impact → context 是典型链路，按 nextStepHint 引导继续调用
+- **不要 N+1**：单次 impact 调用即可拿到 BFS 全 list，不需要多次 Grep 累计
+<!-- preference-rules:block-end -->

package/plugins/spectra/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spectra",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "把任意代码库变成可查询、可视化、可按场景伸缩的代码阅读平台。AST + LLM 混合 pipeline 生成分层 Spec、知识图谱、技术债清单、自然语言问答与交互式 graph.html",
   "author": {
     "name": "Connor Lu",

package/plugins/spectra/README.md

@@ -1,6 +1,6 @@
 # Spectra — Claude Code Plugin
 
-> 当前发布版本: v4.1.1
+> 当前发布版本: v4.2.0
 
 通过 AST 静态分析 + LLM 混合流水线，将遗留源代码逆向工程为结构化 Spec 文档。
 
@@ -123,6 +123,53 @@ Plugin 安装后，`.mcp.json` 自动配置 MCP server：
 /spectra-diff specs/auth.spec.md src/auth/
 ```
 
+## Spectra Index — UnifiedGraph 索引（Feature 156）
+
+`spectra index` 把整个项目索引为 `.spectra/unified-graph.json` snapshot，
+供下游 panoramic / spectra batch / IDE 工具消费同一份图。
+
+### 三种模式
+
+```bash
+# 1. 全量索引（首次使用 / corruption 自愈）
+spectra index
+
+# 2. 一次性增量更新（基于 git diff + caller expansion）
+spectra index --incremental
+
+# 3. 持续监听模式（chokidar + 批量 incremental，进程不退出，Ctrl+C 退出）
+spectra index --watch
+```
+
+### post-commit hook 自动触发（可选，FR-15）
+
+每次 `git commit` 完成后自动跑一次 `spectra index --incremental`，
+保持 `.spectra/unified-graph.json` 与代码库同步。**不会** 阻塞 commit 流程
+（脚本后台异步触发）。
+
+```bash
+# 手动安装：拷贝脚本到 .git/hooks/ 并赋可执行权限
+cp plugins/spectra/hooks/post-commit.sh .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+```
+
+行为说明（FR-16）：
+- 仅在仓库根存在 `.spectra/` 时触发；未启用用户不受影响
+- 后台异步调用，输出到 `.spectra/index-hook.log`（已被 `.gitignore` 涵盖）
+- 任何失败不影响 commit 退出码（hook 始终 exit 0）
+
+不通过 npm postinstall / install --git-hook 子命令自动安装（保持非破坏性）。
+
+### 验证
+
+`scripts/verify-feature-156.mjs` 提供端到端验证：跑 full → 改动 1 个文件 →
+跑 incremental → canonical sort 后对比 `depends-on / calls / cross-module` 三类边
+diff = 0（AC-3a / AC-3b）。
+
+```bash
+node scripts/verify-feature-156.mjs --project-root <dir>
+```
+
 ## 许可证
 
 MIT

package/plugins/spectra/hooks/post-commit.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Feature 156 — Spectra incremental index 自动触发（post-commit hook）
+#
+# 用户手动安装：
+#   cp plugins/spectra/hooks/post-commit.sh .git/hooks/post-commit
+#   chmod +x .git/hooks/post-commit
+#
+# 行为：
+#   1. 仅在仓库根目录已存在 .spectra/ 时触发（用户已显式跑过一次 spectra index）
+#   2. 后台异步调用 spectra index --incremental，避免阻塞 commit 流程
+#   3. 输出重定向到 .spectra/index-hook.log（已被 .gitignore 涵盖）
+#   4. 任何失败都不会回退到 commit 失败（exit 0 总是返回）
+#
+# 设计决策（clarify Q4）：
+#   - 不新增 spectra install --git-hook 子命令，仅提供脚本文件 + README 安装步骤
+#   - 不通过 npm postinstall 自动注入，保持非破坏性（FR-16）
+
+set -euo pipefail
+
+# 取仓库根目录（如果不在 git 仓库内则静默退出）
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+# .spectra/ 不存在 → 用户尚未启用 spectra index，跳过（FR-16）
+if [ ! -d "$REPO_ROOT/.spectra" ]; then
+  exit 0
+fi
+
+# 后台异步触发 incremental，使用 ORIG_HEAD HEAD（post-commit 上下文标准 ref）
+# 输出 redirect 到 .spectra/index-hook.log，避免污染 git commit terminal
+(
+  cd "$REPO_ROOT"
+  npx spectra index --incremental --git-range "ORIG_HEAD HEAD" \
+    >> .spectra/index-hook.log 2>&1
+) &
+
+# 立即 exit 0；不等待后台进程，不阻塞 commit
+exit 0