sillyspec 3.25.11 → 3.26.0

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,9 +55,12 @@ 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);
@@ -117,6 +122,8 @@ export class ChangeRegistry {
         status === 'approved' ? now : null,
         status === 'rejected' ? reason : null,
       );
+      // 本地脏度（D-013 / task-04）：审批状态变更也是本地推进
+      this.pm._touchLocalModified(cwd, changeName, now);
     });
   }
 
@@ -167,6 +174,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 +192,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 +224,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 = 4;
 
 // 空阶段骨架
 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);
     });
   }
 

package/src/progress.js

@@ -10,7 +10,7 @@
  * worktree-guard hook 直读 sillyspec.db，不再有 gate-status.json 缓存双源（task-10 废除）。
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir } from 'os';
 import { DB } from './db.js';
@@ -347,7 +347,7 @@ export class ProgressManager {
     }
 
     const result = {
-      _version: 3,
+      _version: 4,
       project: projectName,
       currentChange: cName,
       currentStage: currentStage || '',
@@ -364,6 +364,292 @@ export class ProgressManager {
     return result;
   }
 
+  /**
+   * 同步专用六表完整序列化（design §8/B1，task-02 / D-005@v2 / FR-07）。
+   * 与 read()（聚合视图，不读 approvals 且 changes 只投影五列）不同，本方法输出真正六表投影，
+   * 作为同步载体（ProgressManager.import() 的逆运算，task-03）。
+   *
+   * 输出契约（字段名 = DB 列名 snake_case，import 直接对列写回，round-trip 无映射损耗）：
+   *   project        { name, schema_version }                                        —— 全局单行稳定字段（id/created_at/updated_at 本地元数据不同步）
+   *   changes        [{ name, current_stage, status, last_active,
+   *                      last_synced_platform_ts, last_local_modified_ts }]           —— 只投影流程进度列；
+   *                     排除 isolation_* 系列 与 platform_* 系列（platform_change_id/workspace_id/last_sync/sync_enabled）
+   *                     以及 created_at（本地强相关，不同步，B2）
+   *   stages         [{ change_name, stage, status, started_at, completed_at,
+   *                      revision, reopened_from_step, reopened_at, stale_reason }]   —— 用 change_name+stage 替代 id 外键
+   *   steps          [{ change_name, stage, name, status, output, completed_at, ordering,
+   *                      wait_reason, wait_options, wait_answer, waited_at, wait_answers,
+   *                      wait_round, max_wait_rounds }]                               —— wait_options/wait_answers 透传 DB JSON 字符串
+   *   batch_progress [{ change_name, total, completed, failed, skipped }]
+   *   approvals      [{ change_name, status, requested_at, approved_by, approved_at, rejection_reason }]
+   * 可空列归一为 null（非 undefined，保证 JSON 往返键稳定）；不含 user/base_ts/pushed_at（D-015，sync.js 放 HTTP header）。
+   *
+   * @param {string} cwd
+   * @param {string|null} [changeName] - 空时单活跃变更自动推导（对齐 read()）；多/零活跃返回 null
+   * @returns {object|null} 六键同步 JSON；change 不存在或无法推导返回 null
+   */
+  serializeForSync(cwd, changeName = null) {
+    // 自动检测变更名（与 read() 同口径）：单活跃变更推导，多/零无法确定返回 null
+    if (!changeName) {
+      const changes = this.listChanges(cwd);
+      if (changes.length === 1) {
+        changeName = changes[0];
+      } else {
+        return null;
+      }
+    }
+
+    const db = this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+
+    // 1. changes 行（投影流程进度列 + name 标识）
+    const changeRow = sqlDb.prepare(
+      `SELECT id, name, current_stage, status, last_active, last_synced_platform_ts, last_local_modified_ts
+       FROM changes WHERE name = ?`
+    ).get(changeName);
+    if (changeRow === undefined) return null;
+    const changeId = changeRow.id;
+    const changeProj = {
+      name: changeRow.name,
+      current_stage: changeRow.current_stage,
+      status: changeRow.status,
+      last_active: changeRow.last_active,
+      last_synced_platform_ts: changeRow.last_synced_platform_ts ?? null,
+      last_local_modified_ts: changeRow.last_local_modified_ts ?? null,
+    };
+
+    // 2. project 全局单行（只投影稳定字段 name/schema_version；created_at/updated_at 是本地库元数据，
+    //    同步无意义且破坏 round-trip 跨库等值——与 changes 排除 created_at 同理，B2）
+    const projectRow = sqlDb.prepare(
+      'SELECT name, schema_version FROM project WHERE id = 1'
+    ).get();
+
+    // 3. stages（该 change 下，用 change_name+stage 表达外键）
+    const stageRows = sqlDb.prepare(
+      `SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason
+       FROM stages WHERE change_id = ? ORDER BY id`
+    ).all(changeId);
+    const stageJson = stageRows.map(r => ({
+      change_name: changeRow.name,
+      stage: r.stage,
+      status: r.status,
+      started_at: r.started_at ?? null,
+      completed_at: r.completed_at ?? null,
+      revision: r.revision ?? null,
+      reopened_from_step: r.reopened_from_step ?? null,
+      reopened_at: r.reopened_at ?? null,
+      stale_reason: r.stale_reason ?? null,
+    }));
+
+    // 4. steps（stage_id IN；用 change_name+stage 关联回 stage）
+    const stageIds = stageRows.map(r => r.id);
+    const stageIdToName = new Map(stageRows.map(r => [r.id, r.stage]));
+    let stepJson = [];
+    if (stageIds.length > 0) {
+      const placeholders = stageIds.map(() => '?').join(',');
+      const stepRows = sqlDb.prepare(
+        `SELECT stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options,
+                wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds
+         FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+      ).all(...stageIds);
+      stepJson = stepRows.map(r => ({
+        change_name: changeRow.name,
+        stage: stageIdToName.get(r.stage_id),
+        name: r.name,
+        status: r.status,
+        output: r.output ?? null,
+        completed_at: r.completed_at ?? null,
+        ordering: r.ordering ?? null,
+        wait_reason: r.wait_reason ?? null,
+        wait_options: r.wait_options ?? null,
+        wait_answer: r.wait_answer ?? null,
+        waited_at: r.waited_at ?? null,
+        wait_answers: r.wait_answers ?? null,
+        wait_round: r.wait_round ?? null,
+        max_wait_rounds: r.max_wait_rounds ?? null,
+      }));
+    }
+
+    // 5. batch_progress（无行则空数组，import 侧幂等）
+    const batchRow = sqlDb.prepare(
+      'SELECT total, completed, failed, skipped FROM batch_progress WHERE change_id = ?'
+    ).get(changeId);
+    const batchJson = batchRow !== undefined ? [{
+      change_name: changeRow.name,
+      total: batchRow.total,
+      completed: batchRow.completed,
+      failed: batchRow.failed,
+      skipped: batchRow.skipped,
+    }] : [];
+
+    // 6. approvals（read() 不读此表，serializeForSync 补齐；无行则空数组）
+    const approvalRow = sqlDb.prepare(
+      'SELECT status, requested_at, approved_by, approved_at, rejection_reason FROM approvals WHERE change_id = ?'
+    ).get(changeId);
+    const approvalJson = approvalRow !== undefined ? [{
+      change_name: changeRow.name,
+      status: approvalRow.status,
+      requested_at: approvalRow.requested_at ?? null,
+      approved_by: approvalRow.approved_by ?? null,
+      approved_at: approvalRow.approved_at ?? null,
+      rejection_reason: approvalRow.rejection_reason ?? null,
+    }] : [];
+
+    return {
+      project: projectRow || null,
+      changes: [changeProj],
+      stages: stageJson,
+      steps: stepJson,
+      batch_progress: batchJson,
+      approvals: approvalJson,
+    };
+  }
+
+  /**
+   * serializeForSync 的逆运算：把平台权威 JSON 原子写回本地 DB 的该 change 行（design §8/B1，task-03 / D-005@v2 / D-011 / FR-07）。
+   * ⚠️ 必须保护真实资产：import 前对 DB 做【独立】snapshot `.runtime/sillyspec.db.pre-import-<ts>.bak`，
+   *   不抢 _openWithFallback 的 `${dbPath}.bak`（gap5/R-08）；任何失败本地进度库不损坏。
+   *
+   * 语义：
+   * - 单个 DB.transaction() 包裹，原子重建 stages/steps/batch_progress/approvals 四表（任一失败整体回滚）
+   * - changes 行用 UPDATE 选择投影列（current_stage/status/last_active/last_synced_platform_ts/last_local_modified_ts），
+   *   保留 isolation_* / platform_* / created_at（本地强相关状态不被覆盖，B2；change 不存在时 INSERT 兜底平台新增）
+   * - import 后 last_synced_platform_ts 与 last_local_modified_ts 均置为 progressObj.pushed_at（D-013 例外：
+   *   不更新 now()——否则 now()>base_ts 下次 pull 误判冲突；pushed_at 由 sync.js pull() 从响应 header attach）
+   * - 本地确定性操作，失败 throw 中文（非 sync 类 Best Effort，CONVENTIONS #4）
+   *
+   * @param {string} cwd
+   * @param {object} progressObj - serializeForSync 输出 + sync.js 附加的 pushed_at
+   * @param {string|null} [changeName] - 空则从 progressObj.changes[0].name 推导
+   * @returns {ImportResult} { ok:true, imported:changeName, reason?, bakPath }
+   */
+  import(cwd, progressObj, changeName = null) {
+    if (!progressObj || typeof progressObj !== 'object') {
+      throw new Error('import 参数无效：progressObj 必须是 serializeForSync() 输出的六表 JSON 对象');
+    }
+
+    const cn = changeName || (progressObj.changes && progressObj.changes[0] && progressObj.changes[0].name);
+    if (!cn) {
+      throw new Error('import 缺少 changeName：无法定位目标 change（progressObj.changes[0].name 为空）');
+    }
+
+    // ⚠️ 必须保护真实资产：独立 .bak snapshot（前缀 pre-import- 区分于主 .bak 备份机制）
+    const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      throw new Error(`本地进度库不存在，无法 import：${dbPath}`);
+    }
+    const bakTs = new Date().toISOString().replace(/[:.]/g, '-');
+    const bakPath = this._runtimePath(cwd, `sillyspec.db.pre-import-${bakTs}.bak`);
+    copyFileSync(dbPath, bakPath);
+
+    const pushedAt = progressObj.pushed_at ?? null;
+    const now = new Date().toISOString();
+
+    try {
+      const db = this._ensureDB(cwd);
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+
+        // 1. changes 行：INSERT OR IGNORE 兜底平台新增 change；UPDATE 只覆盖投影列（保留本地隔离/平台/created_at 列）
+        sqlDb.prepare(
+          `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active)
+           VALUES (?, '', 'active', ?, ?)`
+        ).run(cn, now, now);
+        const ch = progressObj.changes && progressObj.changes[0];
+        sqlDb.prepare(
+          `UPDATE changes SET
+             current_stage = ?, status = ?, last_active = ?,
+             last_synced_platform_ts = ?, last_local_modified_ts = ?
+           WHERE name = ?`
+        ).run(
+          ch && ch.current_stage != null ? ch.current_stage : '',
+          ch && ch.status != null ? ch.status : 'active',
+          ch && ch.last_active != null ? ch.last_active : now,
+          pushedAt, pushedAt, cn
+        );
+        const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
+        const changeId = changeRow.id;
+
+        // 2. project 行：幂等确保存在（不覆盖已有全局行，round-trip 等值不受影响；仅补缺失）
+        const projExists = sqlDb.prepare('SELECT id FROM project WHERE id = 1').get();
+        if (projExists === undefined) {
+          const pj = progressObj.project || {};
+          sqlDb.prepare(
+            `INSERT INTO project (id, name, schema_version, created_at, updated_at)
+             VALUES (1, ?, ?, ?, ?)`
+          ).run(pj.name != null ? pj.name : 'project', pj.schema_version != null ? pj.schema_version : CURRENT_VERSION, now, now);
+        }
+
+        // 3. 重建 stages + steps：DELETE stages（ON DELETE CASCADE 级联删 steps），按 JSON 重建
+        sqlDb.prepare('DELETE FROM stages WHERE change_id = ?').run(changeId);
+        const stageToId = new Map();
+        for (const s of (progressObj.stages || [])) {
+          if (!s || !s.stage) continue;
+          sqlDb.prepare(
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          ).run(changeId, s.stage, s.status != null ? s.status : 'pending', s.started_at ?? null, s.completed_at ?? null,
+            s.revision != null ? s.revision : 0, s.reopened_from_step ?? null, s.reopened_at ?? null, s.stale_reason ?? null);
+          const row = sqlDb.prepare('SELECT id FROM stages WHERE change_id = ? AND stage = ?').get(changeId, s.stage);
+          stageToId.set(s.stage, row.id);
+        }
+        for (const st of (progressObj.steps || [])) {
+          if (!st || !st.name) continue;
+          const stageId = stageToId.get(st.stage);
+          if (stageId === undefined) continue; // 孤儿 step（stage 不在 JSON）跳过，不破坏完整性
+          sqlDb.prepare(
+            `INSERT INTO steps (stage_id, name, status, output, completed_at, ordering, wait_reason, wait_options, wait_answer, waited_at, wait_answers, wait_round, max_wait_rounds)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          ).run(stageId, st.name, st.status != null ? st.status : 'pending', st.output ?? null, st.completed_at ?? null,
+            st.ordering != null ? st.ordering : 0, st.wait_reason ?? null, st.wait_options ?? null, st.wait_answer ?? null,
+            st.waited_at ?? null, st.wait_answers ?? null, st.wait_round ?? null, st.max_wait_rounds ?? null);
+        }
+
+        // 4. 重建 batch_progress（DELETE 再插，无行则清空）
+        sqlDb.prepare('DELETE FROM batch_progress WHERE change_id = ?').run(changeId);
+        const bp = progressObj.batch_progress && progressObj.batch_progress[0];
+        if (bp) {
+          sqlDb.prepare(
+            `INSERT INTO batch_progress (change_id, total, completed, failed, skipped)
+             VALUES (?, ?, ?, ?, ?)`
+          ).run(changeId, bp.total != null ? bp.total : 0, bp.completed != null ? bp.completed : 0,
+            bp.failed != null ? bp.failed : 0, bp.skipped != null ? bp.skipped : 0);
+        }
+
+        // 5. 重建 approvals（DELETE 再插，无行则清空）
+        sqlDb.prepare('DELETE FROM approvals WHERE change_id = ?').run(changeId);
+        const ap = progressObj.approvals && progressObj.approvals[0];
+        if (ap) {
+          sqlDb.prepare(
+            `INSERT INTO approvals (change_id, status, requested_at, approved_by, approved_at, rejection_reason)
+             VALUES (?, ?, ?, ?, ?, ?)`
+          ).run(changeId, ap.status != null ? ap.status : 'not_required', ap.requested_at ?? null, ap.approved_by ?? null,
+            ap.approved_at ?? null, ap.rejection_reason ?? null);
+        }
+      });
+    } catch (e) {
+      // 事务失败自动回滚（DB 未变），.bak 保留可恢复；fail-loud 中文
+      throw new Error(`import 失败，本地进度库已回滚（snapshot: ${bakPath}）：${e.message}`);
+    }
+
+    return { ok: true, imported: cn, reason: undefined, bakPath };
+  }
+
+  /**
+   * 本地脏度标记（D-013 / task-04）：写入路径末尾更新 changes.last_local_modified_ts。
+   * 在写方法的事务内调用则属于该事务（原子，失败整体回滚）；import 是例外不调本方法
+   * （import 自己把 last_local_modified_ts 置为 pushed_at，表示本地=平台干净）。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @param {string} [ts] - 复用调用方事务内的时间戳，保证与本次写入同时刻
+   */
+  _touchLocalModified(cwd, changeName, ts = null) {
+    if (!changeName) return;
+    const db = this._ensureDB(cwd);
+    const stamp = ts || new Date().toISOString();
+    db.getDb().prepare('UPDATE changes SET last_local_modified_ts = ? WHERE name = ?').run(stamp, changeName);
+  }
+
   /**
    * 写入指定变更的 progress
    * @param {string} cwd
@@ -392,12 +678,12 @@ export class ProgressManager {
     const db = this._ensureDB(cwd);
     db.transaction(() => {
       const sqlDb = db.getDb();
-      // 1. 更新 changes 表
+      // 1. 更新 changes 表（last_local_modified_ts 脏度：D-013 / task-04）
       const now = new Date().toISOString();
       const noWorktree = data.noWorktree ? 1 : 0;
       sqlDb.prepare(
-        'UPDATE changes SET current_stage = ?, last_active = ?, no_worktree = ? WHERE name = ?'
-      ).run(data.currentStage || '', now, noWorktree, cn);
+        'UPDATE changes SET current_stage = ?, last_active = ?, no_worktree = ?, last_local_modified_ts = ? WHERE name = ?'
+      ).run(data.currentStage || '', now, noWorktree, now, cn);
 
       // 2. 获取 change_id
       const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
@@ -566,6 +852,8 @@ export class ProgressManager {
            VALUES (?, ?, 'pending')`
         ).run(changeId, stage);
       }
+      // 本地脏度（D-013 / task-04）：新建 change 视为有未同步数据
+      this._touchLocalModified(cwd, changeName, now);
     });
 
     // 不再需要写文件：read() 已改为 SQL
@@ -620,7 +908,7 @@ export class ProgressManager {
         db.transaction(() => {
           const sqlDb = db.getDb();
           const now = new Date().toISOString();
-          sqlDb.prepare(
+          const ins = sqlDb.prepare(
             `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active) VALUES (?, 'scan', 'active', ?, ?)`
           ).run(changeName, now, now);
           const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
@@ -630,6 +918,8 @@ export class ProgressManager {
               sqlDb.prepare(`INSERT OR IGNORE INTO stages (change_id, stage, status) VALUES (?, ?, 'pending')`).run(changeId, s);
             }
           }
+          // 只在真正创建 change 时标脏（D-013/task-04）；读路径（change 已存在）不标，避免 pull 误判本地有未同步改动
+          if (ins.changes > 0) this._touchLocalModified(cwd, changeName, now);
         });
         this.registerChange(cwd, changeName);
       }

package/src/quicklog.js

@@ -117,6 +117,36 @@ function sanitizeResult(resultText) {
   return String(resultText || '').trim()
 }
 
+// ── quick step3 --file-notes 旁路通道 ──
+// flag 在 command.js 解析（--file-notes），completeQuicklogEntry 在 quick 收尾时消费。
+// 不经 completeStep → handleQuickStageCompletion → completeQuicklogEntry 三层透传（会扩 3 处签名，
+// 且 quick 收尾路径是多 agent 并发改热点）；用 per-process setter，CLI 单进程生命周期内有效，
+// completeQuicklogEntry 读后即清。无 --file-notes 时为 '' → 回退 changedFiles 单行（向后兼容）。
+let _pendingFileNotes = ''
+export function setQuickFileNotes(raw) { _pendingFileNotes = raw == null ? '' : String(raw) }
+export function getQuickFileNotes() { return _pendingFileNotes }
+
+/**
+ * 解析 --file-notes 原文 → [{path, note}]。
+ * 格式：「path1::括注1 || path2::括注2」——`||` 分隔条目，`::` 分隔路径与括注（首个 `::` 为界，
+ * 括注内含 `::` 不误切）；路径反斜杠归一正斜杠（匹配 git 路径风格）。无 `::` 的段 → note=''。
+ * 空 / 全空段 → []（调用方回退 changedFiles 单行）。导出供测试 + 未来直接调用。
+ */
+export function parseFileNotes(raw) {
+  if (!raw) return []
+  return String(raw)
+    .split('||')
+    .map((seg) => {
+      const s = seg.trim()
+      if (!s) return null
+      const idx = s.indexOf('::')
+      const path = (idx === -1 ? s : s.slice(0, idx)).replace(/\\/g, '/').trim()
+      const note = idx === -1 ? '' : s.slice(idx + 2).trim()
+      return path ? { path, note } : null
+    })
+    .filter(Boolean)
+}
+
 // 结果块必填字段（quick step3 --done --output 的结构化结果模板，见 src/stages/quick.js）。
 // 4 个必填字段标签从 manifest 同源(stage-contract-spec.js quick.result-labels),prompt 事前契约与本校验单源。
 const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
@@ -284,7 +314,7 @@ function splitSingleLineFields(body) {
   return scanFields(body, findBoundaryLabel) ?? scanFields(body, (b, l, f) => b.indexOf(l, f))
 }
 
-function flipEntryInContent(content, qlId, result, changedFiles = []) {
+function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes = []) {
   const lines = content.split('\n')
   const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
   if (startIdx === -1) return null
@@ -303,11 +333,16 @@ function flipEntryInContent(content, qlId, result, changedFiles = []) {
   for (let i = startIdx + 1; i < endIdx; i++) {
     if (/^状态：进行中\r?$/.test(lines[i])) { lines[i] = '状态：已完成'; flipped = true }
     if (lines[i].startsWith('结果：')) hasResult = true
-    // 回填实际改动文件（调用方已用 isQuickMetadata 过滤 quick 自身元数据，只留业务文件）。
-    // 原地替换 lines[i]，不改数组长度 → 与下方状态/结果 splice 的索引完全解耦。
-    // changedFiles 空（brownfield 无 guard / 调用方未传）→ 不动文件行，保持「（见实际改动）」。
-    if (changedFiles.length > 0 && lines[i].startsWith('文件：')) {
-      lines[i] = `文件：${changedFiles.join(', ')}`
+    // 文件行落盘：--file-notes 优先（多行 bullet 带括注），否则回填审计到的实际改动文件单行，
+    // 都空则不动（保持「（见实际改动）」）。bullet 用「数组元素内嵌 \n」写——lines.join('\n') 展平为
+    // 多行，数组长度不变 → 与下方状态/结果 splice 的索引完全解耦（changedFiles 单行同理原地替换）。
+    if (lines[i].startsWith('文件：')) {
+      if (fileNotes.length > 0) {
+        const bullets = fileNotes.map((n) => `- ${n.path}${n.note ? `（${n.note}）` : ''}`)
+        lines[i] = `文件：\n${bullets.join('\n')}`
+      } else if (changedFiles.length > 0) {
+        lines[i] = `文件：${changedFiles.join(', ')}`
+      }
     }
   }
   if (!flipped && !lines.slice(startIdx, endIdx).some(l => /^状态：已完成\r?$/.test(l))) {
@@ -405,6 +440,10 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
   const linked = Array.isArray(linkedChanges) ? linkedChanges : []
   // 实际改动文件（调用方 complete-handlers 已用 isQuickMetadata 过滤 quick 自身元数据）。空 → 不动文件行。
   const realFiles = Array.isArray(changedFiles) ? changedFiles.filter(Boolean) : []
+  // --file-notes（command.js 经 setQuickFileNotes 注入）：有则文件行写多行 bullet 带括注。
+  // 读后即清（per-process，防残留跨调用）。flipEntryInContent 优先用 fileNotes，空则回退 realFiles。
+  const fileNotes = parseFileNotes(_pendingFileNotes)
+  _pendingFileNotes = ''
 
   await withFileLock(lockPath, async () => {
     // 条目可能在主文件或轮转归档中
@@ -412,7 +451,7 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
       const filePath = join(quicklogDir, f)
       let content = ''
       try { content = readFileSync(filePath, 'utf8') } catch { continue }
-      const updated = flipEntryInContent(content, qlId, result, realFiles)
+      const updated = flipEntryInContent(content, qlId, result, realFiles, fileNotes)
       if (updated !== null) {
         await writeAtomic(filePath, updated) // 命中处原子落盘（只改含目标条目的那一个文件）
         break

package/src/run/command.js

@@ -32,6 +32,7 @@ import { ProgressManager } from '../progress.js'
 import { validateChangeExists } from '../stage-contract.js'
 import { stageRegistry, auxiliaryStages } from '../stages/index.js'
 import { definition as brainstormAutoDef } from '../stages/brainstorm-auto.js'
+import { setQuickFileNotes } from '../quicklog.js'
 
 // F2/F4: 哪些 flag 吃下一个 token 作「值」（其余 --flag 都是布尔，不吞值）。
 // 校验循环只对 VALUE_FLAGS 跳下一个 token（否则 --done 后跟 typo 会被当 --done 的值吞掉）。
@@ -40,7 +41,7 @@ const VALUE_FLAGS = new Set([
   '--reason', '--options', '--answer', '--confirm-mode',
   '--output', '--input', '--change', '--linked-changes',
   '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
-  '--files', '--from-step', '--mode', '--dir', '--confirm-mode',
+  '--files', '--file-notes', '--from-step', '--mode', '--dir', '--confirm-mode',
 ])
 
 /**
@@ -449,6 +450,16 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     quickFiles = flags[filesIdx + 1].split(',').map(f => f.trim()).filter(Boolean)
   }
 
+  // 解析 --file-notes "path::括注 || path::括注"（quick 专用：QUICKLOG「文件：」行落盘多行括注）。
+  // 旁路注入 quicklog.js（per-process setter），不经 complete 收尾路径透传（避碰多 agent 并发改的收尾热点）。
+  // completeQuicklogEntry 读后即清；不传 → '' → 回填审计到的实际文件单行（向后兼容）。
+  let quickFileNotes = ''
+  const fileNotesIdx = flags.indexOf('--file-notes')
+  if (fileNotesIdx !== -1 && flags[fileNotesIdx + 1]) {
+    quickFileNotes = flags[fileNotesIdx + 1]
+  }
+  setQuickFileNotes(quickFileNotes)
+
   const isAllowNew = flags.includes('--allow-new')
   const isForceBaseline = flags.includes('--force-baseline')
   const isForceRescan = flags.includes('--force-rescan')
@@ -460,7 +471,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--reason', '--options', '--answer', '--confirm-mode',
     '--output', '--input', '--change', '--linked-changes',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
-    '--files', '--allow-new', '--force-baseline', '--force-rescan',
+    '--files', '--file-notes', '--allow-new', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
     '--reopen', '--from-step', '--mode',
     '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）