sillyspec 3.31.0 → 3.32.1

package/src/run/command.js

@@ -29,7 +29,7 @@ import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, completeStepBurst, skipStep, waitStep, continueStep, synthesizeStepOutput } from './complete.js'
 import { runStage } from './stage.js'
-import { sanitizeDesc } from '../quicklog.js'
+import { sanitizeDesc, deriveChangeTitle } from '../quicklog.js'
 import { ProgressManager, resolveSessionIdentity } from '../progress.js'
 import { validateChangeExists, checkTransition } from '../stage-contract.js'
 import { READONLY_AUXILIARY_STAGES } from '../constants.js'
@@ -215,6 +215,22 @@ export async function ensureStageSteps(progress, stageName, cwd, specDir = null)
  * run <stage> --help/-h 的用法帮助（runCommand 内 --help 短路调用）。
  * 只打印不落盘：帮助查询不该有副作用（建会话/写 QUICKLOG）。
  */
+/**
+ * 只读空态引导文案（2026-10-05-status-empty-guide 首创；2026-10-06-status-multi-active-list
+ * 抽出单一源——库不在场前置门与 read 后空分支共用一份，防两处文案漂移）。静态文案——引用
+ * 通用命令形态而非本仓状态（空态定义即无数据可读）。可照抄实例（2026-10-05-input-teach-copyable）：
+ * 引号内换行合法，extractSuccessCriteria 行级 trim 容忍缩进，带缩进照抄亦过门。
+ */
+function emitReadonlyEmptyGuide() {
+  console.log('ℹ️ 未找到进度数据（只读查询不建变更）')
+  console.log('   → 可开始轻量变更（--input 引号内换行合法，下例可照抄）：')
+  console.log('     sillyspec flow start --change <YYYY-MM-DD-名> --input "<动机与背景>')
+  console.log('')
+  console.log('     成功标准：')
+  console.log('     - <可验证标准>"')
+  console.log('   → 需求不明可 sillyspec run brainstorm --change <名> 先探索')
+}
+
 function printStageUsage(stageName) {
   const stage = stageRegistry[stageName]
   console.log(`
@@ -833,7 +849,11 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
             quickSessionId = recent
             quickFallbackUsed = true
           } else {
-            console.log('   本仓无近期 quick 会话记录（current marker 与 quick-sessions 均空）——新工作请走轻量变更：sillyspec flow start --change <名> --input "<动机与背景；随后独立一行『成功标准：』；再每行一条『- <可验证标准>』>"')
+            console.log('   本仓无近期 quick 会话记录（current marker 与 quick-sessions 均空）——新工作请走轻量变更（--input 引号内换行合法，可照抄）：')
+            console.log('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<动机与背景>')
+            console.log('')
+            console.log('   成功标准：')
+            console.log('   - <可验证标准>"')
             process.exit(0)
           }
         } else {
@@ -1111,9 +1131,23 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // 只读辅助阶段的写意图 flag 清单（下方两处只读短路共用：库不在场前置门 + read 后短路）
+  const READONLY_WRITE_ACTIONS = ['--cleanup-remnant', '--align-execute-progress', '--done', '--skip', '--reset', '--reopen', '--wait', '--continue']
+
+  // 只读前置门（2026-10-06-status-multi-active-list）：库文件不在场时不得进入 pm.read()——
+  // read() 无显式 --change 先走 listChanges→_ensureDB，会凭空新建空库（只读承诺破防，实测）；
+  // 空库撞残留 schema-version 戳无表可查，首个 SELECT 直接崩（no such table: changes）。
+  // 库不在场=字面意义的零进度：与零活跃同款空态引导 + exit 0，零落盘。
+  if (READONLY_AUXILIARY_STAGES.includes(stageName) && !flags.some(f => READONLY_WRITE_ACTIONS.includes(f))
+      && !existsSync(pm._runtimePath(cwd, 'sillyspec.db'))) {
+    emitReadonlyEmptyGuide()
+    process.exit(0)
+  }
+
   let progress = pm.read(cwd, changeName)
 
-  // task-03 (D-005@v2 / FR-04): READONLY_AUXILIARY_STAGES（status/doctor）查询只读短路。
+  // task-03 (D-005@v2 / FR-04): READONLY_AUXILIARY_STAGES（status；doctor 已于 2026-09-09-doctor-noai
+  // 移出——阶段形态走状态机，顶层 doctor 只读语义由 index.js case 头部分流保真）查询只读短路。
   // 无显式写 flag 时在 registerChange / ensureStageSteps 之前拦截，零副作用：
   //   - 目标 progress 不存在 → 提示「只读查询不建变更」exit 0（不 initChange、不建 default 行，治 8b）
   //   - 目标 progress 存在 → 只读展示，不 seed steps、不刷新 lastActive、不 registerChange
@@ -1121,10 +1155,25 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 显式写意图不短路：doctor 写操作 flag（--cleanup-remnant / --align-execute-progress）与
   // 步骤动作 flag（--done/--skip/--reset/--reopen/--wait/--continue）走原写路径；--status 本身
   // 是只读查询，纳入短路。--fix 是 worktree doctor 的 flag 不在此列（design.md Phase 4）。
-  const READONLY_WRITE_ACTIONS = ['--cleanup-remnant', '--align-execute-progress', '--done', '--skip', '--reset', '--reopen', '--wait', '--continue']
   if (READONLY_AUXILIARY_STAGES.includes(stageName) && !flags.some(f => READONLY_WRITE_ACTIONS.includes(f))) {
     if (!progress) {
-      console.log('ℹ️ 未找到进度数据（只读查询不建变更）')
+      // 多活跃分流（2026-10-06-status-multi-active-list）：read() 无显式 --change 在 ≥2 活跃
+      // 时同样返回 null——「有数据但需要点名」被空态文案一律误报成「无数据」（本仓实测
+      // 10 行 active、2 个目录待收口却被告知未找到）。前置门保证走到这库必在场，listChanges
+      // 纯读；显式 --change 未命中仍走空态引导（点名失败与未点名歧义是两件事）。
+      let activeChanges = []
+      try { activeChanges = pm.listChanges(cwd) || [] } catch { activeChanges = [] }
+      if (!changeName && activeChanges.length >= 2) {
+        console.log(`ℹ️ 进度数据存在，但有 ${activeChanges.length} 个活跃变更（未指定 --change，无法确定展示哪个）：`)
+        for (const name of activeChanges) {
+          // DB 行与目录是两个真相层：目录缺失的幽灵行如实标注（清幽灵走既有 doctor --cleanup-remnant）
+          console.log(`   - ${name}${existsSync(pm._changePath(cwd, name)) ? '' : '（本地无目录）'}`)
+        }
+        console.log(`   → 指定查看其一：sillyspec status --change ${activeChanges[0]}`)
+        console.log('   → 恢复面：sillyspec flow status --change <名>')
+        process.exit(0)
+      }
+      emitReadonlyEmptyGuide()
       process.exit(0)
     }
     // 只读展示路径：复用阶段定义渲染当前步骤 prompt（outputStep 对 status/doctor 纯只读），
@@ -1225,10 +1274,11 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     // 如果指定了变更名或有变更目录，自动初始化变更的 progress
     const autoChange = changeName || resolveChangeNameAuto(cwd, specRoot)
     if (autoChange) {
-      // 创建时即写 title（与 name/KEY 同时落 db）：--input 需求描述 sanitizeDesc 优先，无则用 name 兜底。
+      // 创建时即写 title（与 name/KEY 同时落 db）：--input 首行推导 deriveChangeTitle（≤50 字，
+      // 用户需求 2026-09-29）优先，长输入兜底 sanitizeDesc 压行，无则用 name 兜底。
       // proposal 还没写、无权威标题来源，这是临时值；brainstorm/plan 完成 proposal/design 落盘后由
       // complete.js 通用完成路径 deriveTitleFromLinkedChange 刷新为真实 # 标题（与 quick 启动 title 同源）。
-      progress = pm.initChange(cwd, autoChange, { title: inputText ? sanitizeDesc(inputText) : autoChange })
+      progress = pm.initChange(cwd, autoChange, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoChange })
     } else if (isAuxiliary) {
       let autoName = changeName || resolveChangeNameAuto(cwd, specRoot) || 'default'
       // archive 特例：归档后变更从活跃列表排除（listChanges WHERE status='active'），
@@ -1255,7 +1305,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       changeName = autoName
       if (!progress) {
         // auxiliary 创建也写 title（--input 优先 / name 兜底），同上完整流程语义。
-        progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
+        progress = pm.initChange(cwd, autoName, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
         // initChange 可能因 project 表为空返回 null
         if (!progress) {
           progress = { currentStage: stageName, stages: {}, lastActive: new Date().toLocaleString('zh-CN', { hour12: false }), project: '' }
@@ -1287,7 +1337,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         console.log(`  提示：可以用 --change <名称> 指定自定义变更名`)
         console.log(`  或事后重命名：sillyspec change-rename ${autoName} <新名称>`)
         // brainstorm 自动创建变更也写 title（--input 需求描述优先 / 自动名兜底），proposal 落盘后刷新。
-        progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
+        progress = pm.initChange(cwd, autoName, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
         changeName = autoName
       } else if (stageName === 'auto') {
         // auto 零活跃建变更（2026-09-08-auto-driver D-003@v1，Grill P1-②）：SKILL 启动命令即
@@ -1303,7 +1353,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
         console.log(`🔄 auto 模式自动创建变更：${autoName}（可用 --change 指定名称，或事后 change-rename）`)
-        progress = pm.initChange(cwd, autoName, { title: inputText ? sanitizeDesc(inputText) : autoName })
+        progress = pm.initChange(cwd, autoName, { title: inputText ? (deriveChangeTitle(inputText) || sanitizeDesc(inputText)) : autoName })
         changeName = autoName
       } else {
         console.error('❌ 未找到进度数据，请先运行 sillyspec init 或指定 --change <变更名>')
@@ -2010,8 +2060,11 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     const classification = classifyChange({ description: inputText || '', explicitMode, localConfig })
     if (classification.mode === 'quick') {
       console.log(`📊 auto 模式分类：${classification.reason} 判为小变更`)
-      console.log(`   小变更请走轻量变更（quick 通道已退役，v3.31.0 起拒绝新会话）：`)
-      console.log(`   sillyspec flow start --change <名> --input "<动机与背景；随后独立一行『成功标准：』；再每行一条『- <可验证标准>』>"`)
+      console.log(`   小变更请走轻量变更（quick 通道已退役，v3.30.0 起拒绝新会话；--input 引号内换行合法，可照抄）：`)
+      console.log('   sillyspec flow start --change <YYYY-MM-DD-名> --input "<动机与背景>')
+      console.log('')
+      console.log('   成功标准：')
+      console.log('   - <可验证标准>"')
       return
     }
     console.log(`📊 auto 模式分类：${classification.mode}（${classification.reason}）`)

package/src/run/complete-handlers.js

@@ -410,6 +410,60 @@ export function extractPendingDocSyncRows(content) {
   return rows
 }
 
+/**
+ * module-impact.md pending 死信一键回填（2026-10-07-flow-friction-batch3 task-04）：verify 硬拦
+ * 「更新结果」表 pending/待办行后，agent 实测写一次性 node 脚本批量回填——CLI 化。语义对齐
+ * 文件内规则行「确定不同步的行改 skipped 并在操作列写明原因」：状态列 pending/待办→skipped，
+ * --reason 追加进操作列（`——skipped：<reason>`）；done/其余状态行与表外内容逐字不动；幂等
+ * （无 pending 行时零写盘）。与 extractPendingDocSyncRows 同一节段解析口径（不二算规则集）。
+ * @param {string} mdPath module-impact.md 路径
+ * @param {{ reason?: string }} opts reason 追加进操作列的一句话原因（缺省只翻状态）
+ * @returns {{ filled: number, ok: boolean, error?: string }} filled=回填行数；ok=false 时 error 带原因
+ */
+export function fillModuleImpactSkipped(mdPath, { reason = '' } = {}) {
+  let content
+  try { content = readFileSync(mdPath, 'utf8') } catch (e) {
+    return { filled: 0, ok: false, error: `module-impact.md 不可读：${mdPath}（${e && e.message ? e.message : e}）` }
+  }
+  const normalized = content.replace(/\r\n/g, '\n')
+  const sectionStart = normalized.search(/^#{2,3}\s*更新结果\s*$/m)
+  if (sectionStart === -1) return { filled: 0, ok: false, error: 'module-impact.md 无「更新结果」小节——无可回填行（先核对文件是否为骨架未填形态）' }
+  const titleMatch = normalized.slice(sectionStart).match(/^#{2,3}\s*更新结果\s*$/m)
+  const bodyStart = sectionStart + titleMatch[0].length
+  const afterTitle = normalized.slice(bodyStart)
+  const nextSection = afterTitle.search(/^#{1,3}\s/m)
+  const section = nextSection === -1 ? afterTitle : afterTitle.slice(0, nextSection)
+  const sectionEnd = nextSection === -1 ? normalized.length : bodyStart + nextSection
+  const PENDING_STATUSES = new Set(['pending', '待办', '未同步', 'not-done', 'todo'])
+  let filled = 0
+  const newSection = section.split('\n').map((line) => {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('|')) return line
+    const cells = trimmed.split('|').map(c => c.trim())
+    const lastCell = cells[cells.length - 1]
+    if (lastCell === '' && cells.length >= 2) cells.pop()
+    const statusCell = cells[cells.length - 1]
+    if (!statusCell || !PENDING_STATUSES.has(statusCell.toLowerCase())) return line
+    filled++
+    // 结构 | 目标 | 操作 | 状态 | → cells ['', 目标, 操作, 状态]；操作列 = 倒数第二格
+    if (cells.length >= 3 && reason) {
+      cells[cells.length - 2] = `${cells[cells.length - 2]}——skipped：${reason}`
+    }
+    cells[cells.length - 1] = 'skipped'
+    // 重拼保留「| a | b | c |」空格形态（cells[0] 是行首 | 产生的空串）；行首缩进对齐原行
+    const indent = line.slice(0, line.indexOf('|'))
+    return `${indent}| ${cells.slice(1).join(' | ')} |`
+  }).join('\n')
+  if (filled === 0) return { filled: 0, ok: true }
+  const next = normalized.slice(0, bodyStart) + newSection + normalized.slice(sectionEnd)
+  try {
+    writeFileSync(mdPath, next, 'utf8')
+    return { filled, ok: true }
+  } catch (e) {
+    return { filled: 0, ok: false, error: `回填写盘失败：${e && e.message ? e.message : e}` }
+  }
+}
+
 /**
  * 提取 module-impact.md「更新结果」表中的已完成（done）行声明的目标文档路径（债单 D-4 窄口径）。
  *
@@ -508,6 +562,47 @@ export function resolveArchiveDocAddPaths(cwd, specBase, tokens) {
   return [...out]
 }
 
+/**
+ * 归档源侧移动补暂存（坑 archive-stage-claim，2026-10-06-module-map-list-leak 收口实测发现）。
+ *
+ * safeGit 契约是返回 {value, error} 不抛错——此前调用方忽略返回值无条件打成功提示，add 失败
+ * （index.lock 竞态等）时「已补暂存 N 项」假成功、暂存面实际缺项（实测声称 1 项暂存面为空，
+ * 靠核对暂存面纪律兜住后手工补提交）。本助手逐批 add 并校验 error，失败明细返回给调用方
+ * 择路打印（fail-soft：不抛错不阻断归档链，幂等 add 重跑同值）。
+ *
+ * @param {{ cwd: string, paths: string[] }} opts paths 已按本变更目录名过滤的精确 pathspec
+ * @returns {{ ok: boolean, count: number, failures: Array<{ path: string, error: string }> }}
+ */
+export function stageArchiveSourceSideMoves({ cwd, paths }) {
+  const failures = []
+  let count = 0
+  for (const batch of chunkPaths(paths)) {
+    const r = safeGit(cwd, ['add', '--', ...batch])
+    if (r && r.error) {
+      for (const p of batch) failures.push({ path: p, error: r.error })
+    } else {
+      count += batch.length
+    }
+  }
+  return { ok: failures.length === 0, count, failures }
+}
+
+/**
+ * 补暂存结果文案（成功=既有提示逐字不变；失败=⚠️ 告警含失败路径与 error 首行 + 手工兜底指引；
+ * 空清单零文案）。独立导出供测试断言两半（返回值与文案），打印决策归调用方。
+ * @param {{ ok: boolean, count: number, failures: Array<{ path: string, error: string }> }} r
+ * @returns {string}
+ */
+export function renderStageSourceSideMovesMessage(r) {
+  if (!r || r.count === 0 && (!r.failures || r.failures.length === 0)) return ''
+  if (r.ok) return `🧾 已补暂存本变更归档的源侧移动（${r.count} 项，归档成单次原子提交）`
+  const lines = [`⚠️ 补暂存本变更归档的源侧移动失败（${r.failures.length} 个路径，成功 ${r.count} 项）——暂存面可能缺项，归档提交前请核对 git diff --cached --name-only：`]
+  for (const f of r.failures.slice(0, 10)) lines.push(`   - ${f.path}（${f.error}）`)
+  if (r.failures.length > 10) lines.push(`   … 共 ${r.failures.length} 个`)
+  lines.push(`   手工兜底：git add -- <上述路径> 后重跑收口命令（归档子步幂等续）`)
+  return lines.join('\n')
+}
+
 /**
  * 归档收尾的窄化 git add（ql-20260915-001 修复④，坑 archive-git-add-sweeps-parallel-docs）。
  *
@@ -731,6 +826,60 @@ export async function bakeArchiveTimeline({ cwd, specBase, changeName, destDir,
  *
  * @returns {Promise<void>} 失败面沿链内既有 process.exit 语义（纯搬运不改）。
  */
+/**
+ * 归档提交 pathspec 构成（2026-10-06-archive-cmd-race-and-brief：共享暂存区竞态加固）。
+ *
+ * 背景：旧实现照抄 `git diff --cached --name-status` 单元格——多 agent 共享仓下，兄弟会话/
+ * 后台同步可在「打印→执行」窗口瞬改暂存区（实测 flow-status-json 收尾：建议命令含转瞬即逝
+ * 的源侧 A 条目，照抄执行报 pathspec did not match；单会话镜像复盘命令干净=竞态即现即逝）。
+ *
+ * 构成按稳定性分级：
+ *   - src 侧（changes/<名>/ 非归档）：仅取 HEAD 树在册路径——HEAD 不可变，不受暂存区竞态
+ *     影响；rename src / 删除 D 恒在册，转瞬即逝的源侧 A 条目恒不在册（天然滤幽灵）。
+ *   - dst 侧：本变更专属归档目录单条 pathspec（archive/<名>/ 与窄化 add 同一专属前提），
+ *     目录在场即匹配，条目级抖动无感。
+ *   - knowledge/docs 共享面：HEAD 在册（M 形态）或工作区在场（蒸馏新产 A 形态）才入列。
+ *   - 其余丢弃并回报（dropped），由调用方显式提示。
+ *
+ * 纯函数（git 读数由调用方喂入），单测直接钉构成口径。
+ * @param {{changeName:string, stagedNameStatus:string, headTreeFiles:string, existsFn?:(p:string)=>boolean}} p
+ * @returns {{pathspecs:string[], dropped:string[]}}
+ */
+export function resolveArchiveCommitPathspecs({ changeName, stagedNameStatus, headTreeFiles, existsFn }) {
+  const changesPrefix = '.sillyspec/changes/'
+  // 与旧实现同源的单元格收集（--name-status：R 行 src<TAB>dst 两格，A/M 单格）
+  const mineCells = new Set()
+  for (const line of String(stagedNameStatus || '').split('\n')) {
+    if (!line.trim()) continue
+    for (const cell of line.split('\t').slice(1)) {
+      const p = cell.trim().replace(/^"|"$/g, '')
+      if (!p) continue
+      if (p.startsWith(changesPrefix + changeName + '/')
+        || p.startsWith(changesPrefix + 'archive/' + changeName + '/')
+        || p.startsWith('.sillyspec/knowledge/')
+        || p.startsWith('.sillyspec/docs/')) mineCells.add(p)
+    }
+  }
+  const headSet = new Set(String(headTreeFiles || '').split('\n').map((s) => s.trim()).filter(Boolean))
+  const srcPaths = []
+  let archiveHit = false
+  const sharedPaths = []
+  const dropped = []
+  for (const p of mineCells) {
+    if (p.startsWith(changesPrefix + 'archive/' + changeName + '/')) {
+      archiveHit = true
+    } else if (p.startsWith(changesPrefix + changeName + '/')) {
+      if (headSet.has(p)) srcPaths.push(p)
+      else dropped.push(p)
+    } else {
+      if (headSet.has(p) || (typeof existsFn === 'function' && existsFn(p))) sharedPaths.push(p)
+      else dropped.push(p)
+    }
+  }
+  const pathspecs = [...(archiveHit ? [`${changesPrefix}archive/${changeName}/`] : []), ...srcPaths, ...sharedPaths]
+  return { pathspecs, dropped }
+}
+
 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）──
@@ -858,9 +1007,16 @@ export async function runArchiveChain({ pm, cwd, specBase, changeName, srcDir, d
   // pathspec 把并行会话同目录未提交文件夹带进共享暂存区）：改为窄化——changes 侧只 add 本变更
   // 归档目录 archive/<destName>/，docs 侧按 module-impact「更新结果」done 行精确文件集（提取
   // 失败回退目录级 + 前置 warning，见 archiveNarrowedGitAdd）。
+  // destName 推导（2026-10-05-flow-tail-polish 根因修复）：本链签名无 destName——此前下方
+  // 调用引用未声明标识符抛 ReferenceError 被空 catch 静默吞，archiveNarrowedGitAdd 在 flow
+  // done 路径从未生效（归档目录/knowledge/docs 自动暂存全失效，靠 agent 手工兜底——实测
+  // porcelain 实证）。basename(destDir) 与调用方 destDir 恒一致（flow.js 与 run archive 同构）。
+  const destName = basename(destDir)
   try {
     archiveNarrowedGitAdd({ cwd, specBase, destDir, destName })
-  } catch {}
+  } catch (e) {
+    console.warn(`⚠️ 归档窄化 git add 异常（不阻断归档，交付面靠下方探测块兜底/agent git status 核对）: ${(e && e.message) || e}`)
+  }
 
   // ── 他者半归档残留探测（坑 archive-other-residual-rename，2026-08-21 实证）──
   // 并行变更的手动归档把 R 残留（源目录 rename 目标行）留在暂存区；本变更归档提交时
@@ -875,6 +1031,10 @@ export async function runArchiveChain({ pm, cwd, specBase, changeName, srcDir, d
       const changesPrefix = '.sillyspec/changes/'
       const minePaths = []
       const othersResidual = []
+      // 兜底信号（2026-10-05-flow-tail-polish）：正常路径 archiveNarrowedGitAdd 已暂存归档目录
+      // 与 knowledge——这两个信号只在窄化 add 失败降级时非空/置位
+      let untrackedArchiveHit = false
+      const knowledgePending = []
       for (const line of raw.split('\n')) {
         if (!line || line.length < 4) continue
         const x = line[0], y = line[1]
@@ -894,18 +1054,72 @@ export async function runArchiveChain({ pm, cwd, specBase, changeName, srcDir, d
                     || p.startsWith(changesPrefix + 'archive/' + changeName + '/'))) {
             minePaths.push(p)
           }
+        } else if (x === '?' && y === '?') {
+          // 未跟踪兜底：归档新目录（目录聚合/逐文件两形态都收，archive/<me>/ 专属本变更零共享）
+          if (dst === `${changesPrefix}archive/${changeName}/` || dst.startsWith(`${changesPrefix}archive/${changeName}/`)) {
+            untrackedArchiveHit = true
+          } else if (dst.startsWith('.sillyspec/knowledge/')) {
+            knowledgePending.push(dst)
+          }
+        } else if (x === ' ' && y === 'M' && dst.startsWith('.sillyspec/knowledge/')) {
+          // knowledge 未暂存修改（同兜底语义）
+          knowledgePending.push(dst)
         }
       }
       if (minePaths.length > 0) {
         // 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])
+        // 同坑不同点；git add -- <已删路径> 即暂存删除，语义等价 -A 限本变更面）。
+        // 坑 archive-stage-claim（2026-10-06-module-map-list-leak 收口实测）：safeGit 不抛错返回
+        // {value,error}——此前忽略返回值无条件打成功提示，add 失败（index.lock 竞态等）时假成功。
+        const staged = stageArchiveSourceSideMoves({ cwd, paths: minePaths })
+        const msg = renderStageSourceSideMovesMessage(staged)
+        if (msg) (staged.ok ? console.log : console.warn)(msg)
+      }
+      if (untrackedArchiveHit) {
+        // 文件级枚举补暂存（守 AGENTS.md 规则 11 不用目录级 add；实际仅窄化 add 降级时可达）
+        try {
+          const archFiles = []
+          const walk = (d) => { for (const e of readdirSync(d, { withFileTypes: true })) { const p = join(d, e.name); if (e.isDirectory()) walk(p); else archFiles.push(p) } }
+          walk(destDir)
+          const rel = archFiles.map((p) => relative(cwd, p).replace(/\\/g, '/'))
+          for (const batch of chunkPaths(rel)) safeGit(cwd, ['add', '--', ...batch])
+          console.log(`🧾 已补暂存未跟踪的归档目录文件（${rel.length} 项，archive/${changeName}/ 专属本变更——窄化 add 降级兜底）`)
+        } catch (e) {
+          console.warn(`⚠️ 归档目录兜底补暂存失败（请手工 git add -- .sillyspec/changes/archive/${changeName}/ 下文件）: ${(e && e.message) || e}`)
         }
-        console.log(`🧾 已补暂存本变更归档的源侧移动（${minePaths.length} 项，归档成单次原子提交）`)
       }
+      if (knowledgePending.length > 0) {
+        console.log(`📎 归档提交待办（knowledge 蒸馏产物未暂存——核对归属后随归档提交一并带上）：`)
+        console.log(`   git add -- ${knowledgePending.join(' ')}`)
+      }
+// 归档提交一笔到位提示（2026-10-06-litest-p1-fixes 实测 b112d738/2c8fd25c：git commit
+// -- <pathspec> 是部分提交——rename 条目 pathspec 只匹配 archive/ 侧时提交树里源文件
+// 不会被删（D 留暂存区，源侧得再来一笔）。补暂存只保证暂存面完整，提交 pathspec 仍由
+// agent 掌握）。聚合本变更归档面全量 staged 路径打印可直接执行的一笔到位 commit 命令。
+// 2026-10-06-archive-cmd-race-and-brief 竞态加固：真仓实测（flow-status-json 收尾）照抄执行报
+// pathspec did not match——共享仓多会话/后台同步可在「打印→执行」窗口瞬改暂存区，单会话镜像
+// 复盘命令干净（竞态即现即逝）。照抄暂存面不可靠，pathspec 构成按稳定性分级（见
+// resolveArchiveCommitPathspecs JSDoc）；无 staged 面不打印（幂等重入）。
+try {
+  const stagedRaw = gitQuiet(cwd, ['diff', '--cached', '--name-status'])
+  const headTreeRaw = gitQuiet(cwd, ['ls-tree', '-r', '--name-only', 'HEAD'])
+  const { pathspecs, dropped } = resolveArchiveCommitPathspecs({
+    changeName,
+    stagedNameStatus: String(stagedRaw || ''),
+    headTreeFiles: String(headTreeRaw || ''),
+    existsFn: (p) => { try { return existsSync(join(cwd, p)) } catch { return false } },
+  })
+  if (pathspecs.length > 0) {
+    console.log(`🧾 归档提交一笔到位（src 锚 HEAD 树/归档侧目录 pathspec/共享面按在场——共享暂存区竞态加固）：`)
+    console.log(`   git commit -m "chore(archive): ${changeName} 归档留档" -- ${pathspecs.join(' ')}`)
+    if (dropped.length > 0) {
+      console.log(`   ⚠️ 丢弃 ${dropped.length} 个瞬时暂存条目（HEAD 不在册且工作区不在场——并行会话动了共享暂存区，未入命令）：${dropped.join('、')}`)
+    }
+    console.log(`   （若执行报 pathspec 不匹配：共享仓暂存区在打印→执行间又被并行会话改动——git diff --cached --name-only 全量重核，以实际面替换 pathspec 后再提交）`)
+  }
+} catch { /* 提示失败不阻断归档（advisory） */ }
       if (othersResidual.length > 0) {
         const owners = [...new Set(othersResidual)].filter(Boolean)
         console.warn(`⚠️  检测到「他者半归档」残留（暂存区存在其他变更的 rename 记录）：${owners.join('、')}`)

package/src/run/complete.js

@@ -18,9 +18,9 @@
  */
 import { join, isAbsolute, resolve } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { gitQuiet } from '../git-helper.js'
+import { writeCloseTraceArtifacts, projectTraceFaceRows } from '../flow-parity.js'
 import { withFileLock } from '../quicklog.js'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveRuntimeRoot, getOrCreateMultiRepoContext, resolveChangeDir, writePlatformDocsPointer } from './shared.js'
 import { isExplicitReviewWrite, collectWorktreeChangedFiles } from '../task-review.js'
@@ -451,6 +451,70 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     }
   }
 
+  // ── 方案步 --done 知识检索命中回显（FR-03/D-004，2026-09-28-unclear-req-to-brainstorm）──
+  // 设计时点此前零检索面（自动注入只锚变更入口）——方案步 --done 对 --output 与 decisions.md
+  // 当前条目（D-xxx 标题+question 拼串；执行期裁决 D-007：条目无时间戳，「自上次 --done 新增」
+  // 无机械锚点，取全部条目为超集）跑既有检索匹配器 matchKnowledge（复用不另写）；命中 → warn
+  // 回显（decisionHits rejected 优先排序为匹配器既有行为）+ evidence 回应提示；v1 只 warn 不
+  // 阻断（D-004 故障面自留退路）。逃生阀 local.yaml commands.knowledge-gate: false/off 关回显
+  // （缺省开，config-schema 已登记）；无命中输出与现状一致。fail-open：检索异常静默放行。
+  if (stageName === 'brainstorm' && steps[currentIdx]?.name?.includes('提出 2-3 种方案') && changeName) {
+    try {
+      let _kgOn = true
+      try {
+        const _ly = readFileSync(join(specBase, 'local.yaml'), 'utf8')
+        const _kgm = _ly.match(/^\s*knowledge-gate\s*:\s*(true|false|on|off)\s*$/m)
+        if (_kgm && (_kgm[1] === 'false' || _kgm[1] === 'off')) _kgOn = false
+      } catch { /* 无 local.yaml = 缺省开 */ }
+      if (_kgOn) {
+        let _kgQuery = String(outputText || '')
+        let _dm = ''
+        try {
+          _dm = readFileSync(join(specBase, 'changes', changeName, 'decisions.md'), 'utf8')
+          const _parts = []
+          for (const m of _dm.matchAll(/^##\s+(D-\d+@v\d+):\s*(.+)$/gm)) _parts.push(`${m[1]} ${m[2]}`)
+          for (const m of _dm.matchAll(/^- question:\s*(.+)$/gm)) _parts.push(m[1])
+          if (_parts.length > 0) _kgQuery += '\n' + _parts.join('\n')
+        } catch { /* 无 decisions.md = 仅 --output */ }
+        _kgQuery = _kgQuery.slice(0, 4000)
+        if (_kgQuery.trim()) {
+          const { matchKnowledgeHybrid } = await import('../knowledge-vector.js')
+          const km = await matchKnowledgeHybrid(join(specBase, 'knowledge'), _kgQuery, { cwd })
+          // 零分不弹（2026-09-28-knowledge-gate-denoise）：score 零且非死路的 rejected 与查询零主题
+          // 重叠——空标题条目靠状态蹭进回显是行为实测三例的噪音源；死路条目不受限（防复潮先验）。
+          const _hits = (km.decisionHits || []).filter((h) => h.deathPath || (h.status === 'rejected' && h.score > 0))
+          // 已回应不重弹：decisions.md 正文已含「命中 id＋域文件名」共现（小白鼠回应形态
+          // 「unmapped.md D-001@v1」）→ 视为已甄别过，静默；同轮查询串仍含其词面属预期。
+          const _answered = _dm
+            ? (h) => {
+                const _dom = String(h.file || '').replace(/^decisions\//, '').replace(/\.md$/, '')
+                return _dm.includes(h.id) && _dm.includes(_dom)
+              }
+            : () => false
+          const _echoHits = _hits.filter((h) => !_answered(h))
+          const _entries = km.matched ? (km.entries || []) : []
+          if (_echoHits.length > 0 || _entries.length > 0) {
+            const { deathPathNote } = await import('../knowledge-match.js')
+            console.warn(`\n⚠️ [knowledge-gate] 方案/决策知识命中（设计时点防复潮提示，warn 不阻断）：`)
+            for (const h of _echoHits.slice(0, 5)) {
+              const _note = h.status === 'rejected'
+                ? ` 否决理由：${h.reason || '（未记录）'}`
+                : h.deathPath ? ` ⚰️死路注记：${deathPathNote(h.reason)}` : ''
+              console.warn(`   - ${h.id} ${h.title}（${h.file}）status=${h.status || '?'}${_note}`)
+            }
+            for (const e of _entries.slice(0, 3)) {
+              const _base = e.anchor ? `${e.file}#${e.anchor}` : e.file
+              console.warn(`   - 知识条目 ${_base}${e.display ? `（${e.display}）` : ''}`)
+            }
+            console.warn(`   须在对应决策的 evidence 回应或说明不复潮（v1 提示级；local.yaml commands.knowledge-gate: false 可关本回显）`)
+          }
+        }
+      }
+    } catch (_kgEx) {
+      console.warn(`   ⚠️ knowledge-gate 检索自身异常，fail-open 放行（不误拦本次完成）：${_kgEx && _kgEx.message ? _kgEx.message : _kgEx}`)
+    }
+  }
+
   // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
   // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
   // （stage.js noAI 分支，不写 step output）；若 agent 对 noAI step 直接 --done，此前
@@ -898,15 +962,17 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
       // 避免校验失败（FAIL / 缺 verify-result.md）时仍声称"验证通过可以归档"。
     } else if (stageName === 'brainstorm') {
-      // brainstorm 下一步按 design.md 的 scale 分叉（与末步 prompt 的 large→plan / small→quick 对齐），
+      // brainstorm 下一步按 design.md 的 scale 分叉（2026-09-29-brainstorm-exit-thin-default：large→plan；small/未标→flow start 收编），
       // 不走下方 _getNextSuggestion —— 后者按全局状态机「第一个未完成且上游就绪的阶段」推荐，
       // 当 scan 未完成时会误推 scan（回头路），与 brainstorm 已完成、应进入 plan/quick 矛盾。
       // 历史教训：曾因此让 agent 在 brainstorm 完成后被误导去跑 scan。
       const _bscale = readDesignScale(specBase, changeName)
-      if (_bscale === 'small') {
-        console.log(`\n👉 brainstorm 已完成（small）。下一步：sillyspec flow start --change ${changeName}（轻量变更收编头脑风暴产物，2 调用收口）`)
+      if (_bscale === 'large') {
+        console.log(`\n👉 brainstorm 已完成（large）。下一步：sillyspec run plan${changeName ? ` --change ${changeName}` : ''}（完整五阶段）`)
       } else {
-        console.log(`\n👉 brainstorm 已完成。下一步：sillyspec run plan${changeName ? ` --change ${changeName}` : ''}（scale=large 或未标 small 走完整 plan）`)
+        // 未标/small 默认收编轻量道（2026-09-29-brainstorm-exit-thin-default：此前「未标走完整 plan」
+        // 是缺省即厚；翻转与 thin-default-flip 同哲学——升厚留运行时证据＋用户决策）
+        console.log(`\n👉 brainstorm 已完成（scale=${_bscale || '未标，默认 small'}）。下一步：sillyspec flow start --change ${changeName}（轻量变更收编头脑风暴产物，2 调用收口；实测失败自动升厚 / --upgrade-thick 用户决策）`)
       }
     } else if (stageName === 'quick') {
       // quick 是收尾阶段（辅助流程，不走主链 scan→archive），完成后该提交，而非推 scan。
@@ -1043,16 +1109,27 @@ async function printExecuteScopeAudit({ cwd, changeName, specBase, platformOpts,
     mkdirSync(changeDir, { recursive: true })
     const { frozenPatch, ...snap } = result
     snap.note = 'execute --done 时点冻结（本文件落盘时采集）'
-    if (typeof frozenPatch === 'string') {
-      const patchText = frozenPatch.endsWith('\n') ? frozenPatch : frozenPatch + '\n'
-      writeFileSync(join(changeDir, 'scope-audit.patch'), patchText)
-      snap.patchSha256 = createHash('sha256').update(patchText.replace(/\r\n/g, '\n'), 'utf8').digest('hex')
-      snap.patchStatus = 'ok'
-    } else if (frozenPatch === null) {
-      snap.patchStatus = 'failed'
-    }
-    writeFileSync(join(changeDir, 'scope-audit.json'), JSON.stringify({ ...snap, savedAt: new Date().toISOString() }, null, 2) + '\n')
-    console.log(`   📦 范围快照已落变更目录（scope-audit.json${snap.patchStatus === 'ok' ? ' + scope-audit.patch（收尾时点冻结，sha256 已锚）' : snap.patchStatus === 'failed' ? '——patch 采集失败已留痕' : ''}）`)
+    snap.closedBy = 'execute --done'
+    // 沉淀资产面投影（2026-10-07-unify-close-trace）：files/totals = 主仓实改行（planned+
+    // unplanned；untouched 0/0 是声明不是改动、crossRepo 行 patch 不在主仓——均不入）。
+    // 经共用 writeCloseTraceArtifacts 与 thin flow done 同一处写四件（sha256 双套同锚）；
+    // 投影口径抽 flow-parity.projectTraceFaceRows 纯函数（排除路径有单测钉住）。
+    const face = projectTraceFaceRows(snap.rows)
+    const closeTrace = writeCloseTraceArtifacts({
+      changeDir,
+      change: changeName,
+      baseline: typeof snap.baseAnchor === 'string' ? snap.baseAnchor : null,
+      head: String(gitQuiet(cwd, ['rev-parse', 'HEAD']) || '').trim() || null,
+      files: face.files,
+      metaTotals: face.totals,
+      patchText: typeof frozenPatch === 'string' && frozenPatch ? frozenPatch : null,
+      savedAt: new Date().toISOString(),
+      snapObj: snap,
+      meta: {
+        note: 'execute --done 时点冻结（沉淀资产面：主仓实改行投影——thin flow done 对等；治理工件目录与其后 verify/archive 演进不在内）',
+      },
+    })
+    console.log(`   📦 范围快照 + 沉淀资产双轨落盘（scope-audit.json${closeTrace.patchStatus === 'ok' ? ' + scope-audit.patch' : ''} + change-patch.json${closeTrace.patchStatus === 'ok' ? ' + change.patch' : ''}${closeTrace.patchStatus === 'ok' ? '——收尾时点冻结，sha256 同锚' : '——patch 采集失败已留痕'}）`)
   } catch (e) {
     console.warn(`   ⚠️ 范围对账快照写入失败（不阻断，verify 漂移对比将按无快照降级）：${e && e.message ? String(e.message).split('\n')[0] : e}`)
   }
@@ -2086,16 +2163,16 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {
-      // brainstorm 按 design.md frontmatter 的 scale 分叉（与末步 prompt 对齐）：
-      //   small → quick --linked-changes（小变更免走完整 plan）；large / 读不到 scale → plan（保守默认）。
-      // 修历史 bug：此处曾硬编码 brainstorm→plan 不读 scale，small 档与末步 prompt（quick）矛盾、误导小变更进 plan。
+      // brainstorm 按 design.md frontmatter 的 scale 分叉（2026-09-29-brainstorm-exit-thin-default
+      // 与 completeStep 主路径同口径）：large → run plan（完整五阶段）；small/未标 → flow start
+      // 收编轻量道（此前 small→quick --linked-changes 是旧收编通道、未标→plan 是缺省即厚，均已退役）。
       let hintStage = nextStageHint
       let hintChangeFlag = changeName ? ` --change ${changeName}` : ''
-      if (stageName === 'brainstorm' && changeName && readDesignScale(specBase, changeName) === 'small') {
-        hintStage = 'quick'
-        hintChangeFlag = ` --linked-changes ${changeName}`
+      if (stageName === 'brainstorm' && changeName && readDesignScale(specBase, changeName) !== 'large') {
+        console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec flow start --change ${changeName}（轻量变更收编头脑风暴产物，2 调用收口）`)
+      } else {
+        console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${hintStage}${hintChangeFlag}`)
       }
-      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${hintStage}${hintChangeFlag}`)
       if (stageName === 'execute') {
         console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
         console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)

package/src/run/gate-snapshot.js

@@ -722,6 +722,21 @@ export function detectSymlinkStoreLayout(cwd) {
     if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
     if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) return 'bun'
     if (existsSync(join(cwd, 'lerna.json'))) return 'lerna'
+    // ── 子目录 lockfile（apps 型 monorepo——2026-09-30-snapshot-symlink-store-subdir）──
+    // 实证：multi-agent-platform（frontend/ + sillyhub-daemon/ 各自 pnpm-lock.yaml，根目录无
+    // lockfile）漏检 → 快照照建，verify 收敛循环每轮 ~160s 纯烧快照构建/junction。packages/*
+    // workspace 型不扫（该形态 lockfile 在根，根判据已覆盖）。子目录命中=该 app 的
+    // node_modules 符号链接网同样跨根失效——跳快照回主仓是既有保守裁决（宁主仓口径）。
+    try {
+      for (const e of readdirSync(cwd, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue
+        if (e.name === 'node_modules' || e.name.startsWith('.')) continue
+        const d = join(cwd, e.name)
+        if (existsSync(join(d, 'pnpm-lock.yaml'))) return `pnpm(subdir:${e.name})`
+        if (existsSync(join(d, 'bun.lockb')) || existsSync(join(d, 'bun.lock'))) return `bun(subdir:${e.name})`
+        if (existsSync(join(d, 'lerna.json'))) return `lerna(subdir:${e.name})`
+      }
+    } catch { /* 根不可读（与非仓目录同语义）→ 落到 packageManager 判据 */ }
     try {
       const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))
       const pm = pkg && pkg.packageManager ? String(pkg.packageManager) : ''