sillyspec 3.27.2 → 3.27.6

package/.claude/worktrees/sillyspec-data-model-research/src/progress.js

@@ -0,0 +1,1304 @@
+/**
+ * SillySpec ProgressManager — 进度恢复管理
+ *
+ * 纯 Node.js，无外部依赖。支持多变更并行。
+ *
+ * 存储结构：
+ *   .sillyspec/.runtime/sillyspec.db          — SQLite 数据库（权威状态源，含全局状态/项目名/活跃变更）
+ *
+ * 历史迁移：v1/v2 使用 progress.json 文件，v3 已全部迁移至 SQLite。
+ * worktree-guard hook 直读 sillyspec.db，不再有 gate-status.json 缓存双源（task-10 废除）。
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync } from 'fs';
+import { join, basename, dirname, resolve, sep } from 'path';
+import { tmpdir } from 'os';
+import { writeAtomicSync } from './fs-atomic.js';
+import { DB } from './db.js';
+import { checkExecuteCodeEvidence } from './stage-contract.js';
+import { ConsistencyDoctor } from './progress/consistency-doctor.js';
+import { ChangeRegistry } from './progress/change-registry.js';
+import { StepStore } from './progress/step-store.js';
+import { StageMachine } from './progress/stage-machine.js';
+import { stageRegistry } from './stages/index.js';
+import { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './progress/shared.js';
+// resolveSpecDir 单一真相源在 src/run/shared.js（含 home 拒绝守卫，坑 cwd-correction-home-collision
+// 根治：home 下 .sillyspec 恒不命中，防 smoke/临时目录污染自我延续）。此处 re-export 保持
+// 既有 import 路径兼容；run/shared.js 对 progress.js 只有动态 import，无静态循环。
+import { resolveSpecDir } from './run/shared.js';
+import { checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './run/shared.js';
+export { resolveSpecDir };
+
+// 默认规范目录名（相对于 cwd）
+// SPEC_DIR_NAME → ./progress/shared.js（W6 Step9d）
+const RUNTIME_SUBDIR = '.runtime';
+
+/**
+ * 向上查找含 .sillyspec 目录的祖先目录——实现已收敛至 src/run/shared.js（单一真相源，
+ * 含 home 拒绝守卫），此处 re-export。见顶部 import 说明。
+ */
+
+/**
+ * 平台指针不可达错误。pointer 存在但失效时抛出，阻止静默回退到本地孤儿 db。
+ * 逃生口：显式 --spec-dir 绕过 pointer 校验。
+ */
+export class PointerUnreachableError extends Error {
+  constructor({ pointerPath, specRoot, reason, hint }) {
+    super(
+      `平台指针不可用：${reason}\n` +
+      `  pointer: ${pointerPath}\n` +
+      `  specRoot: ${specRoot || '(缺失)'}\n` +
+      `修复：${hint}`
+    );
+    this.name = 'PointerUnreachableError';
+    this.pointerPath = pointerPath;
+    this.specRoot = specRoot || null;
+  }
+}
+
+/**
+ * 平台接管声明生效错误（指针缺失但声明存在）。fail-closed 入口一：
+ * 防指针被 cleanup/STALE 清理或项目挪动后裸调静默建本地进度库（状态分裂根因）。
+ *
+ * ⚠️ 不覆写 this.name（保持父类的 'PointerUnreachableError'）——CLI 顶层 catch 按
+ * err?.name === 'PointerUnreachableError' 严格字符串匹配（index.js），子类改名会
+ * 落通用错误分支打 stack noise。靠 message 首行"平台接管声明生效"区分场景。
+ */
+export class PlatformManagedError extends PointerUnreachableError {
+  constructor({ declarationPath, specRoot }) {
+    super({
+      pointerPath: declarationPath,
+      specRoot,
+      reason: `平台接管声明生效——本项目已由平台托管，但恢复指针缺失（可能被 platform pointer --cleanup 清理或项目目录被移动），拒绝静默回退本地模式`,
+      hint: `① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录`,
+    });
+    this.declarationPath = declarationPath;
+  }
+}
+
+/**
+ * 平台感知的 specDir 解析（fail-closed，所有 CLI 子命令统一入口）。
+ *
+ * 优先级：显式 --spec-dir > pointer.specRoot（可达）> resolveSpecDir(cwd)。
+ *
+ * fail-closed 语义（修复"状态穿越"定时炸弹）：
+ *   一旦项目进入过平台模式（pointer 文件存在），pointer 失效（specRoot 不可达 /
+ *   损坏 / 缺字段）不再静默回退到本地——否则会读到切平台前的过期本地 db。
+ *   此时抛 PointerUnreachableError，由 CLI 顶层捕获并打印修复引导。
+ *
+ *   无 pointer = 纯本地项目（从未平台 scan），正常走本地解析，不受影响。
+ */
+export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
+  if (explicitSpecDir) return resolve(explicitSpecDir);
+  const pointerPath = join(resolve(cwd), '.sillyspec-platform.json');
+  if (!existsSync(pointerPath)) {
+    // 指针缺失：查平台接管声明（fail-closed 入口一）。声明存在 = 项目进过平台模式，
+    // 指针丢失不该静默当纯本地项目处理（会建本地进度库 → 状态分裂）。
+    const decl = checkPlatformManaged(cwd);
+    if (decl) {
+      throw new PlatformManagedError({
+        declarationPath: join(resolve(cwd), PLATFORM_MANAGED_FILENAME),
+        specRoot: decl.specRoot,
+      });
+    }
+    return resolveSpecDir(cwd);
+  }
+  // pointer 存在 = 进过平台模式，严格校验，不静默回退
+  let ptr;
+  try {
+    ptr = JSON.parse(readFileSync(pointerPath, 'utf8'));
+  } catch (e) {
+    throw new PointerUnreachableError({
+      pointerPath,
+      specRoot: null,
+      reason: `pointer 文件损坏（${e.message}）`,
+      hint: `sillyspec platform pointer --cleanup 删除后重跑平台 scan`,
+    });
+  }
+  if (!ptr.specRoot) {
+    throw new PointerUnreachableError({
+      pointerPath,
+      specRoot: null,
+      reason: 'pointer 缺少 specRoot 字段',
+      hint: `sillyspec platform pointer --cleanup 删除后重跑平台 scan`,
+    });
+  }
+  if (!existsSync(ptr.specRoot)) {
+    throw new PointerUnreachableError({
+      pointerPath,
+      specRoot: ptr.specRoot,
+      reason: 'pointer.specRoot 路径不存在（daemon 未起？已迁移？）',
+      hint: `启动 SillyHub daemon；或 sillyspec doctor --json 诊断；或显式 --spec-dir <本地路径> 临时走本地`,
+    });
+  }
+  // 驾驭：pointer 指向 OS temp 目录几乎肯定是陈旧测试/CI 残留（合法项目不会把 specRoot 放 temp）。
+  // 历史：npm test 等会写 pointer 到 Temp/spec-dir-test-*，不清理则污染真实环境，所有命令静默落错库。
+  // 非阻断警告：让 agent 知道当前解析到的 specDir 可疑，而非静默写到死库。
+  const resolvedTmp = resolve(tmpdir());
+  if (resolve(ptr.specRoot) === resolvedTmp || resolve(ptr.specRoot).startsWith(resolvedTmp + sep)) {
+    console.warn(
+      `⚠️  平台 pointer 的 specRoot 指向系统 temp 目录：${ptr.specRoot}\n` +
+      `   这通常是陈旧的测试/CI 残留，命令会写进这个可疑库而非你当前项目。\n` +
+      `   修复：sillyspec platform pointer --cleanup（删除 ${pointerPath}），或删除该 pointer 文件后回到项目目录重跑。`
+    );
+  }
+  return ptr.specRoot;
+}
+
+const CHANGES_SUBDIR = 'changes';
+// CURRENT_VERSION → ./progress/shared.js（W6 Step9d）
+// VALID_STAGES → ./progress/shared.js（W6 Step9c）
+// VALID_STATUSES → ./progress/step-store.js（updateStep 专用，本地化）
+
+
+// ── ProgressManager ──
+
+export class ProgressManager {
+  /** 模块级 DB 连接池：Map<dbPath, DB>（SEC-09/PERF-10，见 _ensureDB 注释） */
+  static _dbPool = new Map();
+
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.specDir] - 规范目录绝对路径（默认 cwd/.sillyspec）
+   */
+  constructor(opts = {}) {
+    this._customSpecDir = opts.specDir || null;
+    this._consistency = new ConsistencyDoctor(this);
+    this._changeRegistry = new ChangeRegistry(this);
+    this._stepStore = new StepStore(this);
+    this._stageMachine = new StageMachine(this);
+  }
+
+  // ── 路径工具 ──
+
+  /** 获取 specDir（优先自定义，否则向上查找含 .sillyspec 的目录，fallback 到 cwd/.sillyspec） */
+  _getSpecDir(cwd) {
+    if (this._customSpecDir) return this._customSpecDir;
+    // specDir 对给定 cwd 在进程生命周期内不变（.sillyspec 目录不会被移动），
+    // 按 cwd 缓存，避免每次路径解析都向上 existsSync 遍历目录树（热路径）。
+    if (!this._specDirCache) this._specDirCache = new Map();
+    const cached = this._specDirCache.get(cwd);
+    if (cached) return cached;
+    const resolved = resolveSpecDir(cwd);
+    this._specDirCache.set(cwd, resolved);
+    return resolved;
+  }
+
+  _runtimePath(cwd, ...parts) {
+    return join(this._getSpecDir(cwd), RUNTIME_SUBDIR, ...parts);
+  }
+
+  _changePath(cwd, changeName, ...parts) {
+    return join(this._getSpecDir(cwd), CHANGES_SUBDIR, changeName, ...parts);
+  }
+
+  _ensureRuntimeDir(cwd) {
+    const runtimeDir = this._runtimePath(cwd);
+    if (!existsSync(runtimeDir)) {
+      mkdirSync(runtimeDir, { recursive: true });
+      for (const d of ['artifacts', 'history', 'logs', 'templates']) {
+        mkdirSync(join(runtimeDir, d), { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * 懒初始化 DB 连接，缓存在实例上（better-sqlite3 同步 API，init 无 async）。
+   *
+   * SEC-09/PERF-10（2026-08-20 体检）：连接额外进模块级 Map<dbPath, DB> 单例——
+   * 一条平台命令此前会 new 多个 ProgressManager（triggerPull / sync / import 各建），
+   * 同一 sillyspec.db 被 open 3-5 次，每次重跑 PRAGMA + schema 探测，且多连接
+   * 提升 SQLITE_BUSY 概率、Windows 残留句柄影响文件替换。CLI 短进程生命周期内
+   * dbPath 不变，进程退出由 OS 回收句柄（node:sqlite 无显式泄漏）；进程内共享
+   * 单连接后 WAL 写竞争面反而缩小。
+   */
+  _ensureDB(cwd) {
+    if (!this._db) {
+      const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+      let db = ProgressManager._dbPool.get(dbPath);
+      if (!db) {
+        db = new DB(dbPath);
+        db.init();
+        ProgressManager._dbPool.set(dbPath, db);
+      }
+      this._db = db;
+    }
+    return this._db;
+  }
+
+  _ensureChangeDir(cwd, changeName) {
+    const dir = this._changePath(cwd, changeName);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  // ── 全局状态 ──
+
+  readGlobal(cwd) {
+    // SQL: SELECT FROM project + changes
+    const db = this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+
+    // 读取 project 行（id=1）
+    const row = sqlDb.prepare('SELECT name, schema_version FROM project WHERE id = 1').get();
+    if (row === undefined) return null;
+    const { name, schema_version: schemaVersion } = row;
+
+    // 读取 active 变更列表
+    const changeRows = sqlDb.prepare("SELECT name FROM changes WHERE status = 'active' ORDER BY name").all();
+    const activeChanges = changeRows.map(r => r.name);
+
+    return {
+      _version: schemaVersion,
+      project: name,
+      activeChanges,
+    };
+  }
+
+  // ── 变更级别状态 ──
+
+  /**
+   * 读取指定变更的 progress（SQL 版）
+   * @param {string} cwd
+   * @param {string|null} changeName - 变更名，null 时尝试自动检测
+   * @returns {object|null} 与 SQLite 查询结果一致的 JS 对象
+   */
+  read(cwd, changeName = null) {
+    // 自动检测变更名（listChanges 已在 task-08 同步化，此处直接拿到活跃变更数组）
+    if (!changeName) {
+      const changes = this.listChanges(cwd);
+      if (changes.length === 1) {
+        changeName = changes[0];
+      } else {
+        // 多个或零个活跃变更，无法确定
+        return null;
+      }
+    }
+
+    const db = this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+
+    // 1. 从 changes 表获取基本信息
+    const changeRow = sqlDb.prepare('SELECT id, name, current_stage, no_worktree, last_active FROM changes WHERE name = ?').get(changeName);
+    if (changeRow === undefined) return null;
+    const { id: changeId, name: cName, current_stage: currentStage, no_worktree: noWorktree, last_active: lastActive } = changeRow;
+
+    // 2. 从 stages 表获取所有阶段（含 revision 列）
+    const stageRows = sqlDb.prepare('SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason FROM stages WHERE change_id = ? ORDER BY id').all(changeId);
+    const stageMap = {};
+    const stageIds = [];
+    for (const row of stageRows) {
+      const { id: sId, stage, status, started_at: startedAt, completed_at: completedAt, revision, reopened_from_step: reopenedFromStep, reopened_at: reopenedAt, stale_reason: staleReason } = row;
+      stageMap[stage] = { _dbId: sId, status, startedAt, completedAt,
+        ...(revision != null ? { revision } : {}),
+        ...(reopenedFromStep ? { reopenedFromStep } : {}),
+        ...(reopenedAt ? { reopenedAt } : {}),
+        ...(staleReason ? { staleReason } : {}),
+      };
+      stageIds.push(sId);
+    }
+
+    // 3. 从 steps 表获取所有步骤
+    const stepsByStage = {};
+    if (stageIds.length > 0) {
+      const placeholders = stageIds.map(() => '?').join(',');
+      const stepRows = sqlDb.prepare(
+        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+      ).all(...stageIds);
+      // 按阶段分组步骤
+      for (const row of stepRows) {
+        const { stage_id: stageId, name, status, output, completed_at: completedAt, wait_reason: waitReason, wait_options: waitOptions, wait_answer: waitAnswer, waited_at: waitedAt, wait_answers: waitAnswersJson, wait_round: waitRound, max_wait_rounds: maxWaitRounds } = row;
+        if (!stepsByStage[stageId]) stepsByStage[stageId] = [];
+        let waitAnswers = null;
+        if (waitAnswersJson) {
+          try { waitAnswers = JSON.parse(waitAnswersJson); } catch (e) { console.warn(`[progress] waitAnswers JSON 损坏，已跳过: ${e.message}`); }
+        }
+        stepsByStage[stageId].push({
+          name, status, output, completedAt,
+          ...(waitReason ? { waitReason } : {}),
+          ...(waitOptions ? { waitOptions } : {}),
+          ...(waitAnswer ? { waitAnswer } : {}),
+          ...(waitedAt ? { waitedAt } : {}),
+          ...(waitAnswers ? { waitAnswers } : {}),
+          ...(waitRound != null ? { waitRound } : {}),
+          ...(maxWaitRounds != null ? { maxWaitRounds } : {}),
+        });
+      }
+    }
+
+    // 4. 从 batch_progress 表获取批量进度
+    const batchRow = sqlDb.prepare('SELECT total, completed, failed, skipped FROM batch_progress WHERE change_id = ?').get(changeId);
+    let batchProgress = undefined;
+    if (batchRow !== undefined) {
+      const { total, completed, failed, skipped } = batchRow;
+      batchProgress = { total, completed, failed, skipped };
+    }
+
+    // 5. 获取项目名
+    const projectRow = sqlDb.prepare('SELECT name FROM project WHERE id = 1').get();
+    const projectName = projectRow !== undefined ? projectRow.name : '';
+
+    // 6. 组装为兼容对象
+    const stages = {};
+    // 先填充所有 VALID_STAGES
+    for (const s of VALID_STAGES) {
+      stages[s] = emptyStage();
+    }
+    // 用 DB 数据覆盖
+    for (const [stage, info] of Object.entries(stageMap)) {
+      const steps = (stepsByStage[info._dbId] || []).map(s => ({
+        name: s.name,
+        status: s.status,
+        output: s.output,
+        completedAt: s.completedAt,
+        ...(s.waitReason ? { waitReason: s.waitReason } : {}),
+        ...(s.waitOptions ? { waitOptions: s.waitOptions } : {}),
+        ...(s.waitAnswer ? { waitAnswer: s.waitAnswer } : {}),
+        ...(s.waitedAt ? { waitedAt: s.waitedAt } : {}),
+        ...(s.waitAnswers ? { waitAnswers: s.waitAnswers } : {}),
+        ...(s.waitRound != null ? { waitRound: s.waitRound } : {}),
+        ...(s.maxWaitRounds != null ? { maxWaitRounds: s.maxWaitRounds } : {}),
+      }));
+      stages[stage] = {
+        status: info.status,
+        steps,
+        startedAt: info.startedAt,
+        completedAt: info.completedAt,
+        // Revision v1 fields
+        ...(info.revision ? { revision: info.revision } : {}),
+        ...(info.reopenedFromStep ? { reopenedFromStep: info.reopenedFromStep } : {}),
+        ...(info.reopenedAt ? { reopenedAt: info.reopenedAt } : {}),
+        ...(info.staleReason ? { staleReason: info.staleReason } : {}),
+      };
+    }
+
+    const result = {
+      _version: 5,
+      project: projectName,
+      currentChange: cName,
+      currentStage: currentStage || '',
+      lastActive: lastActive || null,
+      stages,
+    };
+
+    // noWorktree
+    if (noWorktree) result.noWorktree = true;
+
+    // batchProgress（仅在 DB 中有记录时才包含）
+    if (batchProgress) result.batchProgress = batchProgress;
+
+    return result;
+  }
+
+  /**
+   * 同步专用六表完整序列化（design §8/B1，task-02 / D-005@v2 / FR-07）。
+   * 与 read()（聚合视图，不读 approvals 且 changes 只投影五列）不同，本方法输出真正六表投影，
+   * 作为同步载体（ProgressManager.import() 的逆运算，task-03）。
+   *
+   * 输出契约（字段名 = DB 列名 snake_case，import 直接对列写回，round-trip 无映射损耗）：
+   *   project        { name, schema_version }                                        —— 全局单行稳定字段（id/created_at/updated_at 本地元数据不同步）
+   *   changes        [{ name, current_stage, status, last_active,
+   *                      last_synced_platform_ts, last_local_modified_ts }]           —— 只投影流程进度列；
+   *                     排除 isolation_* 系列 与 platform_* 系列（platform_change_id/workspace_id/last_sync/sync_enabled）
+   *                     以及 created_at（本地强相关，不同步，B2）
+   *   stages         [{ change_name, stage, status, started_at, completed_at,
+   *                      revision, reopened_from_step, reopened_at, stale_reason }]   —— 用 change_name+stage 替代 id 外键
+   *   steps          [{ change_name, stage, name, status, output, completed_at, ordering,
+   *                      wait_reason, wait_options, wait_answer, waited_at, wait_answers,
+   *                      wait_round, max_wait_rounds }]                               —— wait_options/wait_answers 透传 DB JSON 字符串
+   *   batch_progress [{ change_name, total, completed, failed, skipped }]
+   *   approvals      [{ change_name, status, requested_at, approved_by, approved_at, rejection_reason }]
+   * 可空列归一为 null（非 undefined，保证 JSON 往返键稳定）；不含 user/base_ts/pushed_at（D-015，sync.js 放 HTTP header）。
+   *
+   * @param {string} cwd
+   * @param {string|null} [changeName] - 空时单活跃变更自动推导（对齐 read()）；多/零活跃返回 null
+   * @returns {object|null} 六键同步 JSON；change 不存在或无法推导返回 null
+   */
+  serializeForSync(cwd, changeName = null) {
+    // 自动检测变更名（与 read() 同口径）：单活跃变更推导，多/零无法确定返回 null
+    if (!changeName) {
+      const changes = this.listChanges(cwd);
+      if (changes.length === 1) {
+        changeName = changes[0];
+      } else {
+        return null;
+      }
+    }
+
+    const db = this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+
+    // 1. changes 行（投影流程进度列 + name 标识）
+    const changeRow = sqlDb.prepare(
+      `SELECT id, name, current_stage, status, last_active, last_synced_platform_ts, last_local_modified_ts
+       FROM changes WHERE name = ?`
+    ).get(changeName);
+    if (changeRow === undefined) return null;
+    const changeId = changeRow.id;
+    const changeProj = {
+      name: changeRow.name,
+      current_stage: changeRow.current_stage,
+      status: changeRow.status,
+      last_active: changeRow.last_active,
+      last_synced_platform_ts: changeRow.last_synced_platform_ts ?? null,
+      last_local_modified_ts: changeRow.last_local_modified_ts ?? null,
+    };
+
+    // 2. project 全局单行（只投影稳定字段 name/schema_version；created_at/updated_at 是本地库元数据，
+    //    同步无意义且破坏 round-trip 跨库等值——与 changes 排除 created_at 同理，B2）
+    const projectRow = sqlDb.prepare(
+      'SELECT name, schema_version FROM project WHERE id = 1'
+    ).get();
+
+    // 3. stages（该 change 下，用 change_name+stage 表达外键）
+    const stageRows = sqlDb.prepare(
+      `SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason
+       FROM stages WHERE change_id = ? ORDER BY id`
+    ).all(changeId);
+    const stageJson = stageRows.map(r => ({
+      change_name: changeRow.name,
+      stage: r.stage,
+      status: r.status,
+      started_at: r.started_at ?? null,
+      completed_at: r.completed_at ?? null,
+      revision: r.revision ?? null,
+      reopened_from_step: r.reopened_from_step ?? null,
+      reopened_at: r.reopened_at ?? null,
+      stale_reason: r.stale_reason ?? null,
+    }));
+
+    // 4. steps（stage_id IN；用 change_name+stage 关联回 stage）
+    const stageIds = stageRows.map(r => r.id);
+    const stageIdToName = new Map(stageRows.map(r => [r.id, r.stage]));
+    let stepJson = [];
+    if (stageIds.length > 0) {
+      const placeholders = stageIds.map(() => '?').join(',');
+      const stepRows = sqlDb.prepare(
+        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options,
+                wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds
+         FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+      ).all(...stageIds);
+      stepJson = stepRows.map(r => ({
+        change_name: changeRow.name,
+        stage: stageIdToName.get(r.stage_id),
+        name: r.name,
+        status: r.status,
+        output: r.output ?? null,
+        completed_at: r.completed_at ?? null,
+        ordering: r.ordering ?? null,
+        wait_reason: r.wait_reason ?? null,
+        wait_options: r.wait_options ?? null,
+        wait_answer: r.wait_answer ?? null,
+        waited_at: r.waited_at ?? null,
+        wait_answers: r.wait_answers ?? null,
+        wait_round: r.wait_round ?? null,
+        max_wait_rounds: r.max_wait_rounds ?? null,
+      }));
+    }
+
+    // 5. batch_progress（无行则空数组，import 侧幂等）
+    const batchRow = sqlDb.prepare(
+      'SELECT total, completed, failed, skipped FROM batch_progress WHERE change_id = ?'
+    ).get(changeId);
+    const batchJson = batchRow !== undefined ? [{
+      change_name: changeRow.name,
+      total: batchRow.total,
+      completed: batchRow.completed,
+      failed: batchRow.failed,
+      skipped: batchRow.skipped,
+    }] : [];
+
+    // 6. approvals（read() 不读此表，serializeForSync 补齐；无行则空数组）
+    const approvalRow = sqlDb.prepare(
+      'SELECT status, requested_at, approved_by, approved_at, rejection_reason FROM approvals WHERE change_id = ?'
+    ).get(changeId);
+    const approvalJson = approvalRow !== undefined ? [{
+      change_name: changeRow.name,
+      status: approvalRow.status,
+      requested_at: approvalRow.requested_at ?? null,
+      approved_by: approvalRow.approved_by ?? null,
+      approved_at: approvalRow.approved_at ?? null,
+      rejection_reason: approvalRow.rejection_reason ?? null,
+    }] : [];
+
+    return {
+      project: projectRow || null,
+      changes: [changeProj],
+      stages: stageJson,
+      steps: stepJson,
+      batch_progress: batchJson,
+      approvals: approvalJson,
+    };
+  }
+
+  /**
+   * serializeForSync 的逆运算：把平台权威 JSON 原子写回本地 DB 的该 change 行（design §8/B1，task-03 / D-005@v2 / D-011 / FR-07）。
+   * ⚠️ 必须保护真实资产：import 前对 DB 做【独立】snapshot `.runtime/sillyspec.db.pre-import-<ts>.bak`，
+   *   不抢 _openWithFallback 的 `${dbPath}.bak`（gap5/R-08）；任何失败本地进度库不损坏。
+   *
+   * 语义：
+   * - 单个 DB.transaction() 包裹，原子重建 stages/steps/batch_progress/approvals 四表（任一失败整体回滚）
+   * - changes 行用 UPDATE 选择投影列（current_stage/status/last_active/last_synced_platform_ts/last_local_modified_ts），
+   *   保留 isolation_* / platform_* / created_at（本地强相关状态不被覆盖，B2；change 不存在时 INSERT 兜底平台新增）
+   * - import 后 last_synced_platform_ts 与 last_local_modified_ts 均置为 progressObj.pushed_at（D-013 例外：
+   *   不更新 now()——否则 now()>base_ts 下次 pull 误判冲突；pushed_at 由 sync.js pull() 从响应 header attach）
+   * - 本地确定性操作，失败 throw 中文（非 sync 类 Best Effort，CONVENTIONS #4）
+   *
+   * @param {string} cwd
+   * @param {object} progressObj - serializeForSync 输出 + sync.js 附加的 pushed_at
+   * @param {string|null} [changeName] - 空则从 progressObj.changes[0].name 推导
+   * @returns {ImportResult} { ok:true, imported:changeName, reason?, bakPath }
+   */
+  import(cwd, progressObj, changeName = null) {
+    if (!progressObj || typeof progressObj !== 'object') {
+      throw new Error('import 参数无效：progressObj 必须是 serializeForSync() 输出的六表 JSON 对象');
+    }
+
+    const cn = changeName || (progressObj.changes && progressObj.changes[0] && progressObj.changes[0].name);
+    if (!cn) {
+      throw new Error('import 缺少 changeName：无法定位目标 change（progressObj.changes[0].name 为空）');
+    }
+
+    // ⚠️ 必须保护真实资产：独立 .bak snapshot（前缀 pre-import- 区分于主 .bak 备份机制）
+    const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      throw new Error(`本地进度库不存在，无法 import：${dbPath}`);
+    }
+    const bakTs = new Date().toISOString().replace(/[:.]/g, '-');
+    const bakPath = this._runtimePath(cwd, `sillyspec.db.pre-import-${bakTs}.bak`);
+    // 体检 BUG-18：WAL 模式下最近已提交事务可能仍在 -wal 侧车，直接 copy 主库文件会拿到
+    // 缺尾部提交的快照（恢复时静默回退进度）。先尽力 checkpoint(TRUNCATE) 把 WAL 合并回主库；
+    // 他进程持连接致 checkpoint 不完全时，把 -wal 侧车一并备份，恢复侧才有完整提交
+    try {
+      this._ensureDB(cwd).getDb().exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    } catch { /* best-effort：失败退化为连 -wal 一起备份 */ }
+    copyFileSync(dbPath, bakPath);
+    const walSidecar = `${dbPath}-wal`;
+    if (existsSync(walSidecar)) {
+      try { copyFileSync(walSidecar, `${bakPath}-wal`); } catch { /* 侧车消失=已 checkpoint，无碍 */ }
+    }
+
+    const pushedAt = progressObj.pushed_at ?? null;
+    const now = new Date().toISOString();
+
+    try {
+      const db = this._ensureDB(cwd);
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+
+        // 1. changes 行：INSERT OR IGNORE 兜底平台新增 change；UPDATE 只覆盖投影列（保留本地隔离/平台/created_at 列）
+        sqlDb.prepare(
+          `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active)
+           VALUES (?, '', 'active', ?, ?)`
+        ).run(cn, now, now);
+        const ch = progressObj.changes && progressObj.changes[0];
+        sqlDb.prepare(
+          `UPDATE changes SET
+             current_stage = ?, status = ?, last_active = ?,
+             last_synced_platform_ts = ?, last_local_modified_ts = ?
+           WHERE name = ?`
+        ).run(
+          ch && ch.current_stage != null ? ch.current_stage : '',
+          ch && ch.status != null ? ch.status : 'active',
+          ch && ch.last_active != null ? ch.last_active : now,
+          pushedAt, pushedAt, cn
+        );
+        const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
+        const changeId = changeRow.id;
+
+        // 2. project 行：幂等确保存在（不覆盖已有全局行，round-trip 等值不受影响；仅补缺失）
+        const projExists = sqlDb.prepare('SELECT id FROM project WHERE id = 1').get();
+        if (projExists === undefined) {
+          const pj = progressObj.project || {};
+          sqlDb.prepare(
+            `INSERT INTO project (id, name, schema_version, created_at, updated_at)
+             VALUES (1, ?, ?, ?, ?)`
+          ).run(pj.name != null ? pj.name : 'project', pj.schema_version != null ? pj.schema_version : CURRENT_VERSION, now, now);
+        }
+
+        // 3. 重建 stages + steps：DELETE stages（ON DELETE CASCADE 级联删 steps），按 JSON 重建
+        sqlDb.prepare('DELETE FROM stages WHERE change_id = ?').run(changeId);
+        const stageToId = new Map();
+        for (const s of (progressObj.stages || [])) {
+          if (!s || !s.stage) continue;
+          sqlDb.prepare(
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          ).run(changeId, s.stage, s.status != null ? s.status : 'pending', s.started_at ?? null, s.completed_at ?? null,
+            s.revision != null ? s.revision : 0, s.reopened_from_step ?? null, s.reopened_at ?? null, s.stale_reason ?? null);
+          const row = sqlDb.prepare('SELECT id FROM stages WHERE change_id = ? AND stage = ?').get(changeId, s.stage);
+          stageToId.set(s.stage, row.id);
+        }
+        for (const st of (progressObj.steps || [])) {
+          if (!st || !st.name) continue;
+          const stageId = stageToId.get(st.stage);
+          if (stageId === undefined) continue; // 孤儿 step（stage 不在 JSON）跳过，不破坏完整性
+          sqlDb.prepare(
+            `INSERT INTO steps (stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          ).run(stageId, st.name, st.status != null ? st.status : 'pending', st.output ?? null, st.completed_at ?? null,
+            st.ordering != null ? st.ordering : 0, st.wait_reason ?? null, st.wait_options ?? null, st.wait_answer ?? null,
+            st.waited_at ?? null, st.wait_answers ?? null, st.wait_round ?? null, st.max_wait_rounds ?? null);
+        }
+
+        // 4. 重建 batch_progress（DELETE 再插，无行则清空）
+        sqlDb.prepare('DELETE FROM batch_progress WHERE change_id = ?').run(changeId);
+        const bp = progressObj.batch_progress && progressObj.batch_progress[0];
+        if (bp) {
+          sqlDb.prepare(
+            `INSERT INTO batch_progress (change_id, total, completed, failed, skipped)
+             VALUES (?, ?, ?, ?, ?)`
+          ).run(changeId, bp.total != null ? bp.total : 0, bp.completed != null ? bp.completed : 0,
+            bp.failed != null ? bp.failed : 0, bp.skipped != null ? bp.skipped : 0);
+        }
+
+        // 5. 重建 approvals（DELETE 再插，无行则清空）
+        sqlDb.prepare('DELETE FROM approvals WHERE change_id = ?').run(changeId);
+        const ap = progressObj.approvals && progressObj.approvals[0];
+        if (ap) {
+          sqlDb.prepare(
+            `INSERT INTO approvals (change_id, status, requested_at, approved_by, approved_at, rejection_reason)
+             VALUES (?, ?, ?, ?, ?, ?)`
+          ).run(changeId, ap.status != null ? ap.status : 'not_required', ap.requested_at ?? null, ap.approved_by ?? null,
+            ap.approved_at ?? null, ap.rejection_reason ?? null);
+        }
+      });
+    } catch (e) {
+      // 事务失败自动回滚（DB 未变），.bak 保留可恢复；fail-loud 中文
+      throw new Error(`import 失败，本地进度库已回滚（snapshot: ${bakPath}）：${e.message}`);
+    }
+
+    return { ok: true, imported: cn, reason: undefined, bakPath };
+  }
+
+  /**
+   * 本地脏度标记（D-013 / task-04）：写入路径末尾更新 changes.last_local_modified_ts。
+   * 在写方法的事务内调用则属于该事务（原子，失败整体回滚）；import 是例外不调本方法
+   * （import 自己把 last_local_modified_ts 置为 pushed_at，表示本地=平台干净）。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @param {string} [ts] - 复用调用方事务内的时间戳，保证与本次写入同时刻
+   */
+  _touchLocalModified(cwd, changeName, ts = null) {
+    if (!changeName) return;
+    const db = this._ensureDB(cwd);
+    const stamp = ts || new Date().toISOString();
+    db.getDb().prepare('UPDATE changes SET last_local_modified_ts = ? WHERE name = ?').run(stamp, changeName);
+  }
+
+  /**
+   * 写入指定变更的 progress
+   * @param {string} cwd
+   * @param {object} data
+   * @param {string|null} changeName - 从 data.currentChange 推导，或显式传入
+   *
+   * 持锁窗口评估（task-05 / R-08）：本方法采用全量 UPSERT——无条件 UPDATE changes 行 +
+   * 遍历所有 stages（每 stage UPSERT stages 行 + 每 step 先 DELETE 再 INSERT 全量 + 末尾
+   * DELETE data 中不存在的多余 step）。评估过改"只写 diff（仅写变更过的 change/stage/step 行）"
+   * 以缩小事务持锁窗口、降低 BUSY 概率，结论：保持现状（全量 UPSERT）。
+   * 理由：
+   *   1. steps 表无 UNIQUE 约束（见循环内 DELETE-then-INSERT 注释），diff 写需先读现状再逐条
+   *      比较，复杂度高易错，易引入孤儿/缺失步骤破坏 FK 级联语义（design §3/§8）；
+   *   2. busy_timeout=5000 + DB 层 SQLITE_BUSY 应用层有限重试（见 db.js transaction）已兜底
+   *      并发冲突，全量 UPSERT 的持锁窗口在此兜底下不是瓶颈；
+   *   3. 单进程内调用串行（design §9），事务窗口短（毫秒级），全量写正确性远高于 diff 的边际收益。
+   * 结论：全量 UPSERT 的简单正确性 > 持锁窗口优化的边际收益，不强行改 diff。
+   */
+  _write(cwd, data, changeName = null) {
+    const cn = changeName || data.currentChange;
+    if (!cn) {
+      console.warn('⚠️  _write: 无变更名，跳过写入');
+      return;
+    }
+
+    const db = this._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      // 1. 更新 changes 表（last_local_modified_ts 脏度：D-013 / task-04）
+      const now = new Date().toISOString();
+      const noWorktree = data.noWorktree ? 1 : 0;
+      sqlDb.prepare(
+        'UPDATE changes SET current_stage = ?, last_active = ?, no_worktree = ?, last_local_modified_ts = ? WHERE name = ?'
+      ).run(data.currentStage || '', now, noWorktree, now, cn);
+
+      // 2. 获取 change_id
+      const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
+      if (changeRow === undefined) return;
+      const changeId = changeRow.id;
+
+      // 3. 遍历 stages，UPSERT stages 表和 steps 表
+      if (data.stages && typeof data.stages === 'object') {
+        for (const [stageName, stageData] of Object.entries(data.stages)) {
+          // UPSERT stages 行（含 revision 列）
+          sqlDb.prepare(
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+             ON CONFLICT(change_id, stage) DO UPDATE SET
+               status = excluded.status,
+               started_at = excluded.started_at,
+               completed_at = excluded.completed_at,
+               revision = COALESCE(excluded.revision, stages.revision),
+               reopened_from_step = excluded.reopened_from_step,
+               reopened_at = excluded.reopened_at,
+               stale_reason = excluded.stale_reason`
+          ).run(changeId, stageName, stageData.status || 'pending', stageData.startedAt || null, stageData.completedAt || null,
+             stageData.revision || 0, stageData.reopenedFromStep || null, stageData.reopenedAt || null, stageData.staleReason || null);
+
+          // 获取 stage_id
+          const stageRow = sqlDb.prepare('SELECT id FROM stages WHERE change_id = ? AND stage = ?').get(changeId, stageName);
+          if (stageRow === undefined) continue;
+          const stageId = stageRow.id;
+
+          // 收集 data 中的步骤名
+          const stepNames = new Set();
+          if (Array.isArray(stageData.steps)) {
+            for (let i = 0; i < stageData.steps.length; i++) {
+              const step = stageData.steps[i];
+              stepNames.add(step.name);
+              // UPSERT 步骤（先删再插，steps 表无 UNIQUE 约束）
+              sqlDb.prepare('DELETE FROM steps WHERE stage_id = ? AND name = ?').run(stageId, step.name);
+              sqlDb.prepare(
+                'INSERT INTO steps (stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'
+              ).run(stageId, step.name, step.status || 'pending', step.output || null, step.completedAt || null, i,
+                  step.waitReason ?? null, Array.isArray(step.waitOptions) ? JSON.stringify(step.waitOptions) : (step.waitOptions ?? null), step.waitAnswer ?? null, step.waitedAt ?? null,
+                  Array.isArray(step.waitAnswers) ? JSON.stringify(step.waitAnswers) : null,
+                  step.waitRound ?? null, step.maxWaitRounds ?? null);
+            }
+          }
+
+          // 删除 data 中不存在的多余步骤
+          if (stepNames.size > 0) {
+            const namePlaceholders = [...stepNames].map(() => '?').join(',');
+            sqlDb.prepare(
+              `DELETE FROM steps WHERE stage_id = ? AND name NOT IN (${namePlaceholders})`
+            ).run(stageId, ...stepNames);
+          } else {
+            // data 中没有步骤，清空该阶段所有步骤
+            sqlDb.prepare('DELETE FROM steps WHERE stage_id = ?').run(stageId);
+          }
+        }
+      }
+
+      // 4. UPSERT batch_progress
+      if (data.batchProgress && typeof data.batchProgress === 'object') {
+        sqlDb.prepare(
+          `INSERT INTO batch_progress (change_id, total, completed, failed, skipped)
+           VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(change_id) DO UPDATE SET
+             total = excluded.total,
+             completed = excluded.completed,
+             failed = excluded.failed,
+             skipped = excluded.skipped`
+        ).run(changeId, data.batchProgress.total || 0, data.batchProgress.completed || 0, data.batchProgress.failed || 0, data.batchProgress.skipped || 0);
+      }
+    });
+  }
+
+  // ── 变更管理 ──
+
+  listChanges(cwd) { return this._changeRegistry.listChanges(cwd); }
+
+  // 单变更阶段查询（quick 轻量归档阶段闸）：无行 null，读失败抛（调用方 fail-closed）
+  getChangeStage(cwd, changeName) { return this._changeRegistry.getChangeStage(cwd, changeName); }
+
+  registerChange(cwd, changeName) { return this._changeRegistry.registerChange(cwd, changeName); }
+
+  updateChangeIsolation(cwd, changeName, isolation) { return this._changeRegistry.updateChangeIsolation(cwd, changeName, isolation); }
+
+  readChangeIsolation(cwd, changeName) { return this._changeRegistry.readChangeIsolation(cwd, changeName); }
+
+  // syncedTs 透传（ql-20260818-008）：push 成功推进 base_ts，facade 曾丢参致列永不写入
+  _updatePlatformLastSync(cwd, changeName, syncedTs = null) { return this._changeRegistry._updatePlatformLastSync(cwd, changeName, syncedTs); }
+
+  _updateApprovalStatus(cwd, changeName, status, reason = null) { return this._changeRegistry._updateApprovalStatus(cwd, changeName, status, reason); }
+
+  renameChange(cwd, oldName, newName) { return this._changeRegistry.renameChange(cwd, oldName, newName); }
+
+  // opts.archiveStepNames 给定时做归档终态一致化收尾（见 change-registry.unregisterChange 注释，
+  // 坑 manual-archive-desync-status-only）；archiveStepNamesForArchive() 取 stageRegistry 单一真相
+  //（stages/* 不反向依赖 progress.js，静态 import 无环）。
+  unregisterChange(cwd, changeName, opts) { return this._changeRegistry.unregisterChange(cwd, changeName, opts); }
+
+  archiveStepNamesForArchive() {
+    if (!this._archiveStepNamesCache) {
+      const defs = stageRegistry?.archive?.steps
+      this._archiveStepNamesCache = Array.isArray(defs) ? defs.map(s => s.name) : []
+    }
+    return this._archiveStepNamesCache
+  }
+
+  updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
+
+  // ── CLI 命令 ──
+
+  init(cwd) {
+    this._ensureRuntimeDir(cwd);
+
+    // 初始化 DB（如不存在则创建文件 + 建表）
+    const db = this._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      const now = new Date().toISOString();
+      const projectName = basename(cwd) || 'project';
+
+      // 检查 project id=1 是否已存在
+      const existing = sqlDb.prepare('SELECT id FROM project WHERE id = 1').get();
+      if (existing === undefined) {
+        sqlDb.prepare(
+          `INSERT INTO project (id, name, schema_version, created_at, updated_at)
+           VALUES (1, ?, ?, ?, ?)`
+        ).run(projectName, CURRENT_VERSION, now, now);
+        console.log(`✅ 已创建全局状态文件（SQLite）`);
+      } else {
+        console.log(`ℹ️  全局状态文件已存在，跳过`);
+      }
+    });
+
+    // 创建 user-inputs.md
+    const inputsPath = this._runtimePath(cwd, 'user-inputs.md');
+    if (!existsSync(inputsPath)) {
+      writeFileSync(inputsPath, '# 用户输入记录\n\n> 每步完成时由 AI 自动追加，记录用户所有原话。\n\n');
+    }
+
+    this._ensureGitignore(cwd);
+    return this.readGlobal(cwd);
+  }
+
+  /**
+   * 初始化指定变更的 progress
+   * SQL: INSERT changes + 批量 INSERT stages
+   */
+  initChange(cwd, changeName, meta = {}) {
+    if (!changeName) {
+      console.warn('⚠️  initChange: changeName 为空，跳过');
+      return null;
+    }
+    // quick 会话 id（quick-<uuid8>，见 run.js QUICK_SID_RE）只作 progress 的跨进程 session key，
+    // 进度存 SQL 不需要实体 change 目录——跳过避免 changes/quick-<uuid>/ 空目录残留。
+    if (!/^quick-[0-9a-f]{8}$/.test(changeName)) {
+      this._ensureChangeDir(cwd, changeName);
+    }
+
+    const db = this._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      const now = new Date().toISOString();
+
+      // 检查变更是否已存在
+      const existing = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+      if (existing === undefined) {
+        // 插入 changes 行
+        sqlDb.prepare(
+          `INSERT INTO changes (name, current_stage, status, created_at, last_active, title, quicklog_id)
+           VALUES (?, 'scan', 'active', ?, ?, ?, ?)`
+        ).run(changeName, now, now, meta.title || null, meta.quicklogId || null);
+      }
+
+      // 获取 change_id
+      const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+      const changeId = changeRow.id;
+
+      // 批量插入所有合法阶段（INSERT OR IGNORE 跳过已存在的）；沿用顶部 import 的 VALID_STAGES 单一源
+      for (const stage of VALID_STAGES) {
+        sqlDb.prepare(
+          `INSERT OR IGNORE INTO stages (change_id, stage, status)
+           VALUES (?, ?, 'pending')`
+        ).run(changeId, stage);
+      }
+      // 本地脏度（D-013 / task-04）：新建 change 视为有未同步数据
+      this._touchLocalModified(cwd, changeName, now);
+    });
+
+    // 不再需要写文件：read() 已改为 SQL
+    return this.read(cwd, changeName);
+  }
+
+  setStage(cwd, stage, changeName = null) { return this._stepStore.setStage(cwd, stage, changeName); }
+
+  addStep(cwd, stage, stepName, changeName = null) { return this._stepStore.addStep(cwd, stage, stepName, changeName); }
+
+  updateStep(cwd, stage, stepName, options = {}, changeName = null) { return this._stepStore.updateStep(cwd, stage, stepName, options, changeName); }
+
+  _appendAuditLog(cwd, entry) { return this._consistency._appendAuditLog(cwd, entry); }
+
+  _validateStageArtifacts(cwd, stage, changeName) { return this._stageMachine._validateStageArtifacts(cwd, stage, changeName); }
+
+  completeStage(cwd, stage, changeName = null, opts = {}) { return this._stageMachine.completeStage(cwd, stage, changeName, opts); }
+
+  show(cwd, changeName = null) { return this._stageMachine.show(cwd, changeName); }
+
+  _showChange(cwd, changeName) { return this._stageMachine._showChange(cwd, changeName); }
+
+  _getNextSuggestion(data) { return this._stageMachine._getNextSuggestion(data); }
+
+  status(cwd, changeName = null) { return this._stageMachine.status(cwd, changeName); }
+
+  checkConsistency(cwd, changeName = null) { return this._consistency.checkConsistency(cwd, changeName); }
+
+  repairConsistency(cwd, opts = {}) { return this._consistency.repairConsistency(cwd, opts); }
+
+  validate(cwd, changeName = null) { return this._stageMachine.validate(cwd, changeName); }
+
+  reopenStage(cwd, stage, opts = {}) { return this._stageMachine.reopenStage(cwd, stage, opts); }
+
+  _getDownstreamStages(stage) { return this._stageMachine._getDownstreamStages(stage); }
+
+  reset(cwd, stage, changeName = null) { return this._stageMachine.reset(cwd, stage, changeName); }
+
+  // ── 内部辅助 ──
+
+  _readOrInit(cwd, changeName = null) {
+    let data = this.read(cwd, changeName);
+    if (!data) {
+      // 尝试自动检测变更名
+      if (!changeName) {
+        const changes = this.listChanges(cwd);
+        if (changes.length === 1) changeName = changes[0];
+      }
+      if (changeName) {
+        // 确保变更在 DB 中已初始化
+        const db = this._ensureDB(cwd);
+        db.transaction(() => {
+          const sqlDb = db.getDb();
+          const now = new Date().toISOString();
+          const ins = sqlDb.prepare(
+            `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active) VALUES (?, 'scan', 'active', ?, ?)`
+          ).run(changeName, now, now);
+          const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+          if (changeRow !== undefined) {
+            const changeId = changeRow.id;
+            for (const s of VALID_STAGES) {
+              sqlDb.prepare(`INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, 'pending')`).run(changeId, s);
+            }
+          }
+          // 只在真正创建 change 时标脏（D-013/task-04）；读路径（change 已存在）不标，避免 pull 误判本地有未同步改动
+          if (ins.changes > 0) this._touchLocalModified(cwd, changeName, now);
+        });
+        this.registerChange(cwd, changeName);
+      }
+      if (!data) {
+        data = this.read(cwd, changeName);
+      }
+      if (!data) {
+        console.log('❌ 无法确定当前变更，请指定 --change <name>');
+        return null;
+      }
+    }
+    return data;
+  }
+
+  _requireStage(cwd, stage, changeName = null) {
+    if (!VALID_STAGES.includes(stage)) {
+      console.log(`❌ 未知阶段: ${stage}，可选: ${VALID_STAGES.join(', ')}`);
+      return null;
+    }
+    const data = this._readOrInit(cwd, changeName);
+    if (!data) return null;
+    if (!data.stages[stage]) data.stages[stage] = emptyStage();
+    return data;
+  }
+
+  _timeAgo(dateStr) { return this._stageMachine._timeAgo(dateStr); }
+
+  // ── 批量进度 ──
+
+  updateBatchProgress(cwd, batchData, changeName = null) { return this._stepStore.updateBatchProgress(cwd, batchData, changeName); }
+
+  readBatchProgress(cwd, changeName = null) { return this._stepStore.readBatchProgress(cwd, changeName); }
+
+  _renderBatchProgress(batchProgress) { return this._stepStore._renderBatchProgress(batchProgress); }
+
+  _ensureGitignore(cwd) {
+    // 外部 specDir 不需要修改项目 .gitignore
+    if (this._customSpecDir) return;
+    const gitignorePath = join(cwd, '.gitignore');
+    const rule = '.sillyspec/.runtime/';
+    if (existsSync(gitignorePath)) {
+      const content = readFileSync(gitignorePath, 'utf8');
+      if (content.includes(rule)) return;
+      // 按既有 EOL 追加（2026-08-21 审查 BUG-9）：CRLF 检出的文件混入 LF 行产生全文件
+      // diff 噪声/autocrlf 折腾；写走原子 rename 防并发 init 双跑交错
+      const eol = content.includes('\r\n') ? '\r\n' : '\n';
+      writeAtomicSync(gitignorePath, content.trimEnd() + eol + rule + eol);
+    } else {
+      writeAtomicSync(gitignorePath, rule + '\n');
+    }
+  }
+
+  // ── plan.md 对齐（doctor --align-execute-progress 入口）──
+
+  /**
+   * 解析 changeDir/tasks.md（任务注册表唯一真相）的 task checkbox 统计。
+   * 2026-08-20-task-truth-unify：源从「plan.md 优先回退 tasks.md」改为 tasks.md 唯一源——
+   * 旧顺序下新契约 plan.md（纯 ID 引用行）恒 total=0，doctor --align-execute-progress 会静默失效。
+   * tasks.md 缺失时回退 plan.md（旧归档变更兼容读侧，不写侧迁移）。
+   * 仅匹配 `- [ ] task-NN` / `- [x] task-NN` 形态的行（task- 前缀锚定，避免误捞非任务项）。
+   * @param {string} changeDir - 变更目录绝对路径（含 tasks.md/plan.md）
+   * @returns {{ total: number, checked: number }}
+   */
+  readPlanCheckboxStatus(changeDir) {
+    if (!changeDir || typeof changeDir !== 'string') {
+      throw new Error('changeDir 不能为空');
+    }
+    const tasksPath = join(changeDir, 'tasks.md');
+    const planPath = join(changeDir, 'plan.md');
+    let content = null;
+    if (existsSync(tasksPath)) {
+      content = readFileSync(tasksPath, 'utf8');
+    } else if (existsSync(planPath)) {
+      content = readFileSync(planPath, 'utf8');
+    } else {
+      return { total: 0, checked: 0 };
+    }
+    // 匹配 `- [ ] task-NN` / `- [x] task-NN`（允许 [x] 大小写、空格弹性、task- 前缀）
+    const re = /^\s*[-*]\s+\[([ xX])\]\s+task-\d+/gm;
+    let total = 0;
+    let checked = 0;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      total++;
+      if (m[1] === 'x' || m[1] === 'X') checked++;
+    }
+    return { total, checked };
+  }
+
+  /**
+   * 按 plan.md 声明对齐 execute 阶段派生进度戳。
+   * 仅当 plan.md 所有 task checkbox 全勾时，把 execute 阶段所有非 completed step 标 completed，
+   * 并显式置 execute stageData.status='completed' + completedAt（绕过 completeStep 推导，D-003@v2）。
+   * 不复核代码，信任 plan.md 声明（与 archive 同源，verify 阶段兜底，D-002/D-004）。
+   *
+   * @param {string} cwd
+   * @param {string} changeName
+   * @param {string} specBase - platformOpts.specRoot || join(cwd, '.sillyspec')，用于定位 changes 目录
+   * @param {object} [opts]
+   * @param {boolean} [opts.confirm=false] - 默认 dry-run，仅当 confirm=true 才落盘
+   * @returns {{ ok: boolean, aligned: number, skipped: number, planTotal: number, planChecked: number, reason?: string, dryRun?: boolean }}
+   */
+  alignExecuteToPlan(cwd, changeName, specBase, opts = {}) {
+    if (!changeName) throw new Error('changeName 不能为空');
+    const { confirm = false } = opts;
+
+    // 1. 读 progress；无 progress / 无 execute 阶段 → 拒绝
+    const progress = this.read(cwd, changeName);
+    if (!progress || !progress.stages || !progress.stages.execute) {
+      return { ok: false, aligned: 0, skipped: 0, planTotal: 0, planChecked: 0, reason: 'execute 阶段无进度数据' };
+    }
+    const executeStage = progress.stages.execute;
+    const steps = Array.isArray(executeStage.steps) ? executeStage.steps : [];
+    if (steps.length === 0) {
+      return { ok: false, aligned: 0, skipped: 0, planTotal: 0, planChecked: 0, reason: 'execute 阶段无进度数据' };
+    }
+
+    // 2. 读 plan.md checkbox；未全勾 → 拒绝（D-002）
+    const specRoot = specBase || this._getSpecDir(cwd);
+    const changeDir = join(specRoot, CHANGES_SUBDIR, changeName);
+    const { total: planTotal, checked: planChecked } = this.readPlanCheckboxStatus(changeDir);
+    if (planTotal === 0) {
+      return { ok: false, aligned: 0, skipped: 0, planTotal, planChecked, reason: 'plan.md 无 task checkbox（无法判定完成度）' };
+    }
+    if (planChecked < planTotal) {
+      return {
+        ok: false,
+        aligned: 0,
+        skipped: 0,
+        planTotal,
+        planChecked,
+        reason: `plan.md 有未勾选 task（${planChecked}/${planTotal}），拒绝对齐`,
+      };
+    }
+
+    // 2.5 最低事实核验：plan.md checkbox 可被手动勾选伪造，
+    // 对齐前用 git 客观核验是否存在真实代码变更（能确证零变更时才拒绝，
+    // unknown 不阻断——worktree 已清理且变更已提交的正常场景无法对账）。
+    try {
+      const evidence = checkExecuteCodeEvidence(cwd, changeName);
+      if (evidence.status === 'unchanged') {
+        return {
+          ok: false,
+          aligned: 0,
+          skipped: 0,
+          planTotal,
+          planChecked,
+          reason: `plan.md 全勾但代码零变更（${evidence.detail}），拒绝对齐 — 请先运行 sillyspec doctor --json 诊断`,
+        };
+      }
+    } catch (e) {
+      console.warn(`⚠️  代码变更核验异常（不阻断对齐）: ${e.message}`);
+    }
+
+    // 3. 全勾：计算将补哪些 step
+    const now = new Date().toISOString();
+    let aligned = 0;
+    let skipped = 0;
+    for (const step of steps) {
+      if (step.status === 'completed') {
+        skipped++;
+        continue;
+      }
+      aligned++;
+      if (confirm) {
+        step.status = 'completed';
+        step.completedAt = now;
+      }
+    }
+
+    // dry-run：只报告，不落盘
+    if (!confirm) {
+      return { ok: true, aligned, skipped, planTotal, planChecked, dryRun: true };
+    }
+
+    // 4. confirm：显式置 execute stageData.status='completed' + completedAt（D-003@v2，复刻 run.js:2303-2304）
+    executeStage.status = 'completed';
+    executeStage.completedAt = now;
+    progress.currentStage = progress.currentStage || 'execute';
+    progress.lastActive = now;
+    this._write(cwd, progress, changeName);
+
+    return { ok: true, aligned, skipped, planTotal, planChecked };
+  }
+
+  // ── 只读 dump（task-01/02/03：daemon 进度读取）──
+
+  /**
+   * dump 输出的时间戳规范化：DB 内部两类形态（步骤推进时 JS Date 变量序列化
+   * 的 ISO 形态、部分历史路径写入的 `YYYY/M/D H:mm:ss` 斜杠形态）统一转 ISO。
+   * backend pydantic datetime 只吃 ISO（斜杠形态校验失败），斜杠 → new Date
+   * 可解析；解析失败原样返回（backend 侧按无效丢弃）。
+   */
+  _dumpIso(ts) {
+    if (!ts) return ts;
+    if (typeof ts === 'string' && /^\d{4}-\d{2}-\d{2}/.test(ts)) return ts;
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime())) return ts;
+    return d.toISOString();
+  }
+
+  /**
+   * 只读导出进度数据，供 daemon 通过 `sillyspec progress dump --json` 消费。
+   *
+   * 纯读路径：打开 DB 只读、读 user-inputs.md、列 artifacts 目录，不写任何状态。
+   * 无活跃变更或 DB 不存在时返回 null（不抛异常，daemon 按 null 处理空数据）。
+   *
+   * 输出字段 snake_case + ISO 时间戳（2026-08-19-runtime-live-daemon-read
+   * acceptance review P0 修复）：契约消费端 backend RuntimeProgress pydantic
+   * 是 snake_case（current_stage/last_active/started_at/size_bytes），
+   * dump 早期误用内部 camelCase；跨端字段名断裂会让 pydantic 静默忽略
+   * 未知字段导致前端核心字段全空。
+   *
+   * @param {string} cwd - specDir（`.sillyspec` 目录），由 CLI 层 --spec-dir 传入
+   * @returns {object|null} 结构化进度数据，格式见 design.md §6.2
+   */
+  dump(cwd) {
+    const specRoot = this._getSpecDir(cwd);
+    const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+
+    // DB 不存在 → 返回 null（项目未初始化进度）
+    if (!existsSync(dbPath)) return null;
+
+    const db = this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+
+    // 1. project 行
+    const projectRow = sqlDb.prepare('SELECT name FROM project WHERE id = 1').get();
+    if (projectRow === undefined) return null;
+    const projectName = projectRow.name;
+
+    // 2. 活跃变更（取 last_active 最新的一个）
+    // ql-20260821-003：多活跃仓（变更隔离是常态，单仓可同时存在 N 个 active）下
+    // 原 ORDER BY name 恒取字典序最前（通常是最老的变更），「当前变更/最后活动」
+    // 停留在历史数据。dump 语义是「当前工作流状态」→ 取最近活跃的那个。
+    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY last_active DESC").all();
+    if (changeRows.length === 0) {
+      // 无活跃变更 → 返回仅含 project 的骨架
+      return {
+        project: projectName,
+        current_stage: null,
+        current_change: null,
+        last_active: null,
+        stages: {},
+        user_inputs: this._readUserInputs(cwd),
+        artifacts: this._listArtifacts(cwd),
+      };
+    }
+
+    const change = changeRows[0];
+    const { id: changeId, name: changeName, current_stage: currentStage, last_active: lastActive } = change;
+
+    // 3. stages
+    const stageRows = sqlDb.prepare(
+      'SELECT id, stage, status, started_at, completed_at, revision FROM stages WHERE change_id = ? ORDER BY id'
+    ).all(changeId);
+
+    const stages = {};
+    for (const s of VALID_STAGES) {
+      stages[s] = { status: 'pending', steps: [] };
+    }
+    // PERF-06：一次 IN (...) 批量取全部 steps 再按 stage_id 分组（原逐 stage 查询是 N+1，
+    // dump 是 daemon 轮询接口；与 read() :283-287 的批量读法对齐）
+    const stepsByStage = new Map();
+    if (stageRows.length > 0) {
+      const placeholders = stageRows.map(() => '?').join(', ');
+      const allStepRows = sqlDb.prepare(
+        `SELECT stage_id, name, status, output, completed_at FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+      ).all(...stageRows.map(r => r.id));
+      for (const sr of allStepRows) {
+        if (!stepsByStage.has(sr.stage_id)) stepsByStage.set(sr.stage_id, []);
+        stepsByStage.get(sr.stage_id).push(sr);
+      }
+    }
+    for (const row of stageRows) {
+      const stepRows = stepsByStage.get(row.id) || [];
+      stages[row.stage] = {
+        status: row.status,
+        started_at: this._dumpIso(row.started_at) || undefined,
+        completed_at: this._dumpIso(row.completed_at) || undefined,
+        ...(row.revision ? { revision: row.revision } : {}),
+        steps: stepRows.map(sr => ({
+          name: sr.name,
+          status: sr.status,
+          ...(sr.output ? { output: sr.output } : {}),
+          ...(sr.completed_at ? { completed_at: this._dumpIso(sr.completed_at) } : {}),
+        })),
+      };
+    }
+
+    return {
+      project: projectName,
+      current_stage: currentStage || null,
+      current_change: changeName,
+      last_active: this._dumpIso(lastActive) || null,
+      stages,
+      user_inputs: this._readUserInputs(cwd),
+      artifacts: this._listArtifacts(cwd),
+    };
+  }
+
+  /** 只读 user-inputs.md 内容（不存在返回 null） */
+  _readUserInputs(cwd) {
+    const p = this._runtimePath(cwd, 'user-inputs.md');
+    if (!existsSync(p)) return null;
+    return readFileSync(p, 'utf8');
+  }
+
+  /** 列 artifacts 目录（不存在返回空数组） */
+  _listArtifacts(cwd) {
+    const dir = this._runtimePath(cwd, 'artifacts');
+    if (!existsSync(dir)) return [];
+    try {
+      return readdirSync(dir, { withFileTypes: true })
+        .filter(e => e.isFile())
+        .map(e => {
+          const fullPath = join(dir, e.name);
+          const st = statSync(fullPath);
+          return {
+            filename: e.name,
+            size_bytes: st.size,
+            last_modified: st.mtime.toISOString(),
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
+}