sillyspec 3.27.12 → 3.28.2

package/src/progress/consistency-doctor.js

@@ -1,8 +1,9 @@
 // W6 Step9a: Revision v1 状态一致性检查 + 修复 + --force 审计日志。
 // 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm.read / pm._write /
 // pm._ensureRuntimeDir / pm._runtimePath（persistence-core 留 facade 本体）。
-import { appendFileSync, existsSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { appendFileSync, existsSync, readFileSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { DB } from '../db.js';
 import { summarizeTaskCompletion } from '../task-review.js';
 import { STAGE_ORDER, MAIN_FLOW_ORDER } from './shared.js';
 
@@ -11,6 +12,104 @@ export class ConsistencyDoctor {
     this.pm = pm;
   }
 
+  /**
+   * 双进度库分裂探测（坑 progress-repair-dual-library-blind，2026-09-04 用户实证②：
+   * 接管指针切换库后 progress repair 只看当前库，旧库残留的活跃变更进度完全不可见，
+   * 报告「未发现问题，无需修复」的假阴性）。
+   *
+   * 判据：cwd 存在平台接管指针（.sillyspec-platform.json 指向库 A = 当前修复目标），
+   * 同时 cwd/.sillyspec/.runtime/sillyspec.db（库 B = 切库前旧库）也存在且 ≠ 库 A
+   * → 双库并存。自指指针（specRoot 解析回本地 .sillyspec）不算。
+   *
+   * 只读探测：另一库仅在 sillyspec.db 已存在时直读（DB 类 + 存在性前置检查，绝不新建库文件）；
+   * 读失败 fail-open 返回库存在但活跃清单不可读，不阻断 check/repair 主流程。
+   *
+   * @param {string} cwd - 进度库锚定 cwd（index.js 传入 progDir）
+   * @param {string|null} [changeName] - check/repair 的 --change 目标（判「操作错了库」用）
+   * @returns {{ split: boolean, dualDb: boolean, bothActive: boolean, targetInOther: boolean, lines: string[] }}
+   */
+  detectLibrarySplit(cwd, changeName = null) {
+    const out = { split: false, dualDb: false, bothActive: false, targetInOther: false, lines: [] };
+    const pointerPath = join(cwd, '.sillyspec-platform.json');
+    if (!existsSync(pointerPath)) return out;
+    let ptr = null;
+    try {
+      ptr = JSON.parse(readFileSync(pointerPath, 'utf8'));
+    } catch {
+      return out; // 指针损坏由 resolvePlatformSpecDir fail-closed 负责，此处不重复报
+    }
+    if (!ptr.specRoot) return out;
+
+    const localRoot = join(cwd, '.sillyspec');
+    const localDbPath = join(localRoot, '.runtime', 'sillyspec.db');
+    if (resolve(ptr.specRoot) === resolve(localRoot)) return out; // 自指/同库
+    if (!existsSync(localDbPath)) return out; // 旧库无 DB → 无分裂
+
+    out.dualDb = true;
+    const currentSpecDir = this.pm._getSpecDir(cwd);
+    // 当前库：DB 已存在才读（readGlobal 走 pm 连接池，不新开连接；不存在时 readGlobal 会
+    // 隐式建库，须前置 existsSync 挡住——探测绝不产生写副作用）
+    let current = null;
+    if (existsSync(join(currentSpecDir, '.runtime', 'sillyspec.db'))) {
+      try {
+        const g = this.pm.readGlobal(cwd);
+        current = { activeChanges: (g && g.activeChanges) || [] };
+      } catch (e) {
+        current = { activeChanges: [], unreadable: true, error: e.message };
+      }
+    }
+    const other = this._readActiveQuiet(localRoot, cwd);
+    const currentActive = current?.activeChanges || [];
+    const otherActive = other?.activeChanges || [];
+
+    out.lines.push(
+      `双进度库并存（接管指针 ${pointerPath} → ${currentSpecDir}；切库前旧库残留 ${localRoot}）` +
+      `——本次 check/repair 只作用于当前库，旧库状态不可见`
+    );
+    out.lines.push(
+      `  当前库活跃变更: ${currentActive.length > 0 ? currentActive.join('、') : '(无)'}${current?.unreadable ? '（读取失败：' + current.error + '）' : ''}`
+    );
+    out.lines.push(
+      `  旧库活跃变更: ${otherActive.length > 0 ? otherActive.join('、') : '(无)'}${other?.unreadable ? '（读取失败：' + other.error + '）' : ''}`
+    );
+    out.lines.push(
+      `  处理：确认权威库后收尾/归档弃用库的活跃变更；或 sillyspec platform pointer --cleanup 删指针后重跑平台 scan 指向正确库；临时读旧库用 --spec-dir ${localRoot}`
+    );
+
+    if (currentActive.length > 0 && otherActive.length > 0) {
+      out.bothActive = true;
+      out.split = true;
+    }
+    // 目标变更只在旧库活跃（当前库查无）→ 本次操作几乎必然找错了库，最强信号
+    if (changeName && otherActive.includes(changeName) && !currentActive.includes(changeName)) {
+      out.targetInOther = true;
+      out.split = true;
+      out.lines.push(
+        `  ⚠️ 目标变更 "${changeName}" 不在当前库，但旧库有同名活跃变更——本次操作错了库，修复应带上 --spec-dir ${localRoot}（或修正指针）`
+      );
+    }
+    return out;
+  }
+
+  /**
+   * 只读读一个库的活跃变更清单（detectLibrarySplit 专用）。
+   * sillyspec.db 不存在返回 null（绝不新建库）；打开/读取失败返回 { unreadable, error }
+   * 不上抛——分裂探测 fail-open，不阻断主流程。
+   */
+  _readActiveQuiet(specDir, cwd) {
+    const dbPath = join(specDir, '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) return null;
+    let db = null;
+    try {
+      db = new DB(dbPath);
+      db.init();
+      const rows = db.getDb().prepare("SELECT name FROM changes WHERE status = 'active' ORDER BY name").all();
+      return { activeChanges: rows.map(r => r.name) };
+    } catch (e) {
+      return { activeChanges: [], unreadable: true, error: e.message };
+    }
+  }
+
   /**
    * 强制状态变更的审计记录（--force 逃生口专用）。
    * 追加到 .runtime/audit.log，供人工/doctor 追溯"谁在什么时候绕过了校验"。
@@ -36,12 +135,26 @@ export class ConsistencyDoctor {
   checkConsistency(cwd, changeName = null) {
     const data = this.pm.read(cwd, changeName);
     if (!data) {
-      return { ok: false, issues: ['无法读取进度数据'], warnings: [] };
+      // 双库分裂探测不依赖单变更 progress 可读（read 失败时更要看见另一库，坑
+      // progress-repair-dual-library-blind）：无 progress 也要报分裂，不能只报「无法读取」
+      const splitNoData = this.detectLibrarySplit(cwd, changeName);
+      const issuesNoData = ['无法读取进度数据'];
+      if (splitNoData.targetInOther || splitNoData.bothActive) issuesNoData.push(...splitNoData.lines);
+      return { ok: false, issues: issuesNoData, warnings: splitNoData.dualDb && !splitNoData.split ? splitNoData.lines : [] };
     }
 
     const issues = [];
     const warnings = [];
 
+    // 双库分裂（2026-09-04 ②）：目标变更只在旧库 / 两库皆有活跃 → issue；
+    // 仅双库并存（单侧活跃）→ warning（平台模式本地库保留真实资产是容忍态，避免常态误报）
+    const libSplit = this.detectLibrarySplit(cwd, changeName);
+    if (libSplit.targetInOther || libSplit.bothActive) {
+      issues.push(...libSplit.lines);
+    } else if (libSplit.dualDb) {
+      warnings.push(...libSplit.lines);
+    }
+
     for (const stageName of STAGE_ORDER) {
       const sd = data.stages[stageName];
       if (!sd) continue;
@@ -186,14 +299,20 @@ export class ConsistencyDoctor {
   repairConsistency(cwd, opts = {}) {
     const { apply = false, changeName = null } = opts;
 
+    // 双库分裂（2026-09-04 ②）：repair 修不了「哪边是权威库」，只能把另一库的存在与活跃
+    // 变更亮出来进 manual 清单。放 read 之前——多活跃/读不了库时 read 早退，探测不能跟着瞎。
+    const libSplit = this.detectLibrarySplit(cwd, changeName);
+    const splitManual = libSplit.dualDb ? [...libSplit.lines] : [];
+
     const data = this.pm.read(cwd, changeName);
     if (!data) {
       console.log('❌ 无法读取进度数据');
-      return { fixable: [], manual: ['无法读取进度数据'], applied: [] };
+      for (const m of splitManual) console.log(`   - ${m}`);
+      return { fixable: [], manual: ['无法读取进度数据', ...splitManual], applied: [] };
     }
 
     const fixable = []; // { stage, action, description, apply: (data) => void }
-    const manual = [];  // string
+    const manual = [...splitManual];  // string
 
     const now = new Date().toLocaleString('zh-CN', { hour12: false });
 

package/src/progress/stage-machine.js

@@ -3,12 +3,23 @@
 // 调 pm.read/_write/_ensureDB/_getSpecDir/readGlobal/_runtimePath/listChanges/_appendAuditLog/
 // _renderBatchProgress（persistence-core + 其他组 delegate）。组内方法互调保持 this.X（同 class）。
 // completeStage 五层（resolve/validate/force/tx/history/print）整体搬迁，不拆流水线（保行为、最低风险）。
-import { mkdirSync, existsSync } from 'fs';
+import { mkdirSync, existsSync, readdirSync, readFileSync } from 'fs';
 import { join, resolve, basename } from 'path';
 import { writeAtomicSync } from '../fs-atomic.js';
 import { runValidators } from '../stage-contract.js';
+import { QUICK_SID_RE } from '../run/shared.js';
 import { VALID_STAGES, STAGE_LABELS, STAGE_ORDER, MAIN_FLOW_ORDER, SPEC_DIR_NAME, CURRENT_VERSION, STALL_WARN_DAYS, emptyStage } from './shared.js';
 
+// quick 会话行（quick-<8hex>）按设计无实体 changes/ 目录（progress.js initChange 跳过建目录），
+// 「DB active + changes/ 无同名目录」的 ghost 判定对它是类别错误——进行中的 quick 从写库那
+// 一刻起即命中误报（2026-09-07 quick-inflight-ghost-misjudge，面板「一键清理」清了又长：
+// 每次清理都成功，新 ghost 是清理后才启动的 quick）。show 与 overview 统一经此判定排除。
+// 注意：排除的只是「判定」，doctor --cleanup-ghosts 仍保留 quick 行归档能力（QUICKLOG 已
+// 完成但 DB 行未注销的收尾中断形态，那是兜底出口，不在此排除）。
+function _isGhostChange(changesRoot, cn) {
+  return !QUICK_SID_RE.test(cn) && !existsSync(join(changesRoot, cn));
+}
+
 /**
  * 归一化步骤的已记录等待回答（show 渲染用，跨会话恢复数据源）。
  * waitAnswers 走 pm.read 时已 JSON.parse，但容错字符串/损坏；单值列 wait_answer（旧路径）并入第 1 轮。
@@ -205,9 +216,11 @@ export class StageMachine {
     console.log('');
 
     const changesRoot = join(this.pm._getSpecDir(cwd), 'changes');
+    // P2-2-①：未决同步冲突标红（overview 同源 _listPendingConflicts；该变更命中 → 🔴 行）
+    const pendingConflicts = this._listPendingConflicts(this.pm._getSpecDir(cwd));
     for (const cn of changes) {
       const data = this.pm.read(cwd, cn);
-      const dirMissing = !existsSync(join(changesRoot, cn));
+      const dirMissing = _isGhostChange(changesRoot, cn);
       if (!data) {
         console.log(`  📂 ${cn} — (无法读取)${dirMissing ? ' ⚠️ 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）' : ''}`);
         continue;
@@ -217,6 +230,13 @@ export class StageMachine {
       const lastActive = data.lastActive ? this._timeAgo(data.lastActive) : '未知';
 
       console.log(`  📂 ${cn}${dirMissing ? ' ⚠️ 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）' : ''}`);
+      // 变更级未决冲突标红（冲突可见性，2026-09-02 P2-2-①）：不再靠 agent 自己撞上才发现
+      const cnConflicts = pendingConflicts.filter(c => c.change === cn);
+      if (cnConflicts.length > 0) {
+        for (const cf of cnConflicts) {
+          console.log(`     🔴 未决同步冲突（${cf.type === 'progress' ? '进度' : 'spec 树'}${cf.created_at ? `，${cf.created_at}` : ''}）——请 sillyspec platform resolve 处理后再推进`);
+        }
+      }
       console.log(`     当前阶段: ${stageLabel}  最近活跃: ${lastActive}`);
       // 滞留/疑似完成信号（2026-08-30 用户反馈②）：多变更汇总逐行透出，无需逐个 --change 看详情
       const stall = this._stallSignal(cwd, data, cn);
@@ -229,10 +249,106 @@ export class StageMachine {
       console.log('');
     }
 
+    // P2-2-① 补丁（2026-09-02 晚）：全局未决冲突汇总段——逐变更行只显示「对上活跃变更」的冲突，
+    // 挂在 ghost/非活跃变更上的冲突会漏（huber 面板联调实证 11 条只显示 0）。此处按
+    // pending_conflicts 全量兜底显示，与 --json envelope 顶层字段同口径。
+    if (pendingConflicts.length > 0) {
+      console.log(`  🔴 未决同步冲突（${pendingConflicts.length} 条，含未匹配活跃变更的）:`);
+      for (const cf of pendingConflicts) {
+        console.log(`     - ${cf.change}${cf.type ? `（${cf.type === 'progress' ? '进度' : 'spec 树'}${cf.created_at ? `，${cf.created_at}` : ''}）` : ''}`);
+      }
+      console.log(`     → sillyspec platform resolve 逐条裁决（以本地/以平台为准），处理完冲突消失`);
+    }
+
     console.log(`  💡 查看详情：sillyspec progress show --change <name>`);
     console.log('');
   }
 
+  /**
+   * 只读全局总览数据（show 多变更汇总视图的机器版，2026-09-02 跨 agent 单一状态源）。
+   * 列出全部活跃变更：各自当前阶段 / 各阶段步骤计数 / ghost（目录缺失残留）/ stall 信号。
+   * 纯数据零 console——machine-interface.runStatusOverview 包装 envelope（`sillyspec progress show --json`）。
+   *
+   * 与 dump（§6.2 单变更视角）语义互补：dump 取最近活跃一个供 daemon 轮询「当前工作流状态」；
+   * overview 列出全部活跃，供 SillyHub 面板 / 跨 agent 看「谁在动哪些变更」（多活跃是变更隔离常态）。
+   * 字段 snake_case + last_active ISO 规范化（_dumpIso），与 dump 契约风格对齐（backend pydantic 消费）。
+   *
+   * @param {string} cwd - 项目根目录（show 同参语义，非 specDir）
+   * @returns {{project: string|null, active_changes: number, changes: Array<object>}}
+   */
+  overview(cwd) {
+    const changes = this.pm.listChanges(cwd);
+    const specDir = this.pm._getSpecDir(cwd);
+    const changesRoot = join(specDir, 'changes');
+    const list = [];
+    for (const cn of changes) {
+      const data = this.pm.read(cwd, cn);
+      const dirMissing = _isGhostChange(changesRoot, cn);
+      const entry = {
+        name: cn,
+        readable: !!data,
+        ghost: dirMissing,
+        current_stage: data?.currentStage || null,
+        stage_label: data ? (STAGE_LABELS[data.currentStage] || data.currentStage || null) : null,
+        last_active: this.pm._dumpIso(data?.lastActive) || null,
+      };
+      if (data) {
+        // 各阶段状态 + 步骤计数（面板进度条数据源）；总计另出顶层 steps 汇总
+        let stepsTotal = 0, stepsCompleted = 0;
+        const stages = {};
+        for (const st of VALID_STAGES) {
+          const sd = data.stages?.[st];
+          if (!sd) continue;
+          const steps = Array.isArray(sd.steps) ? sd.steps : [];
+          const completed = steps.filter(s => s.status === 'completed').length;
+          stages[st] = { status: sd.status || 'pending', steps_total: steps.length, steps_completed: completed };
+          stepsTotal += steps.length;
+          stepsCompleted += completed;
+        }
+        entry.stages = stages;
+        entry.steps = { total: stepsTotal, completed: stepsCompleted };
+        // 滞留/疑似完成信号（与 show 汇总同源 _stallSignal，纯数据不带渲染建议文案）
+        const stall = this._stallSignal(cwd, data, cn);
+        if (stall) {
+          entry.stall = { kind: stall.kind, days: this._daysSince(data.lastActive), text: stall.text };
+        }
+      }
+      list.push(entry);
+    }
+    const global = this.pm.readGlobal(cwd);
+    return {
+      project: global?.project || basename(cwd) || null,
+      active_changes: changes.length,
+      changes: list,
+      // P2-2-① 未决同步冲突透出（2026-09-02 跨 agent 工单）：fs-only 扫描 .runtime/ 下
+      // sync-conflict-*（进度冲突）与 spec-sync-conflict-*（spec 树冲突），前缀/字段与
+      // sync.js listConflictFiles 同源（此处不 new SyncManager——progress 层不引网络依赖，
+      // 损坏文件跳过不崩同 constraints）。有冲突时 show 汇总标红、--json envelope 升 warnings。
+      pending_conflicts: this._listPendingConflicts(specDir),
+    };
+  }
+
+  /** 未决同步冲突列表（overview 数据源；与 sync.js listConflictFiles 同前缀同字段，fs-only） */
+  _listPendingConflicts(specDir) {
+    const runtimeDir = join(specDir, '.runtime');
+    let files = [];
+    try { files = readdirSync(runtimeDir); } catch { return []; }
+    const conflicts = [];
+    for (const f of files) {
+      const isProgress = f.startsWith('sync-conflict-');
+      if (!(isProgress || f.startsWith('spec-sync-conflict-')) || !f.endsWith('.json')) continue;
+      let change = f.replace(/^spec-sync-conflict-|^sync-conflict-/, '').replace(/\.json$/, '');
+      let createdAt = null;
+      try {
+        const cf = JSON.parse(readFileSync(join(runtimeDir, f), 'utf8'));
+        change = cf.change || change;
+        createdAt = cf.created_at || null;
+      } catch { /* 损坏文件按文件名兜底，不崩 */ }
+      conflicts.push({ change, created_at: createdAt, type: isProgress ? 'progress' : 'spec-tree' });
+    }
+    return conflicts;
+  }
+
   _showChange(cwd, changeName) {
     const data = this.pm.read(cwd, changeName);
     if (!data) {

package/src/progress.js

@@ -868,6 +868,9 @@ export class ProgressManager {
 
   updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
 
+  // quick --done 兜底复用启动 ql-ID（坑 platform-takeover-phantom-progress-db 同日变体）
+  getQuicklogId(cwd, changeName) { return this._changeRegistry.getQuicklogId(cwd, changeName); }
+
   // ── CLI 命令 ──
 
   init(cwd) {
@@ -966,6 +969,9 @@ export class ProgressManager {
 
   show(cwd, changeName = null) { return this._stageMachine.show(cwd, changeName); }
 
+  // 只读全局总览（show 多变更汇总的机器版，2026-09-02 单一状态源）：纯数据，machine-interface 包装
+  overview(cwd) { return this._stageMachine.overview(cwd); }
+
   _showChange(cwd, changeName) { return this._stageMachine._showChange(cwd, changeName); }
 
   _getNextSuggestion(data) { return this._stageMachine._getNextSuggestion(data); }

package/src/quicklog.js

@@ -713,6 +713,57 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
   })
 }
 
+/**
+ * 以**给定 ql-ID** 追加一条「进行中」骨架条目（不分配新 ID）。
+ *
+ * 坑 platform-takeover-phantom-progress-db 同日变体：quick --done 兜底复用启动分配的
+ * ql-ID（进度库 changes.quicklog_id 可查）时，该 ID 的条目可能不在当前 specBase 的
+ * QUICKLOG 文件里（启动与 --done 落到不同库/文件的分裂形态）——用原 ID 补建骨架再走
+ * 完成翻态，保证「同一次会话只有一个 ql-ID」。条目已存在则幂等跳过（不重复追加）。
+ * 与 allocateQuicklogEntry 同锁同格式同平台推送，仅跳过 ID 分配段。
+ */
+export async function appendQuicklogEntryWithId(specBase, gitUser, qlId, { description = '(guard 缺失补建)', linkedChanges = [], allowedFiles = [] } = {}) {
+  if (!qlId || typeof qlId !== 'string') throw new Error('appendQuicklogEntryWithId: qlId 必填')
+  if (findQuicklogEntry(specBase, gitUser, qlId)) return { qlId, existed: true }
+  const quicklogDir = join(specBase, 'quicklog')
+  mkdirSync(quicklogDir, { recursive: true })
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
+  const userFile = join(quicklogDir, `QUICKLOG-${user}.md`)
+  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
+  const desc = sanitizeDesc(description)
+  const linked = Array.isArray(linkedChanges) ? linkedChanges : []
+  const files = Array.isArray(allowedFiles) ? allowedFiles : []
+
+  return await withFileLock(lockPath, async () => {
+    // 双检（锁内）：并发兜底同 ID 只落一条
+    if (findQuicklogEntry(specBase, gitUser, qlId)) return { qlId, existed: true }
+    await rotateIfNeeded(userFile, user)
+    const entry = [
+      '',
+      `## ${qlId} | ${nowDatetime()} | ${desc}`,
+      '状态：进行中',
+      `关联变更：${linked.length > 0 ? linked.join(', ') : '（无）'}`,
+      `文件：${files.length > 0 ? files.join(', ') : '（见实际改动）'}`,
+      '',
+    ].join('\n')
+    appendFileSync(userFile, entry)
+    for (const c of linked) await appendTaskCheckbox(specBase, c, qlId, desc)
+    await pushQuicklogEntryToPlatform(specBase, {
+      ql_id: qlId,
+      timestamp: nowDatetime(),
+      title: desc,
+      status: 'in_progress',
+      status_note: null,
+      author_raw: user,
+      linked_changes: linked.filter(c => /^\d{4}-\d{2}-\d{2}-/.test(c)),
+      files: files.map(f => ({ path: f, note: null })),
+      body_sections: {},
+      raw_block: entry,
+    }).catch(() => {})
+    return { qlId, existed: false }
+  })
+}
+
 /**
  * 翻某 qlId 条目为「已完成」+ 追加结果 + 勾选关联 tasks.md。持锁。
  */

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, ancestorSpecDirs, resolveAncestorCeiling, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, resolveQuickSessionsDir, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -107,6 +107,38 @@ function warnMsysMangledFlag(flag, value) {
   console.error('   非本意 → 去掉前导 / 或改写表述后重发本命令；确需原样 → 命令前加 MSYS_NO_PATHCONV=1。')
 }
 
+/**
+ * done-like 步骤动作（--done/--skip/--wait/--continue/--reset/--reopen）的目标 change 在当前
+ * 库是否已「物化」（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）。
+ *
+ * 背景：接管指针切换/重建进度库后，--change 常指向旧库的变更名；新库里既无 DB 行也无
+ * changes/<name>/ 目录，runCommand 的 !progress 分支却无条件 initChange 静默新建——幻影
+ * 变更零进度起步，--done 被记到幻影上，原变更进度停滞（本次事故直接元凶）。
+ *
+ * 物化口径（progress 已知为 null，只查磁盘标记）：
+ *   - 普通变更：changes/<name>/ 存在（archive 已归档目录也算——归档后 DB 行仍可读，
+ *     但行被清理的恢复场景认 archive 目录物化，走 initChange 自愈是合法路径）；
+ *   - quick-<8hex> 会话：无 changes/ 目录，物化标记 = 会话 guard（per-session 目录或
+ *     legacy 单文件——legacy 无法归属会话，保守认物化，宁可漏拦不误杀真会话）。
+ *
+ * 纯函数：只读磁盘，供 command.js 守卫 + 单测复用。
+ * @param {object} opts
+ * @param {string|null} opts.target - 目标 change 名（--change 值或 changes/ 目录唯一推导）
+ * @param {string} opts.specBase - 当前进度库根（平台 specRoot 或 cwd/.sillyspec）
+ * @param {string|null} [opts.quickSessionsDir] - quick 会话 guard 目录（缺省按 specBase/.runtime 推导）
+ * @returns {boolean} true = 目标已物化（可走既有 initChange 自愈），false = 幻影（应拒绝新建）
+ */
+export function doneLikeTargetMaterialized({ target, specBase, quickSessionsDir = null }) {
+  if (!target || !specBase) return false
+  if (/^quick-[0-9a-f]{8}$/.test(target)) {
+    const rt = quickSessionsDir || join(specBase, '.runtime', 'quick-sessions')
+    return existsSync(join(rt, target, 'guard.json'))
+      || existsSync(join(specBase, '.runtime', 'quick-guard.json'))
+  }
+  return existsSync(join(specBase, 'changes', target))
+    || existsSync(join(specBase, 'changes', 'archive', target))
+}
+
 /**
  * 从 progress 或变更目录推导变更名
  */
@@ -951,6 +983,43 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   if (!progress) {
+    // ── done-like 存在性守卫（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）──
+    // --done/--skip/--wait/--continue/--reset/--reopen 都预设「目标 change 已存在于当前进度库」。
+    // 此前 !progress 时无条件 initChange 静默新建——接管指针切库/换库后 --change 指向旧库的
+    // 变更名，新库里凭空建幻影变更再把动作记上去。目标已物化（changes/ 目录或 quick 会话
+    // guard 存在）仍放行走下方 initChange 自愈（DB 重建/迁移后从目录物化是合法恢复路径）。
+    if (isDone || isSkip || isWait || isContinue || isReset || isReopen) {
+      const actionFlag = isDone ? '--done' : isSkip ? '--skip' : isWait ? '--wait'
+        : isContinue ? '--continue' : isReset ? '--reset' : '--reopen'
+      const guardTarget = changeName || resolveChangeNameAuto(cwd, specRoot)
+      if (!doneLikeTargetMaterialized({
+        target: guardTarget,
+        specBase,
+        quickSessionsDir: resolveQuickSessionsDir(platformOpts, specBase),
+      })) {
+        const pointerPath = join(cwd, '.sillyspec-platform.json')
+        const pointerMode = existsSync(pointerPath)
+        let activeList = []
+        try { activeList = pm.listChanges(cwd) } catch { /* 列举失败不掩盖主报错 */ }
+        console.error(`❌ ${actionFlag} 找不到目标变更的进度，拒绝静默新建（防幻影变更）。`)
+        console.error(`   目标变更: ${guardTarget || '(未指定 --change，且当前库无唯一活跃变更)'}`)
+        console.error(`   当前进度库: ${specBase}${pointerMode ? `（平台接管指针 ${pointerPath} 指向此库）` : '（本地模式）'}`)
+        console.error(`   本库活跃变更: ${activeList.length > 0 ? activeList.join('、') : '(无)'}`)
+        console.error('   排查：')
+        console.error(`   ① 变更名是否打错——从上面活跃列表选，或 sillyspec progress show 查看各变更进度`)
+        if (pointerMode) {
+          console.error(`   ② 最近是否切换/重建过平台接管指针（重跑平台 scan 会换库）——原变更可能留在旧库：检查 ${pointerPath} 的 specRoot，或用 --spec-dir 显式指回旧库`)
+        } else {
+          console.error(`   ② cwd 是否漂移/切库——用 --spec-dir <路径>/.sillyspec 显式指定正确的进度库`)
+        }
+        if (stageName === 'quick' || /^quick-[0-9a-f]{8}$/.test(guardTarget || '')) {
+          console.error(`   ③ quick 会话跨进程恢复须带 --change <quick-session-id>；本库无该会话 guard——会话可能属于旧库`)
+        } else {
+          console.error(`   ③ 确要新建变更：先 sillyspec run brainstorm --change <名>（不带 ${actionFlag}）`)
+        }
+        process.exit(2) // 用法/环境错（目标变更不在当前库）→ exit 2
+      }
+    }
     // 如果指定了变更名或有变更目录，自动初始化变更的 progress
     const autoChange = changeName || resolveChangeNameAuto(cwd, specRoot)
     if (autoChange) {
@@ -1310,7 +1379,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
     }
     const doneAnswer = getFlagValue('--answer')
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete })
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete, quickFiles })
   }
 
   // 默认：输出当前步骤