sillyspec 3.27.11 → 3.28.0

package/.worktrees/542c4415/src/machine-interface.js

@@ -1,543 +0,0 @@
-/**
- * Machine Interface v1 — 机器接口层（SillyHub driver 模式地基）
- *
- * 把 SillySpec 既有的门控与事实核验从「埋在 run <stage> --done 人类可读输出流里」
- * 抽象成可被程序化消费的统一 JSON envelope + 退出码契约。
- *
- * 设计原则（见 change 2026-07-09-machine-interface-v1 design.md §2/§3）：
- *   - 方案 B：独立模块单点封装，不污染既有 run/progress 输出
- *   - 只聚合不新增校验：复用 stage-contract / task-review / verify-postcheck 既有策略引擎
- *   - 只读语义边界（D-002@v1）：只调 ProgressManager 读路径，不写 sillyspec.db
- *   - stdout 纯 JSON（D-005@v1）：--json 模式下由 CLI 层（src/index.js 的 withJsonOutput）
- *     在调用 runGate/runDerive 期间劫持 console.log 到 stderr，防被调模块污染机器输出
- *   - 退出码 0/1/2 三段语义（D-004@v1）：0=通过，1=事实阻断，2=无法核验
- *
- * 仅依赖 Node 18+ 原生 API，零新增外部依赖。
- */
-
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { ProgressManager, resolveSpecDir } from './progress.js';
-import { resolveRuntimeRoot } from './run/shared.js';
-import { runValidators, checkTransition, checkExecuteCodeEvidence } from './stage-contract.js';
-import { validateTaskReviews, resolveLatestExecuteRunId } from './task-review.js';
-import { runVerifyTestCheck } from './verify-postcheck.js';
-
-// ============ 退出码常量（D-004@v1）============
-
-export const EXIT_OK = 0;          // 核验通过（可含 warnings）
-export const EXIT_BLOCKED = 1;     // 事实性阻断（JSON 含 errors）
-export const EXIT_UNKNOWN = 2;     // 无法核验（用法错/变更不存在/环境错/内部异常）
-
-// ============ envelope schema 版本（D-005@v1）============
-
-export const SCHEMA_VERSION = 1;
-
-// ============ envelope 组装 ============
-
-/**
- * 组装统一的 JSON envelope。
- *
- * 顶层固定字段：schema_version / command / change / ok / errors / warnings / generated_at。
- * stage / facet / checks / data 仅在显式传参（!== undefined）时出现——保持 envelope 紧凑，
- * daemon 可只看顶层 ok/errors/warnings。
- *
- * @param {object} fields
- * @param {string|undefined} [fields.command]
- * @param {string|undefined} [fields.stage]
- * @param {string|undefined} [fields.facet]
- * @param {string|undefined} [fields.change]
- * @param {boolean} fields.ok
- * @param {string[]} [fields.errors=[]]
- * @param {string[]} [fields.warnings=[]]
- * @param {Array<object>|undefined} [fields.checks]
- * @param {object|undefined} [fields.data]
- * @returns {object} 可直接 JSON.stringify 的 envelope 对象
- */
-export function buildEnvelope({
-  command,
-  stage,
-  facet,
-  change,
-  ok,
-  errors = [],
-  warnings = [],
-  checks,
-  data,
-}) {
-  const envelope = {
-    schema_version: SCHEMA_VERSION,
-    command,
-    change,
-    ok,
-    errors,
-    warnings,
-    generated_at: new Date().toISOString(),
-  };
-
-  // 按需字段：仅当显式传参时挂上，避免空 null 污染
-  if (stage !== undefined) envelope.stage = stage;
-  if (facet !== undefined) envelope.facet = facet;
-  if (checks !== undefined) envelope.checks = checks;
-  if (data !== undefined) envelope.data = data;
-
-  return envelope;
-}
-
-// ============ 输出纪律（design §8）============
-// --json 模式的 stdout 劫持（console.log/info → stderr）由 CLI 层 src/index.js 的
-// withJsonOutput 在调用 runGate/runDerive 期间统一处理（覆盖整个调用期，非仅输出瞬间）。
-// 本模块只返回 { envelope, exitCode }，不直接写 stdout。
-
-// ============ gate 聚合门控 ============
-
-/**
- * 聚合「变更 <changeName> 的 <stage> 阶段此刻能否被标记完成」的综合结论。
- *
- * 只读：仅调 ProgressManager.read，不写状态（D-002@v1）。
- * 只聚合：每个 check 复用既有策略引擎，不在本模块重写校验逻辑（design §2）。
- *
- * @param {string} stage - 目标阶段（brainstorm/plan/execute/verify/...）
- * @param {string} changeName - 变更名
- * @param {object} opts
- * @param {string} opts.cwd - 项目根目录
- * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
- * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 resolveRuntimeRoot 三级优先级解析
- * @param {string} [opts.specDriftAnchor] - drift 场景主仓 specBase 锚点（坑 execute-runs-isolation）。
- *   drift 守卫命中时由调用方传入，task-reviews 的 execute-run-id marker 落点经
- *   resolveRuntimeRoot 锚主仓 .runtime，不读 worktree 副本（与 contract-matrix 调用方同语义）。
- * @param {object} [opts.ctx] - MultiRepoContext 单例（W3 task-09，D-013）。缺省=null 退化单仓。
- *   透传给 validateTaskReviews（execute task-reviews check）+ runVerifyTestCheck（verify-test check），
- *   让两函数按 ctx 切跨仓 gitDir / per-repo cwd。null 时两函数按既有单仓行为零回归。
- * @returns {Promise<{ envelope: object, exitCode: number }>}
- */
-export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null } = {}) {
-  const specRoot = specBase || resolveSpecDir(cwd);
-  // A4：pm 用 specRoot（而非默认 resolveSpecDir(cwd)）——--spec-dir/平台模式下 specBase 是真实
-  // specDir，默认解析会指向本地孤儿库，与下方 planContent/changeDir 的 specRoot 两套事实源混拼。
-  const pm = new ProgressManager({ specDir: specRoot });
-
-  try {
-    // ── 只读契约守卫（D-002@v1）：db 不存在时 fail-closed 返回 exit 2，不触发建库落盘 ──
-    // pm.read → _ensureDB → db.init() 在 db 不存在/schema 戳落后时会 _createSchema + _save 落盘
-    // （db.js:init），这会让一个声明只读的查询命令在 spec 目录凭空建 sillyspec.db，违反只读契约。
-    // db 还没建 = 该变更从未跑过流程，无从核验 → 显式返回「无法核验」而非建库。
-    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
-    if (!existsSync(dbPath)) {
-      const envelope = buildEnvelope({
-        command: 'gate',
-        stage,
-        change: changeName,
-        ok: false,
-        errors: [`无法核验：进度库不存在（${dbPath}）——变更 ${changeName} 尚未运行过任何阶段，只读 gate 不会为其建库`],
-      });
-      return { envelope, exitCode: EXIT_UNKNOWN };
-    }
-
-    // ── 读进度：变更不存在 → exit 2（D-004@v1）──
-    const progress = pm.read(cwd, changeName);
-    if (!progress) {
-      const envelope = buildEnvelope({
-        command: 'gate',
-        stage,
-        change: changeName,
-        ok: false,
-        errors: [`变更不存在: ${changeName}`],
-      });
-      return { envelope, exitCode: EXIT_UNKNOWN };
-    }
-
-    const currentStage = progress.currentStage || '';
-    const checks = [];
-
-    // W4-G (D-008)：execute 阶段预计算 code evidence 一次，供 artifacts check（经 runValidators
-    // → validateExecuteOutputs）与下方 execute-evidence check 共享——避免各调一次 checkExecuteCodeEvidence
-    // 各 spawn 2 个 git 进程（gate execute 一次省 ≈ 60-200ms on Windows）。
-    const sharedEvidence = stage === 'execute' ? checkExecuteCodeEvidence(cwd, changeName) : undefined;
-
-    // ── a. artifacts：阶段产物校验（全部阶段）──
-    const r = runValidators(stage, cwd, changeName, {
-      projectName: progress.project,
-      specRoot,
-      ...(sharedEvidence ? { evidence: sharedEvidence } : {}),
-    });
-    checks.push({
-      id: 'artifacts',
-      ok: r.ok,
-      errors: r.errors || [],
-      warnings: r.warnings || [],
-    });
-
-    // ── b. transition：状态转换合法性（参与综合 ok，与 completeStep 硬阻断一致）──
-    // 与 run.js runStage 同源：传 fromStageData 触发 failed_post_check 门控。
-    // transition 必须参与 ok：否则 gate 返回 ok=true、exit 0，Agent 据此 --done 却被
-    // runStage 的 checkTransition 硬阻断（exit 1），gate/run 判定分裂（design §8 漂移）。
-    const fromStageData = (progress.stages && currentStage && progress.stages[currentStage]) || undefined;
-    const t = checkTransition(currentStage, stage, fromStageData ? { fromStageData } : {});
-    checks.push({
-      id: 'transition',
-      ok: t.allowed,
-      errors: t.allowed ? [] : [t.reason].filter(Boolean),
-      warnings: [],
-    });
-
-    // ── c. execute 阶段追加 execute-evidence + task-reviews ──
-    // D-008 + W4-G：checkExecuteCodeEvidence 整个 runGate 只调一次（顶部 sharedEvidence 预计算），
-    // 这里复用——真正落实去重（原注释声称"只调一次"但实现里 execute-evidence check 仍重复调了第二次）。
-    if (stage === 'execute') {
-      const ev = sharedEvidence;
-      checks.push({
-        id: 'execute-evidence',
-        ok: ev.status !== 'unchanged',
-        errors: ev.status === 'unchanged' ? [`base..head 无代码变更: ${ev.detail}`] : [],
-        warnings: ev.status === 'unknown' ? [`无法判定代码变更: ${ev.detail}`] : [],
-        data: { status: ev.status, detail: ev.detail },
-      });
-
-      // task-reviews：参数组装照抄 run.js:3223-3249 现成范式
-      const planDir = join(specRoot, 'changes', changeName);
-      const planPath = join(planDir, 'plan.md');
-      let planContent = '';
-      if (existsSync(planPath)) {
-        try {
-          planContent = readFileSync(planPath, 'utf8');
-        } catch {
-          planContent = '';
-        }
-      }
-
-      // drift 场景经 resolveRuntimeRoot 三级优先级解析（runtimeRoot > specDriftAnchor > 本地兜底），
-      // 锚主仓 .runtime，不读 worktree 副本（坑 execute-runs-isolation，与 contract-matrix 调用方同语义）
-      const rtRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot);
-      // marker 缺失/为空时先扫描 execute-runs/ 找回真实 runId（与 gates.js #6 同源），
-      // 避免拿 '' 进 validateTaskReviews 拼出 execute-runs//tasks/... 产出全量误导 errors。
-      let executeRunId = '';
-      try {
-        executeRunId = resolveLatestExecuteRunId({ runtimeRoot: rtRoot, changeName }) || '';
-      } catch {
-        executeRunId = '';
-      }
-
-      // git 真实性交叉校验目录：worktree 存在用 worktreePath，否则 null（交由 task-review 降级 warning）
-      let gitDir = null;
-      try {
-        const { WorktreeManager } = await import('./worktree.js');
-        const wm = new WorktreeManager({ cwd });
-        const meta = wm.getMeta(changeName);
-        if (meta?.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
-          gitDir = meta.worktreePath;
-        }
-      } catch {
-        gitDir = null;
-      }
-
-      const tr = validateTaskReviews({
-        planContent,
-        runtimeRoot: rtRoot,
-        executeRunId,
-        changeDir: planDir,
-        gitDir,
-        ctx,
-      });
-      checks.push({
-        id: 'task-reviews',
-        ok: tr.ok,
-        errors: tr.errors || [],
-        warnings: tr.warnings || [],
-      });
-    }
-
-    // ── d. verify 阶段追加 verify-test（CLI 实测 local.yaml commands.test）──
-    if (stage === 'verify') {
-      const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx });
-      const vtWarnings = [];
-      if (vt.status === 'skipped') {
-        vtWarnings.push(`⚠️ verify-test SKIPPED — gate 未核验测试（${vt.reason || 'local.yaml 未配置 commands.test 或显式无测试'}）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL`);
-      }
-      // known_failures 豁免披露：本次 PASS 含豁免，driver 应提示人工复核清单是否过宽
-      if (vt.exemptedCount > 0) {
-        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）`);
-      }
-      // 全量 fallback 明示：跑了全量 commands.test 但非变更范围子集，失败可能含未变更
-      // 模块的预存错误——driver 不应据 exit 0 判定本次变更范围已客观测试（见 3.24 verify 坑1）。
-      if (vt.status !== 'skipped' && vt.mode === 'full' && vt.fallbackReason) {
-        vtWarnings.push(`⚠️ verify-test 跑的是全量 commands.test（${vt.fallbackReason}）；失败可能含未变更模块的预存错误，driver 不应据 exit 0 判定本次变更范围已测`);
-      }
-      checks.push({
-        id: 'verify-test',
-        ok: vt.status !== 'failed',
-        errors: vt.status === 'failed' ? [`测试失败: ${vt.reason || ''}`] : [],
-        warnings: vtWarnings,
-        data: {
-          status: vt.status,
-          exitCode: vt.exitCode,
-          durationMs: vt.durationMs,
-          resultPath: vt.resultPath,
-          mode: vt.mode ?? null,
-          fallbackReason: vt.fallbackReason ?? null,
-        },
-      });
-    }
-
-    // ── 综合结论：所有非 informational check 均 ok ──
-    const ok = checks.filter((c) => !c.informational).every((c) => c.ok);
-    const exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
-
-    const errors = [];
-    const warnings = [];
-    for (const c of checks) {
-      if (c.errors && c.errors.length) errors.push(...c.errors);
-      if (c.warnings && c.warnings.length) warnings.push(...c.warnings);
-    }
-
-    const envelope = buildEnvelope({
-      command: 'gate',
-      stage,
-      change: changeName,
-      ok,
-      errors,
-      warnings,
-      checks,
-    });
-
-    return { envelope, exitCode };
-  } catch (e) {
-    // 内部异常兜底（D-004@v1 / design §3.5）：保证 stdout 永远是合法 JSON 结构，exit 2
-    const envelope = buildEnvelope({
-      command: 'gate',
-      stage,
-      change: changeName,
-      ok: false,
-      errors: [`internal: ${e.message}`],
-    });
-    return { envelope, exitCode: EXIT_UNKNOWN };
-  }
-}
-
-// ============ derive 单项事实核验 ============
-
-/**
- * facet 枚举（D-003@v1）。machine 接口对外只接受这四个值。
- */
-export const FACETS = ['execute-evidence', 'verify-test', 'task-reviews', 'artifacts'];
-
-/**
- * 单项事实核验：针对变更 <changeName> 查询某一 facet 的真实状态（design §3.2）。
- *
- * 与 gate 的差异：gate 聚合某阶段所有 check 的综合结论；derive 只返回单一 facet 的结构化 data，
- * daemon 用来做细粒度事实采集（如轮询 execute-evidence 判断代码是否变更）。
- *
- * 只读语义边界同 gate（D-002@v1）：仅调 ProgressManager.read，不写 sillyspec.db。
- * 唯一例外是 verify-test 会真实执行测试并落盘 test-result.json（产物取证，非状态写入，design §3.3）。
- *
- * 退出码语义（D-004@v1）：0=事实通过，1=事实性阻断，2=无法核验（用法错/变更不存在/内部异常）。
- *
- * @param {string} facet - 必须 ∈ FACETS
- * @param {string} changeName - 变更名
- * @param {object} opts
- * @param {string} opts.cwd - 项目根目录
- * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
- * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 resolveRuntimeRoot 三级优先级解析
- * @param {string} [opts.specDriftAnchor] - drift 场景主仓 specBase 锚点（坑 execute-runs-isolation），
- *   task-reviews facet 的 execute-run-id marker 落点经 resolveRuntimeRoot 锚主仓 .runtime，不读副本。
- * @param {object} [opts.ctx] - MultiRepoContext 单例（W3 task-09，D-013）。缺省=null 退化单仓。
- *   透传给 verify-test / task-reviews facet（runVerifyTestCheck + validateTaskReviews）。
- * @returns {Promise<{ envelope: object, exitCode: number }>}
- */
-export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null } = {}) {
-  // ── 非法 facet：用法错 → exit 2（D-004@v1）──
-  if (!FACETS.includes(facet)) {
-    const envelope = buildEnvelope({
-      command: 'derive',
-      facet,
-      change: changeName,
-      ok: false,
-      errors: [`非法 facet: ${facet}，合法值: ${FACETS.join(', ')}`],
-    });
-    return { envelope, exitCode: EXIT_UNKNOWN };
-  }
-
-  const specRoot = specBase || resolveSpecDir(cwd);
-  // A4：同 runGate——pm 用 specRoot 统一事实源，平台/--spec-dir 模式不读本地孤儿库。
-  const pm = new ProgressManager({ specDir: specRoot });
-
-  try {
-    // ── 只读契约守卫（D-002@v1，同 runGate）：db 不存在时 fail-closed 返回 exit 2，不建库落盘 ──
-    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
-    if (!existsSync(dbPath)) {
-      const envelope = buildEnvelope({
-        command: 'derive',
-        facet,
-        change: changeName,
-        ok: false,
-        errors: [`无法核验：进度库不存在（${dbPath}）——变更 ${changeName} 尚未运行过任何阶段，只读 derive 不会为其建库`],
-      });
-      return { envelope, exitCode: EXIT_UNKNOWN };
-    }
-
-    // ── 读进度：变更不存在 → exit 2 ──
-    const progress = pm.read(cwd, changeName);
-    if (!progress) {
-      const envelope = buildEnvelope({
-        command: 'derive',
-        facet,
-        change: changeName,
-        ok: false,
-        errors: [`变更不存在: ${changeName}`],
-      });
-      return { envelope, exitCode: EXIT_UNKNOWN };
-    }
-
-    const currentStage = progress.currentStage || '';
-
-    let data;
-    let ok;
-    let errors = [];
-    let warnings = [];
-    let exitCode;
-
-    switch (facet) {
-      // ── a. execute-evidence：base..head 代码变更判定 ──
-      // 语义与 validateExecuteOutputs 一致：unknown 不等于失败（无法判定不应阻断）。
-      case 'execute-evidence': {
-        const ev = checkExecuteCodeEvidence(cwd, changeName);
-        data = { status: ev.status, detail: ev.detail };
-        ok = ev.status !== 'unchanged';
-        errors = ev.status === 'unchanged' ? [`base..head 无代码变更: ${ev.detail}`] : [];
-        warnings = ev.status === 'unknown' ? [`无法判定代码变更: ${ev.detail}`] : [];
-        exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
-        break;
-      }
-
-      // ── b. verify-test：真实执行测试命令并取证 ──
-      case 'verify-test': {
-        const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx });
-        data = {
-          status: vt.status,
-          exitCode: vt.exitCode,
-          durationMs: vt.durationMs,
-          resultPath: vt.resultPath,
-          mode: vt.mode ?? null,
-          fallbackReason: vt.fallbackReason ?? null,
-        };
-        ok = vt.status !== 'failed';
-        errors = vt.status === 'failed' ? [`测试失败: ${vt.reason || ''}`] : [];
-        warnings = vt.status === 'skipped'
-          ? ['测试被跳过']
-          : (vt.mode === 'full' && vt.fallbackReason)
-            ? [`⚠️ verify-test 跑的是全量 commands.test（${vt.fallbackReason}）；失败可能含未变更模块的预存错误`]
-            : [];
-        exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
-        break;
-      }
-
-      // ── c. task-reviews：plan 任务评审核验（参数组装照抄 runGate execute 段）──
-      case 'task-reviews': {
-        const changeDir = join(specRoot, 'changes', changeName);
-        const planPath = join(changeDir, 'plan.md');
-        let planContent = '';
-        if (existsSync(planPath)) {
-          try {
-            planContent = readFileSync(planPath, 'utf8');
-          } catch {
-            planContent = '';
-          }
-        }
-
-        // drift 场景经 resolveRuntimeRoot 三级优先级解析（同 runGate execute 段），锚主仓 .runtime 不读副本
-        const rtRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot);
-        // marker 缺失/为空时先扫描 execute-runs/ 找回真实 runId（同 runGate execute 段），避免拿 '' 误导校验
-        let executeRunId = '';
-        try {
-          executeRunId = resolveLatestExecuteRunId({ runtimeRoot: rtRoot, changeName }) || '';
-        } catch {
-          executeRunId = '';
-        }
-
-        // git 真实性交叉校验目录：worktree 存在用 worktreePath，否则 null（交由 task-review 降级 warning）
-        let gitDir = null;
-        try {
-          const { WorktreeManager } = await import('./worktree.js');
-          const wm = new WorktreeManager({ cwd });
-          const meta = wm.getMeta(changeName);
-          if (meta?.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
-            gitDir = meta.worktreePath;
-          }
-        } catch {
-          gitDir = null;
-        }
-
-        const tr = validateTaskReviews({
-          planContent,
-          runtimeRoot: rtRoot,
-          executeRunId,
-          changeDir,
-          gitDir,
-          ctx,
-        });
-        data = {
-          ok: tr.ok,
-          errors: tr.errors,
-          warnings: tr.warnings,
-          requiredEvidence: tr.requiredEvidence,
-        };
-        ok = tr.ok;
-        errors = tr.errors || [];
-        warnings = tr.warnings || [];
-        exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
-        break;
-      }
-
-      // ── d. artifacts：当前阶段产物校验 ──
-      // runValidators 需要 stage：用 progress.currentStage（若为空串则校验器内部处理）。
-      case 'artifacts': {
-        const r = runValidators(currentStage, cwd, changeName, {
-          projectName: progress.project,
-          specRoot,
-        });
-        data = { ok: r.ok, errors: r.errors, warnings: r.warnings };
-        ok = r.ok;
-        errors = r.errors || [];
-        warnings = r.warnings || [];
-        exitCode = ok ? EXIT_OK : EXIT_BLOCKED;
-        break;
-      }
-
-      // 不可达：facet 已在入口白名单校验
-      default: {
-        const envelope = buildEnvelope({
-          command: 'derive',
-          facet,
-          change: changeName,
-          ok: false,
-          errors: [`非法 facet: ${facet}，合法值: ${FACETS.join(', ')}`],
-        });
-        return { envelope, exitCode: EXIT_UNKNOWN };
-      }
-    }
-
-    // stage 仅 artifacts 时出现（产物校验绑定阶段语义）；其余 facet 不传 stage。
-    const envelope = buildEnvelope({
-      command: 'derive',
-      facet,
-      change: changeName,
-      ok,
-      errors,
-      warnings,
-      data,
-      stage: facet === 'artifacts' ? currentStage : undefined,
-    });
-
-    return { envelope, exitCode };
-  } catch (e) {
-    // 内部异常兜底（D-004@v1 / design §3.5）：保证 stdout 永远是合法 JSON 结构，exit 2
-    const envelope = buildEnvelope({
-      command: 'derive',
-      facet,
-      change: changeName,
-      ok: false,
-      errors: [`internal: ${e.message}`],
-    });
-    return { envelope, exitCode: EXIT_UNKNOWN };
-  }
-}

package/.worktrees/542c4415/src/migrate.js

@@ -1,127 +0,0 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync, statSync, cpSync } from 'fs';
-import { basename, join, resolve } from 'path';
-import chalk from 'chalk';
-
-/**
- * Migrate old .sillyspec/ structure to unified .sillyspec/docs/<project>/ structure
- * @param {string} projectDir - Path to the project directory
- */
-export function migrateDocs(projectDir) {
-  const sillyspecDir = join(projectDir, '.sillyspec');
-  if (!existsSync(sillyspecDir)) {
-    console.error('❌ .sillyspec/ 目录不存在');
-    process.exit(1);
-  }
-
-  // Determine project name from projects/*.yaml or directory name
-  let projectName = basename(resolve(projectDir));
-  const projectsDir = join(sillyspecDir, 'projects');
-  if (existsSync(projectsDir)) {
-    const yamlFiles = readdirSync(projectsDir).filter(f => f.endsWith('.yaml'));
-    if (yamlFiles.length > 0) {
-      projectName = yamlFiles[0].replace('.yaml', '');
-    }
-  }
-
-  console.log(chalk.cyan(`📦 迁移项目: ${projectName}`));
-  console.log('');
-
-  const docsBase = join(sillyspecDir, 'docs', projectName);
-  let migrated = 0;
-
-  // 1. codebase/ → .sillyspec/docs/<project>/scan/
-  const codebaseDir = join(sillyspecDir, 'codebase');
-  if (existsSync(codebaseDir)) {
-    const targetDir = join(docsBase, 'scan');
-    mkdirSync(targetDir, { recursive: true });
-    const files = readdirSync(codebaseDir).filter(f => f.endsWith('.md'));
-    for (const file of files) {
-      const src = join(codebaseDir, file);
-      const dest = join(targetDir, file);
-      if (!existsSync(dest)) {
-        copyFileSync(src, dest);
-        console.log(chalk.green('  ✅') + ` scan/${file}`);
-        migrated++;
-      } else {
-        console.log(chalk.yellow('  ⏭️') + ` scan/${file} (已存在)`);
-      }
-    }
-  }
-
-  // 2. specs/ is deprecated — designs live in changes/<变更名>/design.md
-
-  // 3. changes/archive/ → .sillyspec/docs/<project>/archive/
-  const archiveDir = join(sillyspecDir, 'changes', 'archive');
-  if (existsSync(archiveDir)) {
-    const targetDir = join(docsBase, 'archive');
-    mkdirSync(targetDir, { recursive: true });
-    const entries = readdirSync(archiveDir);
-    for (const entry of entries) {
-      const src = join(archiveDir, entry);
-      const dest = join(targetDir, entry);
-      if (!existsSync(dest)) {
-        // 归档变更本身是目录（含 design.md 等），copyFileSync 对目录源抛 EISDIR；
-        // 按类型分发：目录用 cpSync 递归、文件用 copyFileSync，单条失败 try/catch 不中断整体迁移
-        try {
-          if (statSync(src).isDirectory()) {
-            cpSync(src, dest, { recursive: true });
-          } else {
-            copyFileSync(src, dest);
-          }
-          console.log(chalk.green('  ✅') + ` archive/${entry}`);
-          migrated++;
-        } catch (err) {
-          console.log(chalk.yellow('  ⚠️') + ` archive/${entry} 迁移失败: ${err.message}`);
-        }
-      } else {
-        console.log(chalk.yellow('  ⏭️') + ` archive/${entry} (已存在)`);
-      }
-    }
-  }
-
-  // 4. knowledge/ → .sillyspec/docs/<project>/archive/ (append knowledge files)
-  const knowledgeDir = join(sillyspecDir, 'knowledge');
-  if (existsSync(knowledgeDir)) {
-    const targetDir = join(docsBase, 'archive');
-    mkdirSync(targetDir, { recursive: true });
-    const files = readdirSync(knowledgeDir).filter(f => f.endsWith('.md'));
-    for (const file of files) {
-      const src = join(knowledgeDir, file);
-      const dest = join(targetDir, `knowledge-${file}`);
-      if (!existsSync(dest)) {
-        copyFileSync(src, dest);
-        console.log(chalk.green('  ✅') + ` archive/knowledge-${file}`);
-        migrated++;
-      } else {
-        console.log(chalk.yellow('  ⏭️') + ` archive/knowledge-${file} (已存在)`);
-      }
-    }
-  }
-
-  // 5. quicklog/ → .sillyspec/docs/<project>/quicklog/
-  const quicklogDir = join(sillyspecDir, 'quicklog');
-  if (existsSync(quicklogDir)) {
-    const targetDir = join(docsBase, 'quicklog');
-    mkdirSync(targetDir, { recursive: true });
-    const files = readdirSync(quicklogDir).filter(f => f.endsWith('.md'));
-    for (const file of files) {
-      const src = join(quicklogDir, file);
-      const dest = join(targetDir, file);
-      if (!existsSync(dest)) {
-        copyFileSync(src, dest);
-        console.log(chalk.green('  ✅') + ` quicklog/${file}`);
-        migrated++;
-      } else {
-        console.log(chalk.yellow('  ⏭️') + ` quicklog/${file} (已存在)`);
-      }
-    }
-  }
-
-  console.log('');
-  if (migrated > 0) {
-    console.log(chalk.green(`  ✅ 迁移完成，共迁移 ${migrated} 个文件`));
-    console.log(chalk.dim('  旧文件保留在原位，确认无误后可手动删除'));
-  } else {
-    console.log(chalk.yellow('  没有需要迁移的文件'));
-  }
-}