spectra-cli 4.1.1 → 4.3.0

package/plugins/spec-driver/docs/customization.md

@@ -0,0 +1,134 @@
+# Spec Driver 定制指引（Fork 用户）
+
+本文档针对 **fork 了 spectra plugin 并修改 plugin name** 的用户，说明如何调整 spec-driver 的 sub-agent 配置以匹配自定义 namespace。
+
+---
+
+## 背景
+
+Spec Driver 的 5 个 sub-agent（`plan` / `implement` / `verify` / `spec-review` / `quality-review`）在 frontmatter 中声明了访问 spectra MCP 工具的 namespace：
+
+```yaml
+tools: [..., mcp__plugin_spectra_spectra__context, mcp__plugin_spectra_spectra__impact]
+```
+
+这个 namespace 由 Claude Code plugin 系统根据 **plugin name** 自动生成：
+
+```
+mcp__plugin_{your-plugin-name}_spectra__{tool-name}
+```
+
+如果你将 spectra fork 并改名，需要批量更新这些 namespace。
+
+---
+
+## 一键替换指引
+
+### 方法 1: sed（macOS / Linux）
+
+假设你将 spectra plugin 改名为 `my-spectra-fork`：
+
+```bash
+# 预览变更（dry-run）
+grep -rn "mcp__plugin_spectra_spectra__" plugins/spec-driver/agents/
+
+# 执行替换（macOS）
+find plugins/spec-driver/agents -name "*.md" -exec sed -i '' \
+  's/mcp__plugin_spectra_spectra__/mcp__plugin_my-spectra-fork_spectra__/g' {} \;
+
+# 执行替换（Linux）
+find plugins/spec-driver/agents -name "*.md" -exec sed -i \
+  's/mcp__plugin_spectra_spectra__/mcp__plugin_my-spectra-fork_spectra__/g' {} \;
+
+# 验证替换结果
+grep -rn "mcp__plugin_" plugins/spec-driver/agents/
+```
+
+### 方法 2: awk
+
+```bash
+for f in plugins/spec-driver/agents/plan.md \
+         plugins/spec-driver/agents/implement.md \
+         plugins/spec-driver/agents/verify.md \
+         plugins/spec-driver/agents/spec-review.md \
+         plugins/spec-driver/agents/quality-review.md; do
+  awk '{gsub(/mcp__plugin_spectra_spectra__/, "mcp__plugin_my-spectra-fork_spectra__"); print}' \
+    "$f" > "$f.tmp" && mv "$f.tmp" "$f"
+done
+```
+
+### 方法 3: 使用脚本（推荐，可重复运行）
+
+创建 `scripts/update-spectra-namespace.sh`：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+OLD_NAMESPACE="${1:-mcp__plugin_spectra_spectra__}"
+NEW_NAMESPACE="${2:?需要提供新 namespace，例如: mcp__plugin_my-spectra-fork_spectra__}"
+
+echo "替换 namespace: $OLD_NAMESPACE → $NEW_NAMESPACE"
+
+find plugins/spec-driver/agents -name "*.md" | while read -r f; do
+  if grep -q "$OLD_NAMESPACE" "$f"; then
+    sed -i '' "s|${OLD_NAMESPACE}|${NEW_NAMESPACE}|g" "$f"
+    echo "  已更新: $f"
+  fi
+done
+
+echo "完成。验证结果："
+grep -rn "mcp__plugin_" plugins/spec-driver/agents/ | head -20
+```
+
+运行：
+
+```bash
+chmod +x scripts/update-spectra-namespace.sh
+bash scripts/update-spectra-namespace.sh \
+  "mcp__plugin_spectra_spectra__" \
+  "mcp__plugin_my-spectra-fork_spectra__"
+```
+
+---
+
+## 受影响的文件清单
+
+| 文件 | 需替换的工具 |
+|------|------------|
+| `plugins/spec-driver/agents/plan.md` | `context`, `impact` |
+| `plugins/spec-driver/agents/implement.md` | `context`, `impact` |
+| `plugins/spec-driver/agents/verify.md` | `detect_changes`, `impact` |
+| `plugins/spec-driver/agents/spec-review.md` | `impact`, `context` |
+| `plugins/spec-driver/agents/quality-review.md` | `impact`, `context` |
+
+---
+
+## 验证替换正确性
+
+```bash
+# 1. 不应有旧 namespace 残留
+grep -rn "mcp__plugin_spectra_spectra__" plugins/spec-driver/agents/ && echo "ERROR: 旧 namespace 残留" || echo "✅ 旧 namespace 已清除"
+
+# 2. 新 namespace 应存在于所有 5 个文件
+grep -rn "mcp__plugin_my-spectra-fork_spectra__" plugins/spec-driver/agents/ | wc -l
+# 预期: 至少 8 行（5 个文件共 8 个工具声明）
+
+# 3. 验证 MCP server 名称不变（server-name 仍是 spectra）
+cat plugins/spectra/.mcp.json 2>/dev/null | grep -i "spectra" || cat plugins/my-spectra-fork/.mcp.json | grep -i "spectra"
+```
+
+---
+
+## 注意事项
+
+- **替换的是 plugin-name 部分**，不是 server-name（`spectra`）。server-name 由 `.mcp.json` 的 server key 决定，若你的 fork 保持 server key 为 `spectra`，则 namespace 中间段仍是 `_spectra__`。
+- 如果同时修改了 server key，需调整替换命令中的 `_spectra__` 部分为你的新 server key。
+- 替换后运行 `npm run repo:check` 确认仓库同步状态正常。
+
+---
+
+## 相关文档
+
+- [Spectra MCP 集成指引](./spectra-mcp-integration.md) — namespace 规则详细说明
+- [Milestone M7 设计文档](../../docs/design/milestone-M7-spectra-mcp-productization.md)

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/hooks/hooks.json

@@ -42,6 +42,15 @@
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop-task-check.sh"
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop-fix-compliance-check.sh"
+          }
+        ]
       }
     ],
     "WorktreeCreate": [

package/plugins/spec-driver/hooks/stop-fix-compliance-check.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Stop Hook: fix 模式流程依从性判定（Feature 208，阻断型）
+#
+# 薄壳职责（research.md D3）：读 stdin payload → 转发给 Node CLI → 按 CLI 退出码原样转发 0/2，
+# 任何非 0/2 的异常退出码一律兜底为 0（放行）。自身无判定逻辑，构成 FR-013 fail-open 的第二道保险
+# （即便 Node 判定器抛出未捕获异常，本层仍兜底放行，不把崩溃泄漏为 Claude Code 侧未定义阻断）。
+
+set -euo pipefail
+
+# 定位插件根：优先 CLAUDE_PLUGIN_ROOT，缺省时按脚本自身相对路径推导（hooks/ 的上一级）
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [ -z "$PLUGIN_ROOT" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+fi
+
+CLI="${FIX_COMPLIANCE_CLI:-$PLUGIN_ROOT/scripts/fix-compliance-judge.mjs}"
+
+# node 不可用 → 放行（无法判定不阻断，FR-013）
+if ! command -v node >/dev/null 2>&1; then
+  exit 0
+fi
+
+# stdin 转发给 CLI；临时禁用 errexit 以便捕获非零退出码做兜底判定
+STDIN_PAYLOAD="$(cat)"
+
+set +e
+printf '%s' "$STDIN_PAYLOAD" | node "$CLI" --mode hook --project-root "$(pwd)"
+CLI_EXIT=$?
+set -e
+
+# 退出码转发：0/2 原样转发，其余（崩溃/信号）兜底放行
+if [ "$CLI_EXIT" -eq 2 ]; then
+  exit 2
+fi
+exit 0

package/plugins/spec-driver/lib/delegation-contract.mjs

@@ -0,0 +1,84 @@
+/**
+ * delegation-contract — 「编排器必须委派子代理」硬约束块渲染核心（plugin-owned，自包含，无 root 依赖）
+ *
+ * canonical 源：templates/delegation-contract.md 的 block-start/block-end 之间内容。
+ * 与 preference-rules 不同：delegation-contract 是**整块原样注入**（无 per-row tool 过滤），
+ * 被注入到 5 个主编排器 SKILL.md 正文（fix/story/feature/implement/resume）。
+ *
+ * 被两处消费：
+ *   - plugins/spec-driver/scripts/sync-delegation-contract.mjs（按各 SKILL 锚点注入约束块）
+ *   - tests（纯函数级断言）
+ *
+ * 设计意图：plugin 必须自包含（发布后不依赖仓库 root scripts/），故渲染逻辑落在 plugin lib。
+ */
+
+export const BEGIN_MARKER = '<!-- BEGIN delegation-contract (generated from templates/delegation-contract.md; do not edit) -->';
+export const END_MARKER = '<!-- END delegation-contract -->';
+
+const BLOCK_START_RE = /<!--\s*delegation-contract:block-start\s*-->/;
+const BLOCK_END_RE = /<!--\s*delegation-contract:block-end\s*-->/;
+
+/**
+ * 提取 canonical 块文本：取 block-start/block-end marker 之间的内容。
+ * 若无 block-start → 原样返回（兼容单测直接传 block 内容的场景）。
+ * 有 block-start 却无 block-end → fail-loud（对齐 preference-rules，禁止静默截断到 EOF）。
+ */
+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; }
+  }
+  if (end < 0) {
+    throw new Error('[delegation-contract] template 含 block-start 但缺 block-end，拒绝静默截断');
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+/** 将 canonical 块包裹 BEGIN/END marker（供 SKILL 文件嵌入）。 */
+export function wrapWithMarkers(block) {
+  return `${BEGIN_MARKER}\n${String(block).trimEnd()}\n${END_MARKER}`;
+}
+
+/**
+ * 计算 SKILL 文件应有的内容（注入或替换约束块）。
+ * - 若已含 BEGIN..END → 仅替换 marker 之间内容（锚点不移动，幂等）。
+ * - 否则 → 在 anchorHeading 行**之后**（紧随该标题行的下一行）插入 wrapped 块，前后各留一空行。
+ * - anchorHeading 在 skillText 中未找到 → fail-loud（不静默跳过）。
+ *
+ * @param {string} skillText SKILL.md 全文
+ * @param {string} templateText delegation-contract.md 全文（或仅 block 内容）
+ * @param {string} anchorHeading 形如 '## 工作流定义'，必须与 SKILL 中某行完整匹配
+ * @returns {string}
+ */
+export function computeExpectedSkillContent(skillText, templateText, anchorHeading) {
+  const block = extractCanonicalBlock(templateText);
+  const wrapped = wrapWithMarkers(block);
+
+  const beginIdx = skillText.indexOf(BEGIN_MARKER);
+  // 在 BEGIN 之后查找 END，避免匹配到文档引用里的字面 marker
+  const endIdx = beginIdx >= 0 ? skillText.indexOf(END_MARKER, beginIdx + BEGIN_MARKER.length) : -1;
+  if (beginIdx >= 0 && endIdx > beginIdx) {
+    const before = skillText.slice(0, beginIdx);
+    const after = skillText.slice(endIdx + END_MARKER.length);
+    return before + wrapped + after;
+  }
+  // fail-loud（codex CRITICAL）：孤儿 BEGIN（有 BEGIN 无 END，如手动截断/上次写入中断）若放行
+  // 会落入首次插入路径 → 文件出现双 BEGIN 单 END，且此后 --check 稳定假绿，守护永远看不见
+  if (beginIdx >= 0) {
+    throw new Error('[delegation-contract] SKILL 含 BEGIN marker 但缺 END marker（畸形块），拒绝重复注入；请手动修复或删除残块后重跑 sync');
+  }
+
+  // 首次插入：定位锚点标题行
+  const lines = skillText.split('\n');
+  const anchorIdx = lines.findIndex((l) => l === anchorHeading);
+  if (anchorIdx < 0) {
+    throw new Error(`[delegation-contract] 锚点未找到: ${JSON.stringify(anchorHeading)}`);
+  }
+  // 在锚点标题行之后插入，前后各留一空行
+  const head = lines.slice(0, anchorIdx + 1).join('\n');
+  const tail = lines.slice(anchorIdx + 1).join('\n').replace(/^\n+/, '');
+  return `${head}\n\n${wrapped}\n\n${tail}`;
+}

package/plugins/spec-driver/lib/orchestration-resolver.mjs

@@ -23,6 +23,7 @@ import {
   orchestrationOverridesSchema,
   orchestrationMergedSchema,
   formatZodIssue,
+  zodAvailable,
 } from '../contracts/orchestration-schema.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -208,6 +209,54 @@ export async function resolveOrchestrationConfig({ projectRoot, _loadBase, _load
     };
   }
 
+  // ── zod 缺失短路（步骤 1 成功之后、步骤 2 safeParse 之前）────────
+  // 缺 zod 时全部 schema 为 null，无法 safeParse；此处 best-effort 信任 base、
+  // 跳过项目级 overrides（用户输入无法校验），返回结构化结果而非硬崩。
+  if (!zodAvailable) {
+    // 纯对象检查（复用既有 isPlainObject 守卫模式）
+    const isBaseRawPlainObject =
+      rawBase !== null &&
+      rawBase !== undefined &&
+      Object.prototype.toString.call(rawBase) === '[object Object]';
+
+    if (!isBaseRawPlainObject) {
+      // base 解析结果不是纯对象 → 视为 base 损坏，退 generateFallbackConfig
+      diagnostics.push(createDiagnostic(
+        'error',
+        'orchestration.base-invalid',
+        '[orchestration] base 配置不是合法对象（zod 缺失 + base 非纯对象）',
+      ));
+      const fallbackConfig = generateFallbackConfig();
+      return {
+        mergedConfig: fallbackConfig,
+        baseConfig: fallbackConfig,
+        fieldSources: {},
+        diagnostics,
+        isFallback: true,
+        isBaseInvalid: true,
+      };
+    }
+
+    // base 是纯对象 → best-effort 信任，跳过 overrides（无法校验用户输入）
+    diagnostics.push(createDiagnostic(
+      'warning',
+      'orchestration.zod-unavailable',
+      '[orchestration] 未能加载 zod，已跳过 orchestration schema 校验并 best-effort 信任 base 配置；' +
+      '项目级 orchestration-overrides 在缺 zod 时不被应用。' +
+      '如需完整校验请在已安装依赖的目录运行（npm i）或从仓内源路径运行 spec-driver 脚本',
+    ));
+    const baseFieldSources = buildBaseOnlyFieldSources(rawBase);
+    return {
+      mergedConfig: rawBase,
+      baseConfig: rawBase,
+      fieldSources: baseFieldSources,
+      diagnostics,
+      isFallback: true,
+      isBaseInvalid: false,
+    };
+  }
+  // ── zod 缺失短路结束 ─────────────────────────────────────────────
+
   // ── 步骤 2：base Zod 校验 ──────────────────────────────────
   const baseParseResult = orchestrationBaseSchema.safeParse(rawBase);
   if (!baseParseResult.success) {

package/plugins/spec-driver/lib/orchestrator.mjs

@@ -10,7 +10,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { parseYamlDocument } from '../scripts/lib/simple-yaml.mjs';
 import { generateFallbackConfig } from './orchestrator-fallback.mjs';
-import { orchestrationBaseSchema, formatZodIssue } from '../contracts/orchestration-schema.mjs';
+import { orchestrationBaseSchema, formatZodIssue, zodAvailable } from '../contracts/orchestration-schema.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -58,6 +58,34 @@ export class Orchestrator {
       const content = fs.readFileSync(configPath, 'utf-8');
       const parsed = parseYamlDocument(content);
 
+      // ── zod 缺失守卫（YAML 解析成功之后、safeParse 之前）────────────
+      // 缺 zod 时 orchestrationBaseSchema 为 null，调用 .safeParse 会抛 TypeError 被外层
+      // catch 误判为加载失败并丢弃真实配置。显式守卫在此 best-effort 信任已解析 YAML。
+      if (!zodAvailable) {
+        const isParsedPlainObject =
+          parsed !== null &&
+          parsed !== undefined &&
+          Object.prototype.toString.call(parsed) === '[object Object]';
+
+        if (isParsedPlainObject) {
+          // parsed 是纯对象 → best-effort 信任已解析的 YAML
+          this.logger.warn(
+            '[ORCHESTRATOR] zod 未加载，已跳过 orchestration schema 校验并 best-effort 信任已解析配置',
+          );
+          this.config = parsed;
+          this.isFallback = false;   // 真实配置，非最小桩
+        } else {
+          // parsed 不是纯对象（YAML 解析为 null/数组/标量等）→ 退 generateFallbackConfig
+          this.logger.warn(
+            '[ORCHESTRATOR] zod 未加载且 YAML 解析结果非纯对象，使用 fallback 配置',
+          );
+          this.config = generateFallbackConfig();
+          this.isFallback = true;
+        }
+        return;   // 跳过 safeParse，退出 loadAndValidateConfig
+      }
+      // ── zod 缺失守卫结束 ─────────────────────────────────────────────
+
       // 使用 orchestrationBaseSchema.safeParse 替代手写校验（CL-016，T-011）
       const zodResult = orchestrationBaseSchema.safeParse(parsed);
       if (!zodResult.success) {

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}`;
+}