sillyspec 3.22.9 → 3.23.1

package/src/sync.js

@@ -75,7 +75,9 @@ function parseSimpleYaml(content) {
   for (const line of content.split('\n')) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
-    if (!trimmed.startsWith(' ')) {
+    // 用原始 line（非 trimmed）判断缩进：trimmed 已去前导空格，startsWith(' ') 恒 false
+    // 会导致缩进子段（如 platform 下 url/token）被误判为 root 行、section 恒为空 {}
+    if (!line.startsWith(' ')) {
       const m = trimmed.match(/^(\S+)\s*:\s*(.*)$/);
       if (m) {
         const key = m[1];
@@ -413,14 +415,80 @@ export async function checkApproval(changeName, cwd) {
   return new SyncManager(cwd).checkApproval(changeName);
 }
 
+// TBD-hub-api: approve/reject 端点路径与请求体以 SillyHub 仓库实际 API 为准；
+// 对齐时只改本函数（_submitApproval），无需动 approve/reject 入口。
+/**
+ * 向平台提交审批决定（approve/reject 共用）。
+ *
+ * 显式用户/daemon 动作：网络/平台失败必须可见（decisions.md D-006@v1）——
+ * 与 best-effort 的 sync 不同，此处失败打 error 并置 process.exitCode = 1。
+ *
+ * @param {string} cwd - 工作目录
+ * @param {string} changeName - 变更名称
+ * @param {'approved'|'rejected'} decision - 审批决定
+ * @param {string|null} reason - rejected 时的原因（approved 时忽略）
+ * @returns {Promise<boolean>} 是否成功
+ */
+async function _submitApproval(cwd, changeName, decision, reason = null) {
+  const sm = new SyncManager(cwd);
+  const platform = sm._getPlatform();
+  if (!platform) {
+    console.error('❌ 未连接平台，请先 sillyspec platform connect');
+    process.exitCode = 1;
+    return false;
+  }
+
+  if (!changeName) {
+    console.error('❌ 审批需要指定变更名称 (changeName)');
+    process.exitCode = 1;
+    return false;
+  }
+
+  // TBD-hub-api: 端点路径/body 以 SillyHub 实际 API 为准，对齐时只改此处
+  const approvalUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/approval`;
+  const body = decision === 'rejected'
+    ? { decision: 'rejected', reason }
+    : { decision: 'approved' };
+
+  const result = await fetchJson(approvalUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${platform.token}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  // fetchJson 在非 2xx / 网络错 / 超时 / 非 JSON 时返回 null
+  if (result === null) {
+    console.error(`❌ 审批请求失败 (${changeName} → ${decision})，详情见上方 [sync] 警告`);
+    process.exitCode = 1;
+    return false;
+  }
+
+  // HTTP 成功后更新本地 approvals 表（HTTP 已成功是主要目标，落库失败只 warn 不阻断）
+  try {
+    const { ProgressManager } = await import('./progress.js');
+    const pm = new ProgressManager({ specDir: safePlatformSpecDir(cwd) });
+    await pm._updateApprovalStatus(cwd, changeName, decision, reason);
+  } catch (err) {
+    console.warn(`[sync] 更新本地审批状态失败 (${changeName}): ${err.message}`);
+  }
+
+  if (decision === 'approved') {
+    console.log(`✅ 已批准变更 ${changeName}`);
+  } else {
+    console.log(`✅ 已拒绝变更 ${changeName}${reason ? `（原因: ${reason}）` : ''}`);
+  }
+  return true;
+}
+
 export async function approve(changeName, cwd) {
-  // TODO: SillyHub 平台侧实现后启用
-  console.warn(`[sync] approve 尚未实现 (${changeName})`);
+  return _submitApproval(cwd, changeName, 'approved');
 }
 
 export async function reject(changeName, reason, cwd) {
-  // TODO: SillyHub 平台侧实现后启用
-  console.warn(`[sync] reject 尚未实现 (${changeName})`);
+  return _submitApproval(cwd, changeName, 'rejected', reason);
 }
 
 export async function status(cwd) {

package/src/task-review.js

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from 'fs'
 import { join, resolve } from 'path'
+import { execFileSync } from 'child_process'
 
 // ── review.json schema version ──
 export const REVIEW_SCHEMA_VERSION = 1
@@ -147,7 +148,7 @@ function isTaskLowRisk(changeDir, taskId) {
 }
 
 export function validateTaskReviews(opts) {
-  const { planContent, runtimeRoot, executeRunId, allowCannotVerify = true, changeDir = null } = opts
+  const { planContent, runtimeRoot, executeRunId, allowCannotVerify = true, changeDir = null, gitDir = null } = opts
 
   const taskIds = parseTaskIdsFromPlan(planContent)
 
@@ -178,7 +179,7 @@ export function validateTaskReviews(opts) {
         if (isTaskLowRisk(changeDir, taskId)) {
           warnings.push(`${taskId}: 缺少 review.json — task 声明 low_risk: true，已豁免评审（type-only/机械迁移）`)
         } else {
-          errors.push(`${taskId}: 缺少 review.json — task 未经过评审`)
+          errors.push(`${taskId}: 缺少 review.json — task 未经过评审（期望路径：${reviewPath}，execute run ID: ${executeRunId}）`)
         }
       }
       continue
@@ -201,6 +202,24 @@ export function validateTaskReviews(opts) {
       continue
     }
 
+    // ── git 真实性交叉校验：base/head 必须是真实 commit，diff 不能为空 ──
+    if (gitDir) {
+      const evidence = verifyReviewGitEvidence(review, gitDir)
+      for (const w of evidence.warnings) warnings.push(`${taskId}: ${w}`)
+      if (!evidence.ok) {
+        for (const err of evidence.errors) errors.push(`${taskId}: ${err}`)
+        continue
+      }
+      if (evidence.emptyDiff) {
+        if (isTaskLowRisk(changeDir, taskId)) {
+          warnings.push(`${taskId}: base..head 无代码变更（task 声明 low_risk: true，不阻断）`)
+        } else {
+          errors.push(`${taskId}: base..head（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}）无任何代码变更 — 评审了一个零改动的任务，review 疑似伪造`)
+          continue
+        }
+      }
+    }
+
     // 检查 cannot_verify
     if (review.specVerdict === 'cannot_verify' || review.qualityVerdict === 'cannot_verify') {
       if (!allowCannotVerify) {
@@ -252,6 +271,90 @@ export function validateTaskReviews(opts) {
   }
 }
 
+// ── Git 真实性交叉校验 ──
+
+function runGit(gitDir, args) {
+  return execFileSync('git', args, {
+    cwd: gitDir,
+    encoding: 'utf8',
+    timeout: 15000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim()
+}
+
+/**
+ * 校验 review.json 的 base/head 是否指向真实 git 提交，且 diff 非空。
+ *
+ * 历史漏洞：base/head 只做非空字符串检查，agent 可以填任意假 hash 批量伪造
+ * review.json 通过 Task Review Gate。此函数用 git 做客观交叉校验：
+ *   1. base/head 必须是仓库中可解析的真实 commit
+ *   2. base..head 的 diff 不能为空（评审一个零改动的"任务"无意义）
+ *   3. review.changedFiles（如提供）必须与实际 diff 文件有交集
+ *
+ * git 环境不可用（非 git 仓库 / git 缺失）时返回 unavailable，由调用方降级为
+ * warning——不因环境问题误杀，但记录在输出中。
+ *
+ * @param {object} review - 已通过 schema 校验的 review 对象
+ * @param {string} gitDir - 执行 git 命令的目录（worktree 优先，回退主仓库）
+ * @returns {{ ok: boolean, emptyDiff: boolean, errors: string[], warnings: string[], unavailable: boolean }}
+ */
+export function verifyReviewGitEvidence(review, gitDir) {
+  const errors = []
+  const warnings = []
+
+  // git 环境探测：失败即 unavailable，交由调用方降级
+  try {
+    runGit(gitDir, ['rev-parse', '--git-dir'])
+  } catch (e) {
+    return {
+      ok: true,
+      emptyDiff: false,
+      errors: [],
+      warnings: [`git 环境不可用（${gitDir}），跳过 review 真实性交叉校验: ${e.message?.split('\n')[0] || e.message}`],
+      unavailable: true,
+    }
+  }
+
+  for (const field of ['base', 'head']) {
+    const hash = review[field]
+    try {
+      runGit(gitDir, ['rev-parse', '--verify', '--quiet', `${hash}^{commit}`])
+    } catch {
+      errors.push(`${field} "${hash}" 不是仓库中的真实 commit — review.json 疑似伪造`)
+    }
+  }
+  if (errors.length > 0) {
+    return { ok: false, emptyDiff: false, errors, warnings, unavailable: false }
+  }
+
+  let diffFiles = []
+  try {
+    const out = runGit(gitDir, ['diff', '--name-only', `${review.base}..${review.head}`])
+    diffFiles = out ? out.split('\n').filter(Boolean) : []
+  } catch (e) {
+    warnings.push(`git diff ${review.base}..${review.head} 执行失败，跳过 diff 校验: ${e.message?.split('\n')[0] || e.message}`)
+    return { ok: true, emptyDiff: false, errors, warnings, unavailable: false }
+  }
+
+  const emptyDiff = diffFiles.length === 0
+
+  // changedFiles 交叉比对：完全不相交 = review 描述的改动与实际 diff 无关
+  if (!emptyDiff && Array.isArray(review.changedFiles) && review.changedFiles.length > 0) {
+    const normalize = (p) => String(p).replace(/^\.\//, '')
+    const diffSet = new Set(diffFiles.map(normalize))
+    const hasOverlap = review.changedFiles.some(f => {
+      const nf = normalize(f)
+      // 兼容 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 内容与代码变更无关`)
+    }
+  }
+
+  return { ok: errors.length === 0, emptyDiff, errors, warnings, unavailable: false }
+}
+
 /**
  * 将 cannot_verify 的 requiredEvidence 写入 change 目录
  * 供 verify 阶段消费
@@ -344,7 +447,7 @@ export function ensureTaskReviewDir(runtimeRoot, executeRunId, taskId) {
  * 打印校验结果
  * @param {{ ok: boolean, errors: string[], warnings: string[], requiredEvidence: Array }} result
  */
-export function printReviewResult(result) {
+export function printReviewResult(result, context = {}) {
   if (result.ok && result.warnings.length === 0) {
     console.log('\n✅ Task Review Gate — 所有任务评审通过')
     return
@@ -355,7 +458,10 @@ export function printReviewResult(result) {
     for (const err of result.errors) {
       console.error(`   - ${err}`)
     }
-    console.error('\n   提示：为缺失/失败的任务补充 review.json，然后重新 --done')
+    const hint = context.runtimeRoot && context.executeRunId
+      ? `期望路径：${context.runtimeRoot}/execute-runs/${context.executeRunId}/tasks/<task-XX>/review.json`
+      : '为缺失/失败的任务补充 review.json'
+    console.error(`\n   提示：${hint}，然后重新 --done`)
   }
 
   if (result.warnings.length > 0) {

package/src/verify-postcheck.js

@@ -0,0 +1,433 @@
+/**
+ * Verify Postcheck — CLI 客观测试执行与自报告对账
+ *
+ * verify 阶段历史上完全依赖 agent 自报告（跑没跑测试、结果如何全写在
+ * verify-result.md 里），可被文案绕过。此模块让 CLI 在 verify 完成时
+ * 亲自执行 local.yaml 配置的测试命令，与 verify-result.md 的结论对账：
+ * 自报告 PASS 但实测失败 → 阻断 verify 完成。
+ *
+ * 未配置 commands.test（或标记 unavailable）时降级为 warning 不阻断，
+ * 兼容无测试项目。
+ *
+ * test_strategy 支持（D-002@v1）：
+ * - full（默认）：整跑 commands.test（brownfield 行为不变）
+ * - module：按 local.yaml modules 映射，仅跑 git diff 命中的模块子集
+ *           测试，避免 monorepo 全量测试超 gate timeout。
+ */
+
+import { execSync } from 'child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+// 测试命令最长执行时间；超时视为失败（防止 CLI 被挂起的测试卡死）
+const TEST_TIMEOUT_MS = Number(process.env.SILLYSPEC_TEST_TIMEOUT_MS) || 10 * 60 * 1000
+const OUTPUT_TAIL_CHARS = 4000
+
+/**
+ * 从 local.yaml 文本提取 commands.test。
+ * 轻量正则（与 worktree-deps/scan-postcheck 同风格，不引 yaml 依赖）：
+ * 支持带引号与不带引号两种写法；'unavailable' 视为未配置。
+ */
+export function extractTestCommand(yamlText) {
+  if (!yamlText) return null
+  const doubleQuoted = yamlText.match(/^\s*test:\s*"([^"]+)"\s*(?:#.*)?$/m)
+  const singleQuoted = yamlText.match(/^\s*test:\s*'([^']+)'\s*(?:#.*)?$/m)
+  const quoted = doubleQuoted || singleQuoted
+  if (quoted && quoted[1]) {
+    return quoted[1].toLowerCase() === 'unavailable' ? null : quoted[1].trim()
+  }
+  const bare = yamlText.match(/^\s*test:\s*([^\n#"']+?)\s*(?:#.*)?$/m)
+  if (bare && bare[1]) {
+    const cmd = bare[1].trim()
+    return cmd.toLowerCase() === 'unavailable' ? null : cmd
+  }
+  return null
+}
+
+/**
+ * 从 local.yaml 文本提取顶层 test_strategy。
+ * 轻量正则（与 extractTestCommand 同风格，不引 yaml 依赖）。
+ *
+ * @param {string} yamlText
+ * @returns {'full'|'module'|null} - 解析到的策略；缺省/无法解析返回 null（调用方按 full 处理）
+ */
+export function extractTestStrategy(yamlText) {
+  if (!yamlText) return null
+  const m = yamlText.match(/^\s*test_strategy:\s*([A-Za-z_]+)\s*(?:#.*)?$/m)
+  if (!m || !m[1]) return null
+  const v = m[1].trim().toLowerCase()
+  if (v === 'module') return 'module'
+  if (v === 'full') return 'full'
+  return null
+}
+
+/**
+ * 从 local.yaml 文本解析 modules 映射块。
+ * 设计约定（见 change 2026-07-10-tooling-followups design.md #2 方案 A）：
+ *
+ *   modules:
+ *     backend: { path: "backend/", test: "cd backend && uv run pytest" }
+ *     frontend: { path: "frontend/", test: "cd frontend && pnpm test" }
+ *
+ * 每个模块一行 inline flow mapping，含 path 与 test 两个键。
+ * 轻量行扫描（与 modules.js parseModuleMapSimple 同风格，不引 yaml 依赖）。
+ *
+ * @param {string} yamlText
+ * @returns {Record<string, {path:string, test:string}>|null}
+ *   - 找不到 modules 块 → null（调用方 fallback commands.test）
+ *   - 找到块但无有效条目 → null
+ */
+export function extractModules(yamlText) {
+  if (!yamlText) return null
+  const lines = yamlText.split('\n')
+
+  // 定位 modules: 起始行（必须是顶层 key，行首无缩进或仅注释后顶层）
+  let startIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^modules:\s*(?:#.*)?$/)
+    if (m) { startIdx = i; break }
+  }
+  if (startIdx === -1) return null
+
+  const modules = {}
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i]
+    // 子条目：以 2 空格缩进 + key + ':' 开头
+    const entry = line.match(/^  ([A-Za-z0-9_.\-]+):\s*(.*)$/)
+    if (!entry) {
+      // 遇到新的顶层 key（行首非空格且非注释）→ modules 块结束
+      if (line.length > 0 && !line.startsWith(' ') && !line.startsWith('#') && line.trim() !== '') break
+      continue
+    }
+    const name = entry[1]
+    const rest = entry[2].trim()
+    if (rest === '' || rest.startsWith('#')) continue // 子块展开式（本实现只支持 inline flow）
+    // 解析 inline flow mapping: { path: "...", test: "..." }
+    const pathVal = parseFlowValue(rest, 'path')
+    const testVal = parseFlowValue(rest, 'test')
+    if (pathVal && testVal) {
+      modules[name] = { path: pathVal, test: testVal }
+    }
+  }
+
+  return Object.keys(modules).length > 0 ? modules : null
+}
+
+/**
+ * 从 inline flow mapping 文本（如 `{ path: "backend/", test: "cd ..." }`）
+ * 提取指定键的值。支持双引号/单引号/bare 值。
+ */
+function parseFlowValue(flowText, key) {
+  // 键可能带引号也可能不带：path: "x" 或 "path": "x"
+  const re = new RegExp(String.raw`(?:^|[{,]\s*)"?${key}"?\s*:\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|(?:[^,}]+?))\s*(?=[,}]|$)`)
+  const m = flowText.match(re)
+  if (!m) return null
+  let v = m[1].trim()
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    v = v.slice(1, -1)
+  }
+  return v.length > 0 ? v : null
+}
+
+/**
+ * 根据变更文件列表 + modules 映射，算出被命中的模块（去重保序）。
+ * 文件路径以 module.path 为前缀（含子目录）即视为命中。
+ *
+ * @param {string[]} changedFiles - git diff 产出的相对路径列表
+ * @param {Record<string, {path:string, test:string}>} modules - extractModules 解析结果
+ * @returns {Array<{name:string, path:string, test:string}>} - 命中的模块（按 modules 声明顺序去重）
+ */
+export function pickHitModules(changedFiles, modules) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return []
+  if (!modules || typeof modules !== 'object') return []
+
+  const files = changedFiles.map(f => String(f).replace(/\\/g, '/'))
+  const hits = []
+  for (const [name, mod] of Object.entries(modules)) {
+    if (!mod || !mod.path) continue
+    const modPath = String(mod.path).replace(/\\/g, '/')
+    const prefix = modPath.endsWith('/') ? modPath : modPath + '/'
+    // path 本身被改 或 path/ 下任意文件被改
+    const hit = files.some(f => f === modPath || f.startsWith(prefix))
+    if (hit) hits.push({ name, path: modPath, test: mod.test })
+  }
+  return hits
+}
+
+/**
+ * 聚合多个模块测试结果为单一 status。
+ * - 全 passed → 'passed'
+ * - 任一 failed → 'failed'
+ * - 空 → null（调用方按 fallback 处理）
+ *
+ * @param {Array<{status:'passed'|'failed'}>} results
+ * @returns {'passed'|'failed'|null}
+ */
+export function aggregateStatus(results) {
+  if (!Array.isArray(results) || results.length === 0) return null
+  if (results.every(r => r && r.status === 'passed')) return 'passed'
+  return 'failed'
+}
+
+/**
+ * 跑单个模块的 test 命令（串行调用方逐个调用）。
+ * @returns {{name, status:'passed'|'failed', command, exitCode, durationMs, outputTail, reason}}
+ */
+function runOneModule(name, testCommand, cwd) {
+  const startedAt = Date.now()
+  let exitCode = 0
+  let output = ''
+  let reason = null
+  try {
+    output = execSync(testCommand, {
+      cwd,
+      encoding: 'utf8',
+      timeout: TEST_TIMEOUT_MS,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  } catch (e) {
+    exitCode = typeof e.status === 'number' ? e.status : 1
+    output = [e.stdout, e.stderr].filter(Boolean).join('\n') || e.message
+    reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= TEST_TIMEOUT_MS
+      ? `模块 ${name} 测试超时（>${TEST_TIMEOUT_MS / 1000}s）`
+      : `模块 ${name} 测试退出码 ${exitCode}`
+  }
+  const durationMs = Date.now() - startedAt
+  const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
+  return {
+    name,
+    status: exitCode === 0 ? 'passed' : 'failed',
+    command: testCommand,
+    exitCode,
+    durationMs,
+    outputTail,
+    reason,
+  }
+}
+
+/**
+ * 取 git 变更文件列表（worktree unstaged + staged，相对仓库根）。
+ * 务实策略：先取 unstaged working tree 改动（`git diff --name-only HEAD`），
+ * 它同时覆盖已暂存与未暂存改动（相对 HEAD），最适合 worktree 内尚未 commit 的场景。
+ * git 不可用 / 非仓库 → 返回 null（调用方 fallback）。
+ */
+function gitChangedFiles(cwd) {
+  try {
+    const out = execSync('git diff --name-only HEAD', {
+      cwd,
+      encoding: 'utf8',
+      timeout: 30 * 1000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    return out.split('\n').map(l => l.trim()).filter(Boolean)
+  } catch {
+    // HEAD 不存在（空仓库）或 git 不可用 → 尝试纯 unstaged
+    try {
+      const out = execSync('git diff --name-only', {
+        cwd,
+        encoding: 'utf8',
+        timeout: 30 * 1000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      return out.split('\n').map(l => l.trim()).filter(Boolean)
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * 执行 verify 实测：读取 local.yaml 配置，按 test_strategy 决定全量或模块子集。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 项目根目录（测试执行目录）
+ * @param {string} opts.specBase - .sillyspec（或平台 specRoot）目录
+ * @param {string|null} [opts.changeName]
+ * @returns {{
+ *   status: 'passed'|'failed'|'skipped',
+ *   command: string|null,
+ *   exitCode: number|null,
+ *   durationMs: number|null,
+ *   outputTail: string|null,
+ *   reason: string|null,
+ *   resultPath: string|null,
+ * }}
+ */
+export function runVerifyTestCheck({ cwd, specBase, changeName = null }) {
+  const localYamlPath = join(specBase, 'local.yaml')
+  const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
+
+  // —— 模块子集路径（test_strategy: module）——
+  const strategy = extractTestStrategy(yamlText)
+  if (strategy === 'module') {
+    const modules = extractModules(yamlText)
+    if (modules) {
+      const changedFiles = gitChangedFiles(cwd)
+      const hits = changedFiles ? pickHitModules(changedFiles, modules) : []
+      if (hits.length > 0) {
+        return runModuleSubset({ cwd, specBase, changeName, hits })
+      }
+      // 有 modules 配置但无命中 / git 不可用 → fallback commands.test（D-002@v1 向后兼容）
+    }
+    // test_strategy:module 但无 modules 配置 → fallback commands.test（brownfield 友好）
+  }
+
+  // —— 全量路径（默认 full / fallback）——
+  return runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName })
+}
+
+/**
+ * 全量跑 commands.test（现有逻辑，brownfield 行为不变）。
+ */
+function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName }) {
+  const command = extractTestCommand(yamlText)
+
+  if (!command) {
+    return {
+      status: 'skipped',
+      command: null,
+      exitCode: null,
+      durationMs: null,
+      outputTail: null,
+      reason: yamlText
+        ? 'local.yaml 未配置 commands.test（或标记 unavailable）'
+        : `local.yaml 不存在（${localYamlPath}）`,
+      resultPath: null,
+    }
+  }
+
+  const startedAt = Date.now()
+  let exitCode = 0
+  let output = ''
+  let reason = null
+  try {
+    output = execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      timeout: TEST_TIMEOUT_MS,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  } catch (e) {
+    exitCode = typeof e.status === 'number' ? e.status : 1
+    output = [e.stdout, e.stderr].filter(Boolean).join('\n') || e.message
+    reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= TEST_TIMEOUT_MS
+      ? `测试命令超时（>${TEST_TIMEOUT_MS / 1000}s）`
+      : `测试命令退出码 ${exitCode}`
+  }
+  const durationMs = Date.now() - startedAt
+  const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
+
+  const result = {
+    status: exitCode === 0 ? 'passed' : 'failed',
+    command,
+    exitCode,
+    durationMs,
+    outputTail,
+    reason,
+    resultPath: null,
+  }
+
+  writeRunResult({ specBase, changeName, result })
+  return result
+}
+
+/**
+ * 串行跑命中的模块子集，聚合结果。
+ * 返回 shape 与 runFullCommand 一致（status/command/exitCode/durationMs/outputTail/reason/resultPath）。
+ */
+function runModuleSubset({ cwd, specBase, changeName, hits }) {
+  const subsetStartedAt = Date.now()
+  const perModule = hits.map(h => runOneModule(h.name, h.test, cwd))
+  const status = aggregateStatus(perModule)
+
+  const command = `module[${hits.map(h => h.name).join(',')}]`
+  const exitCode = status === 'passed' ? 0 : 1
+  const durationMs = Date.now() - subsetStartedAt
+
+  // 合并各模块输出尾部（标注模块名）
+  const outputTail = perModule
+    .map(r => `── module ${r.name} (${r.status}) ──\n${r.outputTail || ''}`)
+    .join('\n')
+  const reason = status === 'passed'
+    ? null
+    : `模块子集测试失败：${perModule.filter(r => r.status === 'failed').map(r => r.name).join(', ')}`
+
+  const result = {
+    status,
+    command,
+    exitCode,
+    durationMs,
+    outputTail: outputTail.length > OUTPUT_TAIL_CHARS ? '…' + outputTail.slice(-OUTPUT_TAIL_CHARS) : outputTail,
+    reason,
+    resultPath: null,
+  }
+
+  writeRunResult({
+    specBase,
+    changeName,
+    result,
+    extra: {
+      modules: perModule.map(r => ({
+        name: r.name,
+        command: r.command,
+        exit_code: r.exitCode,
+        status: r.status,
+        duration_ms: r.durationMs,
+        output_tail: r.outputTail,
+        reason: r.reason,
+      })),
+    },
+  })
+  return result
+}
+
+/**
+ * 结果落盘到 .runtime/verify-runs/<ts>/test-result.json（供追溯与 SillyHub 消费）。
+ * 多模块时 extra.modules 描述各模块明细。
+ */
+function writeRunResult({ specBase, changeName, result, extra = {} }) {
+  try {
+    const ts = new Date().toISOString().slice(0, 19).replace(/[-T:]/g, '')
+    const runDir = join(specBase, '.runtime', 'verify-runs', ts)
+    mkdirSync(runDir, { recursive: true })
+    const resultPath = join(runDir, 'test-result.json')
+    writeFileSync(resultPath, JSON.stringify({
+      change: changeName,
+      command: result.command,
+      exit_code: result.exitCode,
+      status: result.status,
+      duration_ms: result.durationMs,
+      output_tail: result.outputTail,
+      reason: result.reason,
+      ran_at: new Date().toISOString(),
+      ...extra,
+    }, null, 2) + '\n')
+    result.resultPath = resultPath
+  } catch (e) {
+    console.warn(`⚠️  verify 实测结果落盘失败: ${e.message}`)
+  }
+}
+
+/** 打印实测结果（人类/agent 可读） */
+export function printVerifyTestCheck(result) {
+  if (result.status === 'skipped') {
+    console.warn(`\n⚠️  Verify 实测跳过：${result.reason}`)
+    console.warn('   建议在 local.yaml 的 commands.test 配置真实测试命令，让 CLI 可客观对账。')
+    return
+  }
+  if (result.status === 'passed') {
+    console.log(`\n✅ Verify 实测通过：\`${result.command}\` 退出码 0（${(result.durationMs / 1000).toFixed(1)}s）`)
+  } else {
+    console.error(`\n❌ Verify 实测失败：\`${result.command}\` — ${result.reason}`)
+    if (result.outputTail) {
+      const tail = result.outputTail.split('\n').slice(-20).join('\n')
+      console.error('   输出（末尾）：')
+      for (const line of tail.split('\n')) console.error(`   | ${line}`)
+    }
+  }
+  if (result.resultPath) {
+    console.log(`📄 实测结果已写入: ${result.resultPath}`)
+  }
+}