spectra-cli 4.2.0 → 4.3.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/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();