sillyspec 3.25.9 → 3.26.0

package/src/run/concurrent-detect.js

@@ -0,0 +1,132 @@
+/**
+ * concurrent-detect — 多 agent 并发写预检的纯函数检测核心（design §7）。
+ *
+ * 单次 git status --porcelain 扫描，复用 isQuickMetadata 的「关联 vs 他者」分类口径，
+ * 产出两类并发信号：
+ *   - foreignFiles: 脏文件里非 metadata、不在 ownFiles 的真实业务文件（他者未提交改动）
+ *   - otherActiveChanges: 脏文件落在 .sillyspec/changes/<他者变更>/ 下去重成的变更名集合
+ *
+ * 非阻塞 advisory：检测结果仅在调用点本地消费（→ formatConcurrentWarning → console.warn），
+ * 不改 audit status / gate 通过性 / isQuickMetadata 语义（design §2/§9）。
+ *
+ * 纯函数无副作用：不写盘、不 console（console 留给调用点 task-02/03）。
+ */
+import { safeGit, parsePorcelainPath, isQuickMetadata } from './shared.js'
+
+/**
+ * 内联解析 .sillyspec/changes/<dir>/ 路径取 <dir>。
+ * 与 shared.js isQuickMetadata 内部 regex（^\.sillyspec\/changes\/([^/]+)(\/|$)）同源——
+ * D-008 deferred：暂不抽 shared.js 公共 helper，改其一改其二。
+ * @param {string} file 已归一化（正斜杠）的 git 路径
+ * @returns {string|null} 变更目录名，不在 changes/ 下返回 null
+ */
+function extractChangeDir(file) {
+  const m = file.match(/^\.sillyspec\/changes\/([^/]+)(\/|$)/)
+  return m ? m[1] : null
+}
+
+/** git 路径反斜杠归一（跨平台 Windows 兼容）。 */
+function normalizeGitPath(p) {
+  return String(p).replace(/\\/g, '/')
+}
+
+/**
+ * 检测工作树里的并发他者改动（非阻塞 advisory 用）。
+ *
+ * @param {string} cwd 主仓库根
+ * @param {{ changeName: string, linkedChanges?: string[], ownFiles?: string[], specDir?: string }} opts
+ *   - changeName: 当前变更名（排除自身变更目录）
+ *   - linkedChanges: 关联变更（透传给 isQuickMetadata 的关联归类，同时从 otherActiveChanges 排除）
+ *   - ownFiles: 本 --done 负责的文件（从 foreignFiles 排除，避免把自己当他者）
+ *   - specDir: 规范目录（保留参数，当前实现用 .sillyspec/ 前缀 regex 定位，暂未使用）
+ * @returns {{ hasForeign: boolean, foreignFiles: string[], otherActiveChanges: string[], gitError: string|null }}
+ *   - foreignFiles: 脏文件里非 metadata、不在 ownFiles 的真实业务文件
+ *   - otherActiveChanges: 脏文件落在 .sillyspec/changes/<他者变更>/ 下，去重成的变更名集合
+ *   - gitError: git status 读失败时填错误串，hasForeign=false（FR-04 fail-open，不抛异常）
+ */
+export function detectConcurrentChanges(cwd, { changeName, linkedChanges = [], ownFiles = [], specDir } = {}) {
+  // safeGit 必传 trim:false（D-004）：porcelain 首行前导空格是状态码一部分，trim 会削掉致
+  // parsePorcelainPath 丢首字符（坑见 shared.js auditQuickCompletion :448 注释）。
+  const statusResult = safeGit(cwd, ['status', '--porcelain'], { trim: false })
+
+  // FR-04 fail-open：git status 读不到不崩、不阻断、不误报（advisory 漏报可接受，最坏漏报而非误阻）。
+  if (statusResult.error) {
+    return { hasForeign: false, foreignFiles: [], otherActiveChanges: [], gitError: statusResult.error }
+  }
+
+  const gitStatus = statusResult.value || ''
+  // 不整段 trim：同 auditQuickCompletion :455 注释，会削首行前导空格致首文件路径丢首字符。
+  const entries = gitStatus.split('\n').filter(Boolean)
+
+  // 本变更 + 关联变更目录集合：rule1 据此把「自己/关联」从他者变更中排除。
+  const ownChangeSet = new Set(
+    (Array.isArray(linkedChanges) ? linkedChanges : [])
+      .map(normalizeGitPath)
+      .filter(Boolean)
+  )
+  if (changeName) ownChangeSet.add(normalizeGitPath(changeName))
+
+  // ownFiles 归一化集合：rule3 据此把本会话产出从他者业务文件中排除。
+  const ownFileSet = new Set(
+    (Array.isArray(ownFiles) ? ownFiles : [])
+      .map(normalizeGitPath)
+      .filter(Boolean)
+  )
+
+  const foreignFiles = []
+  const otherActiveSet = new Set()
+
+  for (const line of entries) {
+    // parsePorcelainPath：去引号 / 处理 rename / 归一化反斜杠（跨平台）。
+    const file = parsePorcelainPath(line)
+    if (!file) continue
+
+    // rule1：落 .sillyspec/changes/<dir>/ 且 <dir> 非本变更非关联 → otherActiveChanges 去重。
+    const dir = extractChangeDir(file)
+    if (dir && !ownChangeSet.has(normalizeGitPath(dir))) {
+      otherActiveSet.add(dir)
+      continue
+    }
+
+    // rule2：isQuickMetadata 为 true（quick 元数据 / 关联变更目录 / quicklog/.runtime/modules 等）→ 跳过。
+    // 注意：当前变更自己的 changes/<changeName>/ 也走这里——changeName 通常不在 linkedChanges，
+    // isQuickMetadata 视为元数据放行，与本变更自身目录不该当他者的语义一致。
+    if (isQuickMetadata(file, linkedChanges)) continue
+
+    // rule3：真实业务文件 → 不在 ownFiles 则归入他者 foreignFiles。
+    if (!ownFileSet.has(file)) {
+      foreignFiles.push(file)
+    }
+  }
+
+  const otherActiveChanges = [...otherActiveSet]
+  const hasForeign = foreignFiles.length > 0 || otherActiveChanges.length > 0
+  return { hasForeign, foreignFiles, otherActiveChanges, gitError: null }
+}
+
+/**
+ * 把检测结果格式化为多行 ⚠️ 警告串。
+ * @param {{ hasForeign: boolean, foreignFiles?: string[], otherActiveChanges?: string[], gitError?: string|null }|null} detected
+ * @returns {string|null} 无他者并发（hasForeign 为 false / null 输入）返回 null，调用点据此跳过 console.warn
+ */
+export function formatConcurrentWarning(detected) {
+  if (!detected || !detected.hasForeign) return null
+  const foreignFiles = Array.isArray(detected.foreignFiles) ? detected.foreignFiles : []
+  const otherActiveChanges = Array.isArray(detected.otherActiveChanges) ? detected.otherActiveChanges : []
+
+  const lines = ['⚠️ 检测到工作树存在并发他者改动（非阻断 advisory，请人工确认）：']
+
+  if (foreignFiles.length > 0) {
+    lines.push('他者业务文件（git-dirty，可能非本变更产出）：')
+    for (const f of foreignFiles) lines.push(`  - ${f}`)
+  }
+
+  if (otherActiveChanges.length > 0) {
+    // D-005：文案用「脏变更目录」+ git-dirty 标注，勿用「活跃」防与 DB active 状态混淆。
+    lines.push('他者脏变更目录（git-dirty，非 DB active）：')
+    for (const c of otherActiveChanges) lines.push(`  - ${c}`)
+  }
+
+  lines.push('提交请用显式 pathspec 隔离本变更文件，勿 git add . 扫入他者工作。')
+  return lines.join('\n')
+}

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,13 +111,24 @@ 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
-  const executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  let executeRunId = readFileSync(runIdFile, 'utf8').trim()
   const planContent = readFileSync(planPath, 'utf8')
-  const { validateCheckedTaskReviews } = await import('../task-review.js')
+  const { validateCheckedTaskReviews, resolveLatestExecuteRunIdWithTasks } = await import('../task-review.js')
+  // marker 漂移兜底（gate-atom-a 正确修法）：marker 指向的 run 缺 tasks/（generateExecuteRunId 只写
+  // marker 不建目录，漂移后新 run 不继承旧 review）时，无视 marker 改扫 execute-runs/ 取 mtime 最新
+  // 且真正含 tasks/ 的 run，用其齐备的 review.json 校验，避免误报「review.json 不存在」。注意不能用
+  // resolveLatestExecuteRunId——它见 marker 非空即原样返回（不校验目录），恰是本场景要绕开的值。
+  if (executeRunId && !existsSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'))) {
+    const relocated = resolveLatestExecuteRunIdWithTasks({ runtimeRoot })
+    if (relocated && relocated !== executeRunId) {
+      console.warn(`⚠️ execute run marker 漂移：${executeRunId} 无 tasks/，改用真实含 review 的 run ${relocated}`)
+      executeRunId = relocated
+    }
+  }
   const result = validateCheckedTaskReviews({ planContent, runtimeRoot, executeRunId })
   if (result.ok) return true
   if (steps && steps[currentIdx]) steps[currentIdx].status = 'blocked'
@@ -158,10 +172,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 +230,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 +271,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 +289,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 +331,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 +342,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 +398,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
+}
+