sillyspec 3.26.15 → 3.27.2

package/src/module-resolve.js

@@ -0,0 +1,211 @@
+/**
+ * module-resolve.js — 模块卡两级级联解析（token 成本优化 P0a，2026-08-22-token-cost-optimization）
+ *
+ * 背景（multi-agent-platform 2026-08-22 实测）：monorepo 根层 _module-map.yaml 把整个子项目
+ * （backend/**）映射到单张大卡（backend.md 58KB），而子项目细粒度卡（docs/backend/modules/
+ * agent.md，~6KB）由 scan 生成却无人消费——execute 每个 task 子代理都被指引去读整张大卡，
+ * 单卡一项全流程烧 20 万+ tokens 输入，且大卡「变更索引」段每变更追加、单调膨胀。
+ *
+ * 本模块 = 纯机械分类（与 module-impact.js 同性质，CLI 算事实）：
+ *   - collectModuleMaps：收齐 <spec>/docs/<project>/modules/_module-map.yaml 全部层级；
+ *     project 名恰为仓库顶层目录（monorepo 子项目，如 backend/）→ 其 paths 视为相对该
+ *     子目录（effective = `<project>/` + path）；否则视为仓库根相对（根层粗粒度 map）
+ *   - matchModuleCard：跨全部 map 最长有效前缀匹配（细卡 agent/** 胜过粗卡 backend/**）
+ *   - resolveChangeModuleCards：tasks.md 注册表 × tasks/task-NN.md allowed_paths → per-task
+ *     最优卡表；卡的体量（字节数）一并给出，读取建议按体量分级（>12KB 按节读）
+ *
+ * 铁律（对齐仓内先例）：
+ *   - 纯读：不写任何文件，不跑 git
+ *   - 无 map / 无 tasks.md / 无 task 卡 → 空结果（调用方注入占位说明，不抛）
+ *   - 判定语义（哪个模块才是「对的」）仍归 agent——本表只是机械最优匹配
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import { parseModuleMapSimple } from './modules.js'
+import { parseTaskRegistry } from './stages/execute.js'
+import { parseAllowedPaths } from './stages/plan-postcheck.js'
+
+/** 模块卡「整卡可读」软上限（字节）。超过则建议按节读（契约摘要/注意事项/定位），跳过历史累积段。 */
+export const MODULE_CARD_SOFT_LIMIT_BYTES = 12 * 1024
+
+/**
+ * 收齐 spec 下全部模块映射层。
+ * @param {{ cwd: string, specBase: string }} opts
+ * @returns {Array<{ project: string, mapPath: string, modulesDir: string, prefix: string,
+ *            entries: Map<string, { paths: string[], doc: string|null }> }>}
+ *   prefix：project 名为仓库顶层目录时 `<project>/`（子项目细 map），否则 ''（根层粗 map）
+ */
+export function collectModuleMaps({ cwd, specBase }) {
+  const maps = []
+  const docsDir = join(specBase, 'docs')
+  if (!existsSync(docsDir)) return maps
+  let projects = []
+  try {
+    projects = readdirSync(docsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+  } catch { return maps }
+  for (const project of projects) {
+    const modulesDir = join(docsDir, project, 'modules')
+    const mapPath = join(modulesDir, '_module-map.yaml')
+    if (!existsSync(mapPath)) continue
+    let parsed = {}
+    try {
+      parsed = parseModuleMapSimple(readFileSync(mapPath, 'utf8'))
+    } catch { continue }
+    const entries = new Map()
+    for (const [id, data] of Object.entries(parsed)) {
+      const paths = Array.isArray(data?.paths) ? data.paths : []
+      if (paths.length === 0) continue
+      entries.set(id, { paths, doc: typeof data?.doc === 'string' ? data.doc : null })
+    }
+    if (entries.size === 0) continue
+    // 子项目判定：project 名恰为仓库顶层目录 → map 的 paths 相对该子目录（monorepo 细 map）。
+    // 根层 map（project = 仓名）paths 本就仓库根相对，prefix=''。
+    let prefix = ''
+    try {
+      const topDir = join(cwd, project)
+      if (existsSync(topDir) && statSync(topDir).isDirectory()) prefix = `${project}/`
+    } catch { /* stat 失败按根层处理 */ }
+    maps.push({ project, mapPath, modulesDir, prefix, entries })
+  }
+  return maps
+}
+
+/**
+ * 路径归一：反斜杠→正斜杠，剥尾部 glob（/** 与 /*）与目录斜杠。
+ * `backend/**` / `backend/` / `backend` → `backend`。
+ */
+function normalizeMapPath(raw) {
+  return String(raw).replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/\*$/, '').replace(/\/$/, '')
+}
+
+/**
+ * 跨全部 map 最长有效前缀匹配一个仓库根相对路径。
+ * @param {string} posixPath 仓库根相对 posix 路径
+ * @param {Array} maps collectModuleMaps 产物
+ * @returns {{ moduleId: string, map: object, effectivePrefix: string }|null}
+ */
+export function matchModuleCard(posixPath, maps) {
+  const p = String(posixPath).replace(/\\/g, '/')
+  let best = null
+  for (const map of maps) {
+    for (const [moduleId, entry] of map.entries) {
+      for (const raw of entry.paths) {
+        const effective = (map.prefix + normalizeMapPath(raw)).replace(/\/+$/, '')
+        if (!effective) continue
+        if (p === effective || p.startsWith(effective + '/')) {
+          if (!best || effective.length > best.effectivePrefix.length) {
+            best = { moduleId, map, effectivePrefix: effective }
+          }
+        }
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * 解析变更全部 task 的最优模块卡。
+ * @param {{ cwd: string, specBase: string, changeName: string }} opts
+ * @returns {{ hasMaps: boolean, rows: Array<{ taskId: string, taskName: string,
+ *            moduleId: string|null, granularity: 'fine'|'coarse'|null,
+ *            cardPath: string|null, cardBytes: number, advice: string,
+ *            matchedCount: number, pathCount: number }> }}
+ *   granularity：按胜者有效前缀段数判——1 段（整子项目）=coarse 大卡，≥2 段=fine 细卡
+ */
+export function resolveChangeModuleCards({ cwd, specBase, changeName }) {
+  const maps = collectModuleMaps({ cwd, specBase })
+  const changeDir = join(specBase, 'changes', changeName || '')
+  let registry = []
+  const tasksMd = join(changeDir, 'tasks.md')
+  if (existsSync(tasksMd)) {
+    registry = parseTaskRegistry(readFileSync(tasksMd, 'utf8'))
+  }
+  const rows = []
+  for (const task of registry) {
+    // 任务路径源：task 卡 allowed_paths（主）> 注册表行内 (文件路径) 尾注（兜底）
+    let paths = []
+    const cardFile = join(changeDir, 'tasks', `${task.id}.md`)
+    if (existsSync(cardFile)) {
+      paths = parseAllowedPaths(readFileSync(cardFile, 'utf8'))
+    }
+    if (paths.length === 0 && task.file) paths = [task.file]
+    paths = paths.map(p => p.replace(/\\/g, '/')).filter(Boolean)
+
+    // 全路径逐个匹配，取「最长有效前缀」的模块为该 task 的最优卡。粒度按有效前缀段数判：
+    // 1 段（backend/frontend 整子项目）=粗层大卡；≥2 段=细层卡（段数与卡体量正相关，
+    // SillyHub 这类根相对细 map 同样正确——不能按 map 的 prefix 有无判，会误标）
+    let winner = null
+    let matchedCount = 0
+    for (const p of paths) {
+      const m = matchModuleCard(p, maps)
+      if (!m) continue
+      matchedCount++
+      if (!winner || m.effectivePrefix.length > winner.effectivePrefix.length) winner = m
+    }
+    let granularity = null
+    if (winner) {
+      const segs = winner.effectivePrefix.split('/').filter(Boolean).length
+      granularity = segs >= 2 ? 'fine' : 'coarse'
+    }
+
+    let cardPath = null
+    let cardBytes = 0
+    let advice = '—'
+    if (winner) {
+      const docRel = winner.map.entries.get(winner.moduleId)?.doc || `modules/${winner.moduleId}.md`
+      const abs = join(winner.map.modulesDir, '..', docRel)
+      if (existsSync(abs)) {
+        const rel = relative(cwd, abs).replace(/\\/g, '/')
+        cardPath = rel.startsWith('..') ? abs.replace(/\\/g, '/') : rel
+        try { cardBytes = statSync(abs).size } catch { cardBytes = 0 }
+        advice = cardBytes > MODULE_CARD_SOFT_LIMIT_BYTES
+          ? `按节读（契约摘要/注意事项/定位；跳过变更索引/人工备注）`
+          : '整卡可读'
+      } else {
+        cardPath = relative(cwd, abs).replace(/\\/g, '/')
+        advice = '卡文件缺失（modules rebuild？）'
+      }
+    }
+    rows.push({
+      taskId: task.id,
+      taskName: task.name,
+      moduleId: winner ? winner.moduleId : null,
+      granularity,
+      cardPath,
+      cardBytes,
+      advice,
+      matchedCount,
+      pathCount: paths.length,
+    })
+  }
+  return { hasMaps: maps.length > 0, rows }
+}
+
+/**
+ * 渲染 per-task 模块卡表（注入 execute「加载上下文」步 prompt 用）。
+ * 无 map → 提示跳过；有 map 无命中行 → 单行说明。恒返回非空字符串（占位符必被替换）。
+ */
+export function renderModuleResolveTable({ cwd, specBase, changeName }) {
+  const { hasMaps, rows } = resolveChangeModuleCards({ cwd, specBase, changeName })
+  if (!hasMaps) return '（未找到 _module-map.yaml——本项目无模块卡，跳过模块文档加载）'
+  const withMatch = rows.filter(r => r.moduleId)
+  if (withMatch.length === 0) {
+    return '（已找到 _module-map.yaml，但当前变更任务未命中任何模块 paths——跳过模块文档加载；游离文件可在 Wave 收尾后跑 `sillyspec modules rebuild`）'
+  }
+  const kb = (n) => n > 0 ? `${(n / 1024).toFixed(1)}KB` : '?'
+  const L = [
+    '| task | 模块 | 粒度 | 模块卡（只读命中的卡，勿按目录整读） | 体量 | 读取建议 |',
+    '|---|---|---|---|---|---|',
+  ]
+  for (const r of rows) {
+    if (r.moduleId) {
+      L.push(`| ${r.taskId} | ${r.moduleId} | ${r.granularity === 'fine' ? '细' : '粗'} | \`${r.cardPath}\` | ${kb(r.cardBytes)} | ${r.advice} |`)
+    } else {
+      L.push(`| ${r.taskId} | — | — | （无命中，跳过模块文档） | — | — |`)
+    }
+  }
+  L.push('')
+  L.push('> 匹配规则：全部 _module-map.yaml 跨层最长前缀（子项目细卡优先于根层大卡），源=tasks 卡 allowed_paths。')
+  L.push('> 细卡整卡可读；仅粗卡命中且体量大时**按节读**——只读「契约摘要/注意事项/定位」，跳过「变更索引/人工备注」历史累积段。')
+  return L.join('\n')
+}

package/src/modules.js

@@ -181,11 +181,91 @@ export async function rebuildModuleMap(cwd, { force = false } = {}) {
   return { dryRun: false, path: mapPath, modules: allModuleIds.size }
 }
 
+/**
+ * split-changelog：把模块卡的「变更索引」历史段迁出到同目录 <module>.changelog.md sidecar
+ * （token 成本优化 P0b，2026-08-22-token-cost-optimization）。
+ *
+ * 背景：变更索引段每变更追加、单调膨胀（multi-agent-platform backend.md 实测 19.9KB/占整卡
+ * 36%，18 天 3.6 倍），而子代理实现新 task 只需要卡的「定位/契约摘要/注意事项」当前态——
+ * 历史段是纯读取税。迁出后卡只留指针行，新条目由 prompt 约定直接追加 sidecar。
+ *
+ * 安全（对齐 rebuild 的破坏性保护）：默认 dry-run 只预览不写，--force 才落盘。
+ * 只动「## 变更索引」一节，卡内其他节原样保留；sidecar 已存在则追加（幂等可重跑）。
+ *
+ * @param {string} cwd 项目根
+ * @param {{ force?: boolean }} opts
+ * @returns {{ dryRun: boolean, files: Array<{ card: string, sidecar: string, bytesMoved: number }>, skipped: number }}
+ */
+export function splitChangelog(cwd, { force = false } = {}) {
+  const docsDir = join(cwd, '.sillyspec', 'docs');
+  const results = [];
+  let skipped = 0;
+  const projects = existsSync(docsDir)
+    ? readdirSync(docsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+    : [];
+
+  for (const project of projects) {
+    const modulesDir = join(docsDir, project, 'modules');
+    if (!existsSync(modulesDir)) continue;
+    const cards = readdirSync(modulesDir).filter(f => f.endsWith('.md') && f !== '_module-map.yaml');
+    for (const f of cards) {
+      const cardPath = join(modulesDir, f);
+      const content = readFileSync(cardPath, 'utf8');
+      // 提取「## 变更索引」节（CRLF 归一后行级匹配，与 modules.js 其余解析同防线）
+      const lines = content.replace(/\r\n/g, '\n').split('\n');
+      const startIdx = lines.findIndex(l => /^##\s*变更索引\s*$/.test(l));
+      if (startIdx < 0) { skipped++; continue; }
+      let endIdx = lines.length;
+      for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i])) { endIdx = i; break; }
+      }
+      const body = lines.slice(startIdx + 1, endIdx).join('\n').trim();
+      // 已迁出（只剩指针行）或本就为空 → 跳过
+      if (!body || /^见\s/.test(body) || body.includes('.changelog.md')) { skipped++; continue; }
+      const bytesMoved = Buffer.byteLength(body, 'utf8');
+      const stem = f.replace(/\.md$/, '');
+      const sidecarPath = join(modulesDir, `${stem}.changelog.md`);
+      results.push({ card: cardPath, sidecar: sidecarPath, bytesMoved, _lines: lines, _startIdx: startIdx, _endIdx: endIdx, _body: body });
+    }
+  }
+
+  if (!force) {
+    if (results.length === 0) {
+      console.log('📭 没有需要迁出的「变更索引」段（无模块卡 / 已迁出 / 段为空）');
+    } else {
+      console.log('⚠️  split-changelog 默认不写入（破坏性保护）：会把模块卡「变更索引」节迁出到同目录 <module>.changelog.md');
+      for (const r of results) {
+        console.log(`    ${r.card} → ${r.sidecar}（${(r.bytesMoved / 1024).toFixed(1)}KB）`);
+      }
+      console.log('    本次为预览，未写入磁盘。确认迁出请运行：sillyspec modules split-changelog --force');
+    }
+    return { dryRun: true, files: results.map(({ card, sidecar, bytesMoved }) => ({ card, sidecar, bytesMoved })), skipped };
+  }
+
+  for (const r of results) {
+    // sidecar：已存在追加（分隔线 + 迁出来源），否则新建带头部
+    const header = `# ${r.card.split(/[\\/]/).pop().replace(/\.md$/, '')} 变更索引\n\n> 由 sillyspec modules split-changelog 自模块卡迁出；新条目继续追加到本文件，勿写回模块卡。\n`;
+    let sidecarContent = header;
+    if (existsSync(r.sidecar)) {
+      sidecarContent = readFileSync(r.sidecar, 'utf8').replace(/\s*$/, '') + '\n\n---\n\n' + r._body + '\n';
+    } else {
+      sidecarContent = header + '\n' + r._body + '\n';
+    }
+    writeFileSync(r.sidecar, sidecarContent, 'utf8');
+    // 卡内节体替换为指针行（只动该节，其余逐字保留；_lines 已是 LF 归一）
+    const stem = r.card.split(/[\\/]/).pop().replace(/\.md$/, '');
+    const newLines = [...r._lines.slice(0, r._startIdx + 1), '', `见 \`${stem}.changelog.md\`——历史条目已迁出；新条目直接追加 sidecar，勿写回本卡。`, '', ...r._lines.slice(r._endIdx)];
+    writeFileSync(r.card, newLines.join('\n'), 'utf8');
+    console.log(`✅ ${r.card} → ${r.sidecar}（迁出 ${(r.bytesMoved / 1024).toFixed(1)}KB，卡内留指针）`);
+  }
+  if (results.length === 0) console.log('📭 没有需要迁出的「变更索引」段');
+  return { dryRun: false, files: results.map(({ card, sidecar, bytesMoved }) => ({ card, sidecar, bytesMoved })), skipped };
+}
+
 /**
  * status: 显示模块索引状态
  */
-export async function showModuleStatus(cwd) {
-  const mapPath = findModuleMapPath(cwd);
+export async function showModuleStatus(cwd) {  const mapPath = findModuleMapPath(cwd);
   if (!mapPath || !existsSync(mapPath)) {
     console.log('📭 未找到 _module-map.yaml');
     console.log('   提示：先运行 sillyspec run scan 生成模块文档');

package/src/progress/step-store.js

@@ -88,16 +88,16 @@ export class StepStore {
     }
     const stageId = stageRow.id;
 
-    // 重复步骤名检查
-    const dupRow = sqlDb.prepare('SELECT id FROM steps WHERE stage_id = ? AND name = ?').get(stageId, stepName);
-    if (dupRow !== undefined) {
-      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
-      return;
-    }
-
-    // INSERT INTO steps（ordering 递增）
+    // 重复步骤名检查 + INSERT 同事务（2026-08-21 审查 BUG-8）：查重在事务外时，
+    // 并发 add-step 同名可双双通过检查双插（steps 无 UNIQUE 约束），另一份 status 后续被 _write 覆盖丢失
+    let dupFound = false;
     db.transaction(() => {
       const tDb = db.getDb();
+      const dupRow = tDb.prepare('SELECT id FROM steps WHERE stage_id = ? AND name = ?').get(stageId, stepName);
+      if (dupRow !== undefined) {
+        dupFound = true;
+        return;
+      }
       tDb.prepare(
         `INSERT INTO steps (stage_id, name, ordering, status)
          VALUES (?, ?, (SELECT COALESCE(MAX(ordering), 0) + 1 FROM steps WHERE stage_id = ?), 'pending')`
@@ -106,6 +106,10 @@ export class StepStore {
       // 本地脏度（D-013 / task-04）：添加步骤是本地推进
       this.pm._touchLocalModified(cwd, cn);
     });
+    if (dupFound) {
+      console.log(`ℹ️  步骤 "${stepName}" 已存在于 ${stage}`);
+      return;
+    }
 
     console.log(`✅ 已添加步骤: ${stage}/${stepName}`);
   }

package/src/progress.js

@@ -13,6 +13,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir } from 'os';
+import { writeAtomicSync } from './fs-atomic.js';
 import { DB } from './db.js';
 import { checkExecuteCodeEvidence } from './stage-contract.js';
 import { ConsistencyDoctor } from './progress/consistency-doctor.js';
@@ -1015,9 +1016,12 @@ export class ProgressManager {
     if (existsSync(gitignorePath)) {
       const content = readFileSync(gitignorePath, 'utf8');
       if (content.includes(rule)) return;
-      writeFileSync(gitignorePath, content.trimEnd() + '\n' + rule + '\n');
+      // 按既有 EOL 追加（2026-08-21 审查 BUG-9）：CRLF 检出的文件混入 LF 行产生全文件
+      // diff 噪声/autocrlf 折腾；写走原子 rename 防并发 init 双跑交错
+      const eol = content.includes('\r\n') ? '\r\n' : '\n';
+      writeAtomicSync(gitignorePath, content.trimEnd() + eol + rule + eol);
     } else {
-      writeFileSync(gitignorePath, rule + '\n');
+      writeAtomicSync(gitignorePath, rule + '\n');
     }
   }
 

package/src/quicklog.js

@@ -265,10 +265,18 @@ export function deriveTitleFromLinkedChange(specBase, change) {
     try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
     const m = content.match(/^#\s+(.+?)\s*$/m)
     if (!m) continue
-    const raw = m[1].trim()
-    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc
+    let raw = m[1].trim()
+    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc。
+    // 固定前缀显式剥（坑 linked-task-placeholder-title，2026-08-22 实证：标题「# 提案书（Proposal）:
+    // xxx」或「# 提案书（Proposal）」无破折号时 dash 匹配失败，整串前缀落进 tasks.md 追加行）——
+    // 先剥固定模板词（含全/半角冒号分隔形态），再剥破折号；剥完为空（纯模板标题）继续找下一文档
+    for (const prefix of [/^提案书（Proposal）\s*[：:—\-]?\s*/, /^设计文档（Design）\s*[：:—\-]?\s*/, /^Proposal\s*[：:—\-]?\s*/i, /^Design\s*[：:—\-]?\s*/i]) {
+      raw = raw.replace(prefix, '').trim()
+    }
+    if (!raw) continue
     const dash = raw.match(/[—-]\s*(.+)$/)
-    return dash ? dash[1].trim() : raw
+    const title = dash ? dash[1].trim() : raw
+    if (title) return title
   }
   return ''
 }

package/src/run/command.js

@@ -163,6 +163,9 @@ sillyspec run ${stageName}${stage && stage.title ? ` — ${stage.title}` : ''}${
  * sillyspec run <stage> 主命令
  */
 export async function runCommand(args, cwd, specDir = null, opts = {}) {
+  // 原始 cwd 快照（下方 cwd 纠正前）：agent 在子目录启动时，其会话 transcript 挂在子目录
+  // 对应的 harness 项目目录下，agent-log 探测须用原始 cwd（纠正后的是项目根，探测会扑空）
+  const invokedCwd = cwd
   // W1-B: run <stage> 暂不支持 --json。之前 --json 进 knownFlags 白名单却从不读取（静默吞），
   // agent 按 gate/derive 契约期望 envelope 实则拿到混合人类文本。显式 fail-fast 杜绝歧义；
   // 完整 run envelope 待 outputStep 重构（W6）后支持（prompt + nextAction 结构化）。
@@ -366,6 +369,29 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // let：下方 worktree 副本漂移守卫命中时锚回 wt.mainSpecBase（task-05/D-03）
   let specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
+  // ── 本地 agent 会话日志登记 + 上报（平台会话展示用，best-effort）──
+  // 平台/daemon 模式下 SillyHub 只能看到 CLI 阶段信息，看不到本地 agent 的实际执行日志。
+  // 在此探测当前 agent 环境（Claude Code / Codex / ZCode transcript / SILLYSPEC_AGENT_LOG
+  // 覆盖），把日志本地路径登记进 <runtimeRoot>/agent-session-log.json（留底）并立即
+  // REST 上报平台（POST /api/agent-logs，与进度上报同风格；协议见
+  // docs/platform-agent-log-protocol.md）。探测不到不发不写；任何失败只 warn 一行，
+  // 绝不阻断 run 主流程。
+  try {
+    const { recordAgentLogInvocation } = await import('../agent-session-log.js')
+    const r = await recordAgentLogInvocation({
+      cwd,
+      invokedCwd,
+      platformOpts,
+      specBase,
+      // 只记 flag 名不记值（--output 等 flag 值是 agent 工作文本，不进产物）
+      command: [stageName, ...flags.filter(t => typeof t === 'string' && t.startsWith('--'))].join(' '),
+    })
+    if (r && r.isNew && r.latestLogPath) {
+      const pushNote = r.pushed === true ? '已上报平台' : r.pushed === false ? '上报失败（本地已留底）' : '本地留底'
+      console.log(`📄 本地 agent 日志已登记（${pushNote}）: ${r.latestLogPath}`)
+    }
+  } catch { /* best-effort：登记失败不影响 run 主流程 */ }
+
   // 漂移提醒:cwd 祖先链 ≥2 个 .sillyspec = monorepo 多实例,当前命中的「最近」实例
   // 可能不是用户意图的项目(如 cd 进被独立 scan 的子项目跑测试后忘回根)。
   // 平台模式 / 显式 --spec-dir 跳过(已明确指定,无歧义)。仅提醒不阻断。
@@ -1076,6 +1102,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     progress = pm.read(cwd, effectiveChange) || progress
   }
 
+  // --file-notes 非末步静默忽略前置 warn（坑 quick-file-notes-nonfinal-ignored，2026-08-22 实证：
+  // step2 --done 传 --file-notes 被静默丢——CLI 短进程，注入随进程结束即丢，白传一轮）。
+  // 放此处：ensureStageSteps 之后 progress 已就绪可判步骤状态；仅 quick + 带了 --file-notes +
+  // 非「唯一 pending 的末步 --done」时提示。末步 --done 是消费点，不提示。
+  if (quickFileNotes !== '' && stageName === 'quick' && !isStatus) {
+    try {
+      const qSteps = progress?.stages?.quick?.steps
+      const pendingCount = Array.isArray(qSteps) ? qSteps.filter(st => ['pending', 'in-progress'].includes(st?.status)).length : 0
+      if (!isDone || pendingCount > 1) {
+        console.warn(`⚠️ --file-notes 本次不会生效：它只在 quick 末步（暂存和更新记录）--done 时随收尾消费——CLI 是短进程，本次注入随进程结束即丢。请在末步 --done 时连同 --output 一起传。`)
+      }
+    } catch { /* 判定失败不提示（fail-open） */ }
+  }
+
   // --status
   if (isStatus) {
     // D9：状态展示末尾附「下一步该跑什么」。pm 持有状态机，按 progress 实际进度算出精确命令；

package/src/run/complete-handlers.js

@@ -127,7 +127,7 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
  * 见 stage.js execute 启动固定 executeRunId / stage-review.js stageReviewMarkerPath）。
  * 从 archiveChangeDirectory 抽出，供正常归档 + 自愈归档复用。
  */
-async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
+export async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts = {}) {
   // ── 清理 runId marker：execute（current-execute-run-id-<change>）与 stage-review
   //    （current-stage-review-run-id-<stage>-<change>）。marker 只服务 execute→verify→archive
   //    期间，归档后无读者；不删则 .runtime 随变更数无限累积。runtimeRoot 解析同写入侧
@@ -158,7 +158,17 @@ async function archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platform
     const { WorktreeManager } = await import('../worktree.js')
     const wm = new WorktreeManager({ cwd })
     const meta = wm.getMeta(archiveChangeName)
-    if (!meta) return
+    if (!meta) {
+      // 无 meta 兜底（坑 archive-cleanup-orphan-physical-dir，2026-08-21 实证）：meta 已被先行
+      // 流程注销（apply 自动 cleanup / doctor 幽灵清理）时此前直接 return——若物理目录因中途
+      // 失败残留下就是孤儿（无 meta=无锚定基准，残留即孤儿）。force 清理（幂等：什么都不存在
+      // 时 cleanup 返回 skipped 零副作用）。
+      const orphan = wm.cleanup(archiveChangeName, { force: true })
+      if (orphan.result === 'cleaned' || orphan.result === 'force-cleaned' || orphan.result === 'partial') {
+        console.log(`🧹 归档清理孤儿 worktree 残留（meta 已注销）: ${archiveChangeName}${orphan.residual?.length ? '（残留: ' + orphan.residual.join('; ') + '）' : ''}`)
+      }
+      return
+    }
     const check = meta.mode !== 'in-place-fallback' ? wm.hasUnappliedChanges(archiveChangeName) : { hasChanges: false }
     if (check.hasChanges) {
       console.warn(`⚠️  归档时 worktree 仍有 ${check.changedFiles.length} 个未 apply 变更，保留 worktree`)
@@ -423,6 +433,11 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
   }
   const archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts)
   if (archivedDir && existsSync(archivedDir)) {
+    // 内存快照同步（坑 archive-progress-show-stale，2026-08-21 实证）：archiveChangeDirectory 内
+    // unregisterChange 已在 DB 写 current_stage='archive'（终态一致化），但本进程 progress 是命令
+    // 开始时读的旧快照——不同步的话，completeStep 后续 _write 会用旧值（如停在 verify）把
+    // DB 覆盖回去，progress show 就一直显示归档前的阶段
+    progress.currentStage = 'archive'
     const recommendedDocs = ['design.md', 'module-impact.md']
     const missingRecommended = recommendedDocs.filter(d => !existsSync(join(archivedDir, d)))
     if (missingRecommended.length > 0) {

package/src/run/complete.js

@@ -167,6 +167,38 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       steps[_staleIdx].status = 'pending'
       currentIdx = _staleIdx
       console.log(`⚠️  --confirm 收尾：把 stale 步骤 "${steps[_staleIdx].name}" 拉回当前步骤走完成管线，其余 stale 由回填门控一并确认。`)
+    } else if (stageData?.status !== 'completed' && steps.length > 0) {
+      // ── 矛盾态自愈（坑 execute-status-machine-contradiction，2026-08-23 实证：--done 报
+      // 「没有待完成的步骤」而 status 显示 15 步未完成——并发进程写入竞争后 DB 步骤行停在
+      // completed 但阶段 status 未推进的矛盾态，用户只能靠 verify 启动碰运气自愈）。
+      // 自愈 = 重播种：ensureStageSteps 按 def 步骤名重建步骤行（保留同名完成态），矛盾行
+      // （DB 有但 def 无的幽灵行/半写行）被清掉；重读后再走正常管线。自愈失败再报错给精确指引。
+      console.warn(`⚠️ 检测到状态机矛盾：阶段 ${stageName} 无 pending/in-progress 步骤但 status=${stageData.status}（并发写入竞争的半写态）。自动重播种修复…`)
+      try {
+        const { ensureStageSteps } = await import('./command.js')
+        const reseeded = await ensureStageSteps(progress, stageName, cwd, platformOpts?.specRoot || null)
+        if (reseeded && effectiveChange) {
+          pm._write(cwd, progress, effectiveChange)
+          progress = pm.read(cwd, effectiveChange) || progress
+        }
+        const freshSteps = progress?.stages?.[stageName]?.steps || []
+        const freshPending = freshSteps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+        if (freshPending !== -1) {
+          console.log(`✅ 重播种成功：${freshSteps.filter(s => s.status === 'pending').length} 个待完成步骤恢复，继续完成管线`)
+          currentIdx = freshPending
+          steps.length = 0
+          steps.push(...freshSteps)
+          stageData.steps = freshSteps
+        } else {
+          console.error(`重播种后仍无待完成步骤（阶段 status=${progress?.stages?.[stageName]?.status ?? '未知'}）。`)
+          console.error(`   手动修复：sillyspec run ${stageName} --reset${changeName ? ` --change ${changeName}` : ''} 从头重跑，或 sillyspec doctor 诊断。`)
+          process.exit(1)
+        }
+      } catch (e) {
+        console.error(`❌ 矛盾态自愈失败: ${e.message}`)
+        console.error(`   手动修复：sillyspec run ${stageName} --reset${changeName ? ` --change ${changeName}` : ''}，或 sillyspec doctor`)
+        process.exit(1)
+      }
     } else {
       console.error(`没有待完成的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
       process.exit(1)
@@ -222,10 +254,13 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   // ── execute deps 验证硬门（change 2026-06-28-worktree-deps-provision）──
-  await enforceDepsGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  // persist 回调：gate 置 step=blocked 后 exit(1) 前落库（否则 blocked 只在内存，
+  // progress show/doctor 看到的仍是 pending，误导诊断）
+  const persistBlocked = () => pm._write(cwd, progress, changeName)
+  await enforceDepsGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts, persistBlocked)
   // review.json 字段硬门（坑 review-json-field-gap）：已勾 [x] task 的 review.json 必须 schema 完整，
   // 提前到每次 --done 校验（而非等 Task Review Gate 在整阶段收尾才暴露，迫使用户事后批量补）。
-  await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts, persistBlocked)
   // 符号影响面报告硬门（ql-20260816-005-3d7f）：execute「加载上下文」步产出落盘核验——
   // symbol-impact.md 存在 + plan 每 task 有结论行；防前缀步被一句「上下文在会话内」盖章跳过。
   await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
@@ -594,6 +629,22 @@ async function buildDraftContext(cwd, changeName) {
   }
 }
 
+/**
+ * 预取 base..head 全量 diff 文件集（一次 git spawn），供草稿零 diff 守卫按 task 内存归属判定。
+ * 此前每草稿 task 一次 `git diff --name-only base..head -- <files>`（同一对 base..head 查 N 次，
+ * 8 task ≈ 8-16 次串行 spawn）。失败返回 null → 调用方回退逐 task 实测路径。
+ */
+function prefetchDiffFileSet(ctx) {
+  if (!ctx?.gitDir || !ctx.base || !ctx.head) return ctx
+  try {
+    const out = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`], { trim: true })
+    if (!out) return ctx
+    return { ...ctx, diffFileSet: new Set(out.split('\n').filter(Boolean)) }
+  } catch {
+    return ctx
+  }
+}
+
 /**
  * 判定 task 是否该被 autoCheckPlanFromReviews 自动勾选。
  * 端到端/deployment-critical task 要求 review spec+quality 双 pass（cannot_verify 不算，防批量完成
@@ -628,6 +679,16 @@ export function shouldAutoCheckTask(r, endToEnd, ctx = null) {
       console.warn(`⚠️ ctx 信息不完整（gitDir=${ctx.gitDir}, base=${ctx.base}, head=${ctx.head}），跳过草稿 diff 校验，保守不勾`)
       return false
     }
+    // 预取路径：一次全量 diff 文件集内存归属（autoCheckPlanFromReviews/批量路径已 prefetch）
+    if (ctx.diffFileSet) {
+      const hit = changedFiles.filter(f => ctx.diffFileSet.has(f))
+      if (hit.length === 0) {
+        console.warn(`⚠️ 草稿 review 实测 diff 为空（base=${ctx.base.slice(0, 8)}, head=${ctx.head.slice(0, 8)}, files=${changedFiles.length}），跳过自动勾选`)
+        return false
+      }
+      console.log(`   ✓ 草稿 diff 校验通过（实测 ${hit.length}/${changedFiles.length} 个声明文件有改动）`)
+      return true
+    }
     try {
       // 实测 diff：git diff --name-only <base>..<head> -- <changedFiles>
       // 用数组参数避免 shell 拆词，复用 git-helper 安全模式
@@ -650,7 +711,12 @@ async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOp
     return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
   }
   try {
-    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    // 勾选写入目标漂移锚定（坑 autocheck-worktree-tasks-lost，2026-08-23 实证：agent 在
+    // worktree 内跑 execute --done 且 drift 守卫未拦（非平台模式+无 specDriftAnchor 透传的
+    // 直调路径）时，tasks.md 勾选写进 worktree 的 .sillyspec/changes/ 副本——worktree 被
+    // cleanup 整目录删除后勾选丢失，主仓 tasks.md 停在未勾态需手动补。runtimeRoot 已走
+    // resolveRuntimeRoot（drift-aware），changeDir 同步对齐：specDriftAnchor > specRoot > cwd。
+    const specBaseLc = platformOpts?.specDriftAnchor || platformOpts?.specRoot || join(cwd, '.sillyspec')
     const changeDir = join(specBaseLc, 'changes', changeName)
     // 2026-08-20-task-truth-unify D-001@v1：勾选写入目标从 plan.md 迁 tasks.md（任务唯一真相；
     // plan.md Wave 引用行无 checkbox，无处可勾）。tasks.md 存在性作前置。
@@ -670,7 +736,7 @@ async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOp
     const executeRunId = c
 
     // W2 task-04 FR-03：构造 ctx 供草稿零 diff 守卫用（与 task-review.js generateTaskReviewDrafts 同源）
-    const ctx = await buildDraftContext(cwd, changeName)
+    const ctx = prefetchDiffFileSet(await buildDraftContext(cwd, changeName))
 
     // tasks.md 是 agent 与 CLI 都会写的共享文件（agent 勾 checkbox、此处 autoCheck 也勾选）。
     // 读-改-写必须整体持锁（withFileLock 串行化多进程），否则并发 execute --done / 手动勾选互相覆盖
@@ -748,7 +814,7 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
     }
 
     // 构造 ctx 供草稿零 diff 校验用（与 task-04 同源）
-    const ctx = await buildDraftContext(cwd, changeName)
+    const ctx = prefetchDiffFileSet(await buildDraftContext(cwd, changeName))
     const runtimeRoot = resolveRuntimeRoot({ specRoot: specBase }, specBase)
     const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
     const blockedTasks = []
@@ -783,11 +849,18 @@ async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBa
           blockedTasks.push(taskId)
           continue
         }
-        // 草稿且有 changedFiles → 实测 diff 校验（ctx 与 task-04 同源）
+        // 草稿且有 changedFiles → 实测 diff 校验（ctx 与 task-04 同源；优先用预取全量集，
+        // 免去每 task 一次 spawn——与 shouldAutoCheckTask 同口径）
         if (ctx && ctx.gitDir && ctx.base && ctx.head) {
           try {
-            const diffResult = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`, '--', ...changedFiles], { trim: true })
-            if (!diffResult || diffResult.trim() === '') {
+            let hit = null
+            if (ctx.diffFileSet) {
+              hit = changedFiles.filter(f => ctx.diffFileSet.has(f))
+            } else {
+              const diffResult = gitQuiet(ctx.gitDir, ['diff', '--name-only', `${ctx.base}..${ctx.head}`, '--', ...changedFiles], { trim: true })
+              hit = diffResult && diffResult.trim() !== '' ? changedFiles : []
+            }
+            if (hit.length === 0) {
               blockedTasks.push(taskId)
             }
           } catch (e) {