sillyspec 3.25.0 → 3.25.2

package/src/index.js

@@ -16,6 +16,8 @@ import { detectLocalYaml } from './local-detect.js';
 
 // ── CLI 入口 ──
 
+// did-you-mean 从 ./run/shared.js 复用（命令级 + flag 级 typo 建议）。
+import { didYouMean, assertSafeChangeName } from './run/shared.js'
 function printUsage() {
   console.log(`
 SillySpec CLI — 规范驱动开发工具包
@@ -73,11 +75,20 @@ SillySpec CLI — 规范驱动开发工具包
     doctor [--fix] [--stale-hours N]    健康检查 + 修复
 
   sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
+  sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
 
-  sillyspec workflow check <name> [--project <p>] [--change <c>] [--json]
+  sillyspec workflow check <name> [--project <p>] [--change <c>] [--json] [--save]
+                                      全局 workflow 校验（--save 归档到 .sillyspec/.runtime/workflow-runs/）
   sillyspec workflow list
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
+
+  sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
+    （无子命令）                       跑诊断，列出问题
+    --align-execute-progress [--change <名>] [--confirm]   基于 plan.md 对齐 execute 派生戳（默认 dry-run）
+    --cleanup-remnant [--confirm]      删除 0 字节空占位 db（默认 dry-run，仅 --confirm 落盘）
+    --dump-db --path <db 路径>         dump 指定 db 内容到文件（取证用）
+    --json                             结构化诊断 + 落盘 .sillyspec/.runtime/doctor-diagnosis.json
   sillyspec modules <rebuild | status | migrate>
   sillyspec change-rename <旧变更名> <新变更名>
   sillyspec knowledge <search --query "..." --limit N
@@ -175,6 +186,13 @@ async function main() {
     }
   }
 
+  // F3：--interactive（全局 flag，被上面吞进 interactive 变量）与 --non-interactive（透传到 filteredArgs）
+  // 语义相反，同时给是矛盾。在此层检测（command.js 看不到 --interactive）。
+  if (interactive && filteredArgs.includes('--non-interactive')) {
+    console.error('❌ --non-interactive 与 --interactive 互斥（一个禁用交互、一个强制交互），请只保留一个。');
+    process.exit(2);
+  }
+
   const command = filteredArgs[0];
   // 支持 sillyspec init /path/to/project 语法：如果第二个参数看起来像路径，当作 targetDir
   if (command === 'init' && filteredArgs[1] && !filteredArgs[1].startsWith('-')) {
@@ -233,9 +251,19 @@ async function main() {
         case 'show':
           pm.show(progDir, progChangeName);
           break;
-        case 'check':
-          await pm.checkConsistency(progDir, progChangeName);
+        case 'check': {
+          const result = await pm.checkConsistency(progDir, progChangeName);
+          // checkConsistency 只返回 {ok, issues, warnings}，不打印——必须在此输出，
+          // 否则 agent 跑只读健康检查得到一片寂静，无法分辨「正常」还是「已损坏」。
+          if (!result || result.ok) {
+            console.log(`✅ 状态一致性检查通过${progChangeName ? `（变更 ${progChangeName}）` : '（所有变更）'}`);
+          } else {
+            console.error(`❌ 状态一致性检查发现问题（${result.issues?.length || 0} 项）：`);
+            for (const issue of (result.issues || [])) console.error(`   - ${issue}`);
+            console.error(`   修复：sillyspec progress repair${progChangeName ? ` --change ${progChangeName}` : ''}（先 dry-run 看可修项，加 --apply 执行）`);
+          }
           break;
+        }
         case 'repair': {
           const repairApply = filteredArgs.includes('--apply');
           await pm.repairConsistency(progDir, { apply: repairApply, changeName: progChangeName });
@@ -340,8 +368,8 @@ async function main() {
           for (const e of (c.errors || [])) console.log(`     ✗ ${e}`);
           for (const w of (c.warnings || [])) console.log(`     ⚠ ${w}`);
         }
-        for (const e of (envelope.errors || [])) console.log(`  ✗ ${e}`);
-        for (const w of (envelope.warnings || [])) console.log(`  ⚠ ${w}`);
+        // 顶层 errors/warnings 是各 check 的聚合，已在上面按 check 分组显示；不再重复打印——
+        // 非 json 是 agent 默认消费路径，重复文本纯耗 context（W1-J）。
       }
       process.exitCode = exitCode;
       break;
@@ -402,7 +430,7 @@ async function main() {
       const { runCommand } = await import('./run.js')
       // 平台模式（--spec-dir 已指定）时，--dir 是明确的 source_root，不应被 resolveEffectiveDir 纠正
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
-      await runCommand(filteredArgs.slice(1), effectiveDir, specDir)
+      await runCommand(filteredArgs.slice(1), effectiveDir, specDir, { json })
       break
     }
     // 顶层命令别名：转发 runCommand，与 case 'run': 路径行为一致。
@@ -513,7 +541,7 @@ async function main() {
       }
       // 否则：保持原有 prompt 驱动的 bash 自检流程
       const { runCommand } = await import('./run.js');
-      await runCommand([command, ...filteredArgs.slice(1)], doctorEffectiveDir, specDir);
+      await runCommand([command, ...filteredArgs.slice(1)], doctorEffectiveDir, specDir, { json });
       break;
     }
     case 'scan':
@@ -528,7 +556,7 @@ async function main() {
       const { runCommand } = await import('./run.js')
       const stageArgs = [command, ...filteredArgs.slice(1)]
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
-      await runCommand(stageArgs, effectiveDir, specDir)
+      await runCommand(stageArgs, effectiveDir, specDir, { json })
       break
     }
     case 'knowledge': {
@@ -610,6 +638,9 @@ SillySpec worktree — git worktree 隔离管理
             console.error('❌ 用法: sillyspec worktree create <change-name> [--base <branch>]');
             process.exit(1);
           }
+          // F6 路径穿越消毒：worktree 名用于分支名 + worktree 目录，含 ../ 会逃出 .sillyspec/worktrees/。
+          try { assertSafeChangeName(wtName, 'worktree 变更名'); }
+          catch (e) { console.error(`❌ ${e.message}`); process.exit(2); }
           const baseIdx = args.indexOf('--base');
           const base = baseIdx >= 0 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
           try {
@@ -662,7 +693,14 @@ SillySpec worktree — git worktree 隔离管理
           } else if (result.merged) {
             console.log(`✅ 已通过 git merge 应用变更（baseline 漂移降级，引入合并提交）${result.mergeSummary ? '：' + result.mergeSummary : ''}`);
           } else {
-            console.log(`✅ 已应用 ${result.changedFiles.length} 个文件变更`);
+            console.log(`✅ 已应用 ${result.changedFiles.length} 个文件变更：`);
+            for (const f of result.changedFiles) {
+              console.log(`   ${f}`);
+            }
+            // filterDeliverableFiles 一刀切排除 .sillyspec/ + meta.json：
+            // 模块文档/变更文档等不会 auto-apply 到主工作区。须告知 agent，
+            // 否则它期望这些文件落地却找不到（memory: worktree-apply-excludes-module-docs）。
+            console.log(`   ℹ️  注：.sillyspec/ 下的文件（模块文档/变更文档等）按规则不自动 apply，如需请手动从 worktree 分支或 dangling commit 取（git show sillyspec/${wtName}:<path>）。`);
           }
           if (result.warnings && result.warnings.length > 0) {
             for (const w of result.warnings) {
@@ -708,7 +746,9 @@ SillySpec worktree — git worktree 隔离管理
             if (applyResult.errors.length > 0) {
               console.error('❌ apply 失败:', applyResult.errors.join('; '));
             } else {
-              console.log(`✅ 已自动应用 ${applyResult.changedFiles.length} 个文件变更`);
+              console.log(`✅ 已自动应用 ${applyResult.changedFiles.length} 个文件变更：`);
+              for (const f of applyResult.changedFiles) console.log(`   ${f}`);
+              console.log(`   ℹ️  注：.sillyspec/ 下的文件按规则不自动 apply，如需请手动从分支取（git show sillyspec/${wtName}:<path>）。`);
             }
           } else {
             console.log('Action: blocked');
@@ -970,6 +1010,14 @@ SillySpec platform — SillyHub 平台同步
         console.error('❌ 用法: sillyspec change-rename <旧变更名> <新变更名>');
         process.exit(1);
       }
+      // F6 路径穿越消毒：renameChange 会 mv changes/<old> → changes/<new>，名含 ../ 会逃出 changes/。
+      try {
+        assertSafeChangeName(oldName, '旧变更名');
+        assertSafeChangeName(newName, '新变更名');
+      } catch (e) {
+        console.error(`❌ ${e.message}`);
+        process.exit(2);
+      }
       const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
       await pm.renameChange(dir, oldName, newName);
       break;
@@ -1100,7 +1148,11 @@ SillySpec workflow — 工作流管理
         }
         process.exit(result.status === 'pass' ? 0 : 1);
       } else {
+        const wfSubs = ['check', 'list'];
+        const sug = didYouMean(wfSub, wfSubs);
         console.error(`❌ 未知子命令: workflow ${wfSub}`);
+        if (sug) console.error(`   你是想输入「workflow ${sug}」吗？`);
+        console.error(`   可用子命令：${wfSubs.join(' | ')}（运行 sillyspec workflow 查看用法）`);
         process.exit(1);
       }
       break;
@@ -1128,7 +1180,11 @@ SillySpec modules — 模块文档管理
         const { migrateModuleDocs } = await import('./modules.js');
         await migrateModuleDocs(dir);
       } else {
+        const modSubs = ['rebuild', 'status', 'migrate'];
+        const sug = didYouMean(modulesSub, modSubs);
         console.error(`❌ 未知子命令: modules ${modulesSub}`);
+        if (sug) console.error(`   你是想输入「modules ${sug}」吗？`);
+        console.error(`   可用子命令：${modSubs.join(' | ')}（运行 sillyspec modules 查看用法）`);
         process.exit(1);
       }
       break;
@@ -1180,10 +1236,83 @@ SillySpec modules — 模块文档管理
       console.log(`   路径: ${localYamlPath}`);
       break;
     }
-    default:
+    case 'runtime': {
+      // D2：.runtime/ 产物索引。CLI 往 .runtime/ 写各种证据/状态文件（db、doctor-diagnosis、
+      // workflow-runs、gate-status、user-inputs…），却没有命令让 agent 一眼看到「我手上有哪些产物」。
+      // 多会话/压缩后尤其痛：上轮写的证据文件，下轮不知去哪找。纯只读枚举，不写盘。
+      const runtimeSubCmd = filteredArgs[1];
+      if (runtimeSubCmd && runtimeSubCmd !== 'list') {
+        const sug = didYouMean(runtimeSubCmd, ['list']);
+        console.error(`❌ 未知子命令: runtime ${runtimeSubCmd}`);
+        if (sug) console.error(`   你是想输入「runtime ${sug}」吗？`);
+        console.error('用法: sillyspec runtime list   枚举 .sillyspec/.runtime/ 产物（只读）');
+        process.exit(2);
+      }
+      const specRoot = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const runtimeDir = join(specRoot, '.runtime');
+      if (!existsSync(runtimeDir)) {
+        if (json) { console.log(JSON.stringify({ runtimeDir, exists: false, artifacts: [] }, null, 2)); break; }
+        console.log(`📭 无 .runtime/ 目录（${runtimeDir}）——尚未产生任何运行时产物。`);
+        break;
+      }
+      // 已知产物 → 用途说明。agent 据此判断每份产物能否作为证据/该读哪个。
+      const KNOWN = {
+        'sillyspec.db': '进度库 SQLite（stages/steps/changes 表）',
+        'sillyspec.db.bak': '进度库备份（写前快照）',
+        'sillyspec.db.schema-version': '进度库 schema 版本标记',
+        'doctor-diagnosis.json': 'doctor --json 结构化诊断快照',
+        'doctor-dumps': 'doctor --dump-db 取证输出目录',
+        'workflow-runs': 'workflow check --save 归档目录',
+        'gate-status.json': '门控结果缓存',
+        'scan-guard.json': 'scan 覆盖保护记录',
+        'quick-sessions': 'quick 会话记录目录',
+        'quick-guard.json': 'quick baseline 守卫（旧位置）',
+        'worktrees': 'worktree meta（hooks 侧）',
+        'user-inputs.md': '步骤输出/输入历史追加日志',
+        'current-quick-run-id': '当前 quick sessionId 指针（--done 无 --change 时 fallback）',
+        'scan-runs': '平台模式 scan/workflow 取证目录',
+        'artifacts': '派生产物目录（init 预建）',
+        'contract-artifacts': 'execute endpoint 契约产物（verify 阶段读取）',
+        'history': '历史记录目录（init 预建）',
+        'logs': '日志目录（init 预建）',
+        'templates': '工作流模板目录（init 预建）',
+      };
+      let entries;
+      try {
+        entries = readdirSync(runtimeDir, { withFileTypes: true });
+      } catch (e) {
+        console.error(`❌ 读取 .runtime/ 失败: ${e.message}`);
+        process.exit(1);
+      }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      if (json) {
+        console.log(JSON.stringify({
+          runtimeDir, exists: true,
+          artifacts: entries.map(e => ({ name: e.name, type: e.isDirectory() ? 'dir' : 'file', desc: KNOWN[e.name] || null })),
+        }, null, 2));
+        break;
+      }
+      console.log(`📂 .runtime/ 产物（${runtimeDir}）`);
+      if (entries.length === 0) { console.log('   （空目录）'); break; }
+      for (const e of entries) {
+        const kind = e.isDirectory() ? '📁' : '📄';
+        const desc = KNOWN[e.name] ? `  — ${KNOWN[e.name]}` : '';
+        console.log(`   ${kind} ${e.name}${desc}`);
+      }
+      const unknown = entries.filter(e => !KNOWN[e.name]);
+      if (unknown.length > 0) {
+        console.log(`\n   （${unknown.length} 项未登记：${unknown.map(e => e.name).join(', ')}）`);
+      }
+      break;
+    }
+    default: {
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'local', 'workflow', 'gate', 'derive', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
+      if (suggestion) console.error(`   你是想输入「${suggestion}」吗？`);
       printUsage();
       process.exit(1);
+    }
   }
 }
 

package/src/machine-interface.js

@@ -125,10 +125,16 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot }
     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',
@@ -137,24 +143,24 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot }
       warnings: r.warnings || [],
     });
 
-    // ── b. transition：状态转换合法性（信息性，不参与综合 ok）──
-    // 与 run.js:1727 同源：传 fromStageData 触发 failed_post_check 门控，避免 gate 的
-    // transition 结论与 completeStep 漂移（design §8「聚合语义漂移」风险对策）。
+    // ── 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,
-      informational: true,
       errors: t.allowed ? [] : [t.reason].filter(Boolean),
       warnings: [],
     });
 
     // ── c. execute 阶段追加 execute-evidence + task-reviews ──
-    // D-008@v1 去重：checkExecuteCodeEvidence 整个 runGate 只调一次，
-    // 结果同时供 execute-evidence check 的 data 与综合结论。
+    // D-008 + W4-G：checkExecuteCodeEvidence 整个 runGate 只调一次（顶部 sharedEvidence 预计算），
+    // 这里复用——真正落实去重（原注释声称"只调一次"但实现里 execute-evidence check 仍重复调了第二次）。
     if (stage === 'execute') {
-      const ev = checkExecuteCodeEvidence(cwd, changeName);
+      const ev = sharedEvidence;
       checks.push({
         id: 'execute-evidence',
         ok: ev.status !== 'unchanged',

package/src/progress/change-registry.js

@@ -0,0 +1,217 @@
+// W6 Step9b: 变更注册表（changes 表生命周期）—— 注册/注销/重命名/隔离状态/平台同步戳/审批状态。
+// 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm._ensureDB /
+// pm._changePath（persistence-core 留 facade 本体）。无共享常量依赖。
+import { existsSync, mkdirSync, renameSync } from 'fs';
+
+export class ChangeRegistry {
+  constructor(pm) {
+    this.pm = pm;
+  }
+
+  /**
+   * 列出所有活跃变更名
+   * SQL: SELECT name FROM changes WHERE status = 'active'
+   */
+  async listChanges(cwd) {
+    const db = await this.pm._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    const rows = sqlDb.exec("SELECT name FROM changes WHERE status = 'active' ORDER BY name");
+    if (!rows || rows.length === 0) return [];
+    return rows[0].values.map(r => r[0]);
+  }
+
+  /**
+   * 注册变更到活跃列表
+   * SQL: INSERT OR IGNORE → 若已 archived 则 UPDATE status='active'
+   */
+  async registerChange(cwd, changeName) {
+    if (!changeName) {
+      console.warn('⚠️  registerChange: changeName 为空，跳过');
+      return;
+    }
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      const now = new Date().toISOString();
+      // 尝试插入新行
+      sqlDb.run(
+        `INSERT OR IGNORE INTO changes (name, created_at, last_active)
+         VALUES (?, ?, ?)`,
+        [changeName, now, now]
+      );
+      // 注意：不复活已归档的变更——归档是不可逆操作
+      // 如果变更已存在且为 archived，保持 archived 状态不变
+    });
+  }
+
+  /**
+   * 更新变更的隔离状态
+   * @param {string} cwd - 项目根目录
+   * @param {string} changeName - 变更名
+   * @param {{ status: string, mode?: string, reason?: string }} isolation
+   */
+  async updateChangeIsolation(cwd, changeName, isolation) {
+    const db = await this.pm._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    try {
+      sqlDb.run(
+        `UPDATE changes SET isolation_status = ?, isolation_mode = ?, isolation_reason = ?, last_active = ? WHERE name = ?`,
+        [isolation.status, isolation.mode || null, isolation.reason || null, new Date().toISOString(), changeName]
+      );
+      db._save();
+    } catch (err) {
+      console.warn('⚠️  更新 isolation 状态失败:', err.message);
+    }
+  }
+
+  /**
+   * 读取变更的隔离状态
+   * @param {string} cwd - 项目根目录
+   * @param {string} changeName - 变更名
+   * @returns {{ status: string|null, mode: string|null, reason: string|null }|null}
+   */
+  async readChangeIsolation(cwd, changeName) {
+    const db = await this.pm._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    try {
+      const rows = sqlDb.exec(
+        `SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name = ?`,
+        [changeName]
+      );
+      if (!rows || rows.length === 0 || rows[0].values.length === 0) return null;
+      const [status, mode, reason] = rows[0].values[0];
+      return { status: status || null, mode: mode || null, reason: reason || null };
+    } catch {
+      return null;
+    }
+  }
+
+  async _updatePlatformLastSync(cwd, changeName) {
+    if (!changeName) return;
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      sqlDb.run(
+        'UPDATE changes SET platform_last_sync = ?, platform_sync_enabled = 1 WHERE name = ?',
+        [new Date().toISOString(), changeName]
+      );
+    });
+  }
+
+  async _updateApprovalStatus(cwd, changeName, status, reason = null) {
+    if (!changeName || !status) return;
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      const rows = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [changeName]);
+      if (!rows || rows.length === 0 || rows[0].values.length === 0) return;
+      const changeId = rows[0].values[0][0];
+      const now = new Date().toISOString();
+      sqlDb.run(
+        `INSERT INTO approvals (change_id, status, requested_at, approved_at, rejection_reason)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(change_id) DO UPDATE SET
+           status = excluded.status,
+           approved_at = excluded.approved_at,
+           rejection_reason = excluded.rejection_reason`,
+        [
+          changeId,
+          status,
+          now,
+          status === 'approved' ? now : null,
+          status === 'rejected' ? reason : null,
+        ]
+      );
+    });
+  }
+
+  /**
+   * 重命名变更：同步更新 DB + 目录
+   * @param {string} cwd - 项目根目录
+   * @param {string} oldName - 旧变更名
+   * @param {string} newName - 新变更名
+   */
+  async renameChange(cwd, oldName, newName) {
+    if (!oldName || !newName) {
+      console.warn('⚠️  renameChange: 旧名或新名为空，跳过');
+      return;
+    }
+    if (oldName === newName) {
+      console.warn('⚠️  renameChange: 新旧名称相同，跳过');
+      return;
+    }
+    const db = await this.pm._ensureDB(cwd);
+    // 检查旧名是否存在
+    const existing = db.transaction((sqlDb) => {
+      const row = sqlDb.exec(`SELECT name, status FROM changes WHERE name = ?`, [oldName]);
+      if (!row || !row[0] || row[0].values.length === 0) return null;
+      return { name: row[0].values[0][0], status: row[0].values[0][1] };
+    });
+    if (!existing) {
+      console.error(`❌ 变更 ${oldName} 不存在`);
+      return;
+    }
+    // 检查新名是否已存在
+    const conflict = db.transaction((sqlDb) => {
+      const row = sqlDb.exec(`SELECT name FROM changes WHERE name = ?`, [newName]);
+      return row && row[0] && row[0].values.length > 0;
+    });
+    if (conflict) {
+      console.error(`❌ 变更 ${newName} 已存在`);
+      return;
+    }
+    // 先更新 DB，再重命名目录；FS 失败则回滚 DB，避免"目录已改名但 DB 旧名"的孤儿
+    // （旧实现 FS-first 无补偿：renameSync 成功后 DB transaction 抛 EPERM/EBUSY 会让
+    //  目录已是 newName、DB 仍是 oldName，read(两名) 都失联且无自动恢复）。
+    const oldDir = this.pm._changePath(cwd, oldName);
+    const newDir = this.pm._changePath(cwd, newName);
+    const now = new Date().toISOString();
+    try {
+      db.transaction((sqlDb) => {
+        sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
+      });
+    } catch (e) {
+      console.error(`❌ 重命名失败：更新数据库时出错（${e.message}）`);
+      return;
+    }
+    let renamed = true;
+    if (existsSync(oldDir)) {
+      try {
+        renameSync(oldDir, newDir);
+      } catch (e) {
+        renamed = false;
+        // FS 重命名失败：回滚 DB 恢复 oldName，保持 DB 与目录一致
+        try {
+          db.transaction((sqlDb) => {
+            sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [oldName, now, newName]);
+          });
+          console.error(`❌ 重命名失败：移动目录出错（${e.message}），已回滚数据库`);
+        } catch (rollbackErr) {
+          // 回滚本身也失败：DB 是 newName、目录是 oldName，两端分裂且无自动恢复。
+          // 不能再撒谎"已回滚"——必须显式报错让用户跑 doctor 修复。
+          console.error(`❌ 重命名失败且数据库回滚也失败（状态分裂，需手动修复）：原错=${e.message} 回滚错=${rollbackErr.message}。请跑 sillyspec doctor --json`);
+        }
+      }
+    } else {
+      mkdirSync(newDir, { recursive: true });
+    }
+    if (renamed) console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
+  }
+
+  /**
+   * 从活跃列表移除变更（归档时调用，不物理删除）
+   * SQL: UPDATE changes SET status = 'archived'
+   */
+  async unregisterChange(cwd, changeName) {
+    if (!changeName) {
+      console.warn('⚠️  unregisterChange: changeName 为空，跳过');
+      return;
+    }
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      const now = new Date().toISOString();
+      sqlDb.run(
+        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`,
+        [now, changeName]
+      );
+    });
+  }
+}
+