spectra-cli 4.1.1 → 4.3.0

package/plugins/spec-driver/scripts/generate-adoption-insights.mjs

@@ -18,6 +18,14 @@ import { readJsonArtifact, writeJsonArtifact, writeMarkdownArtifact } from './li
 const SCHEMA_VERSION = 1;
 const PRODUCT_ID = 'spec-driver';
 
+/**
+ * 已知的非 summary 事件类型白名单（Feature 208，data-model.md §9）。
+ * 这些事件与 workflow-run-summary 共存于同一 .specify/runs/*.jsonl，但不参与 adoption 统计。
+ * why 需要白名单：normalizeRunEvent 对非 summary 行返回 null → 原逻辑会计入 invalidLineCount 并
+ * 产生"忽略无效 run event"warning，污染 adoption 报告 invalid 统计。白名单命中者静默 skip。
+ */
+const KNOWN_NON_SUMMARY_EVENT_TYPES = new Set(['fix-compliance-verdict']);
+
 function parseArgs(argv) {
   const args = {
     projectRoot: process.cwd(),
@@ -126,6 +134,10 @@ function readRunLogs(projectRoot) {
       const line = lines[index];
       try {
         const parsed = JSON.parse(line);
+        // 已知非 summary 事件类型（如 fix-compliance-verdict）静默 skip：不计 invalid、不产生 warning
+        if (isObject(parsed) && KNOWN_NON_SUMMARY_EVENT_TYPES.has(parsed.eventType)) {
+          continue;
+        }
         const normalized = normalizeRunEvent(parsed);
         if (normalized) {
           events.push(normalized);
@@ -181,12 +193,47 @@ function normalizeRunEvent(entry) {
   };
 }
 
+// 同一 (workflowId, runId) 可能出现多条终态事件：Feature 211 的 compliant-reset 语义下，
+// 同一 session 后续再次耗尽额度降级会重写 workflow-run-summary 终态事件（每个"阻断周期"一条）。
+// JSONL 是 append-only 审计日志，原始事件全部保留；此处仅在统计聚合前按 (workflowId, runId)
+// 去重，取时间最晚的一条作为该 run 的最终结果，避免同一 run 被重复计入 totalRuns 等指标。
+// runId 缺失的事件在 normalizeRunEvent 阶段已被判为无效（不进入本函数），故无需在此特殊处理。
+function dedupeRunEvents(events) {
+  const latestByRun = new Map();
+  const order = [];
+  for (const event of events) {
+    const key = `${event.workflowId}\u0000${event.runId}`;
+    const existing = latestByRun.get(key);
+    if (!existing) {
+      latestByRun.set(key, event);
+      order.push(key);
+      continue;
+    }
+    // 时间可比时取更晚者；时间相等或缺失时取文件内后出现者（append-only 天然有序）
+    const newMs = eventRecencyMs(event);
+    const existingMs = eventRecencyMs(existing);
+    if (newMs === null || existingMs === null || newMs >= existingMs) {
+      latestByRun.set(key, event);
+    }
+  }
+  return order.map((key) => latestByRun.get(key));
+}
+
+// 终态事件的"新近度"：取 recordedAt / finishedAt 中可解析的最晚时间戳（ms），均缺失则返回 null
+function eventRecencyMs(event) {
+  const candidates = [event.recordedAt, event.finishedAt]
+    .map((value) => (value ? Date.parse(value) : Number.NaN))
+    .filter((value) => !Number.isNaN(value));
+  return candidates.length > 0 ? Math.max(...candidates) : null;
+}
+
 function calculateMetrics(events, workflowDefs) {
   const workflowMap = new Map(
     (Array.isArray(workflowDefs) ? workflowDefs : [])
       .filter((workflow) => isObject(workflow) && typeof workflow.id === 'string')
       .map((workflow) => [workflow.id, workflow]),
   );
+  const dedupedEvents = dedupeRunEvents(events);
   const grouped = new Map();
   const rerunPhaseCounts = new Map();
   const gatePauseCounts = new Map();
@@ -194,7 +241,7 @@ function calculateMetrics(events, workflowDefs) {
   const phaseDurationCounts = new Map();
   let runsWithPhaseDurations = 0;
 
-  for (const event of events) {
+  for (const event of dedupedEvents) {
     if (!grouped.has(event.workflowId)) {
       grouped.set(event.workflowId, []);
     }

package/plugins/spec-driver/scripts/goal-loop-cli.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+
+/**
+ * goal-loop-cli.mjs
+ * Feature 201 — goal_loop core 的薄 CLI 包装（仿 orchestrator-cli.mjs）
+ *
+ * 设计契约（plan §1.1 / tasks T018，修正 Codex C-02）：
+ *   所有"需要复杂结构输入"的子命令一律接受**单个 JSON payload**（文件路径），
+ *   输出 JSON 到 stdout；简单标量子命令用位置参数。SKILL.md 散文必须按本契约调用。
+ *
+ * 用法:
+ *   node goal-loop-cli.mjs parse-report <reportJsonFile>
+ *   node goal-loop-cli.mjs classify-command <cmdJsonFile>
+ *   node goal-loop-cli.mjs decide-stop <payloadJsonFile>      # payload={report,round,config,prevReports,rollbackResult}
+ *   node goal-loop-cli.mjs plan-snapshot <isClean:true|false>
+ *   node goal-loop-cli.mjs plan-rollback <snapshotJsonFile>   # snapshot={clean,ref}
+ *   node goal-loop-cli.mjs select-verify-mode <round> <max> <aboutToExit:true|false>
+ *   node goal-loop-cli.mjs decide-dispatch <phaseId> <agentMode>
+ *   node goal-loop-cli.mjs interpret-impact <mcpResultJsonFile>
+ *   node goal-loop-cli.mjs format-iteration-log-entry <entryJsonFile>  # 输出 markdown 块到 stdout
+ *   node goal-loop-cli.mjs assess-preserved-config-safety <porcelainFile|-（stdin）>
+ *     # 输入 = `git status --porcelain --untracked-files=all -- <PRESERVED_CONFIG_PATHSPECS>` 原始 stdout
+ *     #   （MUST 带 --untracked-files=all：避免 untracked 目录折叠成 `?? .specify/` 漏检 preserved 文件）
+ *     # CLI 内部 parsePreservedConfigStates(porcelain, PRESERVED_CONFIG_PATHSPECS) → assessPreservedConfigSafety
+ *   node goal-loop-cli.mjs is-clean-excluding-preserved <porcelainFile|-（stdin）>
+ *     # 输入 = **全仓** `git status --porcelain --untracked-files=all` 原始 stdout（不带 -- pathspec）
+ *     #   （MUST 带 --untracked-files=all：默认会把 untracked 目录折叠成 `?? .specify/`，折叠形式喂入
+ *     #    会使 isClean 误判 false → 空 stash 抓无关旧 stash，CRITICAL-7 漏网根因）
+ *     # 输出 {isClean:boolean}：排除 PRESERVED_CONFIG_PATHSPECS 后是否干净（F203 CRITICAL-7）
+ *   node goal-loop-cli.mjs acquire-lock <lockPath>
+ *   node goal-loop-cli.mjs release-lock <lockPath>
+ */
+
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  classifyCommand,
+  decideStop,
+  decideDispatch,
+  selectVerifyMode,
+  planSnapshotCommands,
+  planRollbackCommands,
+  parseReport,
+  interpretImpactResult,
+  formatIterationLogEntry,
+  assessPreservedConfigSafety,
+  parsePreservedConfigStates,
+  isCleanExcludingPreserved,
+  PRESERVED_CONFIG_PATHSPECS,
+} from './lib/goal-loop-core.mjs';
+
+// ──────────────────────────────────────────────────────────────────────────
+// I/O 边界：单实例文件锁（FR-018）—— 非纯函数，故放 CLI 不放纯 core
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * 写锁 payload 到已打开的 fd 并关闭
+ * @param {number} fd
+ */
+function writeLockPayload(fd) {
+  const payload = JSON.stringify({ pid: process.pid, start_time: new Date().toISOString() });
+  try {
+    fs.writeSync(fd, payload);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * 判定现有锁是否为 stale（仅当持锁进程已不存在 或 锁内容损坏）（Codex W3 / Phase B 复审修正）
+ *
+ * 关键不变量（FR-018 单实例保证）：**持锁 PID 存活时永不视为 stale**，无论锁多老。
+ * 早期版本曾用 TTL（30min）兜底接管"超龄但存活"的锁，但真实 goal_loop 跑满
+ * max_iterations × max_verify_seconds 很容易超 30min，会导致新实例强抢活锁、破坏单实例保证。
+ * 因此移除 TTL 接管路径：接管只发生在"持有者证明已死"或"锁文件损坏无法证明存活"两种情况。
+ *
+ * 已知罕见残留：PID 复用——死 goal_loop 的 PID 被无关进程复用后，process.kill(pid,0) 误判存活，
+ * 锁将无法自动接管，需人工清理 .lock 文件。我们接受这个罕见 case，不引入 TTL 接管活锁的
+ * 更大风险（误杀正在跑的长任务）来换取它。
+ * @param {string} lockPath
+ * @returns {{ stale: boolean, holderPid: number|null, reason: string }}
+ */
+function inspectLock(lockPath) {
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+  } catch {
+    // 锁内容损坏/不可解析 → 无法证明持有者存活，视为 stale 可接管
+    return { stale: true, holderPid: null, reason: 'lock_payload_unreadable' };
+  }
+  const holderPid = typeof payload.pid === 'number' ? payload.pid : null;
+
+  // 进程存活探测：process.kill(pid, 0) 不发信号，仅校验进程存在；ESRCH = 进程不存在
+  if (holderPid !== null) {
+    try {
+      process.kill(holderPid, 0);
+    } catch (err) {
+      if (err.code === 'ESRCH') {
+        return { stale: true, holderPid, reason: 'holder_process_gone' };
+      }
+      // EPERM = 进程存在但无权限发信号 → 持有者存活（保守），非 stale
+    }
+  } else {
+    // payload 缺合法 pid 字段 → 无法证明存活，视为 stale 可接管
+    return { stale: true, holderPid: null, reason: 'lock_payload_unreadable' };
+  }
+
+  // 走到这里：holderPid 存活（kill 未抛 ESRCH）→ 永不接管，无论锁龄
+  return { stale: false, holderPid, reason: 'holder_alive' };
+}
+
+/**
+ * 单实例文件锁：以 O_EXCL 原子创建 .lock（FR-018）
+ *
+ * stale 恢复（Codex W3 / Phase B 复审修正）：遇 EEXIST 时校验现有锁——仅当持锁进程不存在（ESRCH）
+ * 或锁文件损坏无法证明持有者存活时，原子清理 stale 锁后重试一次获取；否则（持有者存活）返回
+ * lock_exists（含 holder pid）。不再用 TTL 接管"超龄但存活"的活锁（见 inspectLock 注释）。
+ * @param {string} lockPath
+ * @returns {{ acquired: true }|{ acquired: false, reason: string, holderPid?: number|null }}
+ */
+export function acquireLock(lockPath) {
+  let fd;
+  try {
+    // 'wx' = O_CREAT | O_EXCL | O_WRONLY：文件已存在则抛 EEXIST（原子，防竞态）
+    fd = fs.openSync(lockPath, 'wx');
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      const info = inspectLock(lockPath);
+      if (!info.stale) {
+        return { acquired: false, reason: 'lock_exists', holderPid: info.holderPid };
+      }
+      // stale 锁：原子清理后重试一次获取。
+      // 用第二个 'wx' 而非先 unlink 再 open，避免清理与重建之间的竞态（仅重试一次防活锁）。
+      try {
+        fs.unlinkSync(lockPath);
+      } catch (unlinkErr) {
+        if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+        // ENOENT：他人已抢先清理，继续尝试创建
+      }
+      try {
+        fd = fs.openSync(lockPath, 'wx');
+      } catch (retryErr) {
+        if (retryErr.code === 'EEXIST') {
+          // 清理后被其他进程抢占 → 让对方持有，返回 lock_exists
+          const after = inspectLock(lockPath);
+          return { acquired: false, reason: 'lock_exists', holderPid: after.holderPid };
+        }
+        throw retryErr;
+      }
+      writeLockPayload(fd);
+      return { acquired: true };
+    }
+    throw err;
+  }
+  writeLockPayload(fd);
+  return { acquired: true };
+}
+
+/**
+ * 释放单实例文件锁（FR-018）
+ * @param {string} lockPath
+ * @returns {{ released: boolean }}
+ */
+export function releaseLock(lockPath) {
+  try {
+    fs.unlinkSync(lockPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // 锁不存在视为已释放（幂等）
+      return { released: true };
+    }
+    throw err;
+  }
+  return { released: true };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// CLI dispatch
+// ──────────────────────────────────────────────────────────────────────────
+
+function output(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function fail(message) {
+  console.error(JSON.stringify({ success: false, error: message }, null, 2));
+  process.exit(1);
+}
+
+function readJsonFile(filePath) {
+  if (!filePath) {
+    fail('缺少 JSON payload 文件路径参数');
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+/** 同步读取 stdin（fd 0）全部内容为 UTF-8 文本 */
+function readStdin() {
+  return fs.readFileSync(0, 'utf-8');
+}
+
+function parseBool(value, name) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  fail(`参数 ${name} 必须为 true|false，实际为 "${value}"`);
+}
+
+function main(argv) {
+  const [subcommand, ...args] = argv;
+
+  switch (subcommand) {
+    case 'parse-report': {
+      // parseReport 接受原始文本（含可能非法 JSON），故直接读文本不预解析
+      const filePath = args[0];
+      if (!filePath) fail('parse-report 需要 <reportJsonFile>');
+      const text = fs.readFileSync(filePath, 'utf-8');
+      output(parseReport(text));
+      break;
+    }
+    case 'classify-command': {
+      output({ status: classifyCommand(readJsonFile(args[0])) });
+      break;
+    }
+    case 'decide-stop': {
+      const payload = readJsonFile(args[0]);
+      output(
+        decideStop({
+          report: payload.report,
+          round: payload.round,
+          config: payload.config,
+          prevReports: payload.prevReports ?? [],
+          rollbackResult: payload.rollbackResult ?? null,
+        }),
+      );
+      break;
+    }
+    case 'plan-snapshot': {
+      output({ commands: planSnapshotCommands(parseBool(args[0], 'isClean')) });
+      break;
+    }
+    case 'plan-rollback': {
+      output({ commands: planRollbackCommands(readJsonFile(args[0])) });
+      break;
+    }
+    case 'select-verify-mode': {
+      const round = Number(args[0]);
+      const max = Number(args[1]);
+      const aboutToExit = parseBool(args[2], 'aboutToExit');
+      if (Number.isNaN(round) || Number.isNaN(max)) {
+        fail('select-verify-mode 需要数字 <round> <max>');
+      }
+      output({ mode: selectVerifyMode(round, max, aboutToExit) });
+      break;
+    }
+    case 'decide-dispatch': {
+      if (args.length < 2) fail('decide-dispatch 需要 <phaseId> <agentMode>');
+      output(decideDispatch(args[0], args[1]));
+      break;
+    }
+    case 'interpret-impact': {
+      output(interpretImpactResult(readJsonFile(args[0])));
+      break;
+    }
+    case 'format-iteration-log-entry': {
+      // 输出 markdown 块（含内嵌 ```json 围栏）到 stdout，供编排器直接追加写入 iteration-log.md。
+      // 与其它子命令不同：本子命令输出原始 markdown 文本，而非 JSON.stringify 包裹（散文直接拼日志）。
+      if (!args[0]) fail('format-iteration-log-entry 需要 <entryJsonFile>');
+      process.stdout.write(formatIterationLogEntry(readJsonFile(args[0])));
+      break;
+    }
+    case 'assess-preserved-config-safety': {
+      // 吃原始 `git status --porcelain` 文本（解析在 core，编排器零解析）：
+      // porcelain → state 由 parsePreservedConfigStates；state → 安全 由 assessPreservedConfigSafety。
+      if (!args[0]) fail('assess-preserved-config-safety 需要 <porcelainFile|-（stdin）>');
+      const porcelain = args[0] === '-' ? readStdin() : fs.readFileSync(args[0], 'utf-8');
+      const entries = parsePreservedConfigStates(porcelain, PRESERVED_CONFIG_PATHSPECS);
+      output(assessPreservedConfigSafety(entries));
+      break;
+    }
+    case 'is-clean-excluding-preserved': {
+      // 吃**全仓** `git status --porcelain` 文本（不带 pathspec），排除 PRESERVED_CONFIG_PATHSPECS
+      // 后判 isClean——杜绝"唯一 dirty 是 preserved override 却按全仓判 false → 空 stash 抓无关旧
+      // stash"的 CRITICAL-7 危险路径。解析全在已单测 core。
+      if (!args[0]) fail('is-clean-excluding-preserved 需要 <porcelainFile|-（stdin）>');
+      const porcelainAll = args[0] === '-' ? readStdin() : fs.readFileSync(args[0], 'utf-8');
+      output({ isClean: isCleanExcludingPreserved(porcelainAll, PRESERVED_CONFIG_PATHSPECS) });
+      break;
+    }
+    case 'acquire-lock': {
+      if (!args[0]) fail('acquire-lock 需要 <lockPath>');
+      output(acquireLock(args[0]));
+      break;
+    }
+    case 'release-lock': {
+      if (!args[0]) fail('release-lock 需要 <lockPath>');
+      output(releaseLock(args[0]));
+      break;
+    }
+    default:
+      fail(`未知子命令: ${subcommand ?? '(空)'}`);
+  }
+}
+
+// 仅当作为入口脚本直接运行时执行 dispatch（被 import 时不触发，便于单测）
+if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
+  main(process.argv.slice(2));
+}

package/plugins/spec-driver/scripts/init-project.sh

@@ -46,6 +46,7 @@ ALT_CONFIG_FILE="${SPECIFY_DIR}/spec-driver.config.yaml"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
 source "${SCRIPT_DIR}/lib/init-project-output.sh"
+source "${SCRIPT_DIR}/lib/ensure-gitignore.sh"
 SPECIFY_BASE_TEMPLATES_DIR="${PLUGIN_DIR}/templates/specify-base"
 FALLBACK_SPECIFY_TEMPLATES_DIR="${PLUGIN_DIR}/../../.specify/templates"
 DEFAULT_SCORECARD_DIR="${PLUGIN_DIR}/scorecards"
@@ -291,8 +292,63 @@ detect_spec_driver_skills() {
   fi
 }
 
+# 步骤 1a: 确保 Spec Driver 落盘产物的 ignore 规则就位（Feature 207，分层防线）
+# 分两条防线：
+#   (1) .git/info/exclude — 非 tracked 的主防线（零 diff 污染），仅 .git 为目录时执行
+#   (2) .gitignore        — 团队共享配置（.git/info/exclude 无法共享的兜底，覆盖 worktree/非 git 场景）
+# 防御：吞掉共享库的非零返回（极端只读文件系统等），只记录信号，绝不 exit 中断初始化
+ensure_gitignore_step() {
+  # 主防线：.git/info/exclude（非 git / worktree 场景返回 skipped）
+  local exclude_result
+  exclude_result="$(ensure_spec_driver_git_exclude "$PROJECT_ROOT")" || {
+    INIT_RESULTS+=("git_exclude:skip_error")
+    exclude_result="__handled__"
+  }
+  if [[ "$exclude_result" != "__handled__" ]]; then
+    case "$exclude_result" in
+      created:*)   INIT_RESULTS+=("git_exclude:created:${exclude_result#created:}") ;;
+      appended:*)  INIT_RESULTS+=("git_exclude:injected:${exclude_result#appended:}") ;;
+      ready:*)     INIT_RESULTS+=("git_exclude:ready") ;;
+      failed:*)    INIT_RESULTS+=("git_exclude:skip_error") ;;
+      skipped:*)   INIT_RESULTS+=("git_exclude:skipped") ;;
+      *)           INIT_RESULTS+=("git_exclude:unknown") ;;
+    esac
+  fi
+
+  # 兜底防线：.gitignore（团队共享配置）
+  local result
+  result="$(ensure_spec_driver_gitignore "$PROJECT_ROOT")" || {
+    INIT_RESULTS+=("gitignore:skip_error")
+    return 0
+  }
+
+  case "$result" in
+    created:*)
+      INIT_RESULTS+=("gitignore:created:${result#created:}")
+      ;;
+    appended:*)
+      INIT_RESULTS+=("gitignore:injected:${result#appended:}")
+      ;;
+    ready:*)
+      INIT_RESULTS+=("gitignore:ready")
+      ;;
+    failed:*)
+      # 写入失败（只读 FS 等）→ 复用既有 skip_error 文本分支
+      INIT_RESULTS+=("gitignore:skip_error")
+      ;;
+    skipped:*)
+      # 并发会话持锁 → 本次跳过检查，下次会话自然补齐（不等同 ready，勿撒谎为已就位）
+      INIT_RESULTS+=("gitignore:lock_skipped")
+      ;;
+    *)
+      INIT_RESULTS+=("gitignore:unknown")
+      ;;
+  esac
+}
+
 run_init_checks() {
   init_specify_dir
+  ensure_gitignore_step
   sync_specify_templates
   sync_scorecard_defaults
   ensure_project_context

package/plugins/spec-driver/scripts/kb-prequery.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * F191 kb-prequery — spec-driver 编排器在 specify 阶段前的 KB 预查（确定性脚本）。
+ *
+ * 读 resolved knowledge_sources → bin 发现 + 能力探测 → shell out `spectra scaffold-kb query`
+ * → 注入块透传 stdout。退出**始终 0**（不阻断 spec-driver 流程）；降级原因写 stderr。
+ * keyword 提取 / 检索 / 格式化 / 字符 cap 全在 spectra query 侧（本脚本只薄编排）。
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROBE_SENTINEL = 'scaffold-kb-query:1';
+const SPAWN_TIMEOUT_MS = 10_000;
+const MAX_BUFFER = 4 * 1024 * 1024;
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--requirement') out.requirement = argv[++i];
+    else if (argv[i] === '--project-root') out.projectRoot = argv[++i];
+  }
+  return out;
+}
+
+function diag(reason) {
+  process.stderr.write(`[kb-prequery] ${reason}\n`);
+}
+
+/** 经 resolve-project-context.mjs --json 读取 resolvedProfile.knowledgeSources */
+function resolveKnowledgeSources(projectRoot) {
+  const resolver = join(__dirname, 'resolve-project-context.mjs');
+  const r = spawnSync('node', [resolver, '--project-root', projectRoot, '--json'], {
+    encoding: 'utf-8',
+    timeout: SPAWN_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER,
+  });
+  if (r.status !== 0 || typeof r.stdout !== 'string') return null;
+  try {
+    return JSON.parse(r.stdout).resolvedProfile?.knowledgeSources ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** bin 发现（覆盖优先）：$SPECTRA_BIN → 项目 node_modules/.bin → PATH */
+function discoverSpectraBin(projectRoot) {
+  const envBin = process.env['SPECTRA_BIN'];
+  if (envBin && existsSync(envBin)) return envBin;
+  const local = join(projectRoot, 'node_modules', '.bin', 'spectra');
+  if (existsSync(local)) return local;
+  return 'spectra'; // 交给 PATH；不存在则 spawnSync ENOENT
+}
+
+/**
+ * 能力探测：区分 ok / missing（bin 不存在 ENOENT）/ too-old（能跑但无 sentinel = 旧版无 query）。
+ * 修 Codex W2：原实现全归 spectra-unavailable，无法区分缺 bin 与旧版。
+ */
+function probeBin(bin) {
+  const r = spawnSync(bin, ['scaffold-kb', 'query', '--probe'], {
+    encoding: 'utf-8',
+    timeout: SPAWN_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER,
+  });
+  if (r.error && r.error.code === 'ENOENT') return 'missing';
+  if (r.status === 0 && typeof r.stdout === 'string' && r.stdout.includes(PROBE_SENTINEL)) return 'ok';
+  return 'too-old';
+}
+
+function main() {
+  const { requirement, projectRoot = process.cwd() } = parseArgs(process.argv.slice(2));
+  if (!requirement) {
+    diag('no-requirement');
+    return;
+  }
+
+  const ks = resolveKnowledgeSources(projectRoot);
+  if (!ks || ks.enabled !== true || !ks.vendorKb) {
+    diag('disabled-or-unconfigured');
+    return;
+  }
+
+  const bin = discoverSpectraBin(projectRoot);
+  const probeResult = probeBin(bin);
+  if (probeResult === 'missing') {
+    diag(`spectra-unavailable (bin=${bin}; 未安装 spectra)`);
+    return;
+  }
+  if (probeResult === 'too-old') {
+    diag(`spectra-too-old (bin=${bin}; 版本过旧，无 scaffold-kb query 子命令)`);
+    return;
+  }
+
+  const args = [
+    'scaffold-kb', 'query',
+    '--requirement', requirement,
+    '--vendor-kb', ks.vendorKb,
+    '--top-k', String(ks.topK ?? 3),
+    '--max-inject-chars', String(ks.maxInjectChars ?? 6000),
+    '--format', 'markdown',
+  ];
+  if (ks.projectKb) args.push('--project-kb', ks.projectKb);
+
+  const q = spawnSync(bin, args, {
+    encoding: 'utf-8',
+    timeout: SPAWN_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER,
+  });
+  if (q.status !== 0) {
+    diag(`query-failed (status=${q.status}): ${(q.stderr ?? '').trim()}`);
+    return;
+  }
+  const block = (q.stdout ?? '').trim();
+  if (block.length === 0) {
+    // 透传 query 自身的结构化降级原因（kb-missing / no-hit / no-query），不再一律标 no-hit（修 Codex W2）
+    diag(`no-injection: ${(q.stderr ?? 'no-hit').trim()}`);
+    return;
+  }
+  process.stdout.write(`${block}\n`);
+}
+
+main();