sillyspec 3.29.3 → 3.29.4

package/src/run/bg-sync.js

@@ -0,0 +1,231 @@
+/**
+ * spec-sync 后台异步执行（detached 子进程）。
+ *
+ * 背景（2026-09-20 用户反馈：末步 --done 因 spec-sync 网络同步约 4 分钟不返回）：
+ * triggerSync 的 17 个调用点全部 fire-and-forget，但 Node 进程退出要等事件循环排空——
+ * 在飞 fetch 拖住进程，CLI 输出打完后仍要等网络收尾才返回 shell（平台慢时分钟级体感
+ * hang；本机制落地当天的会话启动命令尾部 3 行 [spec-sync] 已同步 逐条等网络，现场即
+ * 实证）。8s 总熔断（raceWithAbort）只保证「最多等 8s」，治标；本模块治本：同步整体
+ * 挪进 detached 后台子进程，父进程 spawn + unref 后立即返回，命令零网络尾巴。
+ *
+ * 架构（父侧/子侧同一模块，职责分开）：
+ * - 父侧 spawnBackgroundSync（shared.js triggerSync 唯一接入点调用）：
+ *   ① 未连接平台预判（sync.js peekPlatformConnected 同源判据）——未连接不 spawn，
+ *     本地独立用户零开销零行为变化；② 单飞锁判定：活锁 → rerunQueued 置位合并
+ *     （跑完当前轮再补一轮，防进程堆积），无锁/死锁 → spawn detached 子进程。
+ * - 子侧 runBgSyncFromEnv（node -e bootstrap 动态 import 本模块）：写锁 → 循环
+ *   〔清 rerunQueued → triggerSync inline 执行一轮 → 期间有新请求则再来一轮〕，
+ *   上限 5 轮 / 总预算 ~2.5min → 清锁退出。轮前清位 + 轮后查位：清位后本轮树 hash
+ *   晚于清位时刻，天然覆盖此后到达的状态；hash 之后到达的靠置位标记触发下一轮。
+ * - 子进程 stdout/stderr 接 <runtimeRoot>/spec-sync-bg.log（append，超 1MB 截尾保
+ *   后 512KB）：[spec-sync]/[sync] 的 warn/冲突横幅全量留痕，不进主命令输出也不再丢。
+ *
+ * 与既有机制的交互：
+ * - raceWithAbort / SILLYSPEC_SYNC_TIMEOUT_MS 不动——inline 路径原样。后台轮预算 =
+ *   max(resolveSyncTotalTimeoutMs(), 45s)：后台无人等待，放宽到 45s 提高「慢平台真的
+ *   同步成功」概率（2026-09-07 平台 >8s 响应间歇熔断的 pain 点在后台模式下自然消解）。
+ * - sync-noise.js 噪音闸 / spec-sync-conflict-*.json / 基线快照在子进程内照常工作
+ *   （同一 .runtime 目录，跨进程 marker 语义不变）。
+ * - 冲突可见性不降级：横幅进日志文件 + 冲突文件照落，下一条命令 progress show 照常
+ *   红标提示（resolve 三态处置入口不变）。
+ * - SILLYSPEC_SYNC_BG=0 逃生阀：triggerSync 回落 inline（测试断言进程内行为/用户自救）。
+ *
+ * 循环 import 说明：本模块与 shared.js 双向引用（shared 调本模块 spawnBackgroundSync、
+ * 本模块两侧调 shared 的 triggerSync/resolveRuntimeRoot/resolveSyncTotalTimeoutMs）。
+ * 对 shared 的引用一律走函数内动态 import，避免静态环（ESM 环可运行但初始化序脆弱，
+ * 刻意不赌）；父进程内 shared.js 已加载，动态 import 走缓存无额外成本。
+ */
+import { spawn } from 'child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export const BG_LOCK_FILENAME = 'spec-sync-bg.lock';
+export const BG_LOG_FILENAME = 'spec-sync-bg.log';
+
+// 后台轮参数：单轮预算下限（与 env SILLYSPEC_SYNC_TIMEOUT_MS 取 max）、轮数与总预算帽
+// （防慢平台下无限续轮）；锁时效（pid 活性之外的第二道判死——pid 复用假活兜底，
+// 子进程自身总预算 ~2.5min + 收尾余量远小于该值，超时必是异常残留）。
+const BG_ROUND_FLOOR_MS = 45_000;
+const BG_MAX_ROUNDS = 5;
+const BG_TOTAL_BUDGET_MS = 150_000;
+const LOCK_STALE_MS = 15 * 60 * 1000;
+const LOG_TRUNCATE_THRESHOLD = 1_000_000;
+const LOG_TRUNCATE_KEEP = 512 * 1024;
+
+/** pid 活性探测（跨平台）：signal 0 探测；EPERM = 进程存在但属他户，保守按活。 */
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e && e.code === 'EPERM';
+  }
+}
+
+/** 读后台单飞锁（缺失/损坏 → null）。 */
+export function readBgSyncLock(runtimeRoot) {
+  try {
+    const raw = readFileSync(join(runtimeRoot, BG_LOCK_FILENAME), 'utf8');
+    const obj = JSON.parse(raw);
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeBgSyncLock(runtimeRoot, lock) {
+  mkdirSync(runtimeRoot, { recursive: true });
+  const tmp = join(runtimeRoot, `${BG_LOCK_FILENAME}.${process.pid}.tmp`);
+  writeFileSync(tmp, JSON.stringify(lock) + '\n', 'utf8');
+  renameSync(tmp, join(runtimeRoot, BG_LOCK_FILENAME));
+}
+
+function removeBgSyncLock(runtimeRoot) {
+  try {
+    const p = join(runtimeRoot, BG_LOCK_FILENAME);
+    if (existsSync(p)) unlinkSync(p);
+  } catch { /* 清锁失败：残留锁按时效/pid 判死后自动接管，不影响正确性 */ }
+}
+
+/**
+ * 锁活性判定（pid 活 + 未超时）。纯函数（pid 探测单列 isPidAlive 便于注入测试）。
+ * @param {object|null} lock readBgSyncLock 产物
+ * @param {number} [now] 注入时钟（测试用）
+ */
+export function isBgSyncLockLive(lock, now = Date.now()) {
+  if (!lock || !Number.isInteger(lock.pid) || lock.pid <= 0) return false;
+  if (typeof lock.startedAt !== 'number') return false;
+  if (now - lock.startedAt > LOCK_STALE_MS) return false;
+  return isPidAlive(lock.pid);
+}
+
+/** 子进程起步截尾日志（>1MB 保后 512KB，从整行边界起）。失败只影响日志体积。 */
+function truncateLogIfNeeded(runtimeRoot) {
+  try {
+    const p = join(runtimeRoot, BG_LOG_FILENAME);
+    if (statSync(p).size <= LOG_TRUNCATE_THRESHOLD) return;
+    const buf = readFileSync(p);
+    const keep = buf.subarray(Math.max(0, buf.length - LOG_TRUNCATE_KEEP));
+    const nl = keep.indexOf(10);
+    writeFileSync(p, nl >= 0 ? keep.subarray(nl + 1) : keep);
+  } catch { /* 截断失败：继续 append */ }
+}
+
+/** 子进程 bootstrap：node -e 动态 import 本模块（file URL 精确定位，不依赖 CLI 安装形态）。 */
+function buildChildBootstrap() {
+  const selfUrl = new URL('./bg-sync.js', import.meta.url).href;
+  return `import(${JSON.stringify(selfUrl)}).then(m=>m.runBgSyncFromEnv()).catch(e=>{console.error('[spec-sync-bg] 后台同步进程异常退出:',(e&&e.message)||e)});`;
+}
+
+/**
+ * 父侧后台同步入口（triggerSync 调用，不直接被业务代码使用）。
+ *
+ * @returns {Promise<{status:'spawned'|'coalesced'|'not-connected', logPath?:string}>}
+ *   spawned=已起后台子进程；coalesced=活锁在跑、本轮状态已并入其下一轮（rerunQueued）；
+ *   not-connected=未连接平台（调用方回落 inline 路径=与旧行为一致的静默 no-op）。
+ *   spawn 失败抛异常（调用方 catch 降级 inline，绝不因后台化阻断主流程）。
+ */
+export async function spawnBackgroundSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  const syncMod = await import('../sync.js');
+  if (!syncMod.peekPlatformConnected(cwd)) return { status: 'not-connected' };
+
+  const { resolveRuntimeRoot } = await import('./shared.js');
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, platformOpts?.specRoot || join(cwd, '.sillyspec'));
+
+  const lock = readBgSyncLock(runtimeRoot);
+  if (isBgSyncLockLive(lock)) {
+    // 单飞合并：活后台轮在跑，把「还有新状态要同步」并入其下一轮。置位失败（并发写锁）
+    // 只损失合并信号——后台轮收尾锁自清，下一条命令重新 spawn，收敛不丢。
+    try { writeBgSyncLock(runtimeRoot, { ...lock, rerunQueued: true }); } catch { /* 见上 */ }
+    return { status: 'coalesced', logPath: join(runtimeRoot, BG_LOG_FILENAME) };
+  }
+
+  // 日志 fd：子进程 stdout/stderr 直接 append 进日志文件（跨平台 fd 继承）；开不了退 ignore
+  const logPath = join(runtimeRoot, BG_LOG_FILENAME);
+  let stdio = ['ignore', 'ignore', 'ignore'];
+  let logFd = null;
+  try {
+    mkdirSync(runtimeRoot, { recursive: true });
+    logFd = openSync(logPath, 'a');
+    stdio = ['ignore', logFd, logFd];
+  } catch {
+    logFd = null;
+  }
+
+  const env = {
+    ...process.env,
+    SILLYSPEC_BG_SYNC_CHANGE: String(changeName),
+    SILLYSPEC_BG_SYNC_CWD: String(cwd),
+  };
+  if (platformOpts?.specRoot) env.SILLYSPEC_BG_SYNC_SPEC_ROOT = String(platformOpts.specRoot);
+  if (platformOpts?.runtimeRoot) env.SILLYSPEC_BG_SYNC_RUNTIME_ROOT = String(platformOpts.runtimeRoot);
+
+  try {
+    const child = (opts.spawnImpl || spawn)(process.execPath, ['-e', buildChildBootstrap()], {
+      cwd,
+      detached: true,
+      stdio,
+      windowsHide: true,
+      env,
+    });
+    child.unref?.();
+  } finally {
+    if (logFd !== null) {
+      try { closeSync(logFd); } catch { /* 父侧 fd 副本关闭；子进程持有继承副本 */ }
+    }
+  }
+  return { status: 'spawned', logPath };
+}
+
+/**
+ * 子侧入口（bootstrap 经 env 传参调起；env 注入默认值供测试覆盖）。
+ *
+ * 单飞循环：写锁（本 pid）→ 每轮清 rerunQueued 后 inline 跑一轮 triggerSync →
+ * 轮末查位，被置位且预算未尽则续轮（迟到状态收敛），否则清锁退出。
+ * 锁 pid 非本进程（双 spawn 竞态窗口被后写者接管）→ 让位退出防双跑。
+ */
+export async function runBgSyncFromEnv(env = process.env) {
+  const changeName = env.SILLYSPEC_BG_SYNC_CHANGE;
+  const cwd = env.SILLYSPEC_BG_SYNC_CWD;
+  if (!changeName || !cwd) return;
+
+  const platformOpts = {};
+  if (env.SILLYSPEC_BG_SYNC_SPEC_ROOT) platformOpts.specRoot = env.SILLYSPEC_BG_SYNC_SPEC_ROOT;
+  if (env.SILLYSPEC_BG_SYNC_RUNTIME_ROOT) platformOpts.runtimeRoot = env.SILLYSPEC_BG_SYNC_RUNTIME_ROOT;
+
+  const { triggerSync, resolveRuntimeRoot, resolveSyncTotalTimeoutMs } = await import('./shared.js');
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, platformOpts.specRoot || join(cwd, '.sillyspec'));
+  truncateLogIfNeeded(runtimeRoot);
+  const startedAt = Date.now();
+  writeBgSyncLock(runtimeRoot, { pid: process.pid, startedAt, change: changeName, rerunQueued: false });
+
+  const roundTimeoutMs = Math.max(resolveSyncTotalTimeoutMs(), BG_ROUND_FLOOR_MS);
+  const deadline = startedAt + BG_TOTAL_BUDGET_MS;
+  for (let round = 1; round <= BG_MAX_ROUNDS; round++) {
+    // 轮前清位：本轮 triggerSync 的树 hash 晚于清位时刻，覆盖此后到达的全部状态；
+    // 读→写间隙内的置位存在丢失窗口（毫秒级），由下一条命令的同步兜底收敛。
+    const cur = readBgSyncLock(runtimeRoot);
+    writeBgSyncLock(runtimeRoot, { pid: process.pid, startedAt: cur?.startedAt || startedAt, change: changeName, rerunQueued: false });
+    console.log(`[spec-sync-bg] 第 ${round}/${BG_MAX_ROUNDS} 轮开始 ${new Date().toISOString()}: ${changeName}`);
+    try {
+      await triggerSync(cwd, changeName, platformOpts, { inline: true, timeoutMs: roundTimeoutMs });
+    } catch (e) {
+      console.warn(`[spec-sync-bg] 本轮同步异常（best-effort，下一条命令自动重试）: ${(e && e.message) || e}`);
+    }
+    const lock = readBgSyncLock(runtimeRoot);
+    if (!lock || lock.pid !== process.pid) {
+      console.warn('[spec-sync-bg] 锁已不属于本进程（被并行 spawn 接管），让位退出');
+      return;
+    }
+    if (!lock.rerunQueued) break;
+    if (Date.now() + roundTimeoutMs > deadline) {
+      console.warn('[spec-sync-bg] 总预算用尽，残留待同步状态由下一条命令的同步接管');
+      break;
+    }
+  }
+  console.log(`[spec-sync-bg] 后台同步完成 ${new Date().toISOString()}: ${changeName}`);
+  removeBgSyncLock(runtimeRoot);
+}
+
+export default { spawnBackgroundSync, runBgSyncFromEnv, readBgSyncLock, isBgSyncLockLive, isPidAlive };

package/src/run/complete-handlers.js

@@ -30,11 +30,11 @@
  * （非被外层吞）；process.exit 不可被 try 捕获 → 搬迁行为完全等价。
  */
 import { basename, dirname, join, resolve, relative, isAbsolute } from 'node:path'
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync, renameSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, isQuicklogFileLineNoise, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, isQuicklogFileLineNoise, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, mergeQuickBoundaryFiles, QUICK_SID_RE } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
@@ -1399,6 +1399,70 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       progress.lastQuickReview = review
     }
 
+    // ── quick 资产尾（2026-09-20-quick-asset-tail，D-001/D-002/D-005）：门禁过后三件机械
+    // 事，agent 零新增命令/零写作义务，fail-open 全链（任何异常 warn 不拦 quick 完成）。
+    // ① 薄通道蒸馏尾：linked 真变更（非 quick-<hex>）→ decision-distill + fr-index（幂等）
+    //    + lite 归档（治「薄通道零资产 + 僵尸 brainstorm 态」——autocompact 对撞实证）。
+    //    挂点在门禁后（D-002 时序：防未实现设计进索引）。
+    // ② 模块 changelog 机械追加：changedFiles×moduleIndex join → 边车存在才 append 一行
+    //    （纯 quick 的检索面——QUICKLOG 是时间流水账，模块边车是空间索引）。
+    // ③ 根因 classify 提示：--cause 原文 × INDEX 关键词命中 → 打一行确切命令（非空提示）。
+    try {
+      // linkedChangesAuto 排除（S2 执行审查缺陷③）：auto-link 命中的他者中途/僵尸变更不走蒸馏
+      // 尾（quick-single-change-auto-link §3 契约——即便 requirements.md 在场也不蒸馏不归档，
+      // 防未实现设计进索引 + 误归档他者 brainstorm 进行中变更）
+      const linkedChanges = Array.isArray(mergedGuard?.linkedChanges) ? mergedGuard.linkedChanges : []
+      const autoLinked = new Set(Array.isArray(mergedGuard?.linkedChangesAuto) ? mergedGuard.linkedChangesAuto : [])
+      const manualLinked = linkedChanges.filter((c) => c && !QUICK_SID_RE.test(c) && !autoLinked.has(c))
+      const { distillLinkedChangeAssets } = await import('./complete-handlers.js')
+      const tail = await distillLinkedChangeAssets({ pm, cwd, specBase, changeName, linkedChanges: manualLinked, platformOpts })
+      for (const w of tail.warnings) console.warn(`⚠️ [资产尾] ${w}`)
+    } catch (e) {
+      console.warn(`⚠️ [资产尾] 蒸馏尾异常（fail-open 不拦 quick 完成）：${e && e.message ? e.message : e}`)
+    }
+    try {
+      // ② changelog 边车追加——projectName 同源修复（S2 执行审查缺陷①a）：progress.project
+      // （与 outputStep 占位符渲染同源，平台模式真实项目名）三级回退，不再硬编码 null。
+      const projName = progress.project
+        || steps[currentIdx].project
+        || (steps[currentIdx].name.match(/\[([^\]]+)\]\s*$/) || [])[1]
+        || null
+      const { loadQuickModuleIndex } = await import('./shared.js')
+      const moduleIndex2 = await loadQuickModuleIndex(specBase, projName)
+      const changed2 = (progress.lastQuickReview?.changedFiles ?? []).map(f => String(f).replace(/\\/g, '/'))
+      if (changed2.length > 0 && moduleIndex2 && projName) {
+        const touchedMods = new Map()
+        for (const [modId, mod] of Object.entries(moduleIndex2)) {
+          const prefixes = [...(mod && Array.isArray(mod.paths) ? mod.paths : []), ...(mod && Array.isArray(mod.core_files) ? mod.core_files : [])]
+          for (const raw of prefixes) {
+            const p = String(raw).replace(/\\/g, '/').replace(/\/+$/, '')
+            if (p && changed2.some(f => f === p || f.startsWith(p + '/'))) { touchedMods.set(modId, mod); break }
+          }
+        }
+        // 修复①b：边车路径补 <project> 段——map 的 doc 字段相对 docs/<project>/（如 modules/x.md）
+        const modulesDir = join(specBase, 'docs', projName)
+        for (const [modId, mod] of touchedMods) {
+          try {
+            const docRel = mod && mod.doc
+            if (!docRel) continue
+            const docNorm = String(docRel).replace(/\\/g, '/')
+            const sidecarRel = docNorm.replace(/\.md$/, '.changelog.md')
+            const target = join(modulesDir, sidecarRel)
+            if (!existsSync(target)) continue // 边车不存在静默跳过（建卡是 scan 职责）
+            const line = `- ${changeName} | quick 机械留痕（${changed2.length} 文件触达 ${modId}；详账见 QUICKLOG）`
+            appendFileSync(target, line + '\n')
+            console.log(`🗂️ 模块留痕：${modId} changelog 边车 +1 行（${changeName}）`)
+          } catch { /* 单模块失败不连坐 */ }
+        }
+      }
+    } catch (e) {
+      console.warn(`⚠️ [资产尾] changelog 追加异常（fail-open）：${e && e.message ? e.message : e}`)
+    }
+    // ③ 根因 classify 提示——S2 复审缺陷②终裁：**删除本块**。既有「待归类提议」块
+    // （下方 extractQuickCauseField → matchKnowledge → 确切 classify 命令）已完全承担此职责
+    // 且传参/qlId/文件路径全正确（1836-1844）；本块首版传对象给字符串参数（TypeError 被吞）
+    // 二版仍是重复建设——机械件③的 classify 职责由既有块唯一承担，本变更不再另造。
+
     // task-02 并发预检（FR-05/FR-07，纯副作用 advisory）：auditQuickCompletion 返回后、推进前
     // 扫工作树，识别他者未提交改动 / 他者脏变更目录，有则 console.warn。不改 status/gate、
     // 不 exit、不 return early（FR-07 铁律）。ownFiles 必含 baselineFiles（D-001：脏工作树 quick
@@ -1897,6 +1961,15 @@ async function closeSingleQuickLinkedChange({ pm, cwd, specBase, changeName, pla
  * 缺陷①）：current_stage=brainstorm 但该阶段 status=completed（brainstorm 收尾到 plan
  * 开始之间的空窗）≠ 僵尸变更——此时关联 quick --done 会把即将进 plan 的进行中变更误
  * 轻量归档。stage_status=completed 一律走原流程收尾。
+ *
+ * 转轨放行（2026-09-20 僵尸状态实证缺口）：缺陷①②两闸把 d192f89 的原始目标场景——
+ * brainstorm 精判 scale:small、设计裁定实现路径即 `quick --linked-changes <本变更>` 的
+ * 刻意转轨变更——也拦成了永真（brainstorm --done 必然置 completed、转轨间隔天然分钟级
+ * 必中时近性闸），linked quick --done 后变更永留 active/brainstorm 成僵尸。识别信号用
+ * brainstorm 末步已落盘的机器可读产物：current_stage=brainstorm + stage_status=completed
+ * + design.md frontmatter scale:small（readDesignScale，gates.js）三条件齐 = 转轨变更，
+ * 放行两闸且 tasks 判定按 quick 语义（无 tasks.md=无待办）；scale=large/未写 scale 的
+ * 在途变更两闸原样生效（缺陷①②防护面不变）。
  */
 const QUICK_CLOSE_ALLOWED_STAGES = new Set(['', 'scan', 'brainstorm'])
 
@@ -1913,6 +1986,10 @@ const QUICK_CLOSE_ACTIVITY_WINDOW_MS = 60 * 60 * 1000
  * scan/brainstorm 才继续 tasks 判定；plan/execute/verify/archive 一律 skip 走原流程收尾。
  * pm 缺 getChangeStage 接口或查询抛错同样 skip，不静默放行。
  *
+ * 转轨放行：current_stage=brainstorm + stage_status=completed + design.md scale:small =
+ * brainstorm 精判裁定走 quick 的刻意转轨变更（见 QUICK_CLOSE_ALLOWED_STAGES 上注释），
+ * 豁免「阶段完成态」「时近性」两闸与「无 tasks.md」判定，linked quick --done 即收尾。
+ *
  * @param {Object} opts
  * @param {ProgressManager} opts.pm
  * @param {string} opts.cwd
@@ -1952,13 +2029,25 @@ export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges
         })
         continue
       }
+      // 刻意转轨判定（见 QUICK_CLOSE_ALLOWED_STAGES 上注释「转轨放行」段）：scale:small 是
+      // brainstorm 末步写进 design.md frontmatter 的精判产物（stages/brainstorm.js「生成规范
+      // 文件」步），其设计实现路径就是本 quick 会话——linked quick --done 即本变更流程收尾点。
+      // readDesignScale 动态导入破环（gates.js 静态导入本模块，其 :1175 反向动态 import 先例）；
+      // 导入/执行异常 fail-safe 按「非转轨」走原闸，不废既有护栏。
+      let quickHandoff = false
+      if (stageInfo !== null && stageInfo.current_stage === 'brainstorm' && stageInfo.stage_status === 'completed') {
+        try {
+          const { readDesignScale } = await import('./gates.js')
+          quickHandoff = readDesignScale(specBase, changeName) === 'small'
+        } catch { /* fail-safe：识别不了按非转轨走原闸 */ }
+      }
       // ql-20260819-010（quick-done-autoarchive-misfire 缺陷①）：当前阶段已完成 ≠
       // 从未进入完整流程的僵尸。brainstorm 收尾到 plan 开始之间的空窗里 current_stage
       // 仍读 brainstorm，只看阶段名会把即将进 plan 的变更误轻量归档（propose 骨架
       // tasks.md 除 quick 追加的 ql 行外没有任务行，「无未勾选框=全勾」恒真）。
       // stage_status=completed 一律原流程收尾；null（无阶段行/brownfield）与旧调用方
       // mock 缺字段（undefined）均按未完成放行，僵尸逃生通道行为不变。
-      if (stageInfo !== null && stageInfo.stage_status === 'completed') {
+      if (!quickHandoff && stageInfo !== null && stageInfo.stage_status === 'completed') {
         skipped.push({
           name: changeName,
           reason: `变更当前阶段「${stageInfo.current_stage || '(空)'}」已完成（推进/收尾中，非僵尸变更），不自动归档——请走原流程收尾（sillyspec progress show 查看进度）`,
@@ -1974,7 +2063,10 @@ export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges
       //（既有「真·僵尸 in_progress→closed」行为保留）。pm 无此方法（旧 mock/旧进度库）
       // 按无近期活动放行——与 getChangeStage 缺失 skip 的 fail-safe 不同向：本闸误放行的
       // 最坏后果是回到缺陷②现状（有 D-002 防护兜底），误拦截则僵尸永不清——权衡取放行。
-      if (typeof pm.getLatestActivityAt === 'function') {
+      // （转轨变更例外：brainstorm --done → quick 启动/--done 间隔天然分钟级，时近性对它
+      // 是永真拦截信号——quickHandoff 已用 scale:small 坐实「等 quick 落地」，不在「在途」
+      // 语义面内，放行。）
+      if (!quickHandoff && typeof pm.getLatestActivityAt === 'function') {
         const latest = pm.getLatestActivityAt(cwd, changeName)
         if (latest && Date.now() - new Date(latest).getTime() < QUICK_CLOSE_ACTIVITY_WINDOW_MS) {
           skipped.push({
@@ -1984,7 +2076,13 @@ export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges
           continue
         }
       }
-      if (!isChangeTasksComplete(specBase, changeName)) {
+      // tasks 判定（转轨例外）：scale=small 按 brainstorm 末步约定不生成 tasks.md
+      //（「proposal/requirements/tasks 对 quick 无用」）——转轨变更无 tasks.md = 无待办
+      // 放行；文件存在（propose 骨架等）仍按全勾判定，未勾任务行照拦。
+      const tasksComplete = quickHandoff && !existsSync(join(specBase, 'changes', changeName, 'tasks.md'))
+        ? true
+        : isChangeTasksComplete(specBase, changeName)
+      if (!tasksComplete) {
         skipped.push({ name: changeName, reason: 'tasks.md 未全勾选或不存在' })
         continue
       }
@@ -2733,3 +2831,108 @@ async function runArchiveCeremonyDualRunExit({ cwd, specBase, changeName, platfo
   }
 }
 
+
+// ── quick 资产尾（2026-09-20-quick-asset-tail，D-001/D-002/D-004）─────────────────
+
+/**
+ * lite 归档（D-004）：薄通道（brainstorm→linked quick）变更的轻量收口——所有权 assert →
+ * 命名 → rename → unregisterChange。不复用 archiveChangeDirectory 的 9 处重门（未 apply
+ * 交付面等 worktree 导向，linked quick 变更无 worktree 语义会被误拦）；重件
+ * （module-impact/ROADMAP/delta）明确豁免。自愈：源目录缺失但已在 archive/ 时补
+ * unregister 不留永久 skipped（与重路径 586-604 同款语义）。
+ * @returns {Promise<{archivedTo: string}|{skipped: string}>}
+ */
+export async function liteArchiveChange({ pm, cwd, specBase, changeName, platformOpts = {} }) {
+  const changesDir = join(specBase, 'changes')
+  const archiveDir = join(changesDir, 'archive')
+  const srcDir = join(changesDir, changeName)
+  // 所有权（同重路径语义：他人活跃拒；self/stale/forced 放行并接管）
+  const { session } = resolveSessionIdentity({ flagSession: platformOpts.sessionFlag || null, cwd })
+  const check = pm.assertChangeOwnership(cwd, changeName, { selfSession: session, nowMs: Date.now() })
+  if (!check.allowed) return { skipped: `所有权拒（owner=${check.owner}，活跃窗内）` }
+  if (check.action !== 'self') pm.setChangeOwner(cwd, changeName, session)
+  // 自愈：目录已被手动/前次部分流程移到 archive/ → 只补 unregister（不留永久 desync）
+  if (!existsSync(srcDir)) {
+    // lite 变更目录常无 plan.md（findAlreadyArchivedDir 精确命中的硬条件）——本场景放宽：
+    // archive/ 下有以变更名为末段的目录且含 requirements.md 或 decisions.md 即认自愈
+    const already = (() => {
+      try {
+        const entries = readdirSync(archiveDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+        const hit = entries.find(e => (e === changeName || e.endsWith('-' + changeName)) &&
+          (existsSync(join(archiveDir, e, 'requirements.md')) || existsSync(join(archiveDir, e, 'decisions.md'))))
+        return hit ? join(archiveDir, hit) : null
+      } catch { return null }
+    })()
+    if (already) {
+      pm.unregisterChange(cwd, changeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
+      console.log(`📦 lite 自愈归档：${changeName} 已在 archive/（${basename(already)}），补注销 DB 行`)
+      return { archivedTo: already }
+    }
+    return { skipped: `源目录不存在且 archive/ 无此变更（requirements/decisions 均缺的空关联）` }
+  }
+  const destName = archiveDestDirName(new Date().toISOString().slice(0, 10), changeName)
+  const destDir = join(archiveDir, destName)
+  mkdirSync(archiveDir, { recursive: true })
+  renameSync(srcDir, destDir) // 先 rename 后 unregister：失败时 change 留 active 可重试（D-004 顺序保证）
+  pm.unregisterChange(cwd, changeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
+  console.log(`📦 lite 归档：${changeName} → archive/${destName}/（薄通道轻收口：蒸馏已先行，module-impact/ROADMAP 豁免）`)
+  return { archivedTo: destDir }
+}
+
+/**
+ * 薄通道蒸馏尾（D-001/D-002）：quick --done 门禁过后对 linked 真变更（非 quick-<hex>）跑
+ * decision-distill + fr-index（均幂等）→ lite 归档。挂点在质量闸后（D-002：防未实现设计进
+ * 索引——quick 中途废弃永不 --done 永不蒸馏）；两文件均缺失零打扰跳过；fail-open 全链
+ * （任何异常 warn 留痕不拦 quick 完成）。
+ * @returns {Promise<{distilled: boolean, frCount: number, decisionCount: number, archived: boolean, warnings: string[]}>}
+ */
+export async function distillLinkedChangeAssets({ pm, cwd, specBase, changeName, linkedChanges = [], platformOpts = {} }) {
+  const out = { distilled: false, frCount: 0, decisionCount: 0, archived: false, warnings: [] }
+  const realChanges = (linkedChanges || []).filter((c) => c && !QUICK_SID_RE.test(c))
+  if (realChanges.length === 0) return out // 纯 quick：无关联真变更，零打扰
+  try {
+    const knowledgeRoot = join(specBase, 'knowledge')
+    let anyDistilled = false
+    for (const linked of realChanges) {
+      const changeDir = join(specBase, 'changes', linked)
+      if (!existsSync(changeDir)) { out.warnings.push(`linked 变更目录缺失：${linked}`); continue }
+      const hasReqs = existsSync(join(changeDir, 'requirements.md'))
+      const hasDecisions = existsSync(join(changeDir, 'decisions.md'))
+      if (!hasReqs && !hasDecisions) continue // quick/scale:small 无索引义务（fr-index 既有语义对齐）
+      // 决策蒸馏（decisions.md → knowledge/decisions/，幂等；无文件内部自跳过）
+      if (hasDecisions) {
+        try {
+          const { distillIntoKnowledge } = await import('../decision-distill.js')
+          const r = distillIntoKnowledge(changeDir, knowledgeRoot, '')
+          const writtenCount = r && Array.isArray(r.written) ? r.written.length : 0
+          if (writtenCount > 0) { out.decisionCount += writtenCount; anyDistilled = true }
+        } catch (e) { out.warnings.push(`decision-distill ${linked} 异常跳过：${e && e.message ? e.message : e}`) }
+      }
+      // FR 索引（requirements.md → knowledge/fr/，幂等：同变更名 no-op）
+      if (hasReqs) {
+        try {
+          const { indexRequirements } = await import('../fr-index.js')
+          const r = indexRequirements({ changeDir, knowledgeRoot, headHash: '' })
+          if (r && Array.isArray(r.written) && r.written.length > 0) { out.frCount += r.written.length; anyDistilled = true }
+        } catch (e) { out.warnings.push(`fr-index ${linked} 异常跳过：${e && e.message ? e.message : e}`) }
+      }
+    }
+    out.distilled = anyDistilled
+    // lite 归档（蒸馏后；仅四件套容器变更——requirements.md 在场=brainstorm 承接的薄通道形态；
+    // 纯信号自动关联的 proposal-only 变更不归档〔quick-single-change-auto-link §3 契约钉死〕）
+    for (const linked of realChanges) {
+      if (!existsSync(join(specBase, 'changes', linked, 'requirements.md'))) continue
+      try {
+        const r = await liteArchiveChange({ pm, cwd, specBase, changeName: linked, platformOpts })
+        if (r.archivedTo) out.archived = true
+        else if (r.skipped) out.warnings.push(`lite 归档 ${linked}：${r.skipped}`)
+      } catch (e) { out.warnings.push(`lite 归档 ${linked} 异常跳过：${e && e.message ? e.message : e}`) }
+    }
+    if (anyDistilled || out.archived) {
+      console.log(`📚 quick 资产尾：${out.frCount} 条 FR 入索引、${out.decisionCount} 条决策入 knowledge${out.archived ? '、linked 变更 lite 归档' : ''}（门禁后自动，agent 零新增命令）`)
+    }
+  } catch (e) {
+    out.warnings.push(`蒸馏尾异常（fail-open 不拦 quick 完成）：${e && e.message ? e.message : e}`)
+  }
+  return out
+}

package/src/run/gates.js

@@ -1905,22 +1905,27 @@ export function writeReconcileRunResult({ runtimeRoot, changeName, envelope, res
  */
 /**
  * 打印跨仓 per-repo 对账结果（cross-repo-reconcile.js 产出的 advisory 明细，verify 块接线）。
- * 恒不阻断（返回 void）：跨仓 diff 锚点=各仓最近提交窗口，锚点脆弱期（已 commit 多笔/全在
- * working-tree）会产②类假信号——明细供人工裁决，不翻主仓对账状态。
+ * 恒不阻断（返回 void）：锚点档逐行携带（内核分级：A reviews 锡点区间 > B 最近提交窗口 >
+ * C 未提交窗口，anchor.label 透传），锚点脆弱期（已 commit 多笔/全在 working-tree）会产②类
+ * 假信号——明细供人工裁决，不翻主仓对账状态。
  * @param {Array<{repo:string,repoPath:string|null,declaredCount:number,actualCount:number,
  *   matched:string[],missing:Array<{task:string,path:string,isNew?:boolean}>,
- *   undeclared:string[],scaffoldCount:number,degradedReason:string|null}>|undefined} crossRepo
+ *   undeclared:string[],scaffoldCount:number,degradedReason:string|null,
+ *   anchor?:{source:string,base:string|null,head:string|null,label:string}}>|undefined} crossRepo
  */
 function printCrossRepoReconcile(crossRepo) {
   if (!Array.isArray(crossRepo) || crossRepo.length === 0) return
-  console.log(`\n🔀 跨仓 per-repo 对账（advisory 不阻断，锚点=各仓最近提交窗口）：`)
+  console.log(`\n🔀 跨仓 per-repo 对账（advisory 不阻断）：`)
   for (const r of crossRepo) {
     if (r.degradedReason) {
       console.warn(`   ⚠️ ${r.repo}：${r.degradedReason}`)
       continue
     }
     const flag = (r.missing.length > 0 || r.undeclared.length > 0) ? '⚠️ ' : '✅ '
-    console.log(`   ${flag}${r.repo}（${r.repoPath}）：声明 ${r.declaredCount} / 实测 ${r.actualCount} / 对上 ${r.matched.length} / ②缺 ${r.missing.length} / ③多 ${r.undeclared.length}${r.scaffoldCount > 0 ? ` / 脚手架聚合 ${r.scaffoldCount}` : ''}`)
+    // 锚点档标签（task-03）：有 anchor.label 时追加（A/B/C 档人类可读描述）；无 anchor（旧形态）
+    // 零输出——逐字兼容
+    const anchorTag = r.anchor && typeof r.anchor.label === 'string' && r.anchor.label ? `｜锚点 ${r.anchor.label}` : ''
+    console.log(`   ${flag}${r.repo}（${r.repoPath}）：声明 ${r.declaredCount} / 实测 ${r.actualCount} / 对上 ${r.matched.length} / ②缺 ${r.missing.length} / ③多 ${r.undeclared.length}${r.scaffoldCount > 0 ? ` / 脚手架聚合 ${r.scaffoldCount}` : ''}${anchorTag}`)
     for (const m of r.missing.slice(0, 10)) {
       console.warn(`      ②缺 ${m.task}: ${m.path}${m.isNew ? '（NEW: 声明新建，该仓未见）' : ''}——锚点窗口外已提交或多笔时可能假信号，到该仓 git log 核实`)
     }

package/src/run/prompt.js

@@ -1151,7 +1151,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       if (entries.length === 0) {
         promptText = promptText.replace(/\{FR_INDEX_DIGEST\}/g, '（触达域暂无 active FR 索引条目——本变更大概率是这些域的首批需求，照常写作）')
       } else {
-        const lines = entries.map((e) => `- ${e.id} ${e.title}（来源 ${e.change}${e.scenarios.length ? '；场景：' + e.scenarios.slice(0, 3).join('，') : ''}${(e.decisions || []).length ? '；依据：' + e.decisions.slice(0, 3).join('、') : ''}）`)
+        const lines = entries.map((e) => `- ${e.id} ${e.title}（来源 ${e.change}${e.scenarios.length ? '；场景：' + e.scenarios.slice(0, 3).join('，') : ''}${(e.decisions || []).length ? '；依据：' + e.decisions.slice(0, 3).join('、') : ''}）${e.needsReview ? ` ⚠️ 待复核（${e.needsReview}）——该 FR 覆盖的代码近期被 quick 触达，行为可能已变；本变更若触及同域先核对现状再决定承接/新写` : ''}`)
         lines.push('')
         lines.push('> 域解析自本变更 design.md 文件清单（漏域先核对清单）。改写/取代已有行为 → 对应 FR 块加承接行；新行为 → 新 FR 块。superseded 条目默认不列（历史回溯自行读 knowledge/fr/）。依据决策（L2）= 当年取舍锚——翻案须先读 knowledge/decisions/<域>.md 的否决理由，满足复潮条件走 D-xxx@vN+1，不得静默改行为。承接行可带退役理由：`承接: FR-<域>-NNN（退役理由：一句话）`——归档时写进被取代条目（理由内禁逗号）；条目正文是截断摘要，全文锚（全文：<归档路径>#FR-NN）由 CLI 自动落。')
         promptText = promptText.replace(/\{FR_INDEX_DIGEST\}/g, lines.join('\n'))

package/src/run/shared.js

@@ -854,6 +854,28 @@ async function raceWithAbort(op, timeoutMs = resolveSyncTotalTimeoutMs()) {
 export const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
 
 export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  // ── 后台异步化（2026-09-20 用户反馈：--done 被网络尾巴拖住分钟级）──
+  // 默认把同步整体挪进 detached 后台子进程：17 个调用点全部 fire-and-forget，但进程
+  // 退出要等事件循环排空，在飞 fetch 拖住命令返回。回落 inline 的三条件：
+  //   opts.inline（bg 子进程自身回环调用/测试断言进程内行为）
+  //   env SILLYSPEC_SYNC_BG=0（逃生阀，回退旧行为）
+  //   env SILLYSPEC_BG_SYNC_CWD 在场（本进程已是后台子进程，防 fork 链）
+  // spawn 决策（未连接预判/单飞锁/rerunQueued 合并/日志）见 bg-sync.js；bg 机制任何
+  // 异常降级 inline，绝不因后台化阻断主流程。
+  if (!opts.inline && changeName
+    && process.env.SILLYSPEC_SYNC_BG !== '0'
+    && !process.env.SILLYSPEC_BG_SYNC_CWD) {
+    try {
+      const bg = await import('./bg-sync.js')
+      const r = await bg.spawnBackgroundSync(cwd, changeName, platformOpts, opts)
+      if (r.status === 'spawned') {
+        console.log(`🔄 [spec-sync] 平台同步转后台执行（不阻塞本命令返回；输出与结果见 ${r.logPath}）`)
+        return
+      }
+      if (r.status === 'coalesced') return // 活后台轮在跑，本轮状态已并入其下一轮
+      // not-connected → 落回 inline（内部静默 no-op，与旧行为一致）
+    } catch { /* 后台化失败降级 inline（best-effort 契约不变） */ }
+  }
   // 平台模式不再整体跳过（2026-08-26 用户决策）：上行回传（进度 + 四件套 + spec 树）
   // 在平台模式同样执行，凭据经 env SILLYHUB_PLATFORM_URL/TOKEN（预留通道，daemon 未
   // 实现注入——需外部显式 export，sync.js _getPlatform，链路 D 同款）或 local.yaml
@@ -1815,6 +1837,16 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
               type: 'fr-rot-suspect', change: guard.changeName || null,
               domains: [...touchedDomains], count: frs.length, source: 'quick-done',
             })
+            // 地图诚实升级（2026-09-20-quick-asset-tail FR-02/D-003）：遥测之外给条目打
+            // 待复核标记——下一次 brainstorm 注入行带 ⚠️，承接翻链时清除。fail-open 同块。
+            const markRef = guard.changeName || 'recent-quick'
+            try {
+              const { markFrNeedsReview } = await import('../fr-index.js')
+              const mr = markFrNeedsReview(join(specBase, 'knowledge'), frs.map(f => f.id), markRef)
+              if (mr.marked > 0) {
+                console.warn(`⚠️ [FR 待复核标记] ${mr.marked} 条 active FR 已标「待复核：${markRef}」——下次 brainstorm 注入可见，承接翻链时自动清除`)
+              }
+            } catch { /* 标记失败不影响遥测/审计 */ }
             console.warn(`⚠️ [FR 腐烂 suspect·advisory] 本次 quick 触达 ${[...touchedDomains].join('、')} 域的 ${frs.length} 条 active FR——quick 不走归档，若改动影响这些行为，索引不会自动 supersede（L3 声明义务；盲区：unmapped 文件/map 漂移不报警）`)
           }
         }