sillyspec 3.26.14 → 3.26.15

package/src/run/complete-handlers.js

@@ -283,7 +283,10 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     const alreadyArchivedDir = findAlreadyArchivedDir(archiveDir, archiveChangeName)
     if (alreadyArchivedDir) {
       console.log(`ℹ️  源目录不存在但变更已在 archive/（${basename(alreadyArchivedDir)}），判定已归档，自愈进度 DB`)
-      pm.unregisterChange(cwd, archiveChangeName)
+      // 终态一致化（坑 manual-archive-desync-status-only）：手动搬目录绕过标准归档后，本自愈路径
+      // 不能只翻 status——同时收尾 archive 阶段（steps/stages/current_stage），否则推送平台的终态
+      // 是「已归档 + 归档 0/5 + 停在 execute」的矛盾体，详情页渲染成「进度丢失」
+      pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
       await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
       console.log(`📦 已自愈归档：${archiveChangeName} → archive/${basename(alreadyArchivedDir)}/`)
       return alreadyArchivedDir
@@ -332,7 +335,9 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     process.exit(1)
   }
 
-  pm.unregisterChange(cwd, archiveChangeName)
+  // 正常路径同样走终态一致化（坑 manual-archive-desync-status-only）：标准 --done --confirm 流程
+  // 中 completeStep 随后也会逐项完成，此处先收尾是幂等写同值——保证任何走出本函数的归档终态一致
+  pm.unregisterChange(cwd, archiveChangeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
 
   // CLI 下沉 git add（坑4，FR-04）：确定性暂存归档目录 + 模块文档，不靠 step5 prompt 驱动。
   // step5 prompt 的 git add 保留作幂等兜底；POSIX 路径跨平台（git 接受正斜杠）。
@@ -343,6 +348,53 @@ export async function archiveChangeDirectory(pm, cwd, progress, specBase, platfo
     safeGit(cwd, ['add', '--', '.sillyspec/docs/'])
   } catch {}
 
+  // ── 他者半归档残留探测（坑 archive-other-residual-rename，2026-08-21 实证）──
+  // 并行变更的手动归档把 R 残留（源目录 rename 目标行）留在暂存区；本变更归档提交时
+  // git status 显示它们，agent 会误判「还没提交完 / 要做第二次提交」。区分：
+  //   本变更：未暂存的源侧移动（` D changes/<me>/...` + 未跟踪 archive/<me>/...）→ 补暂存
+  //           让归档成单次原子提交；
+  //   他者：已暂存的 rename（`R  changes/<他人>/... -> changes/archive/<他人>/...`）→ 只 warn
+  //         提示归属（不 stage 不动——别人的归别人的）。
+  try {
+    const raw = gitQuiet(cwd, ['status', '--porcelain'], { trim: false, timeout: 30000 })
+    if (raw && raw.trim()) {
+      const changesPrefix = '.sillyspec/changes/'
+      const minePaths = []
+      const othersResidual = []
+      for (const line of raw.split('\n')) {
+        if (!line || line.length < 4) continue
+        const x = line[0], y = line[1]
+        const body = line.slice(3).trim()
+        const arrow = body.indexOf(' -> ')
+        const src = arrow !== -1 ? body.slice(0, arrow).replace(/^"|"$/g, '') : null
+        const dst = (arrow !== -1 ? body.slice(arrow + 4) : body).replace(/^"|"$/g, '')
+        if (x === 'R' && y === ' ' && arrow !== -1 && dst.startsWith(changesPrefix + 'archive/')) {
+          // 已暂存 rename → 半归档残留；按目标目录名归属他者变更
+          const m = /^\.sillyspec\/changes\/archive\/([^/]+)\//.exec(dst)
+          const owner = m ? m[1] : '?'
+          if (owner !== archiveChangeName) othersResidual.push(owner)
+        } else if (x === ' ' && (y === 'D' || y === 'A' || y === 'M')) {
+          // 未暂存的源侧移动：源目录 D / 新位置 A——指向本变更的补暂存
+          const p = dst || src
+          if (p && (p.startsWith(changesPrefix + archiveChangeName + '/')
+                    || p.startsWith(changesPrefix + 'archive/' + archiveChangeName + '/'))) {
+            minePaths.push(p)
+          }
+        }
+      }
+      if (minePaths.length > 0) {
+        try { safeGit(cwd, ['add', '-A', '--', changesPrefix]) } catch {}
+        console.log(`🧾 已补暂存本变更归档的源侧移动（${minePaths.length} 项，归档成单次原子提交）`)
+      }
+      if (othersResidual.length > 0) {
+        const owners = [...new Set(othersResidual)].filter(Boolean)
+        console.warn(`⚠️  检测到「他者半归档」残留（暂存区存在其他变更的 rename 记录）：${owners.join('、')}`)
+        console.warn(`   这些是别的变更此前手动归档留下的暂存项，不属于本次归档——git status 里看到它们是正常的，`)
+        console.warn(`   本变更归档已完成，无需为其做第二次提交；如需清理走它们自己的收尾（或 git restore --staged 后核对）。`)
+      }
+    }
+  } catch { /* 探测失败不阻断归档（advisory） */ }
+
   // 归档时清理可能残留的 worktree（自愈路径也复用，见上方 srcDir 缺失分支）。
   await archiveWorktreeCleanup(cwd, archiveChangeName, specBase, platformOpts)
 
@@ -1037,7 +1089,8 @@ async function closeSingleQuickLinkedChange({ pm, cwd, specBase, changeName, pla
     return { closed: false, reason: `移动目录失败：${e.message}` }
   }
 
-  pm.unregisterChange(cwd, changeName)
+  // 终态一致化同标准归档（坑 manual-archive-desync-status-only）：轻量归档路径不能只翻 status
+  pm.unregisterChange(cwd, changeName, { archiveStepNames: typeof pm.archiveStepNamesForArchive === 'function' ? pm.archiveStepNamesForArchive() : null })
   await archiveWorktreeCleanup(cwd, changeName, specBase, platformOpts)
   safeGit(cwd, ['add', '--', `.sillyspec/changes/archive/${destName}/`])
 

package/src/run/complete.js

@@ -456,7 +456,7 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
         console.log(`\n${summary}`)
       } catch (e) {
         // summary 失败不影响主流程
-        console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
+        console.log(`\n👉 下一步：sillyspec run verify${changeName ? ` --change ${changeName}` : ''}（验证通过后才能归档）`)
       }
     } else if (stageName === 'archive') {
       console.log('\n👉 归档完成！现在可以提交了：git commit -m "..."')
@@ -534,12 +534,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     // 易被 tail 截断），agent 常到 --done 被拦才第一次见到模板。推进到末步的此刻用底部短块预告
     // 模板 + 可照抄命令，省一轮拦截往返（拦截路径保留兜底）。
     if (stageName === 'quick' && nextPendingIdx === steps.length - 1) {
-      console.log(`\n📌 本步是 quick 末步：--done 的 --output 必须含四字段（CLI 硬校验，缺任一项会被拒、补全重跑不丢进度）。预告模板：`)
-      console.log(`   sillyspec run quick --done${changeName ? ` --change ${changeName}` : ''} --output "需求：一句话语义化短标题（即 QUICKLOG 条目标题）`)
-      console.log(`   根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
-      console.log(`   方案：怎么改的`)
-      console.log(`   结果：验证情况（测试数 / lint / typecheck / 部署状态）"`)
-      console.log(`   四字段逐项一句话、不可「见前述」；可选 --file-notes "path::括注 || path2" 落多行文件括注`)
+      console.log(`\n📌 本步是 quick 末步：--done 必须给全四字段（CLI 硬校验，缺任一项会被拒、补全重跑不丢进度）。推荐四参数形式（CLI 自动合成，无格式事故面）：`)
+      console.log(`   sillyspec run quick --done${changeName ? ` --change ${changeName}` : ''} --req "一句话语义化短标题（即 QUICKLOG 条目标题）" --cause "为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"`)
+      console.log(`   兼容旧形式：--output "需求：… 根因：… 方案：… 结果：…"（四字段逐项一句话、不可「见前述」，正文内禁嵌套全角冒号）；可选 --file-notes "path::括注 || path2" 落多行文件括注`)
     }
   }
   return { stageCompleted: false, currentIdx, nextPendingIdx }

package/src/run/gates.js

@@ -65,9 +65,43 @@ export function validateSymbolImpactReport({ reportContent, planContent }) {
   for (const id of missing) {
     errors.push(`${id} 未在 symbol-impact.md 中出现——每个 task 都要有一行结论（含「无签名级变更」的显式声明）`)
   }
+  // 防骨架直接过门（2026-08-21 agent-手工产出审计项⑤）：CLI 会代生成逐 task TODO 骨架
+  //（generateSymbolImpactSkeleton），占位未替换即拦——骨架消灭的是「从零手写/漏 task」错误面，
+  // 不是把「逐 task 结论」本身变成走过场。
+  const report = String(reportContent)
+  const todoPending = taskIds.filter(id => new RegExp(`^[-*]\\s*${id}[^\\n]*<!--TODO-->`, 'm').test(report))
+  for (const id of todoPending) {
+    errors.push(`${id} 的结论仍是骨架 <!--TODO--> 占位——替换为真实结论（无签名级变更也显式写「无」）`)
+  }
   return { ok: errors.length === 0, errors }
 }
 
+/**
+ * 生成 symbol-impact.md 逐 task TODO 骨架（2026-08-21 审计项⑤「报错即生成」）。
+ *
+ * gate 此前只报错不代填 → agent 从零手写整份报告，忘一个 task 就被拦、再补再撞。
+ * 骨架从 tasks.md 注册表生成逐 task 占位行，agent 只需逐行填结论；占位 <!--TODO-->
+ * 由 validateSymbolImpactReport 拒绝，骨架不能直接过门（防偷懒）。
+ *
+ * @param {string} tasksContent - 任务注册表（tasks.md，回退 plan.md）内容
+ * @returns {string|null} 骨架全文（LF）；注册表无 task 行 → null
+ */
+export function generateSymbolImpactSkeleton(tasksContent) {
+  const taskIds = extractTaskIdsFromRegistry(tasksContent)
+  if (taskIds.length === 0) return null
+  const lines = [
+    '# 符号影响面报告',
+    '',
+    '> 骨架由 CLI 生成（`sillyspec symbol-impact --change <变更名>`，gate 失败时也会自动落一份）。',
+    '> 逐行把 `<!--TODO-->` 替换为真实结论：涉及签名级变更（构造函数参数/接口/DTO/方法签名增删改）',
+    '> 写变更类型 + 受影响调用点 + 是否在任务范围内；无签名级变更也要显式写「无签名级变更」。',
+    '> **gate 拒绝仍含 <!--TODO--> 的行**——骨架不能直接过门。',
+    '',
+  ]
+  for (const id of taskIds) lines.push(`- ${id}: <!--TODO-->`)
+  return lines.join('\n') + '\n'
+}
+
 /**
  * 符号影响面报告硬门：execute「加载上下文」步 --done 时校验 symbol-impact.md 落盘 + task 覆盖度。
  * fail-closed：不通过 → 当前步标 blocked + exit 1（进度不推进）。非目标步骤/阶段直接放行。
@@ -88,7 +122,19 @@ export async function enforceSymbolImpactGate(stageName, changeName, currentStep
   console.error(`   「加载上下文」步的符号影响面检查报告未落盘或不完整：`)
   console.error(`   期望路径：${reportPath}`)
   for (const e of result.errors) console.error(`   • ${e}`)
-  console.error('   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论（无签名级变更也要显式写「无」），落盘后重跑 execute --done。')
+  // 报错即生成（2026-08-21 审计项⑤）：报告缺失时自动落一份逐 task TODO 骨架，agent 从
+  // 「从零手写整份」变「逐行填结论」；TODO 占位由 validate 拒绝，骨架不能直接过门。
+  let skeletonNote = ''
+  if (!existsSync(reportPath)) {
+    const skeleton = generateSymbolImpactSkeleton(tasksContent)
+    if (skeleton) {
+      try {
+        writeFileSync(reportPath, skeleton)
+        skeletonNote = `\n   📄 已代生成逐 task 骨架：${reportPath}（逐行替换 <!--TODO--> 为结论，无签名级变更也显式写「无」）`
+      } catch { /* 写失败只影响提示，不掩盖原始错误 */ }
+    }
+  }
+  console.error(`   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论后重跑 execute --done。${skeletonNote}`)
   process.exit(1)
 }
 
@@ -195,7 +241,7 @@ export async function enforceAlignExecuteReviewGate({ cwd, changeName, specBase,
       }
       const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
       const reviewResult = validateStageReview({ stage: 'execute', reviewType: 'acceptance', runtimeRoot, reviewRunId, searchDirs })
-      printStageReviewResult(reviewResult, { stage: 'execute', reviewRunId, runtimeRoot })
+      printStageReviewResult(reviewResult, { stage: 'execute', reviewRunId, runtimeRoot, changeName })
       if (!reviewResult.ok) return true // printStageReviewResult 已给明细，不再重复列
     }
   } catch (e) {
@@ -292,6 +338,18 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
  */
 export async function enforceReviewJsonGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts) {
   if (stageName !== 'execute' || !changeName) return true
+  // head 锡点自动落盘（2026-08-21 审计项③，D-010 补对称）：跨仓 task base_commit 已在派发时
+  // CLI 落盘，head_commit 此前靠主 agent 按 prompt 手跑 rev-parse 手写（漏抄/抄错炸 review gate）。
+  // 每次 --done 时机幂等补齐（已存在不覆盖）。best-effort：失败只 warn，不阻断 --done 主流程。
+  try {
+    const { stampCrossRepoHeadCommits } = await import('../stages/execute.js')
+    const stamped = await stampCrossRepoHeadCommits({ changeName, cwd, specBase, platformOpts })
+    if (stamped && stamped.stamped > 0) {
+      console.log(`📌 已自动落盘跨仓 task head_commit 锡点：${stamped.stampedTasks.join(', ')}（幂等，此后 --done 不再重复写）`)
+    }
+  } catch (e) {
+    console.warn(`⚠️ head_commit 锡点自动落盘失败（降级留给 agent 手写）: ${e.message}`)
+  }
   const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
   const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
   const planPath = join(specBase, 'changes', changeName, 'plan.md')
@@ -340,7 +398,7 @@ export async function enforceReviewJsonGate(stageName, cwd, changeName, step, st
     console.error(`   • ${f.taskId}（${kindLabel}）: ${f.reviewPath}`)
     for (const e of f.errors) console.error(`       - ${e}`)
   }
-  console.error('   修复：补全上述 review.json 字段后重跑 execute --done。')
+  console.error('   修复：mechanics 字段（base/head/changedFiles/schemaVersion）缺错可跑 sillyspec backfill-reviews --change ' + changeName + ' --adopt 一键代填（verdict 保留）；verdict/证据缺失需人工补全后重跑 execute --done。')
   process.exit(1)
 }
 
@@ -531,7 +589,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           : 'acceptance'
         const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
         const reviewResult = validateStageReview({ stage: stageName, reviewType, runtimeRoot, reviewRunId, searchDirs })
-        printStageReviewResult(reviewResult, { stage: stageName, reviewRunId, runtimeRoot })
+        printStageReviewResult(reviewResult, { stage: stageName, reviewRunId, runtimeRoot, changeName })
         if (!reviewResult.ok) {
           return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
         }

package/src/run/multi-repo-context.js

@@ -79,7 +79,9 @@ export class MultiRepoContext {
       throw new Error(
         `MultiRepoContext: 以下 repo 未在 local.yaml repos: 段注册：[${unregistered.join(', ')}]。` +
         `当前已注册 repo：[${registered.join(', ')}]。` +
-        `请在 local.yaml repos: 段补注册后再启动 execute（约束② fail-closed，跨仓 apply 走错仓=数据所有权事故）。`
+        `一键注册（每个缺的 key 各跑一次，勿手编 YAML）：` +
+        unregistered.map(k => `sillyspec local register-repo ${k} <${k} 仓根路径>`).join('；') +
+        `。补注册后再启动 execute（约束② fail-closed，跨仓 apply 走错仓=数据所有权事故）。`
       );
     }
 

package/src/run/next.js

@@ -0,0 +1,128 @@
+/**
+ * next.js — `sillyspec next` 项目状态探测（吸收 continue/resume 两个 skill 的手工探测表，
+ * 2026-08-21 agent-手工产出审计第二批 G7/G8）。
+ *
+ * 两个 skill 各自维护一套「文件存在性状态机」推断表且内容重复，agent 每次手工跑
+ * ls/cat 探测再查表——纯机械探测是 CLI 的本职。本模块输出「状态描述 + 下一步命令 +
+ * 依据文件」，agent 按输出执行即可；skill 保留作兜底（CLI 不可用/输出异常时）。
+ *
+ * 纯 fs 探测（零 DB 依赖、零 token、快）：进度库的权威状态归 `sillyspec progress show`，
+ * 本命令管「没有活跃进度时从产物文件反推该干什么」。决策表（两个 skill 合并）：
+ *
+ *   1. HANDOFF.json 存在 → 交接恢复
+ *   2. 活跃变更（changes/ 非 archive）逐个推断：
+ *      无文件→补 proposal / 无 design.md→brainstorm / 无 tasks.md→brainstorm 末步 /
+ *      无 plan.md→plan / tasks.md 有未勾→execute / 全勾无 verify-result.md→verify /
+ *      有 verify-result.md→archive
+ *   3. 有 docs/<p>/scan/ 无活跃变更 → brainstorm（已扫描待开变更）
+ *   4. 有 REQUIREMENTS.md/ROADMAP.md 无变更 → brainstorm（绿地已有需求）
+ *   5. 什么都没有 → init（新项目）或 scan（棕地）
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { resolveSpecDir } from './shared.js'
+
+/**
+ * 数 tasks.md checkbox：返回 { checked, total }（无文件 → {checked:0,total:0}）
+ */
+function countTasks(tasksPath) {
+  if (!existsSync(tasksPath)) return { checked: 0, total: 0 }
+  let checked = 0
+  let total = 0
+  for (const line of readFileSync(tasksPath, 'utf8').split('\n')) {
+    const m = line.match(/^[-*]\s*\[([ xX])\]\s*task-\d+\b/)
+    if (!m) continue
+    total++
+    if (m[1] !== ' ') checked++
+  }
+  return { checked, total }
+}
+
+/**
+ * 单个活跃变更的产物推断：返回 { state, next, evidence }
+ */
+function inferChange(changeDir, name) {
+  const has = (f) => existsSync(join(changeDir, f))
+  const ev = (f) => join('.sillyspec', 'changes', name, f)
+  const t = countTasks(join(changeDir, 'tasks.md'))
+
+  if (!has('proposal.md') && !has('design.md') && !has('tasks.md') && !has('plan.md')) {
+    return { state: `${name}：变更目录为空`, next: 'sillyspec run brainstorm（完善 proposal）或清理该空目录', evidence: [ev('（无产物）')] }
+  }
+  if (!has('design.md')) {
+    return { state: `${name}：有 proposal 缺 design.md`, next: `sillyspec run brainstorm --change ${name}（推进到设计产物）`, evidence: [ev('proposal.md')] }
+  }
+  if (!has('tasks.md')) {
+    return { state: `${name}：有 design 缺 tasks.md`, next: `sillyspec run brainstorm --change ${name}（末步生成规范文件）`, evidence: [ev('design.md')] }
+  }
+  if (!has('plan.md')) {
+    return { state: `${name}：有 tasks.md 缺 plan.md`, next: `sillyspec run plan --change ${name}`, evidence: [ev('tasks.md')] }
+  }
+  if (t.total > 0 && t.checked < t.total) {
+    return {
+      state: `${name}：执行中（task ${t.checked}/${t.total}）`,
+      next: `sillyspec run execute --change ${name}`,
+      evidence: [ev('plan.md'), ev('tasks.md')],
+    }
+  }
+  if (!has('verify-result.md')) {
+    return { state: `${name}：task 全勾，待验证`, next: `sillyspec run verify --change ${name}`, evidence: [ev('tasks.md'), ev('plan.md')] }
+  }
+  return { state: `${name}：已验证，待归档`, next: `sillyspec run archive --change ${name}`, evidence: [ev('verify-result.md')] }
+}
+
+/**
+ * 探测当前项目状态与下一步命令。
+ * @param {{ cwd: string, specDir?: string|null }} opts
+ * @returns {{ state: string, next: string, evidence: string[], activeChanges: Array<{name,checked,total}> }}
+ *   activeChanges 附带各变更 task 勾选进度（供 --json 消费）；evidence 为相对 spec 根的路径
+ */
+export function detectNextStep({ cwd, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const changesRoot = join(specBase, 'changes')
+
+  // 1. HANDOFF 交接
+  for (const handoff of [join(cwd, 'HANDOFF.json'), join(specBase, 'HANDOFF.json')]) {
+    if (existsSync(handoff)) {
+      return { state: '存在 HANDOFF.json（上次会话交接）', next: '读 HANDOFF.json 后从交接点继续（sillyspec progress show 看活跃进度）', evidence: [handoff], activeChanges: [] }
+    }
+  }
+
+  // 2. 活跃变更（排除 archive）
+  let active = []
+  try {
+    active = readdirSync(changesRoot, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== 'archive')
+      .map(e => e.name)
+      .sort()
+  } catch { /* 无 changes/ 目录 */ }
+  if (active.length > 0) {
+    // 多活跃时逐个推断全报告，next 取第一个（字典序最前）的；调用方输出含全部状态行
+    const inferences = active.map(name => inferChange(join(changesRoot, name), name))
+    const progress = active.map((name, i) => {
+      const t = countTasks(join(changesRoot, name, 'tasks.md'))
+      return { name, checked: t.checked, total: t.total, state: inferences[i].state }
+    })
+    return { state: inferences.map(i => i.state).join('；'), next: inferences[0].next, evidence: inferences[0].evidence, activeChanges: progress }
+  }
+
+  // 3. 已扫描无变更
+  const docsDir = join(specBase, 'docs')
+  try {
+    const scanned = readdirSync(docsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && existsSync(join(docsDir, e.name, 'scan')))
+    if (scanned.length > 0) {
+      return { state: `已扫描（${scanned.length} 个项目文档），无活跃变更`, next: 'sillyspec run brainstorm "你的想法"', evidence: [join('.sillyspec', 'docs', scanned[0].name, 'scan')], activeChanges: [] }
+    }
+  } catch { /* 无 docs/ */ }
+
+  // 4. 绿地已有需求
+  for (const f of ['REQUIREMENTS.md', 'ROADMAP.md']) {
+    if (existsSync(join(specBase, f))) {
+      return { state: `绿地项目已有 ${f}，无活跃变更`, next: 'sillyspec run brainstorm "你的想法"', evidence: [join('.sillyspec', f)], activeChanges: [] }
+    }
+  }
+
+  // 5. 什么都没有
+  return { state: '未初始化（无 .sillyspec 产物）', next: 'sillyspec init（新项目）或 sillyspec scan（棕地项目）', evidence: [], activeChanges: [] }
+}

package/src/run/prompt.js

@@ -21,7 +21,7 @@
 import { basename, join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
 import { stageRegistry } from '../stages/index.js'
-import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE } from './shared.js'
+import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE, QUICK_SID_RE } from './shared.js'
 import { renderStageContract } from '../stage-contract-spec.js'
 import { parseModuleMapSimple } from '../modules.js'
 import { REVIEW_SCHEMA_VERSION, isValidExecuteRunId } from '../task-review.js'
@@ -236,6 +236,16 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   promptText = promptText.replace(/<now-datetime>/g, nowDatetime)
   promptText = promptText.replace(/<now-timestamp>/g, nowTimestamp)
   promptText = promptText.replace(/<now-date>/g, nowDate)
+  // <now-iso-datetime>（scan frontmatter updated_at 用；与 scan-fix-headers 同款秒级格式）
+  promptText = promptText.replace(/<now-iso-datetime>/g, now.toISOString().slice(0, 19).replace('T', ' '))
+  // <git-head-short>（scan frontmatter source_commit 用；CLI 代查，agent 勿自跑 rev-parse）
+  if (promptText.includes('<git-head-short>')) {
+    let headShort = 'unknown'
+    try {
+      headShort = safeGit(cwd, ['rev-parse', '--short', 'HEAD']).value || 'unknown'
+    } catch { /* git 不可用 → unknown，scan-postcheck 失配时再核 */ }
+    promptText = promptText.replace(/<git-head-short>/g, headShort)
+  }
   // 替换 {REVIEW_SCHEMA_VERSION} 占位符（task review 示例模板用，值=CLI 当前 REVIEW_SCHEMA_VERSION 常量，
   // 避免 agent 照抄 design 目标版本与 CLI 写侧常量漂移；与 stage review 契约 renderReviewJsonContract 动态注入同源）
   if (promptText.includes('{REVIEW_SCHEMA_VERSION}')) {
@@ -722,7 +732,15 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       // 普通本地保持相对 '.sillyspec' 展示；runtimeRoot-only 组合不再 join(null) 崩溃
       const changeDirBase = platformOpts?.specRoot || platformOpts?.specDriftAnchor || '.sillyspec'
       const changeDir = join(changeDirBase, 'changes', changeName)
-      console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
+      // quick 会话（quick-<hex8>）按设计无实体变更目录（progress.js initChange 同款跳过），
+      // 纯代码 quick 根本不产 spec 文档——「所有变更文件必须写入 changes/<change>/」的硬规则
+      // 对它是误导（ql-20260821-011 实证：CLI 反复提示一个用不到的目录）。改述条件化：
+      // 仅「若本 quick 决定补文档」才落该目录，代码改动照常写源码目录。
+      if (QUICK_SID_RE.test(changeName)) {
+        console.log(`- **文件路径规则（quick 会话）：纯代码改动直接写源码目录，无目录限制。仅当本 quick 需要落 spec 文档（design/plan 等，复杂任务建议升级完整流程）时才写 \`${changeDir}/\`；QUICKLOG/tasks.md 记录由 CLI 接管，不要手建。**`)
+      } else {
+        console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
+      }
     }
   }
   const changeFlag = changeName ? ` --change ${changeName}` : ''

package/src/run/shared.js

@@ -460,8 +460,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

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-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) {