sillyspec 3.25.11 → 3.26.1

package/src/index.js

@@ -84,6 +84,8 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
   sillyspec backfill-reviews --change <name> [--json]  为手动补的 task 生成 review.json 草稿（cannot_verify，解 archive 客观完成度阻断）
+  sillyspec register-stage-review --change <name> --stage <brainstorm|plan|execute> [--from <review.json>] [--json]
+                                      生成/adopt stage 级 review.json（docHash 自动算 + 写 marker，治 tier=independent marker 死锁）
 
   sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
     （无子命令）                       跑诊断，列出问题
@@ -458,6 +460,41 @@ async function main() {
       }
       break;
     }
+    case 'register-stage-review': {
+      // 手动注册 stage 级 review（brainstorm/plan/execute-acceptance）的确定性 writer ——
+      // 生成 run 目录 + review.json 骨架（cannot_verify，待独立审查子代理填 verdict）或 adopt
+      // agent 草稿（--from，保留 verdict/checklist 重算 docHash）+ 写 marker。治 tier=independent 时
+      // 调度者手动派独立子代理不写 marker 的死锁。docHash 由 CLI computeDocHash 算（部分实现 P6.1b defer）。
+      // 纯新增，不改 gate 语义。与 task 级 backfill-reviews 对称（stage 级等价物）。
+      const rsrChangeIdx = args.indexOf('--change');
+      const rsrChange = rsrChangeIdx >= 0 && args[rsrChangeIdx + 1] ? args[rsrChangeIdx + 1] : null;
+      const rsrStageIdx = args.indexOf('--stage');
+      const rsrStage = rsrStageIdx >= 0 && args[rsrStageIdx + 1] ? args[rsrStageIdx + 1] : null;
+      const rsrFromIdx = args.indexOf('--from');
+      const rsrFrom = rsrFromIdx >= 0 && args[rsrFromIdx + 1] ? args[rsrFromIdx + 1] : null;
+      if (!rsrChange || !rsrStage) {
+        console.error('用法: sillyspec register-stage-review --change <名> --stage <brainstorm|plan|execute> [--from <review.json>] [--spec-dir <path>] [--json]\n  生成/adopt stage 级 review.json（docHash 自动算 + 写 marker），治 tier=independent marker 死锁');
+        process.exit(2);
+      }
+      const { registerStageReview } = await import('./stage-review.js');
+      const rsrPlatformOpts = {};
+      if (specDir) rsrPlatformOpts.specRoot = specDir;
+      try {
+        const result = registerStageReview({ changeName: rsrChange, stage: rsrStage, fromFile: rsrFrom, cwd: dir, platformOpts: rsrPlatformOpts });
+        if (json) {
+          process.stdout.write(JSON.stringify({ ok: true, command: 'register-stage-review', change: rsrChange, stage: rsrStage, ...result }));
+        } else {
+          console.log(`✅ 已注册 ${rsrStage} stage review [${result.reviewRunId}] → ${result.reviewPath}（mode: ${result.mode}）`);
+          console.log(`   marker → ${result.markerPath}`);
+          console.log(`   下一步：独立审查子代理对照 ${result.mainDoc} 填 verdict/checklist 后重跑 --done`);
+        }
+      } catch (e) {
+        if (json) process.stdout.write(JSON.stringify({ ok: false, command: 'register-stage-review', error: e.message }));
+        else console.error('❌ ' + e.message);
+        process.exitCode = 1;
+      }
+      break;
+    }
     case 'docs': {
       const docsSubCmd = filteredArgs[1];
       if (docsSubCmd === 'migrate') {
@@ -612,6 +649,10 @@ async function main() {
       const { runCommand } = await import('./run.js')
       const stageArgs = [command, ...filteredArgs.slice(1)]
       const effectiveDir = specDir ? dir : resolveEffectiveDir(dir)
+      // 下行 pull：stage 命令（run/--done，含 archive）启动时拉一次（task-10 / D-009 / FR-04）
+      // 不在每步 pull，仅低频边界点；未连接平台静默跳过
+      const { triggerPullActiveChange } = await import('./run/shared.js')
+      await triggerPullActiveChange(effectiveDir)
       await runCommand(stageArgs, effectiveDir, specDir, { json })
       break
     }
@@ -734,6 +775,12 @@ SillySpec worktree — git worktree 隔离管理
             for (const err of result.errors) {
               console.error(`   ${err}`);
             }
+            if (result.rescueCommands) {
+              console.error('');
+              console.error(`🆘 Rescue commands (${result.rescueCommands.cpFileCount} safe / ${result.rescueCommands.excludedCount} excluded，旁路 git apply，cp 后需手动 sillyspec worktree cleanup ${wtName}):`);
+              for (const c of result.rescueCommands.commands) console.error(`   ${c}`);
+              for (const w of result.rescueCommands.warnings) console.error(`   ⚠️  ${w}`);
+            }
             process.exit(1);
           }
 
@@ -795,6 +842,12 @@ SillySpec worktree — git worktree 隔离管理
             for (const w of assessment.warnings) console.log(`   ⚠️  ${w}`);
           }
 
+          if (assessment.rescueCommands) {
+            console.log('');
+            console.log(`🆘 Rescue commands (${assessment.rescueCommands.cpFileCount} safe / ${assessment.rescueCommands.excludedCount} excluded，旁路 git apply，cp 后需手动 sillyspec worktree cleanup ${wtName}):`);
+            for (const c of assessment.rescueCommands.commands) console.log(`   ${c}`);
+            for (const w of assessment.rescueCommands.warnings) console.log(`   ⚠️  ${w}`);
+          }
           console.log('');
           if (assessment.decision === 'SAFE' || assessment.decision === 'WARNING') {
             console.log('Action: auto-applying...');
@@ -1045,6 +1098,8 @@ SillySpec platform — SillyHub 平台同步
   sillyspec platform disconnect
   sillyspec platform sync [--change <name>]
   sillyspec platform sync-docs [--change <name>]
+  sillyspec platform pull [--change <name>]
+  sillyspec platform resolve <change-name> <--keep-local|--take-platform|--abort>
   sillyspec platform status
   sillyspec platform pointer [--cleanup]
   sillyspec platform approve <change-name>
@@ -1145,15 +1200,108 @@ SillySpec platform — SillyHub 平台同步
           await syncModule.syncDocuments(syncDocsChangeName, dir);
           break;
         }
-        case 'status':
-          await syncModule.status(dir);
+        case 'status': {
+          // task-14 / FR-05：扩展 status（落后标记 + 未决冲突列表）；未连接输出与现状一致
+          const st = await syncModule.collectStatus(dir);
+          if (!st.connected) {
+            console.log('平台: 未连接');
+            break;
+          }
+          console.log(`平台: ${st.url}`);
+          console.log(`上次连接: ${st.lastSync || '未知'}`);
+          if (st.listFailed) {
+            console.log('ℹ️  无法连接平台获取落后状态');
+          } else if (st.behind.length > 0) {
+            console.log(`⚠️ 本地可能落后（${st.behind.length} 个变更平台有更新）:`);
+            for (const b of st.behind) {
+              console.log(`   - ${b.name}: 平台 ${b.platform_pushed_at} > 本地 ${b.local_synced}`);
+            }
+          } else {
+            console.log('✅ 本地与平台进度同步');
+          }
+          if (st.conflicts.length > 0) {
+            console.log(`⚠️ 未决冲突（${st.conflicts.length} 个，请 platform resolve 处理）:`);
+            for (const c of st.conflicts) {
+              console.log(`   - ${c.change}${c.created_at ? ` (创建于 ${c.created_at})` : ''}`);
+            }
+          }
           break;
+        }
+        case 'pull': {
+          // task-11 / D-006 / D-009 / FR-03：手动下行拉取平台进度到本地。
+          // 与自动 triggerPull 共用 syncModule.pull（SyncManager.pull 实例方法），行为一致。
+          const pullChangeIdx = args.indexOf('--change');
+          const pullChangeName = pullChangeIdx >= 0 && args[pullChangeIdx + 1] ? args[pullChangeIdx + 1] : null;
+          // 未连接明确提示不崩（acceptance：未连接平台输出明确提示）
+          const smForCheck = new syncModule.SyncManager(dir);
+          if (!smForCheck._getPlatform()) {
+            console.error('❌ 未连接平台，请先 sillyspec platform connect');
+            process.exit(1);
+          }
+          if (pullChangeName) {
+            // 单变更完整 pull（两级 pull 第二级）
+            const r = await syncModule.pull(pullChangeName, {}, dir);
+            if (r.conflict) {
+              console.log(`⚠️ ${pullChangeName}: 冲突（已写 sync-conflict 文件），请 sillyspec platform resolve 处理`);
+            } else if (r.imported) {
+              console.log(`✅ ${pullChangeName}: 已拉取并 import`);
+            } else {
+              console.log(`⏭️ ${pullChangeName}: 未 import（${r.reason || '无变更'}）`);
+            }
+          } else {
+            // 无 --change：先拉轻量列表（两级 pull 第一级），再对每个 change 按需完整 pull
+            const list = await syncModule.pullList(dir);
+            if (!list.ok) {
+              console.error(`❌ 拉取变更列表失败: ${list.reason || '未知'}`);
+              process.exit(1);
+            }
+            console.log(`平台变更 ${list.changes.length} 个：`);
+            let importedCount = 0, conflictCount = 0;
+            for (const ch of list.changes) {
+              const name = typeof ch === 'string' ? ch : ch.name;
+              if (!name) continue;
+              const r = await syncModule.pull(name, {}, dir);
+              if (r.imported) { importedCount++; console.log(`  ✅ ${name}: 已 import`); }
+              else if (r.conflict) { conflictCount++; console.log(`  ⚠️ ${name}: 冲突，请 platform resolve`); }
+              else { console.log(`  ⏭️ ${name}: ${r.reason || '未 import'}`); }
+            }
+            console.log(`拉取完成：imported ${importedCount}，冲突 ${conflictCount}`);
+          }
+          break;
+        }
+        case 'resolve': {
+          // task-13 / D-002 / D-010 / D-013 / FR-05：冲突解决三选一（绝不字段级 auto-merge）
+          const resolveName = platformArgs[0];
+          if (!resolveName) {
+            console.error('❌ 用法: sillyspec platform resolve <change-name> <--keep-local|--take-platform|--abort>');
+            process.exit(1);
+          }
+          // 解析 mode flag（三选一互斥，多传/不传均报错）
+          const resolveFlags = ['--keep-local', '--take-platform', '--abort'].filter((f) => args.includes(f));
+          if (resolveFlags.length !== 1) {
+            console.error('❌ 必须恰好指定 --keep-local / --take-platform / --abort 之一');
+            process.exit(1);
+          }
+          const modeMap = { '--keep-local': 'keep-local', '--take-platform': 'take-platform', '--abort': 'abort' };
+          const resolveMode = modeMap[resolveFlags[0]];
+          const r = await syncModule.resolve(resolveName, resolveMode, dir);
+          if (r.ok && r.resolved) {
+            console.log(`✅ ${resolveName} [${resolveMode}]: ${r.reason}`);
+          } else {
+            console.error(`❌ ${resolveName}: ${r.reason}`);
+            process.exit(1);
+          }
+          break;
+        }
         case 'approve': {
           const approveName = platformArgs[0];
           if (!approveName) {
             console.error('❌ 用法: sillyspec platform approve <change-name>');
             process.exit(1);
           }
+          // 审批前下行 pull（task-10 / D-009 / FR-06）：拉最新进度避免基于过期状态审批；未连接跳过
+          const { triggerPull } = await import('./run/shared.js');
+          await triggerPull(dir, approveName);
           await syncModule.approve(approveName, dir);
           break;
         }
@@ -1481,7 +1629,7 @@ SillySpec modules — 模块文档管理
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
       if (command === '--status') {

package/src/local-detect.js

@@ -1,110 +1,120 @@
-/**
- * Local Detect — 纯 fs 项目类型嗅探
- *
- * 把"生成本地配置"里的项目类型判定从 scan（半小时 + 大量 token）抽出来，
- * 变成纯 fs 同步读几秒可完成的独立探测。create/gate 只需 project.type +
- * commands，不该被迫跑完整 scan。
- *
- * 纯函数：不 spawn 任何子进程、不调用任何 AI/LLM、不消耗 token。
- * 不写 local.yaml 到磁盘——只返回数据结构，落盘由调用方（CLI 路由 / scan.js）负责。
- * 不引 yaml 依赖。
- */
-
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
-
-/**
- * 从 Makefile 文本提取 test 目标的命令（轻量正则，与 verify-postcheck 同风格）。
- * 支持两种常见写法：
- *   - 同行命令：`test: pytest`            → 'pytest'
- *   - tab 续行：`test:\n\tpytest\n`        → 'pytest'（命令在下一 tab 开头行）
- * 边界：
- *   - 纯空目标（`test:` 无同行命令、无 tab 续行）→ 回退 'make test'
- *   - 命令行内 `#` 注释截断；取第一个非空命令行
- * @param {string} makefileText
- * @returns {string}
- */
-function parseMakefileTestCommand(makefileText) {
-  if (!makefileText) return 'make test'
-  // 定位 `test:` 行；捕获 `:` 后同行内容（同行命令或空）
-  const head = makefileText.match(/^test:\s*([^\n#]*?)\s*(?:#.*)?$/m)
-  if (!head) return 'make test'
-  const inline = (head[1] || '').trim()
-  if (inline) return inline
-  // 同行为空 → 找该行之后第一个 tab 续行命令（`\tcmd` 或 `    cmd`）
-  const after = makefileText.slice(head.index + head[0].length)
-  const cont = after.match(/^[ \t]+([^\n#]+?)\s*(?:#.*)?$/m)
-  if (cont && cont[1]) return cont[1].trim()
-  return 'make test'
-}
-
-/**
- * 嗅探 workdir 的项目类型与默认 commands（纯 fs，零 AI / 零 token）。
- *
- * 嗅探规则（按顺序，命中即返回）：
- *   - package.json → nodejs（npm run build / npm test / npm run lint）
- *   - pom.xml → maven（mvn compile / mvn test / mvn checkstyle:check）
- *   - build.gradle → gradle（./gradlew build / test / check）
- *   - Makefile → make（test 命令从 test: 目标解析；build/lint 无则不写）
- *   - 都没有 → generic（commands 为空对象）
- *
- * @param {string} workdir - 项目根目录
- * @returns {{
- *   project: { type: 'nodejs'|'maven'|'gradle'|'make'|'generic' },
- *   commands: { build?: string, test?: string, lint?: string }
- * }}
- */
-export function detectLocalYaml(workdir) {
-  // 1. nodejs
-  if (existsSync(join(workdir, 'package.json'))) {
-    return {
-      project: { type: 'nodejs' },
-      commands: {
-        build: 'npm run build',
-        test: 'npm test',
-        lint: 'npm run lint',
-      },
-    }
-  }
-
-  // 2. maven
-  if (existsSync(join(workdir, 'pom.xml'))) {
-    return {
-      project: { type: 'maven' },
-      commands: {
-        build: 'mvn compile',
-        test: 'mvn test',
-        lint: 'mvn checkstyle:check',
-      },
-    }
-  }
-
-  // 3. gradle
-  if (existsSync(join(workdir, 'build.gradle'))) {
-    return {
-      project: { type: 'gradle' },
-      commands: {
-        build: './gradlew build',
-        test: './gradlew test',
-        lint: './gradlew check',
-      },
-    }
-  }
-
-  // 4. make（test 命令从 Makefile 解析；build/lint 无则省略）
-  const makefilePath = join(workdir, 'Makefile')
-  if (existsSync(makefilePath)) {
-    const makefileText = readFileSync(makefilePath, 'utf8')
-    const test = parseMakefileTestCommand(makefileText)
-    return {
-      project: { type: 'make' },
-      commands: { test },
-    }
-  }
-
-  // 5. generic
-  return {
-    project: { type: 'generic' },
-    commands: {},
-  }
-}
+/**
+ * Local Detect — 纯 fs 项目类型嗅探
+ *
+ * 把"生成本地配置"里的项目类型判定从 scan（半小时 + 大量 token）抽出来，
+ * 变成纯 fs 同步读几秒可完成的独立探测。create/gate 只需 project.type +
+ * commands，不该被迫跑完整 scan。
+ *
+ * 纯函数：不 spawn 任何子进程、不调用任何 AI/LLM、不消耗 token。
+ * 不写 local.yaml 到磁盘——只返回数据结构，落盘由调用方（CLI 路由 / scan.js）负责。
+ * 不引 yaml 依赖。
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+/**
+ * 从 Makefile 文本提取 test 目标的命令（轻量正则，与 verify-postcheck 同风格）。
+ * 支持两种常见写法：
+ *   - 同行命令：`test: pytest`            → 'pytest'
+ *   - tab 续行：`test:\n\tpytest\n`        → 'pytest'（命令在下一 tab 开头行）
+ * 边界：
+ *   - 纯空目标（`test:` 无同行命令、无 tab 续行）→ 回退 'make test'
+ *   - 命令行内 `#` 注释截断；取第一个非空命令行
+ * @param {string} makefileText
+ * @returns {string}
+ */
+function parseMakefileTestCommand(makefileText) {
+  if (!makefileText) return 'make test'
+  // 定位 `test:` 行；捕获 `:` 后同行内容（同行命令或空）
+  const head = makefileText.match(/^test:\s*([^\n#]*?)\s*(?:#.*)?$/m)
+  if (!head) return 'make test'
+  const inline = (head[1] || '').trim()
+  if (inline) return inline
+  // 同行为空 → 找该行之后第一个 tab 续行命令（`\tcmd` 或 `    cmd`）
+  const after = makefileText.slice(head.index + head[0].length)
+  const cont = after.match(/^[ \t]+([^\n#]+?)\s*(?:#.*)?$/m)
+  if (cont && cont[1]) return cont[1].trim()
+  return 'make test'
+}
+
+/**
+ * 嗅探 workdir 的项目类型与默认 commands（纯 fs，零 AI / 零 token）。
+ *
+ * 嗅探规则（按顺序，命中即返回）：
+ *   - package.json → nodejs（核验 scripts.{build,test,lint} 存在才写对应键；缺失不写）
+ *   - pom.xml → maven（mvn compile / mvn test / mvn checkstyle:check）
+ *   - build.gradle → gradle（gradlew 存在用 ./gradlew 否则 gradle；build / test / check）
+ *   - Makefile → make（test 命令从 test: 目标解析；build/lint 无则不写）
+ *   - 都没有 → generic（commands 为空对象）
+ *
+ * @param {string} workdir - 项目根目录
+ * @returns {{
+ *   project: { type: 'nodejs'|'maven'|'gradle'|'make'|'generic' },
+ *   commands: { build?: string, test?: string, lint?: string }
+ * }}
+ */
+export function detectLocalYaml(workdir) {
+  // 1. nodejs
+  if (existsSync(join(workdir, 'package.json'))) {
+    const pkgPath = join(workdir, 'package.json')
+    const raw = readFileSync(pkgPath, 'utf8')
+    let pkg
+    try {
+      pkg = JSON.parse(raw)
+    } catch (e) {
+      throw new Error('package.json 解析失败：' + pkgPath)
+    }
+    const scripts = (pkg && pkg.scripts) || {}
+    const commands = {}
+    if (scripts.build) commands.build = 'npm run build'
+    if (scripts.test) commands.test = 'npm test'
+    if (scripts.lint) commands.lint = 'npm run lint'
+    return {
+      project: { type: 'nodejs' },
+      commands,
+    }
+  }
+
+  // 2. maven
+  if (existsSync(join(workdir, 'pom.xml'))) {
+    return {
+      project: { type: 'maven' },
+      commands: {
+        build: 'mvn compile',
+        test: 'mvn test',
+        lint: 'mvn checkstyle:check',
+      },
+    }
+  }
+
+  // 3. gradle
+  if (existsSync(join(workdir, 'build.gradle'))) {
+    const gradlePrefix = existsSync(join(workdir, 'gradlew')) ? './gradlew' : 'gradle'
+    return {
+      project: { type: 'gradle' },
+      commands: {
+        build: `${gradlePrefix} build`,
+        test: `${gradlePrefix} test`,
+        lint: `${gradlePrefix} check`,
+      },
+    }
+  }
+
+  // 4. make（test 命令从 Makefile 解析；build/lint 无则省略）
+  const makefilePath = join(workdir, 'Makefile')
+  if (existsSync(makefilePath)) {
+    const makefileText = readFileSync(makefilePath, 'utf8')
+    const test = parseMakefileTestCommand(makefileText)
+    return {
+      project: { type: 'make' },
+      commands: { test },
+    }
+  }
+
+  // 5. generic
+  return {
+    project: { type: 'generic' },
+    commands: {},
+  }
+}

package/src/progress/change-registry.js

@@ -33,10 +33,12 @@ export class ChangeRegistry {
       const sqlDb = db.getDb();
       const now = new Date().toISOString();
       // 尝试插入新行
-      sqlDb.prepare(
+      const ins = sqlDb.prepare(
         `INSERT OR IGNORE INTO changes (name, created_at, last_active)
          VALUES (?, ?, ?)`
       ).run(changeName, now, now);
+      // 只在真正创建 change 时标脏（D-013/task-04）；已存在行不标（读路径/重复调用不误判脏）
+      if (ins.changes > 0) this.pm._touchLocalModified(cwd, changeName, now);
       // 注意：不复活已归档的变更——归档是不可逆操作
       // 如果变更已存在且为 archived，保持 archived 状态不变
     });
@@ -53,15 +55,46 @@ export class ChangeRegistry {
     try {
       db.transaction(() => {
         const sqlDb = db.getDb();
+        const now = new Date().toISOString();
         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);
+        ).run(isolation.status, isolation.mode || null, isolation.reason || null, now, changeName);
+        // 本地脏度（D-013 / task-04）：隔离状态变更也是本地推进
+        this.pm._touchLocalModified(cwd, changeName, now);
       });
     } catch (err) {
       console.warn('⚠️  更新 isolation 状态失败:', err.message);
     }
   }
 
+  /**
+   * 更新变更的人类可读元信息（title / quicklog_id），让 quick-<hex> 行可读、DB↔QUICKLOG 可对账。
+   * quick 启动时回填（title 从任务描述、quicklog_id 用分配的 qlId）；--done 时从 step3「需求：」刷新 title。
+   * 部分更新（只传 title 不动 quicklog_id，反之亦然）。不调 _touchLocalModified：title/quicklog_id 是
+   * 本地展示用元信息，纳入脏度会扰动平台同步（平台 changes 表无此列）。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @param {{ title?: string, quicklogId?: string }} meta
+   */
+  updateChangeMeta(cwd, changeName, meta) {
+    if (!changeName || !meta) return;
+    const db = this.pm._ensureDB(cwd);
+    try {
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+        const sets = [];
+        const params = [];
+        if (meta.title !== undefined) { sets.push('title = ?'); params.push(meta.title); }
+        if (meta.quicklogId !== undefined) { sets.push('quicklog_id = ?'); params.push(meta.quicklogId); }
+        if (sets.length === 0) return;
+        params.push(changeName);
+        sqlDb.prepare(`UPDATE changes SET ${sets.join(', ')} WHERE name = ?`).run(...params);
+      });
+    } catch (err) {
+      console.warn('⚠️  更新 change 元信息失败:', err.message);
+    }
+  }
+
   /**
    * 读取变更的隔离状态
    * @param {string} cwd - 项目根目录
@@ -117,6 +150,8 @@ export class ChangeRegistry {
         status === 'approved' ? now : null,
         status === 'rejected' ? reason : null,
       );
+      // 本地脏度（D-013 / task-04）：审批状态变更也是本地推进
+      this.pm._touchLocalModified(cwd, changeName, now);
     });
   }
 
@@ -167,6 +202,8 @@ export class ChangeRegistry {
       db.transaction(() => {
         const sqlDb = db.getDb();
         sqlDb.prepare(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`).run(newName, now, oldName);
+        // 本地脏度（D-013 / task-04）：重命名也是本地推进（标新名）
+        this.pm._touchLocalModified(cwd, newName, now);
       });
     } catch (e) {
       console.error(`❌ 重命名失败：更新数据库时出错（${e.message}）`);
@@ -183,6 +220,8 @@ export class ChangeRegistry {
           db.transaction(() => {
             const sqlDb = db.getDb();
             sqlDb.prepare(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`).run(oldName, now, newName);
+            // 回滚也是写（恢复 oldName），对称标脏旧名
+            this.pm._touchLocalModified(cwd, oldName, now);
           });
           console.error(`❌ 重命名失败：移动目录出错（${e.message}），已回滚数据库`);
         } catch (rollbackErr) {
@@ -213,6 +252,8 @@ export class ChangeRegistry {
       sqlDb.prepare(
         `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`
       ).run(now, changeName);
+      // 本地脏度（D-013 / task-04）：归档也是本地状态推进
+      this.pm._touchLocalModified(cwd, changeName, now);
     });
   }
 }

package/src/progress/shared.js

@@ -26,8 +26,8 @@ export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', '
 // （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;
+// progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8）
+export const CURRENT_VERSION = 5;
 
 // 空阶段骨架
 export function emptyStage() {

package/src/progress/stage-machine.js

@@ -98,6 +98,8 @@ export class StageMachine {
 
       // UPDATE changes.last_active
       sqlDb.prepare('UPDATE changes SET last_active = ? WHERE name = ?').run(now, cn);
+      // 本地脏度（D-013 / task-04）：阶段完成是本地推进
+      this.pm._touchLocalModified(cwd, cn, now);
     });
 
     // 写 history 文件（保持文件系统，不变）
@@ -492,6 +494,8 @@ export class StageMachine {
             for (const s of VALID_STAGES) {
               sqlDb.prepare(`INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, 'pending')`).run(changeId, s);
             }
+            // 本地脏度（D-013 / task-04）：重置该变更全部进度是本地推进
+            this.pm._touchLocalModified(cwd, changeName);
           }
         });
         console.log(`✅ 已重置变更 ${changeName} 的进度`);
@@ -507,6 +511,8 @@ export class StageMachine {
               const changeId = changeRow.id;
               sqlDb.prepare('DELETE FROM steps WHERE stage_id IN (SELECT id FROM stages WHERE change_id = ?)').run(changeId);
               sqlDb.prepare(`UPDATE stages SET status = 'pending', started_at = NULL, completed_at = NULL WHERE change_id = ?`).run(changeId);
+              // 本地脏度（D-013 / task-04）：重置进度是本地推进
+              this.pm._touchLocalModified(cwd, cn);
             }
           }
         });

package/src/progress/step-store.js

@@ -47,6 +47,9 @@ export class StepStore {
 
       // 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) {
@@ -100,6 +103,8 @@ export class StepStore {
          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}`);
@@ -166,6 +171,8 @@ export class StepStore {
       }
 
       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) {
@@ -227,6 +234,9 @@ export class StepStore {
            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);
     });
   }