spectra-cli 4.1.1 → 4.3.0

package/plugins/spec-driver/scripts/codex-skills.sh

@@ -76,18 +76,8 @@ ensure_source_exists() {
   fi
 }
 
-rewrite_codex_runtime_text() {
-  sed \
-    -e 's|/spec-driver:spec-driver-feature|$spec-driver-feature|g' \
-    -e 's|/spec-driver:spec-driver-implement|$spec-driver-implement|g' \
-    -e 's|/spec-driver:spec-driver-story|$spec-driver-story|g' \
-    -e 's|/spec-driver:spec-driver-fix|$spec-driver-fix|g' \
-    -e 's|/spec-driver:spec-driver-resume|$spec-driver-resume|g' \
-    -e 's|/spec-driver:spec-driver-sync|$spec-driver-sync|g' \
-    -e 's|/spec-driver:spec-driver-doc|$spec-driver-doc|g' \
-    -e 's|Claude Code 的 Task tool|Task tool（Codex 下按内联子代理执行）|g' \
-    -e 's|在同一消息中同时发出多个 Task tool 调用。Claude Code 的 function calling 机制支持在单个 assistant 消息中发出多个 tool calls，这些 tool calls 会被并行执行。|若当前环境支持并行工具调用，则在同一消息中并行执行；否则按本 Skill 的回退规则串行执行。|g'
-}
+# F186 T2：原 rewrite_codex_runtime_text（awk|sed 管道的 9 条替换）已迁移到单一 Node helper
+# plugins/spec-driver/scripts/lib/extract-wrapper-body.mjs，与 JS 校验端共用，杜绝双实现漂移。
 
 write_frontmatter() {
   local skill_name="$1"
@@ -134,11 +124,24 @@ EOF_ADAPTER
 
 write_wrapper_source_contract() {
   local source_skill_name="$1"
+  local source_skill_path="$2"
+
+  # F186 T2：盖印 source body sha256（与 JS 校验端共用同一 helper，杜绝双实现漂移）。
+  local body_sha
+  body_sha="$(node "$PLUGIN_DIR/scripts/lib/extract-wrapper-body.mjs" "$source_skill_path" --sha256)"
+
+  # CRITICAL-1：helper 在安装路径含空格/非 ASCII 时若 isDirectExecution 误判会输出空 stdout 但退出码 0，
+  # 静默生成空 sha → 空 wrapper。此处对非 64 位十六进制 sha 做 hard fail，杜绝静默降级。
+  if [[ ! "$body_sha" =~ ^[0-9a-f]{64}$ ]]; then
+    echo "[错误] extract-wrapper-body.mjs 未产出合法 sha256（got: '${body_sha}'），source: $source_skill_path" >&2
+    exit 1
+  fi
 
   cat <<EOF_CONTRACT
 ## Wrapper Source Contract
 
 - Canonical source: \`\$PLUGIN_DIR/skills/$source_skill_name/SKILL.md\`
+- Source SHA256: $body_sha
 - Generated by: \`bash \$PLUGIN_DIR/scripts/codex-skills.sh install\`
 - Contract: \`\$PLUGIN_DIR/contracts/wrapper-source-of-truth.yaml\`
 - Maintenance rule: edit the source skill, then reinstall; do not edit this wrapper directly
@@ -150,21 +153,18 @@ EOF_CONTRACT
 write_skill_body() {
   local source_skill_path="$1"
 
-  awk '
-    NR == 1 && $0 == "---" {
-      in_frontmatter = 1
-      next
-    }
-    in_frontmatter {
-      if ($0 == "---") {
-        in_frontmatter = 0
-      }
-      next
-    }
-    {
-      print
-    }
-  ' "$source_skill_path" | rewrite_codex_runtime_text
+  # F186 T2：frontmatter 剥除 + runtime text 替换改由单一 Node helper 产出，
+  # 与 validate-wrapper-sources.mjs 共用同一提取逻辑（防双实现逐字节漂移）。
+  local body
+  body="$(node "$PLUGIN_DIR/scripts/lib/extract-wrapper-body.mjs" "$source_skill_path")"
+
+  # CRITICAL-1：helper 误判 isDirectExecution（含空格/非 ASCII 安装路径）时会输出空 body 但退出码 0，
+  # 静默生成空正文 wrapper。source skill 正文恒非空，故空 body 必为 helper 故障 → hard fail。
+  if [[ -z "$body" ]]; then
+    echo "[错误] extract-wrapper-body.mjs 产出空 body，source: $source_skill_path" >&2
+    exit 1
+  fi
+  printf '%s\n' "$body"
 }
 
 write_wrapper() {
@@ -179,7 +179,7 @@ write_wrapper() {
   {
     write_frontmatter "$skill_name" "$source_skill_path"
     printf '\n'
-    write_wrapper_source_contract "$source_skill_name"
+    write_wrapper_source_contract "$source_skill_name" "$source_skill_path"
     printf '\n'
     write_codex_adapter "$skill_name" "$source_skill_name"
     printf '\n'

package/plugins/spec-driver/scripts/dev/spike-fix-compliance-e2e.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+/**
+ * spike-fix-compliance-e2e.mjs
+ * Feature 208 / T028 — fix 依从性 Stop hook 的手工 headless E2E spike。
+ *
+ * ⚠️ 手工触发脚本：会 spawn `claude --print` 消耗真实订阅凭据（haiku + 极简任务，
+ * 单次 <$0.05），**不计入 `npm test`**、不在 CI 自动跑。用途 = 在与评测同构的
+ * headless 入口（--plugin-dir 注入插件副本 + Stop hook 挂载）下，观测
+ * `stop-fix-compliance-check.sh` 的 exit code 与 `[FIX-COMPLIANCE]` 反馈闭环。
+ *
+ * 手法复刻 specs/208-.../research/harness-verification.md 的"插件副本 + hook-trace"实锤：
+ *   1. 拷贝 plugins/spec-driver 到 scratchpad/os.tmpdir 副本（不污染源码）
+ *   2. 副本 hooks.json 追加 Stop → stop-fix-compliance-check.sh
+ *   3. claude --print --plugin-dir <副本> 跑 collapsed / compliant 极简场景
+ *   4. 打印 hook-trace 时间线与最终 exit code
+ *
+ * 用法：
+ *   node plugins/spec-driver/scripts/dev/spike-fix-compliance-e2e.mjs --scenario collapsed
+ *   node plugins/spec-driver/scripts/dev/spike-fix-compliance-e2e.mjs --scenario compliant
+ *   node plugins/spec-driver/scripts/dev/spike-fix-compliance-e2e.mjs --scenario collapsed --keep   # 保留副本供排查
+ *
+ * 执行属 T029 主编排器职责；本文件仅提供可重跑脚本。
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCENARIOS = new Set(['collapsed', 'compliant']);
+
+function parseArgs(argv) {
+  const args = { scenario: 'collapsed', keep: false, model: 'claude-haiku-4-5' };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--scenario') { args.scenario = argv[i + 1] ?? args.scenario; i += 1; } else if (argv[i] === '--keep') { args.keep = true; } else if (argv[i] === '--model') { args.model = argv[i + 1] ?? args.model; i += 1; }
+  }
+  if (!SCENARIOS.has(args.scenario)) {
+    throw new Error(`未知场景: ${args.scenario}（可选: ${[...SCENARIOS].join(', ')}）`);
+  }
+  return args;
+}
+
+/** 递归拷贝插件源码到副本目录（node 20 fs.cpSync） */
+function copyPluginTo(destRoot) {
+  const pluginSrc = fileURLToPath(new URL('../..', import.meta.url)); // plugins/spec-driver
+  const dest = path.join(destRoot, 'spec-driver');
+  fs.cpSync(pluginSrc, dest, {
+    recursive: true,
+    filter: (src) => !src.includes(`${path.sep}node_modules${path.sep}`) && !src.endsWith(`${path.sep}node_modules`),
+  });
+  return dest;
+}
+
+/** 在副本 hooks.json 的 Stop 数组挂载新 hook（幂等：T026 之后源码已自带该条目，重复追加会双挂双计数） */
+function mountStopHook(pluginDest) {
+  const hooksPath = path.join(pluginDest, 'hooks', 'hooks.json');
+  const hooks = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+  hooks.hooks.Stop = hooks.hooks.Stop || [];
+  const alreadyMounted = hooks.hooks.Stop.some((entry) =>
+    (entry.hooks || []).some((h) => typeof h.command === 'string' && h.command.includes('stop-fix-compliance-check.sh')));
+  if (!alreadyMounted) {
+    hooks.hooks.Stop.push({
+      matcher: '',
+      hooks: [{ type: 'command', command: 'bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop-fix-compliance-check.sh' }],
+    });
+    fs.writeFileSync(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`, 'utf8');
+  }
+  return alreadyMounted;
+}
+
+/**
+ * 构造极简 headless prompt。
+ * collapsed：诱导模型直接输出"完成"而不走委派（观测 exit 2 + [FIX-COMPLIANCE]）。
+ * compliant：仅要求回一个字（不会触发 fix 展开 → 非 fix 会话零接触，作为对照）。
+ *
+ * 说明：真正的 fix 展开由 slash 命令 harness 注入，spike 无法在 --print 位置参数里
+ * 完美复刻 SKILL 展开；本 spike 主要观测 hook 是否执行 + 退出码转发是否成立，
+ * 完整 opus + 真实展开的端到端可靠性属评测阶段（harness-verification.md 外推边界）。
+ */
+function buildPrompt(scenario) {
+  if (scenario === 'collapsed') {
+    return 'Base directory for this skill: /w/plugins/spec-driver/skills/spec-driver-fix\n请直接回复"已修复"，不要调用任何工具。';
+  }
+  return 'say only ok';
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const scratchBase = process.env.SCRATCHPAD || os.tmpdir();
+  const workdir = fs.mkdtempSync(path.join(scratchBase, 'fix-compliance-spike-'));
+  const pluginCopyRoot = path.join(workdir, 'plugins');
+  fs.mkdirSync(pluginCopyRoot, { recursive: true });
+
+  console.log(`[spike] scenario=${args.scenario} model=${args.model}`);
+  console.log(`[spike] workdir=${workdir}`);
+
+  const pluginDest = copyPluginTo(pluginCopyRoot);
+  mountStopHook(pluginDest);
+  console.log(`[spike] 插件副本已就绪 + Stop hook 已挂载: ${pluginDest}/hooks/hooks.json`);
+
+  const prompt = buildPrompt(args.scenario);
+  const started = Date.now();
+  const res = spawnSync('claude', [
+    '--print',
+    '--model', args.model,
+    '--plugin-dir', pluginDest,
+    '--permission-mode', 'acceptEdits',
+    '--', prompt,
+  ], { encoding: 'utf8', cwd: workdir });
+
+  const elapsedMs = Date.now() - started;
+  console.log('──────── hook-trace / 输出 ────────');
+  console.log(`[spike] exit=${res.status} elapsedMs=${elapsedMs}`);
+  console.log('[spike] stdout:');
+  console.log(res.stdout || '(空)');
+  console.log('[spike] stderr（关注 [FIX-COMPLIANCE] / [GATE-DEGRADED] 前缀）:');
+  console.log(res.stderr || '(空)');
+  console.log('───────────────────────────────────');
+
+  if (args.keep) {
+    console.log(`[spike] --keep：保留副本 ${workdir}`);
+  } else {
+    fs.rmSync(workdir, { recursive: true, force: true });
+    console.log('[spike] 已清理副本');
+  }
+}
+
+main();

package/plugins/spec-driver/scripts/fix-compliance-judge.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+
+/**
+ * fix-compliance-judge.mjs
+ * Feature 208 — fix 模式流程依从性判定 CLI 编排入口（唯一由 hooks.json 挂载的生产路径）
+ *
+ * 分层契约（research.md D3）：本文件是 I/O 编排层，负责
+ *   解析参数与 stdin payload → 编排 io 层读取（config/transcript/state）→ 调用 core 纯函数判定
+ *   → 编排 io 层写入（审计事件 / 阻断计数 / 降级放行的 record-workflow-run 终态事件）
+ *   → 决定退出码与 stderr 反馈文本。
+ *
+ * 不变量（contracts/fix-compliance-judge-cli.md）：
+ *   - 零 LLM / 零子代理委派：全程无 `Task(` / 模型 API 调用。
+ *   - 顶层 try/catch 兜底（FR-013）：任何未捕获异常在 hook 模式下转化为 exit 0，不泄漏崩溃退出码。
+ *   - `--mode report` 恒 exit 0、只打印 verdict JSON、零落盘副作用。
+ *   - 不读取任务 ID / 任务描述文本作为判据（FR-011）。
+ */
+
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import { realpathSync } from 'node:fs';
+import {
+  detectFixSkillExpansion,
+  extractDelegationsAfter,
+  resolveFeatureDirCandidate,
+  judgeCompliance,
+  MISSING_ACTION_TEXT,
+  DUAL_PATH_GUIDANCE,
+  GATE_DEGRADED_PREFIX_LINE,
+} from './lib/fix-compliance-core.mjs';
+import {
+  readHookPayload,
+  readTranscriptEntries,
+  findAndParseConfig,
+  appendAuditEvent,
+  checkFeatureDirOnDisk,
+  readArtifactFile,
+  loadBlockState,
+  saveBlockState,
+  resetBlockState,
+} from './lib/fix-compliance-io.mjs';
+import { recordWorkflowRun } from './record-workflow-run.mjs';
+
+/** stderr 反馈前缀（FR-010，与既有 stop-task-check.sh 的 `[提醒]` 相区分） */
+const PREFIX_BLOCK = '[FIX-COMPLIANCE]';
+const PREFIX_WARN = '[FIX-COMPLIANCE][WARN]';
+const PREFIX_DEGRADED = '[FIX-COMPLIANCE][GATE-DEGRADED]';
+
+/** 会话内不合规阻断上限（FR-006）：达到后降级放行 */
+const BLOCK_LIMIT = 2;
+
+// ────────────────────────────────────────
+// 参数解析
+// ────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const args = { mode: 'hook', projectRoot: process.cwd(), transcriptPath: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--mode') {
+      args.mode = argv[i + 1] ?? args.mode;
+      i += 1;
+    } else if (token === '--project-root') {
+      args.projectRoot = argv[i + 1] ?? args.projectRoot;
+      i += 1;
+    } else if (token === '--transcript-path') {
+      args.transcriptPath = argv[i + 1] ?? args.transcriptPath;
+      i += 1;
+    }
+  }
+  if (args.mode !== 'hook' && args.mode !== 'report') args.mode = 'hook';
+  return args;
+}
+
+// ────────────────────────────────────────
+// stdin 读取（同步，避免异步竞态；hook payload 体量极小）
+// ────────────────────────────────────────
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// ────────────────────────────────────────
+// 判定编排（纯读取，不落盘；hook 与 report 共用）
+// ────────────────────────────────────────
+
+/**
+ * 编排一次完整判定：读配置 → 读 transcript → 锚定 → 抽取委派/制品 → core 判定。
+ * @returns {{
+ *   enforcement:string, configDegraded:boolean,
+ *   isFix:boolean, mode:string|null,
+ *   transcriptDiagnostics:string[],
+ *   verdict:object|null,
+ * }}
+ */
+function evaluate(projectRoot, transcriptPath, cfg = null) {
+  const config = cfg || findAndParseConfig(projectRoot);
+  const enforcement = config.enforcement;
+  const configDegraded = config.configDegraded;
+  const configDiagnostics = config.diagnostics || [];
+
+  const { entries, diagnostics: transcriptDiagnostics } = readTranscriptEntries(transcriptPath);
+  if (transcriptDiagnostics.length > 0) {
+    // transcript 不可用/超限 → FR-013 fail-open（无法得出判定结论）
+    return {
+      enforcement, configDegraded, isFix: false, mode: null,
+      transcriptDiagnostics, verdict: null,
+    };
+  }
+
+  const anchor = detectFixSkillExpansion(entries);
+  const isFix = anchor.found && anchor.mode === 'fix';
+  if (!isFix) {
+    return {
+      enforcement, configDegraded, isFix: false, mode: anchor.mode,
+      transcriptDiagnostics: [], verdict: null,
+    };
+  }
+
+  const delegations = extractDelegationsAfter(entries, anchor.anchorLineIndex);
+  const candidate = resolveFeatureDirCandidate(entries, anchor.anchorLineIndex);
+  const featureDirCheck = checkFeatureDirOnDisk(projectRoot, candidate.path);
+  const fixReport = candidate.path
+    ? readArtifactFile(projectRoot, `${candidate.path}/fix-report.md`)
+    : { exists: false, content: null, nonEmpty: false };
+  const verificationReport = candidate.path
+    ? readArtifactFile(projectRoot, `${candidate.path}/verification/verification-report.md`)
+    : { exists: false, content: null, nonEmpty: false };
+
+  const verdict = judgeCompliance({
+    delegations,
+    featureDir: { path: candidate.path, existsOnDisk: featureDirCheck.existsOnDisk },
+    fixReport: { exists: fixReport.exists, content: fixReport.content },
+    verificationReport: { exists: verificationReport.exists, nonEmpty: verificationReport.nonEmpty },
+    enforcement,
+    configDegraded,
+    diagnostics: configDiagnostics,
+  });
+
+  return {
+    enforcement, configDegraded, isFix: true, mode: anchor.mode,
+    transcriptDiagnostics: [], verdict,
+  };
+}
+
+// ────────────────────────────────────────
+// FR-010 反馈文本机械拼装（core 常量拼装，非自由生成）
+// ────────────────────────────────────────
+
+/**
+ * 由 missing 枚举拼装反馈文本：稳定动作行 + 双路径指引。
+ * @param {string[]} missing
+ * @param {{ degraded?:boolean, diagnostics?:string[] }} [opts]
+ */
+export function buildFeedbackText(missing, opts = {}) {
+  const actionLines = (Array.isArray(missing) ? missing : [])
+    .map((key) => MISSING_ACTION_TEXT[key])
+    .filter(Boolean);
+  const segments = [];
+  if (opts.degraded) segments.push(GATE_DEGRADED_PREFIX_LINE);
+  segments.push(...actionLines);
+  segments.push('', DUAL_PATH_GUIDANCE);
+  if (Array.isArray(opts.diagnostics) && opts.diagnostics.length > 0) {
+    segments.push('', `诊断: ${opts.diagnostics.join(', ')}`);
+  }
+  return segments.join('\n');
+}
+
+// ────────────────────────────────────────
+// 审计事件构造（contracts/fix-compliance-verdict-event.schema.json）
+// ────────────────────────────────────────
+
+function buildAuditEvent({ sessionId, enforcement, verdict, blockCount, degraded, extraDiagnostics }) {
+  const diag = new Set([
+    ...((verdict && verdict.diagnostics) || []),
+    ...(extraDiagnostics || []),
+  ]);
+  return {
+    schemaVersion: 1,
+    eventType: 'fix-compliance-verdict',
+    recordedAt: new Date().toISOString(),
+    sessionId,
+    enforcement,
+    closureForm: verdict ? verdict.closureForm : 'undetermined',
+    compliant: verdict ? verdict.compliant : null,
+    missing: verdict ? verdict.missing : [],
+    blockCount: enforcement === 'block' ? (typeof blockCount === 'number' ? blockCount : null) : null,
+    degraded: Boolean(degraded),
+    diagnostics: [...diag],
+  };
+}
+
+// ────────────────────────────────────────
+// hook 模式路由（阻断 / 警告 / 降级放行）
+// ────────────────────────────────────────
+
+/**
+ * 处理不合规 + block 档：阻断计数路由（FR-006 有界化）。
+ * @returns {number} 退出码
+ */
+function routeBlock(projectRoot, sessionId, verdict) {
+  const loaded = loadBlockState(projectRoot, sessionId);
+  const count = loaded.blockCount;
+
+  if (count < BLOCK_LIMIT) {
+    // 未达上限：尝试持久化 N+1 → 成功则硬阻断，失败（存储不可用）则等同已达上限降级放行
+    const nextCount = count + 1;
+    const saved = saveBlockState(projectRoot, sessionId, {
+      blockCount: nextCount,
+      degradedRecorded: loaded.degradedRecorded,
+    });
+    if (saved.ok) {
+      appendAuditEvent(projectRoot, buildAuditEvent({
+        sessionId, enforcement: 'block', verdict, blockCount: nextCount, degraded: false,
+      }));
+      process.stderr.write(`${PREFIX_BLOCK} ${buildFeedbackText(verdict.missing)}\n`);
+      return 2;
+    }
+    // 存储不可用 → 无法可靠维持计数，按等同"已达上限"降级放行（research.md D2）
+    return releaseDegraded(projectRoot, sessionId, verdict, {
+      alreadyRecorded: false,
+      storageUnavailable: true,
+    });
+  }
+
+  // 已达上限（count >= 2）→ 降级放行
+  return releaseDegraded(projectRoot, sessionId, verdict, {
+    alreadyRecorded: loaded.degradedRecorded,
+    storageUnavailable: false,
+  });
+}
+
+/**
+ * 降级放行：exit 0 + [GATE-DEGRADED] reason + 幂等终态双写（首次）或轻量审计（重复）。
+ * @returns {number} 恒 0
+ */
+function releaseDegraded(projectRoot, sessionId, verdict, { alreadyRecorded, storageUnavailable }) {
+  const extraDiagnostics = storageUnavailable ? ['state-storage-unavailable'] : [];
+  const blockCount = BLOCK_LIMIT;
+  // 存储不可用无法读写幂等标记 → 允许重复终态（宁可可审计不可静默丢失，research.md D2/D4）
+  const shouldWriteTerminal = storageUnavailable || !alreadyRecorded;
+
+  if (shouldWriteTerminal) {
+    try {
+      recordWorkflowRun({
+        projectRoot,
+        workflowId: 'spec-driver-fix',
+        runId: sessionId,
+        result: 'failed',
+        warnings: [`${PREFIX_DEGRADED} fix 会话在 ${BLOCK_LIMIT + 1} 次不合规尝试后降级放行，缺失: ${verdict.missing.join(', ')}`],
+        complianceVerdict: {
+          closureForm: verdict.closureForm,
+          compliant: verdict.compliant,
+          missing: verdict.missing,
+          degraded: true,
+          blockCount,
+        },
+      });
+    } catch {
+      // 终态写入失败不得让降级路由崩溃（FR-013 精神）
+    }
+    // 首次降级成功后置幂等标记（存储可用时才有意义）
+    if (!storageUnavailable) {
+      saveBlockState(projectRoot, sessionId, { blockCount, degradedRecorded: true });
+    }
+  }
+
+  appendAuditEvent(projectRoot, buildAuditEvent({
+    sessionId, enforcement: 'block', verdict, blockCount, degraded: true, extraDiagnostics,
+  }));
+  process.stderr.write(`${PREFIX_DEGRADED} ${buildFeedbackText(verdict.missing, { degraded: true, diagnostics: extraDiagnostics })}\n`);
+  return 0;
+}
+
+/**
+ * FR-013 fail-open 的 loud 半边：判定能力失效时 best-effort 落盘 degraded 诊断事件，
+ * 使"漏拦"在事后审计中可被发现而非彻底隐没。写入自身失败不得影响放行（双重兜底）。
+ */
+function tryAppendFailOpenEvent(projectRoot, sessionId, enforcement, diagnostics, configDiagnostics = []) {
+  try {
+    // 合并配置层诊断（如 config-degraded）——配置非法与判定异常同时发生时两类信息都不得丢失
+    // （codex implement 审查 W-2，FR-015 可追溯性）
+    const merged = [...new Set([
+      ...(Array.isArray(configDiagnostics) ? configDiagnostics : []),
+      ...(Array.isArray(diagnostics) ? diagnostics : []),
+    ])];
+    appendAuditEvent(projectRoot, {
+      schemaVersion: 1,
+      eventType: 'fix-compliance-verdict',
+      recordedAt: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'unknown',
+      enforcement: enforcement === 'warn' ? 'warn' : 'block',
+      closureForm: 'undetermined',
+      compliant: null,
+      missing: [],
+      blockCount: null,
+      degraded: true,
+      diagnostics: merged,
+    });
+  } catch {
+    // 诊断落盘失败不得让 fail-open 路径崩溃
+  }
+}
+
+/**
+ * hook 模式主路由。
+ * @returns {number} 退出码
+ */
+function runHook(projectRoot, payload) {
+  // FR-015 判定顺序：(1) 非抛出式配置解析 →(2) off 立即零接触退出（在任何 transcript 读取之前）
+  const cfg = findAndParseConfig(projectRoot);
+  if (cfg.enforcement === 'off') return 0;
+
+  const result = evaluate(projectRoot, payload.transcript_path, cfg);
+
+  // transcript 不可用/超限 → FR-013 fail-open 放行 + loud 诊断落盘（合并配置层诊断）
+  if (result.transcriptDiagnostics.length > 0) {
+    tryAppendFailOpenEvent(projectRoot, payload.session_id, cfg.enforcement, result.transcriptDiagnostics, cfg.diagnostics);
+    return 0;
+  }
+  // 非 fix 会话 → 零接触放行（US5：健康路径不产生任何落盘），不 reset 保持零落盘语义
+  if (!result.isFix || !result.verdict) return 0;
+  // 合规 → 重置该 session 阻断状态（补救成功清零转移，FR-006 增补）后静默放行。
+  // 无条件调用（不区分 block/warn）：warn 档从不 bump 计数、其状态文件本就不存在，
+  // reset 对其为空操作；off 档已在函数入口短路，永不触达此分支。
+  if (result.verdict.compliant) {
+    resetBlockState(projectRoot, payload.session_id);
+    return 0;
+  }
+
+  const sessionId = payload.session_id;
+
+  if (result.enforcement === 'warn') {
+    appendAuditEvent(projectRoot, buildAuditEvent({
+      sessionId, enforcement: 'warn', verdict: result.verdict, blockCount: null, degraded: false,
+    }));
+    process.stderr.write(`${PREFIX_WARN} ${buildFeedbackText(result.verdict.missing)}\n`);
+    return 0;
+  }
+
+  // enforcement=block
+  return routeBlock(projectRoot, sessionId, result.verdict);
+}
+
+// ────────────────────────────────────────
+// report 模式（只读，恒 exit 0，仅 stdout verdict JSON）
+// ────────────────────────────────────────
+
+function runReport(projectRoot, transcriptPath) {
+  const result = evaluate(projectRoot, transcriptPath);
+  const out = {
+    mode: result.mode,
+    fixSession: result.isFix,
+    enforcement: result.enforcement,
+    configDegraded: result.configDegraded,
+    transcriptDiagnostics: result.transcriptDiagnostics,
+    ...(result.verdict || {}),
+  };
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+  return 0;
+}
+
+// ────────────────────────────────────────
+// main（顶层 try/catch 兜底 FR-013）
+// ────────────────────────────────────────
+
+export function main(argv, stdinRaw) {
+  const args = parseArgs(argv);
+  try {
+    if (args.mode === 'report') {
+      // report 优先用 --transcript-path，缺省时回落 stdin payload
+      let transcriptPath = args.transcriptPath;
+      if (!transcriptPath) {
+        const parsed = readHookPayload(stdinRaw);
+        transcriptPath = parsed.ok ? parsed.payload.transcript_path : null;
+      }
+      return runReport(args.projectRoot, transcriptPath);
+    }
+    // hook 模式：stdin payload 必需
+    const parsed = readHookPayload(stdinRaw);
+    if (!parsed.ok) {
+      // payload 非法 → FR-013 fail-open 放行 + loud 诊断落盘（off 档除外，维持零接触）
+      const cfg = findAndParseConfig(args.projectRoot);
+      if (cfg.enforcement !== 'off') {
+        tryAppendFailOpenEvent(args.projectRoot, null, cfg.enforcement, ['payload-invalid'], cfg.diagnostics);
+      }
+      return 0;
+    }
+    return runHook(args.projectRoot, parsed.payload);
+  } catch {
+    // 任何未预期异常 → fail-open 放行（FR-013）+ best-effort loud 诊断（自身再失败则彻底静默放行）
+    try {
+      const cfg = findAndParseConfig(args.projectRoot);
+      if (cfg.enforcement !== 'off') {
+        tryAppendFailOpenEvent(args.projectRoot, null, cfg.enforcement, ['internal-error'], cfg.diagnostics);
+      }
+    } catch {
+      // 连诊断都写不了 → 仍然放行
+    }
+    return 0;
+  }
+}
+
+// 仅作为入口脚本直接运行时执行（被 import 时不触发，便于单测）
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
+  const argv = process.argv.slice(2);
+  const stdinRaw = readStdinSync();
+  const code = main(argv, stdinRaw);
+  process.exit(code);
+}