sillyspec 3.28.2 → 3.28.3

package/src/run/stage.js

@@ -21,6 +21,7 @@ import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles, mergeQuickBoundaryFiles, detectEmptyShellQuickSessions } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck, executeScanDetectProjects, executeScanResumeCheck, executeScanFinalize } from './scan-profile.js'
+import { executeProgressConfirm } from './progress-confirm.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
 import { createHash } from 'node:crypto'
@@ -537,6 +538,10 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         await executeScanFinalize(cwd, platformOpts)
       } else if (cliAction === 'planPostcheck') {
         await executePlanPostcheck(cwd, platformOpts, progress)
+      } else if (cliAction === 'progressConfirm') {
+        // 主流程 step1「进度确认」noAI 化（2026-09-07）：brainstorm/execute/verify——
+        // 快照本就 CLI 注入、阶段路由已由 run 落定，省一轮「复述摘要→--done」往返
+        executeProgressConfirm({ stageName, cwd, stageData, changeName, pm })
       } else {
         throw new Error(`noAI 步骤 ${stepName} 的未知 _cliAction: ${cliAction}——请在 stage.js 注册对应分支`)
       }
@@ -552,6 +557,8 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         // 所有步骤完成
         stageData.status = 'completed'
         stageData.completedAt = new Date().toLocaleString('zh-CN', { hour12: false })
+        // 主阶段完成钉 currentStage（troubleshooting #56 根因修复，2026-09-08；与 complete.js 两处同语义）
+        if (!AUXILIARY_STAGES.includes(stageName)) progress.currentStage = stageName
         // persist _write 移到 completeStageGates 成功之后（task-02 / review-2026-08-09 #2）：gate 异常/失败 → rollback 回 in-progress 落盘，此处未到 _write，DB 不留假 completed。
         // 阶段完成收尾共享管线（noAI 末步核心修复 S1：plan postcheck independent-tier review verdict=fail /
         // 平台 scan manifest 此前被绕过）。gate 失败已 rollback 为 in-progress，early-return（不 fall through 到末尾 return）。

package/src/scan-postcheck.js

@@ -42,7 +42,11 @@ function checkScanDocRefs(cwd, scanDir, docs) {
     severity: CHECK_SEVERITY.WARNING,
     detail: `${invalid.length} 条 file:line 引用未通过核验（${totalRefs} 条中）: ${sample}${invalid.length > 3 ? ` 等 ${invalid.length} 条` : ''}`,
     evidence: { invalidCount: invalid.length, totalRefs, skippedCrossRepo, checkedDocs: docs.length, sample: invalid.slice(0, 3) },
-    supportedFixes: ['运行 sillyspec docs check --suggest 查看候选锚点后修正引用', '删除无法核验的引用（引用了不存在的文件/行号）'],
+    supportedFixes: [
+      'sillyspec docs check --paths <该文档> --dry-run  查看候选锚点（fixable 条目会给出 newLine），确认后去 --dry-run 落盘重锚',
+      'sillyspec docs check --paths <该文档> --fix  对 fixable 引用自动重锚（回执附修复前后失效数对比）',
+      '先跑 sillyspec docs check --paths <该文档> 确认零候选锚点后，再删除确认无法核验的引用行',
+    ],
   }
 }
 

package/src/stages/brainstorm-auto.js

@@ -28,7 +28,8 @@ export const definition = {
 ### 加载上下文
 4. 读取项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）+ 共享规范 + 子项目上下文
 5. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
-6. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
+6. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 7. 棕地项目：读取 scan 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
 8. 加载模块索引：读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（如存在）
 9. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`

package/src/stages/brainstorm.js

@@ -7,22 +7,13 @@ export const definition = {
       name: '进度确认',
       // 重命名自「状态检查」（③ status 消歧）：老进度里的「状态检查」completed 由迁移逻辑承接，防 currentIdx 回跳
       migratedFrom: ['状态检查'],
-      prompt: `检查当前变更的进度状态（快照已由 CLI 注入，勿再跑 progress show——那是全量输出，浪费上下文；\`sillyspec status\` 是项目级快照，也不推进流程）。
-
-### 进度快照（CLI 注入）
-{PROGRESS_SNAPSHOT}
-
-### 操作
-1. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
-2. 如果快照显示阶段不符或未初始化，输出正确提示并停止
-
-### 输出
-当前状态摘要（1-2 句话）
-
-### 注意
-- 以 CLI 注入快照为准，不要自行推断阶段
-- **不要用 mv 命令重命名变更目录**，必须使用 \`sillyspec change-rename\`，否则 DB 和目录会脱节`,
-      outputHint: '状态摘要',
+      // noAI 化（2026-09-07）：快照本就 CLI 注入、阶段路由由 run 落定、变更名自动生成检测为机械
+      // 正则（命中只打印 rename 建议，agent 在工具结果可见、可在后续步骤交互改名）——省一轮
+      // 复述往返。步骤名保持不变（存量进度库按名匹配迁移）。
+      noAI: true,
+      _cliAction: 'progressConfirm',
+      prompt: '',
+      outputHint: '状态摘要（CLI 快照输出）',
       optional: false
     },
     {
@@ -34,7 +25,8 @@ export const definition = {
    - 漂移事实（CLI 算）：{SCAN_STALENESS}
    - 机械事实底稿（CLI 注入，无 scan 底稿则为空）：{SCAN_FACTS}
 2. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`
-3. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`
+3. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 4. 棕地项目：读取 {SPEC_ROOT}/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
 5. **加载模块索引**：读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（如存在）
    - 这一步是高频操作，_module-map.yaml 回答"哪个文件属于哪个模块、模块之间怎么依赖"

package/src/stages/execute.js

@@ -220,18 +220,12 @@ const fixedPrefix = [
   {
     name: '进度确认',
     migratedFrom: ['状态检查'],
-    prompt: `检查当前进度，确认可以执行 execute（快照已由 CLI 注入，勿再跑 progress show；\`sillyspec status\` 是项目级快照，也不推进流程）。
-
-### 进度快照（CLI 注入）
-{PROGRESS_SNAPSHOT}
-
-### 操作
-1. 如果快照显示不是 execute 阶段 → 检查是否有未完成的 tasks.md
-2. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
-
-### 输出
-当前状态 + 执行范围确认`,
-    outputHint: '当前状态 + 执行范围',
+    // noAI 化（2026-09-07）：快照复述/阶段检查机械化（progressConfirm 补 tasks 勾选计数）；
+    // 执行范围是会话层信息（$ARGUMENTS 不经 CLI），以用户会话指定为准。步骤名不变。
+    noAI: true,
+    _cliAction: 'progressConfirm',
+    prompt: '',
+    outputHint: '当前状态 + 执行范围（CLI 快照输出）',
     optional: false
   },
   {
@@ -242,7 +236,8 @@ const fixedPrefix = [
 1. 读取 tasks.md（任务注册表与勾选唯一真相；plan.md 只提供 Wave 分组/依赖结构——Wave 段下为纯 ID 引用行）
 2. 读取 design.md（技术方案）
 3. 读取 CONVENTIONS.md、ARCHITECTURE.md
-4. 读取 local.yaml（构建命令）；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+4. 构建命令（CLI 自 local.yaml 注入，勿再读文件；未配置时按注入说明跑 local detect）：
+{LOCAL_COMMANDS}
 5. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）
 
 ### 模块文档加载（细粒度卡优先——CLI 已按 tasks 卡 allowed_paths 级联匹配）
@@ -378,7 +373,8 @@ review.json 已落盘（checklist=逐项核验表）+ checklist 摘要与偏差
 本步骤由当前 agent 执行，不需要启动独立子代理。
 
 ### 操作
-1. 读取 local.yaml 获取构建和测试命令；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+1. 构建命令（CLI 自 local.yaml 注入，勿再读文件；未配置时按注入说明跑 local detect）：
+{LOCAL_COMMANDS}
 2. 运行测试套件（单元测试、集成测试）
 3. 运行 lint 检查 **+ 格式化**：凡变更涉及的源码，既跑 lint check 也跑 formatter（如 \`ruff format\` / \`prettier --write\` / \`black\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截
 4. 如果有测试失败 → 分析原因，标注是代码问题还是测试本身的问题

package/src/stages/plan.js

@@ -63,7 +63,8 @@ const stepClassify = {
    - 如果发现 priority=P0/P1 且 status=unresolved/blocking 的决策，停止生成计划，要求先回到 brainstorm 的 Design Grill 修正
    - 如果发现 superseded 决策，只引用最新版本，不引用旧版本
 5. 读取 CONVENTIONS.md、ARCHITECTURE.md（技术栈含在 ARCHITECTURE.md）
-6. 读取 local.yaml 获取构建/测试命令
+6. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 7. 读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（不存在则跳过）
    - 根据 design.md 的文件变更清单匹配模块
    - 读取匹配到的模块文档

package/src/stages/quick.js

@@ -23,7 +23,8 @@ step 3 --done 审计会把 src 核心文件（CLI / 状态机 / 注入框架等
 2. 理解任务：模糊则问一个问题确认
 3. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`（了解项目结构和技术栈）
 4. 加载上下文：\`cat {SPEC_ROOT}/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
-5. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`（构建命令、测试命令、环境变量等）
+5. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 6. 若有关联变更，加载每个变更的设计文档：\`cat {SPEC_ROOT}/changes/<c>/design.md 2>/dev/null\`（理解设计意图）
 7. 如有需要，查询知识库：\`cat {SPEC_ROOT}/knowledge/INDEX.md 2>/dev/null\`
 
@@ -121,7 +122,8 @@ sillyspec run quick --done --change <id> --req "…" --cause "…" --solution "
 3. 【--done 后】核对 QUICKLOG 标题（CLI 已从「需求：」自动提取，仅弱标题才手改）→ 若改了再 \`git add\`
 
 ### 操作
-1. 查看 \`git status --porcelain\`，确认只包含本次 quick 相关文件
+1. 工作区脏文件（CLI 注入，勿重跑 \`git status\`）——确认只包含本次 quick 相关文件，无关改动不暂存：
+{GIT_DIRTY}
 2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）
    - 禁止使用 \`git add -A\`
    - 不要暂存 quick 开始前就已存在的无关改动

package/src/stages/verify.js

@@ -45,19 +45,12 @@ export const definition = {
     {
       name: '进度确认',
       migratedFrom: ['状态检查'],
-      prompt: `> 💡 先说清楚：\`sillyspec run verify\`（不带 --done）**只下发执行指令，不会替你跑测试/构建**——真正的测试由 CLI 在最后 --done 时统一执行（local.yaml 的 commands.test，同步对账可能耗时较长）；「运行测试和质量扫描」那步**不需要你重复手动跑全量**（避免与 CLI 对账重复耗时），只做 lint/静态检查 + 可选快速冒烟。别以为敲了 run verify 就自动验证了。
-
-检查当前进度，确认可以执行 verify（快照已由 CLI 注入，勿再跑 progress show；\`sillyspec status\` 是项目级快照，也不推进流程）。
-
-### 进度快照（CLI 注入）
-{PROGRESS_SNAPSHOT}
-
-### 操作
-1. 如果快照显示阶段不符，输出正确提示并停止
-
-### 输出
-当前进度摘要`,
-      outputHint: '进度摘要',
+      // noAI 化（2026-09-07）：唯一非常量信息（「CLI 在 --done 统一跑测试」）改由 progressConfirm
+      // console 提示；快照复述与阶段检查已机械化。步骤名不变（存量进度库按名匹配迁移）。
+      noAI: true,
+      _cliAction: 'progressConfirm',
+      prompt: '',
+      outputHint: '进度摘要（CLI 快照输出）',
       optional: false
     },
     {
@@ -70,7 +63,8 @@ export const definition = {
    - 如果存在 P0/P1 unresolved/blocking 决策，验证结论不能为 PASS
    - 如果发现 superseded 决策被下游引用，标记为 ⚠️ stale decision reference
 3. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`
-4. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`（构建命令、测试命令、lint 命令等）若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+4. 构建命令（CLI 自 local.yaml 注入，勿再读文件；未配置时按注入说明跑 local detect）：
+{LOCAL_COMMANDS}
 5. 加载代码规范：\`cat {SPEC_ROOT}/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
    - 测试现状：\`cat {SPEC_ROOT}/docs/<project>/scan/TESTING.md 2>/dev/null\`（了解既有测试约定与覆盖范围，验收时对照）
    - 技术债清单：\`cat {SPEC_ROOT}/docs/<project>/scan/CONCERNS.md 2>/dev/null\`（🔴/🟡 区域；本次变更若触碰须在 verify-result.md 标注）
@@ -104,6 +98,9 @@ export const definition = {
       name: '逐项检查任务',
       prompt: `对照 tasks.md（任务注册表唯一真相）检查每个任务完成状态。勾选由 execute 双路写入（agent 按 review gate 手动勾 + CLI autoCheckPlanFromReviews 机器勾选器按 review.json 自动勾），本阶段只读对照、不改勾。
 
+### 勾选状态（CLI 注入，勿手数）
+{TASKS_CHECKBOX}
+
 ### 操作
 对每个 checkbox：
 1. 检查相关文件是否存在
@@ -173,7 +170,8 @@ export const definition = {
       prompt: `运行代码质量扫描（测试实测统一由 CLI 对账执行，本步不重复手动跑全量）。
 
 ### 操作
-1. 读取 \`{SPEC_ROOT}/local.yaml\` 获取构建、测试和 lint 命令若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+1. 构建命令（CLI 自 local.yaml 注入，勿再读文件；未配置时按注入说明跑 local detect）：
+{LOCAL_COMMANDS}
 2. **不要手动重复跑 commands.test**——CLI 会在最终 --done 时统一执行一次（按变更命中模块子集），本步再跑 = 与 CLI 对账重复耗时（实测 198s×2）。如为提前发现实现问题，可对变更模块做**针对性快速冒烟**（可选，非必需）：
    - Maven：\`mvn test -pl <变更模块> -am\`（仅编译变更模块及其依赖）
    - Gradle：\`./gradlew :<模块>:test\`

package/src/task-review.js

@@ -1468,6 +1468,206 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
   return { adopted, unchanged, skipped, missing, downgraded, reasons, executeRunId }
 }
 
+/**
+ * writeTaskReview —— 单 task review.json 的命令式写入（`sillyspec review write`，2026-09-07）。
+ *
+ * 背景（noAI 主流程批次 T2-4）：task 级 review.json 此前由 agent/子代理手拼 JSON + 手算
+ * base/head + 手抄 changedFiles——schemaVersion/目录创建/executeRunId 解析/git 锡点全部是
+ * 纯机械活（generateTaskReviewDrafts/adoptTaskReviewMechanics 已证明 CLI 可代算），agent 只
+ * 应贡献判断字段（verdict/notes/evidence）。命令式写入消灭「手拼 JSON→gate 拒→重写」循环。
+ *
+ * 职责分工：
+ *   - CLI 代算（mechanics）：executeRunId（marker 优先）、base/head（worktree meta 优先，
+ *     --base/--head 显式覆盖）、changedFiles（diff × allowed_paths 归属切片，--changed-files
+ *     显式覆盖）、diffPaths（allowed_paths 非空时）、repo 锡点（task 卡）。
+ *   - agent 供给（判断）：--spec/--quality verdict、--notes、--evidence。
+ *
+ * 防伪/防误写：
+ *   - review.json 已存在 → 拒绝覆盖（--force 显式越过，控制台留痕）——保护独立 reviewer 产物。
+ *   - verdict=cannot_verify 且未给 --evidence → 报错（schema 硬要求非空 requiredEvidence），
+ *     不静默填占位（与草稿语义不同：草稿是兜底待复核，这里是 agent 明确结论）。
+ *   - 归属切片为空（allowed_paths 未命中 diff）→ 报错并列出 diff 候选与 task allowed_paths
+ *     （帮 agent 当场发现「改了声明外文件 / 路径写错」），--changed-files 显式越过。
+ *
+ * @param {object} opts
+ * @param {string} opts.changeName
+ * @param {string} opts.cwd
+ * @param {string} opts.taskId - 形如 task-NN
+ * @param {string} opts.specVerdict - pass | fail | cannot_verify
+ * @param {string} opts.qualityVerdict - 同上
+ * @param {string} [opts.reviewerNotes]
+ * @param {string[]} [opts.requiredEvidence]
+ * @param {string|null} [opts.baseOverride] - 显式 base 锡点（无 worktree meta 时必填）
+ * @param {string|null} [opts.headOverride]
+ * @param {string[]|null} [opts.changedFilesOverride]
+ * @param {boolean} [opts.force] - 覆盖已存在 review.json
+ * @param {object} [opts.platformOpts]
+ * @returns {Promise<{ok: boolean, reviewPath?: string, executeRunId?: string, errors: string[], warnings: string[]}>}
+ */
+export async function writeTaskReview({
+  changeName, cwd, taskId, specVerdict, qualityVerdict,
+  reviewerNotes = '', requiredEvidence = [],
+  baseOverride = null, headOverride = null, changedFilesOverride = null,
+  force = false, platformOpts = {},
+}) {
+  const errors = []
+  const warnings = []
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+  const changeDir = join(specBase, 'changes', changeName)
+
+  // ── 入参校验 ──
+  if (!changeName || typeof changeName !== 'string') errors.push('缺少 --change <变更名>')
+  if (!taskId || !/^task-\d+$/.test(taskId)) errors.push(`--task 格式应为 task-NN（实际 ${taskId}）`)
+  if (!VALID_VERDICTS.includes(specVerdict)) errors.push(`--spec verdict 无效：${specVerdict}（应为 ${VALID_VERDICTS.join('/')}）`)
+  if (!VALID_VERDICTS.includes(qualityVerdict)) errors.push(`--quality verdict 无效：${qualityVerdict}（应为 ${VALID_VERDICTS.join('/')}）`)
+  if ((specVerdict === 'cannot_verify' || qualityVerdict === 'cannot_verify')
+    && (!Array.isArray(requiredEvidence) || requiredEvidence.filter(Boolean).length === 0)) {
+    errors.push('verdict=cannot_verify 必须给 --evidence "<非空说明>"（schema 硬要求 requiredEvidence 非空）')
+  }
+  if (errors.length > 0) return { ok: false, errors, warnings }
+
+  // ── task 卡与 executeRunId 解析（与草稿生成同源）──
+  const taskCardPath = join(changeDir, 'tasks', `${taskId}.md`)
+  if (!existsSync(taskCardPath)) {
+    return { ok: false, errors: [`task 卡不存在：${taskCardPath}（先由 plan 阶段生成或手建）`], warnings }
+  }
+  const markerFile = join(runtimeRoot, 'current-execute-run-id-' + changeName)
+  let executeRunId = ''
+  try {
+    if (existsSync(markerFile)) {
+      const c = readFileSync(markerFile, 'utf8').trim()
+      if (isValidExecuteRunId(c)) executeRunId = c
+    }
+  } catch {}
+  if (!executeRunId) {
+    executeRunId = resolveLatestExecuteRunId({ runtimeRoot, changeName }) || ''
+  }
+  if (!executeRunId) {
+    executeRunId = generateExecuteRunId()
+    warnings.push(`无 execute run marker——已生成新 runId ${executeRunId} 并建目录（正常应先跑过 execute Wave 步）`)
+    try {
+      mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
+      writeFileSync(markerFile, executeRunId + '\n')
+      stampExecuteRunChange(runtimeRoot, executeRunId, changeName)
+    } catch (e) {
+      return { ok: false, errors: [`execute run 目录/marker 写入失败：${e.message}`], warnings }
+    }
+  }
+
+  const reviewDir = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId)
+  const reviewPath = join(reviewDir, 'review.json')
+
+  // ── 已存在保护（--force 越过）──
+  if (existsSync(reviewPath) && !force) {
+    return { ok: false, errors: [`review.json 已存在：${reviewPath}——拒绝覆盖（保护既有 reviewer 结论）；确认重写加 --force`], warnings }
+  }
+  if (existsSync(reviewPath)) warnings.push(`--force 覆盖已存在 review：${reviewPath}`)
+
+  // ── mechanics 代算：base/head（worktree meta 优先，显式覆盖次之）──
+  let base = baseOverride
+  let head = headOverride
+  let reviewGitDir = cwd
+  if (!base || !head) {
+    try {
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (!base) base = (meta && (meta.baselineCommit || meta.baseHash)) || null
+      if (meta && meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
+        reviewGitDir = meta.worktreePath
+      }
+    } catch { /* meta 读取失败走显式覆盖路径 */ }
+  }
+  if (!head) {
+    try { head = runGit(reviewGitDir, ['rev-parse', 'HEAD']) } catch { head = null }
+  }
+  if (!base || !head) {
+    return {
+      ok: false,
+      errors: [`无法确定 base/head（无 worktree meta 且未显式覆盖）——用 --base <commit> --head <commit> 显式给出（git rev-parse 取值）`],
+      warnings,
+    }
+  }
+
+  // ── mechanics 代算：changedFiles（diff × allowed_paths 归属切片；显式覆盖优先）──
+  const content = readFileSync(taskCardPath, 'utf8')
+  // 跨仓 task 守卫：base/head/changedFiles 的跨仓口径（task 卡锡点 + 跨仓仓 diff）本函数未实现
+  //（草稿生成有专门分支）——显式拒绝并引导既有路径，防主仓锡点被误配到跨仓改动上
+  const guardRepo = normalizeRepoKey(parseRepo(content))
+  if (guardRepo && guardRepo !== 'main') {
+    return {
+      ok: false,
+      errors: [`task 卡声明 repo=${guardRepo}（跨仓 task）——review write 暂不支持跨仓口径，请手写 review.json 后跑 sillyspec backfill-reviews --change ${changeName} --adopt 代填 mechanics（base/head 从 task 卡锡点取）`],
+      warnings,
+    }
+  }
+  const allowedPaths = parseAllowedPaths(content)
+  let changedFiles = null
+  if (Array.isArray(changedFilesOverride)) {
+    // 显式覆盖（含空数组=纯验证任务的合法零 diff 声明）
+    changedFiles = changedFilesOverride.map(p => String(p).replace(/\\/g, '/'))
+    warnings.push(`changedFiles 采用显式覆盖（${changedFiles.length} 个）——evidence 校验仍会与 git diff 相交比对`)
+  } else {
+    let diffFiles = resolveVerifyChangedFiles(cwd, changeName, null, { specBase })
+    // 并入 worktree 未提交改动（与草稿生成同源口径：子代理默认不 commit）
+    try {
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (meta) {
+        const wtGitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+          ? meta.worktreePath
+          : cwd
+        const wtStatus = runGit(wtGitDir, ['status', '--porcelain', '--untracked-files=all'], { trim: false })
+        const wtFiles = parsePorcelainFiles(wtStatus)
+          .map(p => String(p).replace(/\\/g, '/'))
+          .filter(p => p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
+        if (wtFiles.length > 0) diffFiles = [...new Set([...(Array.isArray(diffFiles) ? diffFiles : []), ...wtFiles])]
+      }
+    } catch { /* 退回 commit diff 口径 */ }
+    const mainDiff = Array.isArray(diffFiles) ? diffFiles : []
+    changedFiles = allowedPaths.length > 0
+      ? mainDiff.filter(f => allowedPaths.some(p => pathMatches(f, p)))
+      : []
+    if (changedFiles.length === 0) {
+      return {
+        ok: false,
+        errors: [
+          `归属切片为空：task 卡 allowed_paths ${JSON.stringify(allowedPaths)} 未命中本次 diff 任何文件。` +
+          `本变更 diff 共 ${mainDiff.length} 个文件：${mainDiff.slice(0, 10).join('、')}${mainDiff.length > 10 ? '…' : ''}。` +
+          `确认改动确属本 task → 用 --changed-files <a,b> 显式给出；纯验证任务（无代码 diff 是本质属性）用 --changed-files ""（空覆盖）+ --evidence 披露验证区间`,
+        ],
+        warnings,
+      }
+    }
+  }
+
+  // ── 组装 + schema 自检 + 落盘 ──
+  const review = {
+    schemaVersion: REVIEW_SCHEMA_VERSION,
+    task: taskId,
+    base,
+    head,
+    changedFiles,
+    ...(allowedPaths.length > 0 ? { diffPaths: allowedPaths } : {}),
+    specVerdict,
+    qualityVerdict,
+    ...(requiredEvidence.filter(Boolean).length > 0 ? { requiredEvidence: requiredEvidence.filter(Boolean) } : {}),
+    reviewerNotes: reviewerNotes || `written by sillyspec review write (${base.slice(0, 8)}..${head.slice(0, 8)})`,
+  }
+  const schemaResult = validateReviewSchema(review)
+  if (!schemaResult.ok) {
+    return { ok: false, errors: schemaResult.errors, warnings }
+  }
+  try {
+    mkdirSync(reviewDir, { recursive: true })
+    writeFileSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
+  } catch (e) {
+    return { ok: false, errors: [`review.json 落盘失败：${e.message}`], warnings }
+  }
+  return { ok: true, reviewPath, executeRunId, errors: [], warnings }
+}
+// 注：跨仓 task（repo≠main）在上方 mechanics 段前置守卫拒绝——review.repo 恒为 main，不再单独赋值
+
 /**
  * 获取当前（或最新）execute run id
  * 从 runtime 目录下查找 execute-runs/ 子目录