sillyspec 3.29.3 → 3.29.5

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'
@@ -1265,6 +1265,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 +1293,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 +1312,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'
@@ -1399,6 +1434,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 +1996,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 +2021,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 +2064,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 +2098,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 +2111,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 +2866,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/complete.js

@@ -120,7 +120,7 @@ export function synthesizeStepOutput({ stageName, stepName, cwd }) {
 }
 
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [] } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [], linkedChanges = [], linkedChangesAuto = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
   // 与 prompt.js resolvePromptSpecBase 同序：--done 收尾的 user-inputs.md/超长 artifact 落盘
   // 必须与 prompt 渲染同一根，否则写进 worktree 副本目录、随 cleanup 整目录删除。
@@ -619,8 +619,11 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     }
     // quick 收尾（W6 Step6b 抽至 complete-handlers.js handleQuickStageCompletion）；
     // isNoDocs（task-02）--no-docs 豁免随链透传进 auditQuickCompletion options；
-    // sessionFlag（task-03）--session 随链透传进 quick 轻量归档链所有权校验
-    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag, platformOpts, pm, quickFiles })
+    // sessionFlag（task-03）--session 随链透传进 quick 轻量归档链所有权校验；
+    // linkedChanges/linkedChangesAuto（R4-S-Q 缺陷 B）：--done 时显式 --linked-changes 随链透传——
+    // 完成侧 guard 从落盘文件读，不接 opts 会静默丢弃 --done 时声明的关联（蒸馏尾/quicklog
+    // 关联变更行/closeQuickLinkedChanges 三处消费同断）
+    await handleQuickStageCompletion({ stageName, steps, currentIdx, cwd, progress, changeName, specBase, outputText, confirm, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, sessionFlag, platformOpts, pm, quickFiles, linkedChanges, linkedChangesAuto })
 
     // ── reopen --done 回填（坑 brainstorm-reopen-step-state-desync）──
     // nextPendingIdx === -1 且无 waiting，说明要进阶段完成分支。此时若存在 stale 步骤

package/src/run/gate-snapshot.js

@@ -389,15 +389,21 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
     // 两份都变于祖先且互不相等（真双写分叉）→ 显式警告 + 取 cwd（主仓直写=本会话最新编辑位约定）。
     // 行尾归一（坑 autocrlf-byte-misjudge）：本机 autocrlf=true 时快照 checkout 是 CRLF、
     // 工作区文件常是 LF——字节直比会误判「两边都改」。比较一律 CRLF→LF 归一后做。
+    // 对称 trim（坑 gate-snapshot-ancestor-trim，2026-09-20 taskcard-yaml-hardgate verify 实证）：
+    // git() 助手对全部输出 .trim()（rev-parse 场景需要），git show 的祖先内容因此被剥掉尾换行——
+    // 与磁盘读取（仅 CRLF 归一）不对称，已存在文件恒 anc!==cwd 误判「双写分叉」取主仓旧版，
+    // worktree 交付的修改进不了 verify 门快照→门假红（新文件因主仓不存在幸免）。比较三侧
+    // 统一 normalizeEol+trim 同口径——首尾空白差异不参与分叉判定（语义修改不会只差首尾空白）。
     const normalizeEol = (buf) => String(buf).replace(/\r\n/g, '\n')
+    const cmpText = (t) => normalizeEol(t).trim()
     const headFileContent = (rel) => {
       if (mergeBase) {
         try {
           const anc = git(cwd, ['show', `${mergeBase}:${rel}`])
-          if (typeof anc === 'string') return normalizeEol(anc)
+          if (typeof anc === 'string') return cmpText(anc)
         } catch { /* 祖先无此文件（新增文件）→ 落到快照 HEAD 口径 */ }
       }
-      try { return normalizeEol(readFileSync(join(snapshotRoot, rel))) } catch { return null }
+      try { return cmpText(readFileSync(join(snapshotRoot, rel))) } catch { return null }
     }
     for (const f of files) {
       const isSillyspecRuntime = typeof f === 'string' && (f.startsWith('.sillyspec/.runtime/') || f.startsWith('.sillyspec/quicklog/') || f === '.sillyspec/local.yaml' || f === '.sillyspec/.sillyspec-platform.json')
@@ -407,8 +413,8 @@ export function createGateSnapshot({ cwd, files, sourceRoot = null, skipImportSm
         const wtPath = join(sourceRoot, f), cwdPath = join(cwd, f)
         if (existsSync(wtPath) && existsSync(cwdPath)) {
           let wtText = null, cwdText = null
-          try { wtText = normalizeEol(readFileSync(wtPath)) } catch { /* 读失败不介入 */ }
-          try { cwdText = normalizeEol(readFileSync(cwdPath)) } catch { /* 读失败不介入 */ }
+          try { wtText = cmpText(readFileSync(wtPath)) } catch { /* 读失败不介入 */ }
+          try { cwdText = cmpText(readFileSync(cwdPath)) } catch { /* 读失败不介入 */ }
           if (wtText !== null && cwdText !== null && wtText !== cwdText) {
             const base = headFileContent(f)
             const wtDiff = base === null || wtText !== base