spectra-cli 4.2.0 → 4.3.0

package/plugins/spec-driver/scripts/sync-delegation-contract.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * sync-delegation-contract — 从 templates/delegation-contract.md 单一事实源，把委派硬约束块
+ * 按各 SKILL 显式锚点注入 5 个主编排器 SKILL.md 的 BEGIN/END marker 之间。
+ *
+ * 用法：
+ *   node plugins/spec-driver/scripts/sync-delegation-contract.mjs --write   # 生成/更新（默认）
+ *   node plugins/spec-driver/scripts/sync-delegation-contract.mjs --check   # 漂移检测（CI/repo:check）
+ *
+ * ⚠️ --write 只写 plugins 层 5 个源 SKILL；.codex wrapper 由 repo:sync 的
+ * spec-driver-codex-wrappers 步骤再生（顺序已编排在本注入之后）。模板变更后单跑
+ * --write 再跑 --check 会因 .codex stale 而 fail——这是预期信号，跑 `npm run repo:sync` 消除。
+ *
+ * 注入锚点（已实测，per-SKILL 精确匹配；锚点未找到 → fail-loud）：
+ *   fix/story/implement → '## 工作流定义'
+ *   feature             → '## 工作流执行（动态模式）'
+ *   resume              → '## 恢复后执行流程'
+ * 已有 marker：仅替换 marker 之间内容（锚点不移动，幂等）。
+ *
+ * 退出码：0 = 无漂移 / 写入完成；1 = --check 检测到漂移。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  extractCanonicalBlock,
+  wrapWithMarkers,
+  computeExpectedSkillContent,
+  BEGIN_MARKER,
+  END_MARKER,
+} from '../lib/delegation-contract.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_DIR = path.resolve(__dirname, '..');
+
+/** 显式 per-SKILL 注入锚点 map（已实测）。 */
+const SKILL_ANCHORS = {
+  fix: '## 工作流定义',
+  story: '## 工作流定义',
+  feature: '## 工作流执行（动态模式）',
+  implement: '## 工作流定义',
+  resume: '## 恢复后执行流程',
+};
+
+function resolvePaths(projectRoot) {
+  const root = projectRoot ? path.resolve(projectRoot) : path.resolve(PLUGIN_DIR, '../..');
+  const pluginDir = path.join(root, 'plugins/spec-driver');
+  return {
+    root,
+    pluginDir,
+    templatePath: path.join(pluginDir, 'templates/delegation-contract.md'),
+  };
+}
+
+function skillPath(pluginDir, mode) {
+  return path.join(pluginDir, 'skills', `spec-driver-${mode}`, 'SKILL.md');
+}
+
+function codexWrapperPath(root, mode) {
+  return path.join(root, '.codex/skills', `spec-driver-${mode}`, 'SKILL.md');
+}
+
+/**
+ * 供 repo:check（repo-maintenance-core）复用的漂移校验：
+ * 返回 { status, checks, warnings, errors }，与 aggregateValidation 契约一致。
+ */
+export function validateDelegationContract({ projectRoot } = {}) {
+  const { root, pluginDir, templatePath } = resolvePaths(projectRoot);
+  const errors = [];
+  const checks = [];
+
+  if (!fs.existsSync(templatePath)) {
+    return {
+      status: 'fail',
+      checks: [{ id: 'skill-block-sync', title: 'delegation-contract 单一源同步', status: 'fail', evidence: { reason: 'template 缺失' } }],
+      warnings: [],
+      errors: ['template 缺失: templates/delegation-contract.md'],
+    };
+  }
+  const templateText = fs.readFileSync(templatePath, 'utf-8');
+  const drifted = [];
+  for (const [mode, anchor] of Object.entries(SKILL_ANCHORS)) {
+    const p = skillPath(pluginDir, mode);
+    if (!fs.existsSync(p)) {
+      drifted.push(`${mode}(缺失)`);
+      errors.push(`SKILL 文件缺失: spec-driver-${mode}/SKILL.md`);
+      continue;
+    }
+    const actual = fs.readFileSync(p, 'utf-8');
+    let expected;
+    try {
+      expected = computeExpectedSkillContent(actual, templateText, anchor);
+    } catch (err) {
+      drifted.push(`${mode}(锚点错)`);
+      errors.push(`spec-driver-${mode}/SKILL.md: ${err.message}`);
+      continue;
+    }
+    if (actual !== expected) {
+      drifted.push(mode);
+      errors.push(`spec-driver-${mode}/SKILL.md delegation-contract 块与 template 漂移；运行 sync-delegation-contract.mjs --write`);
+    }
+  }
+  const status = drifted.length > 0 ? 'fail' : 'pass';
+  checks.push({
+    id: 'skill-block-sync',
+    title: '5 SKILL delegation-contract 块与单一源一致',
+    status,
+    evidence: { drifted },
+  });
+
+  // .codex 双层守护（codex Warning-4）：resume 原始事故正是 .codex 层 stale。
+  // 断言每个 .codex wrapper 内嵌的委派块与单一源一致——若 source 改了但未跑 repo:sync
+  // 再生 wrapper，这里 fail-loud（不依赖 codex-skills.sh 的 marker-only 校验）。
+  const expectedBlock = wrapWithMarkers(extractCanonicalBlock(templateText));
+  const codexDrifted = [];
+  for (const mode of Object.keys(SKILL_ANCHORS)) {
+    const cp = codexWrapperPath(root, mode);
+    if (!fs.existsSync(cp)) {
+      codexDrifted.push(`${mode}(缺失)`);
+      errors.push(`.codex wrapper 缺失: .codex/skills/spec-driver-${mode}/SKILL.md`);
+      continue;
+    }
+    if (!fs.readFileSync(cp, 'utf-8').includes(expectedBlock)) {
+      codexDrifted.push(mode);
+      errors.push(`.codex/skills/spec-driver-${mode}/SKILL.md 未含最新委派块（stale wrapper）；运行 npm run repo:sync 再生`);
+    }
+  }
+  const codexStatus = codexDrifted.length > 0 ? 'fail' : 'pass';
+  checks.push({
+    id: 'codex-wrapper-block-sync',
+    title: '5 .codex wrapper 委派块与单一源一致',
+    status: codexStatus,
+    evidence: { codexDrifted },
+  });
+
+  return { status: status === 'fail' || codexStatus === 'fail' ? 'fail' : 'pass', checks, warnings: [], errors };
+}
+
+/**
+ * 程序化写入（repo:sync 复用）：按 template 重新注入 5 SKILL 的 delegation-contract 块。
+ * 返回 { written: string[] }。
+ */
+export function syncDelegationContract({ projectRoot } = {}) {
+  const { pluginDir, templatePath } = resolvePaths(projectRoot);
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`[sync-delegation-contract] template 不存在: ${templatePath}`);
+  }
+  const templateText = fs.readFileSync(templatePath, 'utf-8');
+  const written = [];
+  for (const [mode, anchor] of Object.entries(SKILL_ANCHORS)) {
+    const p = skillPath(pluginDir, mode);
+    if (!fs.existsSync(p)) throw new Error(`[sync-delegation-contract] SKILL 文件不存在: ${p}`);
+    const actual = fs.readFileSync(p, 'utf-8');
+    const expected = computeExpectedSkillContent(actual, templateText, anchor);
+    if (actual !== expected) { fs.writeFileSync(p, expected, 'utf-8'); written.push(mode); }
+  }
+  return { written };
+}
+
+function run(mode) {
+  if (mode === 'check') {
+    const result = validateDelegationContract({});
+    if (result.errors.length > 0) {
+      result.errors.forEach((e) => console.error(`[sync-delegation-contract] ${e}`));
+      console.error('  运行 `node plugins/spec-driver/scripts/sync-delegation-contract.mjs --write` 重新同步');
+      process.exit(1);
+    }
+    console.log('[sync-delegation-contract] 无漂移 ✅');
+    return;
+  }
+  const { written } = syncDelegationContract({});
+  written.forEach((m) => console.log(`[sync-delegation-contract] 已更新 spec-driver-${m}/SKILL.md`));
+  console.log(`[sync-delegation-contract] 完成（更新 ${written.length} 个 SKILL 文件）`);
+  if (written.length > 0) {
+    console.log('[sync-delegation-contract] ⚠️ .codex wrapper 未在此步再生；跑 `npm run repo:sync` 同步双层（--check 含 .codex 校验）');
+  }
+}
+
+// 显式 re-export 供测试直接消费（避免测试重复 import lib）
+export { extractCanonicalBlock, wrapWithMarkers, computeExpectedSkillContent, BEGIN_MARKER, END_MARKER };
+
+const isCliEntry = process.argv[1] != null
+  && path.resolve(process.argv[1]).endsWith('sync-delegation-contract.mjs');
+if (isCliEntry) {
+  const cliMode = process.argv.includes('--check') ? 'check' : 'write';
+  run(cliMode);
+}

package/plugins/spec-driver/scripts/validate-orchestrator-models.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * validate-orchestrator-models — 断言 5 个主编排器 SKILL 的双层 frontmatter `model: opus`。
+ *
+ * 显式 allowlist（不要用"任何含 Task 的 SKILL"）：fix/story/feature/implement/resume。
+ * sync/doc 也委派子代理但设计上保持 sonnet（轻编排器），全量断言会误伤。
+ *
+ * 校验双层：
+ *   - plugins/spec-driver/skills/spec-driver-<m>/SKILL.md
+ *   - .codex/skills/spec-driver-<m>/SKILL.md
+ * 任一层 model ≠ opus → status fail + error 明示哪个文件哪层。
+ *
+ * 背景：F176 实测 sonnet 编排器无视委派硬约束；6281a27 sonnet→opus 漂移多时无人发现的根因
+ * 是 frontmatter model 不在任何 contract/check 管辖——本断言机制化守护。
+ *
+ * 退出码：0 = 全 opus；1 = 检测到非 opus。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_DIR = path.resolve(__dirname, '..');
+
+/** 显式 allowlist：仅这 5 个主编排器要求 opus。 */
+const ORCHESTRATOR_MODES = ['fix', 'story', 'feature', 'implement', 'resume'];
+
+/**
+ * 已记录的豁免：在 allowed-tools 声明了 Task（具备委派能力）但**不**纳入 F185 opus 硬断言的 mode。
+ * key = mode，value = 豁免理由（fail-loud 时回显，杜绝"无说明的漏网"，对应 codex Warning-3）。
+ * - refactor：已是 opus 且委派 batch implement，但 F185 硬约束块注入范围限定 5 个核心模式；
+ *   refactor 委派契约纳入视后续 milestone（当前已 opus，无 model 漂移风险）。
+ * 注：sync / doc 的 allowed-tools **不含 Task**（无委派能力），天然不进入此覆盖断言。
+ */
+const DOCUMENTED_EXCEPTIONS = {
+  refactor: 'F185 硬约束范围限定 5 核心模式；refactor 已 opus，委派契约纳入视后续',
+};
+
+/**
+ * 动态枚举全部 SKILL 目录 mode（去 spec-driver- 前缀）。
+ * 不用硬编码列表（codex Warning：新增 skill 目录若漏更新列表，coverage 守护对其失效）。
+ */
+function listAllModes(root) {
+  const skillsDir = path.join(root, 'plugins/spec-driver/skills');
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && d.name.startsWith('spec-driver-'))
+    .map((d) => d.name.slice('spec-driver-'.length));
+}
+
+/** 判断某 mode 的 plugins 层 SKILL 是否在 allowed-tools 声明了 Task（即具备委派能力）。 */
+function declaresTaskTool(root, mode) {
+  const p = path.join(root, 'plugins/spec-driver/skills', `spec-driver-${mode}`, 'SKILL.md');
+  if (!fs.existsSync(p)) return false;
+  const fm = String(fs.readFileSync(p, 'utf-8')).match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return false;
+  const at = fm[1].match(/^allowed-tools:\s*\[(.*)\]/m);
+  return at ? /\bTask\b/.test(at[1]) : false;
+}
+
+/** 从 SKILL.md frontmatter 解析 `model:` 值（仅 frontmatter 首块内）。 */
+function parseFrontmatterModel(skillText) {
+  const text = String(skillText ?? '');
+  // 仅匹配文件开头 --- ... --- 之间的 frontmatter
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const m = fm[1].match(/^model:\s*(\S+)\s*$/m);
+  return m ? m[1] : null;
+}
+
+function resolveRoot(projectRoot) {
+  return projectRoot ? path.resolve(projectRoot) : path.resolve(PLUGIN_DIR, '../..');
+}
+
+/** 返回某 mode 的双层 SKILL 路径（plugins + .codex）。 */
+function layerPaths(root, mode) {
+  return [
+    {
+      layer: 'plugins',
+      path: path.join(root, 'plugins/spec-driver/skills', `spec-driver-${mode}`, 'SKILL.md'),
+    },
+    {
+      layer: '.codex',
+      path: path.join(root, '.codex/skills', `spec-driver-${mode}`, 'SKILL.md'),
+    },
+  ];
+}
+
+/**
+ * 供 repo:check（repo-maintenance-core）复用的 model 断言：
+ * 返回 { status, checks, warnings, errors }，与 aggregateValidation 契约一致。
+ * check id 形如 `orchestrator-model-<m>`。
+ */
+export function validateOrchestratorModels({ projectRoot } = {}) {
+  const root = resolveRoot(projectRoot);
+  const errors = [];
+  const checks = [];
+
+  for (const mode of ORCHESTRATOR_MODES) {
+    const offenders = [];
+    for (const { layer, path: p } of layerPaths(root, mode)) {
+      if (!fs.existsSync(p)) {
+        offenders.push(`${layer}(缺失)`);
+        errors.push(`spec-driver-${mode} ${layer} 层 SKILL.md 缺失: ${path.relative(root, p)}`);
+        continue;
+      }
+      const model = parseFrontmatterModel(fs.readFileSync(p, 'utf-8'));
+      if (model !== 'opus') {
+        offenders.push(`${layer}=${model ?? '未声明'}`);
+        errors.push(`spec-driver-${mode} ${layer} 层 frontmatter model=${model ?? '未声明'}，要求 opus（${path.relative(root, p)}）`);
+      }
+    }
+    checks.push({
+      id: `orchestrator-model-${mode}`,
+      title: `spec-driver-${mode} 双层 frontmatter model=opus`,
+      status: offenders.length > 0 ? 'fail' : 'pass',
+      evidence: { offenders },
+    });
+  }
+
+  // 覆盖断言（codex Warning-3）：任何在 allowed-tools 声明 Task 的 mode，必须要么在
+  // opus-allowlist，要么在已记录豁免里——杜绝未来新增委派 SKILL 静默漏出硬约束管辖。
+  const classified = new Set([...ORCHESTRATOR_MODES, ...Object.keys(DOCUMENTED_EXCEPTIONS)]);
+  const unclassified = listAllModes(root).filter((m) => declaresTaskTool(root, m) && !classified.has(m));
+  for (const m of unclassified) {
+    errors.push(`spec-driver-${m} 在 allowed-tools 声明了 Task（具备委派能力）但未分类：需加入 ORCHESTRATOR_MODES（要求 opus）或 DOCUMENTED_EXCEPTIONS（注明理由）`);
+  }
+  checks.push({
+    id: 'orchestrator-task-coverage',
+    title: '所有含 Task 委派的 SKILL 均已分类（allowlist 或已记录豁免）',
+    status: unclassified.length > 0 ? 'fail' : 'pass',
+    evidence: { unclassified, exceptions: Object.keys(DOCUMENTED_EXCEPTIONS) },
+  });
+
+  return {
+    status: errors.length > 0 ? 'fail' : 'pass',
+    checks,
+    warnings: [],
+    errors,
+  };
+}
+
+function run() {
+  const result = validateOrchestratorModels({});
+  if (result.errors.length > 0) {
+    result.errors.forEach((e) => console.error(`[validate-orchestrator-models] ${e}`));
+    process.exit(1);
+  }
+  console.log('[validate-orchestrator-models] 5 编排器双层 model=opus ✅');
+}
+
+const isCliEntry = process.argv[1] != null
+  && path.resolve(process.argv[1]).endsWith('validate-orchestrator-models.mjs');
+if (isCliEntry) {
+  run();
+}

package/plugins/spec-driver/scripts/validate-wrapper-sources.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYamlDocument } from './lib/simple-yaml.mjs';
+import { computeWrapperBodySha256 } from './lib/extract-wrapper-body.mjs';
 
 function parseArgs(argv) {
   const options = {
@@ -69,6 +70,9 @@ function validateWrapperMarkers(projectRoot, entries, errors) {
   const checked = [];
   const missingFiles = [];
   const invalidMarkers = [];
+  // F186 T2：wrapper body sha256 漂移检测
+  const shaMismatches = [];
+  const missingSha = [];
 
   for (const entry of entries) {
     const targetPath = path.resolve(projectRoot, entry.target);
@@ -96,6 +100,25 @@ function validateWrapperMarkers(projectRoot, entries, errors) {
       continue;
     }
 
+    // F186 T2：解析 wrapper 内嵌的 Source SHA256，对 source 用同一 helper 重算比对。
+    // 缺 `Source SHA256:` 行 → fail（FINAL CRITICAL-2：缺 sha 即视为漂移/被手改，不是 warn）。
+    const shaMatch = content.match(/^- Source SHA256:\s*([0-9a-f]{64})\s*$/m);
+    if (!shaMatch) {
+      missingSha.push(entry.target);
+      continue;
+    }
+    const sourcePath = path.resolve(projectRoot, entry.source);
+    if (!fs.existsSync(sourcePath)) {
+      // source 缺失由 source-skills check 单独报；此处不重复，但 sha 无法校验 → 视为不通过
+      shaMismatches.push({ target: entry.target, expected: shaMatch[1], actual: '<source-missing>' });
+      continue;
+    }
+    const actualSha = computeWrapperBodySha256(sourcePath);
+    if (actualSha !== shaMatch[1]) {
+      shaMismatches.push({ target: entry.target, expected: shaMatch[1], actual: actualSha });
+      continue;
+    }
+
     checked.push(entry.target);
   }
 
@@ -113,14 +136,36 @@ function validateWrapperMarkers(projectRoot, entries, errors) {
     );
   }
 
+  if (missingSha.length > 0) {
+    errors.push(
+      `以下 Codex 包装技能缺少 \`Source SHA256:\` 行（疑似漂移/被手改，请重新运行 npm run codex:spec-driver:install）：${missingSha.join(', ')}`,
+    );
+  }
+
+  if (shaMismatches.length > 0) {
+    errors.push(
+      `以下 Codex 包装技能 body sha256 不匹配（source 已变更但 wrapper 未重生成）：${shaMismatches
+        .map((item) => `${item.target}（期望 ${item.expected.slice(0, 12)}…，实际 ${item.actual.slice(0, 12)}…）`)
+        .join(', ')}`,
+    );
+  }
+
+  const ok =
+    missingFiles.length === 0 &&
+    invalidMarkers.length === 0 &&
+    missingSha.length === 0 &&
+    shaMismatches.length === 0;
+
   return createCheck(
     'codex-wrapper-markers',
     'Codex 包装技能 source-of-truth 标记',
-    missingFiles.length === 0 && invalidMarkers.length === 0 ? 'pass' : 'fail',
+    ok ? 'pass' : 'fail',
     {
       checkedCount: checked.length,
       missingFiles,
       invalidMarkers,
+      missingSha,
+      shaMismatches,
     },
   );
 }