sillyspec 3.26.14 → 3.27.1

package/src/run/shared.js

@@ -17,9 +17,10 @@ import os from 'node:os'
 
 // safeGit 收口至 src/git-helper.js：import 建本地词法绑定（本模块内部 L128/130/431 调用）+
 // re-export 供 run/ 层现有调用方继续从 shared.js 引用（pure re-export 不建本地绑定，会致内部 ReferenceError）。
-import { safeGit } from '../git-helper.js'
+// unquoteGitPath 同理：parsePorcelainPath 内部消费 + re-export。
+import { safeGit, unquoteGitPath } from '../git-helper.js'
 import { createHash } from 'node:crypto'
-export { safeGit }
+export { safeGit, unquoteGitPath }
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -133,23 +134,41 @@ export function resolveSpecDir(cwd, opts = {}) {
  * 被 countAncestorSpecDirs（漂移提醒 warn）与 locateQuickSessionGuard（quick 漂移 fail-fast
  * 守卫，坑 quick-cwd-drift-splits-specdir）共用 —— 单一真相源，避免两处各自重写祖先枚举漂移。
  */
+// 祖先链 ceiling（git 主仓根）按 cwd 进程级缓存：每条 stage 命令必经（countAncestorSpecDirs
+// 漂移提醒 + quick 漂移守卫两条路径），此前固定 2 次串行 git spawn（Windows 60-200ms）。
+// 只缓存"git root 已找到"的结果——非 git 仓库不缓存，防测试流程中途 git init 后读到陈旧 null。
+const _ancestorCeilingCache = new Map()
+
+function resolveAncestorCeiling(resolved) {
+  if (_ancestorCeilingCache.has(resolved)) return _ancestorCeilingCache.get(resolved)
+  // 一次 spawn 拿两值（rev-parse 按参数序输出，每值一行）
+  const out = safeGit(resolved, ['rev-parse', '--show-toplevel', '--git-common-dir']).value
+  let ceiling = null
+  if (out) {
+    const lines = out.split('\n')
+    const topLevel = (lines[0] || '').trim()
+    if (topLevel) ceiling = resolve(topLevel)
+    const commonDir = (lines[1] || '').trim()
+    if (commonDir) {
+      const absCommonDir = resolve(resolved, commonDir)
+      if (existsSync(absCommonDir) && statSync(absCommonDir).isDirectory()) {
+        const mainRoot = dirname(absCommonDir)
+        // 主仓根是 worktree 根的祖先时取它(更靠上);monorepo/单仓两者相等不替换,行为不变
+        if (!ceiling || resolve(ceiling).startsWith(resolve(mainRoot) + sep)) ceiling = mainRoot
+      }
+    }
+  }
+  if (ceiling) _ancestorCeilingCache.set(resolved, ceiling)
+  return ceiling
+}
+
 export function ancestorSpecDirs(cwd) {
   const resolved = resolve(cwd)
   // 上界 = git root。但 linked worktree 内 --show-toplevel 返回 worktree 根(非主仓根),
   // 祖先链到不了主仓 .sillyspec → 漂移提醒/quick 守卫全哑(坑 worktree-execute-spec-drift)。
   // 复刻 worktree.js _resolveMainRepoRoot:--git-common-dir 的 dirname 才是主仓根,取更靠上者作 ceiling。
   // (git 可能返回相对路径,须 resolve(cwd, commonDir) 绝对化,否则相对 process.cwd 误解析。)
-  const topLevel = safeGit(resolved, ['rev-parse', '--show-toplevel']).value
-  let ceiling = topLevel ? resolve(topLevel) : null
-  const commonDir = safeGit(resolved, ['rev-parse', '--git-common-dir']).value
-  if (commonDir) {
-    const absCommonDir = resolve(resolved, commonDir)
-    if (existsSync(absCommonDir) && statSync(absCommonDir).isDirectory()) {
-      const mainRoot = dirname(absCommonDir)
-      // 主仓根是 worktree 根的祖先时取它(更靠上);monorepo/单仓两者相等不替换,行为不变
-      if (!ceiling || resolve(ceiling).startsWith(resolve(mainRoot) + sep)) ceiling = mainRoot
-    }
-  }
+  const ceiling = resolveAncestorCeiling(resolved)
   const dirs = []
   let dir = resolved
   while (true) {
@@ -460,8 +479,8 @@ async function raceWithAbort(op, timeoutMs = SYNC_TOTAL_TIMEOUT_MS) {
 
 // quick 会话 ID 形态（quick-<hex8>）。与 run/command.js QUICK_SID_RE、progress.js
 // initChange 的跳过实体目录判断同源；shared.js 不反向 import command.js（重模块），
-// 局部复制正则保持轻载——改形态时三处同改。
-const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
+// 局部复制正则保持轻载——改形态时三处同改（prompt.js 经本导出消费，勿再复制一份）。
+export const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
 
 export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
@@ -499,6 +518,12 @@ export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {})
  */
 const AUTO_PULL_THROTTLE_MS = 10_000
 
+// 自动 pull 专属熔断（2026-08-21 性能审查 PERF-04）：自动注入点（stage 命令分发前 / approve 前）
+// 在打印任何输出前 await，daemon 慢/挂时每 10s 窗口首条命令硬等上限即体感 hang——降为 2s。
+// 手动 `platform pull` 不经此路径（用户显式发起，等待 8s 合理）。超时语义与 8s 版一致：
+// abort 在飞请求（HUB-09），错过窗口的平台更新由下一条 >10s 命令或 push 409 自愈兜底。
+const AUTO_PULL_TIMEOUT_MS = 2_000
+
 function _autoPullThrottlePath(cwd) {
   return join(cwd, '.sillyspec', '.runtime', 'auto-pull-throttle.json')
 }
@@ -521,7 +546,7 @@ function _stampAutoPull(cwd) {
 
 /**
  * 触发 pull（下行同步，task-10 / D-009 / FR-04 / FR-06）。
- * 复用 triggerSync 的 8s 熔断与 Best Effort 语义；未连接平台静默跳过（与现状一致）。
+ * 熔断走 AUTO_PULL_TIMEOUT_MS（2s，见常量注释）与 Best Effort 语义；未连接平台静默跳过（与现状一致）。
  * 注入时机：stage 命令启动（顶层别名 + case 'run'，ql-20260818-008 补齐后者）+ 关键决策点
  * （approve 前）+ 手动 platform pull。不在每步 pull（避免高频写入与网络压力），仅低频边界点。
  * 自动注入走 skipIfLocalDirty 保守守卫：本地有未同步改动时 pull 内部跳过 import，
@@ -541,7 +566,7 @@ export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {})
     if (!sm._getPlatform()) return
     if (_autoPullRecently(cwd)) return
     _stampAutoPull(cwd)
-    await raceWithAbort((sig) => sm.pull(changeName, { skipIfLocalDirty: true, signal: sig.signal }), opts.timeoutMs)
+    await raceWithAbort((sig) => sm.pull(changeName, { skipIfLocalDirty: true, signal: sig.signal }), opts.timeoutMs ?? AUTO_PULL_TIMEOUT_MS)
   } catch (e) {
     // pull 失败静默跳过（Best Effort，失败不影响正确性）
     console.warn('⚠️ 拉取失败:', e.message)
@@ -578,10 +603,10 @@ export async function triggerPullActiveChange(cwd, platformOpts = {}) {
     // progress 不可达则跳过（Best Effort）
   }
   if (!cn) return
-  // 已确认连接 + 单活跃变更，调 pull（复用 8s 熔断 + abort（HUB-09）；skipIfLocalDirty 保守守卫
+  // 已确认连接 + 单活跃变更，调 pull（自动注入 2s 熔断 + abort（HUB-09）；skipIfLocalDirty 保守守卫
   // 同 triggerPull——本地脏时跳过 import，防平台旧快照覆盖本地领先进度，ql-20260818-008）
   try {
-    await raceWithAbort((sig) => sm.pull(cn, { skipIfLocalDirty: true, signal: sig.signal }))
+    await raceWithAbort((sig) => sm.pull(cn, { skipIfLocalDirty: true, signal: sig.signal }), AUTO_PULL_TIMEOUT_MS)
   } catch (e) {
     console.warn('⚠️ 拉取失败:', e.message)
   }
@@ -639,7 +664,10 @@ export function parsePorcelainPath(line) {
   if (!line) return ''
   let path = line.slice(3).trim()
   if (path.length >= 2 && path.startsWith('"') && path.endsWith('"')) {
-    path = path.slice(1, -1).replace(/\\(.)/g, (_, c) => c)
+    // unquoteGitPath：\\ \" \n \t 与 \NNN 八进制字节聚合 UTF-8 解码——原 \\(.) 逐字符
+    // 解引会把 "\346\226\207.md" 拆成 "346226207.md"。git-helper 已统一 core.quotepath=false
+    // （非 ASCII 路径裸输出），此处兜底仍会被引号转义的路径（含控制字符等）。
+    path = unquoteGitPath(path.slice(1, -1))
   }
   const arrow = path.indexOf(' -> ')
   if (arrow !== -1) path = path.slice(arrow + 4)

package/src/run/stage.js

@@ -17,7 +17,7 @@
  *   - 'child_process'（execSync）裸模块名不变
  */
 import { join, dirname } from 'node:path'
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
@@ -122,7 +122,7 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         throw new Error(`execute run 目录创建失败（${join(runtimeRoot, 'execute-runs', currentExecuteRunId)}）: ${e.message}；` +
           `请检查该路径是否为普通文件/只读，清理后重跑（sillyspec run execute --change ${changeName} --skip-approval）`)
       }
-      writeFileSync(runIdFile, currentExecuteRunId + '\n')
+      writeAtomicSync(runIdFile, currentExecuteRunId + '\n')
       // change 归属戳（坑 worktree-cleanup-marker-chain 根治）：run 目录自带变更身份，
       // marker 断裂（worktree cleanup / 归档清理 / 并行误删）后按戳归属，不再错配其他变更的 run
       const { stampExecuteRunChange } = await import('../task-review.js')
@@ -130,6 +130,38 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     }
   }
 
+  // ── 跨变更文件冲突预警（坑 cross-change-conflict-no-warning，2026-08-22 实证：并行变更改
+  // 同一文件靠人工发现——f578a08e 的「锚点更新」是好实践但工具无预警）。execute 启动时把本变更
+  // 的 diff 文件集与其他活跃变更的 diff 文件集求交集，advisory warn 交集与对端变更名 + 锚点
+  // 更新提示。best-effort：任何异常静默跳过（预警不阻断 execute 启动）。
+  if (stageName === 'execute' && changeName) {
+    try {
+      const { resolveVerifyChangedFiles } = await import('../verify-postcheck.js')
+      const activeChanges = (pm.listChanges(cwd) || []).filter(c => c && c !== changeName)
+      if (activeChanges.length > 0) {
+        const myFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
+        const mySet = new Set(myFiles.map(f => f.replace(/\\/g, '/')).filter(f => !f.startsWith('.sillyspec/')))
+        if (mySet.size > 0) {
+          const conflicts = []
+          for (const other of activeChanges) {
+            const otherFiles = resolveVerifyChangedFiles(cwd, other, null, { includeWorkingTree: true }) || []
+            const overlap = [...new Set(otherFiles.map(f => f.replace(/\\/g, '/')))]
+              .filter(f => mySet.has(f))
+            if (overlap.length > 0) conflicts.push({ other, overlap })
+          }
+          if (conflicts.length > 0) {
+            console.warn(`⚠️ 跨变更文件冲突预警：本变更（${changeName}}）与其他活跃变更改动重叠——`)
+            for (const c of conflicts) {
+              console.warn(`   与 ${c.other} 重叠 ${c.overlap.length} 个文件：${c.overlap.slice(0, 5).join(', ')}${c.overlap.length > 5 ? ` …（共 ${c.overlap.length}）` : ''}`)
+            }
+            console.warn(`   并行 apply/归档时重叠文件会互相覆盖或冲突。实践：后完成方在其 verify/design 里记录「锚点更新」`)
+            console.warn(`  （说明基于对方已合入的版本重新锚定），并考虑串行化这两个变更的 apply。`)
+          }
+        }
+      }
+    } catch { /* 预警失败不阻断 execute */ }
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
@@ -207,7 +239,9 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       }
       const guardFile = join(specBase, '.runtime', 'scan-guard.json')
       mkdirSync(dirname(guardFile), { recursive: true })
-      writeFileSync(guardFile, JSON.stringify(scanGuard, null, 2) + '\n')
+      // 原子写：hook 进程（worktree-guard 的 readScanGuard）并发读，裸 truncate→write 的
+      // 半截窗口会被 JSON.parse 吞成 null → 覆盖保护静默失效（fail-open）
+      writeAtomicSync(guardFile, JSON.stringify(scanGuard, null, 2) + '\n')
       if (scanGuard.forceRescan) {
         console.log('🛡️ scan 覆盖保护已记录: --force-rescan 已开启')
       } else {

package/src/scan-postcheck.js

@@ -5,10 +5,11 @@
  * 平台模式下必须通过所有 check 才能 success，否则降级。
  */
 
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, renameSync, rmdirSync } from 'fs'
 import { join, basename } from 'path'
 import { SCAN_STATUS, CHECK_SEVERITY, SCAN_REQUIRED_DOCS, SCAN_REQUIRED_DOCS_QUICK } from './constants.js'
 import { validateScriptCommands } from './stages/cmd-existence.js'
+import { git } from './git-helper.js'
 
 const REQUIRED_SCAN_DOCS = SCAN_REQUIRED_DOCS
 
@@ -112,7 +113,7 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {},
     checks.push({
       name: 'docs_missing_header',
       severity: CHECK_SEVERITY.WARNING,
-      detail: `${docsMissingHeader.length} 份文档缺少 author/created_at: ${docsMissingHeader.join(', ')}`
+      detail: `${docsMissingHeader.length} 份文档缺少 author/created_at: ${docsMissingHeader.join(', ')}（sillyspec scan-fix-headers 一键补齐）`
     })
   }
 
@@ -369,3 +370,142 @@ export function printScanPostCheckResult(result) {
   }
   console.log(`  📋 最终状态: ${result.status}`)
 }
+
+/**
+ * scan 文档 header 幂等补填（2026-08-21 agent-手工产出审计第三批 E3）。
+ *
+ * runScanPostCheck 对缺 author/created_at 只 warning，agent 手改常忘——本函数补齐：
+ * author = git user.name（回退 unknown），created_at = 当前时间。已有两键的文件不动；
+ * 有 frontmatter（--- 开头）就地插缺失键，无则补一段 frontmatter。
+ * `sillyspec scan-fix-headers [--project <名>]` 入口；与 runScanPostCheck 的
+ * 「头部 512 字符含 author:/created_at:」判定口径一致。
+ *
+ * @param {{ cwd: string, specDir?: string|null, project?: string|null }} opts
+ * @returns {{ fixed: string[], skipped: string[] }}
+ */
+export function fixScanDocHeaders({ cwd, specDir = null, project = null }) {
+  const specBase = specDir ? specDir : join(cwd, '.sillyspec')
+  const docsRoot = join(specBase, 'docs')
+  const projects = project
+    ? [project]
+    : (existsSync(docsRoot) ? readdirSync(docsRoot, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) : [])
+
+  let author = 'unknown'
+  try {
+    author = git(cwd, ['config', 'user.name']) || 'unknown'
+  } catch { /* git 不可用 → unknown */ }
+  const now = new Date().toISOString().slice(0, 19).replace('T', ' ')
+
+  const fixed = []
+  const skipped = []
+  for (const p of projects) {
+    const scanDir = join(docsRoot, p, 'scan')
+    if (!existsSync(scanDir)) continue
+    for (const f of readdirSync(scanDir)) {
+      if (!f.endsWith('.md')) continue
+      const filePath = join(scanDir, f)
+      let content
+      try {
+        content = readFileSync(filePath, 'utf8')
+      } catch {
+        continue
+      }
+      const header = content.slice(0, 512)
+      const hasAuthor = /author\s*:/.test(header)
+      const hasCreated = /created_at\s*:/.test(header)
+      if (hasAuthor && hasCreated) {
+        skipped.push(filePath)
+        continue
+      }
+      const inserts = []
+      if (!hasAuthor) inserts.push(`author: ${author}`)
+      if (!hasCreated) inserts.push(`created_at: ${now}`)
+      let newContent
+      if (content.startsWith('---\n') || content.startsWith('---\r\n')) {
+        // 有 frontmatter：插到开标签后（CRLF 归一写回，与其它 CLI 写入口径一致）
+        const normalized = content.replace(/\r\n?/g, '\n')
+        newContent = normalized.replace(/^---\n/, `---\n${inserts.join('\n')}\n`)
+      } else {
+        newContent = `---\n${inserts.join('\n')}\n---\n\n` + content
+      }
+      try {
+        writeFileSync(filePath, newContent)
+        fixed.push(filePath)
+      } catch { /* 只读文件等写失败 → 跳过不抛 */ }
+    }
+  }
+  return { fixed, skipped }
+}
+
+/**
+ * source_root 污染一键修复（2026-08-21 agent-手工产出审计第四批 C-3）。
+ *
+ * runScanPostCheck 对「agent 把产物写到 <source_root>/.sillyspec/ 而非平台 specRoot」只报
+ * FAILED 不修——agent 手工搬目录常搬错。本函数把检查枚举的同款清单（docs/projects/workflows/
+ * knowledge 目录 + manifest.json/local.yaml）搬到 specRoot 对应位置（已存在的不覆盖，报告
+ * skipped），搬完源目录若空则删除。与检查的路径口径逐字一致（pollutePaths/polluteFiles）。
+ *
+ * @param {{ cwd: string, specDir: string }} opts cwd=source_root，specDir=平台 spec_root 绝对路径
+ * @returns {{ moved: string[], skipped: string[], removedDirs: string[] }}
+ */
+export function fixSourceRootLeak({ cwd, specDir }) {
+  if (!cwd || !specDir) return { moved: [], skipped: [], removedDirs: [] }
+  const moved = []
+  const skipped = []
+  const removedDirs = []
+  const pollutePaths = ['docs', 'projects', 'workflows', 'knowledge']
+  const polluteFiles = ['manifest.json', 'local.yaml']
+
+  // 目标目录确保存在
+  try { mkdirSync(join(specDir, '.runtime'), { recursive: true }) } catch {}
+
+  for (const file of polluteFiles) {
+    const src = join(cwd, '.sillyspec', file)
+    const dst = join(specDir, file)
+    if (!existsSync(src)) continue
+    if (existsSync(dst)) {
+      skipped.push(`local.yaml 已存在于 specRoot（保留两份，人工合并凭据后删源）`.replace('local.yaml', file))
+      continue
+    }
+    try {
+      renameSync(src, dst)
+      moved.push(`.sillyspec/${file} → specRoot/${file}`)
+    } catch (e) {
+      skipped.push(`.sillyspec/${file} 搬移失败: ${e.message}`)
+    }
+  }
+
+  for (const sub of pollutePaths) {
+    const srcDir = join(cwd, '.sillyspec', sub)
+    if (!existsSync(srcDir)) continue
+    let entries = []
+    try { entries = readdirSync(srcDir, { withFileTypes: true }) } catch { continue }
+    if (entries.length === 0) {
+      try { rmdirSync(srcDir); removedDirs.push(`.sillyspec/${sub}/（空目录）`) } catch {}
+      continue
+    }
+    const dstDir = join(specDir, sub)
+    mkdirSync(dstDir, { recursive: true })
+    let allMoved = true
+    for (const e of entries) {
+      const src = join(srcDir, e.name)
+      const dst = join(dstDir, e.name)
+      if (existsSync(dst)) {
+        skipped.push(`.sillyspec/${sub}/${e.name}（specRoot 已有同名，不覆盖——人工比对后择一保留）`)
+        allMoved = false
+        continue
+      }
+      try {
+        renameSync(src, dst)
+        moved.push(`.sillyspec/${sub}/${e.name} → specRoot/${sub}/${e.name}`)
+      } catch (err) {
+        skipped.push(`.sillyspec/${sub}/${e.name} 搬移失败: ${err.message}`)
+        allMoved = false
+      }
+    }
+    if (allMoved) {
+      try { rmdirSync(srcDir); removedDirs.push(`.sillyspec/${sub}/`) } catch {}
+    }
+  }
+  return { moved, skipped, removedDirs }
+}

package/src/stage-contract-spec.js

@@ -330,7 +330,7 @@ const PLAN_RULES = [
     id: 'plan.task-plan-reconciliation', stage: 'plan', source: 'validateBlueprintConsistency', severity: 'error', kind: 'task-plan-reconciliation',
     target: { root: 'change', path: 'tasks' },
     data: {
-      messageMissingCards: 'plan.md 声明了 ${declared} 个任务，但 tasks/ 只有部分卡片。缺卡: ${missing}\n   无卡片的任务不进 Wave、不受 execute 审计（allowed_paths/review.json 都不覆盖）→ 必然漏做（典型：尾部文档同步类任务）。\n   修复：为每个缺卡任务补 task-NN.md（含 allowed_paths/验收标准），或从 plan.md 删除该任务。',
+      messageMissingCards: 'plan.md 声明了 ${declared} 个任务，但 tasks/ 只有部分卡片。缺卡: ${missing}\n   无卡任务的 allowed_paths/review.json 都不覆盖，不进 Wave、不受 execute 审计 → 必然漏做（典型：尾部文档同步类任务）。\n   修复：跑 sillyspec taskcard <change> --all 一键补齐全部缺卡安全骨架（已存在的卡不动，之后填充语义字段），或从 tasks.md 删除该任务声明。',
       messageOrphanCards: 'tasks/ 存在 plan.md 未声明的卡片: ${orphans}\n   这些任务不进任何 Wave，execute 不会执行。修复：在 plan.md 补声明，或删除孤儿卡片。',
     },
     spec: 'plan.md 中声明的每个 task-NN 必须有对应 tasks/task-NN.md 卡片（反向亦然），否则阻断——无卡片任务不受 execute 审计，必然漏做。',

package/src/stage-contract.js

@@ -480,7 +480,20 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
         warnings.push(`[${changeRiskProfile.level}] 结论 PASS WITH NOTES：design frontmatter 显式声明 risk_level=${changeRiskProfile.level}，残留项须为真实集成证据缺口，并在 verify-result.md 如实说明`)
       }
       if (requiresEvidence) {
-        const evidenceCheck = checkIntegrationEvidence(verify, changeRiskProfile.requiredVerification)
+        // CLI 回执注入（坑 verify-literal-evidence-mismatch，2026-08-22 实证：证据第一轮就齐
+        // 但自然措辞不含字面词被误拦三轮）：verify 服务回收器落的回执 = 真实启动+PID 登记
+        // 的结构化证据，作为附加匹配文本——有回执不依赖 agent 措辞；无回执维持原字面匹配
+        let receiptText = ''
+        try {
+          const receiptPath = join(cwd, '.sillyspec', '.runtime', 'verify-services.receipt.json')
+          if (existsSync(receiptPath)) {
+            const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'))
+            if (receipt && (receipt.reapedPidCount || 0) > 0 && (!receipt.change || receipt.change === changeName)) {
+              receiptText = `CLI 回执：verify 服务进程已回收 ${receipt.reapedPidCount} 个（PID 已登记，真实启动，运行时证据 reapedAt=${receipt.reapedAt}）`
+            }
+          }
+        } catch { /* 回执损坏按无回执处理（fail 回原字面匹配） */ }
+        const evidenceCheck = checkIntegrationEvidence(verify, changeRiskProfile.requiredVerification, { extraEvidenceText: receiptText })
         if (!evidenceCheck.ok) {
           // A: 报错说人话 —— 把「缺哪一项、要写/做什么、判级原因」逐条列出，
           // 让 agent 不必靠改结论文案撞墙。detail 指明真实启动须是本变更实际改动的

package/src/stage-review.js

@@ -65,9 +65,12 @@ export function renderReviewJsonContract({ stage, changeDir, reviewRunId, tier }
     '- `checklist`(可选): 扁平数组 —— 每项 { item: string, result: ∈ { ' + CHECKLIST_RESULTS.join(' / ') + ' }, note?: string }。注意是**扁平数组**,不是按层(定义/一致/可行性)嵌套对象',
     '- `reviewerNotes`: 说明(verdict=fail 时写明阻断项)',
     '',
-    '### docHash 算法(必须等于 reviewedFiles[0] 的 sha256)',
-    "- node: `crypto.createHash('sha256').update(require('fs').readFileSync(reviewedFiles[0])).digest('hex')`(对原始字节)",
-    '- shell: `sha256sum <reviewedFiles[0]>` 取首列(hex)',
+    '### docHash(一键代填,勿手算)',
+    '- **推荐**:docHash 先占位(如 `"TODO"`),review.json 写完后跑',
+    '  `sillyspec register-stage-review --change <变更名> --stage ' + stageLbl + ' --refresh-hash`',
+    '  —— CLI 重算真实 sha256 代填,verdict/checklist 原样保留;主文档改版后同样跑这条',
+    '  (多阶段联动用 `--all` 一次处理)。gate 拦 docHash 失配时也是同一条命令修复。',
+    '- 兜底手算口径(极端无 CLI 场景):node `crypto.createHash(\'sha256\').update(readFileSync(...))` (原始字节)/ `sha256sum <file>` 首列 hex。',
     '- ⚠️ **review.json 写入后若 ' + mainDoc + ' 再被改,必须重算 docHash** —— gate 会重算 reviewedFiles[0] 的 sha256 比对,不符判伪造(历史翻车根因:design 改了 rev 后 docHash 仍是旧值)',
     '',
     '### 完整 JSON 示例(照抄改值)',
@@ -209,8 +212,9 @@ export function verifyStageReviewDocHash(review, searchDirs) {
     if (claimed !== actualRaw.toLowerCase() && claimed !== actualLf.toLowerCase()) {
       errors.push(
         `docHash 与主审查文档 ${primaryRel} 的实际内容不匹配。` +
-        `若刚改过该文档（如 design 修订后忘重算），重算并更新 review.json 的 docHash 字段：` +
-        `在基准目录 ${base} 下运行 sha256sum "${primaryRel}" 取首列 hex 填入；` +
+        `若刚改过该文档（如 design 修订后忘重算），一键修复：` +
+        `sillyspec register-stage-review --change <变更名> --stage <阶段> --refresh-hash` +
+        `（CLI 重算 docHash 代填，verdict 保留；多阶段联动加 --all）；` +
         `若未改文档，则 review.json 疑似伪造（未真正读取文档）。`
       )
       return { ok: false, errors, warnings }
@@ -414,7 +418,7 @@ export function validateStageReview(opts) {
  * @param {object} context - { stage, reviewRunId } 用于错误提示路径
  */
 export function printStageReviewResult(result, context = {}) {
-  const { stage, reviewRunId, runtimeRoot } = context
+  const { stage, reviewRunId, runtimeRoot, changeName } = context
   if (result.ok && result.warnings.length === 0) {
     console.log(`\n✅ Stage Review Gate — ${stage} 阶段独立审查通过`)
     return
@@ -435,6 +439,11 @@ export function printStageReviewResult(result, context = {}) {
     }
     console.error(`\n   提示：tier=independent 要求独立审查子代理产出 review.json，补全后重新 --done`)
     console.error(`   可用 sillyspec register-stage-review --change <名> --stage ${stage} [--from <已有review.json>] 一步生成 run 目录 + review.json 骨架（docHash 自动算）+ 写 marker + 自检，省掉手动建目录/写 marker`)
+    // docHash 失配精确指路（2026-08-21 agent-手工产出审计项②）：改版后忘重算是最高频失败，
+    // 一键重算命令带上真实 change 名，agent 可直接照抄执行（--refresh-hash 保 verdict）。
+    if (result.errors.some(e => String(e).includes('docHash')) && changeName) {
+      console.error(`   docHash 失配修复：sillyspec register-stage-review --change ${changeName} --stage ${stage} --refresh-hash（主文档改版多阶段联动用 --all）`)
+    }
   }
 
   if (result.warnings.length > 0) {

package/src/stages/archive.js

@@ -36,7 +36,7 @@ export const definition = {
 5. module-impact.md 第一行标题必须用中文：# 模块影响分析（Module Impact）— <变更简述>
 
 ### 降级（module-impact.md 不存在）
-若缺失（如旧变更未经新 plan 流程，或 small 变更从未生成），按原生成逻辑补一份：读 .sillyspec/workflows/archive-impact.yaml 的 impact-analyzer 角色规则 + git diff + _module-map.yaml，生成模块影响矩阵（模块 × 影响类型 × 相关文件 × 更新摘要 × needs_review，未匹配文件归入 unmapped 表）落盘 module-impact.md。
+若缺失（如旧变更未经新 plan 流程，或 small 变更从未生成）：先跑 \`sillyspec module-impact --change <change-name>\`——CLI 按 _module-map.yaml paths 前缀匹配预填「模块影响矩阵」骨架（文件×模块归属 + 未匹配文件清单，机械部分全代算），你只需逐行填「影响类型」（逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增）与 needs_review 标记，补首行中文标题 \`# 模块影响分析（Module Impact）— <变更简述>\`。骨架无从生成（无 module-map / 无 diff）时才按 archive-impact.yaml 的 impact-analyzer 角色规则全手写。
 
 确认完成后，下一步 sync-module-docs 会读 module-impact.md 更新模块卡片文档。`,
       outputHint: 'module-impact.md 终审结果 + 修正摘要',
@@ -82,12 +82,14 @@ export const definition = {
 3. 如果标记缺失或重复 → 在 _module-map.yaml 中标记 needs_review: true
 
 #### 新建模块卡片模板
-一级标题格式 \`# <中文名>（<module-id>）\`——中文名从模块职责提炼 2-8 字，括号内保留 module-id 原样（sillyhub 平台解析识别用，与 scan 生成约定一致）。
+一级标题格式 \`# <中文名>（<module-id>）\`——中文名从模块职责提炼 2-8 字，括号内保留 module-id 原样（sillyhub 平台解析识别用，与 scan 生成约定一致）。frontmatter 已带 author/created_at 真值（<git-user>/<now-datetime> 占位符由 CLI 每步替换），照抄即过元数据校验、勿删。
 \`\`\`markdown
 ---
 schema_version: 1
 doc_type: module-card
 module_id: <module-id>
+author: <git-user>
+created_at: <now-datetime>
 ---
 
 # <中文名>（<module-id>）

package/src/stages/brainstorm.js

@@ -45,6 +45,7 @@ export const definition = {
 7. 检查全局模板：\`ls ~/.sillyspec/templates/\`
    - 有匹配模板 → 询问是否基于模板
    - 无相关内容 → 跳过，不输出
+8. 查询知识库：\`cat {SPEC_ROOT}/knowledge/INDEX.md 2>/dev/null\`（无索引则跳过）——按需求关键词命中条目时读取对应知识文件；known-issues/已知坑要在方案期就规避，不要等 execute 的命中报告才发现
 
 ### 模块匹配方法
 读取 _module-map.yaml 后，根据用户描述的需求关键词，匹配相关模块：