sillyspec 3.26.13 → 3.26.15

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'
@@ -183,8 +183,11 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   console.log(`project: ${projectName}`)
   if (changeName) {
     console.log(`change: ${changeName}`)
-    const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
-    const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+    // changeDir 根（坑 change-dir-base-mismatch）：平台/漂移锚定用绝对根（specDriftAnchor 防
+    // worktree 副本错位），普通本地保持相对 '.sillyspec' 展示契约（test 钉死）。此前
+    // isPlatform 用 specRoot||runtimeRoot 判定、取值只拿 specRoot——runtimeRoot-only 平台组合
+    // join(null,...) 直接 TypeError。
+    const changeDirBase = platformOpts?.specRoot || platformOpts?.specDriftAnchor || '.sillyspec'
     const changeDir = join(changeDirBase, 'changes', changeName)
     console.log(`changeDir: ${changeDir}`)
   }
@@ -233,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}')) {
@@ -715,10 +728,19 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       console.log('- **平台模式：local.yaml 中的 commands 必须在 package.json scripts 中真实存在，不存在的标记 unavailable。**')
     }
     if (changeName) {
-      const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
-      const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+      // changeDir 根与上方头部同源（坑 change-dir-base-mismatch）：平台/漂移锚定绝对根，
+      // 普通本地保持相对 '.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/scan-profile.js

@@ -105,21 +105,15 @@ export function computeScanProfile(cwd, platformOpts) {
 }
 
 /**
- * 根据 scanProfile 裁剪步骤
- * quick:   3 步 — CLI preflight / AI generate / CLI postcheck
- * standard: 跳过续扫检测(4), 跳过可选步骤(9)
+ * quick 档 3 步表构建（唯一真相）：applyScanProfileSteps（首进程裁剪）与 getStageSteps
+ * （后续进程重取定义）共用。此前 quick 步骤表只在首进程 applyScanProfileSteps 里内联构建，
+ * getStageSteps('scan') 恒返回 11 步注册表 → 同进程 outputStep 用注册表 defSteps[1] 渲染错位
+ * prompt；跨进程 ensureStageSteps 见 3 vs 11 触发长度漂移重播种，quick 已完成步丢失、
+ * agent 从未做过的注册表步骤被 --done（坑 scan-quick-profile-step-mismatch）。
  */
-export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
-  const steps = stageData.steps
-  const mode = profile.mode
-
-  if (mode === 'quick') {
-    const specBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-    const projectName = basename(cwd)
-    const docsRoot = join(specBase, 'docs', projectName)
-
-    // Step 1: CLI preflight（不调 AI，自动完成）
-    const step1 = {
+export function buildQuickScanSteps() {
+  return [
+    {
       name: '项目概览（自动探测）',
       status: 'pending',
       noAI: true,
@@ -127,9 +121,8 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
       prompt: '',
       outputHint: 'preflight 结果',
       optional: false
-    }
-    // Step 2: AI 生成核心文档（唯一 AI roundtrip）
-    const step2 = {
+    },
+    {
       name: '生成核心文档',
       status: 'pending',
       prompt: `## Quick Scan — 核心文档生成
@@ -156,13 +149,32 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
 生成的文件列表`,
       outputHint: '文件列表',
       optional: false
+    },
+    {
+      // 名字与注册表末步一致（按名匹配/迁移语义）；prompt 清空、noAI postcheck 自动执行
+      name: '自检和提交',
+      status: 'pending',
+      prompt: '',
+      outputHint: '结果',
+      optional: false,
+      noAI: true,
+      _cliAction: 'scanPostcheck'
     }
-    // Step 3: CLI postcheck（不调 AI，自动完成）
-    const selfCheck = steps.find(s => s.name === '自检和提交') || {
-      name: '自检和提交', status: 'pending', prompt: '', outputHint: '结果', optional: false
-    }
-    const step3 = { ...selfCheck, status: 'pending', noAI: true, _cliAction: 'scanPostcheck', prompt: '' }
-    stageData.steps = [step1, step2, step3]
+  ]
+}
+
+/**
+ * 根据 scanProfile 裁剪步骤
+ * quick:   3 步 — CLI preflight / AI generate / CLI postcheck
+ * standard: 跳过续扫检测(4), 跳过可选步骤(9)
+ */
+export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
+  const steps = stageData.steps
+  const mode = profile.mode
+
+  if (mode === 'quick') {
+    // 3 步表构建抽至 buildQuickScanSteps（getStageSteps 同源复用，防跨进程 3 vs 11 漂移）
+    stageData.steps = buildQuickScanSteps()
     return
   }
 

package/src/run/shared.js

@@ -367,8 +367,14 @@ export function writePlatformPointer(cwd, platformOpts, extra = {}) {
     declaredAt: new Date().toISOString(),
   }
   try {
-    mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
-    writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    // platform-scan.json 只在 specRoot 存在时可写（坑 pointer-runtime-root-only-null-join）：
+    // runtimeRoot-only 平台组合（command.js 明确允许）下 specRoot 为 null，此前 join(null,…)
+    // 抛 ERR_INVALID_ARG_TYPE 落入总 catch → 指针与接管声明也一并静默未写，双入口 fail-closed
+    // 对该组合整体失效。分步写：specRoot 缺失只跳过 platform-scan.json，指针/声明照写。
+    if (platformOpts.specRoot) {
+      mkdirSync(join(platformOpts.specRoot, '.runtime'), { recursive: true })
+      writeFileSync(join(platformOpts.specRoot, '.runtime', 'platform-scan.json'), JSON.stringify(payload, null, 2) + '\n')
+    }
     writeFileSync(join(cwd, '.sillyspec-platform.json'), JSON.stringify(payload, null, 2) + '\n')
     writeFileSync(join(cwd, PLATFORM_MANAGED_FILENAME), JSON.stringify(declaration, null, 2) + '\n')
     return true
@@ -454,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
@@ -913,13 +919,17 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
     // 致 flag 对 status 失效。）
     if ((!forceBaseline && result.baselineHit.length > 0) || (!allowDelete && result.deletedFiles.length > 0) || result.reasons.some(r => r.startsWith('危险') || r.startsWith('删除'))) {
       result.status = 'blocked'
-    } else if ((!allowNew && result.newFiles.length > 0) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+    } else if ((!allowNew && result.newFiles.some(f => !isQuickMetadata(f, guard.linkedChanges))) || (allowedFiles.length > 0 && result.reasons.some(r => r.startsWith('超出')))) {
+      // newFiles 按元数据过滤后判定（坑 quick-metadata-warning-no-reason）：.sillyspec/ 被 git
+      // 跟踪的仓库里 quick 新建的 quicklog/*.md 是合法元数据，不过滤会 status=warning 而
+      // reasons 为空（reasons 侧已过滤），打印空原因的 WARNING 噪声。
       result.status = 'warning'
     }
 
-    // quicklog 存在性检查
+    // quicklog 存在性检查（specBase 感知：平台模式 quicklog 写在 specRoot 下，stage.js
+    // allocateQuicklogEntry 同源；硬编码 cwd/.sillyspec 会恒误报「目录不存在」抬 warning）
     try {
-      const quicklogDir = join(cwd, '.sillyspec', 'quicklog')
+      const quicklogDir = join(specBase || join(cwd, '.sillyspec'), 'quicklog')
       if (existsSync(quicklogDir)) {
         const qlFiles = readdirSync(quicklogDir).filter(f => f.endsWith('.md'))
         if (qlFiles.length === 0) {
@@ -1342,6 +1352,17 @@ export async function getStageSteps(stageName, cwd, progress, specDir = null) {
     const changeDir = resolveChangeDir(cwd, progress, specDir)
     return buildPlanSteps(changeDir)
   }
+  if (stageName === 'scan') {
+    // quick 档感知（坑 scan-quick-profile-step-mismatch）：scan 的 scanProfile 在首进程
+    // runStage 里算出并持久化（stageData.scanProfile），quick 档把 11 步注册表裁成 3 步。
+    // 此处恒返回注册表会让后续进程 ensureStageSteps 见 3 vs 11 触发漂移重播种（quick 已完成
+    // 步丢失、从未执行的注册表步骤被 --done），同进程 outputStep 也用错位 defSteps 渲染。
+    // quick 档 → 与 applyScanProfileSteps 同源返回 3 步表；standard/deep 与注册表同长度零影响。
+    if (progress?.stages?.scan?.scanProfile?.mode === 'quick') {
+      const { buildQuickScanSteps } = await import('./scan-profile.js')
+      return buildQuickScanSteps()
+    }
+  }
   const def = stageRegistry[stageName]
   return def ? def.steps : null
 }

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) {
@@ -465,7 +474,7 @@ export function printStageReviewResult(result, context = {}) {
  * @returns {{ ok: boolean, reviewRunId: string, reviewPath: string, markerPath: string, mode: 'skeleton'|'adopted', mainDoc: string, review: object }}
  * @throws {Error} changeName 空 / stage 非法 / 主文档缺失 / --from 不存在或 schema 不过
  */
-export function registerStageReview({ changeName, stage, fromFile, cwd, platformOpts = {} }) {
+export function registerStageReview({ changeName, stage, fromFile, cwd, platformOpts = {}, refreshHash = false }) {
   if (!changeName) throw new Error('register-stage-review: changeName 不能为空')
   if (!stage || !STAGE_MAIN_DOC[stage]) {
     throw new Error(`register-stage-review: stage 无效 "${stage}"（应为 brainstorm|plan|execute）`)
@@ -486,6 +495,45 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
   }
   const reviewedFiles = [`changes/${changeName}/${mainDoc}`]
 
+  // ── refresh-hash 模式（坑 stage-review-dochash-manual-resync，2026-08-21 实证）：改一版 design
+  // 要重算 2-3 个 stage review 的 docHash（brainstorm/execute 都锚 design.md），手工易漏、gate
+  // 报错才补。就地更新 marker 指向的已有 review.json——保留 verdict/checklist/requiredEvidence
+  // （结论是否仍适用由人确认），仅重算 docHash + reviewerNotes 追加刷新记录；不换 run 目录
+  // （换新 run 会把 marker 重定向到骨架，丢已审结论）。无既有 review → 报错（该用骨架模式生成）。
+  if (refreshHash) {
+    if (fromFile) throw new Error('register-stage-review: --refresh-hash 与 --from 互斥（refresh 就地更新既有 review，adopt 引入新文件）')
+    const existingRunId = getLatestStageReviewRunId(runtimeRoot, stage, changeName)
+    const existingPath = existingRunId
+      ? join(runtimeRoot, 'stage-reviews', `${stage}-${existingRunId}`, 'review.json')
+      : null
+    if (!existingPath || !existsSync(existingPath)) {
+      throw new Error(`register-stage-review: --refresh-hash 找不到 ${stage} 的既有 review.json（marker ${existingRunId || '无'} 无对应 run）——先去掉 --refresh-hash 生成骨架，或派审查子代理产出 review`)
+    }
+    let existing
+    try {
+      existing = JSON.parse(readFileSync(existingPath, 'utf8'))
+    } catch (e) {
+      throw new Error(`register-stage-review: 既有 review.json 解析失败 ${existingPath}: ${e.message}`)
+    }
+    const refreshedAt = new Date().toISOString().slice(0, 19).replace('T', ' ')
+    const review = {
+      ...existing,
+      docHash,
+      reviewedFiles,
+      reviewerNotes: `${existing.reviewerNotes || ''}\ndocHash refreshed at ${refreshedAt}（主文档改版后机械重算；verdict 结论是否仍适用需人工确认）`.trim(),
+    }
+    writeFileSync(existingPath, JSON.stringify(review, null, 2) + '\n')
+    const schemaRecheck = validateStageReviewSchema(review)
+    if (!schemaRecheck.ok) {
+      throw new Error(`register-stage-review: refresh 后 schema 自检失败 — ${schemaRecheck.errors.join('; ')}（原 review 字段异常，先修原文件）`)
+    }
+    const hashRecheck = verifyStageReviewDocHash(review, [specBase, changeDir, cwd])
+    if (!hashRecheck.ok) {
+      throw new Error(`register-stage-review: refresh 后 docHash 自检失败（不应发生）— ${hashRecheck.errors.join('; ')}`)
+    }
+    return { ok: true, reviewRunId: existingRunId, reviewPath: existingPath, markerPath: stageReviewMarkerPath(runtimeRoot, stage, changeName), mode: 'refreshed', mainDoc, review }
+  }
+
   let review
   let mode
   if (fromFile) {

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 终审结果 + 修正摘要',