sillyspec 3.25.8 → 3.25.11

package/src/machine-interface.js

@@ -7,7 +7,7 @@
  * 设计原则（见 change 2026-07-09-machine-interface-v1 design.md §2/§3）：
  *   - 方案 B：独立模块单点封装，不污染既有 run/progress 输出
  *   - 只聚合不新增校验：复用 stage-contract / task-review / verify-postcheck 既有策略引擎
- *   - 只读语义边界（D-002@v1）：只调 ProgressManager 读路径，不写 sillyspec.db / gate-status.json
+ *   - 只读语义边界（D-002@v1）：只调 ProgressManager 读路径，不写 sillyspec.db
  *   - stdout 纯 JSON（D-005@v1）：--json 模式下由 CLI 层（src/index.js 的 withJsonOutput）
  *     在调用 runGate/runDerive 期间劫持 console.log 到 stderr，防被调模块污染机器输出
  *   - 退出码 0/1/2 三段语义（D-004@v1）：0=通过，1=事实阻断，2=无法核验
@@ -18,8 +18,9 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { ProgressManager, resolveSpecDir } from './progress.js';
+import { resolveRuntimeRoot } from './run/shared.js';
 import { runValidators, checkTransition, checkExecuteCodeEvidence } from './stage-contract.js';
-import { validateTaskReviews } from './task-review.js';
+import { validateTaskReviews, resolveLatestExecuteRunId } from './task-review.js';
 import { runVerifyTestCheck } from './verify-postcheck.js';
 
 // ============ 退出码常量（D-004@v1）============
@@ -101,16 +102,35 @@ export function buildEnvelope({
  * @param {object} opts
  * @param {string} opts.cwd - 项目根目录
  * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
- * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 join(specBase, '.runtime')
+ * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 resolveRuntimeRoot 三级优先级解析
+ * @param {string} [opts.specDriftAnchor] - drift 场景主仓 specBase 锚点（坑 execute-runs-isolation）。
+ *   drift 守卫命中时由调用方传入，task-reviews 的 execute-run-id marker 落点经
+ *   resolveRuntimeRoot 锚主仓 .runtime，不读 worktree 副本（与 contract-matrix 调用方同语义）。
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
-export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot } = {}) {
+export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor } = {}) {
   const specRoot = specBase || resolveSpecDir(cwd);
   const pm = new ProgressManager();
 
   try {
+    // ── 只读契约守卫（D-002@v1）：db 不存在时 fail-closed 返回 exit 2，不触发建库落盘 ──
+    // pm.read → _ensureDB → db.init() 在 db 不存在/schema 戳落后时会 _createSchema + _save 落盘
+    // （db.js:init），这会让一个声明只读的查询命令在 spec 目录凭空建 sillyspec.db，违反只读契约。
+    // db 还没建 = 该变更从未跑过流程，无从核验 → 显式返回「无法核验」而非建库。
+    const dbPath = join(resolveSpecDir(cwd), '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'gate',
+        stage,
+        change: changeName,
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——变更 ${changeName} 尚未运行过任何阶段，只读 gate 不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
     // ── 读进度：变更不存在 → exit 2（D-004@v1）──
-    const progress = await pm.read(cwd, changeName);
+    const progress = pm.read(cwd, changeName);
     if (!progress) {
       const envelope = buildEnvelope({
         command: 'gate',
@@ -181,13 +201,14 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot }
         }
       }
 
-      const rtRoot = runtimeRoot || join(specRoot, '.runtime');
-      const runIdFile = join(rtRoot, `current-execute-run-id-${changeName}`);
+      // drift 场景经 resolveRuntimeRoot 三级优先级解析（runtimeRoot > specDriftAnchor > 本地兜底），
+      // 锚主仓 .runtime，不读 worktree 副本（坑 execute-runs-isolation，与 contract-matrix 调用方同语义）
+      const rtRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot);
+      // marker 缺失/为空时先扫描 execute-runs/ 找回真实 runId（与 gates.js #6 同源），
+      // 避免拿 '' 进 validateTaskReviews 拼出 execute-runs//tasks/... 产出全量误导 errors。
       let executeRunId = '';
       try {
-        if (existsSync(runIdFile)) {
-          executeRunId = readFileSync(runIdFile, 'utf8').trim();
-        }
+        executeRunId = resolveLatestExecuteRunId({ runtimeRoot: rtRoot, changeName }) || '';
       } catch {
         executeRunId = '';
       }
@@ -300,7 +321,7 @@ export const FACETS = ['execute-evidence', 'verify-test', 'task-reviews', 'artif
  * 与 gate 的差异：gate 聚合某阶段所有 check 的综合结论；derive 只返回单一 facet 的结构化 data，
  * daemon 用来做细粒度事实采集（如轮询 execute-evidence 判断代码是否变更）。
  *
- * 只读语义边界同 gate（D-002@v1）：仅调 ProgressManager.read，不写 sillyspec.db / gate-status.json。
+ * 只读语义边界同 gate（D-002@v1）：仅调 ProgressManager.read，不写 sillyspec.db。
  * 唯一例外是 verify-test 会真实执行测试并落盘 test-result.json（产物取证，非状态写入，design §3.3）。
  *
  * 退出码语义（D-004@v1）：0=事实通过，1=事实性阻断，2=无法核验（用法错/变更不存在/内部异常）。
@@ -310,10 +331,12 @@ export const FACETS = ['execute-evidence', 'verify-test', 'task-reviews', 'artif
  * @param {object} opts
  * @param {string} opts.cwd - 项目根目录
  * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
- * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 join(specBase, '.runtime')
+ * @param {string} [opts.runtimeRoot] - .runtime 目录；默认 resolveRuntimeRoot 三级优先级解析
+ * @param {string} [opts.specDriftAnchor] - drift 场景主仓 specBase 锚点（坑 execute-runs-isolation），
+ *   task-reviews facet 的 execute-run-id marker 落点经 resolveRuntimeRoot 锚主仓 .runtime，不读副本。
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
-export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot } = {}) {
+export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor } = {}) {
   // ── 非法 facet：用法错 → exit 2（D-004@v1）──
   if (!FACETS.includes(facet)) {
     const envelope = buildEnvelope({
@@ -330,8 +353,21 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot
   const pm = new ProgressManager();
 
   try {
+    // ── 只读契约守卫（D-002@v1，同 runGate）：db 不存在时 fail-closed 返回 exit 2，不建库落盘 ──
+    const dbPath = join(resolveSpecDir(cwd), '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'derive',
+        facet,
+        change: changeName,
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——变更 ${changeName} 尚未运行过任何阶段，只读 derive 不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
     // ── 读进度：变更不存在 → exit 2 ──
-    const progress = await pm.read(cwd, changeName);
+    const progress = pm.read(cwd, changeName);
     if (!progress) {
       const envelope = buildEnvelope({
         command: 'derive',
@@ -399,13 +435,12 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot
           }
         }
 
-        const rtRoot = runtimeRoot || join(specRoot, '.runtime');
-        const runIdFile = join(rtRoot, `current-execute-run-id-${changeName}`);
+        // drift 场景经 resolveRuntimeRoot 三级优先级解析（同 runGate execute 段），锚主仓 .runtime 不读副本
+        const rtRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot);
+        // marker 缺失/为空时先扫描 execute-runs/ 找回真实 runId（同 runGate execute 段），避免拿 '' 误导校验
         let executeRunId = '';
         try {
-          if (existsSync(runIdFile)) {
-            executeRunId = readFileSync(runIdFile, 'utf8').trim();
-          }
+          executeRunId = resolveLatestExecuteRunId({ runtimeRoot: rtRoot, changeName }) || '';
         } catch {
           executeRunId = '';
         }

package/src/migrate.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync, statSync, cpSync } from 'fs';
 import { basename, join, resolve } from 'path';
 import chalk from 'chalk';
 
@@ -60,9 +60,19 @@ export function migrateDocs(projectDir) {
       const src = join(archiveDir, entry);
       const dest = join(targetDir, entry);
       if (!existsSync(dest)) {
-        copyFileSync(src, dest);
-        console.log(chalk.green('  ✅') + ` archive/${entry}`);
-        migrated++;
+        // 归档变更本身是目录（含 design.md 等），copyFileSync 对目录源抛 EISDIR；
+        // 按类型分发：目录用 cpSync 递归、文件用 copyFileSync，单条失败 try/catch 不中断整体迁移
+        try {
+          if (statSync(src).isDirectory()) {
+            cpSync(src, dest, { recursive: true });
+          } else {
+            copyFileSync(src, dest);
+          }
+          console.log(chalk.green('  ✅') + ` archive/${entry}`);
+          migrated++;
+        } catch (err) {
+          console.log(chalk.yellow('  ⚠️') + ` archive/${entry} 迁移失败: ${err.message}`);
+        }
       } else {
         console.log(chalk.yellow('  ⏭️') + ` archive/${entry} (已存在)`);
       }

package/src/modules.js

@@ -60,7 +60,7 @@ function parseModuleCardFrontmatter(content) {
  *   - verify_commands: 验证命令（build/test/lint）
  *   - related_docs: 关联文档路径
  */
-export async function rebuildModuleMap(cwd) {
+export async function rebuildModuleMap(cwd, { force = false } = {}) {
   const mapPath = findModuleMapPath(cwd);
   if (!mapPath) {
     console.error('❌ 未找到 .sillyspec/docs/<project>/modules/ 目录');
@@ -162,6 +162,13 @@ export async function rebuildModuleMap(cwd) {
     yaml += `\n`;
   }
 
+  // 破坏性保护（multi-agent-platform 坑 modules-rebuild-destructive）：默认 dry-run 只预览不写，--force 才覆盖。
+  if (!force && existingMap) {
+    console.log('⚠️  rebuild 默认不写入（破坏性保护）：该命令会覆盖 _module-map.yaml，清空 tags/entrypoints/main_symbols/depends_on/used_by 等手动维护字段');
+    console.log('    本次为预览，未写入磁盘。确认覆盖请运行：sillyspec modules rebuild --force');
+    return { dryRun: true, path: mapPath }
+  }
+
   writeFileSync(mapPath, yaml, 'utf8');
   console.log(`✅ _module-map.yaml 已重建：${mapPath}`);
   console.log(`   模块数量：${allModuleIds.size}`);
@@ -170,6 +177,7 @@ export async function rebuildModuleMap(cwd) {
   }
   console.log(`\n⚠️  注意：rebuild 只重建骨架。tags/entrypoints/main_symbols/depends_on/used_by 需要重新运行 scan 或手动补充。`);
   console.log(`ℹ️  schema 已升级到 v2，支持 role/core_files/test_files/entrypoints/depends_on/risk_level/verify_commands 等字段。`);
+  return { dryRun: false, path: mapPath, modules: allModuleIds.size }
 }
 
 /**
@@ -278,7 +286,10 @@ export async function generateDependenciesMd(cwd) {
   console.log(`✅ dependencies.md 已生成`);
 }
 
-function parseModuleMapSimple(content) {
+// _module-map.yaml 简单 YAML 解析（模块上下文索引）。canonical 单一真相源——run/prompt.js
+// 的 loadModuleContextIndex 与本文件 generateDependenciesMd 共用此函数（合并历史两份分叉副本，
+// 2026-08-07；字段集取并集：core_files/test_files/related_docs/verify_commands + role/risk_level）。
+export function parseModuleMapSimple(content) {
   const modules = {};
   let currentModule = null;
   let currentKey = null;
@@ -299,7 +310,7 @@ function parseModuleMapSimple(content) {
     if (!currentModule) continue;
 
     // Array field like depends_on:\n  - xxx
-    const arrayFieldMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons):$/);
+    const arrayFieldMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands):$/);
     if (arrayFieldMatch) {
       if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray;
       currentKey = arrayFieldMatch[1];
@@ -308,7 +319,7 @@ function parseModuleMapSimple(content) {
     }
 
     // Inline array like tags: [a, b]
-    const inlineArrayMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons): \[(.*)\]$/);
+    const inlineArrayMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands): \[(.*)\]$/);
     if (inlineArrayMatch) {
       if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray;
       const vals = inlineArrayMatch[2].split(',').map(v => v.trim()).filter(Boolean);
@@ -319,7 +330,7 @@ function parseModuleMapSimple(content) {
     }
 
     // Scalar field
-    const scalarMatch = line.match(/^    (status|doc|needs_review): (.+)$/);
+    const scalarMatch = line.match(/^    (status|doc|needs_review|role|risk_level): (.+)$/);
     if (scalarMatch) {
       if (currentArray && currentKey) { modules[currentModule][currentKey] = currentArray; currentArray = null; currentKey = null; }
       modules[currentModule][scalarMatch[1]] = scalarMatch[2];

package/src/progress/change-registry.js

@@ -12,32 +12,31 @@ export class ChangeRegistry {
    * 列出所有活跃变更名
    * SQL: SELECT name FROM changes WHERE status = 'active'
    */
-  async listChanges(cwd) {
-    const db = await this.pm._ensureDB(cwd);
+  listChanges(cwd) {
+    const db = this.pm._ensureDB(cwd);
     const sqlDb = db.getDb();
-    const rows = sqlDb.exec("SELECT name FROM changes WHERE status = 'active' ORDER BY name");
-    if (!rows || rows.length === 0) return [];
-    return rows[0].values.map(r => r[0]);
+    const rows = sqlDb.prepare("SELECT name FROM changes WHERE status = 'active' ORDER BY name").all();
+    return rows.map(r => r.name);
   }
 
   /**
    * 注册变更到活跃列表
    * SQL: INSERT OR IGNORE → 若已 archived 则 UPDATE status='active'
    */
-  async registerChange(cwd, changeName) {
+  registerChange(cwd, changeName) {
     if (!changeName) {
       console.warn('⚠️  registerChange: changeName 为空，跳过');
       return;
     }
-    const db = await this.pm._ensureDB(cwd);
-    db.transaction((sqlDb) => {
+    const db = this.pm._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
       const now = new Date().toISOString();
       // 尝试插入新行
-      sqlDb.run(
+      sqlDb.prepare(
         `INSERT OR IGNORE INTO changes (name, created_at, last_active)
-         VALUES (?, ?, ?)`,
-        [changeName, now, now]
-      );
+         VALUES (?, ?, ?)`
+      ).run(changeName, now, now);
       // 注意：不复活已归档的变更——归档是不可逆操作
       // 如果变更已存在且为 archived，保持 archived 状态不变
     });
@@ -49,15 +48,15 @@ export class ChangeRegistry {
    * @param {string} changeName - 变更名
    * @param {{ status: string, mode?: string, reason?: string }} isolation
    */
-  async updateChangeIsolation(cwd, changeName, isolation) {
-    const db = await this.pm._ensureDB(cwd);
-    const sqlDb = db.getDb();
+  updateChangeIsolation(cwd, changeName, isolation) {
+    const db = this.pm._ensureDB(cwd);
     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();
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+        sqlDb.prepare(
+          `UPDATE changes SET isolation_status = ?, isolation_mode = ?, isolation_reason = ?, last_active = ? WHERE name = ?`
+        ).run(isolation.status, isolation.mode || null, isolation.reason || null, new Date().toISOString(), changeName);
+      });
     } catch (err) {
       console.warn('⚠️  更新 isolation 状态失败:', err.message);
     }
@@ -69,55 +68,54 @@ export class ChangeRegistry {
    * @param {string} changeName - 变更名
    * @returns {{ status: string|null, mode: string|null, reason: string|null }|null}
    */
-  async readChangeIsolation(cwd, changeName) {
-    const db = await this.pm._ensureDB(cwd);
+  readChangeIsolation(cwd, changeName) {
+    const db = this.pm._ensureDB(cwd);
     const sqlDb = db.getDb();
     try {
-      const rows = sqlDb.exec(
-        `SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name = ?`,
-        [changeName]
-      );
-      if (!rows || rows.length === 0 || rows[0].values.length === 0) return null;
-      const [status, mode, reason] = rows[0].values[0];
+      const row = sqlDb.prepare(
+        `SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name = ?`
+      ).get(changeName);
+      if (row === undefined) return null;
+      const { isolation_status: status, isolation_mode: mode, isolation_reason: reason } = row;
       return { status: status || null, mode: mode || null, reason: reason || null };
     } catch {
       return null;
     }
   }
 
-  async _updatePlatformLastSync(cwd, changeName) {
+  _updatePlatformLastSync(cwd, changeName) {
     if (!changeName) return;
-    const db = await this.pm._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      sqlDb.run(
-        'UPDATE changes SET platform_last_sync = ?, platform_sync_enabled = 1 WHERE name = ?',
-        [new Date().toISOString(), changeName]
-      );
+    const db = this.pm._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      sqlDb.prepare(
+        'UPDATE changes SET platform_last_sync = ?, platform_sync_enabled = 1 WHERE name = ?'
+      ).run(new Date().toISOString(), changeName);
     });
   }
 
-  async _updateApprovalStatus(cwd, changeName, status, reason = null) {
+  _updateApprovalStatus(cwd, changeName, status, reason = null) {
     if (!changeName || !status) return;
-    const db = await this.pm._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      const rows = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [changeName]);
-      if (!rows || rows.length === 0 || rows[0].values.length === 0) return;
-      const changeId = rows[0].values[0][0];
+    const db = this.pm._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+      if (row === undefined) return;
+      const changeId = row.id;
       const now = new Date().toISOString();
-      sqlDb.run(
+      sqlDb.prepare(
         `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,
-        ]
+           rejection_reason = excluded.rejection_reason`
+      ).run(
+        changeId,
+        status,
+        now,
+        status === 'approved' ? now : null,
+        status === 'rejected' ? reason : null,
       );
     });
   }
@@ -128,7 +126,7 @@ export class ChangeRegistry {
    * @param {string} oldName - 旧变更名
    * @param {string} newName - 新变更名
    */
-  async renameChange(cwd, oldName, newName) {
+  renameChange(cwd, oldName, newName) {
     if (!oldName || !newName) {
       console.warn('⚠️  renameChange: 旧名或新名为空，跳过');
       return;
@@ -137,21 +135,23 @@ export class ChangeRegistry {
       console.warn('⚠️  renameChange: 新旧名称相同，跳过');
       return;
     }
-    const db = await this.pm._ensureDB(cwd);
+    const db = this.pm._ensureDB(cwd);
     // 检查旧名是否存在
-    const existing = db.transaction((sqlDb) => {
-      const row = sqlDb.exec(`SELECT name, status FROM changes WHERE name = ?`, [oldName]);
-      if (!row || !row[0] || row[0].values.length === 0) return null;
-      return { name: row[0].values[0][0], status: row[0].values[0][1] };
+    const existing = db.transaction(() => {
+      const sqlDb = db.getDb();
+      const row = sqlDb.prepare(`SELECT name, status FROM changes WHERE name = ?`).get(oldName);
+      if (row === undefined) return null;
+      return { name: row.name, status: row.status };
     });
     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;
+    const conflict = db.transaction(() => {
+      const sqlDb = db.getDb();
+      const row = sqlDb.prepare(`SELECT name FROM changes WHERE name = ?`).get(newName);
+      return row !== undefined;
     });
     if (conflict) {
       console.error(`❌ 变更 ${newName} 已存在`);
@@ -164,8 +164,9 @@ export class ChangeRegistry {
     const newDir = this.pm._changePath(cwd, newName);
     const now = new Date().toISOString();
     try {
-      db.transaction((sqlDb) => {
-        sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+        sqlDb.prepare(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`).run(newName, now, oldName);
       });
     } catch (e) {
       console.error(`❌ 重命名失败：更新数据库时出错（${e.message}）`);
@@ -179,8 +180,9 @@ export class ChangeRegistry {
         renamed = false;
         // FS 重命名失败：回滚 DB 恢复 oldName，保持 DB 与目录一致
         try {
-          db.transaction((sqlDb) => {
-            sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [oldName, now, newName]);
+          db.transaction(() => {
+            const sqlDb = db.getDb();
+            sqlDb.prepare(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`).run(oldName, now, newName);
           });
           console.error(`❌ 重命名失败：移动目录出错（${e.message}），已回滚数据库`);
         } catch (rollbackErr) {
@@ -199,18 +201,18 @@ export class ChangeRegistry {
    * 从活跃列表移除变更（归档时调用，不物理删除）
    * SQL: UPDATE changes SET status = 'archived'
    */
-  async unregisterChange(cwd, changeName) {
+  unregisterChange(cwd, changeName) {
     if (!changeName) {
       console.warn('⚠️  unregisterChange: changeName 为空，跳过');
       return;
     }
-    const db = await this.pm._ensureDB(cwd);
-    db.transaction((sqlDb) => {
+    const db = this.pm._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
       const now = new Date().toISOString();
-      sqlDb.run(
-        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`,
-        [now, changeName]
-      );
+      sqlDb.prepare(
+        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`
+      ).run(now, changeName);
     });
   }
 }

package/src/progress/consistency-doctor.js

@@ -1,9 +1,10 @@
 // W6 Step9a: Revision v1 状态一致性检查 + 修复 + --force 审计日志。
 // 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm.read / pm._write /
 // pm._ensureRuntimeDir / pm._runtimePath（persistence-core 留 facade 本体）。
-import { appendFileSync } from 'fs';
-import { existsSync } from 'fs';
-import { STAGE_ORDER } from './shared.js';
+import { appendFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { summarizeTaskCompletion } from '../task-review.js';
+import { STAGE_ORDER, MAIN_FLOW_ORDER } from './shared.js';
 
 export class ConsistencyDoctor {
   constructor(pm) {
@@ -32,8 +33,8 @@ export class ConsistencyDoctor {
    * @param {string|null} changeName
    * @returns {{ ok: boolean, issues: string[], warnings: string[] }}
    */
-  async checkConsistency(cwd, changeName = null) {
-    const data = await this.pm.read(cwd, changeName);
+  checkConsistency(cwd, changeName = null) {
+    const data = this.pm.read(cwd, changeName);
     if (!data) {
       return { ok: false, issues: ['无法读取进度数据'], warnings: [] };
     }
@@ -71,9 +72,11 @@ export class ConsistencyDoctor {
       }
 
       // d. 下游 completed 不能出现在上游 stale/revising 之后
-      const stageIdx = STAGE_ORDER.indexOf(stageName);
+      // 用 MAIN_FLOW_ORDER（不含 scan）算上下游：scan 是 auxiliary 永不要求 completed，
+      // 把 scan 当上游会让「scan stale/revising」误报 brainstorm 不该 completed（plan-c 同根因）。
+      const stageIdx = MAIN_FLOW_ORDER.indexOf(stageName);
       for (let i = 0; i < stageIdx; i++) {
-        const upstream = STAGE_ORDER[i];
+        const upstream = MAIN_FLOW_ORDER[i];
         const upData = data.stages[upstream];
         if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
           if (sd.status === 'completed') {
@@ -91,6 +94,12 @@ export class ConsistencyDoctor {
       }
     }
 
+    // FR-07 / AC-03 / design §7 / D-02：lost-update 间接信号
+    // （.runtime/worktrees/<change> 目录残留 vs DB current_stage≠execute）。
+    // 只读诊断并入 issues 报告，不写 DB / 不删 worktree / 不自动修复。
+    const lostUpdateSignals = this.detectLostUpdateSignals(cwd);
+    issues.push(...lostUpdateSignals);
+
     // 输出报告
     console.log('');
     console.log('  ═══════════════════════════════════════');
@@ -114,6 +123,55 @@ export class ConsistencyDoctor {
     return { ok: issues.length === 0, issues, warnings };
   }
 
+  /**
+   * 检测 lost-update 间接信号（FR-07 / AC-03 / design §7 / D-02）。
+   *
+   * 判据：.runtime/worktrees/<change> 目录存在但 DB current_stage ≠ 'execute'
+   * → worktree 残留但进度被回退，是并发场景下 lost-update 的间接痕迹。
+   *
+   * 信号定义严格遵循 design §7 / FR-07：仅 current_stage !== 'execute' 判信号，
+   * 不扩展到 quick 等其它 stage；DB 无对应行（data=null）的 worktree 目录不算信号。
+   *
+   * 只读诊断：不写 DB、不删 worktree 目录、不自动修复
+   * （修复仍走 doctor --align / repairConsistency 既有逻辑）。
+   *
+   * @param {string} cwd
+   * @returns {string[]} issue 描述数组（每条含 change 名、实际 current_stage、worktree 目录路径）
+   */
+  detectLostUpdateSignals(cwd) {
+    const worktreesRoot = this.pm._runtimePath(cwd, 'worktrees');
+    // 零信号兼容既有 fixture：worktrees 目录不存在或读取失败时直接返回空数组
+    if (!existsSync(worktreesRoot)) return [];
+
+    let entries;
+    try {
+      entries = readdirSync(worktreesRoot, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+
+    const issues = [];
+    for (const entry of entries) {
+      // Dirent.isDirectory 在 Windows / Linux / macOS 上一致判定目录项
+      if (!entry.isDirectory()) continue;
+      const changeName = entry.name;
+      const worktreeDir = join(worktreesRoot, changeName);
+
+      // 复用 pm.read（task-08 已同步化，直接拿返回值，无 await），不新开 DB 连接
+      const data = this.pm.read(cwd, changeName);
+      // DB 无对应行（data=null）不算信号，跳过
+      if (!data) continue;
+      // 仅 current_stage !== 'execute' 判信号
+      if (data.currentStage !== 'execute') {
+        issues.push(
+          `lost-update 信号: change "${changeName}" 的 worktree 目录仍存在（${worktreeDir}），` +
+          `但 current_stage 为 "${data.currentStage}"（非 execute，疑进度被回退）`
+        );
+      }
+    }
+    return issues;
+  }
+
   /**
    * Revision v1.2 状态修复
    * 默认 dry-run，--apply 才真正修改 DB。
@@ -125,10 +183,10 @@ export class ConsistencyDoctor {
    * @param {string|null} [opts.changeName]
    * @returns {{ fixable: object[], manual: string[], applied: object[] }}
    */
-  async repairConsistency(cwd, opts = {}) {
+  repairConsistency(cwd, opts = {}) {
     const { apply = false, changeName = null } = opts;
 
-    const data = await this.pm.read(cwd, changeName);
+    const data = this.pm.read(cwd, changeName);
     if (!data) {
       console.log('❌ 无法读取进度数据');
       return { fixable: [], manual: ['无法读取进度数据'], applied: [] };
@@ -156,10 +214,10 @@ export class ConsistencyDoctor {
         });
       }
 
-      // Fix b: 上游 stale/revising，下游仍 completed → cascade stale
-      const stageIdx = STAGE_ORDER.indexOf(stageName);
+      // Fix b: 上游 stale/revising，下游仍 completed → cascade stale（同 d，用 MAIN_FLOW_ORDER 排除 scan）
+      const stageIdx = MAIN_FLOW_ORDER.indexOf(stageName);
       for (let i = 0; i < stageIdx; i++) {
-        const upstream = STAGE_ORDER[i];
+        const upstream = MAIN_FLOW_ORDER[i];
         const upData = data.stages[upstream];
         if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
           if (sd.status === 'completed') {
@@ -206,7 +264,6 @@ export class ConsistencyDoctor {
             const changeDir = this.pm._changePath(cwd, changeName);
             if (changeDir && existsSync(changeDir)) {
               const runtimeRoot = this.pm._runtimePath(cwd);
-              const { summarizeTaskCompletion } = await import('../task-review.js');
               const summary = summarizeTaskCompletion({ changeDir, runtimeRoot, changeName });
               if (summary.source === 'review.json' && summary.total > 0 && summary.pending.length === 0) {
                 const desc = `execute: ${badSteps.length} 个 step 状态脱钩（${badSteps.map(st => st.name).join(', ')}）——review.json 客观产出全通过（${summary.completed}/${summary.total}），自动标 completed`;
@@ -286,7 +343,7 @@ export class ConsistencyDoctor {
 
     if (apply && applied.length > 0) {
       data.lastActive = now;
-      await this.pm._write(cwd, data, changeName);
+      this.pm._write(cwd, data, changeName);
       console.log(`\n  ✅ 已修复 ${applied.length} 项`);
     }
 

package/src/progress/shared.js

@@ -18,10 +18,13 @@ export const STAGE_LABELS = {
   archive: '📦 归档变更',
 };
 
-// 完整主流程顺序（含 scan），用于下游 cascade / 一致性检查
+// 完整阶段顺序（含 scan），仅用于展示/迭代顺序
 export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive'];
-// 主流程阶段（不含 scan/quick/explore 等辅助阶段）—— 当前与 STAGE_ORDER 同值
-export const MAIN_FLOW_ORDER = STAGE_ORDER;
+// 主流程阶段（不含 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）
 export const CURRENT_VERSION = 3;