sillyspec 3.25.11 → 3.26.1

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: 5,
       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);
@@ -490,6 +776,8 @@ export class ProgressManager {
 
   unregisterChange(cwd, changeName) { return this._changeRegistry.unregisterChange(cwd, changeName); }
 
+  updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
+
   // ── CLI 命令 ──
 
   init(cwd) {
@@ -529,7 +817,7 @@ export class ProgressManager {
    * 初始化指定变更的 progress
    * SQL: INSERT changes + 批量 INSERT stages
    */
-  initChange(cwd, changeName) {
+  initChange(cwd, changeName, meta = {}) {
     if (!changeName) {
       console.warn('⚠️  initChange: changeName 为空，跳过');
       return null;
@@ -550,9 +838,9 @@ export class ProgressManager {
       if (existing === undefined) {
         // 插入 changes 行
         sqlDb.prepare(
-          `INSERT INTO changes (name, current_stage, status, created_at, last_active)
-           VALUES (?, 'scan', 'active', ?, ?)`
-        ).run(changeName, now, now);
+          `INSERT INTO changes (name, current_stage, status, created_at, last_active, title, quicklog_id)
+           VALUES (?, 'scan', 'active', ?, ?, ?, ?)`
+        ).run(changeName, now, now, meta.title || null, meta.quicklogId || null);
       }
 
       // 获取 change_id
@@ -566,6 +854,8 @@ export class ProgressManager {
            VALUES (?, ?, 'pending')`
         ).run(changeId, stage);
       }
+      // 本地脏度（D-013 / task-04）：新建 change 视为有未同步数据
+      this._touchLocalModified(cwd, changeName, now);
     });
 
     // 不再需要写文件：read() 已改为 SQL
@@ -620,7 +910,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 +920,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

@@ -75,7 +75,7 @@ function nowDatetime(d = new Date()) {
 }
 
 // 描述压成一行、限长，避免破坏 QUICKLOG 条目结构
-function sanitizeDesc(description) {
+export function sanitizeDesc(description) {
   const s = String(description || '').replace(/[\r\n]+/g, ' ').trim()
   if (!s) return '(quick 任务)'
   return s.length > 120 ? s.slice(0, 120) + '…' : s
@@ -101,7 +101,7 @@ export function deriveTitleFromLinkedChange(specBase, change) {
 
 // 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
 // （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
-function extractTitleFromResult(result) {
+export function extractTitleFromResult(result) {
   if (!result) return ''
   const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
   if (!m) return ''
@@ -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 检测）

package/src/run/complete-handlers.js

@@ -25,12 +25,12 @@
 import { basename, join, resolve, relative, isAbsolute } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 
@@ -130,9 +130,32 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
 /**
  * 归档时清理可能残留的 worktree（execute 自动清理未走到 / 有未 apply 变更被遗弃）。
  * 安全策略：有未 apply 变更时保留 worktree 并警告，避免误删用户未应用的代码。
+ * 同时清理该变更的 execute / stage-review runId marker（只写不删的累积物，
+ * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）。
  * 从 archiveChangeDirectory 抽出，供正常归档 + 自愈归档复用。
  */
-async function archiveWorktreeCleanup(cwd, archiveChangeName) {
+async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
+  // ── 清理 runId marker：execute（current-execute-run-id-<change>）与 stage-review
+  //    （current-stage-review-run-id-<stage>-<change>）。marker 只服务 execute→verify→archive
+  //    期间，归档后无读者；不删则 .runtime 随变更数无限累积。runtimeRoot 解析同写入侧
+  //    （resolveRuntimeRoot 锚主仓），避免平台模式清理错位置。
+  try {
+    const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+    if (existsSync(runtimeRoot)) {
+      const markers = readdirSync(runtimeRoot).filter((f) =>
+        f === `current-execute-run-id-${archiveChangeName}` ||
+        (f.startsWith('current-stage-review-run-id-') && f.endsWith(`-${archiveChangeName}`)),
+      )
+      for (const m of markers) {
+        try { unlinkSync(join(runtimeRoot, m)) } catch {}
+      }
+      if (markers.length > 0) {
+        console.log(`🧹 归档清理 ${markers.length} 个 runId marker（execute/stage-review）`)
+      }
+    }
+  } catch (e) {
+    console.warn(`⚠️  归档 runId marker 清理失败（不阻断归档）: ${e.message}`)
+  }
   try {
     const { WorktreeManager } = await import('../worktree.js')
     const wm = new WorktreeManager({ cwd })
@@ -154,7 +177,7 @@ async function archiveWorktreeCleanup(cwd, archiveChangeName) {
   }
 }
 
-export async function archiveChangeDirectory(pm, cwd, progress, specBase) {
+export async function archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts = {}) {
   const archiveChangeName = progress.currentChange
   if (!archiveChangeName) {
     console.error('❌ 归档失败：未找到当前变更名（currentChange）')
@@ -176,7 +199,7 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase) {
     if (alreadyArchivedDir) {
       console.log(`ℹ️  源目录不存在但变更已在 archive/（${basename(alreadyArchivedDir)}），判定已归档，自愈进度 DB`)
       pm.unregisterChange(cwd, archiveChangeName)
-      await archiveWorktreeCleanup(cwd, archiveChangeName)
+      await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
       console.log(`📦 已自愈归档：${archiveChangeName} → archive/${basename(alreadyArchivedDir)}/`)
       return alreadyArchivedDir
     }
@@ -221,7 +244,7 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase) {
   } catch {}
 
   // 归档时清理可能残留的 worktree（自愈路径也复用，见上方 srcDir 缺失分支）。
-  await archiveWorktreeCleanup(cwd, archiveChangeName)
+  await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
 
   console.log(`📦 已归档：${archiveChangeName} → archive/${destName}/`)
   return destDir
@@ -236,7 +259,7 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase) {
  *
  * @returns {{stageCompleted:false,currentIdx,nextPendingIdx:number}|null}
  */
-export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase }) {
+export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts = {} }) {
   if (stageName !== 'archive' || steps[currentIdx]?.name !== '确认归档') return null
   if (!confirm) {
     steps[currentIdx].status = 'pending'
@@ -246,7 +269,7 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
-  const archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase)
+  const archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts)
   if (archivedDir && existsSync(archivedDir)) {
     const recommendedDocs = ['design.md', 'module-impact.md']
     const missingRecommended = recommendedDocs.filter(d => !existsSync(join(archivedDir, d)))
@@ -751,6 +774,12 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         changedFiles: realFiles,
       })
       console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      // 刷新 DB title：从 step3「需求：」提取（agent 可改 title 的途径），覆盖启动时的兜底快照。
+      // 与 QUICKLOG 标题刷新（flipEntryInContent 内 extractTitleFromResult）同源，保持 DB↔QUICKLOG 一致。
+      try {
+        const refinedTitle = extractTitleFromResult(outputText || '');
+        if (refinedTitle) pm.updateChangeMeta(cwd, changeName, { title: refinedTitle });
+      } catch { /* title 刷新失败不阻断完成 */ }
     } catch (e) {
       console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
     }