sillyspec 3.29.4 → 3.30.0

package/src/run/complete-handlers.js

@@ -52,6 +52,8 @@ import { resolveSessionIdentity } from '../progress.js'
 // checkDbScriptDeclarationGate（task-04 / FR-05）同排静态引入：门函数自身纯文件集 ×
 // 文本声明对账（verify-probes 文法经 worktree-apply 顶层动态绑定），同样无环约束。
 import { chunkPaths, checkDbScriptDeclarationGate } from '../worktree-apply.js'
+import { parseModulePathsSubset } from '../decision-distill.js'
+import { parseUncategorizedEntries } from '../knowledge-classify.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -527,6 +529,25 @@ export function archiveNarrowedGitAdd({ cwd, specBase, destDir, destName }) {
   // changes 侧：本变更归档目录精确收窄（quick 轻量归档 closeSingleQuickLinkedChange 同款）
   safeGit(cwd, ['add', '--', `.sillyspec/changes/archive/${destName}/`])
 
+  // knowledge 侧（cli-protocol-trust / R17 臂3 实证 distill 产物 untracked 漏提交）：本归档链
+  // distill 刚写的 fr 域文件/decisions/INDEX 必在 status 面——按 status 窄化逐文件精确 add
+  // （非目录级：避免扫入他侧并行会话的同目录 WIP；追加型共享面整文件提交与既有惯例一致）。
+  try {
+    const _knSt = gitQuiet(cwd, ['status', '--porcelain'])
+    if (_knSt) {
+      const knFiles = String(_knSt).split('\n').map((l) => {
+        const p = l.slice(3).trim().replace(/^"|"$/g, '')
+        const arrow = p.indexOf(' -> ')
+        return arrow !== -1 ? p.slice(arrow + 4) : p // rename 形态取新路径（评审 P3 清偿）
+      }).filter((p) => p.replace(/\\/g, '/').startsWith('.sillyspec/knowledge/'))
+      for (const batch of chunkPaths(knFiles)) safeGit(cwd, ['add', '--', ...batch])
+      if (knFiles.length > 0) console.log(`   📚 knowledge 蒸馏产物入暂存：${knFiles.length} 个文件（fr 域/decisions/INDEX）`)
+      else console.log('   ℹ️ knowledge 面无待入暂存文件（本归档无蒸馏产物变更）')
+    }
+  } catch (e) {
+    console.warn(`⚠️ knowledge 侧 add 失败（fail-soft，不阻断归档链）：${e && e.message ? e.message : e}`)
+  }
+
   // docs 侧：module-impact「更新结果」done 行 → 精确文件集。
   // 三态（对齐修复④要求）：
   //   - module-impact.md 无「## 更新结果」段 / 文件缺失 / 读取异常 → docPaths=null → 回退目录级
@@ -570,56 +591,161 @@ export function archiveNarrowedGitAdd({ cwd, specBase, destDir, destName }) {
   return { docsAdded: null, fallbackDocs: true }
 }
 
-export async function archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts = {}, gateOpts = {}) {
-  const archiveChangeName = progress.currentChange
-  if (!archiveChangeName) {
-    console.error('❌ 归档失败：未找到当前变更名（currentChange）')
-    process.exit(1)
+/**
+ * flow 变更交付面推导（资产三小件③）——flow.js changedFilesSinceBaseline 同口径本仓实现
+ * （flow.js 为并行会话在改，不 cross-import；两处语义等价：diff 基线→HEAD + porcelain dirty，
+ * 排除 .sillyspec/ 内部产物）。docsIncrement 单列 .sillyspec/docs/**（文档认领增量信号）。
+ * @returns {{ deliverableFiles: string[], docsIncrement: string[] }|null}
+ *   非 flow 变更（无 flow-state.yaml / 无 baseline_commit / 读取异常）→ null（调用方跳过 advisory）
+ */
+export function deriveFlowDeliverableFace({ cwd, srcDir }) {
+  let baseline = null
+  try {
+    const raw = readFileSync(join(srcDir, 'flow-state.yaml'), 'utf8')
+    const m = raw.match(/^baseline_commit:\s*'?([0-9a-f]{7,40})'?\s*$/m)
+    baseline = m ? m[1] : null
+  } catch { return null }
+  if (!baseline) return null
+  const all = new Set()
+  const addAll = (out) => {
+    if (!out) return
+    for (const l of String(out).split('\n')) {
+      const p = l.trim().replace(/\\/g, '/')
+      if (p) all.add(p)
+    }
   }
-  const changesDir = join(specBase, 'changes')
-  const archiveDir = join(changesDir, 'archive')
-  const srcDir = join(changesDir, archiveChangeName)
-  const date = new Date().toISOString().slice(0, 10)
-  const destName = archiveDestDirName(date, archiveChangeName)
-  const destDir = join(archiveDir, destName)
-
-  if (!existsSync(srcDir)) {
-    // 幂等自愈（issue archive-stage-physical-tracking-desync）：源目录已不存在，但变更可能已被
-    // 手动 / 部分流程移到 changes/archive/ 并 commit，而 --done --confirm 从未正式跑完 → 进度 DB
-    // 卡 archive 阶段、active 列表仍列此 change。检测到已归档则回填进度（unregisterChange）并
-    // 成功返回，让收尾流程把 archive 阶段标完成，而非 exit(1) 死路（source 已移走无法重跑 move）。
-    const alreadyArchivedDir = findAlreadyArchivedDir(archiveDir, archiveChangeName)
-    if (alreadyArchivedDir) {
-      console.log(`ℹ️  源目录不存在但变更已在 archive/（${basename(alreadyArchivedDir)}），判定已归档，自愈进度 DB`)
-      // 终态一致化（坑 manual-archive-desync-status-only）：手动搬目录绕过标准归档后，本自愈路径
-      // 不能只翻 status——同时收尾 archive 阶段（steps/stages/current_stage），否则推送平台的终态
-      // 是「已归档 + 归档 0/5 + 停在 execute」的矛盾体，详情页渲染成「进度丢失」
-      pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
-      await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
-      console.log(`📦 已自愈归档：${archiveChangeName} → archive/${basename(alreadyArchivedDir)}/`)
-      return alreadyArchivedDir
+  addAll(gitQuiet(cwd, ['diff', '--name-only', `${baseline}..HEAD`]))
+  const s = gitQuiet(cwd, ['status', '--porcelain'])
+  if (s) {
+    for (const line of String(s).split('\n')) {
+      if (!line || line.length < 4) continue
+      const p = line.slice(3).trim().replace(/^"|"$/g, '')
+      const arrow = p.indexOf(' -> ')
+      all.add((arrow !== -1 ? p.slice(arrow + 4) : p).replace(/\\/g, '/'))
     }
-    console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
-    console.error(`   且 changes/archive/ 下未找到该变更的归档目录。若已手动归档请核对目录名；否则先补全变更产物。`)
-    process.exit(1)
   }
-  // ── 所有权护栏（2026-09-14-change-ownership-guards task-03 / FR-01 / D-001@v1 接线点）──
-  // 归档=接管类操作（注销 change + 移目录 + 清 worktree），他人活跃 change 硬拒。判定在
-  // withMainRepoLock 锁内（handleArchiveConfirmStep 调用点），判定-执行无 TOCTOU；放行分支
-  // no-owner/takeover-stale 重写 owner=本会话（setChangeOwner 同事务刷新 last_active，心跳从
-  // 接管时刻起算）。会话标识三级解析：--session > env SILLYSPEC_SESSION_ID > anon@host（降级
-  // 时 resolveSessionIdentity 自带教学 warning）。消费 task-02 契约（assertChangeOwnership
-  // 纯读不写库），不重复实现判定语义。
-  {
-    const { session } = resolveSessionIdentity({ flagSession: gateOpts.sessionFlag || null, cwd })
-    const check = pm.assertChangeOwnership(cwd, archiveChangeName, { selfSession: session, nowMs: Date.now() })
-    if (!check.allowed) {
-      console.error(`🚫 归档失败：变更 ${archiveChangeName} 正被其他会话持有（owner: ${check.owner}，最后活跃: ${check.lastActive || '未知'}），活跃窗口 ${Math.round(check.heartbeatMs / 60000)} 分钟内拒绝归档`)
-      console.error(`   等对方会话收尾后重试（窗口过后自动接管）；确认对方已放弃且本会话应接管：先经 sillyspec worktree apply/cleanup ${archiveChangeName} --takeover 显式接管（重写 owner 留痕）再归档`)
-      process.exit(1)
+  return {
+    deliverableFiles: [...all].filter((p) => !p.startsWith('.sillyspec/')),
+    docsIncrement: [...all].filter((p) => p.startsWith('.sillyspec/docs/')),
+  }
+}
+
+/**
+ * 模块文档认领 advisory（资产三小件③，advisory 不阻断归档链）。
+ *
+ * 背景：flow done/burst 收口不产生模块文档增量（旧流程的文档同步挂在 execute/verify 步骤里）
+ * ——R7-L 重放实证零模块文档的资产缺口。判定：deliverableFiles 交付面 × module-map
+ * （discoverModuleIndex 同源解析 parseModulePathsSubset，按项目扫描保卡片路径归属）交集
+ * ≥1 且本次变更无 .sillyspec/docs/** 增量 → 一行警告列出未认领模块卡路径。
+ * --no-docs 豁免仅存在于 quick 出口（run/command.js L2 docClaim），archive 链无该 flag——
+ * 出现豁免语义时在 runArchiveChain 接线处尊重。
+ * @returns {string|null} 命中 → 警告文案；负例（纯 spec 变更/有文档增量/无交集/无 map）→ null
+ */
+export function buildArchiveModuleDocAdvisory({ specBase, deliverableFiles, docsIncrement }) {
+  if (!Array.isArray(deliverableFiles) || deliverableFiles.length === 0) return null
+  if (Array.isArray(docsIncrement) && docsIncrement.length > 0) return null
+  const posix = deliverableFiles.map((f) => String(f).replace(/\\/g, '/')).filter((f) => f && !f.startsWith('.sillyspec/'))
+  if (posix.length === 0) return null
+  const docsDir = join(specBase, 'docs')
+  if (!existsSync(docsDir)) return null
+  const cards = []
+  for (const d of readdirSync(docsDir, { withFileTypes: true })) {
+    if (!d.isDirectory()) continue
+    const mapPath = join(docsDir, d.name, 'modules', '_module-map.yaml')
+    if (!existsSync(mapPath)) continue
+    let mods
+    try { mods = parseModulePathsSubset(readFileSync(mapPath, 'utf8')) } catch { continue }
+    for (const [id, m] of Object.entries(mods || {})) {
+      const prefixes = [...(m && m.paths ? m.paths : []), ...(m && m.core_files ? m.core_files : [])]
+        .map((p) => String(p).replace(/\\/g, '/').replace(/\/+$/, '')).filter(Boolean)
+      const hit = prefixes.some((p) => posix.some((f) => f === p || f.startsWith(p + '/')))
+      if (hit && m && typeof m.doc === 'string' && m.doc.trim() !== '') {
+        // doc 值相对 docs/<项目>/（如 modules/core-engine.md），不再叠 modules/ 段
+        const card = `.sillyspec/docs/${d.name}/${m.doc.replace(/^\.\//, '').replace(/\\/g, '/')}`
+        if (!cards.some((c) => c.card === card)) cards.push({ id, card })
+      }
     }
-    if (check.action !== 'self') pm.setChangeOwner(cwd, archiveChangeName, session)
   }
+  if (cards.length === 0) return null
+  return `⚠️ 模块文档认领 advisory：交付面命中 ${cards.map((c) => c.id).join('、')} 模块但本次变更无 .sillyspec/docs/** 增量——未认领模块卡：${cards.map((c) => c.card).join('、')}（advisory 不阻断归档；确认无需文档增量可忽略，需落盘则先补模块卡再归档）`
+}
+
+// ── 归档时间线烤制（2026-09-28-archive-timeline-bake）──
+// 事件流（.runtime/watcher-events-<change>.jsonl）机本位：gitignore + 平台同步排除区，归档后
+// 本机清理/跨机 clone 均无从合成时间线。本函数在归档链 rename 后调用：用与 `watcher timeline`
+// CLI 同一合成面（readWatcherEvents × parseTaskLines/readBirthTs/flow-state tier ×
+// resolveCommitAnchors(gitLook)）把渲染文本写 destDir/timeline.md、原始事件字节副本写
+// destDir/watcher-events.jsonl（尺寸帽防巨型事件流污染 git，超帽只烤渲染面）。整体 fail-open：
+// 异常返回 {ok:false} 由调用方一行警告，不阻断归档。runtimeRoot 解析与 spawnWatcher 写侧同链
+// （resolvePlatformOpts > resolveRuntimeRoot）——平台模式下事件流在平台 runtime 目录也能读对。
+// gitLook/写读函数/尺寸帽/nowIso 为测试注入面（缺省 gitQuiet 包装与 index.js timeline 接线同形）。
+export const BAKE_EVENTS_COPY_MAX_BYTES = 2 * 1024 * 1024
+
+export async function bakeArchiveTimeline({ cwd, specBase, changeName, destDir, gitLook = null, writeImpl = writeFileSync, readRawImpl = readFileSync, eventsCopyMaxBytes = BAKE_EVENTS_COPY_MAX_BYTES, nowIso = null }) {
+  try {
+    const { resolvePlatformOpts } = await import('../progress.js')
+    const runtimeRoot = resolveRuntimeRoot(resolvePlatformOpts(cwd), specBase)
+    const { readWatcherEvents, watcherEventsPath } = await import('../watcher.js')
+    const res = readWatcherEvents({ runtimeRoot, change: changeName })
+    if (!res.exists) return { ok: true, skipped: true, reason: `无事件流（${watcherEventsPath(runtimeRoot, changeName)}）` }
+    const { parseTaskLines, renderBakedTimeline, resolveCommitAnchors, readBirthTs } = await import('../timeline.js')
+    let tasks = null
+    try { tasks = parseTaskLines(readRawImpl(join(destDir, 'tasks.md'), 'utf8')) } catch { /* 任务面缺失照烤（渲染层有降级段） */ }
+    let tier = null
+    try { const m = /^tier:\s*(\S+)/m.exec(readRawImpl(join(destDir, 'flow-state.yaml'), 'utf8')); if (m) tier = m[1] } catch { /* 头脑风暴预段等无 flow-state 按未知 */ }
+    const look = gitLook || ((hash) => {
+      const out = gitQuiet(cwd, ['log', '-1', '--format=%h%x1f%aI%x1f%B', hash])
+      if (typeof out !== 'string' || !out.trim()) return null
+      const sep = out.indexOf('\x1f')
+      const rest = out.slice(sep + 1)
+      const sep2 = rest.indexOf('\x1f')
+      return { hash: out.slice(0, sep), dateISO: rest.slice(0, sep2), message: rest.slice(sep2 + 1) }
+    })
+    const anchors = resolveCommitAnchors(res.events, look)
+    let eventsRaw = null
+    try { eventsRaw = readRawImpl(watcherEventsPath(runtimeRoot, changeName), 'utf8') } catch { /* 副本缺源只烤渲染面 */ }
+    const oversize = eventsRaw != null && Buffer.byteLength(eventsRaw, 'utf8') > eventsCopyMaxBytes
+    // 评审 P3-1 清偿：副本未落盘（读源失败或超帽）时头注记必须显式「未随包」，不虚报在场
+    const timelineMd = renderBakedTimeline({ change: changeName, events: res.events, tasks, anchors, birthTs: readBirthTs(destDir), tier, bakedAtIso: nowIso || new Date().toISOString(), eventsCopySkipped: eventsRaw == null || oversize })
+    writeImpl(join(destDir, 'timeline.md'), timelineMd)
+    const files = ['timeline.md']
+    if (eventsRaw != null && !oversize) {
+      writeImpl(join(destDir, 'watcher-events.jsonl'), eventsRaw)
+      files.push('watcher-events.jsonl')
+    }
+    return { ok: true, skipped: false, files, eventsCopySkipped: oversize }
+  } catch (e) {
+    return { ok: false, skipped: false, error: e && e.message ? e.message : String(e) }
+  }
+}
+
+/**
+ * runArchiveChain —— 归档执行链（R7 切片二 task-02 从 archiveChangeDirectory 抽出，纯搬运）。
+ *
+ * 链面：未 apply 交付面检查（--skip-apply 留痕旁路）→ plan.md 硬校验（skipPlanCheck 旁路：
+ * flow thin 轻量工件面无 plan.md，task-03 flow done 归档子步传 true；既有 archive 流程缺省
+ * false 行为零变化）→ module-impact pending 死信校验 → 目标目录检查 → 目录搬移（rename 重试）
+ * → 时间线烤制（fail-open，2026-09-28-archive-timeline-bake）→ unregisterChange 终态一致化
+ * → archiveNarrowedGitAdd 窄化暂存 → 他者半归档残留探测。
+ * 消费方：archiveChangeDirectory（既有 archive 流程）与 flow done 归档子步（R7）。
+ *
+ * @returns {Promise<void>} 失败面沿链内既有 process.exit 语义（纯搬运不改）。
+ */
+export async function runArchiveChain({ pm, cwd, specBase, changeName, srcDir, destDir, skipApply = false, skipPlanCheck = false, deliverableFiles = null, docsIncrement = null } = {}) {
+  const archiveDir = dirname(destDir) // 抽取补：原闭包变量（changes/archive），从 destDir 推导等价
+  // ── 模块文档认领 advisory（资产三小件③，2026-09-23）──
+  // flow done/burst 收口不产生模块文档增量（旧流程挂在 execute/verify 步骤）——交付面 ×
+  // module-map 交集 ≥1 且无 .sillyspec/docs/** 增量 → 一行警告列未认领模块卡。advisory 不
+  // 阻断；fail-open（异常零输出）。交付面来源：调用方显式清单优先（burst 等未来调用方），
+  // 缺省从 srcDir/flow-state.yaml 的 baseline_commit 自算（deriveFlowDeliverableFace）；非 flow
+  // 变更（无 flow-state.yaml）跳过——legacy archive 已有 module-impact「更新结果」死信硬门。
+  try {
+    const face = (deliverableFiles !== null && docsIncrement !== null)
+      ? { deliverableFiles, docsIncrement }
+      : deriveFlowDeliverableFace({ cwd, srcDir })
+    const docMsg = face ? buildArchiveModuleDocAdvisory({ specBase, ...face }) : null
+    if (docMsg) console.warn(docMsg)
+  } catch { /* advisory fail-open：任何异常不碰归档链 */ }
   // ── 归档收口（2026-09-14-change-ownership-guards task-03 / FR-02 / D-002@v1）──
   // worktree 有未 apply 交付面 → 归档阻断：归档会注销 change + 清理 worktree（目录/分支/meta），
   // 交付物失去进主仓通道，形成「归档完成但交付物未进主仓」悬空态（troubleshooting §65 事件①
@@ -630,28 +756,28 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
   try {
     const { WorktreeManager } = await import('../worktree.js')
     const wmGate = new WorktreeManager({ cwd })
-    const gateMeta = wmGate.getMeta(archiveChangeName)
+    const gateMeta = wmGate.getMeta(changeName)
     if (gateMeta
       && gateMeta.mode !== 'in-place-fallback'
       && gateMeta.mode !== 'native-worktree'
       && gateMeta.worktreePath
       && existsSync(gateMeta.worktreePath)) {
       const { applyWorktree } = await import('../worktree-apply.js')
-      const checkApply = applyWorktree(archiveChangeName, { cwd, checkOnly: true })
+      const checkApply = applyWorktree(changeName, { cwd, checkOnly: true })
       const face = (checkApply && Array.isArray(checkApply.changedFiles)) ? checkApply.changedFiles : []
       if (face.length > 0) {
         const facePreview = `${face.slice(0, 5).join('、')}${face.length > 5 ? ' 等' : ''}`
-        if (!gateOpts.skipApply) {
+        if (!skipApply) {
           console.error(`❌ 归档失败：worktree 存在未 apply 的交付面（${face.length} 个文件：${facePreview}）`)
           console.error(`   归档会清理 worktree（目录+分支+meta），交付物将失去进主仓的通道，形成「归档完成但交付物未进主仓」悬空态。`)
-          console.error(`   先 apply 再归档: sillyspec worktree apply ${archiveChangeName}`)
+          console.error(`   先 apply 再归档: sillyspec worktree apply ${changeName}`)
           console.error(`   确认无需 apply（交付面已由其他会话落地/纯探索性变更等）: sillyspec run archive --done --confirm --skip-apply（显式跳过并留痕归档记录）`)
           process.exit(1)
         }
         console.warn(`⚠️  已按 --skip-apply 跳过未 apply 交付面检查（${face.length} 个文件未确认落地主仓：${facePreview}）——留痕归档记录`)
         writeFileSync(join(srcDir, 'skip-apply.record.json'), JSON.stringify({
           schemaVersion: 1,
-          change: archiveChangeName,
+          change: changeName,
           flag: '--skip-apply',
           skippedAt: new Date().toISOString(),
           deliverableCount: face.length,
@@ -667,7 +793,9 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
   }
   // 移动前硬校验：变更包必须含 plan.md，否则不该归档。
   // 在移动前阻断（而非移动后），目录尚未动，用户可直接修复后重试。
-  if (!existsSync(join(srcDir, 'plan.md'))) {
+  // skipPlanCheck（R7 切片二 / task-03 flow 轻量工件面）：flow-state 在场的 thin change 无
+  // plan.md（轻量工件面四件套），flow done 归档子步传 true 旁路；既有 archive 流程缺省 false 零变化。
+  if (!skipPlanCheck && !existsSync(join(srcDir, 'plan.md'))) {
     console.error(`❌ 归档失败：变更目录缺少 plan.md（${srcDir}）`)
     console.error(`   plan.md 是归档的必需产物。请先补全 plan 阶段产出再归档。`)
     process.exit(1)
@@ -705,9 +833,22 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     process.exit(1)
   }
 
+  // ── 时间线烤制（2026-09-28-archive-timeline-bake）──事件流机本位（.runtime gitignore），
+  // 归档时把合成时间线 + 原始事件副本烤进归档目录（跨机进 git）；fail-open：跳过/失败一行
+  // 注记不阻断归档。位于 rename 之后（目录归本链独占、destName 文件面完整）、窄化 git add
+  // 之前（烤制文件随 archiveNarrowedGitAdd 确定性进暂存）。
+  try {
+    const baked = await bakeArchiveTimeline({ cwd, specBase, changeName, destDir })
+    if (baked.skipped) console.log(`⏭️ 时间线烤制跳过：${baked.reason}`)
+    else if (baked.ok) console.log(`📦 时间线烤制完成：${baked.files.join('、')}（随归档包进 git）`)
+    else console.warn(`⚠️ 时间线烤制失败（不阻断归档）: ${baked.error}`)
+  } catch (e) {
+    console.warn(`⚠️ 时间线烤制异常（不阻断归档）: ${e && e.message ? e.message : e}`)
+  }
+
   // 正常路径同样走终态一致化（坑 manual-archive-desync-status-only）：标准 --done --confirm 流程
   // 中 completeStep 随后也会逐项完成，此处先收尾是幂等写同值——保证任何走出本函数的归档终态一致
-  pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
+  pm.unregisterChange(cwd, changeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
 
   // CLI 下沉 git add（坑4，FR-04）：确定性暂存归档目录 + 模块文档，不靠 step5 prompt 驱动。
   // step5 prompt 的 git add 保留作幂等兜底；POSIX 路径跨平台（git 接受正斜杠）。
@@ -745,12 +886,12 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
           // 已暂存 rename → 半归档残留；按目标目录名归属他者变更
           const m = /^\.sillyspec\/changes\/archive\/([^/]+)\//.exec(dst)
           const owner = m ? m[1] : '?'
-          if (owner !== archiveChangeName) othersResidual.push(owner)
+          if (owner !== changeName) othersResidual.push(owner)
         } else if (x === ' ' && (y === 'D' || y === 'A' || y === 'M')) {
           // 未暂存的源侧移动：源目录 D / 新位置 A——指向本变更的补暂存
           const p = dst || src
-          if (p && (p.startsWith(changesPrefix + archiveChangeName + '/')
-                    || p.startsWith(changesPrefix + 'archive/' + archiveChangeName + '/'))) {
+          if (p && (p.startsWith(changesPrefix + changeName + '/')
+                    || p.startsWith(changesPrefix + 'archive/' + changeName + '/'))) {
             minePaths.push(p)
           }
         }
@@ -773,6 +914,60 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
       }
     }
   } catch { /* 探测失败不阻断归档（advisory） */ }
+}
+
+export async function archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts = {}, gateOpts = {}) {
+  const archiveChangeName = progress.currentChange
+  if (!archiveChangeName) {
+    console.error('❌ 归档失败：未找到当前变更名（currentChange）')
+    process.exit(1)
+  }
+  const changesDir = join(specBase, 'changes')
+  const archiveDir = join(changesDir, 'archive')
+  const srcDir = join(changesDir, archiveChangeName)
+  const date = new Date().toISOString().slice(0, 10)
+  const destName = archiveDestDirName(date, archiveChangeName)
+  const destDir = join(archiveDir, destName)
+
+  if (!existsSync(srcDir)) {
+    // 幂等自愈（issue archive-stage-physical-tracking-desync）：源目录已不存在，但变更可能已被
+    // 手动 / 部分流程移到 changes/archive/ 并 commit，而 --done --confirm 从未正式跑完 → 进度 DB
+    // 卡 archive 阶段、active 列表仍列此 change。检测到已归档则回填进度（unregisterChange）并
+    // 成功返回，让收尾流程把 archive 阶段标完成，而非 exit(1) 死路（source 已移走无法重跑 move）。
+    const alreadyArchivedDir = findAlreadyArchivedDir(archiveDir, archiveChangeName)
+    if (alreadyArchivedDir) {
+      console.log(`ℹ️  源目录不存在但变更已在 archive/（${basename(alreadyArchivedDir)}），判定已归档，自愈进度 DB`)
+      // 终态一致化（坑 manual-archive-desync-status-only）：手动搬目录绕过标准归档后，本自愈路径
+      // 不能只翻 status——同时收尾 archive 阶段（steps/stages/current_stage），否则推送平台的终态
+      // 是「已归档 + 归档 0/5 + 停在 execute」的矛盾体，详情页渲染成「进度丢失」
+      pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
+      await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
+      console.log(`📦 已自愈归档：${archiveChangeName} → archive/${basename(alreadyArchivedDir)}/`)
+      return alreadyArchivedDir
+    }
+    console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
+    console.error(`   且 changes/archive/ 下未找到该变更的归档目录。若已手动归档请核对目录名；否则先补全变更产物。`)
+    process.exit(1)
+  }
+  // ── 所有权护栏（2026-09-14-change-ownership-guards task-03 / FR-01 / D-001@v1 接线点）──
+  // 归档=接管类操作（注销 change + 移目录 + 清 worktree），他人活跃 change 硬拒。判定在
+  // withMainRepoLock 锁内（handleArchiveConfirmStep 调用点），判定-执行无 TOCTOU；放行分支
+  // no-owner/takeover-stale 重写 owner=本会话（setChangeOwner 同事务刷新 last_active，心跳从
+  // 接管时刻起算）。会话标识三级解析：--session > env SILLYSPEC_SESSION_ID > anon@host（降级
+  // 时 resolveSessionIdentity 自带教学 warning）。消费 task-02 契约（assertChangeOwnership
+  // 纯读不写库），不重复实现判定语义。
+  {
+    const { session } = resolveSessionIdentity({ flagSession: gateOpts.sessionFlag || null, cwd })
+    const check = pm.assertChangeOwnership(cwd, archiveChangeName, { selfSession: session, nowMs: Date.now() })
+    if (!check.allowed) {
+      console.error(`🚫 归档失败：变更 ${archiveChangeName} 正被其他会话持有（owner: ${check.owner}，最后活跃: ${check.lastActive || '未知'}），活跃窗口 ${Math.round(check.heartbeatMs / 60000)} 分钟内拒绝归档`)
+      console.error(`   等对方会话收尾后重试（窗口过后自动接管）；确认对方已放弃且本会话应接管：先经 sillyspec worktree apply/cleanup ${archiveChangeName} --takeover 显式接管（重写 owner 留痕）再归档`)
+      process.exit(1)
+    }
+    if (check.action !== 'self') pm.setChangeOwner(cwd, archiveChangeName, session)
+  }
+  // ── 归档执行链（task-02 抽取：链体在 runArchiveChain，行为等价纯搬运）──
+  await runArchiveChain({ pm, cwd, specBase, changeName: archiveChangeName, srcDir, destDir, skipApply: Boolean(gateOpts.skipApply), skipPlanCheck: false })
 
   // 归档时清理可能残留的 worktree（自愈路径也复用，见上方 srcDir 缺失分支）。
   await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
@@ -1265,6 +1460,25 @@ export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cw
   }
   return null
 }
+/**
+ * guard.linkedChanges/linkedChangesAuto 并入 --done 显式声明（R4-S-Q 缺陷 B 纯函数核）：
+ * 持久化值 ∪ 显式值（去重保序，persisted 在前）；显式 ['none'] 语义为清空 manual 面（auto 不动）；
+ * 无变化返回原对象引用（调用点以此判「是否需要回写」）。guard 非对象原样返回。
+ */
+export function mergeGuardLinkedChanges(guard, explicitLinked, explicitAuto) {
+  if (!guard || typeof guard !== 'object') return guard
+  const cur = Array.isArray(guard.linkedChanges) ? guard.linkedChanges : []
+  const curAuto = Array.isArray(guard.linkedChangesAuto) ? guard.linkedChangesAuto : []
+  const ex = (Array.isArray(explicitLinked) ? explicitLinked : []).filter(Boolean)
+  const exAuto = (Array.isArray(explicitAuto) ? explicitAuto : []).filter(Boolean)
+  const next = ex.length === 1 && ex[0] === 'none' ? [] : [...new Set([...cur, ...ex])]
+  const nextAuto = exAuto.length === 0 ? curAuto : [...new Set([...curAuto, ...exAuto])]
+  const unchanged = next.length === cur.length && next.every((v, i) => v === cur[i])
+    && nextAuto.length === curAuto.length && nextAuto.every((v, i) => v === curAuto[i])
+  if (unchanged) return guard
+  return { ...guard, linkedChanges: next, linkedChangesAuto: nextAuto }
+}
+
 /**
  * quick 阶段完成收尾（W6 Step6b 从 completeStep 内联块抽出）：
  * 强校验 QUICKLOG 条目 + 审计（auditQuickCompletion）+ 结果摘要结构校验 + 翻状态/勾 tasks.md
@@ -1274,7 +1488,7 @@ export async function handleWorkflowPostCheck({ stageName, steps, currentIdx, cw
  * isForceBaseline/isAllowNew/platformOpts。辅助函数直接 import（safeGit/auditQuickCompletion ← shared，
  * printQuickAuditReview ← quick-audit，4 个 quicklog fns ← quicklog，unlinkSync/rmSync ← fs 静态）。
  */
-export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag = null, platformOpts, pm, quickFiles = [] }) {
+export async function handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag = null, platformOpts, pm, quickFiles = [], linkedChanges = [], linkedChangesAuto = [] }) {
   // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
   if (stageName === 'quick') {
     // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
@@ -1293,6 +1507,22 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
     } catch {}
 
+    // R4-S-Q 缺陷 B：--done 时显式 --linked-changes 并入 guard（启动持久化值 ∪ 本次显式值，
+    // 'none' 清空）再回写 sessionGuardFile。下游关账 closeQuickLinkedChanges / 资产尾蒸馏 /
+    // quicklog「关联变更」渲染全读 guard——不并入则 --done 时声明的关联被静默丢弃（R4-S-Q
+    // 实测：--linked-changes 两次都在命令行上，资产尾零触发 + 条目渲染「（无）」）。
+    // guard 缺失（brownfield）不造对象——保持 D-3 无 guard 降级语义不变。
+    try {
+      if (guard && (linkedChanges.length > 0 || linkedChangesAuto.length > 0)) {
+        const merged = mergeGuardLinkedChanges(guard, linkedChanges, linkedChangesAuto)
+        if (merged !== guard) {
+          guard = merged
+          writeAtomicSync(sessionGuardFile, JSON.stringify(guard, null, 2))
+          console.log(`🔗 --done 显式关联变更已并入 guard: ${(guard.linkedChanges ?? []).join(', ') || '（none 清空）'}`)
+        }
+      }
+    } catch { /* 并入/回写失败不拦完成，guard 内存原值兜底 */ }
+
     // 强校验 / 收尾：本会话必须有一条真实 QUICKLOG 条目（治「报 SAFE 但漏写」bug）。
     // guard 缺失（brownfield：新代码前启动的会话）不阻断——兜底补写一条记录，保住「完成必有记录」不变量。
     const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
@@ -1401,8 +1631,8 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
 
     // ── 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 对撞实证）。
+    // ① 轻量通道蒸馏尾：linked 真变更（非 quick-<hex>）→ decision-distill + fr-index（幂等）
+    //    + lite 归档（治「轻量通道零资产 + 僵尸 brainstorm 态」——autocompact 对撞实证）。
     //    挂点在门禁后（D-002 时序：防未实现设计进索引）。
     // ② 模块 changelog 机械追加：changedFiles×moduleIndex join → 边车存在才 append 一行
     //    （纯 quick 的检索面——QUICKLOG 是时间流水账，模块边车是空间索引）。
@@ -1750,6 +1980,27 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         softFiles,
       })
       console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      // ── ql 绑定行落盘（2026-09-24-fr-test-bindings task-05，fr-test-binding §3.2/D-004@v1）：
+      //    窗口测试文件（命名三信号）机械落 candidate（discovery=machine/confirmed_by=null——
+      //    gate 实测证明「跑过且过」，不证明绑定关系正确，诚实恒 candidate；确认走 tests --bind）。
+      //    fail-open：落行异常不拦收尾。──
+      try {
+        const stripAnno = (f) => String(f).replace(/（[^）]*）$/,'').trim()
+        const isTestFile = (p) => /(^|\/)(test|tests|__tests__)(\/|$)/i.test(p) || /^test_/i.test(p.slice(p.lastIndexOf('/')+1)) || /[._](test|spec)\.[^.]+$/i.test(p)
+        const testFiles = [...new Set((annotatedRealFiles || []).map(stripAnno).filter(isTestFile))]
+        if (testFiles.length > 0) {
+          const { upsertQlBindings } = await import('../test-bindings.js')
+          upsertQlBindings({
+            specBase, qlId,
+            rows: testFiles.map((f, i) => ({
+              anchor: qlId, row_id: `${changeName}:win-${i}:${f}`, tests: [f],
+              reason: 'regression', state: 'candidate', discovery: 'machine', confirmed_by: null,
+              source_change: changeName,
+            })),
+          })
+          console.log(`🔗 ql 绑定候选落盘：${testFiles.length} 行（${qlId}，candidate——确认走 sillyspec tests --bind）`)
+        }
+      } catch { /* ql 绑定落行 fail-open */ }
       // 范围快照/patch 审计级落盘（quick-359a48f1）：quicklog/patches/<qlId>.json+.patch——按
       // ql-ID 对齐 QUICKLOG 条目（平台按条目抓取），json 冗余 sessionId 供 guard 清理后记录态
       // 反查（computeQuickAudit → findQuickPatchRecord 同链）。patch 为 --done 时点全量冻结
@@ -2624,19 +2875,56 @@ export function checkKnowledgeBaselineRatchet(specBase) {
 }
 
 /**
- * 棘轮对比 + console 渲染（quick --done 与 archive 收尾共用）：over → ⚠️ 软警告（条数 +
- * 建议 knowledge classify 清单，不阻断不抛错）；tightened → 📉 单行留痕；disabled/steady
- * 零输出。自身 try/catch fail-open（R-05：棘轮误伤的兜底就是什么都不做）。
+ * 知识收件箱横幅纯函数（2026-09-23 知识可见性 quick）：待审条数 > 0 即渲染（不再基线内静默——
+ * 用户反馈「聊天过程中完全不知道有待审知识」），标题直出聊天面（前 3 条 + 余量指引），超基线
+ * 升级 ⚠️ 前缀。零条目零输出（降噪：清空即静默）。已 export 供 test/knowledge-inbox.test.mjs。
+ */
+export function buildKnowledgeInboxLines({ count = 0, baseline = null, over = false, titles = [] } = {}) {
+  if (!Number.isFinite(count) || count <= 0) return []
+  const head = over
+    ? `\n⚠️  知识收件箱：uncategorized 待审 ${count} 条，超 knowledge-baseline 基线 ${baseline}（软警告不阻断）——请转达用户审阅，别只留在文件里`
+    : `\n📚 知识收件箱：uncategorized 待审 ${count} 条——请转达用户审阅，别只留在文件里`
+  const lines = [head]
+  const shown = titles.filter(Boolean).slice(0, 3)
+  shown.forEach((t, i) => lines.push(`   ${i + 1}. ${t}`))
+  if (count > shown.length) lines.push(`   …（另 ${count - shown.length} 条，sillyspec knowledge inbox 看全文）`)
+  lines.push(`   归类：sillyspec knowledge classify --title "…" --file conventions|patterns|known-issues.md`)
+  return lines
+}
+
+/** uncategorized 待审标题清单（前 limit+1 条，供横幅与余量计算）。fail-open：读失败空集。 */
+function listUncategorizedTitles(specBase, limit = 3) {
+  try {
+    const p = join(specBase, 'knowledge', 'uncategorized.md')
+    if (!existsSync(p)) return []
+    return parseUncategorizedEntries(readFileSync(p, 'utf8').replace(/\r\n/g, '\n'))
+      .slice(0, limit + 1).map((e) => e.title)
+  } catch { return [] }
+}
+
+/**
+ * 棘轮对比 + console 渲染（quick --done 与 archive 收尾共用）：over → 收件箱横幅 ⚠️ 升级形态；
+ * 基线内但有存量 → 📚 横幅（可见性修复：不再静默）；tightened → 📉 单行留痕；零条目零输出。
+ * 自身 try/catch fail-open（R-05：棘轮误伤的兜底就是什么都不做）。
  */
 function renderKnowledgeBaselineRatchet(specBase) {
   try {
     const r = checkKnowledgeBaselineRatchet(specBase)
     if (r && r.status === 'over') {
-      console.warn(`\n⚠️  knowledge/uncategorized.md 待归类 ${r.count} 条，超 knowledge-baseline 基线 ${r.baseline}（软警告不阻断）`)
-      console.warn(`   建议跑 sillyspec knowledge classify 逐条归类（待归类清单见 knowledge/uncategorized.md），条数降后基线自动收紧。`)
-    } else if (r && r.status === 'tightened') {
+      for (const l of buildKnowledgeInboxLines({ count: r.count, baseline: r.baseline, over: true, titles: listUncategorizedTitles(specBase) })) {
+        console.warn(l)
+      }
+      return
+    }
+    if (r && r.status === 'tightened') {
       console.log(`📉 knowledge-baseline 已自动收紧：${r.baseline} → ${r.count}（uncategorized 待归类条数下降）`)
     }
+    // 可见性修复（2026-09-23 用户反馈）：基线内存量不再静默——有待审即出横幅，清空才静默
+    if (r && Number.isFinite(r.count) && r.count > 0) {
+      for (const l of buildKnowledgeInboxLines({ count: r.count, baseline: r.baseline, over: false, titles: listUncategorizedTitles(specBase) })) {
+        console.log(l)
+      }
+    }
   } catch { /* 棘轮渲染失败零副作用（fail-open，R-05） */ }
 }
 
@@ -2835,7 +3123,7 @@ 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 →
+ * lite 归档（D-004）：轻量通道（brainstorm→linked quick）变更的轻量收口——所有权 assert →
  * 命名 → rename → unregisterChange。不复用 archiveChangeDirectory 的 9 处重门（未 apply
  * 交付面等 worktree 导向，linked quick 变更无 worktree 语义会被误拦）；重件
  * （module-impact/ROADMAP/delta）明确豁免。自愈：源目录缺失但已在 archive/ 时补
@@ -2875,19 +3163,19 @@ export async function liteArchiveChange({ pm, cwd, specBase, changeName, platfor
   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 豁免）`)
+  console.log(`📦 lite 归档：${changeName} → archive/${destName}/（轻量通道轻收口：蒸馏已先行，module-impact/ROADMAP 豁免）`)
   return { archivedTo: destDir }
 }
 
 /**
- * 薄通道蒸馏尾（D-001/D-002）：quick --done 门禁过后对 linked 真变更（非 quick-<hex>）跑
+ * 轻量通道蒸馏尾（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 out = { distilled: false, frCount: 0, decisionCount: 0, archived: false, warnings: [], frFiles: [] }
   const realChanges = (linkedChanges || []).filter((c) => c && !QUICK_SID_RE.test(c))
   if (realChanges.length === 0) return out // 纯 quick：无关联真变更，零打扰
   try {
@@ -2911,14 +3199,15 @@ export async function distillLinkedChangeAssets({ pm, cwd, specBase, changeName,
       // 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 }
+          const { indexRequirements, archiveDeliverableFiles } = await import('../fr-index.js')
+          // greenfield-bootstrap：供 deliverableFiles（同 archive-distill 口径——防域路由退化 unmapped）
+          const r = indexRequirements({ changeDir, knowledgeRoot, headHash: '', deliverableFiles: archiveDeliverableFiles(changeDir) })
+          if (r && Array.isArray(r.written) && r.written.length > 0) { out.frCount += r.written.length; r.written.forEach((w) => { if (w && w.file && !out.frFiles.includes(w.file)) out.frFiles.push(w.file) }); anyDistilled = true }
         } catch (e) { out.warnings.push(`fr-index ${linked} 异常跳过：${e && e.message ? e.message : e}`) }
       }
     }
     out.distilled = anyDistilled
-    // lite 归档（蒸馏后；仅四件套容器变更——requirements.md 在场=brainstorm 承接的薄通道形态；
+    // 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
@@ -2929,7 +3218,8 @@ export async function distillLinkedChangeAssets({ pm, cwd, specBase, changeName,
       } 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 零新增命令）`)
+      const frDetail = out.frFiles.length > 0 ? `（${out.frFiles.join('、')}）` : ''
+      console.log(`📚 quick 资产尾：${out.frCount} 条 FR 入索引${frDetail}、${out.decisionCount} 条决策入 knowledge${out.archived ? '、linked 变更 lite 归档' : ''}（门禁后自动，agent 零新增命令）`)
     }
   } catch (e) {
     out.warnings.push(`蒸馏尾异常（fail-open 不拦 quick 完成）：${e && e.message ? e.message : e}`)