sillyspec 3.26.15 → 3.27.2

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
@@ -539,7 +572,7 @@ function parsePorcelainFiles(statusOut) {
   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, '/'))
@@ -611,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) {
@@ -659,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 对照`)
     }
   }
 
@@ -1135,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）',
       }

package/src/taskcard.js

@@ -14,7 +14,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { git } from './git-helper.js'
 import { assertSafeChangeName, resolveSpecDir } from './run/shared.js'
-import { parseTaskNames } from './stages/plan.js'
+import { parseTaskNames, readTaskRegistryContent } from './stages/plan.js'
+import { parseTaskRegistry } from './stages/execute.js'
 
 /**
  * 任务号归一：接受 task-01 / task-1 / 01 / 1，统一为 task-NN（两位补零，与任务卡文件名一致）。
@@ -52,21 +53,44 @@ function yamlScalar(v) {
  * 字符串只含 \n：writeFileSync 直写不经任何行尾转换，Windows 下天然 LF 安全。
  * title/title_zh/author 经 yamlScalar 转义（自由文本防 YAML 指示符炸解析）。
  *
- * @param {{ taskId: string, title: string, titleZh: string, author: string, now: string }} p
+ * @param {{ taskId: string, title: string, titleZh: string, author: string, now: string,
+ *           dependsOn?: string[], sets?: Record<string,string> }} p
+ *   dependsOn：tasks.md 行内注解反填（坑 taskcard-design-field-conflicts，2026-08-21 实证）——
+ *     "(depends_on: task-01,02)" 注解由 CLI 解析进 frontmatter，省主代理逐卡裁决
+ *   sets：--set key=value 覆盖（yamlScalar 转义；仅覆盖已存在的标量键，防注入任意结构）
  * @returns {string}
  */
-export function buildTaskcardSkeleton({ taskId, title, titleZh, author, now }) {
+export function buildTaskcardSkeleton({ taskId, title, titleZh, author, now, dependsOn = [], sets = {} }) {
+  const fm = {
+    id: taskId,
+    title: yamlScalar(title),
+    title_zh: yamlScalar(titleZh),
+    author: yamlScalar(author),
+    created_at: now,
+    priority: 'P0',
+    depends_on: (Array.isArray(dependsOn) && dependsOn.length > 0)
+      ? `[${dependsOn.map(d => `'${d}'`).join(', ')}]`
+      : '[]',
+    blocks: '[]',
+    requirement_ids: '[FR-XX]',
+    decision_ids: '[D-XXX@vN]',
+  }
+  // --set 覆盖（白名单键 + yamlScalar 转义值；depends_on 数组形态单独拼不进标量 map，跳过）
+  const SETTABLE_KEYS = new Set(['id', 'title', 'title_zh', 'author', 'priority', 'created_at', 'requirement_ids', 'decision_ids', 'blocks', 'goal'])
+  for (const [k, v] of Object.entries(sets || {})) {
+    if (SETTABLE_KEYS.has(k)) fm[k] = yamlScalar(v)
+  }
   return `---
-id: ${taskId}
-title: ${yamlScalar(title)}
-title_zh: ${yamlScalar(titleZh)}
-author: ${yamlScalar(author)}
-created_at: ${now}
-priority: P0
-depends_on: []
-blocks: []
-requirement_ids: [FR-XX]
-decision_ids: [D-XXX@vN]
+id: ${fm.id}
+title: ${fm.title}
+title_zh: ${fm.title_zh}
+author: ${fm.author}
+created_at: ${fm.created_at}
+priority: ${fm.priority}
+depends_on: ${fm.depends_on}
+blocks: ${fm.blocks}
+requirement_ids: ${fm.requirement_ids}
+decision_ids: ${fm.decision_ids}
 allowed_paths:
   - src/example/file.ts
 goal: >
@@ -105,7 +129,7 @@ constraints:
  * @returns {{ created: string[], skipped: string[], tasksDir: string }}
  */
 export function cmdTaskcard(changeName, opts = {}) {
-  const { cwd, specDir = null, taskIds, title = null, titleZh = null, force = false } = opts
+  const { cwd, specDir = null, taskIds, title = null, titleZh = null, force = false, sets = {} } = opts
   assertSafeChangeName(changeName, '变更名')
 
   const changeDir = join(resolveSpecDir(cwd, { specDir }), 'changes', changeName)
@@ -114,25 +138,27 @@ export function cmdTaskcard(changeName, opts = {}) {
   }
 
   // 任务注册表 tasks.md（2026-08-20-task-truth-unify 唯一真相；CRLF 归一后解析，
-  // --all 时强依赖）。tasks.md 缺失回退 plan.md（旧归档变更兼容读侧）
-  let planTasks = []
+  // --all 时强依赖）。tasks.md 缺失回退 plan.md（旧归档变更兼容读侧）。
+  // parseTaskRegistry（坑 taskcard-design-field-conflicts，2026-08-21）：除编号/标题外还带出
+  // 行内注解（[model:xxx] / (depends_on: task-01,02)）——depends_on 直接反填进骨架 frontmatter。
+  let registry = []
   const tasksMdPath = join(changeDir, 'tasks.md')
   const planPath = join(changeDir, 'plan.md')
   const registryPath = existsSync(tasksMdPath) ? tasksMdPath : planPath
   if (existsSync(registryPath)) {
     const registryContent = readFileSync(registryPath, 'utf8').replace(/\r\n/g, '\n')
-    planTasks = parseTaskNames(registryContent)
+    registry = parseTaskRegistry(registryContent)
   }
 
   let ids
   if (taskIds === 'all') {
-    if (planTasks.length === 0) {
+    if (registry.length === 0) {
       throw new Error(
         `--all 需要 tasks.md 中存在 checkbox 任务行（格式 "- [ ] task-XX: 任务名"）` +
         (existsSync(registryPath) ? '，当前任务清单未解析到任何任务行' : '，且变更目录下未找到 tasks.md/plan.md')
       )
     }
-    ids = planTasks.map(t => `task-${t.num}`)
+    ids = registry.map(t => t.id)
   } else if (Array.isArray(taskIds) && taskIds.length > 0) {
     ids = taskIds
   } else {
@@ -161,9 +187,9 @@ export function cmdTaskcard(changeName, opts = {}) {
   const created = []
   const skipped = []
   for (const id of ids) {
-    const planMatch = planTasks.find(t => `task-${t.num}` === id)
-    const finalTitle = title || (planMatch ? planMatch.name : null) || `${id} fill-english-title`
-    const finalTitleZh = titleZh || (planMatch ? planMatch.name : null) || finalTitle
+    const reg = registry.find(t => t.id === id)
+    const finalTitle = title || (reg ? reg.name : null) || `${id} fill-english-title`
+    const finalTitleZh = titleZh || (reg ? reg.name : null) || finalTitle
     const filePath = join(tasksDir, `${id}.md`)
     if (existsSync(filePath) && !force) {
       skipped.push(filePath)
@@ -171,6 +197,10 @@ export function cmdTaskcard(changeName, opts = {}) {
     }
     writeFileSync(filePath, buildTaskcardSkeleton({
       taskId: id, title: finalTitle, titleZh: finalTitleZh, author, now,
+      // depends_on 从 tasks.md 行内注解反填（坑 taskcard-design-field-conflicts）：注册表
+      // 注解与 plan/design 的依赖声明同源，骨架直接带上省主代理逐卡转录
+      dependsOn: reg ? reg.dependsOn : [],
+      sets,
     }), 'utf8')
     created.push(filePath)
   }

package/src/verify-postcheck.js

@@ -60,6 +60,104 @@ export function extractTestCommand(yamlText) {
   return null
 }
 
+/**
+ * 从 local.yaml 文本提取 commands.lint（2026-08-21 审查 CLI-1：lint 对账）。
+ * 与 extractTestCommand 同风格同容错（带引号/不带引号/unavailable）。
+ * 模块内私有（runVerifyLintCheck 消费；extractTestCommand 系 export 供 test）。
+ */
+function extractLintCommand(yamlText) {
+  if (!yamlText) return null
+  const doubleQuoted = yamlText.match(/^\s*lint:\s*"([^"]+)"\s*(?:#.*)?$/m)
+  const singleQuoted = yamlText.match(/^\s*lint:\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*lint:\s*([^\n#"']+?)\s*(?:#.*)?$/m)
+  if (bare && bare[1]) {
+    const cmd = bare[1].trim()
+    return cmd.toLowerCase() === 'unavailable' ? null : cmd
+  }
+  return null
+}
+
+/**
+ * verify --done 实测跑 local.yaml commands.lint（2026-08-21 审查 CLI-1）。
+ * 此前 lint 全靠 agent 自跑自报（"我跑过 lint 了"纯口头），与 test 侧的对账不对称——
+ * agent 偷懒漏跑时格式债被推迟到用户 commit 才被 pre-commit hook 炸出。
+ * advisory 起步：失败只打印不阻断（test 门已 fail-closed，lint 门观察期后再升级）。
+ * 信任边界与 runVerifyTestCheck 一致：命令只来源于主仓 .sillyspec/local.yaml。
+ */
+export function runVerifyLintCheck({ cwd, specBase }) {
+  const localYamlPath = join(specBase, 'local.yaml')
+  const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
+  const command = extractLintCommand(yamlText)
+
+  if (!command) {
+    return {
+      status: 'skipped',
+      command: null,
+      exitCode: null,
+      durationMs: null,
+      outputTail: null,
+      reason: yamlText
+        ? 'local.yaml 未配置 commands.lint（或标记 unavailable）'
+        : `local.yaml 不存在（${localYamlPath}）`,
+    }
+  }
+
+  const LINT_TIMEOUT_MS = Number(process.env.SILLYSPEC_LINT_TIMEOUT_MS) || 3 * 60 * 1000
+  const startedAt = Date.now()
+  let exitCode = 0
+  let output = ''
+  let reason = null
+  try {
+    output = execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      timeout: LINT_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 >= LINT_TIMEOUT_MS
+      ? `lint 命令超时（>${LINT_TIMEOUT_MS / 1000}s）`
+      : `lint 命令退出码 ${exitCode}`
+  }
+  const durationMs = Date.now() - startedAt
+  const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
+
+  return {
+    status: exitCode === 0 ? 'passed' : 'failed',
+    command,
+    exitCode,
+    durationMs,
+    outputTail,
+    reason: exitCode === 0 ? null : reason,
+  }
+}
+
+/** 打印 lint 实测结果（advisory：失败不阻断，只把口头汇报对上账） */
+export function printVerifyLintCheck(result) {
+  if (result.status === 'skipped') {
+    console.warn(`\n⚠️  Verify lint 实测跳过：${result.reason}`)
+    return
+  }
+  if (result.status === 'passed') {
+    console.log(`\n✅ Verify lint 实测通过：\`${result.command}\` 退出码 0（${(result.durationMs / 1000).toFixed(1)}s）`)
+    return
+  }
+  console.error(`\n⚠️  Verify lint 实测失败（advisory，不阻断本次完成）：\`${result.command}\` — ${result.reason}`)
+  console.error('   agent 的 lint 自报告与实测不符时以实测为准；请修复后重跑，避免格式债推迟到 commit 被 pre-commit hook 拦截。')
+  if (result.outputTail) {
+    const tail = result.outputTail.split('\n').slice(-15).join('\n')
+    console.error('   输出（末尾）：')
+    for (const line of tail.split('\n')) console.error(`   | ${line}`)
+  }
+}
+
 /**
  * 从 local.yaml 文本提取顶层 test_strategy。
  * 轻量正则（与 extractTestCommand 同风格，不引 yaml 依赖）。
@@ -207,15 +305,30 @@ export function pickHitModules(changedFiles, modules) {
 
   const files = changedFiles.map(f => String(f).replace(/\\/g, '/'))
   const hits = []
+  const looseHits = []
   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 })
+    if (hit) { hits.push({ name, path: modPath, test: mod.test }); continue }
+    // 宽松段匹配 fallback（坑 module-path-layout-mismatch，2026-08-22 实证：pnpm monorepo
+    // 常见 packages/frontend 布局 vs modules 配 frontend/ 前缀——严格前缀 0 命中时按
+    // 「路径段等于模块首段」兜底（packages/frontend/src/x → 命中 frontend），多测不漏测。
+    // 首段去斜杠后比对，防 frontend-guide 之类前缀误蹭）
+    const firstSeg = prefix.split('/')[0]
+    if (firstSeg && files.some(f => ('/' + f + '/').includes('/' + firstSeg + '/'))) {
+      looseHits.push({ name, path: modPath, test: mod.test, looseMatch: true })
+    }
   }
-  return hits
+  // 严格命中优先；全部严格 0 命中才用宽松兜底（并 warn 可见——宽松规则可能多命中）
+  if (hits.length > 0) return hits
+  if (looseHits.length > 0) {
+    console.warn(`⚠️ 模块命中用宽松段匹配（modules path 前缀与 diff 布局不一致，如 packages/<name> vs <name>/）：命中 ${looseHits.map(h => h.name).join(', ')}——建议 local.yaml modules 的 path 对齐实际目录布局`)
+    return looseHits
+  }
+  return []
 }
 
 /**
@@ -360,6 +473,7 @@ function runOneModule(name, testCommand, cwd, knownFailures = []) {
   let exitCode = 0
   let output = ''
   let reason = null
+  warnPortRaceBeforeRun(testCommand)
   try {
     output = execSync(testCommand, {
       cwd,
@@ -374,6 +488,10 @@ function runOneModule(name, testCommand, cwd, knownFailures = []) {
     reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= TEST_TIMEOUT_MS
       ? `模块 ${name} 测试超时（>${TEST_TIMEOUT_MS / 1000}s）`
       : `模块 ${name} 测试退出码 ${exitCode}`
+    // 资源竞争鉴别提示（坑 verify-devserver-port-race，同 runFullCommand）
+    if (/EADDRINUSE|address already in use|端口.*被占用|port.*already/i.test(output)) {
+      reason += '。⚠️ 输出含端口占用信号（EADDRINUSE）——极可能是与你自留 dev server 的资源竞争而非代码问题：停掉占用服务后重跑 verify 再定论'
+    }
   }
   const durationMs = Date.now() - startedAt
   const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
@@ -475,9 +593,35 @@ function gitChangedFiles(cwd) {
  * @param {object|null} [ctx] - MultiRepoContext 实例（可选，缺省/null 走单仓原逻辑）
  * @returns {string[]|null} 变更文件列表；git 不可用返回 null（调用方按 hitCount=-1 处理）
  */
-export function resolveVerifyChangedFiles(cwd, changeName, ctx = null) {
+export function resolveVerifyChangedFiles(cwd, changeName, ctx = null, opts = {}) {
+  const { includeWorkingTree = false } = opts
   // 主仓 diff（原逻辑不动，单仓零回归）
-  const mainFiles = resolveMainChangedFiles(cwd, changeName)
+  let mainFiles = resolveMainChangedFiles(cwd, changeName)
+
+  // 并入 worktree 未提交改动（坑 module-subset-zero-hit-uncommitted，2026-08-21 实证：
+  // 子代理默认不 commit，真实改动全在 worktree working-tree——只看 base..HEAD commit diff
+  // 时 module 映射 0 命中直接跳过（frontend/** 变更未命中 frontend 模块）。与
+  // generateTaskReviewDrafts 的并入口径同源：meta.worktreePath 下 status --porcelain 文件
+  // （排除 .sillyspec/ 运行时产物）。opt-in（默认关）：d drafts 有自己的并入点，避免双并。
+  if (includeWorkingTree && mainFiles !== null) {
+    try {
+      const metaPath = join(cwd, '.sillyspec', '.runtime', 'worktrees', changeName, 'meta.json')
+      if (changeName && existsSync(metaPath)) {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
+        const wtGitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+          ? meta.worktreePath
+          : cwd
+        const wtStatus = gitQuiet(wtGitDir, ['status', '--porcelain'], { timeout: 30000, trim: false })
+        const wtFiles = String(wtStatus || '').split('\n')
+          .map(l => l.slice(3).trim().split(' -> ').pop() || '')
+          .map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/'))
+          .filter(p => p && p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
+        if (wtFiles.length > 0) {
+          mainFiles = [...new Set([...(mainFiles || []), ...wtFiles])]
+        }
+      }
+    } catch { /* working-tree 并入失败退回 commit diff 口径（fail-open） */ }
+  }
 
   // 无 ctx / ctx 无跨仓 entry → 主仓 diff 即结果（零回归）
   if (!ctx || typeof ctx.repos !== 'object' || ctx.repos === null) return mainFiles
@@ -581,11 +725,15 @@ export function runVerifyTestCheck({ cwd, specBase, changeName = null, ctx = nul
   let modulesPresent = false
   let hitCount = 0
   let hits = []
+  let lastChangedFiles = [] // 0 命中诊断用（diff 文件样例可见性，坑 module-path-layout-mismatch）
   if (strategy === 'module') {
     const modules = extractModules(yamlText)
     if (modules) {
       modulesPresent = true
-      const changedFiles = resolveVerifyChangedFiles(cwd, changeName)
+      // includeWorkingTree（坑 module-subset-zero-hit-uncommitted）：子代理不 commit 的改动
+      // 也参与 module 命中判定，0 命中跳过不再误伤 worktree 未提交的真实变更
+      const changedFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true })
+      lastChangedFiles = Array.isArray(changedFiles) ? changedFiles : []
       if (changedFiles === null) {
         hitCount = -1 // git 不可用 / 非仓库
       } else {
@@ -602,13 +750,24 @@ export function runVerifyTestCheck({ cwd, specBase, changeName = null, ctx = nul
   } else if (action === 'module-zero-hit-skip') {
     // module 模式 0 命中：不静默回退注定超时/含预存失败的全量（坑 verify-worktree-... 修复方向 3）。
     // 据 verify-result.md 自报告判定；想跑全量请显式设 test_strategy: full。
+    // 诊断可见性（坑 module-path-layout-mismatch，2026-08-22 实证：0 命中「靠第一次跑过的
+    // 记录兜底」——为何没命中完全黑箱）：落 modules 配置 path vs diff 文件样例，配置前缀
+    // 对不上（如 packages/frontend vs frontend/）一眼可见
+    const modules_ = extractModules(yamlText) || {}
+    const diagLines = [
+      `已配置 modules（${Object.keys(modules_).length} 个）: ${Object.entries(modules_).map(([k, m]) => `${k}→${m.path}`).join('、') || '（无）'}`,
+      `本次 diff（${lastChangedFiles.length} 个文件，前 5）: ${lastChangedFiles.slice(0, 5).join(', ') || '（空）'}`,
+    ]
+    console.warn(`⚠️ 模块 0 命中诊断（对照 path 前缀与 diff 布局是否一致，如 packages/<name> vs <name>/）：`)
+    for (const l of diagLines) console.warn(`   ${l}`)
     mainResult = {
       status: 'skipped',
       command: null,
       exitCode: null,
       durationMs: null,
       outputTail: null,
-      reason: 'test_strategy: module 但本次变更未命中任何已配置 modules（0 命中）。为避免回退到注定超时/含预存失败的全量 commands.test，CLI 未自动跑全量——据 verify-result.md 自报告判定测试。若需全量覆盖，显式设 test_strategy: full。',
+      reason: 'test_strategy: module 但本次变更未命中任何已配置 modules（0 命中）。为避免回退到注定超时/含预存失败的全量 commands.test，CLI 未自动跑全量——据 verify-result.md 自报告判定测试。若需全量覆盖，显式设 test_strategy: full。' +
+        ` 诊断：${diagLines.join('；')}`,
       resultPath: null,
       mode: 'module-zero-hit',
       fallbackReason: null,
@@ -794,6 +953,53 @@ function mergeResultInfo(mainResult, crossResults) {
 /**
  * 全量跑 commands.test（现有逻辑，brownfield 行为不变）。
  */
+/**
+ * 从测试命令文本提取疑似服务端口（坑 verify-devserver-port-race，2026-08-22 实证：CLI 全量
+ * 对账与用户自留 dev server 资源竞争——端口被占导致测试失败，差点误报 FAIL 成代码问题）。
+ * 认 --port=N / --port N / PORT=N。
+ * @param {string} cmd
+ * @returns {number[]}
+ */
+function extractPortsFromCommand(cmd) {
+  const s = String(cmd || '')
+  const ports = new Set()
+  for (const m of s.matchAll(/--port[=\s]+(\d{2,5})/gi)) ports.add(Number(m[1]))
+  for (const m of s.matchAll(/\bPORT=(\d{2,5})/gi)) ports.add(Number(m[1]))
+  return [...ports]
+}
+
+/**
+ * 端口占用探测（同步 spawnSync node 试连——verify 实测是同步 execSync 流，无法 await）。
+ * @param {number} port
+ * @returns {boolean} true=已被占用（疑似自留 dev server/长驻服务在跑）
+ */
+function isPortOccupiedSync(port) {
+  try {
+    const { spawnSync } = require('node:child_process')
+    const r = spawnSync(process.execPath, ['-e',
+      `const n=require('node:net');const s=n.connect(${port},'127.0.0.1',()=>{console.log('Y');s.end()});s.on('error',()=>console.log('N'));setTimeout(()=>{console.log('N');process.exit(0)},1500)`],
+      { encoding: 'utf8', timeout: 4000 })
+    return (r.stdout || '').trim().endsWith('Y')
+  } catch { return false }
+}
+
+/**
+ * 实测前资源竞争预警（坑 verify-devserver-port-race）：测试命令涉及的端口已被占用 →
+ * 显著 warn「疑似自留 dev server」+ 建议停服务重跑——防把资源竞争误判成代码问题报 FAIL。
+ * best-effort：探测失败静默。
+ */
+function warnPortRaceBeforeRun(command) {
+  try {
+    const ports = extractPortsFromCommand(command)
+    for (const p of ports) {
+      if (isPortOccupiedSync(p)) {
+        console.warn(`⚠️ 端口 ${p} 已被占用（测试命令 ${command.slice(0, 50)}… 引用）——疑似你自留的 dev server/长驻服务。`)
+        console.warn(`   测试若因此失败（端口冲突/EADDRINUSE），是资源竞争而非代码问题——停掉占用服务（或换端口）后重跑 verify 再定论，勿直接报 FAIL。`)
+      }
+    }
+  } catch { /* 探测失败不阻断实测 */ }
+}
+
 function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fallbackReason = null, knownFailures = [] }) {
   const command = extractTestCommand(yamlText)
 
@@ -817,6 +1023,7 @@ function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fa
   let exitCode = 0
   let output = ''
   let reason = null
+  warnPortRaceBeforeRun(command)
   try {
     output = execSync(command, {
       cwd,
@@ -831,6 +1038,11 @@ function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fa
     reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= TEST_TIMEOUT_MS
       ? `测试命令超时（>${TEST_TIMEOUT_MS / 1000}s）`
       : `测试命令退出码 ${exitCode}`
+    // 资源竞争鉴别提示（坑 verify-devserver-port-race）：EADDRINUSE/端口占用类失败极可能是
+    // 自留 dev server 竞争而非代码问题——输出里明示鉴别路径，防误报 FAIL
+    if (/EADDRINUSE|address already in use|端口.*被占用|port.*already/i.test(output)) {
+      reason += '。⚠️ 输出含端口占用信号（EADDRINUSE）——极可能是与你自留 dev server 的资源竞争而非代码问题：停掉占用服务后重跑 verify 再定论'
+    }
   }
   const durationMs = Date.now() - startedAt
   const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
@@ -873,6 +1085,11 @@ function runModuleSubset({ cwd, specBase, changeName, hits, knownFailures = [] }
   const reason = status === 'passed'
     ? null
     : `模块子集测试失败：${perModule.filter(r => r.status === 'failed').map(r => r.name).join(', ')}`
+      // 失败模块的 reason 明细透传（坑 verify-devserver-port-race：EADDRINUSE 资源竞争鉴别
+      // 提示在 runOneModule 的 reason 里，不透传会被顶层 reason 吞掉）
+      + (perModule.filter(r => r.status === 'failed' && r.reason).some(r => /EADDRINUSE|资源竞争/.test(r.reason))
+        ? '。' + perModule.filter(r => r.status === 'failed' && r.reason && /EADDRINUSE|资源竞争/.test(r.reason)).map(r => r.reason).join('；')
+        : '')
 
   const result = {
     status,

package/src/worktree-apply.js

@@ -596,7 +596,10 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   result.patchPath = patchPath;
 
   try {
-    let patchContent = '';
+    // patch 以 Buffer 聚合：git diff --binary 对二进制/非 UTF-8 文件输出任意字节序列，
+    // 按 utf8 string 拼接会破坏 NUL 字节成 U+FFFD → corrupt patch（git-helper.js git() 注释
+    // 同款坑；worktree.js 的 diff 采集已是 encoding:'buffer' 正确写法）。
+    const patchParts = [];
 
     // 分 tracked 变更和 untracked 新文件生成 patch
     // 批量化：一次 ls-tree（deliverableBase tree 中存在的文件）+ 一次 ls-files（index 中存在的文件）
@@ -615,32 +618,33 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
 
     // tracked 文件：git diff patchBase（patch 生成锚点，默认 merge-base）
     // 数组形式，文件名逐个展开为独立 argv，不经 shell；
-    // trim:false 保留二进制补丁原样，timeout 放大到 60s 防大 diff 超时——原裸 execSync 无 timeout
+    // encoding:'buffer' 保留二进制补丁原样，timeout 放大到 60s 防大 diff 超时——原裸 execSync 无 timeout
     if (trackedFiles.length > 0) {
-      patchContent += git(
+      patchParts.push(git(
         worktreePath,
         ['diff', '--binary', patchBase, '--', ...trackedFiles],
-        { trim: false, timeout: 60000 }
-      );
+        { encoding: 'buffer', timeout: 60000 }
+      ));
     }
 
     // untracked 新文件：git add 到 index，git diff --cached，然后 reset（均数组形式，文件名逐个展开）
     if (untrackedPatchFiles.length > 0) {
       git(worktreePath, ['add', '--', ...untrackedPatchFiles]);
       try {
-        // trim:false 保留二进制补丁原样，timeout 放大到 60s 防大 diff 超时
-        patchContent += git(
+        // encoding:'buffer' 保留二进制补丁原样，timeout 放大到 60s 防大 diff 超时
+        patchParts.push(git(
           worktreePath,
           ['diff', '--binary', '--cached', '--', ...untrackedPatchFiles],
-          { trim: false, timeout: 60000 }
-        );
+          { encoding: 'buffer', timeout: 60000 }
+        ));
       } finally {
         // 重置 index（不保留 staged 状态）
         gitQuiet(worktreePath, ['reset', 'HEAD', '--', ...untrackedPatchFiles]);
       }
     }
 
-    if (!patchContent.trim()) {
+    const patchContent = Buffer.concat(patchParts);
+    if (patchContent.length === 0) {
       // patch 为空（清单中部分文件可能没实际变更）
       result.ok = true;
       rmSync(tmpDir, { recursive: true, force: true });
@@ -717,6 +721,20 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     }
 
   } catch (e) {
+    // ENOBUFS 自动降级（坑 apply-spawnsync-enobufs，2026-08-22 实证：大 diff 的 binary patch
+    // 超 maxBuffer 抛 ENOBUFS，此前只能 agent 手动 git merge 绕行）——git apply 路径走不通时
+    // 自动落 applyByMerge（既有 --merge 兜底，语义同为三方合并）
+    if (/ENOBUFS/i.test(String(e.message || e.code || ''))) {
+      result.warnings = (result.warnings || []).concat(
+        [`patch 生成超出进程缓冲区（ENOBUFS，超大 diff）——自动降级 git merge 路径应用`]
+      );
+      try {
+        return applyByMerge(result, changeName, projectRoot, wm);
+      } catch (mergeErr) {
+        result.errors.push(`ENOBUFS 降级 merge 也失败: ${mergeErr.message}`);
+        return result;
+      }
+    }
     result.errors.push(`patch 生成/应用异常: ${e.message}`);
     return result;
   } finally {