sillyspec 3.25.1 → 3.25.2

package/src/progress.js

@@ -11,12 +11,18 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync } from 'fs';
-import { join, basename, dirname, resolve } from 'path';
+import { join, basename, dirname, resolve, sep } from 'path';
+import { tmpdir } from 'os';
 import { DB } from './db.js';
 import { writeAtomicSync } from './fs-atomic.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 { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './progress/shared.js';
 
 // 默认规范目录名（相对于 cwd）
-const SPEC_DIR_NAME = '.sillyspec';
+// SPEC_DIR_NAME → ./progress/shared.js（W6 Step9d）
 const RUNTIME_SUBDIR = '.runtime';
 
 /**
@@ -99,37 +105,33 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
       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';
-const CURRENT_VERSION = 3;
-const VALID_STAGES = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
-const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting', 'stale'];
+// CURRENT_VERSION → ./progress/shared.js（W6 Step9d）
+// VALID_STAGES → ./progress/shared.js（W6 Step9c）
+// VALID_STATUSES → ./progress/step-store.js（updateStep 专用，本地化）
 
 // Stage statuses (superset of step statuses)
 const VALID_STAGE_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'revising', 'stale'];
 
-// Main flow stage order (for downstream cascade)
-// 完整主流程顺序（含 scan），用于下游 cascade
-const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive'];
-// 主流程阶段（不含 scan/quick/explore 等辅助阶段）
-const MAIN_FLOW_ORDER = STAGE_ORDER;
-
-const STAGE_LABELS = {
-  brainstorm: '🧠 需求探索',
-  plan: '📐 实现计划',
-  execute: '⚡ 波次执行',
-  verify: '🔍 验证确认',
-  scan: '🔍 代码扫描',
-  quick: '⚡ 快速任务',
-  explore: '🧭 自由探索',
-  archive: '📦 归档变更',
-};
-
-function emptyStage() {
-  return { status: 'pending', steps: [], startedAt: null, completedAt: null };
-}
+// STAGE_ORDER / MAIN_FLOW_ORDER → ./progress/shared.js（W6 Step9a：facade + 子模块共用）
+
+// STAGE_LABELS → ./progress/shared.js（W6 Step9c）
+
+// emptyStage → ./progress/shared.js（W6 Step9d）
 
 function makeInitialProgress(project) {
   const stages = {};
@@ -150,6 +152,10 @@ export class ProgressManager {
    */
   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);
   }
 
   // ── 路径工具 ──
@@ -471,211 +477,21 @@ export class ProgressManager {
 
   // ── 变更管理 ──
 
-  /**
-   * 列出所有活跃变更名
-   * SQL: SELECT name FROM changes WHERE status = 'active'
-   */
-  async listChanges(cwd) {
-    const db = await this._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]);
-  }
+  async listChanges(cwd) { return this._changeRegistry.listChanges(cwd); }
 
-  /**
-   * 注册变更到活跃列表
-   * SQL: INSERT OR IGNORE → 若已 archived 则 UPDATE status='active'
-   */
-  async registerChange(cwd, changeName) {
-    if (!changeName) {
-      console.warn('⚠️  registerChange: changeName 为空，跳过');
-      return;
-    }
-    const db = await this._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 状态不变
-    });
-  }
+  async registerChange(cwd, changeName) { return this._changeRegistry.registerChange(cwd, changeName); }
 
-  /**
-   * 更新变更的隔离状态
-   * @param {string} cwd - 项目根目录
-   * @param {string} changeName - 变更名
-   * @param {{ status: string, mode?: string, reason?: string }} isolation
-   */
-  async updateChangeIsolation(cwd, changeName, isolation) {
-    const db = await this._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);
-    }
-  }
+  async updateChangeIsolation(cwd, changeName, isolation) { return this._changeRegistry.updateChangeIsolation(cwd, changeName, isolation); }
 
-  /**
-   * 读取变更的隔离状态
-   * @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._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 readChangeIsolation(cwd, changeName) { return this._changeRegistry.readChangeIsolation(cwd, changeName); }
 
-  async _updatePlatformLastSync(cwd, changeName) {
-    if (!changeName) return;
-    const db = await this._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      sqlDb.run(
-        'UPDATE changes SET platform_last_sync = ?, platform_sync_enabled = 1 WHERE name = ?',
-        [new Date().toISOString(), changeName]
-      );
-    });
-  }
+  async _updatePlatformLastSync(cwd, changeName) { return this._changeRegistry._updatePlatformLastSync(cwd, changeName); }
 
-  async _updateApprovalStatus(cwd, changeName, status, reason = null) {
-    if (!changeName || !status) return;
-    const db = await this._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,
-        ]
-      );
-    });
-  }
+  async _updateApprovalStatus(cwd, changeName, status, reason = null) { return this._changeRegistry._updateApprovalStatus(cwd, changeName, status, reason); }
 
-  /**
-   * 重命名变更：同步更新 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._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._changePath(cwd, oldName);
-    const newDir = this._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}`);
-  }
+  async renameChange(cwd, oldName, newName) { return this._changeRegistry.renameChange(cwd, oldName, newName); }
 
-  /**
-   * 从活跃列表移除变更（归档时调用，不物理删除）
-   * SQL: UPDATE changes SET status = 'archived'
-   */
-  async unregisterChange(cwd, changeName) {
-    if (!changeName) {
-      console.warn('⚠️  unregisterChange: changeName 为空，跳过');
-      return;
-    }
-    const db = await this._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      const now = new Date().toISOString();
-      sqlDb.run(
-        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`,
-        [now, changeName]
-      );
-    });
-  }
+  async unregisterChange(cwd, changeName) { return this._changeRegistry.unregisterChange(cwd, changeName); }
 
   // ── CLI 命令 ──
 
@@ -761,927 +577,37 @@ export class ProgressManager {
     return await this.read(cwd, changeName);
   }
 
-  async setStage(cwd, stage, changeName = null) {
-    if (!VALID_STAGES.includes(stage)) {
-      console.log(`❌ 未知阶段: ${stage}，可选: ${VALID_STAGES.join(', ')}`);
-      return;
-    }
-
-    const db = await this._ensureDB(cwd);
-    const now = new Date().toISOString();
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = await this.listChanges(cwd);
-      if (changes.length === 1) cn = changes[0];
-      if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
-    }
-
-    db.transaction((sqlDb) => {
-      // 确保 change 存在
-      const changeRow = sqlDb.exec('SELECT id, current_stage FROM changes WHERE name = ?', [cn]);
-      if (!changeRow || changeRow.length === 0 || changeRow[0].values.length === 0) return;
-
-      const changeId = changeRow[0].values[0][0];
-
-      // UPDATE changes.current_stage + last_active
-      sqlDb.run('UPDATE changes SET current_stage = ?, last_active = ? WHERE name = ?', [stage, now, cn]);
-
-      // 确保 stages 行存在（INSERT OR IGNORE）
-      sqlDb.run(
-        'INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, "pending")',
-        [changeId, stage]
-      );
-
-      // UPDATE stages.status 为 in-progress（仅当仍为 pending 时）
-      sqlDb.run(
-        "UPDATE stages SET status = 'in-progress', started_at = ? WHERE change_id = ? AND stage = ? AND status = 'pending'",
-        [now, changeId, stage]
-      );
-    });
-
-    // read() 已改为 SQL，直接通过 SQL 查询即可，无需 _write
-    console.log(`✅ 当前阶段已设为: ${STAGE_LABELS[stage] || stage}`);
-  }
-
-  async addStep(cwd, stage, stepName, changeName = null) {
-    if (!stepName) { console.log('❌ 请指定步骤名称'); return; }
-
-    const db = await this._ensureDB(cwd);
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = await this.listChanges(cwd);
-      if (changes.length === 1) cn = changes[0];
-      if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
-    }
-
-    // 查找 stage_id
-    const sqlDb = db.getDb();
-    const stageRow = sqlDb.exec(
-      'SELECT s.id FROM stages s JOIN changes c ON s.change_id = c.id WHERE c.name = ? AND s.stage = ?',
-      [cn, stage]
-    );
-    if (!stageRow || stageRow.length === 0 || stageRow[0].values.length === 0) {
-      // stages 行不存在，静默跳过
-      console.log(`ℹ️  阶段 ${stage} 不存在`);
-      return;
-    }
-    const stageId = stageRow[0].values[0][0];
-
-    // 重复步骤名检查
-    const dupRow = sqlDb.exec('SELECT id FROM steps WHERE stage_id = ? AND name = ?', [stageId, stepName]);
-    if (dupRow && dupRow.length > 0 && dupRow[0].values.length > 0) {
-      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
-      return;
-    }
-
-    // INSERT INTO steps（ordering 递增）
-    db.transaction((tDb) => {
-      tDb.run(
-        `INSERT INTO steps (stage_id, name, ordering, status)
-         VALUES (?, ?, (SELECT COALESCE(MAX(ordering), 0) + 1 FROM steps WHERE stage_id = ?), 'pending')`,
-        [stageId, stepName, stageId]
-      );
-      tDb.run('UPDATE changes SET last_active = ? WHERE name = ?', [new Date().toISOString(), cn]);
-    });
-
-    console.log(`✅ 已添加步骤: ${stage}/${stepName}`);
-  }
-
-  async updateStep(cwd, stage, stepName, options = {}, changeName = null) {
-    const { status, output } = options;
-    if (!stepName) { console.log('❌ 请指定步骤名称'); return; }
-
-    const db = await this._ensureDB(cwd);
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = await this.listChanges(cwd);
-      if (changes.length === 1) cn = changes[0];
-      if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
-    }
-
-    // 状态校验
-    if (status && !VALID_STATUSES.includes(status)) {
-      console.log(`❌ 无效状态: ${status}，可选: ${VALID_STATUSES.join(', ')}`);
-      return;
-    }
-
-    // 查找 step_id：通过 changes → stages → steps JOIN 查询
-    const sqlDb = db.getDb();
-    const stepRow = sqlDb.exec(
-      `SELECT st.id, st.status FROM steps st
-       JOIN stages sg ON st.stage_id = sg.id
-       JOIN changes c ON sg.change_id = c.id
-       WHERE c.name = ? AND sg.stage = ? AND st.name = ?`,
-      [cn, stage, stepName]
-    );
-    if (!stepRow || stepRow.length === 0 || stepRow[0].values.length === 0) {
-      console.log(`❌ 步骤不存在: ${stage}/${stepName}`);
-      return;
-    }
-    const stepId = stepRow[0].values[0][0];
-
-    // UPDATE steps
-    let stageCompletionCandidateId = null;
-    db.transaction((tDb) => {
-      const now = new Date().toISOString();
-      if (status) {
-        tDb.run('UPDATE steps SET status = ?, completed_at = ? WHERE id = ? AND name = ?', [status, now, stepId, stepName]);
-      }
-      if (output !== undefined) {
-        tDb.run('UPDATE steps SET output = ? WHERE id = ? AND name = ?', [output, stepId, stepName]);
-      }
-
-      // 自动完成检测：同 stage_id 下所有 steps 都 completed 时，候选标记 stage completed
-      // （实际标记延后到事务外，先过产物校验门，防止 update-step 成为绕过 validator 的后门）
-      if (status === 'completed') {
-        // 获取 stage_id
-        const stRow = tDb.exec('SELECT stage_id FROM steps WHERE id = ?', [stepId]);
-        if (stRow && stRow.length > 0 && stRow[0].values.length > 0) {
-          const stId = stRow[0].values[0][0];
-          const pendingRows = tDb.exec('SELECT COUNT(*) FROM steps WHERE stage_id = ? AND status != "completed"', [stId]);
-          if (pendingRows && pendingRows.length > 0 && pendingRows[0].values[0][0] === 0) {
-            stageCompletionCandidateId = stId;
-          }
-        }
-      }
-
-      tDb.run('UPDATE changes SET last_active = ? WHERE name = ?', [now, cn]);
-    });
-
-    if (stageCompletionCandidateId !== null) {
-      const { force = false } = options;
-      const validation = await this._validateStageArtifacts(cwd, stage, cn);
-      if (!validation.ok && !force) {
-        console.error(`⚠️  阶段 ${stage} 所有步骤已完成，但产物校验未通过，阶段不标记为 completed：`);
-        for (const err of validation.errors) console.error(`   - ${err}`);
-        console.error(`   请修复产物后走正常流程 sillyspec run ${stage} --done，或使用 --force（将记录审计日志）。`);
-      } else {
-        if (!validation.ok && force) {
-          console.warn(`⚠️  --force 强制标记阶段 ${stage} completed（校验未通过，已记录审计日志）`);
-          this._appendAuditLog(cwd, {
-            action: 'update-step --force (stage auto-complete)',
-            stage,
-            change: cn,
-            validationErrors: validation.errors,
-          });
-        }
-        db.transaction((tDb) => {
-          tDb.run('UPDATE stages SET status = "completed", completed_at = ? WHERE id = ?', [new Date().toISOString(), stageCompletionCandidateId]);
-        });
-        console.log(`✅ 阶段 ${stage} 所有步骤已完成，阶段已标记为 completed`);
-      }
-    }
-
-    console.log(`✅ 步骤已更新: ${stage}/${stepName} → ${status || '（仅更新 output）'}`);
-  }
-
-  /**
-   * 强制状态变更的审计记录（--force 逃生口专用）。
-   * 追加到 .runtime/audit.log，供人工/doctor 追溯"谁在什么时候绕过了校验"。
-   */
-  _appendAuditLog(cwd, entry) {
-    try {
-      this._ensureRuntimeDir(cwd);
-      const auditPath = this._runtimePath(cwd, 'audit.log');
-      const line = JSON.stringify({ at: new Date().toISOString(), ...entry });
-      appendFileSync(auditPath, line + '\n');
-    } catch (e) {
-      console.warn(`⚠️  审计日志写入失败: ${e.message}`);
-    }
-  }
-
-  /**
-   * 阶段产物校验门：progress complete-stage / update-step 自动完成时复用
-   * stage-contract 的 validator，防止零产物阶段被直接标 completed。
-   */
-  async _validateStageArtifacts(cwd, stage, changeName) {
-    const { runValidators } = await import('./stage-contract.js');
-    const specDir = this._getSpecDir(cwd);
-    const defaultSpec = join(resolve(cwd), SPEC_DIR_NAME);
-    const specRoot = resolve(specDir) === defaultSpec ? null : specDir;
-    let projectName = null;
-    try {
-      const g = await this.readGlobal(cwd);
-      projectName = g?.project || null;
-    } catch {}
-    return runValidators(stage, cwd, changeName, {
-      projectName: projectName || basename(resolve(cwd)),
-      specRoot,
-    });
-  }
-
-  async completeStage(cwd, stage, changeName = null, opts = {}) {
-    const { force = false } = opts;
-    if (!VALID_STAGES.includes(stage)) {
-      console.log(`❌ 未知阶段: ${stage}`);
-      return;
-    }
-
-    const db = await this._ensureDB(cwd);
-    const now = new Date().toISOString();
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = await this.listChanges(cwd);
-      if (changes.length === 1) cn = changes[0];
-      if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
-    }
-
-    // ── 产物校验门：complete-stage 不再是零校验后门 ──
-    // 与 run.js completeStep 的 validator 同源；--force 为显式逃生口（留审计）。
-    const validation = await this._validateStageArtifacts(cwd, stage, cn);
-    if (!validation.ok) {
-      if (!force) {
-        console.error(`❌ complete-stage 被拒绝：阶段 ${stage} 产物校验未通过`);
-        for (const err of validation.errors) console.error(`   - ${err}`);
-        console.error(`   请修复产物后重试，或走正常流程 sillyspec run ${stage} --done。`);
-        console.error(`   确需强制标记（如 doctor 修复），使用 --force（将记录审计日志）。`);
-        return;
-      }
-      console.warn(`⚠️  --force 强制完成阶段 ${stage}（校验未通过，已记录审计日志）`);
-      for (const err of validation.errors) console.warn(`   - ${err}`);
-      this._appendAuditLog(cwd, {
-        action: 'complete-stage --force',
-        stage,
-        change: cn,
-        validationErrors: validation.errors,
-      });
-    } else if (force) {
-      // 校验通过但仍显式 --force：也留一条审计记录，保持行为可追溯
-      this._appendAuditLog(cwd, { action: 'complete-stage --force', stage, change: cn, validationErrors: [] });
-    }
-
-    db.transaction((sqlDb) => {
-      const changeRow = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [cn]);
-      if (!changeRow || changeRow.length === 0 || changeRow[0].values.length === 0) return;
-      const changeId = changeRow[0].values[0][0];
-
-      // 确保 stages 行存在（阶段不存在时自动创建）
-      sqlDb.run(
-        'INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, "pending")',
-        [changeId, stage]
-      );
-
-      // UPDATE stages.status=completed + completed_at
-      sqlDb.run(
-        'UPDATE stages SET status = "completed", completed_at = ? WHERE change_id = ? AND stage = ?',
-        [now, changeId, stage]
-      );
-
-      // 将该阶段所有 pending 步骤标记为 completed
-      const stageRow = sqlDb.exec('SELECT id FROM stages WHERE change_id = ? AND stage = ?', [changeId, stage]);
-      if (stageRow && stageRow.length > 0 && stageRow[0].values.length > 0) {
-        const stageId = stageRow[0].values[0][0];
-        sqlDb.run(
-          'UPDATE steps SET status = "completed", completed_at = ? WHERE stage_id = ? AND status = "pending"',
-          [now, stageId]
-        );
-      }
-
-      // UPDATE changes.last_active
-      sqlDb.run('UPDATE changes SET last_active = ? WHERE name = ?', [now, cn]);
-    });
-
-    // 写 history 文件（保持文件系统，不变）
-    const data = await this.read(cwd, cn);
-    if (data && data.stages && data.stages[stage]) {
-      const historyDir = this._runtimePath(cwd, 'history');
-      mkdirSync(historyDir, { recursive: true });
-      const ts = now.replace(/[:.TZ-]/g, '');
-      const stageData = data.stages[stage];
-      writeAtomicSync(
-        join(historyDir, `${cn}-${stage}-${ts}.json`),
-        JSON.stringify({ change: cn, stage, data: stageData, completedAt: now }, null, 2) + '\n'
-      );
-    }
-
-    console.log(`✅ 阶段 ${stage} 已标记为完成（不自动推进，下一步由你决定）`);
-  }
-
-  async show(cwd, changeName = null) {
-    // 如果指定了变更名，只显示该变更
-    if (changeName) {
-      return await this._showChange(cwd, changeName);
-    }
-
-    // 否则显示所有变更
-    const changes = await this.listChanges(cwd);
-    if (changes.length === 0) {
-      console.log('ℹ️  没有活跃的变更');
-      return;
-    }
-
-    if (changes.length === 1) {
-      return await this._showChange(cwd, changes[0]);
-    }
-
-    // 多个变更：汇总显示
-    const global = await this.readGlobal(cwd);
-    console.log('');
-    console.log('  ═══════════════════════════════════════');
-    console.log(`  项目: ${(global?.project) || basename(cwd) || '(未命名)'}`);
-    console.log(`  活跃变更: ${changes.length} 个`);
-    console.log('  ═══════════════════════════════════════');
-    console.log('');
-
-    for (const cn of changes) {
-      const data = await this.read(cwd, cn);
-      if (!data) {
-        console.log(`  📂 ${cn} — (无法读取)`);
-        continue;
-      }
-      const currentStage = data.currentStage || '(无)';
-      const stageLabel = STAGE_LABELS[data.currentStage] || currentStage;
-      const lastActive = data.lastActive ? this._timeAgo(data.lastActive) : '未知';
-
-      console.log(`  📂 ${cn}`);
-      console.log(`     当前阶段: ${stageLabel}  最近活跃: ${lastActive}`);
-      console.log('');
-    }
-
-    console.log(`  💡 查看详情：sillyspec progress show --change <name>`);
-    console.log('');
-  }
-
-  async _showChange(cwd, changeName) {
-    const data = await this.read(cwd, changeName);
-    if (!data) {
-      console.log(`❌ 未找到变更 ${changeName}`);
-      return;
-    }
-
-    console.log('');
-    console.log('  ═══════════════════════════════════════');
-    console.log(`  变更:     ${changeName}`);
-    console.log(`  项目:     ${data.project || '(未命名)'}`);
-    console.log(`  当前阶段: ${STAGE_LABELS[data.currentStage] || data.currentStage || '(无)'}`);
-    console.log(`  最近活跃: ${data.lastActive ? this._timeAgo(data.lastActive) : '未知'}`);
-    console.log('  ═══════════════════════════════════════');
-    console.log('');
-
-    const statusIcons = { pending: '⬜', 'in-progress': '🔵', completed: '✅', failed: '❌', blocked: '🚫', waiting: '⏸️', revising: '🔧', stale: '⚠️' };
-
-    for (const stage of VALID_STAGES) {
-      const stageData = data.stages[stage] || emptyStage();
-      const label = STAGE_LABELS[stage] || stage;
-      const icon = statusIcons[stageData.status] || '⬜';
-      const isCurrent = data.currentStage === stage ? ' ◀' : '';
-
-      console.log(`  ${icon} ${label}${isCurrent}`);
-
-      // Show revision info
-      if (stageData.revision && stageData.revision > 0) {
-        console.log(`    📋 revision: ${stageData.revision}${stageData.reopenedFromStep ? `, from step: ${stageData.reopenedFromStep}` : ''}`);
-      }
-      if (stageData.staleReason) {
-        console.log(`    ⚠️ stale: ${stageData.staleReason}`);
-        if (stage === 'archive') {
-          console.log(`    📁 已有归档文件仍保留在磁盘上，但不再可信。`);
-        }
-      }
-
-      if (stageData.steps && stageData.steps.length > 0) {
-        for (const step of stageData.steps) {
-          const si = statusIcons[step.status] || '○';
-          const out = step.output ? ` — ${step.output.slice(0, 60)}` : '';
-          const waitingTag = step.status === 'waiting' ? ' [WAITING]' : ''
-          console.log(`    ${si} ${step.name}${out}${waitingTag}`);
-          if (step.status === 'waiting') {
-            if (step.waitReason) console.log(`       原因：${step.waitReason}`);
-            if (step.waitOptions) console.log(`       选项：${(() => { try { const p = JSON.parse(step.waitOptions); return Array.isArray(p) ? p.join(', ') : step.waitOptions; } catch { return step.waitOptions; }})()}`);
-            if (step.waitedAt) console.log(`       等待时间：${step.waitedAt}`);
-          }
-        }
-      }
-
-      if (stageData.startedAt) {
-        console.log(`    开始: ${new Date(stageData.startedAt).toLocaleString('zh-CN')}`);
-      }
-      if (stageData.completedAt) {
-        console.log(`    完成: ${new Date(stageData.completedAt).toLocaleString('zh-CN')}`);
-      }
-    }
-
-    // 批量进度
-    if (data.batchProgress) {
-      const batchLine = this._renderBatchProgress(data.batchProgress);
-      if (batchLine) {
-        console.log('');
-        console.log(`  ${batchLine}`);
-      }
-    }
-
-    // ── Next 建议 ──
-    const suggestion = this._getNextSuggestion(data);
-    if (suggestion) {
-      console.log('');
-      console.log(`  💡 ${suggestion.text}`);
-      if (suggestion.command) console.log(`     ${suggestion.command}`);
-    }
-
-    console.log('');
-  }
-
-  /**
-   * 根据当前状态给出下一步建议
-   * @param {object} data - progress data
-   * @returns {{ text: string, command?: string }|null}
-   */
-  _getNextSuggestion(data) {
-    // 找到第一个 revising 阶段
-    const revisingStage = STAGE_ORDER.find(s => data.stages[s]?.status === 'revising');
-    if (revisingStage) {
-      const sd = data.stages[revisingStage];
-      return {
-        text: `${STAGE_LABELS[revisingStage] || revisingStage} 正在修订中（revision ${sd.revision || 1}），请继续完成修订。`,
-        command: `sillyspec run ${revisingStage}`,
-      };
-    }
-
-    // 找到第一个 stale 阶段（上游已修，下游需要重建）
-    const staleStage = STAGE_ORDER.find(s => data.stages[s]?.status === 'stale');
-    if (staleStage) {
-      const sd = data.stages[staleStage];
-      return {
-        text: `${STAGE_LABELS[staleStage] || staleStage} 已失效（${sd.staleReason || '上游修订'}），需要从第一步重建。`,
-        command: `sillyspec run ${staleStage} --reopen --from-step 1`,
-      };
-    }
-
-    // 找到第一个有 pending/waiting/failed 步骤的 in-progress 阶段
-    for (const s of STAGE_ORDER) {
-      const sd = data.stages[s];
-      if (!sd) continue;
-      if (sd.status === 'in-progress' && sd.steps) {
-        const hasPending = sd.steps.some(st => ['pending', 'waiting', 'failed'].includes(st.status));
-        if (hasPending) {
-          return {
-            text: `${STAGE_LABELS[s] || s} 进行中，继续执行下一步。`,
-            command: `sillyspec run ${s}`,
-          };
-        }
-      }
-    }
-
-    // 找到第一个 pending 主流程阶段
-    for (const s of STAGE_ORDER) {
-      const sd = data.stages[s];
-      if (sd && sd.status === 'pending' && sd.steps && sd.steps.length > 0) {
-        // 检查上游是否都 completed
-        const idx = STAGE_ORDER.indexOf(s);
-        const upstream = STAGE_ORDER.slice(0, idx);
-        const upstreamOk = upstream.every(us =>
-          data.stages[us]?.status === 'completed' || !data.stages[us] || data.stages[us].status === 'pending'
-        );
-        if (upstreamOk) {
-          return {
-            text: `可以开始 ${STAGE_LABELS[s] || s}。`,
-            command: `sillyspec run ${s}`,
-          };
-        }
-      }
-    }
-
-    return null;
-  }
-
-  async status(cwd, changeName = null) {
-    await this.show(cwd, changeName);
-  }
-
-  /**
-   * Revision v1 状态一致性检查
-   * 只报告，不自动修复。
-   * @param {string} cwd
-   * @param {string|null} changeName
-   * @returns {{ ok: boolean, issues: string[], warnings: string[] }}
-   */
-  async checkConsistency(cwd, changeName = null) {
-    const data = await this.read(cwd, changeName);
-    if (!data) {
-      return { ok: false, issues: ['无法读取进度数据'], warnings: [] };
-    }
+  async setStage(cwd, stage, changeName = null) { return this._stepStore.setStage(cwd, stage, changeName); }
 
-    const issues = [];
-    const warnings = [];
+  async addStep(cwd, stage, stepName, changeName = null) { return this._stepStore.addStep(cwd, stage, stepName, changeName); }
 
-    for (const stageName of STAGE_ORDER) {
-      const sd = data.stages[stageName];
-      if (!sd) continue;
+  async updateStep(cwd, stage, stepName, options = {}, changeName = null) { return this._stepStore.updateStep(cwd, stage, stepName, options, changeName); }
 
-      // a. completed stage 不能有 pending/stale steps
-      if (sd.status === 'completed' && sd.steps) {
-        const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
-        for (const step of badSteps) {
-          issues.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed`);
-        }
-      }
-
-      // b. revising stage 应有 revision > 0 或 reopenedFromStep
-      if (sd.status === 'revising') {
-        if (!sd.revision || sd.revision < 1) {
-          issues.push(`${stageName}: 状态为 revising 但 revision 缺失或为 0`);
-        }
-        if (!sd.reopenedFromStep) {
-          warnings.push(`${stageName}: 状态为 revising 但未记录 reopenedFromStep`);
-        }
-      }
+  _appendAuditLog(cwd, entry) { return this._consistency._appendAuditLog(cwd, entry); }
 
-      // c. stale stage 应有 staleReason
-      if (sd.status === 'stale') {
-        if (!sd.staleReason) {
-          warnings.push(`${stageName}: 状态为 stale 但缺少 staleReason`);
-        }
-      }
+  async _validateStageArtifacts(cwd, stage, changeName) { return this._stageMachine._validateStageArtifacts(cwd, stage, changeName); }
 
-      // d. 下游 completed 不能出现在上游 stale/revising 之后
-      const stageIdx = STAGE_ORDER.indexOf(stageName);
-      for (let i = 0; i < stageIdx; i++) {
-        const upstream = STAGE_ORDER[i];
-        const upData = data.stages[upstream];
-        if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
-          if (sd.status === 'completed') {
-            issues.push(`${stageName}: 状态为 completed，但上游 ${upstream} 状态为 ${upData.status}（下游不应在上游修订/失效时保持 completed）`);
-          }
-        }
-      }
+  async completeStage(cwd, stage, changeName = null, opts = {}) { return this._stageMachine.completeStage(cwd, stage, changeName, opts); }
 
-      // e. step stale 时 stage 不应是 completed
-      if (sd.status === 'completed' && sd.steps) {
-        const staleSteps = sd.steps.filter(s => s.status === 'stale');
-        for (const step of staleSteps) {
-          issues.push(`${stageName}/${step.name}: step 状态为 stale，但 stage 状态为 completed`);
-        }
-      }
-    }
+  async show(cwd, changeName = null) { return this._stageMachine.show(cwd, changeName); }
 
-    // 输出报告
-    console.log('');
-    console.log('  ═══════════════════════════════════════');
-    console.log('  状态一致性检查');
-    console.log('  ═══════════════════════════════════════');
+  async _showChange(cwd, changeName) { return this._stageMachine._showChange(cwd, changeName); }
 
-    if (issues.length === 0 && warnings.length === 0) {
-      console.log('  ✅ 未发现一致性问题');
-    } else {
-      if (issues.length > 0) {
-        console.log(`\n  ❌ 问题 (${issues.length}):`);
-        for (const issue of issues) console.log(`     - ${issue}`);
-      }
-      if (warnings.length > 0) {
-        console.log(`\n  ⚠️ 警告 (${warnings.length}):`);
-        for (const w of warnings) console.log(`     - ${w}`);
-      }
-    }
-    console.log('');
+  _getNextSuggestion(data) { return this._stageMachine._getNextSuggestion(data); }
 
-    return { ok: issues.length === 0, issues, warnings };
-  }
+  async status(cwd, changeName = null) { return this._stageMachine.status(cwd, changeName); }
 
-  /**
-   * Revision v1.2 状态修复
-   * 默认 dry-run，--apply 才真正修改 DB。
-   * 只修安全项，不碰产物文件、不 reset/reopen stage。
-   *
-   * @param {string} cwd
-   * @param {object} opts
-   * @param {boolean} [opts.apply=false]
-   * @param {string|null} [opts.changeName]
-   * @returns {{ fixable: object[], manual: string[], applied: object[] }}
-   */
-  async repairConsistency(cwd, opts = {}) {
-    const { apply = false, changeName = null } = opts;
+  async checkConsistency(cwd, changeName = null) { return this._consistency.checkConsistency(cwd, changeName); }
 
-    const data = await this.read(cwd, changeName);
-    if (!data) {
-      console.log('❌ 无法读取进度数据');
-      return { fixable: [], manual: ['无法读取进度数据'], applied: [] };
-    }
+  async repairConsistency(cwd, opts = {}) { return this._consistency.repairConsistency(cwd, opts); }
 
-    const fixable = []; // { stage, action, description, apply: (data) => void }
-    const manual = [];  // string
-
-    const now = new Date().toLocaleString('zh-CN', { hour12: false });
-
-    for (const stageName of STAGE_ORDER) {
-      const sd = data.stages[stageName];
-      if (!sd) continue;
-
-      // Fix a: stale stage 缺 staleReason → 补默认原因
-      if (sd.status === 'stale' && !sd.staleReason) {
-        const reason = stageName === 'archive'
-          ? 'upstream stage revised; existing archive artifacts are preserved but no longer trusted'
-          : 'unknown upstream revision';
-        fixable.push({
-          stage: stageName,
-          action: 'set_stale_reason',
-          description: `${stageName}: stale 缺 staleReason → 补 "${reason}"`,
-          apply: (d) => { d.stages[stageName].staleReason = reason; },
-        });
-      }
+  async validate(cwd, changeName = null) { return this._stageMachine.validate(cwd, changeName); }
 
-      // Fix b: 上游 stale/revising，下游仍 completed → cascade stale
-      const stageIdx = STAGE_ORDER.indexOf(stageName);
-      for (let i = 0; i < stageIdx; i++) {
-        const upstream = STAGE_ORDER[i];
-        const upData = data.stages[upstream];
-        if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
-          if (sd.status === 'completed') {
-            const upStatus = upData.status;
-            const reason = `upstream ${upstream} is ${upStatus}`;
-            fixable.push({
-              stage: stageName,
-              action: 'cascade_stale',
-              description: `${stageName}: completed → stale（上游 ${upstream} 为 ${upStatus}）`,
-              apply: (d) => {
-                d.stages[stageName].status = 'stale';
-                d.stages[stageName].staleReason = reason;
-                d.stages[stageName].completedAt = null;
-              },
-            });
-          }
-        }
-      }
+  async reopenStage(cwd, stage, opts = {}) { return this._stageMachine.reopenStage(cwd, stage, opts); }
 
-      // Fix c: archive stale 缺 staleReason（专用文案）
-      if (stageName === 'archive' && sd.status === 'stale' && !sd.staleReason) {
-        // 已在 Fix a 中处理，这里不重复
-      }
+  _getDownstreamStages(stage) { return this._stageMachine._getDownstreamStages(stage); }
 
-      // Fix d: revising stage 缺 reopenedAt → 补当前时间
-      if (sd.status === 'revising' && !sd.reopenedAt) {
-        fixable.push({
-          stage: stageName,
-          action: 'set_reopened_at',
-          description: `${stageName}: revising 缺 reopenedAt → 补当前时间`,
-          apply: (d) => { d.stages[stageName].reopenedAt = now; },
-        });
-      }
-
-      // Manual a: completed stage 里有 pending/stale/in-progress steps
-      if (sd.status === 'completed' && sd.steps) {
-        const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
-        for (const step of badSteps) {
-          manual.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed（需手动确认）`);
-        }
-      }
-
-      // Manual b: revising stage 缺 reopenedFromStep
-      if (sd.status === 'revising' && !sd.reopenedFromStep) {
-        manual.push(`${stageName}: revising 缺 reopenedFromStep（需手动确认修订起始步骤）`);
-      }
-
-      // Manual c: steps 为空但 stage completed
-      if (sd.status === 'completed' && (!sd.steps || sd.steps.length === 0)) {
-        manual.push(`${stageName}: completed 但 steps 为空（需手动确认）`);
-      }
-    }
-
-    // 输出报告
-    console.log('');
-    console.log('  ═══════════════════════════════════════');
-    console.log(`  状态修复 ${apply ? '（--apply 模式）' : '（dry-run 模式）'}`);
-    console.log('  ═══════════════════════════════════════');
-
-    if (fixable.length === 0 && manual.length === 0) {
-      console.log('  ✅ 未发现问题，无需修复');
-      console.log('');
-      return { fixable: [], manual: [], applied: [] };
-    }
-
-    const applied = [];
-
-    if (fixable.length > 0) {
-      console.log(`\n  🔧 可自动修复 (${fixable.length}):`);
-      for (const item of fixable) {
-        console.log(`     - ${item.description}`);
-        if (apply) {
-          item.apply(data);
-          applied.push({ stage: item.stage, action: item.action });
-        }
-      }
-      if (!apply) {
-        console.log('\n  💡 使用 --apply 执行修复');
-      }
-    }
-
-    if (manual.length > 0) {
-      console.log(`\n  👆 需手动处理 (${manual.length}):`);
-      for (const m of manual) console.log(`     - ${m}`);
-    }
-
-    if (apply && applied.length > 0) {
-      data.lastActive = now;
-      await this._write(cwd, data, changeName);
-      console.log(`\n  ✅ 已修复 ${applied.length} 项`);
-    }
-
-    console.log('');
-
-    return { fixable, manual, applied };
-  }
-
-  async validate(cwd, changeName = null) {
-    const data = await this.read(cwd, changeName);
-    if (!data) { console.log('❌ 无法读取进度数据'); return false; }
-
-    const errors = [];
-    if (!data._version || !Number.isInteger(data._version) || data._version < 1) {
-      errors.push(`_version 缺失或无效（期望正整数，实际为 ${JSON.stringify(data._version)}）`);
-    }
-    if (!data.stages || typeof data.stages !== 'object') errors.push('缺少 stages');
-    if (!VALID_STAGES.every(s => data.stages[s])) errors.push('缺少阶段定义');
-
-    if (errors.length === 0) { console.log('✅ 进度数据格式正确'); return true; }
-
-    console.log(`⚠️  发现问题，尝试修复...`);
-    let fixed = { ...data, stages: { ...data.stages } };
-    let changed = false;
-    if (!fixed.project) {
-      fixed.project = basename(cwd);
-      changed = true;
-    }
-    if (!fixed._version || !Number.isInteger(fixed._version) || fixed._version < 1) {
-      fixed._version = CURRENT_VERSION;
-      changed = true;
-    }
-    for (const s of VALID_STAGES) {
-      if (!fixed.stages[s]) { fixed.stages[s] = emptyStage(); changed = true; }
-    }
-    if (changed) {
-      await this._write(cwd, fixed);
-      console.log('✅ 已修复');
-    }
-
-    return true;
-  }
-
-  /**
-   * 重新打开已完成的阶段进入修订模式
-   * - 不带 fromStep：只允许存在 pending/stale/waiting/failed 步骤时继续
-   * - 带 fromStep：从该步骤起，当前及后续步骤标记 stale/pending
-   * - 自动级联标记下游阶段为 stale
-   *
-   * @param {string} cwd
-   * @param {string} stage - 要重开的阶段
-   * @param {object} opts
-   * @param {string|number} [opts.fromStep] - 步骤名或序号（1-based）
-   * @param {string} [opts.changeName]
-   * @returns {{ ok: boolean, error?: string }}
-   */
-  async reopenStage(cwd, stage, opts = {}) {
-    const { fromStep, changeName = null } = opts;
-
-    const data = await this.read(cwd, changeName);
-    if (!data) return { ok: false, error: '无法读取进度数据' };
-
-    const stageData = data.stages[stage];
-    if (!stageData) return { ok: false, error: `未知阶段: ${stage}` };
-
-    const steps = stageData.steps || [];
-
-    // 确定 fromStep 对应的 index
-    let fromIdx = null;
-    if (fromStep != null) {
-      if (typeof fromStep === 'number' || /^\d+$/.test(String(fromStep))) {
-        fromIdx = parseInt(String(fromStep), 10) - 1; // 1-based → 0-based
-        if (fromIdx < 0 || fromIdx >= steps.length) {
-          return { ok: false, error: `步骤序号超出范围: ${fromStep}（共 ${steps.length} 步）` };
-        }
-      } else {
-        // 按名称匹配
-        fromIdx = steps.findIndex(s => s.name === fromStep);
-        if (fromIdx === -1) {
-          return { ok: false, error: `步骤不存在: ${fromStep}` };
-        }
-      }
-    }
-
-    // 如果不带 fromStep，检查是否存在中断步骤
-    if (fromIdx === null) {
-      const hasInterrupted = steps.some(s =>
-        ['pending', 'stale', 'waiting', 'failed'].includes(s.status)
-      );
-      if (!hasInterrupted) {
-        return { ok: false, error: `阶段 ${stage} 所有步骤均已完成，请使用 --from-step 指定从哪一步开始修订` };
-      }
-      // 找到第一个中断步骤
-      fromIdx = steps.findIndex(s =>
-        ['pending', 'stale', 'waiting', 'failed'].includes(s.status)
-      );
-    }
-
-    // 执行重开操作
-    const newRevision = (stageData.revision || 0) + 1;
-    const fromStepName = steps[fromIdx].name;
-    const now = new Date().toLocaleString('zh-CN', { hour12: false });
-
-    // 更新步骤状态：fromStep 之前的保持 completed，fromStep 变 pending，之后的变 stale
-    for (let i = 0; i < steps.length; i++) {
-      if (i === fromIdx) {
-        steps[i].status = 'pending';
-        steps[i].completedAt = null;
-        steps[i].output = null;
-      } else if (i > fromIdx) {
-        steps[i].status = 'stale';
-        steps[i].completedAt = null;
-      }
-      // i < fromIdx: 保持原状（completed）
-    }
-
-    stageData.status = 'revising';
-    stageData.completedAt = null;
-    stageData.revision = newRevision;
-    stageData.reopenedFromStep = `${fromIdx + 1}: ${fromStepName}`; // 存 "index: name" 格式
-    stageData.reopenedAt = now;
-    stageData.steps = steps;
-
-    data.lastActive = now;
-    data.currentStage = stage;
-
-    await this._write(cwd, data, changeName);
-
-    // 级联标记下游阶段为 stale
-    const downstreamStages = this._getDownstreamStages(stage);
-    if (downstreamStages.length > 0) {
-      const data2 = await this.read(cwd, changeName); // 重新读取以获取最新状态
-      if (data2) {
-        for (const ds of downstreamStages) {
-          if (data2.stages[ds] && data2.stages[ds].status === 'completed') {
-            data2.stages[ds].status = 'stale';
-            data2.stages[ds].staleReason = `上游阶段 ${stage} 已修订 (revision ${newRevision})`;
-            data2.stages[ds].completedAt = null;
-          }
-        }
-        await this._write(cwd, data2, changeName);
-      }
-    }
-
-    return { ok: true, revision: newRevision, fromStep: fromStepName };
-  }
-
-  /**
-   * 获取指定阶段的下游主流程阶段列表
-   * @param {string} stage
-   * @returns {string[]}
-   */
-  _getDownstreamStages(stage) {
-    const idx = MAIN_FLOW_ORDER.indexOf(stage);
-    if (idx === -1) return [];
-    return MAIN_FLOW_ORDER.slice(idx + 1);
-  }
-
-  async reset(cwd, stage, changeName = null) {
-    if (stage) {
-      const data = await this.read(cwd, changeName);
-      if (!data) { console.log('❌ 无法读取进度数据'); return; }
-      if (!data.stages[stage]) { console.log(`❌ 未知阶段: ${stage}`); return; }
-      data.stages[stage] = emptyStage();
-      data.lastActive = new Date().toLocaleString('zh-CN',{hour12:false});
-      await this._write(cwd, data);
-      console.log(`✅ 已重置阶段: ${stage}`);
-    } else {
-      // 重置所有变更或指定变更
-      if (changeName) {
-        // SQL: 删除该变更的所有 stages 和 steps 数据
-        const db = await this._ensureDB(cwd);
-        db.transaction((sqlDb) => {
-          const changeRow = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [changeName]);
-          if (changeRow && changeRow.length > 0 && changeRow[0].values.length > 0) {
-            const changeId = changeRow[0].values[0][0];
-            sqlDb.run('DELETE FROM steps WHERE stage_id IN (SELECT id FROM stages WHERE change_id = ?)', [changeId]);
-            sqlDb.run('DELETE FROM stages WHERE change_id = ?', [changeId]);
-            // 重新插入所有阶段（注意：上方已 DELETE stages，无需再 UPDATE）
-            for (const s of VALID_STAGES) {
-              sqlDb.run('INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, "pending")', [changeId, s]);
-            }
-          }
-        });
-        console.log(`✅ 已重置变更 ${changeName} 的进度`);
-      } else {
-        const changes = await this.listChanges(cwd);
-        const db = await this._ensureDB(cwd);
-        db.transaction((sqlDb) => {
-          for (const cn of changes) {
-            const changeRow = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [cn]);
-            if (changeRow && changeRow.length > 0 && changeRow[0].values.length > 0) {
-              const changeId = changeRow[0].values[0][0];
-              sqlDb.run('DELETE FROM steps WHERE stage_id IN (SELECT id FROM stages WHERE change_id = ?)', [changeId]);
-              sqlDb.run('UPDATE stages SET status = "pending", started_at = NULL, completed_at = NULL WHERE change_id = ?', [changeId]);
-            }
-          }
-        });
-        console.log('✅ 已重置所有变更的进度');
-      }
-    }
-  }
+  async reset(cwd, stage, changeName = null) { return this._stageMachine.reset(cwd, stage, changeName); }
 
   // ── 内部辅助 ──
 
@@ -1734,73 +660,15 @@ export class ProgressManager {
     return data;
   }
 
-  _timeAgo(dateStr) {
-    if (!dateStr) return '未知';
-    let ts = Date.parse(dateStr);
-    if (isNaN(ts)) {
-      const m = dateStr.match(/(\d{4})[\/-](\d{1,2})[\/-](\d{1,2})[\s,]+(\d{1,2}):(\d{2})(?::(\d{2}))?/);
-      if (m) ts = new Date(+m[1], +m[2]-1, +m[3], +m[4], +m[5], +(m[6]||0)).getTime();
-    }
-    if (isNaN(ts)) return dateStr;
-    const diff = Date.now() - ts;
-    const minutes = Math.floor(diff / 60000);
-    if (minutes < 1) return '刚刚';
-    if (minutes < 60) return `${minutes} 分钟前`;
-    const hours = Math.floor(minutes / 60);
-    if (hours < 24) return `${hours} 小时前`;
-    return `${Math.floor(hours / 24)} 天前`;
-  }
+  _timeAgo(dateStr) { return this._stageMachine._timeAgo(dateStr); }
 
   // ── 批量进度 ──
 
-  async updateBatchProgress(cwd, batchData, changeName = null) {
-    const cn = changeName || null;
+  async updateBatchProgress(cwd, batchData, changeName = null) { return this._stepStore.updateBatchProgress(cwd, batchData, changeName); }
 
-    const db = await this._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      // 获取 change_id
-      let changeId = null;
-      if (cn) {
-        const row = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [cn]);
-        if (row && row.length > 0 && row[0].values.length > 0) changeId = row[0].values[0][0];
-      }
-      if (!changeId) {
-        // 尝试从唯一活跃变更获取
-        const rows = sqlDb.exec("SELECT id FROM changes WHERE status = 'active'");
-        if (rows && rows.length > 0 && rows[0].values.length === 1) changeId = rows[0].values[0][0];
-      }
-      if (!changeId) return;
+  async readBatchProgress(cwd, changeName = null) { return this._stepStore.readBatchProgress(cwd, changeName); }
 
-      sqlDb.run(
-        `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`,
-        [changeId, batchData.total || 0, batchData.completed || 0, batchData.failed || 0, batchData.skipped || 0]
-      );
-    });
-  }
-
-  async readBatchProgress(cwd, changeName = null) {
-    const data = await this.read(cwd, changeName);
-    return data?.batchProgress || null;
-  }
-
-  _renderBatchProgress(batchProgress) {
-    if (!batchProgress || !batchProgress.total) return null;
-    const { total, completed = 0, failed = 0, skipped = 0 } = batchProgress;
-    const barLen = 20;
-    const filled = Math.round((completed / total) * barLen);
-    const bar = '█'.repeat(filled) + '░'.repeat(barLen - filled);
-    const parts = [];
-    if (failed > 0) parts.push(`${failed} 失败`);
-    if (skipped > 0) parts.push(`${skipped} 跳过`);
-    const suffix = parts.length ? ` (${parts.join(', ')})` : '';
-    return `📊 批量进度: ${bar} ${completed}/${total}${suffix}`;
-  }
+  _renderBatchProgress(batchProgress) { return this._stepStore._renderBatchProgress(batchProgress); }
 
   /**
    * 更新 gate-status.json，供 worktree-guard hook 读取