sillyspec 3.26.14 → 3.27.1

package/src/stages/verify.js

@@ -172,11 +172,11 @@ export const definition = {
    - Gradle：\`./gradlew :<模块>:test\`
    - npm/pnpm：\`pnpm test --filter=<包名>\` 或 \`npm test -- --testPathPattern=<相关文件>\`
    - Python：\`pytest <变更模块路径>/\`
-3. 如果 local.yaml 有 lint 命令，运行 lint 检查
+3. 如果 local.yaml 有 lint 命令，运行 lint 检查并修复报出的问题（--done 时 CLI 会亲自实测 commands.lint 对账，实测失败会明示）
 4. 搜索技术债务：grep TODO/FIXME/HACK/XXX（仅限变更文件）
 
 ### 注意
-- **CLI 对账机制**：verify 阶段最终 --done 时，CLI 会亲自执行 local.yaml 的 commands.test（同步，耗时可能较长）；实测失败会直接阻断 verify 完成，谎报测试结果没有意义
+- **CLI 对账机制**：verify 阶段最终 --done 时，CLI 会亲自执行 local.yaml 的 commands.test（同步，耗时可能较长）；实测失败会直接阻断 verify 完成，谎报测试结果没有意义。commands.lint 同样会被 CLI 实测对账（advisory）
 - 冒烟测试非必需：全量/模块实测结果以 CLI 对账为准，本步跑的结果仅供你提前发现问题并写入验证报告
 
 ### 输出
@@ -197,57 +197,22 @@ export const definition = {
    你只需：在 verify-result.md 的「变更风险等级」section 如实记录变更性质；若变更涉及 daemon/backend 跨进程、session/lease/lifecycle 状态机、或部署启动路径，在「Runtime Evidence」section 提供真实集成证据（启动命令、daemon↔backend 调用与日志关键片段、终态断言）。
    - **集成证据是自报告、CLI 不独立运行时核验**：「Runtime Evidence」由你如实填写，CLI 只校验其**字面存在**（是否含关键词），**不会替你启动 daemon、打真实请求或跑迁移**——它是否名副其实取决于你是否实跑过。务必实跑后据实填写，不得凭堆关键词通过门控。（测试套件对账另算：commands.test 由 CLI 真实执行，那块谎报无效。）
 
-3. 生成 verify-result.md 文件，保存到 \`.sillyspec/changes/<change-name>/verify-result.md\`
-4. 给出结论：PASS / PASS WITH NOTES / FAIL（受风险门控约束）
+3. **生成 verify-result.md 骨架（勿从零手写）**：先跑 \`sillyspec verify-probes --change <change-name> --init\`——一条命令生成九章节骨架（已存在不覆盖），其中**探针结果章节已机械预填**（探针 1 的 TODO/FIXME 命中清单、探针 3 的测试覆盖、探针 5 的 API 契约对账表、探针 6 的删除对账三态判定），文件落 \`.sillyspec/changes/<change-name>/verify-result.md\`。你只需把各 \`<!--TODO-->\` 占位替换为语义结论；半语义探针（2 关键词覆盖 / 4 决策追踪）与断言抽查、集成盲区标注由你补在对应 TODO 处
+4. 给出结论：PASS / PASS WITH NOTES / FAIL（受风险门控约束）——**结论必须写明 PASS/FAIL 字样，留「待填」会被 gate 判不过**
 5. **核对 module-impact.md**（若 changes/<change>/module-impact.md 存在）：对照本次实际代码变更（git diff）与 module-impact.md 的模块影响矩阵，发现不一致（漏标受影响模块 / 影响类型错误 / 实际未触碰的模块被误标）则在 verify-result.md 标注。module-impact 由 plan 首版生成、execute 各 Wave 更新，verify 是最后一次核对机会（archive 仅终审不再生成）。这是 advisory 核对（不阻断 verify 完成），但 module-impact 与实际严重背离应记为风险。
 
-### verify-result.md 格式
-\`\`\`markdown
-# 验证报告（Verify Result）
-
-## 结论
-PASS / PASS WITH NOTES / FAIL
-
-## 任务完成度
-（逐项检查任务的结果）
-
-## 设计一致性
-（对照 design.md 的检查结果）
-
-## 探针结果
-- 未实现标记扫描：...
-- 关键词覆盖：...
-- 测试覆盖（含断言有效性抽查）：...
-- 决策追踪覆盖：...
-- API 契约对账：...
-- 代码删除对账：声明修改/新增却被整文件删除 = 高风险；清单未列出的删除 = 未声明（CLI 会用 git diff --name-status HEAD advisory 复核，仅 warn 不阻断——是否 FAIL blocker 由你诚实判定）
-
-## 决策追踪矩阵（如存在 decisions.md）
-| 决策 ID | FR | Task | Evidence | 状态 |
-|---|---|---|---|---|
-| D-001@v1 | FR-01 | task-01 | test/file/path | PASS/PARTIAL/MISSING |
-
-## 测试结果
-（测试套件执行结果）
-
-## 技术债务
-（TODO/FIXME/HACK 统计）
-
-## 变更风险等级
-（自动检测的 change_risk_profile: doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical；若 design.md frontmatter 有 risk_level 显式声明，以声明为准并在此注明「显式声明 = <等级>」+ 理由）
-
-## Runtime Evidence（integration-critical / deployment-critical 必填；自报告，CLI 仅校验字面存在、不独立核验，须真实执行过）
-按本次变更实际触碰的运行时组件填写（模板是通用形态——长驻进程 / 服务端点 / 生命周期状态机的证据结构；未涉及的行写「不涉及」并注明原因，勿堆砌无关关键词）：
-- 长驻进程/服务 启动命令：
-- 服务地址（本变更触碰的端点）：
-- 触发核心路径的请求/命令（附关键响应）：
-- 进程日志关键片段（证明走了新路径、无降级/回退分支）：
-- 生命周期终态断言（本变更涉及的状态机：初始态 → 运行态 → 终态，逐个确认到达）：
-- 失败模式排除（针对本变更声明的风险，逐条说明为何未触发）：
-
-## 代码审查
-（问题列表 + 总体评价）
-\`\`\`
+### verify-result.md 章节结构（骨架已含，占位替换即可）
+
+结论（PASS / PASS WITH NOTES / FAIL）→ 任务完成度 → 设计一致性 → 探针结果（已预填）→ 测试结果 → 决策追踪矩阵（\`| 决策 ID | FR | Task | Evidence | 状态 |\`，存在 decisions.md 才留）→ 技术债务 → 变更风险等级 → Runtime Evidence → 代码审查。
+
+**Runtime Evidence 行结构**（integration/deployment-critical 必填；按实际触碰的运行时组件写，未涉及的行写「不涉及」勿堆关键词）：长驻进程启动命令 / 触碰的服务端点 / 触发核心路径的请求（附关键响应）/ 进程日志关键片段（证明走了新路径）/ 生命周期终态断言（初始态→运行态→终态）/ 失败模式排除（逐条说明为何未触发）。
+
+### 🧹 服务进程登记与自动回收（真实启动验证必读，坑 verify-service-process-leak）
+「真实启动一次」起的长驻服务（uvicorn/node server 等）**必须登记 PID，CLI 在 verify 收尾自动回收**——不登记的进程会挂死机器（实测 uvicorn 漏挂一天多）：
+1. 后台启动服务并取 PID（PowerShell：\`Start-Process -PassThru\` 取 \`.Id\`；bash：\`cmd & echo $!\`）
+2. 每行一个 PID 追加到 \`\${SPEC_ROOT}/.runtime/verify-services.pids\`（\`Add-Content\` / \`echo >>\`）
+3. verify \`--done\` 时 CLI 读该文件逐个 kill 并清空——你在 verify-result.md 的「生命周期终态断言」里写「PID 已登记，CLI 收尾回收」即可
+登记是硬要求：没有 PID 登记的「真实启动」证据在 deployment-critical 门控下视为不完整（进程无法证明被回收）。
 
 ### 输出
 verify-result.md 路径 + 验证报告摘要 + 下一步命令

package/src/sync.js

@@ -13,6 +13,7 @@ import { writeAtomicSync } from './fs-atomic.js';
 import { join } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
 import { safeGit } from './git-helper.js';
+import { openDatabase } from './db-engine.js';
 import { PLATFORM_MANAGED_FILENAME } from './run/shared.js';
 import { syncSpecTree } from './spec-sync.js';
 
@@ -267,6 +268,9 @@ async function fetchJsonWithStatus(url, options = {}) {
 export class SyncManager {
   constructor(cwd) {
     this.cwd = cwd;
+    // 归档尾声静默化旗标（坑 post-archive-sync-noise）：sync() 探测到已归档时置位，
+    // 链内 syncDocuments 的「变更不存在」降 debug（每次 sync 调用重置）
+    this._suppressDocsMissingWarn = false;
   }
 
   /**
@@ -411,12 +415,24 @@ export class SyncManager {
       return { synced: 0, errors: ['未指定变更名称'] };
     }
 
-    // 检查变更目录是否存在（warn 不拦：归档后目录已移走但 DB 仍有最终状态需推平台，
-    // serializeForSync 从 DB 读不依赖文件系统目录；目录存在时 warn 也无害，仅辅助排查）
+    // 检查变更目录是否存在（归档后目录已移走但 DB 仍有最终状态需推平台，serializeForSync 从
+    // DB 读不依赖文件系统目录）。归档终态探测（坑 post-archive-sync-noise，2026-08-21 实证：
+    // 归档尾声连打「目录不存在/变更不存在」warn，观感像出错）：确认已归档（changes/archive/
+    // 有实体 或 DB status='archived'）时降为一行 info 措辞——正常时序不是告警。
     const changeDir = join(this.cwd, CHANGES_DIR, changeName);
+    let archivedQuietly = false;
     if (!existsSync(changeDir)) {
-      console.warn(`[sync] 变更目录不存在（可能是已归档，继续从 DB 同步最终状态）: ${changeName}`);
+      archivedQuietly = existsSync(join(this.cwd, CHANGES_DIR, 'archive', changeName))
+        || this._isChangeArchivedInDb(changeName);
+      if (archivedQuietly) {
+        console.log(`[sync] 变更已归档（目录在 archive/），继续从 DB 推送最终状态: ${changeName}`);
+      } else {
+        console.warn(`[sync] 变更目录不存在（可能是已归档，继续从 DB 同步最终状态）: ${changeName}`);
+      }
     }
+    // 透传给本次 sync 链内的 syncDocuments（best-effort 四件套直推：归档后目录已移走，
+    // 其「变更不存在」warn 属正常时序，静默化）
+    this._suppressDocsMissingWarn = archivedQuietly;
 
     const MAX_PUSH_ATTEMPTS = 2;
     for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
@@ -617,6 +633,12 @@ export class SyncManager {
     // 返回值 → 文档在平台模式下静默永不同步。
     const changeDir = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), 'changes', changeName);
     if (!existsSync(changeDir)) {
+      // 归档尾声静默化（坑 post-archive-sync-noise）：sync() 链内调用（_suppressDocsMissingWarn
+      // 置位，目录已移 archive/ 的正常时序）降为 debug；独立调用（手动 sync-docs）保留 warn
+      if (this._suppressDocsMissingWarn) {
+        debugLog(`[sync] 四件套目录不存在（变更已归档，跳过文档直推）: ${changeName}`);
+        return { synced: 0, errors: [] };
+      }
       console.warn(`[sync] 变更不存在: ${changeName}`);
       return { synced: 0, errors: [`变更不存在: ${changeName}`] };
     }
@@ -734,6 +756,25 @@ export class SyncManager {
     return config.platform || null;
   }
 
+  /**
+   * DB 侧归档态探测（坑 post-archive-sync-noise）：changes 表 status='archived' 即真。
+   * 只读直查（node:sqlite，不经 ProgressManager——sync 是短进程，惰性 import 无收益且
+   * 本调用点在同步代码段）；DB 不存在/无行/读失败 → false（保守退回普通 warn 措辞）。
+   * @param {string} changeName
+   * @returns {boolean}
+   */
+  _isChangeArchivedInDb(changeName) {
+    try {
+      const dbPath = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), '.runtime', 'sillyspec.db');
+      if (!existsSync(dbPath)) return false;
+      const db = openDatabase(dbPath, { readOnly: true });
+      try {
+        const row = db.prepare("SELECT status FROM changes WHERE name = ?").get(changeName);
+        return row?.status === 'archived';
+      } finally { try { db.close() } catch {} }
+    } catch { return false }
+  }
+
   /**
    * 写冲突文件 .runtime/sync-conflict-<change>.json（task-12 / D-002 / D-008 / D-010 / FR-05）。
    * push 409 与 pull 本地脏度双向冲突命中时调用，强制提示用户走 platform resolve 三选一。

package/src/task-review.js

@@ -10,7 +10,7 @@
 
 import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs'
 import { join, resolve } from 'path'
-import { git } from './git-helper.js'
+import { git, unquoteGitPath } from './git-helper.js'
 import { pathMatches } from './change-list.js'
 import { parseAllowedPaths, parseRepo, parseBaseCommit, parseHeadCommit } from './stages/plan-postcheck.js'
 import { resolveVerifyChangedFiles } from './verify-postcheck.js'
@@ -378,6 +378,30 @@ function isTaskLowRisk(changeDir, taskId) {
   }
 }
 
+/**
+ * 纯验证 task 判定（坑 verification-task-zero-diff，2026-08-21 实证）：task-10/11 类
+ * 「跑测试/部署验证/观测确认」型任务无代码 diff 是本质属性而非伪造——emptyDiff 判伪造
+ * 对它们必误杀，此前只能引用验证区间并手工披露归属绕过。task 卡 frontmatter 显式声明
+ * `task_type: verification`（或 `verification_only: true`）即走合法零 diff 通道：
+ * emptyDiff 不判伪造（转 warning），但 review 必须带非空 requiredEvidence（披露验证
+ * 区间/结论出处）——不能拿声明逃掉披露义务。
+ * @returns {boolean}
+ */
+function isTaskVerification(changeDir, taskId) {
+  if (!changeDir) return false
+  const taskFile = join(changeDir, 'tasks', `${taskId}.md`)
+  if (!existsSync(taskFile)) return false
+  try {
+    const content = readFileSync(taskFile, 'utf8')
+    const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    if (!fm) return false
+    return /^task_type:\s*['"]?verification['"]?\s*$/im.test(fm[1])
+      || /^verification_only:\s*true\s*$/im.test(fm[1])
+  } catch {
+    return false
+  }
+}
+
 export function validateTaskReviews(opts) {
   const { planContent, runtimeRoot, executeRunId, allowCannotVerify = true, changeDir = null, gitDir = null, ctx = null } = opts
 
@@ -463,6 +487,15 @@ export function validateTaskReviews(opts) {
       if (evidence.emptyDiff) {
         if (isTaskLowRisk(changeDir, taskId)) {
           warnings.push(`${taskId}: base..head 无代码变更（task 声明 low_risk: true，不阻断）`)
+        } else if (isTaskVerification(changeDir, taskId)) {
+          // 纯验证 task 零 diff 通道（坑 verification-task-zero-diff）：声明 task_type: verification
+          // 的「跑测试/部署验证/观测」型任务无代码 diff 是本质属性——不判伪造，但披露义务不豁免：
+          // requiredEvidence 为空 → error（声明不能替代证据）
+          if (Array.isArray(review.requiredEvidence) && review.requiredEvidence.length > 0) {
+            warnings.push(`${taskId}: base..head 无代码变更 — task 声明 task_type: verification（纯验证任务），零 diff 合法；requiredEvidence 已披露验证区间/结论出处`)
+          } else {
+            errors.push(`${taskId}: 纯验证 task（task_type: verification）零 diff 合法，但 review 缺 requiredEvidence（须披露验证区间/命令/结论出处）——声明不能替代披露`)
+          }
         } else {
           errors.push(`${taskId}: base..head（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}）无任何代码变更 — 评审了一个零改动的任务，review 疑似伪造`)
           continue
@@ -525,18 +558,21 @@ export function validateTaskReviews(opts) {
 
 // QUAL-01 收口：原为本地 execFileSync('git')（无 safe.directory、与 git-helper 口径分裂），
 // 现走统一入口；抛错/trim 语义不变，timeout 15000 保留（rev-parse/diff 大仓余量）
-function runGit(gitDir, args) {
-  return git(gitDir, args, { timeout: 15000 })
+function runGit(gitDir, args, opts = {}) {
+  return git(gitDir, args, { timeout: 15000, ...opts })
 }
 
 // porcelain 状态行 → 变更文件路径（对齐 shared.js:343 parsePorcelainPath：`XY path`、引号包裹、
 // rename `R old -> new` 取箭头后）。未 commit 的 working-tree 改动对账用。
+// ⚠️ 入参必须是【未 trim】的原始输出（git(..., {trim:false})）——porcelain 行首空格是状态码
+// 一部分，git() 默认 trim 会把 ' M feature.js' 削成 'M feature.js'，slice(3) 再咬掉路径首字符
+// （实测 'eature.js'）→ 未提交文件对账全错位（verifyReviewGitEvidence 相交比对误判「完全不相交」）。
 function parsePorcelainFiles(statusOut) {
   const files = []
   for (const line of String(statusOut).split('\n')) {
     if (line.trim() === '') continue
     let p = line.slice(3).trim()
-    if (p.length >= 2 && p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1).replace(/\\(.)/g, (_, c) => c)
+    if (p.length >= 2 && p.startsWith('"') && p.endsWith('"')) p = unquoteGitPath(p.slice(1, -1))
     const arrow = p.indexOf(' -> ')
     if (arrow !== -1) p = p.slice(arrow + 4)
     if (p) files.push(p.replace(/\\/g, '/'))
@@ -608,7 +644,11 @@ export function verifyReviewGitEvidence(review, gitDir, cache = null) {
       runGit(gitDir, ['rev-parse', '--verify', '--quiet', `${hash}^{commit}`])
       c.verified.add(vkey)
     } catch {
-      errors.push(`${field} "${hash}" 不是仓库中的真实 commit — review.json 疑似伪造`)
+      // 可执行指引（坑 review-head-real-commit-late，2026-08-22 实证：head 必须真实 commit 的
+      // 要求撞门才知道——报错直接给操作序列：worktree 改动先 commit，取 HEAD 作 head）
+      errors.push(`${field} "${hash}" 不是仓库中的真实 commit — review.json 疑似伪造。` +
+        `head/base 必须是 git rev-parse 可解析的 commit hash：worktree 内先 git add -A && git commit -m "<task>"，` +
+        `再取 git rev-parse HEAD 作 head（base 用 task 卡锡点或基线 commit）；不要填分支名/伪 hash/working-tree 描述`)
     }
   }
   if (errors.length > 0) {
@@ -639,7 +679,7 @@ export function verifyReviewGitEvidence(review, gitDir, cache = null) {
   try {
     let wtStatus = c.wtStatus.get(gitDir)
     if (wtStatus === undefined) {
-      wtStatus = runGit(gitDir, ['status', '--porcelain'])
+      wtStatus = runGit(gitDir, ['status', '--porcelain'], { trim: false })
       c.wtStatus.set(gitDir, wtStatus)
     }
     if (wtStatus && wtStatus.trim().length > 0) {
@@ -656,15 +696,25 @@ export function verifyReviewGitEvidence(review, gitDir, cache = null) {
 
   // changedFiles 交叉比对：完全不相交 = review 描述的改动与实际 diff 无关（diffFiles 已含 working-tree）
   if (!emptyDiff && Array.isArray(review.changedFiles) && review.changedFiles.length > 0) {
-    const normalize = (p) => String(p).replace(/^\.\//, '')
+    // 注记剥离（坑 changedfiles-annotation-suffix-mismatch，2026-08-22 实证：changedFiles 带
+    // 「src/a.js（新增）」类注记后缀被判完全不相交，agent 用正则修还贪婪吞了路径段两轮才对）。
+    // 结构化剥法：只剥「路径尾部」的注记形态——全角/半角括号注记、// 与 # 行内注释、空白后的
+    // 说明文字；注记本身不参与匹配（想写说明放 reviewerNotes/requiredEvidence）。
+    const normalize = (p) => String(p)
+      .replace(/^\.\//, '')
+      .replace(/[（(][^（()）]*[)）]\s*$/, '')   // 尾部（注记）/(note)——中段括号（路径段）不动
+      .replace(/\s+(\/\/|#).*$/, '')              // 空格后的 // 或 # 注释
+      .trim()
     const diffSet = new Set(diffFiles.map(normalize))
     const hasOverlap = review.changedFiles.some(f => {
       const nf = normalize(f)
+      if (!nf) return false
       // 兼容 review 写相对/部分路径：前后缀匹配即可
       return diffSet.has(nf) || diffFiles.some(d => d.endsWith(nf) || nf.endsWith(d))
     })
     if (!hasOverlap) {
-      errors.push(`changedFiles 与实际 git diff（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}，${diffFiles.length} 个文件）完全不相交 — review 内容与代码变更无关`)
+      errors.push(`changedFiles 与实际 git diff（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}，${diffFiles.length} 个文件）完全不相交 — review 内容与代码变更无关。` +
+        `检查：changedFiles 必须是纯文件路径（注记/说明写 reviewerNotes，不拼进路径数组）；路径拼写与 diff 对照`)
     }
   }
 
@@ -983,7 +1033,30 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
   }
 
   // base..head diff 文件集（worktree-aware；null=git 不可用，[]=无 commit diff）
-  const diffFiles = resolveVerifyChangedFiles(cwd, changeName)
+  let diffFiles = resolveVerifyChangedFiles(cwd, changeName)
+  // ⚠️ 并入 worktree 未提交改动（坑 draft-attribution-uncommitted-worktree，2026-08-21 实证）：
+  // 子代理默认不 commit（execute 复盘 a 同源事实），真实改动全在 worktree working-tree——只看
+  // base..HEAD commit diff 时归属恒空，9/9 草稿全成「无归属」靠主代理手写升级。与
+  // verifyReviewGitEvidence 的 working-tree 并入口径同源：status --porcelain 文件（排除
+  // .sillyspec/ 运行时产物）并入归属集，按 allowed_paths 正常路径归属；review.head 仍为 HEAD
+  // commit——evidence 校验对「commit diff 空 + working-tree 有改动」明示不判伪造，语义一致。
+  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'], { 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])]
+        console.log(`[sillyspec] 草稿归属并入 ${wtFiles.length} 个 worktree 未提交文件（子代理未 commit 的改动按 allowed_paths 归属）`)
+      }
+    }
+  } catch { /* working-tree 并入失败退回 commit diff 口径（fail-open，不阻断草稿） */ }
   // 单仓模式（无 ctx）：主仓无 diff 即无任何 task 可生成 → 提前返回（原逻辑零回归）。
   // 有 ctx：主仓无 diff 不阻断——跨仓 task 的 diff 在跨仓仓根独立取（per-task），主仓 task 自然跳过（空 changedFiles）。
   if (!ctx && (!diffFiles || diffFiles.length === 0)) {
@@ -1109,8 +1182,9 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
         specVerdict: 'cannot_verify',
         qualityVerdict: 'cannot_verify',
         requiredEvidence: ['auto-generated draft (no-attributed-diff): ' + taskId +
-          ' 的 allowed_paths 未命中本次 diff 任何文件（task 未实现 / 改动与他人同文件 / 路径不匹配）——' +
-          '需人工确认实际改动后升级 verdict，确属未实现则回 fail'],
+          ' 的 allowed_paths 未命中本次 diff 任何文件（task 未实现 / 改动与他人同文件 / 路径不匹配 / 纯验证任务）——' +
+          '需人工确认实际改动后升级 verdict，确属未实现则回 fail；若是纯验证任务（跑测试/部署验证/观测，无代码 diff 是本质属性），' +
+          'task 卡 frontmatter 声明 task_type: verification + review 披露验证区间即走合法零 diff 通道'],
         reviewerNotes: 'auto-generated draft from git diff ' + taskBase.slice(0, 8) + '..' + taskHead.slice(0, 8) +
           ';verdict=未评审（无归属 diff 兜底草稿，坑 task-review-draft-skip-leak）',
       }
@@ -1150,6 +1224,194 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
   return { generated, skipped, noAttribution: noAttributionCount, unattributed, executeRunId }
 }
 
+/**
+ * adoptTaskReviewMechanics —— 已存在 review.json 的 mechanics 字段一键重算代填（保 verdict）。
+ *
+ * 背景（2026-08-21 agent-手工产出审计项①）：review.json 里 schemaVersion/task/base/head/
+ * changedFiles(/repo) 全部可由 CLI 从 git + task 卡机械推导（generateTaskReviewDrafts 已证明），
+ * agent/子代理手算 hash、手抄 diff 清单是纯错误面——而 gate（verifyReviewGitEvidence）校验的
+ * 恰是这些字段。与草稿生成互补：草稿只补「缺失」，adopt 修「已存在但 mechanics 错/缺」——
+ * 保留人工语义字段（specVerdict/qualityVerdict/requiredEvidence/reviewerNotes），只重写 mechanics。
+ *
+ * verdict 保护策略（不猜 agent 本意）：
+ * - 合法 verdict（VALID_VERDICTS）原样保留；
+ * - 非法/缺失 verdict 降级 cannot_verify，reviewerNotes 追加标记，requiredEvidence 缺失补占位
+ *  （schema 要求 cannot_verify 必带非空 requiredEvidence）；
+ * - JSON 解析失败的 review 不救（无法可信保留任何字段），报出来留给 agent 修 JSON 后重跑。
+ *
+ * fail-open：与草稿生成同契约——缺数据返回统计与 reasons，不抛。
+ *
+ * @param {{ changeName: string, cwd: string, platformOpts?: object, ctx?: object|null }} opts
+ * @returns {Promise<{ adopted: number, unchanged: number, skipped: number, missing: number,
+ *                     downgraded: string[], reasons: string[], executeRunId?: string }>}
+ */
+export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts = {}, ctx = null }) {
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, specBase)
+  const tasksDir = join(specBase, 'changes', changeName, 'tasks')
+  const reasons = []
+
+  if (!changeName) {
+    return { adopted: 0, unchanged: 0, skipped: 0, missing: 0, downgraded: [], reasons: ['无 changeName'] }
+  }
+  if (!existsSync(tasksDir)) {
+    return { adopted: 0, unchanged: 0, skipped: 0, missing: 0, downgraded: [], reasons: ['无 tasks/ 目录'] }
+  }
+
+  // executeRunId：与草稿/gate 同源 marker。缺 marker 不新建 run——adopt 修的是当前 run 里
+  // 已存在的 review，marker 丢失说明无「当前 run」语义，无对象可修（gate 对 marker 缺失放行，
+  // 下游 Task Review Gate 兜底，这里同口径不造 run）。
+  const runIdFile = join(runtimeRoot, 'current-execute-run-id-' + changeName)
+  let executeRunId = ''
+  try {
+    if (existsSync(runIdFile)) {
+      const c = readFileSync(runIdFile, 'utf8').trim()
+      if (isValidExecuteRunId(c)) executeRunId = c
+    }
+  } catch {}
+  if (!executeRunId) {
+    return { adopted: 0, unchanged: 0, skipped: 0, missing: 0, downgraded: [], reasons: ['无 execute run marker——无当前 run，adopt 无对象'] }
+  }
+
+  // base/head + diff：与 generateTaskReviewDrafts 同源口径（meta 锡点 + worktree rev-parse +
+  // resolveVerifyChangedFiles），保证 adopt 产物与 gate 校验输入一致。
+  const diffFiles = resolveVerifyChangedFiles(cwd, changeName)
+  let base = null
+  let head = null
+  let reviewGitDir = cwd
+  try {
+    const wm = new WorktreeManager({ cwd })
+    const meta = wm.getMeta(changeName)
+    base = (meta && (meta.baselineCommit || meta.baseHash)) || null
+    if (meta && meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath)) {
+      reviewGitDir = meta.worktreePath
+    }
+  } catch {}
+  if (base) {
+    try {
+      head = runGit(reviewGitDir, ['rev-parse', 'HEAD'])
+    } catch {
+      head = null
+    }
+  }
+
+  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f)).sort()
+  let adopted = 0
+  let unchanged = 0
+  let skipped = 0
+  let missing = 0
+  const downgraded = []
+
+  for (const tf of taskFiles) {
+    const taskId = tf.replace(/\.md$/, '')
+    const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', taskId, 'review.json')
+    if (!existsSync(reviewPath)) {
+      missing++
+      continue
+    }
+
+    const existing = readReview(reviewPath)
+    if (existing.parseError) {
+      skipped++
+      reasons.push(`${taskId}: JSON 解析失败，adopt 不猜字段——先修 JSON 再重跑`)
+      continue
+    }
+    const prev = existing.review || {}
+
+    const content = readFileSync(join(tasksDir, tf), 'utf8')
+    const allowedPaths = parseAllowedPaths(content)
+    const taskRepo = normalizeRepoKey(parseRepo(content))
+    const crossEntry = (ctx && taskRepo !== DEFAULT_REPO_KEY) ? ctx.resolve(taskRepo) : null
+    let taskBase = base
+    let taskHead = head
+    let taskChangedFiles
+    let draftRepo
+
+    if (crossEntry) {
+      const baseCommit = parseBaseCommit(content)
+      const headCommit = parseHeadCommit(content)
+      if (!baseCommit || !headCommit) {
+        skipped++
+        reasons.push(`${taskId}: 跨仓 task 卡缺 base/head 锡点，无法 adopt`)
+        continue
+      }
+      taskBase = baseCommit
+      taskHead = headCommit
+      draftRepo = taskRepo
+      let crossDiffFiles = []
+      try {
+        const out = runGit(crossEntry.gitDir, ['diff', '--name-only', `${baseCommit}..${headCommit}`])
+        crossDiffFiles = out ? out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')) : []
+      } catch {
+        skipped++
+        reasons.push(`${taskId}: 跨仓 git diff 失败（${crossEntry.gitDir}）`)
+        continue
+      }
+      taskChangedFiles = allowedPaths.length > 0
+        ? crossDiffFiles.filter(f => allowedPaths.some(p => pathMatches(f, p)))
+        : crossDiffFiles
+    } else {
+      const mainDiff = Array.isArray(diffFiles) ? diffFiles : []
+      taskChangedFiles = allowedPaths.length > 0
+        ? mainDiff.filter(f => allowedPaths.some(p => pathMatches(f, p)))
+        : []
+    }
+
+    if (!crossEntry && (!taskBase || !taskHead)) {
+      skipped++
+      reasons.push(`${taskId}: 主仓缺 worktree meta base/head，无法 adopt`)
+      continue
+    }
+
+    const merged = { ...prev }
+    merged.schemaVersion = REVIEW_SCHEMA_VERSION
+    merged.task = taskId
+    merged.base = taskBase
+    merged.head = taskHead
+    merged.changedFiles = taskChangedFiles
+    if (draftRepo) merged.repo = draftRepo
+
+    let verdictTouched = false
+    for (const v of ['specVerdict', 'qualityVerdict']) {
+      if (!VALID_VERDICTS.includes(merged[v])) {
+        merged[v] = 'cannot_verify'
+        verdictTouched = true
+      }
+    }
+    if (verdictTouched) downgraded.push(taskId)
+    let evidenceFilled = false
+    if ((merged.specVerdict === 'cannot_verify' || merged.qualityVerdict === 'cannot_verify')
+      && (!Array.isArray(merged.requiredEvidence) || merged.requiredEvidence.length === 0)) {
+      merged.requiredEvidence = [`adopt 代填：原 review 缺 requiredEvidence（verdict=${merged.specVerdict}/${merged.qualityVerdict}），待人工复核补证据`]
+      evidenceFilled = true
+    }
+    if (verdictTouched) {
+      merged.reviewerNotes = String(merged.reviewerNotes || '') + (merged.reviewerNotes ? '; ' : '')
+        + 'adopt: 原 verdict 非法/缺失已降级 cannot_verify（不猜本意）'
+    }
+
+    const mechanicsChanged = prev.schemaVersion !== merged.schemaVersion
+      || prev.base !== merged.base
+      || prev.head !== merged.head
+      || JSON.stringify(prev.changedFiles ?? null) !== JSON.stringify(merged.changedFiles)
+      || prev.repo !== merged.repo
+
+    try {
+      if (mechanicsChanged || verdictTouched || evidenceFilled) {
+        writeFileSync(reviewPath, JSON.stringify(merged, null, 2) + '\n')
+        adopted++
+      } else {
+        unchanged++
+      }
+    } catch (e) {
+      skipped++
+      reasons.push(`${taskId}: 写回失败 ${e.message}`)
+    }
+  }
+
+  return { adopted, unchanged, skipped, missing, downgraded, reasons, executeRunId }
+}
+
 /**
  * 获取当前（或最新）execute run id
  * 从 runtime 目录下查找 execute-runs/ 子目录