sillyspec 3.29.4 → 3.31.0

package/src/preview-progress.js

@@ -0,0 +1,160 @@
+/**
+ * preview-progress.js — watcher 预览进度账本写路径（2026-09-23-watcher-preview-progress task-02）。
+ *
+ * 职责：把 watcher 快照的阶段级推断态投影为 progress 库 stages 预览行（authority='watcher'）。
+ * 设计契约（decisions D-004/D-005，design §3）：
+ *   - 粒度=阶段级（工件签名→progress 阶段映射；steps 级不投影，D-004）；
+ *   - 写纪律=短连接（open→写→close）+ 自带 PRAGMA busy_timeout（连接级，openDatabase 不自动——
+ *     影子审查 gap①）+ 存在性条件进 SQL + maxRows 写放大护栏 + 全程 fail-open（任何异常返回 false，
+ *     绝不影响 watcher 事件流主循环）。WHERE 认领语义（D-005@v2 执行期修正：initChange 预建
+ *     全套 cli/pending 行，纯 authority='watcher' 条件永远空转）：watcher 行可自刷；**CLI 从未
+ *     触碰的 pending 行（status='pending' 且 started_at IS NULL）可被预览认领**（flip 为 watcher，
+ *     语义无损——pending 空行不含 CLI 任何 authored 信息）；CLI 已触碰行（started/completed/
+ *     reopened）SQL 层不可中招；CLI --done 归章（task-01 fail① 修复）把认领行收回 cli。
+ *   - archived 拍不投影（终态只认 CLI）。
+ * 读侧出口在 progress.js readPreviewProgress（task-03）；读侧保险丝在 progress.js 读方法（task-01）。
+ */
+import { join } from 'node:path'
+import { openDatabase } from './db-engine.js'
+
+/** 工件签名 → progress 阶段映射（纯静态；watcher 快照 files 的键为工件基名）。 */
+export const PREVIEW_STAGE_SOURCES = {
+  brainstorm: ['proposal.md', 'requirements.md', 'decisions.md', 'design.md'],
+  plan: ['plan.md'],
+  execute: ['tasks.md'],
+  verify: ['verify-result.md', 'verify-facts.json'],
+}
+
+/**
+ * 纯函数：快照差分 → 阶段级预览行集合。
+ * @param {{ ts:number, archived:boolean, files?:Object }} snapshot 当前拍
+ * @param {{ files?:Object }=} prevSnapshot 上一拍（缺省全量视角）
+ * @returns {{ stage:string, status:'in-progress', startedAt:string, evidence:Object }[]}
+ *   evidence = { ts, files: 命中的工件清单, changed: 本拍有无内容变化（差分信号） }
+ */
+export function projectPreviewStages({ snapshot, prevSnapshot = null } = {}) {
+  if (!snapshot || snapshot.archived) return []
+  const files = snapshot.files || {}
+  const prevFiles = (prevSnapshot && prevSnapshot.files) || {}
+  const rows = []
+  for (const [stage, sources] of Object.entries(PREVIEW_STAGE_SOURCES)) {
+    const hit = sources.filter((k) => Object.prototype.hasOwnProperty.call(files, k))
+    if (hit.length === 0) continue
+    const changed = hit.some((k) => {
+      const a = files[k]; const b = prevFiles[k]
+      if (b === undefined) return true // 出现
+      return JSON.stringify(a) !== JSON.stringify(b) // 内容变化（checked 增/键值漂移）
+    })
+    rows.push({
+      stage,
+      status: 'in-progress',
+      startedAt: new Date(snapshot.ts || Date.now()).toISOString(),
+      evidence: { ts: snapshot.ts || null, files: hit, changed },
+    })
+  }
+  return rows
+}
+
+/**
+ * 短连接写入预览行（best-effort，全程 fail-open）。
+ * @returns {boolean} true=至少尝试写入（库在/变更注册）；false=跳过（库缺失/变更未注册/异常）
+ */
+export function writePreviewStages({ specDir, changeName, rows, maxRows = 8 } = {}) {
+  if (!specDir || !changeName || !Array.isArray(rows) || rows.length === 0) return false
+  let db = null
+  try {
+    db = openDatabase(join(specDir, '.runtime', 'sillyspec.db'), {})
+    // 连接级 PRAGMA（影子审查 gap①）：openDatabase 不自动带，缺省 0 = 撞锁立即 BUSY
+    db.exec('PRAGMA busy_timeout = 5000')
+    const changeRow = db.prepare('SELECT id FROM changes WHERE name = ?').get(changeName)
+    if (!changeRow) return false // 变更未注册（未跑过任何阶段）——无从挂预览，安静跳过
+    const cid = changeRow.id
+    const stmt = db.prepare(
+      `INSERT INTO stages (change_id, stage, status, started_at, authority, preview_evidence)
+       VALUES (?, ?, ?, ?, 'watcher', ?)
+       ON CONFLICT(change_id, stage) DO UPDATE SET
+         status = excluded.status,
+         started_at = COALESCE(stages.started_at, excluded.started_at),
+         preview_evidence = excluded.preview_evidence,
+         authority = 'watcher'
+       WHERE stages.authority = 'watcher'
+          OR (stages.authority = 'cli' AND stages.status = 'pending' AND stages.started_at IS NULL)`
+    )
+    for (const r of rows.slice(0, maxRows)) {
+      stmt.run(cid, r.stage, r.status, r.startedAt, JSON.stringify(r.evidence || {}))
+    }
+    return true
+  } catch {
+    return false // fail-open：锁竞争/库损坏/迁移未达——事件流不受影响，下轮重投影
+  } finally {
+    if (db) { try { db.close() } catch { /* 关闭失败不放大 */ } }
+  }
+}
+
+/** 步骤级工件映射：变更工件基名 → (阶段, 步骤名) 的对应——watcher 步骤节拍的数据源。 */
+export const PREVIEW_STEP_SOURCES = {
+  'proposal.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'requirements.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'design.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'decisions.md': { stage: 'brainstorm', step: '写设计文档并自审' },
+  'plan.md': { stage: 'plan', step: '生成分级计划' },
+  'verify-result.md': { stage: 'verify', step: '输出验证报告' },
+  'verify-facts.json': { stage: 'verify', step: '输出验证报告' },
+  'module-impact.md': { stage: 'archive', step: 'extract-module-impact 与归档语义收尾' },
+}
+
+/**
+ * 纯函数：快照差分 → 步骤级预览行集合（预览账本 v2，D-004 兑现）。
+ * 粒度=工件信号可映射的步骤（tasks.md 勾选→execute 逐任务步不可靠映射，不做——纯思考
+ * 型步骤由 --done 批量自述，burst 已支持）。返回行带 stage+step 双键。
+ */
+export function projectPreviewSteps({ snapshot, prevSnapshot = null } = {}) {
+  if (!snapshot || snapshot.archived) return []
+  const files = snapshot.files || {}
+  const prevFiles = (prevSnapshot && prevSnapshot.files) || {}
+  const rows = []
+  for (const [fname, target] of Object.entries(PREVIEW_STEP_SOURCES)) {
+    if (!Object.prototype.hasOwnProperty.call(files, fname)) continue
+    const changed = prevFiles[fname] === undefined || JSON.stringify(files[fname]) !== JSON.stringify(prevFiles[fname])
+    rows.push({
+      stage: target.stage,
+      step: target.step,
+      status: 'in-progress',
+      startedAt: new Date(snapshot.ts || Date.now()).toISOString(),
+      evidence: { ts: snapshot.ts || null, file: fname, changed },
+    })
+  }
+  return rows
+}
+
+/**
+ * 写步骤级预览行（短连接，fail-open）：steps 表 authority='watcher'，仅当该步骤
+ * 不存在或也是 watcher 行时写入（CLI 步骤行不可中招）。
+ */
+export function writePreviewSteps({ specDir, changeName, rows, maxRows = 12 } = {}) {
+  if (!specDir || !changeName || !Array.isArray(rows) || rows.length === 0) return false
+  let db = null
+  try {
+    db = openDatabase(join(specDir, '.runtime', 'sillyspec.db'), {})
+    db.exec('PRAGMA busy_timeout = 5000')
+    const changeRow = db.prepare('SELECT id FROM changes WHERE name = ?').get(changeName)
+    if (!changeRow) return false
+    const cid = changeRow.id
+    const stageStmt = db.prepare("SELECT id FROM stages WHERE change_id = ? AND stage = ? AND (authority = 'watcher' OR authority = 'cli' OR authority IS NULL)")
+    const insStmt = db.prepare(
+      `INSERT INTO steps (stage_id, name, status, completed_at, ordering, authority, preview_evidence)
+       VALUES (?, ?, 'in-progress', NULL, 0, 'watcher', ?)
+       ON CONFLICT DO NOTHING`
+    )
+    for (const r of rows.slice(0, maxRows)) {
+      const stageRow = stageStmt.get(cid, r.stage)
+      if (!stageRow) continue // 阶段行不在场——CLI 尚未进入该阶段，不预建
+      insStmt.run(stageRow.id, r.step, JSON.stringify(r.evidence || {}))
+    }
+    return true
+  } catch {
+    return false
+  } finally {
+    if (db) { try { db.close() } catch {} }
+  }
+}

package/src/progress/change-registry.js

@@ -613,9 +613,9 @@ export class ChangeRegistry {
         const row = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
         if (row) {
           sqlDb.prepare(
-            `INSERT INTO stages (change_id, stage, status, started_at, completed_at)
-             VALUES (?, 'archive', 'completed', ?, ?)
-             ON CONFLICT(change_id, stage) DO UPDATE SET status = 'completed', completed_at = excluded.completed_at`
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, authority)
+             VALUES (?, 'archive', 'completed', ?, ?, 'cli')
+             ON CONFLICT(change_id, stage) DO UPDATE SET status = 'completed', completed_at = excluded.completed_at, authority = 'cli'`
           ).run(row.id, now, now);
           const stageRow = sqlDb.prepare(
             'SELECT id FROM stages WHERE change_id = ? AND stage = ?'
@@ -638,6 +638,14 @@ export class ChangeRegistry {
           }
         }
       }
+      // 预览账本 GC（2026-09-23-watcher-preview-progress task-04 / FR-06）：归档收尾清 watcher
+      // 预览行（steps 随 stages 的 ON DELETE CASCADE 级联自动清）。fail-open：失败 warn 不阻断归档。
+      try {
+        const prow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
+        if (prow) sqlDb.prepare("DELETE FROM stages WHERE change_id = ? AND authority = 'watcher'").run(prow.id);
+      } catch (e) {
+        console.warn(`⚠️ 预览行 GC 失败（fail-open 不阻断归档）：${(e && e.message) || e}`);
+      }
       // 本地脏度（D-013 / task-04）：归档也是本地状态推进
       this.pm._touchLocalModified(cwd, changeName, now);
     });

package/src/progress/shared.js

@@ -27,8 +27,9 @@ export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', '
 export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'archive'];
 
 // progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8；
-// v6 = changes 加 owner_session 所有权列，2026-09-14-change-ownership-guards D-005@v1）
-export const CURRENT_VERSION = 6;
+// v6 = changes 加 owner_session 所有权列，2026-09-14-change-ownership-guards D-005@v1；
+// v8 = 出生阶段 'scan'→'brainstorm' + 存量出生默认行迁移，2026-09-27-change-birth-stage-brainstorm）
+export const CURRENT_VERSION = 8;
 
 // 滞留提示阈值（天，2026-08-30 用户反馈②：7 个「代码全落地但流程没收口」的变更挂 38 天
 // 无人发现）：活跃变更 last_active 距今超该天数且流程未收口（archive 未完成）时，progress

package/src/progress.js

@@ -15,6 +15,7 @@ import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir, hostname } from 'os';
 import { writeAtomicSync } from './fs-atomic.js';
 import { DB } from './db.js';
+import { openDatabase } from './db-engine.js';
 import { checkExecuteCodeEvidence } from './stage-contract.js';
 import { ConsistencyDoctor } from './progress/consistency-doctor.js';
 import { ChangeRegistry } from './progress/change-registry.js';
@@ -270,6 +271,36 @@ const CHANGES_SUBDIR = 'changes';
 
 // ── ProgressManager ──
 
+/**
+ * 预览进度读出口（2026-09-23-watcher-preview-progress task-03 / FR-04）：
+ * 读 watcher 预览行（authority='watcher'，读侧保险丝之外的显式出口）+ evidence 解析。
+ * 纯只读短连接；库缺失/变更未注册/异常 → { exists:false, stages:[] }（fail-open）。
+ */
+export function readPreviewProgress(specDir, changeName) {
+  if (!specDir || !changeName) return { exists: false, stages: [] }
+  let db = null
+  try {
+    db = openDatabase(join(specDir, '.runtime', 'sillyspec.db'), { readOnly: true })
+    const changeRow = db.prepare('SELECT id FROM changes WHERE name = ?').get(changeName)
+    if (!changeRow) return { exists: false, stages: [] }
+    const rows = db.prepare(
+      "SELECT stage, status, started_at, preview_evidence FROM stages WHERE change_id = ? AND authority = 'watcher' ORDER BY stage"
+    ).all(changeRow.id)
+    return {
+      exists: true,
+      stages: rows.map((r) => {
+        let evidence = null
+        try { evidence = r.preview_evidence ? JSON.parse(r.preview_evidence) : null } catch { evidence = null }
+        return { stage: r.stage, status: r.status, startedAt: r.started_at, evidence }
+      }),
+    }
+  } catch {
+    return { exists: false, stages: [] }
+  } finally {
+    if (db) { try { db.close() } catch { /* 只读关闭失败不放大 */ } }
+  }
+}
+
 export class ProgressManager {
   /** 模块级 DB 连接池：Map<dbPath, DB>（SEC-09/PERF-10，见 _ensureDB 注释） */
   static _dbPool = new Map();
@@ -401,7 +432,7 @@ export class ProgressManager {
     const { id: changeId, name: cName, current_stage: currentStage, no_worktree: noWorktree, last_active: lastActive } = changeRow;
 
     // 2. 从 stages 表获取所有阶段（含 revision 列）
-    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 stageRows = sqlDb.prepare(`SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason FROM stages WHERE change_id = ? AND (authority = 'cli' OR authority IS NULL) ORDER BY id`).all(changeId);
     const stageMap = {};
     const stageIds = [];
     for (const row of stageRows) {
@@ -420,7 +451,7 @@ export class ProgressManager {
     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`
+        `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}) AND (authority = 'cli' OR authority IS NULL) ORDER BY stage_id, ordering`
       ).all(...stageIds);
       // 按阶段分组步骤
       for (const row of stepRows) {
@@ -490,7 +521,9 @@ export class ProgressManager {
     }
 
     const result = {
-      _version: 6,
+      // 版本单一源（2026-09-27-change-birth-stage-brainstorm 收敛）：此前是字面量 6，
+      // v7 bump（watcher-preview-progress）漏改此处成「四处一致」之外的第五处漂移。
+      _version: CURRENT_VERSION,
       project: projectName,
       currentChange: cName,
       currentStage: currentStage || '',
@@ -572,7 +605,14 @@ export class ProgressManager {
 
     // 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
+      // 权威视图渲染（D-007 钉，2026-09-23-watcher-preview-progress task-05）：被 watcher 认领的行
+      // 在平台载荷里按其 CLI 已知态（pending/未起止）投影——载荷与无预览的干净态逐字节一致，
+      // 不因预览认领缺行（隔离钉 T1 实证：纯过滤会整行剔除该阶段）。
+      `SELECT id, stage,
+         CASE WHEN authority = 'watcher' THEN 'pending' ELSE status END AS status,
+         CASE WHEN authority = 'watcher' THEN NULL ELSE started_at END AS started_at,
+         CASE WHEN authority = 'watcher' THEN NULL ELSE completed_at END AS 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 => ({
@@ -596,7 +636,7 @@ export class ProgressManager {
       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`
+         FROM steps WHERE stage_id IN (${placeholders}) AND (authority = 'cli' OR authority IS NULL) ORDER BY stage_id, ordering`
       ).all(...stageIds);
       stepJson = stepRows.map(r => ({
         change_name: changeRow.name,
@@ -921,8 +961,8 @@ export class ProgressManager {
         for (const [stageName, stageData] of Object.entries(data.stages)) {
           // UPSERT stages 行（含 revision 列）
           sqlDb.prepare(
-            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason, authority)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'cli')
              ON CONFLICT(change_id, stage) DO UPDATE SET
                status = excluded.status,
                started_at = excluded.started_at,
@@ -930,7 +970,8 @@ export class ProgressManager {
                revision = COALESCE(excluded.revision, stages.revision),
                reopened_from_step = excluded.reopened_from_step,
                reopened_at = excluded.reopened_at,
-               stale_reason = excluded.stale_reason`
+               stale_reason = excluded.stale_reason,
+               authority = 'cli'`
           ).run(changeId, stageName, stageData.status || 'pending', stageData.startedAt || null, stageData.completedAt || null,
              stageData.revision || 0, stageData.reopenedFromStep || null, stageData.reopenedAt || null, stageData.staleReason || null);
 
@@ -1125,10 +1166,12 @@ export class ProgressManager {
       // 检查变更是否已存在
       const existing = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
       if (existing === undefined) {
-        // 插入 changes 行
+        // 插入 changes 行。出生阶段=brainstorm（2026-09-27 用户裁定「起步就是头脑风暴」）：
+        // scan 是 auxiliary（shared.js AUXILIARY_STAGES 语义），从未是变更主流程起点；
+        // 旧默认 'scan' 让 thin/quick 等不进主流程的变更全生命周期显示「🔍 代码扫描」误导。
         sqlDb.prepare(
           `INSERT INTO changes (name, current_stage, status, created_at, last_active, title, quicklog_id)
-           VALUES (?, 'scan', 'active', ?, ?, ?, ?)`
+           VALUES (?, 'brainstorm', 'active', ?, ?, ?, ?)`
         ).run(changeName, now, now, meta.title || null, meta.quicklogId || null);
       }
 
@@ -1203,7 +1246,7 @@ export class ProgressManager {
           const sqlDb = db.getDb();
           const now = new Date().toISOString();
           const ins = sqlDb.prepare(
-            `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active) VALUES (?, 'scan', 'active', ?, ?)`
+            `INSERT OR IGNORE INTO changes (name, current_stage, status, created_at, last_active) VALUES (?, 'brainstorm', 'active', ?, ?)`
           ).run(changeName, now, now);
           const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(changeName);
           if (changeRow !== undefined) {
@@ -1468,7 +1511,7 @@ export class ProgressManager {
 
     // 3. stages
     const stageRows = sqlDb.prepare(
-      'SELECT id, stage, status, started_at, completed_at, revision FROM stages WHERE change_id = ? ORDER BY id'
+      `SELECT id, stage, status, started_at, completed_at, revision FROM stages WHERE change_id = ? AND (authority = 'cli' OR authority IS NULL) ORDER BY id`
     ).all(changeId);
 
     const stages = {};
@@ -1481,7 +1524,7 @@ export class ProgressManager {
     if (stageRows.length > 0) {
       const placeholders = stageRows.map(() => '?').join(', ');
       const allStepRows = sqlDb.prepare(
-        `SELECT stage_id, name, status, output, completed_at FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+        `SELECT stage_id, name, status, output, completed_at FROM steps WHERE stage_id IN (${placeholders}) AND (authority = 'cli' OR authority IS NULL) ORDER BY stage_id, ordering`
       ).all(...stageRows.map(r => r.id));
       for (const sr of allStepRows) {
         if (!stepsByStage.has(sr.stage_id)) stepsByStage.set(sr.stage_id, []);

package/src/quicklog.js

@@ -752,10 +752,12 @@ const GUARD_CLAIM_STALE_MS = 7 * 24 * 60 * 60 * 1000
  * 遍历 quick-sessions 目录，按同一僵尸窗口口径读各会话 guard.json（collectGuardReservedQuicklogIds
  * 与 collectActiveQuickGuardFiles 共用，活跃判定勿分叉）：guard.json 损坏/缺失 → guard=null 保留
  * 条目（消费方各自决定跳过或视为空声明）；startedAt 可解析且超 GUARD_CLAIM_STALE_MS → 僵尸剔除。
+ * 附 guardMtimeMs（guard.json 最后写时间——会话结构性更新【启动/--files 追加边界】都会重写该文件，
+ * 是比 startedAt 更新的活性信号；非周期心跳，长思考会话会漂老，消费方 TTL 须以此为前提选窗）。
  *
  * @param {string} dir quick-sessions 目录
  * @param {number} [nowMs] 当前时间戳（可注入，测试用）
- * @returns {Array<{sessionId: string, guard: object|null}>}
+ * @returns {Array<{sessionId: string, guard: object|null, guardMtimeMs: number|null}>}
  */
 function listQuickSessionGuards(dir, nowMs = Date.now()) {
   const out = []
@@ -765,12 +767,17 @@ function listQuickSessionGuards(dir, nowMs = Date.now()) {
   } catch { return out } // 目录不存在/不可读 → 无会话
   for (const sessionName of sessionDirs) {
     let guard = null
-    try { guard = JSON.parse(readFileSync(join(dir, sessionName, 'guard.json'), 'utf8')) } catch { guard = null } // 损坏/缺失 → null
+    let guardMtimeMs = null
+    const guardPath = join(dir, sessionName, 'guard.json')
+    try {
+      guard = JSON.parse(readFileSync(guardPath, 'utf8'))
+      guardMtimeMs = statSync(guardPath).mtimeMs
+    } catch { guard = null } // 损坏/缺失 → null（mtime 一并放弃）
     if (guard && guard.startedAt) {
       const startedAtMs = Date.parse(guard.startedAt)
       if (Number.isFinite(startedAtMs) && nowMs - startedAtMs > GUARD_CLAIM_STALE_MS) continue // 僵尸不活跃
     }
-    out.push({ sessionId: sessionName, guard })
+    out.push({ sessionId: sessionName, guard, guardMtimeMs })
   }
   return out
 }
@@ -795,30 +802,61 @@ export function collectGuardReservedQuicklogIds(specBase, sessionsDirHint = null
  * （quick --done 完成时清理 guard 目录，完成态天然退出），超 7 天僵尸窗口（GUARD_CLAIM_STALE_MS，
  * 异常残留不钉死）剔除。勿用 changes.last_active 判活跃（非周期心跳，D-002）。
  *
+ * **拦截面 TTL（ql-20260921-009 ①，2026-09-21 batch2 归档实证）**：在僵尸窗口之上，本函数（apply
+ * 拦截面专用消费口）再按 guard.json **mtime** 收紧——超过 staleAfterMs（缺省 4h）无结构性更新的
+ * 会话视为放弃，声明不再参与相交拦截。实证形态：quick 会话中断未 --done、guard 目录残留 36h，
+ * apply 被幽灵守卫拦住，人工查证 owner.json 才敢解锁。安全性：守卫只是预警层，apply 的内容级
+ * 脏文件三方合并检查（EXCLUDE-DIRTY）仍兜底真实冲突；4h 窗口对 quick（短命流程）足够宽，
+ * 超窗未动 CLI 的会话即使活着，其声明文件若真有未提交改动也走内容级检查。quicklog ID 预留
+ * （collectGuardReservedQuicklogIds）**不套用**此 TTL——ID 复用避开近期死会话仍取 7 天窗。
+ * 过期跳过时打一行 ℹ️（可观测，不静默）；staleAfterMs=null 关闭（测试/回退口径）。
+ *
  * @param {string} specBase .sillyspec 根目录
- * @param {{ excludeChange?: string|null, sessionsDir?: string|null, nowMs?: number }} [opts]
+ * @param {{ excludeChange?: string|null, sessionsDir?: string|null, nowMs?: number, staleAfterMs?: number|null }} [opts]
  *   - excludeChange：排除自身 change 的 quick 会话——sessionId == changeName（quick 会话 id 即
  *     change 名）或 guard.linkedChanges 显式关联该 change 的协作会话（自己人，非拦截面）
  *   - sessionsDir：quick-sessions 目录（缺省 <specBase>/.runtime/quick-sessions）
  *   - nowMs：当前时间戳（可注入，测试用）
+ *   - staleAfterMs：拦截面 TTL 毫秒数（缺省 GUARD_INTERCEPT_STALE_MS=4h；null 关闭）
  * @returns {Map<string, string[]>} sessionId → guard.allowedFiles（无 guard/无声明 → 空数组；fail-open）
  */
-export function collectActiveQuickGuardFiles(specBase, { excludeChange = null, sessionsDir = null, nowMs = Date.now() } = {}) {
+const GUARD_INTERCEPT_STALE_MS = 4 * 60 * 60 * 1000
+export function collectActiveQuickGuardFiles(specBase, { excludeChange = null, sessionsDir = null, nowMs = Date.now(), staleAfterMs = GUARD_INTERCEPT_STALE_MS } = {}) {
   const out = new Map()
+  let staleSkipped = 0
   try {
     const dir = sessionsDir || join(specBase, '.runtime', 'quick-sessions')
-    for (const { sessionId, guard } of listQuickSessionGuards(dir, nowMs)) {
+    for (const { sessionId, guard, guardMtimeMs } of listQuickSessionGuards(dir, nowMs)) {
       if (excludeChange && (sessionId === excludeChange
         || (guard && Array.isArray(guard.linkedChanges) && guard.linkedChanges.includes(excludeChange)))) continue
+      if (staleAfterMs != null && guardMtimeMs != null && Number.isFinite(guardMtimeMs)
+        && nowMs - guardMtimeMs > staleAfterMs) { staleSkipped++; continue } // TTL 过期：拦截面视为放弃
       const allowed = (guard && Array.isArray(guard.allowedFiles))
         ? guard.allowedFiles.filter(f => typeof f === 'string' && f.length > 0)
         : []
       out.set(sessionId, allowed)
     }
   } catch { /* fail-open：采集失败等同无活跃 guard（不放大拦截面） */ }
+  if (staleSkipped > 0) {
+    console.log(`ℹ️ 已忽略 ${staleSkipped} 个过期 quick 守卫（>${Math.round(staleAfterMs / 3600000)}h 无活动，TTL 自动失效）——内容级脏文件合并检查仍兜底真实冲突`)
+  }
   return out
 }
 
+/**
+ * quick 启动并发错峰建议探测（ql-20260921-009 ③，2026-09-21 batch2 归档实证）。纯读：
+ * 他者活跃 quick 守卫（TTL 过滤后）≥1 且主仓已有 src/test 脏文件 → suggest=true——两者
+ * 同时在场时工作区互写/apply 相交拦截摩擦集中爆发。单会话常态 suggest=false 零输出。
+ * @returns {{ suggest: boolean, others: string[] }}
+ */
+export function detectQuickConcurrencyAdvice({ specBase, changeName, baselineFiles, sessionsDir = null, nowMs = Date.now() } = {}) {
+  const others = collectActiveQuickGuardFiles(specBase, { excludeChange: changeName, sessionsDir, nowMs })
+  const srcTestDirty = Array.isArray(baselineFiles) && baselineFiles.some(
+    (p) => { const n = String(p).split('\\').join('/'); return n.startsWith('src/') || n.startsWith('test/') }
+  )
+  return { suggest: others.size > 0 && !!srcTestDirty, others: [...others.keys()] }
+}
+
 /**
  * 数某 qlId 在所有 QUICKLOG-*.md 里的条目头出现次数（--done 占用校验用）。
  * ≥2 = 分配竞态残留已损坏记录（同 ID 双条目）；容错空白形态与 scanExisting 的 reLoose 同口径。

package/src/redomain.js

@@ -0,0 +1,147 @@
+/**
+ * redomain.js — FR 条目跨域迁移（2026-09-27-redomain，三层治理 v2 ③）
+ *
+ * 伪域信号卡指出迁移建议（suggestDomainFromFiles），本模块给机器通道：
+ * 把 fr/<from>.md 的条目段切出、拼进 fr/<to>.md（缺席则按 loadDomainSections
+ * 同款头新建），目标域无 INDEX 路由行则补（syncIndexRoutingLines 单源）。
+ *
+ * 身份铁律（D-001 单一身份同源）：迁域**不换号**——条目 ID（FR-<旧域>-NNN）
+ * 保持原样，绑定行/supersede 链/最近确认锚全靠 ID 寻址（upsertFrBindings 按
+ * `## ${frId}` 全目录扫描定位，与所在文件无关）；前缀与域不符属历史痕迹。
+ *
+ * 空壳防线：全域迁移后源文件剩 0 条目则删除（防留空壳域文件污染域列表）。
+ * 纯文件手术——不动条目内容、不动绑定块（随条目段整体搬）。
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { splitKnowledgeSections, joinKnowledgeFile, syncIndexRoutingLines } from './decision-distill.js'
+import { FR_SECTION_RE } from './fr-index.js'
+import { writeAtomicSync } from './fs-atomic.js'
+
+/** 条目段头（## FR-xxx-NNN / ## FR-NNN）判定与 ID 提取 */
+const FR_HEADER_RE = /^## (FR-[\w.-]+-\d+|FR-\d+)\s*(.*)$/
+
+function frEntryId(headerLine) {
+  const m = FR_HEADER_RE.exec(headerLine)
+  return m ? m[1] : null
+}
+
+/** 目标域文件头（与 fr-index loadDomainSections 新建头逐字同款） */
+function newDomainPreamble(domain) {
+  // 与 fr-index loadDomainSections 新建头逐字同款（评审 P2-2 清偿：含 superseded 回溯行
+  // 与 伪域/模块卡 条件行，勿再分叉）
+  return [
+    '---',
+    `author: sillyspec-fr-index`,
+    `created_at: ${new Date().toISOString()}`,
+    '---',
+    '',
+    `# FR 索引 — ${domain}`,
+    '',
+    '> fr-index 从归档变更 requirements.md 幂等提炼（「最近确认」= 归档时 HEAD）。条目字段行为机械解析契约，勿手改。',
+    '> superseded 条目保留供取代链回溯；brainstorm 注入默认只给 active。',
+    String(domain).startsWith('auto-')
+      ? '> 伪域（auto- 前缀）：由文件路径段投票派生，无模块卡——为该域补模块卡后，新变更将自动落回真域'
+      : `> 模块卡：modules/${domain}.md（域=模块 id 同构；行为条目↔模块契约互跳）`,
+    '',
+  ]
+}
+
+/**
+ * 执行迁移（纯函数式落盘）。
+ * @param {{knowledgeRoot: string, from: string, to: string, anchors?: string[]}} opts
+ * @returns {{moved: Array<{id,title}>, sourceDeleted: boolean, targetCreated: boolean, indexLineAdded: boolean}}
+ * @throws 源域缺席 / 无匹配条目 / anchor 未命中
+ */
+export function redomainFrEntries({ knowledgeRoot, from, to, anchors = null }) {
+  const frDir = join(knowledgeRoot, 'fr')
+  const fromPath = join(frDir, `${from}.md`)
+  const toPath = join(frDir, `${to}.md`)
+  if (!existsSync(fromPath)) throw new Error(`源域文件不存在：fr/${from}.md`)
+  if (from === to) throw new Error('源域与目标域相同')
+
+  const fromParsed = splitKnowledgeSections(readFileSync(fromPath, 'utf8'), { sectionRegex: FR_SECTION_RE, buildId: (n) => n })
+  const anchorSet = Array.isArray(anchors) && anchors.length > 0 ? new Set(anchors) : null
+
+  // 目标域既有内容（缺席=新建头）
+  const targetCreated = !existsSync(toPath)
+  const toParsed = targetCreated
+    ? { preamble: newDomainPreamble(to), sections: [] }
+    : splitKnowledgeSections(readFileSync(toPath, 'utf8'), { sectionRegex: FR_SECTION_RE, buildId: (n) => n })
+
+  const moving = []
+  const staying = []
+  for (const s of fromParsed.sections) {
+    const id = frEntryId(s.lines[0] || '')
+    if (!id) { staying.push(s); continue } // 非条目段（说明/杂项）留守
+    if (anchorSet && !anchorSet.has(id)) { staying.push(s); continue }
+    moving.push({ id, title: (FR_HEADER_RE.exec(s.lines[0])?.[2] || '').trim(), section: s })
+  }
+  if (moving.length === 0) {
+    throw new Error(anchorSet ? `anchor 未命中（${[...anchorSet].join('、')} 不在 fr/${from}.md）` : `fr/${from}.md 无 FR 条目段`)
+  }
+  if (anchorSet && moving.length !== anchorSet.size) {
+    const got = new Set(moving.map((m) => m.id))
+    const miss = [...anchorSet].filter((a) => !got.has(a))
+    throw new Error(`anchor 未命中：${miss.join('、')}（不在 fr/${from}.md）`)
+  }
+  // 目标域 ID 冲突防线（同 ID 已在目标域=迁移语义不明）
+  const toIds = new Set(toParsed.sections.map((s) => frEntryId(s.lines[0] || '')).filter(Boolean))
+  const clash = moving.filter((m) => toIds.has(m.id))
+  if (clash.length > 0) throw new Error(`目标域已有同 ID 条目（${clash.map((c) => c.id).join('、')}）——先解冲突再迁移`)
+
+  // 落盘：目标域追加；源域留余或删除空壳
+  toParsed.sections.push(...moving.map((m) => m.section))
+  writeAtomicSync(toPath, joinKnowledgeFile(toParsed.preamble, toParsed.sections))
+  const sourceDeleted = staying.length === 0
+  if (sourceDeleted) unlinkSync(fromPath)
+  else writeAtomicSync(fromPath, joinKnowledgeFile(fromParsed.preamble, staying))
+
+  // INDEX 路由行：syncIndexRoutingLines 扫全目录幂等同步（既有行 no-op、目标域缺席行补上）
+  const indexPath = join(knowledgeRoot, 'INDEX.md')
+  const before = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : ''
+  try {
+    syncIndexRoutingLines(knowledgeRoot, {
+      section: 'FR 需求索引',
+      subdir: 'fr',
+      makeLine: (d) => d.startsWith('auto-')
+        ? `- ${d}|${d.slice(5)}|FR|需求|承接 → [fr/${d}.md](fr/${d}.md)`
+        : `- ${d}|FR|需求|承接 → [fr/${d}.md](fr/${d}.md)`,
+    })
+  } catch { /* INDEX 缺席/同步失败不拦迁移（主手术已成） */ }
+  const after = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : ''
+
+  return {
+    moved: moving.map((m) => ({ id: m.id, title: m.title })),
+    sourceDeleted,
+    targetCreated,
+    indexLineAdded: after !== before,
+  }
+}
+
+/** 干跑预览：列出将迁移条目，不落盘 */
+export function planRedomain({ knowledgeRoot, from, to, anchors = null }) {
+  const frDir = join(knowledgeRoot, 'fr')
+  const fromPath = join(frDir, `${from}.md`)
+  if (!existsSync(fromPath)) throw new Error(`源域文件不存在：fr/${from}.md`)
+  if (from === to) throw new Error('源域与目标域相同')
+  const fromParsed = splitKnowledgeSections(readFileSync(fromPath, 'utf8'), { sectionRegex: FR_SECTION_RE, buildId: (n) => n })
+  const anchorSet = Array.isArray(anchors) && anchors.length > 0 ? new Set(anchors) : null
+  const candidates = []
+  for (const s of fromParsed.sections) {
+    const id = frEntryId(s.lines[0] || '')
+    if (!id) continue
+    if (anchorSet && !anchorSet.has(id)) continue
+    candidates.push({ id, title: (FR_HEADER_RE.exec(s.lines[0])?.[2] || '').trim() })
+  }
+  if (candidates.length === 0) {
+    throw new Error(anchorSet ? `anchor 未命中（${[...anchorSet].join('、')}）` : `fr/${from}.md 无 FR 条目段`)
+  }
+  return {
+    from,
+    to,
+    targetExists: existsSync(join(frDir, `${to}.md`)),
+    entries: candidates,
+    sourceWillDelete: candidates.length === fromParsed.sections.filter((s) => frEntryId(s.lines[0] || '')).length,
+  }
+}