sillyspec 3.25.9 → 3.25.11

package/src/run/gates.js

@@ -20,9 +20,12 @@
  * 不搬：ensureDepsFreshness（execute 入口 deps 自检，调用方 runStage 非 completeStep，归属未来 execute-handler）
  */
 import { basename, join } from 'node:path'
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
-import { triggerSync, resolveChangeDir } from './shared.js'
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { triggerSync, resolveChangeDir, resolveRuntimeRoot } from './shared.js'
 import { runValidators } from '../stage-contract.js'
+import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './complete-handlers.js'
+import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
+import { stageRegistry } from '../stages/index.js'
 
 /**
  * 判断当前 execute step 所在 wave 是否全部 task 都声明 no_deps_verify: true（D-006@v2）。
@@ -108,7 +111,7 @@ 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
-  const runtimeRoot = platformOpts?.runtimeRoot || join(specBase, '.runtime')
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
   const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
   const planPath = join(specBase, 'changes', changeName, 'plan.md')
   if (!existsSync(runIdFile) || !existsSync(planPath)) return true
@@ -158,10 +161,10 @@ function rollbackStageCompletion(stageData, steps, currentIdx) {
  * 漏写 triggerSync / 写错 return 结构导致行为分裂。返回 nextPendingIdx=currentIdx，
  * 让上层走「完成但不推进」分支，--done 被拒、agent 修复产物后重跑。
  */
-async function rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts) {
+function rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts) {
   rollbackStageCompletion(stageData, steps, currentIdx)
   progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })
-  await pm._write(cwd, progress, changeName)
+  pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
   return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
 }
@@ -216,12 +219,19 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     // 契约 parity 对账：扫前端 API 调用 vs execute 提取的 provider endpoint artifact。
     // 接线自 contract-matrix pipeline（verifyApiParity 的 CLI 入口）。
     const { runVerifyParityCheck, printVerifyParityCheck } = await import('../verify-postcheck.js')
-    const parityCheck = runVerifyParityCheck({ cwd, specBase, changeName, runtimeRoot: platformOpts?.runtimeRoot })
+    const parityRuntimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+    const parityCheck = runVerifyParityCheck({ cwd, specBase, changeName, runtimeRoot: parityRuntimeRoot })
     printVerifyParityCheck(parityCheck)
     // ── 删除探针（advisory，不阻断）：切斯特顿栅栏护栏，用 git 事实对账静默删除代码 ──
     const { runVerifyDeletionCheck, printVerifyDeletionCheck } = await import('../verify-postcheck.js')
     const deletionCheck = runVerifyDeletionCheck({ cwd, specBase, changeName })
     printVerifyDeletionCheck(deletionCheck)
+    // ── required-evidence 对账（advisory，不阻断）：闭合 execute→verify evidence 死链 ──
+    // execute Task Review Gate 把 cannot_verify 任务的 evidence 落盘 verify-required-evidence.json，
+    // 本探针查每个 cannot_verify 任务是否在 verify-result.md 体现（CLI 只查提及，满足度 agent 自报告）。
+    const { runVerifyRequiredEvidenceCheck, printVerifyRequiredEvidenceCheck } = await import('../verify-postcheck.js')
+    const evidenceCheck = runVerifyRequiredEvidenceCheck({ cwd, specBase, changeName })
+    printVerifyRequiredEvidenceCheck(evidenceCheck)
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 
@@ -250,12 +260,12 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     }
   }
 
-  // ── Stage Review Gate：brainstorm/plan/propose/execute 独立审查（按 tier 分级）──
+  // ── Stage Review Gate：brainstorm/plan/execute 独立审查（按 tier 分级）──
   // tier=self 放行+审计打印；tier=independent 必须 review.json 且 verdict 非 fail，fail-closed
-  if (['brainstorm', 'plan', 'propose', 'execute'].includes(stageName)) {
+  if (['brainstorm', 'plan', 'execute'].includes(stageName)) {
     try {
       const { classifyReviewTier } = await import('../review-tier.js')
-      const { validateStageReview, getLatestStageReviewRunId, printStageReviewResult } = await import('../stage-review.js')
+      const { validateStageReview, getLatestStageReviewRunId, printStageReviewResult, generateStageReviewRunId, stageReviewMarkerPath } = await import('../stage-review.js')
       const effectiveSpecBase = platformOpts?.specRoot || specBase
       const reviewChangeDir = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
       const designPath = reviewChangeDir ? join(reviewChangeDir, 'design.md') : null
@@ -268,15 +278,23 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         }
       }
       const tier = classifyReviewTier({ planLevel, designPath })
-      const runtimeRoot = platformOpts?.runtimeRoot || join(effectiveSpecBase, '.runtime')
+      const runtimeRoot = resolveRuntimeRoot(platformOpts, effectiveSpecBase)
 
       if (tier.tier === 'self') {
         console.log('\nℹ️  Stage Review: ' + stageName + ' tier=self（' + tier.reason + '），已降级为当前 agent 自审，不强制独立子代理。')
       } else {
-        const reviewRunId = getLatestStageReviewRunId(runtimeRoot, stageName, changeName)
+        let reviewRunId = getLatestStageReviewRunId(runtimeRoot, stageName, changeName)
+        if (!reviewRunId) {
+          // marker 缺失（execute 批量完成跳过 prompt 渲染等场景）→ 自生 + 写盘
+          // 让 gate 读到确定 ID，错误从 execute-null 变 execute-review-<id>（可执行）
+          reviewRunId = generateStageReviewRunId()
+          try {
+            mkdirSync(runtimeRoot, { recursive: true })
+            writeFileSync(stageReviewMarkerPath(runtimeRoot, stageName, changeName), reviewRunId + '\n')
+          } catch {}
+        }
         const reviewType = stageName === 'brainstorm' ? 'design'
           : stageName === 'plan' ? 'plan'
-          : stageName === 'propose' ? 'proposal'
           : 'acceptance'
         const searchDirs = [effectiveSpecBase, reviewChangeDir, cwd].filter(Boolean)
         const reviewResult = validateStageReview({ stage: stageName, reviewType, runtimeRoot, reviewRunId, searchDirs })
@@ -302,7 +320,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
 
       if (planPath && existsSync(planPath)) {
         const planContent = readFileSync(planPath, 'utf8')
-        const runtimeRoot = platformOpts?.runtimeRoot || join(effectiveSpecBase, '.runtime')
+        const runtimeRoot = resolveRuntimeRoot(platformOpts, effectiveSpecBase)
 
         // execute run id：从变更专属标记文件读取
         const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
@@ -313,10 +331,16 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           }
         } catch {}
         if (!executeRunId) {
-          const { generateExecuteRunId } = await import('../task-review.js')
-          executeRunId = generateExecuteRunId()
-          // 落盘（marker 缺失时 fallback 生成后写盘，保证后续 checkbox/gate 读到同一 ID）
-          try { mkdirSync(runtimeRoot, { recursive: true }); writeFileSync(runIdFile, executeRunId + '\n') } catch {}
+          // marker 缺失：先扫描 execute-runs/ 既有目录找回真实 runId（与 getLatestStageReviewRunId
+          // 目录扫描兜底同语义），避免 marker 丢失而 agent 已用旧 runId 落盘时，直接 generate 新 ID
+          // 找不到旧 review、误判缺 review.json。仅当确实无既有 run 才 generate 新 ID 并落盘。
+          const { generateExecuteRunId, resolveLatestExecuteRunId } = await import('../task-review.js')
+          executeRunId = resolveLatestExecuteRunId({ runtimeRoot, changeName }) || ''
+          if (!executeRunId) {
+            executeRunId = generateExecuteRunId()
+            // 落盘（marker 缺失时 fallback 生成后写盘，保证后续 checkbox/gate 读到同一 ID）
+            try { mkdirSync(runtimeRoot, { recursive: true }); writeFileSync(runIdFile, executeRunId + '\n') } catch {}
+          }
         }
 
         // git 真实性校验目录：worktree 存在则用 worktree（base/head commit 在其中），否则主仓库
@@ -363,3 +387,251 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
   return null
 }
 
+/**
+ * 读取 design.md frontmatter 的 scale 字段（brainstorm 末步写入 'small'|'large'）。
+ * completeStep 的下一步提示据此分叉：small→quick，large/读不到→plan（fail-safe 走重流程）。
+ * 只解析首个 YAML frontmatter 块，避免误读正文里的 "scale:"。
+ * 从 complete.js 迁入（completeStageGates 共享收尾管线 + completeStep brainstorm 提示消费）。
+ */
+export function readDesignScale(specBase, changeName) {
+  if (!changeName) return null
+  const designPath = join(specBase, 'changes', changeName, 'design.md')
+  if (!existsSync(designPath)) return null
+  const text = readFileSync(designPath, 'utf8')
+  const fm = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
+  if (!fm) return null
+  const m = fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
+  return m ? m[1] : null
+}
+
+/**
+ * 校验变更目录下近 10 分钟新增的 .md/.yaml/.yml 文件含 author/created_at 元数据（advisory 打印）。
+ * 从 complete.js 迁入（completeStageGates 共享收尾管线消费）。
+ */
+export function validateMetadata(cwd, stageName, specBase) {
+  const changesDir = join(specBase, 'changes')
+  if (!existsSync(changesDir)) return
+
+  const cutoff = Date.now() - 10 * 60 * 1000
+  const missing = []
+
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name)
+      try {
+        if (entry.isDirectory()) { walk(full); continue }
+        if (!/\.(md|yaml|yml)$/.test(entry.name)) continue
+        const mtime = statSync(full).mtimeMs
+        if (mtime < cutoff) continue
+        const content = readFileSync(full, 'utf-8')
+        if (!content.includes('author:') && !content.includes('author：')) missing.push(full)
+        if (!content.includes('created_at:') && !content.includes('created_at：')) missing.push(full)
+      } catch (e) { /* skip unreadable files */ }
+    }
+  }
+
+  walk(changesDir)
+  const unique = [...new Set(missing)]
+  if (unique.length > 0) {
+    console.log(`\n⚠️  以下文件缺少 author 或 created_at 元数据：`)
+    unique.forEach(f => console.log(`  - ${f.replace(cwd + '/', '')}`))
+    console.log('请在文件头部添加 author（git 用户名）和 created_at（精确到秒）')
+  }
+}
+
+/**
+ * 验证关键文件是否存在于正确的变更目录下（advisory 打印，防 AI 写错路径）。
+ * 从 complete.js 迁入（completeStageGates 共享收尾管线消费）。
+ */
+export function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
+  const effectiveChange = changeName || progress.currentChange
+  if (!effectiveChange) return
+
+  const changeDir = join(specBase, 'changes', effectiveChange)
+  if (!existsSync(changeDir)) return
+
+  // 每个阶段完成后预期存在的文件
+  // brainstorm:scale=small(小变更)只必产 design.md;large/未标 scale → 四件套全。
+  // 与 validateBrainstormOutputs 的 BRAINSTORM_RULES condition(scale≠small)同源,避免对合法 small 变更
+  // 误报"⬜ proposal/requirements/tasks 未找到"(本检查仅 advisory 打印不 gate,但误导输出仍要消除)。
+  const brainstormExpected = readDesignScale(specBase, effectiveChange) === 'small'
+    ? ['design.md']
+    : ['design.md', 'proposal.md', 'requirements.md', 'tasks.md']
+  const expectedFiles = {
+    brainstorm: brainstormExpected,
+    plan: ['plan.md'],
+    archive: ['module-impact.md'],
+  }
+
+  const expected = expectedFiles[stageName]
+  if (!expected) return
+
+  const missing = []
+  for (const file of expected) {
+    if (!existsSync(join(changeDir, file))) {
+      missing.push(file)
+    }
+  }
+
+  if (missing.length > 0) {
+    console.log(`\n⚠️  文件位置验证：以下文件未在变更目录中找到`)
+    console.log(`  变更目录：${changeDir.replace(cwd + '/', '')}/`)
+    for (const f of missing) {
+      // 检查是否写到了错误的位置
+      const wrongPath = join(specBase, 'changes', 'change', effectiveChange, f)
+      if (existsSync(wrongPath)) {
+        console.log(`  ❌ ${f} — 不存在，但发现了错误路径：${wrongPath.replace(cwd + '/', '')}`)
+        console.log(`     提示：应该写入 ${changeDir.replace(cwd + '/', '')}/${f}`)
+      } else {
+        console.log(`  ⬜ ${f} — 未找到（该阶段可能未产出此文件）`)
+      }
+    }
+  } else {
+    console.log(`\n✅ 文件位置验证：所有 ${expected.length} 个预期文件均在变更目录中`)
+  }
+}
+
+/**
+ * 读本变更 design.md §6「文件变更清单」表格，提取声明交付的文件路径（concurrent 预检 ownFiles 源，D-002）。
+ *
+ * 用途：execute --done 并发预检在 in-place-fallback 模式下，需把本变更交付文件从 foreignFiles 排除
+ * （否则自己产出的脏文件会被当他者）。worktree 模式下交付文件不在主仓 git status，ownFiles 用空数组即可。
+ *
+ * 解析：定位 `## 6.` 段（到下一个 `## N.` 前），逐行扫表格行第 2 列的反引号文件路径，跳过表头/分隔行。
+ * 设计容错（design §9 / R-02）：design.md 缺失 / 无 §6 / 解析空 → 返回 []，foreignFiles 退化为保守噪音，
+ * otherActiveChanges 仍可靠。
+ *
+ * @param {string} specBase 规范根（.sillyspec/ 所在）
+ * @param {string} changeName 当前变更名
+ * @returns {string[]} 本变更声明交付的文件路径（git 路径，正斜杠）
+ */
+function readDesignOwnFiles(specBase, changeName) {
+  if (!specBase || !changeName) return []
+  let content
+  try {
+    content = readFileSync(join(specBase, 'changes', changeName, 'design.md'), 'utf8')
+  } catch {
+    return []
+  }
+  const files = []
+  let inSection6 = false
+  for (const line of content.split('\n')) {
+    const heading = line.match(/^##\s+(\d+)\./)
+    if (heading) {
+      inSection6 = heading[1] === '6'
+      continue
+    }
+    if (!inSection6 || !line.startsWith('|')) continue
+    // 跳过表头分隔行（|---|---|）
+    if (/^\|[\s:|-]+\|?$/.test(line.trim())) continue
+    // 表格第 2 列反引号文件路径：`| 新增 | \`src/.../x.js\` | 说明 |`
+    const m = line.match(/^\|[^|]+\|\s*`([^`]+)`/)
+    if (m) files.push(m[1].trim())
+  }
+  return files
+}
+
+/**
+ * 阶段完成收尾共享管线（从 completeStep 抽出，消除 noAI 末步 / continueStep 完成分支绕过 gate 的
+ * S1/S2/S3 三处不对称）。调用方已自行标记 stageData.status='completed' 并 pm._write 落盘后调用本函数。
+ *
+ * 序列：handleScanStageCompleted → validateMetadata → validateFileLocations[completed‖skipped 守卫] →
+ * auxiliary 重置 → runStageCompletionGates[同守卫] → handleExecuteWorktreeCleanup。
+ *
+ * 关键陷阱（design §5.4）：auxiliary 重置把 stageData.steps 换成 freshSteps（全 pending）；下方
+ * runStageCompletionGates 守卫与 rollbackStageCompletion 必须用入参 steps（pre-reset 原数组），
+ * 不得重读 stageData.steps（否则计数恒 0 → gate 永跳过）。本函数全程用入参 steps，未重读。
+ *
+ * @returns {Promise<{stageCompleted:false,currentIdx,nextPendingIdx:number}|null>}
+ *          null = 全部通过，调用方继续自管收尾（如下一步提示）；
+ *          非 null = gate/handler 失败已 rollback，调用方直接 return。
+ */
+export async function completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText }) {
+  // 整体 try/catch（task-04 / review-2026-08-09 #2）：收尾段（execute 预检 + scan handler + validate* +
+  // auxiliary 重置 + runStageCompletionGates）任一段抛非结构化异常 → rollbackCompletionAndReturn
+  // （回滚 in-progress + 落盘 + 返回未完成对象），不冒顶 exit 1。正常的 _scanResult/_gateEarlyReturn
+  // early-return 是 return 非 throw，不被 catch 拦；下方 handleExecuteWorktreeCleanup 在 try 外（副作用独立，失败不 rollback stage 状态）。
+  try {
+  // ── execute --done 并发他者改动预检（FR-06/FR-07，非阻断 advisory）──
+  // 仅 execute 触发，不影响 scan/plan/verify/archive 等 stage 的 completeStageGates。
+  // 纯副作用：console.warn 后照常推进，不改 stageData / 不阻断级联（FR-07）。
+  // 整个钩子 try/catch 兜底——任何异常吞掉，绝不影响 gate 级联（FR-07 不阻断铁律）。
+  if (stageName === 'execute') {
+    try {
+      // ownFiles 源（D-002 + B-002，钉死）：动态 import WorktreeManager 取 meta.mode（复用上方
+      // Task Review Gate 的 ../worktree.js 动态 import 先例）。WorktreeManager 无 appliedFiles
+      // 字段（B-002 已证），不用模糊的「worktree applied 文件」。
+      //   - worktree 模式（meta.mode 非 in-place-fallback）：主仓 git status 看不见本变更交付文件
+      //     → ownFiles=[]（无害，dogfood 当前实际模式）
+      //   - in-place-fallback 模式：交付文件就在主仓 dirty → ownFiles 读 design.md §6 文件清单排除
+      let ownFiles = []
+      // linkedChanges：execute 通常无（quick 管线概念，存 quick guard 文件）；stageData 取不到则 []。
+      const linkedChanges = Array.isArray(stageData?.linkedChanges) ? stageData.linkedChanges : []
+      try {
+        const { WorktreeManager } = await import('../worktree.js')
+        const wm = new WorktreeManager({ cwd })
+        const meta = wm.getMeta(changeName)
+        if (meta?.mode === 'in-place-fallback') {
+          ownFiles = readDesignOwnFiles(specBase, changeName)
+        }
+      } catch {
+        // getMeta 抛（meta.json 缺 / worktree 损坏）→ ownFiles=[] 兜底，不崩（FR-07）。
+        ownFiles = []
+      }
+      const detected = detectConcurrentChanges(cwd, { changeName, linkedChanges, ownFiles })
+      const warn = formatConcurrentWarning(detected)
+      if (warn) console.warn(warn)
+    } catch {
+      // FR-07 不阻断：钩子任何意外异常静默吞掉，gate 级联照常推进。
+    }
+  }
+
+  // scan 平台 manifest + post-check（S1 平台受害者：noAI scanPostcheck 末步 / continueStep 现也走这里）
+  const _scanResult = await handleScanStageCompleted({ stageName, currentIdx, cwd, progress, pm, stageData, changeName, outputText, platformOpts })
+  if (_scanResult) return _scanResult
+
+  // 守卫计数：completed‖skipped === total（修 S3）；用入参 steps（pre-reset 原数组，design §5.4）
+  const settledCount = steps.filter(s => s.status === 'completed' || s.status === 'skipped').length
+  const total = steps.length
+
+  validateMetadata(cwd, stageName, specBase)
+
+  // 验证关键文件位置（仅当所有步骤已结案 completed‖skipped 时才校验）
+  if (settledCount === total && total > 0) {
+    validateFileLocations(cwd, stageName, progress, changeName, specBase)
+  }
+
+  // 辅助阶段完成后重置步骤（scan 等 auxiliary 阶段重置回 pending 可重跑）
+  const stageDef = stageRegistry[stageName]
+  if (stageDef?.auxiliary) {
+    const freshSteps = (stageDef.steps || []).map(s => ({
+      name: s.name,
+      status: 'pending',
+      output: null,
+      completedAt: null
+    }))
+    stageData.steps = freshSteps
+    stageData.status = 'pending'
+    stageData.completedAt = null
+    if (progress.currentStage === stageName) progress.currentStage = ''
+    pm._write(cwd, progress, changeName)
+  }
+
+  // 阶段完成校验 gate 级联（runValidators → verify-test → Plan→Execute → Stage Review → Task Review）
+  if (settledCount === total && total > 0) {
+    const _gateEarlyReturn = await runStageCompletionGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx })
+    if (_gateEarlyReturn) return _gateEarlyReturn
+  } else if (settledCount < total) {
+    console.log(`\n⚠️ 阶段校验跳过：${total} 步中仅 ${settledCount} 步标记为已结案（completed‖skipped），可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
+  }
+  } catch (e) {
+    console.error(`\n❌ ${stageName} 阶段完成收尾异常（已 rollback 为 in-progress，请修复后重新 --done）：${e?.message || e}`)
+    return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
+  }
+
+  // execute worktree cleanup（completeStep / continueStep 完成分支统一调用，避免双清理）
+  await handleExecuteWorktreeCleanup({ stageName, changeName, cwd })
+
+  return null
+}
+

package/src/run/prompt.js

@@ -20,8 +20,9 @@
 import { basename, join } from 'node:path'
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
 import { stageRegistry } from '../stages/index.js'
-import { resolvePromptIncludes, safeGit, WAIT_MARKER_RE } from './shared.js'
+import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE } from './shared.js'
 import { renderStageContract } from '../stage-contract-spec.js'
+import { parseModuleMapSimple } from '../modules.js'
 
 /**
  * 从 _module-map.yaml 读取模块上下文索引
@@ -36,6 +37,14 @@ function loadModuleContextIndex(specBase, projectName) {
     const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
     if (!existsSync(mapPath)) return null
     const content = readFileSync(mapPath, 'utf8')
+    // schema_version 校验（advisory）：modules.js 写 schema_version: 2；缺失或非 2 → warn，
+    // 提示 v1/v2 格式混用风险（旧格式字段解析会静默错位）。正常生成的文件不触发。
+    const sv = content.match(/^schema_version:\s*(\d+)/m)
+    if (!sv) {
+      console.warn(`⚠️  _module-map.yaml 缺少 schema_version 声明（期望 2），模块解析可能错位：${mapPath}`)
+    } else if (sv[1] !== '2') {
+      console.warn(`⚠️  _module-map.yaml schema_version=${sv[1]}（期望 2），可能为旧格式，模块解析可能错位：${mapPath}`)
+    }
     return parseModuleMapSimple(content)
   } catch {
     return null
@@ -104,63 +113,8 @@ function buildModuleContextInjection(taskDescription, moduleIndex, specBase, pro
   return injection
 }
 
-// 复用 modules.js 的简单 YAML 解析（避免循环依赖）
-function parseModuleMapSimple(content) {
-  const modules = {}
-  let currentModule = null
-  let currentKey = null
-  let currentArray = null
-
-  for (const line of content.split('\n')) {
-    const moduleMatch = line.match(/^  ([a-zA-Z0-9_-]+):$/)
-    if (moduleMatch) {
-      if (currentArray && currentModule && currentKey) {
-        modules[currentModule][currentKey] = currentArray
-      }
-      currentModule = moduleMatch[1]
-      modules[currentModule] = {}
-      currentKey = null
-      currentArray = null
-      continue
-    }
-    if (!currentModule) continue
-
-    const arrayFieldMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands):$/)
-    if (arrayFieldMatch) {
-      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray
-      currentKey = arrayFieldMatch[1]
-      currentArray = []
-      continue
-    }
-
-    const inlineArrayMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands): \[(.*)\]$/)
-    if (inlineArrayMatch) {
-      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray
-      const vals = inlineArrayMatch[2].split(',').map(v => v.trim()).filter(Boolean)
-      modules[currentModule][inlineArrayMatch[1]] = vals
-      currentKey = null
-      currentArray = null
-      continue
-    }
-
-    const scalarMatch = line.match(/^    (status|doc|needs_review|role|risk_level): (.+)$/)
-    if (scalarMatch) {
-      if (currentArray && currentKey) { modules[currentModule][currentKey] = currentArray; currentArray = null; currentKey = null }
-      modules[currentModule][scalarMatch[1]] = scalarMatch[2]
-      continue
-    }
-
-    const itemMatch = line.match(/^      - (.+)$/)
-    if (itemMatch && currentArray !== null) {
-      currentArray.push(itemMatch[1].trim())
-      continue
-    }
-  }
-  if (currentArray && currentModule && currentKey) {
-    modules[currentModule][currentKey] = currentArray
-  }
-  return modules
-}
+// parseModuleMapSimple 复用 modules.js 的 canonical 实现（合并历史 copy-paste 副本，2026-08-07；
+// 无循环依赖：modules.js 仅 import fs/path/db.js，prompt.js → modules.js 单向）。
 /**
  * 输出当前步骤的 prompt
  */
@@ -450,7 +404,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   if (stageName === 'execute' && promptText.includes('{EXECUTE_RUN_ID}')) {
     let runId = ''
     const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-    const runtimeRoot = platformOpts?.runtimeRoot || join(execSpecBase, '.runtime')
+    const runtimeRoot = resolveRuntimeRoot(platformOpts, execSpecBase)
     const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
     try {
       if (existsSync(runIdFile)) {
@@ -466,10 +420,10 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     promptText = promptText.replace(/\{EXECUTE_RUN_ID\}/g, runId)
   }
 
-  // Stage Review Tier：brainstorm/plan/propose/execute 阶段注入审查分级占位符
+  // Stage Review Tier：brainstorm/plan/execute 阶段注入审查分级占位符
   // （scanProfile 只在 scan 生效、change-risk-profile 只管 apply/verify，都不约束这些阶段的审查方式，
   //  故按 plan_level / 变更文件数分级：self 当前 agent 自审，independent 强制独立子代理 + review.json）
-  if (['brainstorm', 'plan', 'propose', 'execute'].includes(stageName) && promptText.includes('{REVIEW_TIER}')) {
+  if (['brainstorm', 'plan', 'execute'].includes(stageName) && promptText.includes('{REVIEW_TIER}')) {
     try {
       const { classifyReviewTier } = await import('../review-tier.js')
       const { generateStageReviewRunId, renderReviewJsonContract, stageReviewMarkerPath } = await import('../stage-review.js')
@@ -488,7 +442,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       // reviewRunId：优先读 marker 复用（保证多次渲染 prompt 注入同一 ID == gate 读取的 ID，
       // 修复「prompt 多次渲染 / 多次 review 时 gate 取错 ID 读错 review.json」），marker 缺失才
       // generate + 落盘。对齐 execute {EXECUTE_RUN_ID} 段（prompt.js:449-467）。
-      const tierRuntimeRoot = platformOpts?.runtimeRoot || join(tierSpecBase, '.runtime')
+      const tierRuntimeRoot = resolveRuntimeRoot(platformOpts, tierSpecBase)
       const reviewRunIdMarker = stageReviewMarkerPath(tierRuntimeRoot, stageName, changeName)
       let reviewRunId = ''
       try {
@@ -526,7 +480,7 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     try {
       const { summarizeTaskCompletion } = await import('../task-review.js')
       const tcrSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-      const tcrRuntimeRoot = platformOpts?.runtimeRoot || join(tcrSpecBase, '.runtime')
+      const tcrRuntimeRoot = resolveRuntimeRoot(platformOpts, tcrSpecBase)
       const tcrChangeDir = changeName ? join(tcrSpecBase, 'changes', changeName) : null
       const summary = tcrChangeDir
         ? summarizeTaskCompletion({ changeDir: tcrChangeDir, runtimeRoot: tcrRuntimeRoot, changeName })
@@ -585,11 +539,11 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   if (stepIndex === 0) {
     console.log(`\n### ⚠️ 铁律`)
     console.log('- 文档优先：代码产出必须先有对应的设计/规范文档支撑。')
-    console.log('- 只做本步骤描述的操作，不得自行扩展或跳过')
-    console.log('- 不要回头修改已完成的步骤')
-    console.log('- 不要编造不存在的 CLI 子命令')
-    console.log('- 完成后立即执行 --done 命令，不得跳过')
-    console.log('- 不要用 mv/rename 重命名变更目录，必须用 `sillyspec change-rename <旧名> <新名>`')
+    console.log('- 聚焦本步骤：只执行本步骤描述的操作并完整做完；自行扩展或跳步会破坏状态机推进，后续步骤再做后续事。')
+    console.log('- 已完成步骤视为只读：需修订用 `sillyspec run <stage> --reopen --from-step N` 回退重做，直接回头改会让进度记录与产物脱节。')
+    console.log('- CLI 子命令以本 prompt 或上一条 --done 输出的字面为准；不确定时停下问用户，猜测命令会让状态机推进到错误位置。')
+    console.log('- 本步骤产物落盘后立即执行 prompt 末尾的 --done：CLI 据此校验产出并推进状态机；不跑则进度永远停在本步。')
+    console.log('- 变更目录改名用 `sillyspec change-rename <旧名> <新名>`：mv/rename 会漏改进度库引用，导致变更失联。')
     console.log('- 文档类型文件（.md/.yaml/.json 等）头部必须包含 author（git 用户名）和 created_at（精确到秒）')
     console.log('- 执行构建/测试前必须先读 local.yaml，优先使用其中配置的命令、路径和环境变量；未配置时才使用默认值')
   }

package/src/run/quick-audit.js

@@ -6,12 +6,11 @@
  *
  * 路径修正（相对 src/run/）：
  *   - resolveQuickLinkedChanges 的 quick-recommend.js 动态 import './quick-recommend.js' → '../quick-recommend.js'
- *   - 原动态 import('child_process') 删除，改顶部静态 execSync
+ *   - 脏文件信号改用 safeGit（带 safe.directory，Q3）；不再 import execSync
  *   - parsePorcelainPath 从 ./shared.js 重 import；checkbox 顶部 import
  */
-import { execSync } from 'node:child_process'
 import { checkbox } from '@inquirer/prompts'
-import { parsePorcelainPath } from './shared.js'
+import { parsePorcelainPath, safeGit } from './shared.js'
 
 /**
  * 打印 quick 完成审计结论（按 review.status 输出 SAFE/WARNING/BLOCKED）。
@@ -55,7 +54,7 @@ export function printQuickAuditReview(review) {
 export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDescription, nonInteractive }) {
   let activeChanges = []
   try {
-    activeChanges = await pm.listChanges(cwd)
+    activeChanges = pm.listChanges(cwd)
   } catch {
     activeChanges = []
   }
@@ -67,15 +66,17 @@ export async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles,
     return []
   }
 
-  // 脏文件（推荐信号之一）
+  // 脏文件（推荐信号之一）。safeGit 带 safe.directory，避免 linked worktree/容器/挂载点下裸
+  // `git status` 抛错致推荐信号静默丢失（multi-agent-review Q3 同类）。推荐非关键路径，失败回退 []。
+  // trim:false：porcelain 首行前导空格是状态码，trim 会削掉致 parsePorcelainPath 丢首字符。
   let baselineFiles = []
-  try {
-    const gs = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 10000 })
-    baselineFiles = gs.split('\n').filter(Boolean)
+  const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+  if (!statusResult.error) {
+    baselineFiles = (statusResult.value || '').split('\n').filter(Boolean)
       .map(l => parsePorcelainPath(l))
       .filter(Boolean)
       .filter(f => !f.startsWith('.sillyspec/'))
-  } catch {}
+  }
 
   // 推荐打分（脏文件 + 任务描述双信号）
   let recommendations = []