sillyspec 3.26.9 → 3.26.11

package/src/progress/shared.js

@@ -1,36 +1,36 @@
-// W6 Step9 共享常量：progress.js facade 与 src/progress/* 子模块共用，避免 facade↔子模块循环引用。
-// 9a: STAGE_ORDER/MAIN_FLOW_ORDER；9c: VALID_STAGES/STAGE_LABELS；9d: SPEC_DIR_NAME/CURRENT_VERSION/emptyStage。
-
-export const SPEC_DIR_NAME = '.sillyspec';
-
-// 合法阶段名（含辅助阶段 scan/quick/explore）
-export const VALID_STAGES = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
-
-// 阶段展示文案
-export const STAGE_LABELS = {
-  brainstorm: '🧠 需求探索',
-  plan: '📐 实现计划',
-  execute: '⚡ 波次执行',
-  verify: '🔍 验证确认',
-  scan: '🔍 代码扫描',
-  quick: '⚡ 快速任务',
-  explore: '🧭 自由探索',
-  archive: '📦 归档变更',
-};
-
-// 完整阶段顺序（含 scan），仅用于展示/迭代顺序
-export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive'];
-// 主流程阶段（不含 scan/quick/explore 等辅助阶段）—— 用于下游 cascade / 一致性上下游判定。
-// scan 是 auxiliary（AUXILIARY_STAGES，按需显式跑、可 failed_post_check、永不要求 completed），
-// 把它算进主流程上下游会让「scan stale/revising」误报 brainstorm/plan/execute 不该 completed
-// （consistency-doctor 坑 + prompt-control-debt plan-c 同根因）。
-export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'archive'];
-
-// progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8）
-export const CURRENT_VERSION = 5;
-
-// 空阶段骨架
-export function emptyStage() {
-  return { status: 'pending', steps: [], startedAt: null, completedAt: null };
-}
-
+// W6 Step9 共享常量：progress.js facade 与 src/progress/* 子模块共用，避免 facade↔子模块循环引用。
+// 9a: STAGE_ORDER/MAIN_FLOW_ORDER；9c: VALID_STAGES/STAGE_LABELS；9d: SPEC_DIR_NAME/CURRENT_VERSION/emptyStage。
+
+export const SPEC_DIR_NAME = '.sillyspec';
+
+// 合法阶段名（含辅助阶段 scan/quick/explore）
+export const VALID_STAGES = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
+
+// 阶段展示文案
+export const STAGE_LABELS = {
+  brainstorm: '🧠 需求探索',
+  plan: '📐 实现计划',
+  execute: '⚡ 波次执行',
+  verify: '🔍 验证确认',
+  scan: '🔍 代码扫描',
+  quick: '⚡ 快速任务',
+  explore: '🧭 自由探索',
+  archive: '📦 归档变更',
+};
+
+// 完整阶段顺序（含 scan），仅用于展示/迭代顺序
+export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive'];
+// 主流程阶段（不含 scan/quick/explore 等辅助阶段）—— 用于下游 cascade / 一致性上下游判定。
+// scan 是 auxiliary（AUXILIARY_STAGES，按需显式跑、可 failed_post_check、永不要求 completed），
+// 把它算进主流程上下游会让「scan stale/revising」误报 brainstorm/plan/execute 不该 completed
+// （consistency-doctor 坑 + prompt-control-debt plan-c 同根因）。
+export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'archive'];
+
+// progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8）
+export const CURRENT_VERSION = 5;
+
+// 空阶段骨架
+export function emptyStage() {
+  return { status: 'pending', steps: [], startedAt: null, completedAt: null };
+}
+

package/src/progress/stage-machine.js

@@ -51,9 +51,37 @@ export class StageMachine {
       if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
     }
 
+    // ── stale 拒绝门（W1 改动点 2）：complete-stage 不再静默回填 stale 步骤 ──
+    // 放在产物校验门之前——stale 是更具体的拒绝原因（产物缺失时旧序会被产物门先拦走，
+    // stale 门永远执行不到）；无 --force 拒绝并列名，有 --force 放行并把 stale 步骤名并入审计。
+    let staleBackfillNote = null;
+    {
+      const sqlDbForStaleCheck = db.getDb();
+      const changeRowForStale = sqlDbForStaleCheck.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
+      if (changeRowForStale !== undefined) {
+        const stageRowForStale = sqlDbForStaleCheck.prepare('SELECT id FROM stages WHERE change_id = ? AND stage = ?').get(changeRowForStale.id, stage);
+        if (stageRowForStale !== undefined) {
+          const staleSteps = sqlDbForStaleCheck.prepare('SELECT name FROM steps WHERE stage_id = ? AND status = ?').all(stageRowForStale.id, 'stale');
+          if (staleSteps.length > 0) {
+            if (!force) {
+              console.error(`❌ complete-stage 被拒绝：阶段 ${stage} 存在 ${staleSteps.length} 个 stale 步骤`);
+              for (const st of staleSteps) console.error(`   - ${st.name}`);
+              console.error(`   stale 步骤需真实执行推进（sillyspec run ${stage} 逐个完成），或确认方案未变后用 --force 强制回填（将记录审计日志）。`);
+              return;
+            }
+            staleBackfillNote = `stale 步骤回填: ${staleSteps.map(s => s.name).join(', ')}`;
+          }
+        }
+      }
+    }
+
     // ── 产物校验门：complete-stage 不再是零校验后门 ──
     // 与 run.js completeStep 的 validator 同源；--force 为显式逃生口（留审计）。
     const validation = this._validateStageArtifacts(cwd, stage, cn);
+    if (staleBackfillNote) {
+      validation.errors = [...(validation.errors || []), staleBackfillNote];
+      validation.ok = false;
+    }
     if (!validation.ok) {
       if (!force) {
         console.error(`❌ complete-stage 被拒绝：阶段 ${stage} 产物校验未通过`);
@@ -92,7 +120,7 @@ export class StageMachine {
       if (stageRow !== undefined) {
         const stageId = stageRow.id;
         sqlDb.prepare(
-          `UPDATE steps SET status = 'completed', completed_at = ? WHERE stage_id = ? AND status IN ('pending', 'stale')` // stale 一并回填（reopen --done 场景，坑 brainstorm-reopen-step-state-desync）
+          `UPDATE steps SET status = 'completed', completed_at = ? WHERE stage_id = ? AND status IN ('pending', 'stale')` // stale 一并回填（reopen --done 场景，坑 brainstorm-reopen-step-state-desync；--force 时放行）
         ).run(now, stageId);
       }
 

package/src/progress/step-store.js

@@ -1,261 +1,261 @@
-// W6 Step9c: 阶段/步骤/批量进度管理（stages + steps + batch_progress 表）。
-// 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm._ensureDB /
-// pm.listChanges / pm._validateStageArtifacts / pm._appendAuditLog / pm.read（persistence-core
-// + 其他组 delegate 留 facade）。纯 SQL + 常量，无 fs/path 依赖。
-import { VALID_STAGES, STAGE_LABELS } from './shared.js';
-
-// step 状态白名单（仅 updateStep 用，本地化）
-const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting', 'stale'];
-
-export class StepStore {
-  constructor(pm) {
-    this.pm = pm;
-  }
-
-  setStage(cwd, stage, changeName = null) {
-    if (!VALID_STAGES.includes(stage)) {
-      console.log(`❌ 未知阶段: ${stage}，可选: ${VALID_STAGES.join(', ')}`);
-      return;
-    }
-
-    const db = this.pm._ensureDB(cwd);
-    const now = new Date().toISOString();
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = this.pm.listChanges(cwd);
-      if (changes.length === 1) cn = changes[0];
-      if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
-    }
-
-    let changeFound = false;
-    db.transaction(() => {
-      const sqlDb = db.getDb();
-      // 确保 change 存在
-      const changeRow = sqlDb.prepare('SELECT id, current_stage FROM changes WHERE name = ?').get(cn);
-      if (changeRow === undefined) return;
-
-      changeFound = true;
-      const changeId = changeRow.id;
-
-      // UPDATE changes.current_stage + last_active
-      sqlDb.prepare('UPDATE changes SET current_stage = ?, last_active = ? WHERE name = ?').run(stage, now, cn);
-
-      // 确保 stages 行存在（INSERT OR IGNORE）
-      sqlDb.prepare(`INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, 'pending')`).run(changeId, stage);
-
-      // UPDATE stages.status 为 in-progress（仅当仍为 pending 时）
-      sqlDb.prepare("UPDATE stages SET status = 'in-progress', started_at = ? WHERE change_id = ? AND stage = ? AND status = 'pending'").run(now, changeId, stage);
-
-      // 本地脏度（D-013 / task-04）：切换阶段是本地推进
-      this.pm._touchLocalModified(cwd, cn, now);
-    });
-
-    if (!changeFound) {
-      // 历史教训：变更名打错/cwd 漂移命中错误 spec 时，事务内静默 return，
-      // 但旧代码此处仍无条件打「✅ 已设为」→ 假成功（agent 以为生效，实际什么都没做）。
-      console.log(`❌ 变更「${cn}」不存在，未设置阶段。检查变更名拼写，或 sillyspec status 查看活跃变更；cwd 漂移时回项目根或加 --spec-dir。`);
-      return;
-    }
-
-    // read() 已改为 SQL，直接通过 SQL 查询即可，无需 _write
-    console.log(`✅ 当前阶段已设为: ${STAGE_LABELS[stage] || stage}（变更 ${cn}）`);
-  }
-
-  addStep(cwd, stage, stepName, changeName = null) {
-    if (!stepName) { console.log('❌ 请指定步骤名称'); return; }
-
-    const db = this.pm._ensureDB(cwd);
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = this.pm.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.prepare(
-      'SELECT s.id FROM stages s JOIN changes c ON s.change_id = c.id WHERE c.name = ? AND s.stage = ?'
-    ).get(cn, stage);
-    if (stageRow === undefined) {
-      // stages 行不存在，静默跳过
-      console.log(`ℹ️  阶段 ${stage} 不存在`);
-      return;
-    }
-    const stageId = stageRow.id;
-
-    // 重复步骤名检查
-    const dupRow = sqlDb.prepare('SELECT id FROM steps WHERE stage_id = ? AND name = ?').get(stageId, stepName);
-    if (dupRow !== undefined) {
-      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
-      return;
-    }
-
-    // INSERT INTO steps（ordering 递增）
-    db.transaction(() => {
-      const tDb = db.getDb();
-      tDb.prepare(
-        `INSERT INTO steps (stage_id, name, ordering, status)
-         VALUES (?, ?, (SELECT COALESCE(MAX(ordering), 0) + 1 FROM steps WHERE stage_id = ?), 'pending')`
-      ).run(stageId, stepName, stageId);
-      tDb.prepare('UPDATE changes SET last_active = ? WHERE name = ?').run(new Date().toISOString(), cn);
-      // 本地脏度（D-013 / task-04）：添加步骤是本地推进
-      this.pm._touchLocalModified(cwd, cn);
-    });
-
-    console.log(`✅ 已添加步骤: ${stage}/${stepName}`);
-  }
-
-  updateStep(cwd, stage, stepName, options = {}, changeName = null) {
-    const { status, output } = options;
-    if (!stepName) { console.log('❌ 请指定步骤名称'); return; }
-
-    const db = this.pm._ensureDB(cwd);
-
-    // 获取变更名
-    let cn = changeName;
-    if (!cn) {
-      const changes = this.pm.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.prepare(
-      `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 = ?`
-    ).get(cn, stage, stepName);
-    if (stepRow === undefined) {
-      console.log(`❌ 步骤不存在: ${stage}/${stepName}`);
-      return;
-    }
-    const stepId = stepRow.id;
-
-    // UPDATE steps
-    let stageCompletionCandidateId = null;
-    db.transaction(() => {
-      const tDb = db.getDb();
-      const now = new Date().toISOString();
-      if (status) {
-        tDb.prepare('UPDATE steps SET status = ?, completed_at = ? WHERE id = ? AND name = ?').run(status, now, stepId, stepName);
-      }
-      if (output !== undefined) {
-        tDb.prepare('UPDATE steps SET output = ? WHERE id = ? AND name = ?').run(output, stepId, stepName);
-      }
-
-      // 自动完成检测：同 stage_id 下所有 steps 都 completed 时，候选标记 stage completed
-      // （实际标记延后到事务外，先过产物校验门，防止 update-step 成为绕过 validator 的后门）
-      if (status === 'completed') {
-        // 获取 stage_id
-        const stRow = tDb.prepare('SELECT stage_id FROM steps WHERE id = ?').get(stepId);
-        if (stRow !== undefined) {
-          const stId = stRow.stage_id;
-          const pendingRow = tDb.prepare("SELECT COUNT(*) AS cnt FROM steps WHERE stage_id = ? AND status NOT IN ('completed','skipped')").get(stId);
-          if (pendingRow.cnt === 0) {
-            stageCompletionCandidateId = stId;
-          }
-        }
-      }
-
-      tDb.prepare('UPDATE changes SET last_active = ? WHERE name = ?').run(now, cn);
-      // 本地脏度（D-013 / task-04）：更新步骤是本地推进
-      this.pm._touchLocalModified(cwd, cn, now);
-    });
-
-    if (stageCompletionCandidateId !== null) {
-      const { force = false } = options;
-      const validation = this.pm._validateStageArtifacts(cwd, stage, cn);
-      if (!validation.ok && !force) {
-        console.error(`⚠️  阶段 ${stage} 所有步骤已完成，但产物校验未通过，阶段不标记为 completed：`);
-        for (const err of validation.errors) console.error(`   - ${err}`);
-        // 出路提示常放在 warnings（如「写明不改理由即可豁免」），阻断时必须一并打出，
-        // 否则 agent 只看到症状看不到怎么过（驾驭问题根因：hint 在 warning、出口只打 error）。
-        for (const warn of (validation.warnings || [])) console.error(`   · ${warn}`);
-        console.error(`   请修复产物后走正常流程 sillyspec run ${stage} --done，或使用 --force（将记录审计日志）。`);
-      } else {
-        if (!validation.ok && force) {
-          console.warn(`⚠️  --force 强制标记阶段 ${stage} completed（校验未通过，已记录审计日志）`);
-          this.pm._appendAuditLog(cwd, {
-            action: 'update-step --force (stage auto-complete)',
-            stage,
-            change: cn,
-            validationErrors: validation.errors,
-          });
-        }
-        db.transaction(() => {
-          const tDb = db.getDb();
-          tDb.prepare(`UPDATE stages SET status = 'completed', completed_at = ? WHERE id = ?`).run(new Date().toISOString(), stageCompletionCandidateId);
-        });
-        console.log(`✅ 阶段 ${stage} 所有步骤已完成，阶段已标记为 completed`);
-      }
-    }
-
-    console.log(`✅ 步骤已更新: ${stage}/${stepName} → ${status || '（仅更新 output）'}`);
-  }
-
-  updateBatchProgress(cwd, batchData, changeName = null) {
-    const cn = changeName || null;
-
-    const db = this.pm._ensureDB(cwd);
-    db.transaction(() => {
-      const sqlDb = db.getDb();
-      // 获取 change_id
-      let changeId = null;
-      if (cn) {
-        const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
-        if (row !== undefined) changeId = row.id;
-      }
-      if (!changeId) {
-        // 尝试从唯一活跃变更获取
-        const rows = sqlDb.prepare("SELECT id FROM changes WHERE status = 'active'").all();
-        if (rows.length === 1) changeId = rows[0].id;
-      }
-      if (!changeId) return;
-
-      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, batchData.total || 0, batchData.completed || 0, batchData.failed || 0, batchData.skipped || 0);
-      // 本地脏度（D-013 / task-04）：批量进度更新是本地推进
-      const nameRow = sqlDb.prepare('SELECT name FROM changes WHERE id = ?').get(changeId);
-      if (nameRow) this.pm._touchLocalModified(cwd, nameRow.name);
-    });
-  }
-
-  readBatchProgress(cwd, changeName = null) {
-    const data = this.pm.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}`;
-  }
-}
-
+// W6 Step9c: 阶段/步骤/批量进度管理（stages + steps + batch_progress 表）。
+// 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm._ensureDB /
+// pm.listChanges / pm._validateStageArtifacts / pm._appendAuditLog / pm.read（persistence-core
+// + 其他组 delegate 留 facade）。纯 SQL + 常量，无 fs/path 依赖。
+import { VALID_STAGES, STAGE_LABELS } from './shared.js';
+
+// step 状态白名单（仅 updateStep 用，本地化）
+const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting', 'stale'];
+
+export class StepStore {
+  constructor(pm) {
+    this.pm = pm;
+  }
+
+  setStage(cwd, stage, changeName = null) {
+    if (!VALID_STAGES.includes(stage)) {
+      console.log(`❌ 未知阶段: ${stage}，可选: ${VALID_STAGES.join(', ')}`);
+      return;
+    }
+
+    const db = this.pm._ensureDB(cwd);
+    const now = new Date().toISOString();
+
+    // 获取变更名
+    let cn = changeName;
+    if (!cn) {
+      const changes = this.pm.listChanges(cwd);
+      if (changes.length === 1) cn = changes[0];
+      if (!cn) { console.log('❌ 无法确定当前变更，请指定 --change <name>'); return; }
+    }
+
+    let changeFound = false;
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      // 确保 change 存在
+      const changeRow = sqlDb.prepare('SELECT id, current_stage FROM changes WHERE name = ?').get(cn);
+      if (changeRow === undefined) return;
+
+      changeFound = true;
+      const changeId = changeRow.id;
+
+      // UPDATE changes.current_stage + last_active
+      sqlDb.prepare('UPDATE changes SET current_stage = ?, last_active = ? WHERE name = ?').run(stage, now, cn);
+
+      // 确保 stages 行存在（INSERT OR IGNORE）
+      sqlDb.prepare(`INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, 'pending')`).run(changeId, stage);
+
+      // UPDATE stages.status 为 in-progress（仅当仍为 pending 时）
+      sqlDb.prepare("UPDATE stages SET status = 'in-progress', started_at = ? WHERE change_id = ? AND stage = ? AND status = 'pending'").run(now, changeId, stage);
+
+      // 本地脏度（D-013 / task-04）：切换阶段是本地推进
+      this.pm._touchLocalModified(cwd, cn, now);
+    });
+
+    if (!changeFound) {
+      // 历史教训：变更名打错/cwd 漂移命中错误 spec 时，事务内静默 return，
+      // 但旧代码此处仍无条件打「✅ 已设为」→ 假成功（agent 以为生效，实际什么都没做）。
+      console.log(`❌ 变更「${cn}」不存在，未设置阶段。检查变更名拼写，或 sillyspec status 查看活跃变更；cwd 漂移时回项目根或加 --spec-dir。`);
+      return;
+    }
+
+    // read() 已改为 SQL，直接通过 SQL 查询即可，无需 _write
+    console.log(`✅ 当前阶段已设为: ${STAGE_LABELS[stage] || stage}（变更 ${cn}）`);
+  }
+
+  addStep(cwd, stage, stepName, changeName = null) {
+    if (!stepName) { console.log('❌ 请指定步骤名称'); return; }
+
+    const db = this.pm._ensureDB(cwd);
+
+    // 获取变更名
+    let cn = changeName;
+    if (!cn) {
+      const changes = this.pm.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.prepare(
+      'SELECT s.id FROM stages s JOIN changes c ON s.change_id = c.id WHERE c.name = ? AND s.stage = ?'
+    ).get(cn, stage);
+    if (stageRow === undefined) {
+      // stages 行不存在，静默跳过
+      console.log(`ℹ️  阶段 ${stage} 不存在`);
+      return;
+    }
+    const stageId = stageRow.id;
+
+    // 重复步骤名检查
+    const dupRow = sqlDb.prepare('SELECT id FROM steps WHERE stage_id = ? AND name = ?').get(stageId, stepName);
+    if (dupRow !== undefined) {
+      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
+      return;
+    }
+
+    // INSERT INTO steps（ordering 递增）
+    db.transaction(() => {
+      const tDb = db.getDb();
+      tDb.prepare(
+        `INSERT INTO steps (stage_id, name, ordering, status)
+         VALUES (?, ?, (SELECT COALESCE(MAX(ordering), 0) + 1 FROM steps WHERE stage_id = ?), 'pending')`
+      ).run(stageId, stepName, stageId);
+      tDb.prepare('UPDATE changes SET last_active = ? WHERE name = ?').run(new Date().toISOString(), cn);
+      // 本地脏度（D-013 / task-04）：添加步骤是本地推进
+      this.pm._touchLocalModified(cwd, cn);
+    });
+
+    console.log(`✅ 已添加步骤: ${stage}/${stepName}`);
+  }
+
+  updateStep(cwd, stage, stepName, options = {}, changeName = null) {
+    const { status, output } = options;
+    if (!stepName) { console.log('❌ 请指定步骤名称'); return; }
+
+    const db = this.pm._ensureDB(cwd);
+
+    // 获取变更名
+    let cn = changeName;
+    if (!cn) {
+      const changes = this.pm.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.prepare(
+      `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 = ?`
+    ).get(cn, stage, stepName);
+    if (stepRow === undefined) {
+      console.log(`❌ 步骤不存在: ${stage}/${stepName}`);
+      return;
+    }
+    const stepId = stepRow.id;
+
+    // UPDATE steps
+    let stageCompletionCandidateId = null;
+    db.transaction(() => {
+      const tDb = db.getDb();
+      const now = new Date().toISOString();
+      if (status) {
+        tDb.prepare('UPDATE steps SET status = ?, completed_at = ? WHERE id = ? AND name = ?').run(status, now, stepId, stepName);
+      }
+      if (output !== undefined) {
+        tDb.prepare('UPDATE steps SET output = ? WHERE id = ? AND name = ?').run(output, stepId, stepName);
+      }
+
+      // 自动完成检测：同 stage_id 下所有 steps 都 completed 时，候选标记 stage completed
+      // （实际标记延后到事务外，先过产物校验门，防止 update-step 成为绕过 validator 的后门）
+      if (status === 'completed') {
+        // 获取 stage_id
+        const stRow = tDb.prepare('SELECT stage_id FROM steps WHERE id = ?').get(stepId);
+        if (stRow !== undefined) {
+          const stId = stRow.stage_id;
+          const pendingRow = tDb.prepare("SELECT COUNT(*) AS cnt FROM steps WHERE stage_id = ? AND status NOT IN ('completed','skipped')").get(stId);
+          if (pendingRow.cnt === 0) {
+            stageCompletionCandidateId = stId;
+          }
+        }
+      }
+
+      tDb.prepare('UPDATE changes SET last_active = ? WHERE name = ?').run(now, cn);
+      // 本地脏度（D-013 / task-04）：更新步骤是本地推进
+      this.pm._touchLocalModified(cwd, cn, now);
+    });
+
+    if (stageCompletionCandidateId !== null) {
+      const { force = false } = options;
+      const validation = this.pm._validateStageArtifacts(cwd, stage, cn);
+      if (!validation.ok && !force) {
+        console.error(`⚠️  阶段 ${stage} 所有步骤已完成，但产物校验未通过，阶段不标记为 completed：`);
+        for (const err of validation.errors) console.error(`   - ${err}`);
+        // 出路提示常放在 warnings（如「写明不改理由即可豁免」），阻断时必须一并打出，
+        // 否则 agent 只看到症状看不到怎么过（驾驭问题根因：hint 在 warning、出口只打 error）。
+        for (const warn of (validation.warnings || [])) console.error(`   · ${warn}`);
+        console.error(`   请修复产物后走正常流程 sillyspec run ${stage} --done，或使用 --force（将记录审计日志）。`);
+      } else {
+        if (!validation.ok && force) {
+          console.warn(`⚠️  --force 强制标记阶段 ${stage} completed（校验未通过，已记录审计日志）`);
+          this.pm._appendAuditLog(cwd, {
+            action: 'update-step --force (stage auto-complete)',
+            stage,
+            change: cn,
+            validationErrors: validation.errors,
+          });
+        }
+        db.transaction(() => {
+          const tDb = db.getDb();
+          tDb.prepare(`UPDATE stages SET status = 'completed', completed_at = ? WHERE id = ?`).run(new Date().toISOString(), stageCompletionCandidateId);
+        });
+        console.log(`✅ 阶段 ${stage} 所有步骤已完成，阶段已标记为 completed`);
+      }
+    }
+
+    console.log(`✅ 步骤已更新: ${stage}/${stepName} → ${status || '（仅更新 output）'}`);
+  }
+
+  updateBatchProgress(cwd, batchData, changeName = null) {
+    const cn = changeName || null;
+
+    const db = this.pm._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      // 获取 change_id
+      let changeId = null;
+      if (cn) {
+        const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
+        if (row !== undefined) changeId = row.id;
+      }
+      if (!changeId) {
+        // 尝试从唯一活跃变更获取
+        const rows = sqlDb.prepare("SELECT id FROM changes WHERE status = 'active'").all();
+        if (rows.length === 1) changeId = rows[0].id;
+      }
+      if (!changeId) return;
+
+      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, batchData.total || 0, batchData.completed || 0, batchData.failed || 0, batchData.skipped || 0);
+      // 本地脏度（D-013 / task-04）：批量进度更新是本地推进
+      const nameRow = sqlDb.prepare('SELECT name FROM changes WHERE id = ?').get(changeId);
+      if (nameRow) this.pm._touchLocalModified(cwd, nameRow.name);
+    });
+  }
+
+  readBatchProgress(cwd, changeName = null) {
+    const data = this.pm.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}`;
+  }
+}
+