sillyspec 3.28.8 → 3.28.9

package/src/run/complete-handlers.js

@@ -5,7 +5,7 @@
  *   - handleArchiveConfirmStep：archive「确认归档」步骤 --confirm 门控 + 推荐文档校验
  *   - handlePlanGeneratePlanStep：plan「generate_plan」完成后动态插入 coordinator + postcheck 步骤
  *   - handleScanProjectListStep：scan step 2 完成后按项目展开 perProject 步骤（用 sanitizeProjectName/validateParsedProjects）
- *   - archiveChangeDirectory：归档移动变更目录（6 处 process.exit(1) + worktree 清理；handleArchiveConfirmStep 内部调用）
+ *   - archiveChangeDirectory：归档移动变更目录（移动前所有权硬校验 + 未 apply 交付面门（--skip-apply 留痕）+ 6 处 process.exit(1) + worktree 清理；handleArchiveConfirmStep 内部调用）
  *     srcDir 缺失时走 findAlreadyArchivedDir 幂等自愈（issue archive-stage-physical-tracking-desync）；
  *     archiveChangeDirectory + findAlreadyArchivedDir 已 export 供 test 直接 import
  *   - sanitizeProjectName / validateParsedProjects：项目名清洗 + 列表校验纯函数（handleScanProjectListStep 专用）
@@ -13,6 +13,10 @@
  * 安全锚：run.js 始终 barrel。3 handler 由 run.js import 回来；sanitizeProjectName + validateParsedProjects
  * 被 test 直接 import（run-sanitize-project-name / run-scan-project-parse），run.js barrel re-export 契约保留。
  * 4 目标 handler 无 test 直接 import；archiveChangeDirectory + findAlreadyArchivedDir 供自愈 test 直接 import，无需 barrel re-export。completeStep（Step7 搬）将把 import 行带走。
+ *   - 知识闭环收尾渲染（2026-09-14-knowledge-loop-close task-03）：归类提议（quick --done 进程内
+ *     outputText 根因 × matchKnowledge）+ knowledge-baseline 棘轮（quick/archive 双宿主）+ archive
+ *     抽审清单（近 7 天 classify 审计）；countUncategorizedEntries / checkKnowledgeBaselineRatchet /
+ *     extractQuickCauseField export 供 test/knowledge-baseline.test.mjs 直接 import（实现收拢文件尾）。
  *
  * 路径修正（相对 src/run/）：
  *   - resolveChangeDir 从 './shared.js'；renameSyncRetry 从 '../fs-atomic.js'；stageRegistry 从 '../stages/index.js'
@@ -31,12 +35,18 @@ import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletio
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
-import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult, parseFileNotes, getQuickFileNotes } from '../quicklog.js'
+import { printQuickAuditReview, runQuickTestLintGate, printQuickTestLintGate, buildGateAuditNote } from './quick-audit.js'
+import { validateQuickResult, allocateQuicklogEntry, appendQuicklogEntryWithId, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult, parseFileNotes, getQuickFileNotes, countQuicklogEntries, collectGuardReservedQuicklogIds } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 import { collectNumstatByPath } from '../scope-audit.js'
 import { recordFrictionEvent, consumeFrictionHint } from '../friction-tally.js'
+import { mergeFrictionEntrySync } from '../friction-ledger.js'
+import { resolveSessionIdentity } from '../progress.js'
+// ql-20260915-001 修复④：chunkPaths（argv 分批）供归档窄化 add / minePaths 精确补暂存用。
+// 无环：worktree-apply 静态闭包（worktree/task-review/quicklog 等）不引本文件；既有
+// withMainRepoLock 走动态 import 是归档链防环的历史形态，chunkPaths 纯函数无此约束。
+import { chunkPaths } from '../worktree-apply.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -152,13 +162,21 @@ function ownerFromReviewedFiles(reviewedFiles) {
  *
  * fail-open：卫生动作失败不抛，返回 { ok:true }。
  *
+ * 台账兜底滚动（2026-09-15-tax-governance FR-02）：删 friction tally 前读残余
+ * events[type].count（X-10：tally 结构 events:{type:{count,lastAt}}，无 counts 字段）merge
+ * 进 <runtimeRoot>/friction-ledger.json 同 change 条目并落 archivedAt——verify 收尾 consume
+ * 已滚主账，此处只兜残余（tally 缺失/全零/坏 JSON 跳过，归档照常）。走 mergeFrictionEntrySync
+ * （同步契约：既有 {ok,removed} 消费方与测试直调，拿不了 async 锁；无锁读改写并发丢失按
+ * design R-02 P3 容忍）。台账写失败 fail-soft 只反映在 ledgerAppend:false，不抛不阻断归档。
+ *
  * @param {string} runtimeRoot
  * @param {string} changeName
- * @returns {{ ok: true, removed: number }}
+ * @returns {{ ok: true, removed: number, ledgerAppend: boolean }}
  */
 export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
-  if (!runtimeRoot || !changeName || !existsSync(runtimeRoot)) return { ok: true, removed: 0 }
+  if (!runtimeRoot || !changeName || !existsSync(runtimeRoot)) return { ok: true, removed: 0, ledgerAppend: false }
   let removed = 0
+  let ledgerAppend = false
   const gone = (p, recursive = false) => {
     try {
       if (recursive) rmSync(p, { recursive: true, force: true })
@@ -174,9 +192,18 @@ export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
 
   // friction tally（friction-signal-hint FR-05）：摩擦计数随变更终态一并回收——真实变更的
   // friction-tally-<change>.json 落 runtimeRoot，变更归档/删除后无读者，残留即孤儿文件。
+  // 删前残余先滚台账（tax-governance FR-02 兜底滚动点，见函数头注释）。
   try {
     const fp = join(runtimeRoot, `friction-tally-${changeName}.json`)
-    if (existsSync(fp)) gone(fp)
+    if (existsSync(fp)) {
+      const merged = mergeFrictionEntrySync(runtimeRoot, {
+        change: changeName,
+        counts: residualFrictionCounts(fp),
+        archivedAt: new Date().toISOString(),
+      })
+      ledgerAppend = !!(merged && merged.ok && !merged.skipped)
+      gone(fp)
+    }
   } catch {}
 
   try {
@@ -231,7 +258,28 @@ export function pruneArchivedChangeRuntime(runtimeRoot, changeName) {
     }
   } catch {}
 
-  return { ok: true, removed }
+  return { ok: true, removed, ledgerAppend }
+}
+
+/**
+ * 残余摩擦计数读取（tax-governance FR-02 prune 兜底用）：tally 的 events 结构是
+ * { type: { count, lastAt } }（X-10——无 counts 字段），转成 mergeFrictionEntry 认的
+ * counts 平面映射（只收三枚举类型且 count>0，与 consumeFrictionHint 的 counts 形态一致）。
+ * 文件缺失/坏 JSON/脏型 → {}（跳过入账，归档照常）。
+ */
+function residualFrictionCounts(tallyPath) {
+  try {
+    const raw = JSON.parse(readFileSync(tallyPath, 'utf8'))
+    const events = raw && typeof raw === 'object' && raw.events && typeof raw.events === 'object' && !Array.isArray(raw.events) ? raw.events : {}
+    const counts = {}
+    for (const type of ['gate_rollback', 'verify_run_failed', 'review_rejected']) {
+      const n = Number(events[type] && events[type].count)
+      if (Number.isFinite(n) && n > 0) counts[type] = n
+    }
+    return counts
+  } catch {
+    return {}
+  }
 }
 
 /**
@@ -393,7 +441,121 @@ export function extractDoneDocTargets(content) {
   return [...targets]
 }
 
-export async function archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts = {}) {
+/**
+ * 归档 docs 侧窄化 add 的目标解析：module-impact「更新结果」done 行 token → 仓相对 POSIX 路径
+ * （ql-20260915-001 修复④，坑 archive-git-add-sweeps-parallel-docs：2026-09-14 实证归档自动
+ * git add 用目录级 pathspec .sillyspec/docs/ 把并行会话同目录未提交文件夹带进共享暂存区）。
+ *
+ * 解析规则（与 extractDoneDocTargets 的 token 形态对齐，保守宁漏勿误扫）：
+ *   - `.sillyspec/docs/...` 全路径 token → 相对 cwd 解析，存在才收
+ *   - `modules/<id>.md` 相对写法（module-impact 骨架的规范形态）→ 扫 <specBase>/docs/ 下各
+ *     project 目录的 modules/<id>.md——project 归属不猜单值，多项目同名命中各自收（仍是
+ *     确定性文件级，不回退目录级）
+ *   - 其他形态 / 仓库外（relative 出 ..） / 不存在 → 跳过
+ *
+ * 纯函数（只读 fs），export 供 test 直接 import。
+ * @param {string} cwd 仓库根
+ * @param {string} specBase .sillyspec 绝对路径
+ * @param {string[]} tokens extractDoneDocTargets 产物
+ * @returns {string[]} 仓相对 POSIX 路径（去重）
+ */
+export function resolveArchiveDocAddPaths(cwd, specBase, tokens) {
+  const out = new Set()
+  const pushIfExists = (abs) => {
+    try {
+      if (abs && existsSync(abs)) {
+        const rel = relative(cwd, abs).replace(/\\/g, '/')
+        if (rel && !rel.startsWith('..')) out.add(rel)
+      }
+    } catch { /* 单 token 解析失败跳过（不收即不误 add） */ }
+  }
+  for (const t of (Array.isArray(tokens) ? tokens : [])) {
+    if (!t || typeof t !== 'string') continue
+    const norm = String(t).replace(/\\/g, '/')
+    if (norm.startsWith('.sillyspec/docs/')) {
+      pushIfExists(resolve(cwd, norm))
+      continue
+    }
+    const m = /^modules\/(.+\.md)$/.exec(norm)
+    if (m) {
+      const docsDir = join(specBase, 'docs')
+      if (!existsSync(docsDir)) continue
+      let projEntries
+      try { projEntries = readdirSync(docsDir, { withFileTypes: true }) } catch { continue }
+      for (const proj of projEntries) {
+        if (!proj.isDirectory()) continue
+        pushIfExists(join(docsDir, proj.name, 'modules', m[1]))
+      }
+    }
+  }
+  return [...out]
+}
+
+/**
+ * 归档收尾的窄化 git add（ql-20260915-001 修复④，坑 archive-git-add-sweeps-parallel-docs）。
+ *
+ * changes 侧：本变更归档目录精确 pathspec（closeSingleQuickLinkedChange 的 :1641 先例）——
+ * 目录级 .sillyspec/changes/archive/ 会把并行会话停在 archive/ 下的未提交归档包一并扫进
+ * 共享暂存区。docs 侧：从（已移动到归档目录的）module-impact.md「## 更新结果」done 行提取
+ * 目标文档逐文件 add；提取失败（无表 / 读取异常）回退目录级 add，但前置 warning 列出将被
+ * 扫入的未提交 docs 文件（git status --porcelain -- .sillyspec/docs/ 差集——回退态无本变更
+ * 声明面，差集即全部未提交项），提示 agent 提交时改用精确 pathspec。表在且解析成功（含
+ * 空集 = 无声明文档，docs 面零 add）不回退。幂等：git add 重复执行无有害副作用。
+ *
+ * 独立函数（非内联）+ export 供 test 直接构造双变更目录场景驱动（不依赖 process.exit 的
+ * archiveChangeDirectory 主链）。
+ *
+ * @param {{ cwd: string, specBase: string, destDir: string, destName: string }} opts
+ * @returns {{ docsAdded: string[]|null, fallbackDocs: boolean }} docsAdded=null 表示走了目录级回退
+ */
+export function archiveNarrowedGitAdd({ cwd, specBase, destDir, destName }) {
+  // changes 侧：本变更归档目录精确收窄（quick 轻量归档 closeSingleQuickLinkedChange 同款）
+  safeGit(cwd, ['add', '--', `.sillyspec/changes/archive/${destName}/`])
+
+  // docs 侧：module-impact「更新结果」done 行 → 精确文件集。
+  // 三态（对齐修复④要求）：
+  //   - module-impact.md 无「## 更新结果」段 / 文件缺失 / 读取异常 → docPaths=null → 回退目录级
+  //   - 表在但无 done 行（全 skipped / 只有表头）→ 精确空集 → docs 面零 add（不回退——
+  //     本变更声明了不同步，目录级扫入他者文件才是错）
+  //   - 表在有 done 行 → 逐文件精确 add
+  let docPaths = null
+  try {
+    const impactPath = join(destDir, 'module-impact.md')
+    if (existsSync(impactPath)) {
+      const content = readFileSync(impactPath, 'utf8')
+      // 段存在性判定与 extractDoneDocTargets/extractPendingDocSyncRows 同一标题正则口径
+      if (/^#{2,3}\s*更新结果\s*$/m.test(content.replace(/\r\n/g, '\n'))) {
+        docPaths = resolveArchiveDocAddPaths(cwd, specBase, extractDoneDocTargets(content))
+      }
+    }
+  } catch (e) {
+    docPaths = null
+    console.warn(`⚠️ 归档 docs 精确 add 目标提取失败（${e && e.message ? e.message : e}）——回退目录级 .sillyspec/docs/ add`)
+  }
+  if (Array.isArray(docPaths)) {
+    for (const batch of chunkPaths(docPaths)) {
+      safeGit(cwd, ['add', '--', ...batch])
+    }
+    return { docsAdded: docPaths, fallbackDocs: false }
+  }
+
+  // 回退：目录级（旧行为），前置 warning 列将被扫入的未提交 docs 文件（unstaged/untracked 面）
+  try {
+    const raw = gitQuiet(cwd, ['status', '--porcelain', '--', '.sillyspec/docs/'], { trim: false })
+    const swept = (raw ? String(raw).split('\n') : []).filter(Boolean)
+      .filter(l => l.length > 3 && (l.slice(0, 2).includes('?') || l[1] !== ' '))
+      .map(l => l.slice(3).trim().replace(/^"|"$/g, ''))
+    if (swept.length > 0) {
+      console.warn(`⚠️ 归档 git add 回退目录级 .sillyspec/docs/（module-impact.md 无「## 更新结果」表或读取失败）——以下 ${swept.length} 个未提交 docs 文件将被扫入共享暂存区（可能含并行会话在途文件），提交时请用精确 pathspec：`)
+      for (const p of swept.slice(0, 10)) console.warn(`   - ${p}`)
+      if (swept.length > 10) console.warn(`   … 共 ${swept.length} 个（git status --porcelain -- .sillyspec/docs/ 查看全量）`)
+    }
+  } catch { /* 差集探测失败不阻断 add 本身（advisory） */ }
+  safeGit(cwd, ['add', '--', '.sillyspec/docs/'])
+  return { docsAdded: null, fallbackDocs: true }
+}
+
+export async function archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts = {}, gateOpts = {}) {
   const archiveChangeName = progress.currentChange
   if (!archiveChangeName) {
     console.error('❌ 归档失败：未找到当前变更名（currentChange）')
@@ -426,6 +588,68 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     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)
+  }
+  // ── 归档收口（2026-09-14-change-ownership-guards task-03 / FR-02 / D-002@v1）──
+  // worktree 有未 apply 交付面 → 归档阻断：归档会注销 change + 清理 worktree（目录/分支/meta），
+  // 交付物失去进主仓通道，形成「归档完成但交付物未进主仓」悬空态（troubleshooting §65 事件①
+  // 的代劳窗口放大器）。只拦不代跑（design 非目标：脏重叠场景人确认更稳）。--skip-apply 显式
+  // 跳过并留痕（控制台输出 + skip-apply.record.json 随归档包留存，可审计）。无 worktree
+  // （meta 缺失/in-place/native）或零交付面 → 零行为变化。探测用 applyWorktree checkOnly
+  // （只读零写盘，Gate 全收集不落盘、不短路）。
+  try {
+    const { WorktreeManager } = await import('../worktree.js')
+    const wmGate = new WorktreeManager({ cwd })
+    const gateMeta = wmGate.getMeta(archiveChangeName)
+    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 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) {
+          console.error(`❌ 归档失败：worktree 存在未 apply 的交付面（${face.length} 个文件：${facePreview}）`)
+          console.error(`   归档会清理 worktree（目录+分支+meta），交付物将失去进主仓的通道，形成「归档完成但交付物未进主仓」悬空态。`)
+          console.error(`   先 apply 再归档: sillyspec worktree apply ${archiveChangeName}`)
+          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,
+          flag: '--skip-apply',
+          skippedAt: new Date().toISOString(),
+          deliverableCount: face.length,
+          deliverableFiles: face,
+          note: '归档时显式跳过未 apply 交付面检查（--skip-apply）：交付物未确认进主仓，本记录随归档包留存供审计',
+        }, null, 2) + '\n')
+      }
+    }
+  } catch (e) {
+    // 探测自身异常 fail-open 留痕：归档主流程既有失败面（rename/git/清理）不叠加；正常路径
+    // 的阻断语义不受影响（无异常时 face 判定照常生效）。
+    console.warn(`⚠️  归档前未 apply 交付面探测失败（不阻断归档）: ${e && e.message ? e.message : e}`)
+  }
   // 移动前硬校验：变更包必须含 plan.md，否则不该归档。
   // 在移动前阻断（而非移动后），目录尚未动，用户可直接修复后重试。
   if (!existsSync(join(srcDir, 'plan.md'))) {
@@ -474,9 +698,12 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
   // step5 prompt 的 git add 保留作幂等兜底；POSIX 路径跨平台（git 接受正斜杠）。
   // safeGit 内部已 try-catch（返回 {value,error} 不抛），外层 try 兜底防御；失败不阻断归档
   // （目录已移动 + change 已注销），由 step5 prompt git add + agent git status 核对兜底。
+  // ql-20260915-001 修复④（坑 archive-git-add-sweeps-parallel-docs，2026-09-14 实证：目录级
+  // pathspec 把并行会话同目录未提交文件夹带进共享暂存区）：改为窄化——changes 侧只 add 本变更
+  // 归档目录 archive/<destName>/，docs 侧按 module-impact「更新结果」done 行精确文件集（提取
+  // 失败回退目录级 + 前置 warning，见 archiveNarrowedGitAdd）。
   try {
-    safeGit(cwd, ['add', '--', '.sillyspec/changes/archive/'])
-    safeGit(cwd, ['add', '--', '.sillyspec/docs/'])
+    archiveNarrowedGitAdd({ cwd, specBase, destDir, destName })
   } catch {}
 
   // ── 他者半归档残留探测（坑 archive-other-residual-rename，2026-08-21 实证）──
@@ -514,7 +741,13 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
         }
       }
       if (minePaths.length > 0) {
-        try { safeGit(cwd, ['add', '-A', '--', changesPrefix]) } catch {}
+        // ql-20260915-001 修复④：补暂存源侧移动改精确 pathspec（minePaths 已按本变更目录名
+        // 过滤，chunkPaths 分批防 Windows argv 上限）——原 add -A -- .sillyspec/changes/ 目录级
+        // 会顺带扫入并行会话在 changes/ 下的未提交文件（坑 archive-git-add-sweeps-parallel-docs
+        // 同坑不同点；git add -- <已删路径> 即暂存删除，语义等价 -A 限本变更面）
+        for (const batch of chunkPaths(minePaths)) {
+          safeGit(cwd, ['add', '--', ...batch])
+        }
         console.log(`🧾 已补暂存本变更归档的源侧移动（${minePaths.length} 项，归档成单次原子提交）`)
       }
       if (othersResidual.length > 0) {
@@ -542,7 +775,7 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
  *
  * @returns {{stageCompleted:false,currentIdx,nextPendingIdx:number}|null}
  */
-export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts = {} }) {
+export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, confirm, outputText, pm, cwd, progress, changeName, specBase, platformOpts = {}, isSkipApply = false, sessionFlag = null }) {
   if (stageName !== 'archive' || steps[currentIdx]?.name !== '确认归档') return null
   if (!confirm) {
     steps[currentIdx].status = 'pending'
@@ -584,7 +817,9 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
   // rename + 共享 index 的 git add + marker 删除 + worktree 清理），与并行会话的 apply/cleanup
   // 互踩。exit 钩子兜底：其内部 guard 失败 exit(1) 时锁也会被清（见 withMainRepoLock）。
   const { withMainRepoLock } = await import('../worktree-apply.js')
-  const archivedDir = await withMainRepoLock(cwd, changeName, 'archive-finalize', () => archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts))
+  // gateOpts（task-03）：--skip-apply（归档收口跳过留痕）+ --session（所有权会话标识）随链
+  // 透传——所有权硬校验与未 apply 交付面门都在 archiveChangeDirectory 内（即锁内）执行。
+  const archivedDir = await withMainRepoLock(cwd, changeName, 'archive-finalize', () => archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts, { skipApply: isSkipApply, sessionFlag }))
   if (archivedDir && existsSync(archivedDir)) {
     // 内存快照同步（坑 archive-progress-show-stale，2026-08-21 实证）：archiveChangeDirectory 内
     // unregisterChange 已在 DB 写 current_stage='archive'（终态一致化），但本进程 progress 是命令
@@ -620,6 +855,22 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
       }
     }
   }
+  // ── 知识闭环收尾渲染（2026-09-14-knowledge-loop-close task-03，X-006 定锚）──
+  // ① knowledge-baseline 棘轮（FR-03/R-05）：与 quick --done 收尾同款三态（超线软警告不阻断 /
+  //    降线自动收紧 / 基线缺失跳过），archive 时刻是归类清欠的另一自然卡点。
+  renderKnowledgeBaselineRatchet(specBase)
+  // ② 自动归类抽审清单：近 7 天 hits.jsonl 里 type:classify 的记录数——归类是机器提案经
+  //    classify 落地，人闸收敛到归档时抽审（R-01：错误归类 revert 的发现面）。读实现为
+  //    task-01 交付的 src/knowledge-hits.js（readKnowledgeHits 坏行容忍）；runtimeRoot 解析
+  //    与本文件既有 delta sidecar 同源（resolveRuntimeRoot，平台模式对齐）。无记录/读失败零输出。
+  try {
+    const { readKnowledgeHits } = await import('../knowledge-hits.js')
+    const classifyCount = readKnowledgeHits(resolveRuntimeRoot(platformOpts, specBase), { sinceDays: 7 })
+      .filter((h) => h && h.type === 'classify').length
+    if (classifyCount > 0) {
+      console.log(`\n🧪 本周期自动归类 ${classifyCount} 条（近 7 天 knowledge classify 审计），建议抽审：sillyspec knowledge stats`)
+    }
+  } catch { /* 抽审清单读取失败不影响归档（advisory fail-open） */ }
   return null
 }
 /**
@@ -980,7 +1231,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, 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 = [] }) {
   // quick 收尾：强校验 QUICKLOG 条目 + 翻状态 + 勾 tasks.md（CLI 接管）
   if (stageName === 'quick') {
     // §4.6 从 session guard.json 读 guard（不依赖 progress.quickGuard）。
@@ -1004,6 +1255,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
     let qlId = guard?.quicklogId || null
     const linkedChanges = Array.isArray(guard?.linkedChanges) ? guard.linkedChanges : []
+    // 机器自动关联溯源（坑 quick-single-change-auto-link）：单候选信号门控命中自动关联的
+    // 子集——归档闸消费（这类变更不触发轻量归档），显式 --linked-changes 关联不在此列
+    const linkedChangesAuto = Array.isArray(guard?.linkedChangesAuto) ? guard.linkedChangesAuto : []
     // 审计结果（仅 guard 存在时填充）。提到 if(guard) 外声明，供下方回填 QUICKLOG 文件行复用
     // review.changedFiles；brownfield 无 guard 时保持 null → 文件行不回填（降级，不报错）。
     let review = null
@@ -1059,7 +1313,13 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         // → 回到无豁免现状。
         otherSessionsDeclared: collectOtherQuickSessionDeclarations(platformOpts, specBase, changeName),
       }
-      review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
+      review = await auditQuickCompletion(cwd, mergedGuard, {
+        isConfirm: confirm,
+        // task-02（FR-03）：--no-docs 豁免 + --file-notes 覆盖率透传进门禁画像（per-process 值与
+        // 上方边界并入、下方 completeQuicklogEntry 消费同源；不传 → 纯默认画像）
+        noDocs: isNoDocs === true,
+        fileNotes: parseFileNotes(getQuickFileNotes()),
+      })
       printQuickAuditReview(review)
       if (review.status === 'blocked') {
         steps[currentIdx].status = 'pending'
@@ -1187,6 +1447,8 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
           description: guard?.taskDescription || '(补分配)',
           linkedChanges,
           allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+          // 他者 guard 预留让位（坑 ql-id-double-occupancy）：与启动分配同源
+          sessionsDir: resolveQuickSessionsDir(platformOpts, specBase),
         })
         qlId = alloc.qlId
         console.log(`📝 QUICKLOG 兜底补写: ${qlId}（guard 缺失/brownfield 会话）`)
@@ -1198,14 +1460,69 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         process.exit(1)
       }
     }
-    if (!findQuicklogEntry(specBase, gitUser, qlId)) {
-      console.error(`\n❌ quick 阶段完成校验失败：QUICKLOG 条目 ${qlId} 不存在。`)
-      console.error(`   会话期间记录被删除或从未写入。请检查 .sillyspec/quicklog/ 后重跑 --done。`)
+    // 占用校验（坑 ql-id-double-occupancy，2026-09-13 实证 007-1351 双占用）：启动预留 ql-ID
+    // 写入 guard.json 后，QUICKLOG 条目丢失/分裂窗口内并行会话可分得同一 ID。--done 落最终
+    // ID 前两级校验：
+    //   ① 盘上同 ID 条目 ≥2 → 记录已损坏，fail-closed 硬拦（不猜哪条属于本会话，手工去重后重跑）
+    //   ② 他者活跃会话 guard 仍预留同 ID → 本会话换新号完成（原 ID 让位他者，双方记录不混写）
+    const sessionsDirForClaims = resolveQuickSessionsDir(platformOpts, specBase)
+    const occupancy = countQuicklogEntries(specBase, qlId)
+    if (occupancy.count >= 2) {
+      console.error(`\n❌ QUICKLOG 条目 ${qlId} 双占用：${occupancy.count} 处命中（${occupancy.files.join('、')}）——分配竞态残留已损坏记录。`)
+      console.error(`   手工去重：编辑上述文件，同 ID 只保留属于本会话的一条（对照时间戳/任务描述），删除其余后重跑 --done。`)
       steps[currentIdx].status = 'pending'
       steps[currentIdx].completedAt = null
       if (outputText) steps[currentIdx].output = null
       process.exit(1)
     }
+    const claimants = (collectGuardReservedQuicklogIds(specBase, sessionsDirForClaims).get(qlId) || []).filter(s => s !== changeName)
+    if (claimants.length > 0) {
+      const oldId = qlId
+      try {
+        const alloc = await allocateQuicklogEntry(specBase, gitUser, {
+          description: guard?.taskDescription || '(占用换号补分配)',
+          linkedChanges,
+          allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+          sessionsDir: sessionsDirForClaims,
+        })
+        qlId = alloc.qlId
+        console.warn(`⚠️ 预留 ql-ID ${oldId} 被并行会话占用（${claimants.join('、')}）——分配竞态残留（坑 ql-id-double-occupancy）。`)
+        console.warn(`   本会话已换新号完成：${qlId}；原 ID 让位该会话（其 --done 正常落原条目），双方 QUICKLOG 记录不混写。`)
+      } catch (e) {
+        console.error(`\n❌ 占用换号失败: ${e.message}`)
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        process.exit(1)
+      }
+    }
+    // 最终 ID 回写 guard（坑 ql-id-double-occupancy 建议项）：换号/兜底分配路径下预留 ID ≠
+    // 最终 ID 时对齐 guard 记录，会话期内 hook/审计读到的不说谎。
+    if (guard && guard.quicklogId !== qlId) {
+      guard.quicklogId = qlId
+      try { writeAtomicSync(sessionGuardFile, JSON.stringify(guard, null, 2)) } catch { /* 回写失败降级：本进程内已对齐 */ }
+    }
+    // 条目缺失自愈（原硬拦改补建，坑 ql-id-double-occupancy 同族）：条目在会话期间丢失
+    // （并行 git 操作回滚未提交 QUICKLOG 等）时，用最终 ID 补建「进行中」骨架再走完成翻态
+    // ——与 guard 缺失分支同 cure（坑 platform-takeover-phantom-progress-db 分裂形态），
+    // 消「检查后重跑」的人工一轮。占用校验已在前：补建不会压到他者条目/预留。
+    if (!findQuicklogEntry(specBase, gitUser, qlId)) {
+      try {
+        await appendQuicklogEntryWithId(specBase, gitUser, qlId, {
+          description: guard?.taskDescription || '(条目丢失补建)',
+          linkedChanges,
+          allowedFiles: Array.isArray(guard?.allowedFiles) ? guard.allowedFiles : [],
+        })
+        console.warn(`⚠️ QUICKLOG 条目 ${qlId} 会话期间丢失，已按原 ID 补建骨架（并行 git 操作回滚未提交 QUICKLOG 所致，详见坑 ql-id-double-occupancy）。`)
+      } catch (e) {
+        console.error(`\n❌ quick 阶段完成校验失败：QUICKLOG 条目 ${qlId} 不存在且补建失败（${e.message}）。`)
+        console.error(`   请检查 .sillyspec/quicklog/ 后重跑 --done。`)
+        steps[currentIdx].status = 'pending'
+        steps[currentIdx].completedAt = null
+        if (outputText) steps[currentIdx].output = null
+        process.exit(1)
+      }
+    }
     // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
     // resultText 不再截断：结构化结果块（需求/根因/方案/结果）完整落盘，多行写成字段化块。
     try {
@@ -1262,6 +1579,13 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
           }
         } catch { /* 自动重锚失败退化为纯 advisory（上方 auditNote 已落盘） */ }
       }
+      // ── [gate] 分级门禁落账（FR-03，2026-09-14-quick-exit-tiered-gates task-02）：L1/L2 画像
+      // 经 buildGateAuditNote 组装单行 [gate] 注记随既有 auditNotes 通道落 QUICKLOG（L1 每文件
+      // 注记+测试增量；L2 模块文档认领+风险命中；--no-docs 豁免同通道留痕）；L0/无画像 → null
+      // 零落账。纯 advisory：不阻断完成、不改 review.status 语义（D-003）；未声明脏文件维持上方
+      // 归属切分注（⚖️/🔍）不并入文档认领判定（D-005）。
+      const gateAuditNote = buildGateAuditNote(review?.gateProfile)
+      if (gateAuditNote) auditNotes.push(gateAuditNote)
       // 归属切分注（2026-08-18 误归属修复）：窗口内未声明脏文件不进「文件：」行，但必须落盘可追溯
       // （多 agent 并发仓他者窗口改动 / 本会话漏声明均可能），防真实改动被静默挤走。
       // 软归属拆分（2026-09-10）：softFiles 中的同模块测试文件已补入文件行，不再占 ⚖️「未计入」
@@ -1327,7 +1651,7 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
           if (typeof frozenPatch === 'string' && frozenPatch) {
             const patchText = frozenPatch.endsWith('\n') ? frozenPatch : frozenPatch + '\n'
             writeFileSync(join(patchesDir, `${qlId}.patch`), patchText)
-            snapObj.patchSha256 = createHash('sha256').update(patchText, 'utf8').digest('hex')
+            snapObj.patchSha256 = createHash('sha256').update(patchText.replace(/\r\n/g, '\n'), 'utf8').digest('hex')
             snapObj.patchStatus = 'ok'
           } else if (frozenPatch === null) {
             snapObj.patchStatus = 'failed'
@@ -1348,9 +1672,31 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
     }
 
+    // ── 归类提议（2026-09-14-knowledge-loop-close task-03，FR-01/D-001@v1）──
+    // QUICKLOG 已落盘，用进程内已过四字段校验的 outputText（免读回盘）提取「根因：」拼查询串跑
+    // matchKnowledge（复用 knowledge-match 既有引擎；INDEX.md 缺失/未命中 matched:false 全链路
+    // no-op）。只渲染不自动执行：确认归类须 agent 显式跑 knowledge classify（R-01，错误归类靠
+    // archive/doctor 抽审 revert）。根因为「无，纯新增/纯样式」形态（无坑可归）或未命中时不渲染
+    // 任何提议（拿不准不写，零输出变化）。实现与口径见文件尾（函数声明提升 + B1 断言窗口约束）。
+    try {
+      const causeText = extractQuickCauseField(outputText)
+      if (causeText && !PURE_NEW_CAUSE_RE.test(causeText)) {
+        const { matchKnowledge } = await import('../knowledge-match.js')
+        const km = matchKnowledge(join(specBase, 'knowledge'), causeText)
+        if (km && km.matched && Array.isArray(km.entries) && km.entries.length > 0) {
+          const hit = km.entries[0]
+          const target = hit.anchor ? `${hit.file}#${hit.anchor}` : hit.file
+          console.log(`\n📚 待归类提议：${qlId} 根因疑似命中 ${target}`)
+          console.log(`   确认归类跑：sillyspec knowledge classify --ql ${qlId} --file ${hit.file}`)
+        }
+      }
+    } catch { /* 提议渲染失败零副作用（advisory fail-open，不阻断 --done 收尾） */ }
+
     // 轻量归档任务已全勾选的关联真实变更
     try {
-      const closeResult = await closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges, platformOpts })
+      // quickSessionName/sessionFlag（task-03 / FR-01）：quick 轻量归档链所有权校验入参——
+      // quick 会话标识（changeName=quick-<hex>，三级解析第三层）+ --session 显式标识。
+      const closeResult = await closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges, linkedChangesAuto, platformOpts, quickSessionName: changeName, sessionFlag })
       if (closeResult.closed.length > 0) {
         console.log(`📦 已自动归档 ${closeResult.closed.length} 个关联变更：${closeResult.closed.join(', ')}`)
       }
@@ -1392,6 +1738,11 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         console.warn(`⚠️ 注销 quick 会话 changes 行失败（不阻断完成）: ${e.message}`)
       }
     }
+
+    // ── knowledge-baseline 棘轮（2026-09-14-knowledge-loop-close task-03，FR-03/R-05）──
+    // uncategorized 待归类条数对比基线：超线 ⚠️ 软警告（不阻断不抛错）、降线自动收紧写回、
+    // 基线文件缺失 = 未启用直接跳过（存量仓零迁移）。实现收拢文件尾（B1 断言窗口约束同上）。
+    renderKnowledgeBaselineRatchet(specBase)
   }
 
   return null
@@ -1491,15 +1842,27 @@ const QUICK_CLOSE_ACTIVITY_WINDOW_MS = 60 * 60 * 1000
  * @param {string} opts.specBase
  * @param {string[]} [opts.linkedChanges]
  * @param {Object} [opts.platformOpts]
+ * @param {string|null} [opts.quickSessionName] quick 会话名（quick-<hex>，所有权三级标识第三层）
+ * @param {string|null} [opts.sessionFlag] --session 显式会话标识（所有权三级标识最高层）
  * @returns {Promise<{closed:string[], skipped:{name:string,reason:string}[]}>}
  */
-export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges = [], platformOpts = {} }) {
+export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges = [], linkedChangesAuto = [], platformOpts = {}, quickSessionName = null, sessionFlag = null }) {
   const closed = []
   const skipped = []
   // 只处理真实变更，跳过 quick 会话 sessionId
   const realChanges = linkedChanges.filter((name) => !/^quick-[0-9a-f]{8}$/.test(name))
   for (const changeName of realChanges) {
     try {
+      // 止血（坑 quick-single-change-auto-link 配套）：仅被机器自动关联（单候选信号门控命中
+      // 的猜测，非 --linked-changes 显式协作声明）的变更不触发轻量归档——归档是破坏性动作，
+      // 机器猜的关联声明不够格；显式关联的僵尸清理通道（D-002@v1/v2 契约）不受影响。
+      if (linkedChangesAuto.includes(changeName)) {
+        skipped.push({
+          name: changeName,
+          reason: '自动关联（信号命中机器猜测，非显式协作声明），不触发自动归档——确要归档请走原流程收尾（sillyspec progress show）',
+        })
+        continue
+      }
       if (typeof pm.getChangeStage !== 'function') {
         skipped.push({ name: changeName, reason: '进度库接口缺失（getChangeStage），无法判定流程阶段，不自动归档' })
         continue
@@ -1548,6 +1911,39 @@ export async function closeQuickLinkedChanges({ pm, cwd, specBase, linkedChanges
         skipped.push({ name: changeName, reason: 'tasks.md 未全勾选或不存在' })
         continue
       }
+      // ── 所有权护栏（2026-09-14-change-ownership-guards task-03 / FR-01 接线点）──
+      // closeSingleQuickLinkedChange 归档移动前对 linked full-flow change 校验（消费 task-02
+      // 契约，不重复实现）：他人活跃 → 跳过该 linked 归档 + warning（不炸 quick --done）；无主/
+      // 窗口外/本会话自有 → 放行，接管分支重写 owner。quick 会话标识=quick-<hex>（三级解析
+      // 第三层，quickChangeName 传入）；quick 面互斥恒 self（design 非目标声明），本闸只拦
+      // full-flow change 的「他人活跃」态。pm 缺接口（旧 mock/旧进度库）fail-open 放行留痕
+      //（同 command.js claim fail-open 先例：护栏退回 no-owner 语义，不废僵尸逃生通道）；
+      // 校验自身异常则跳过该归档（fail-closed 不误归档）。
+      if (typeof pm.assertChangeOwnership !== 'function') {
+        console.warn(`⚠️ 进度库接口缺失（assertChangeOwnership），关联变更 ${changeName} 跳过所有权校验（fail-open 放行）`)
+      } else {
+        try {
+          const { session } = resolveSessionIdentity({
+            flagSession: sessionFlag || null,
+            quickChangeName: quickSessionName || null,
+            cwd,
+          })
+          const ownCheck = pm.assertChangeOwnership(cwd, changeName, { selfSession: session, nowMs: Date.now() })
+          if (!ownCheck.allowed) {
+            skipped.push({
+              name: changeName,
+              reason: `变更正被其他会话持有（owner: ${ownCheck.owner}，最后活跃: ${ownCheck.lastActive || '未知'}），跳过自动归档——由其会话自行收尾（sillyspec progress show 查看进度）`,
+            })
+            continue
+          }
+          if (ownCheck.action !== 'self') {
+            try { pm.setChangeOwner(cwd, changeName, session) } catch { /* 接管写库失败不阻断放行语义 */ }
+          }
+        } catch (e) {
+          skipped.push({ name: changeName, reason: `所有权校验异常（${e && e.message ? e.message : e}），跳过自动归档` })
+          continue
+        }
+      }
       const result = await closeSingleQuickLinkedChange({ pm, cwd, specBase, changeName, platformOpts })
       if (result.closed) {
         closed.push(changeName)
@@ -1991,3 +2387,97 @@ function attachQuickLineCounts({ cwd, realFiles, softFiles, review, auditFiles,
   return { annotatedRealFiles, annotatedSoftFiles, fmtLineCounts }
 }
 
+// ── 知识闭环收尾渲染（2026-09-14-knowledge-loop-close task-03，FR-01/FR-03）──
+// 放文件尾（函数声明提升，同 attachQuickLineCounts 先例）：归类提议/棘轮渲染挂在 quick --done 与
+// archive 收尾两处，插码位置受 concurrent-preflight-hooks.test.mjs B1 源码文本级断言窗口约束
+// （detectConcurrentChanges ±[200,600] 字符内禁 process.exit、须保 try/catch）——实现收拢在此，
+// 调用点只留小段调用，避免大段内联把断言锚推出窗口。全段 fail-open：任何异常只吞不阻断收尾。
+
+/**
+ * 数 knowledge/uncategorized.md 待归类条目数。计数正则与 `sillyspec knowledge` validate 同款
+ * /^#{2,3}\s+\S/gm（X-010 口径对齐，防双数字打架）；文件缺失算 0（未启用知识库的仓不警告）。
+ * 已 export 供 test/knowledge-baseline.test.mjs 直接断言计数口径。
+ */
+export function countUncategorizedEntries(knowledgeDir) {
+  const uncPath = join(knowledgeDir, 'uncategorized.md')
+  if (!existsSync(uncPath)) return 0
+  try {
+    return (readFileSync(uncPath, 'utf8').match(/^#{2,3}\s+\S/gm) || []).length
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * 读 .sillyspec/knowledge-baseline 单整数（uncategorized 条数上限，语义/读写形态对齐
+ * docs-check-baseline：trim 后 parseInt，非负整数才有效）。缺失/不可解析 → null（未启用）。
+ */
+function readKnowledgeBaseline(specBase) {
+  try {
+    const baselinePath = join(specBase, 'knowledge-baseline')
+    if (!existsSync(baselinePath)) return null
+    const n = parseInt(readFileSync(baselinePath, 'utf8').trim(), 10)
+    return Number.isInteger(n) && n >= 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * knowledge-baseline 棘轮三态对比（FR-03/R-05）：
+ *   - 基线缺失 → { status:'disabled' }（未启用，调用方零输出零写盘）
+ *   - count > baseline → { status:'over' }（软警告，不阻断——棘轮起步只警告）
+ *   - count < baseline → 自动收紧：基线文件改写为当前值（writeAtomicSync，Windows 兼容），
+ *     → { status:'tightened' }；写盘失败降级 steady（下次收尾再试，不谎报收紧）
+ *   - count == baseline → { status:'steady' }
+ * 已 export 供 test/knowledge-baseline.test.mjs 断言三态与收紧副作用。
+ */
+export function checkKnowledgeBaselineRatchet(specBase) {
+  const baseline = readKnowledgeBaseline(specBase)
+  const count = countUncategorizedEntries(join(specBase, 'knowledge'))
+  if (baseline === null) return { status: 'disabled', count, baseline: null }
+  if (count > baseline) return { status: 'over', count, baseline }
+  if (count < baseline) {
+    try {
+      writeAtomicSync(join(specBase, 'knowledge-baseline'), `${count}\n`)
+      return { status: 'tightened', count, baseline }
+    } catch {
+      return { status: 'steady', count, baseline }
+    }
+  }
+  return { status: 'steady', count, baseline }
+}
+
+/**
+ * 棘轮对比 + console 渲染（quick --done 与 archive 收尾共用）：over → ⚠️ 软警告（条数 +
+ * 建议 knowledge classify 清单，不阻断不抛错）；tightened → 📉 单行留痕；disabled/steady
+ * 零输出。自身 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') {
+      console.log(`📉 knowledge-baseline 已自动收紧：${r.baseline} → ${r.count}（uncategorized 待归类条数下降）`)
+    }
+  } catch { /* 棘轮渲染失败零副作用（fail-open，R-05） */ }
+}
+
+/** 根因「无，纯新增/纯样式」形态：无坑可归，归类提议不渲染（拿不准不写）。 */
+const PURE_NEW_CAUSE_RE = /^无(?:[，,].*)?$/
+
+/**
+ * 从 quick --done 四字段 outputText 提取「根因：」字段值（归类提议的查询串来源；进程内已过
+ * validateQuickResult 校验，免读回盘）。多行字段块与单行压缩形态都支持；根因块内嵌套子字段
+ * 列表行（- 现象：/- 根因： 等 D-004@v1 合法形态）随正文保留——只是匹配查询串，多文本无害。
+ * 提取失败/无根因字段返回 ''。已 export 供测试断言提取口径。
+ */
+export function extractQuickCauseField(outputText) {
+  const text = String(outputText || '')
+  const m = text.match(/根因\s*[：:]\s*([\s\S]*?)(?=(?:^|\n|\s)(?:方案|结果)\s*[：:]|$)/)
+  if (!m) return ''
+  return m[1].replace(/\s+/g, ' ').trim()
+}
+