sillyspec 3.25.1 → 3.25.3

package/src/stages/plan-postcheck.js

@@ -17,6 +17,7 @@ const readFileSync = (filePath, encoding) => _readFileSync(filePath, encoding).r
 import { join as pJoin } from 'path'
 import jsYaml from 'js-yaml'
 import { parseFileChangeList, pathMatches } from '../change-list.js'
+import { getRule } from '../stage-contract-spec.js'
 
 // ═══════════════════════════════════════════════════════════════
 // 解析工具（从 plan.js 迁移）
@@ -201,6 +202,34 @@ export function topoSortWaves(depMap) {
   return { waves, error: null }
 }
 
+/**
+ * 解析 plan.md 显式 Wave 分组 → Map<taskId, waveIndex>。
+ *
+ * Wave 口径与 execute.js parseWavesFromPlan 一致（execute 的真实并行单元，非 topoSort 建议值）：
+ *   - `## Wave N` 标题下的 task-XX checkbox 归入 Wave N；
+ *   - 非 Wave 标题行（## 自检 等）退出当前 Wave 段，避免其 checkbox 混入。
+ * 返回 null = plan.md 不存在或无显式 Wave 标题 → execute 会把所有 task 放进单个隐式 Wave
+ * 全并行（execute.js:402-408），调用方据此判「同文件即冲突」。
+ *
+ * @param {string} planPath - plan.md 绝对路径
+ * @returns {Map<string, number>|null} taskId → waveIndex；null = 无显式 Wave
+ */
+function parseTaskWavesFromPlan(planPath) {
+  if (!existsSync(planPath)) return null
+  const content = readFileSync(planPath, 'utf8')
+  if (!/^#+\s*Wave\s+\d+/im.test(content)) return null
+  const map = new Map()
+  let currentWave = null
+  for (const line of content.split('\n')) {
+    const wm = line.match(/^#+\s*Wave\s+(\d+)/i)
+    if (wm) { currentWave = parseInt(wm[1], 10); continue }
+    if (/^#+\s/.test(line)) { currentWave = null; continue } // 非 Wave 标题退出当前 Wave 段
+    const tm = line.match(/^[-*]\s*\[[ x]\]\s*(task-\d+)/i)
+    if (tm && currentWave !== null) map.set(tm[1], currentWave)
+  }
+  return map
+}
+
 /**
  * 本地一致性校验器
  * @param {string} changeDir - 变更目录
@@ -220,6 +249,8 @@ export function validateBlueprintConsistency(changeDir) {
     return { ok: false, errors: ['tasks/ 目录下没有 task-NN.md 文件'], warnings }
   }
 
+  // task 卡片基础字段文案从 manifest 同源(plan.task-card-structure);${id} 由下方 `${taskId} (${file})` 替换。
+  const bsRule = getRule('plan.task-card-structure')
   const taskInfo = new Map()
   const pathOwners = new Map()
 
@@ -240,13 +271,13 @@ export function validateBlueprintConsistency(changeDir) {
     taskInfo.set(taskId, { dependsOn, allowedPaths, hasAcceptance, hasTdd, file })
 
     if (allowedPaths.length === 0) {
-      errors.push(`${taskId} (${file}): frontmatter 缺少 allowed_paths（需非空数组，列出本 task 真实改动的源文件；回归类 task 无源码改动时填被验证的关键入口文件）`)
+      errors.push(bsRule.data.messageAllowedPaths.replaceAll('${id}', `${taskId} (${file})`))
     }
     if (!hasAcceptance) {
-      errors.push(`${taskId} (${file}): 缺少验收标准——frontmatter 需有 acceptance: 列表字段，或 body 需有「## 验收标准」/「## Acceptance」章节`)
+      errors.push(bsRule.data.messageAcceptance.replaceAll('${id}', `${taskId} (${file})`))
     }
     if (!hasTdd) {
-      warnings.push(`${taskId} (${file}): 缺少验证步骤——frontmatter 需有 verify: 字段，或 body 需有「## TDD」/「## 验证」/「## Verify」章节`)
+      warnings.push(bsRule.data.messageTdd.replaceAll('${id}', `${taskId} (${file})`))
     }
 
     for (const p of allowedPaths) {
@@ -255,10 +286,40 @@ export function validateBlueprintConsistency(changeDir) {
     }
   }
 
-  // 路径冲突
+  // 路径冲突（Wave 感知）：同 Wave 内 >1 task 共享 allowed_path → execute 强制并行（execute.js:603）
+  // 子代理会互相覆盖该文件 → error。跨 Wave 同文件 → 串行执行安全 → warning。
+  // Wave 口径 = plan.md 显式 `## Wave N`（parseTaskWavesFromPlan，与 execute 同源，非 topoSort 建议值）；
+  // plan.md 无显式 Wave → execute 全并行（隐式单 Wave，execute.js:402-408）→ 同文件即冲突。
+  const waveOfTask = parseTaskWavesFromPlan(pJoin(changeDir, 'plan.md'))
   for (const [p, owners] of pathOwners) {
-    if (owners.length > 1) {
-      warnings.push(`路径 ${p} 被 ${owners.length} 个 task 修改: ${owners.join(', ')}（确认是否为有意共享）`)
+    if (owners.length < 2) continue
+    if (waveOfTask === null) {
+      errors.push(
+        `路径 ${p} 被 ${owners.length} 个 task 修改: ${owners.join(', ')} — plan.md 无显式 Wave 划分，` +
+        `execute 会把它们放进同一隐式 Wave 全并行（execute.js:402-408），子代理互相覆盖。` +
+        `解法：拆到不同 Wave（串行），或合并为单个 task。`
+      )
+      continue
+    }
+    // 显式 Wave：按 wave 分组 owners，找同 Wave 冲突
+    const byWave = new Map()
+    for (const t of owners) {
+      const w = waveOfTask.get(t)
+      if (w === undefined) continue // 未列入任何 Wave → execute 不执行，不参与冲突判定
+      if (!byWave.has(w)) byWave.set(w, [])
+      byWave.get(w).push(t)
+    }
+    for (const [w, ts] of byWave) {
+      if (ts.length > 1) {
+        errors.push(
+          `路径 ${p} 被 Wave ${w} 内 ${ts.length} 个 task 修改: ${ts.join(', ')} — 同 Wave 任务 execute 强制并行（execute.js:603），` +
+          `子代理会互相覆盖该文件。解法：把它们拆到不同 Wave（串行）。`
+        )
+      }
+    }
+    // 跨 Wave 共享：串行安全，仅提示
+    if (byWave.size > 1) {
+      warnings.push(`路径 ${p} 跨 Wave 被修改: ${owners.join(', ')}（不同 Wave 串行执行，安全；确认是否有意共享）`)
     }
   }
 
@@ -314,7 +375,16 @@ export function validateCrossTaskContracts(changeDir) {
     providesByTask.set(taskId, contractMap)
   }
 
-  // 第二遍：校验每个 consumer 的 expects_from 是否被 provider.provides 覆盖
+  // 第二遍：校验每个 consumer 的 expects_from 是否被 provider.provides 覆盖。
+  // 3 种断裂文案(unknown-provider / undeclared / missing-fields)从 manifest 同源
+  // (plan.cross-task-contract.data),${consumer}/${provider}/${contract}/${needs}/${available} replaceAll。
+  const ctRule = getRule('plan.cross-task-contract')
+  const renderCtMsg = (tmpl, consumer, provider, contract, needs, available) => tmpl
+    .replaceAll('${consumer}', consumer)
+    .replaceAll('${provider}', provider)
+    .replaceAll('${contract}', contract)
+    .replaceAll('${needs}', needs)
+    .replaceAll('${available}', available)
   for (const file of taskFiles) {
     const content = readFileSync(pJoin(tasksDir, file), 'utf8')
     const consumerId = parseTaskId(content, file)
@@ -324,7 +394,7 @@ export function validateCrossTaskContracts(changeDir) {
     for (const [providerTask, contracts] of Object.entries(expectsFrom)) {
       if (!providesByTask.has(providerTask)) {
         for (const c of contracts) {
-          errors.push(`${consumerId}: expects_from 引用了不存在的 ${providerTask}（contract "${c.contract}", needs [${c.needs.join(', ')}]）`)
+          errors.push(renderCtMsg(ctRule.data.messageUnknownProvider, consumerId, providerTask, c.contract, c.needs.join(', '), ''))
         }
         continue
       }
@@ -333,12 +403,12 @@ export function validateCrossTaskContracts(changeDir) {
       for (const c of contracts) {
         const providerFields = providerContracts.get(c.contract)
         if (providerFields === undefined) {
-          errors.push(`${consumerId}: expects_from ${providerTask} contract "${c.contract}" needs [${c.needs.join(', ')}] — ${providerTask} 的 provides 未声明此契约`)
+          errors.push(renderCtMsg(ctRule.data.messageUndeclaredContract, consumerId, providerTask, c.contract, c.needs.join(', '), ''))
           continue
         }
         const missing = c.needs.filter(f => !providerFields.has(f))
         if (missing.length > 0) {
-          errors.push(`${consumerId}: expects_from ${providerTask} contract "${c.contract}" needs [${missing.join(', ')}] — ${providerTask}.provides 仅含 [${[...providerFields].join(', ')}]`)
+          errors.push(renderCtMsg(ctRule.data.messageMissingFields, consumerId, providerTask, c.contract, missing.join(', '), [...providerFields].join(', ')))
         }
       }
     }
@@ -388,13 +458,12 @@ export function validateDesignFileCoverage(changeDir) {
   }
 
   const designFiles = [...parseFileChangeList(designPath)]
+  // 两种断裂文案(缺清单章节 / 文件未覆盖)从 manifest 同源(plan.design-file-coverage.data)。
+  const dcRule = getRule('plan.design-file-coverage')
   if (designFiles.length === 0) {
     // 走到 plan-postcheck 说明已生成 task 卡片（light/full），brainstorm 模板规定清单必填。
     // 无清单 = design↔execute 偏差温床（覆盖对账无从对起），阻断，不让它静默放过。
-    errors.push(
-      'design.md 缺少「文件变更清单」章节（或清单解析为空），无法做文件覆盖对账。' +
-      '该章节在 brainstorm 模板中为必填；请在 design.md 补上完整的文件变更清单（列出本次新增/修改/删除的源码文件）后重试。'
-    )
+    errors.push(dcRule.data.messageMissingList)
     return { ok: false, errors, warnings, designFiles: [], uncovered: [] }
   }
   const allAllowed = []
@@ -409,11 +478,9 @@ export function validateDesignFileCoverage(changeDir) {
   const uncovered = designFiles.filter(df => !allAllowed.some(ap => pathMatches(df, ap)))
   if (uncovered.length > 0) {
     errors.push(
-      `design.md 文件变更清单中 ${uncovered.length} 个文件未被任何 task 的 allowed_paths 覆盖：\n` +
-      uncovered.map(f => `     • ${f}`).join('\n') +
-      `\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。` +
-      `\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，` +
-      `或在 design.md「不修改文件」章节说明不改原因。`
+      dcRule.data.messageUncovered
+        .replaceAll('${count}', uncovered.length)
+        .replaceAll('${files}', uncovered.map(f => `     • ${f}`).join('\n'))
     )
   }
 
@@ -441,6 +508,8 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     return { ok: true, errors, warnings }
   }
 
+  // task 卡片完整 schema 文案从 manifest 同源(plan.task-card-schema);${id} 随检查点取 ${file} / ${taskId || file} / ${taskId}。
+  const fsRule = getRule('plan.task-card-schema')
   const allTaskIds = []
   const depMap = new Map()
 
@@ -448,7 +517,7 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     const content = readFileSync(pJoin(tasksDir, file), 'utf8')
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
     if (!fmMatch) {
-      errors.push(`${file}: 缺少 YAML frontmatter`)
+      errors.push(fsRule.data.messageFrontmatter.replaceAll('${id}', file))
       continue
     }
     const fm = fmMatch[1]
@@ -460,13 +529,13 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     const allowedPathsRaw = fm.match(/allowed_paths:\s*\n((?:\s+-\s+.+\n?)+)/)?.[1] || ''
     const allowedPaths = allowedPathsRaw.match(/-\s+(.+)/g)?.map(s => s.replace(/^-\s+/, '').trim()) || []
 
-    if (!taskId) errors.push(`${file}: frontmatter 缺少 id`)
-    if (!title) errors.push(`${file}: frontmatter 缺少 title`)
+    if (!taskId) errors.push(fsRule.data.messageId.replaceAll('${id}', file))
+    if (!title) errors.push(fsRule.data.messageTitle.replaceAll('${id}', file))
     if (taskId) allTaskIds.push(taskId)
 
     // 2. allowed_paths 不为空
     if (allowedPaths.length === 0) {
-      errors.push(`${taskId || file}: allowed_paths 为空`)
+      errors.push(fsRule.data.messageAllowedPaths.replaceAll('${id}', taskId || file))
     }
 
     // 3. allowed_paths 文件存在或父目录存在（仅在 projectRoot 提供时检查）
@@ -491,18 +560,18 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     const hasVerify = /verify:/m.test(fm)
     const hasConstraints = /constraints:/m.test(fm)
 
-    if (!hasGoal) errors.push(`${taskId || file}: 缺少 goal 字段`)
-    if (!hasImplementation) errors.push(`${taskId || file}: 缺少 implementation 字段`)
-    if (!hasAcceptance) errors.push(`${taskId || file}: 缺少 acceptance 字段`)
-    if (!hasVerify) errors.push(`${taskId || file}: 缺少 verify 字段`)
-    if (!hasConstraints) errors.push(`${taskId || file}: 缺少 constraints 字段`)
+    if (!hasGoal) errors.push(fsRule.data.messageGoal.replaceAll('${id}', taskId || file))
+    if (!hasImplementation) errors.push(fsRule.data.messageImplementation.replaceAll('${id}', taskId || file))
+    if (!hasAcceptance) errors.push(fsRule.data.messageAcceptance.replaceAll('${id}', taskId || file))
+    if (!hasVerify) errors.push(fsRule.data.messageVerify.replaceAll('${id}', taskId || file))
+    if (!hasConstraints) errors.push(fsRule.data.messageConstraints.replaceAll('${id}', taskId || file))
   }
 
   // 4b. depends_on 引用存在性
   for (const [taskId, deps] of depMap) {
     for (const dep of deps) {
       if (!depMap.has(dep)) {
-        errors.push(`${taskId}: depends_on 引用了不存在的 ${dep}`)
+        errors.push(fsRule.data.messageDependsOnMissing.replaceAll('${id}', taskId).replaceAll('${dep}', dep))
       }
     }
   }
@@ -522,7 +591,7 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     if (nums.length > 0 && nums[0] === 1) {
       for (let i = 0; i < nums.length; i++) {
         if (nums[i] !== i + 1) {
-          errors.push(`task id 不连续: 期望 task-${String(i + 1).padStart(2, '0')}, 实际 task-${String(nums[i]).padStart(2, '0')}`)
+          errors.push(getRule('plan.task-id-continuity').failMessage.replaceAll('${expected}', String(i + 1).padStart(2, '0')).replaceAll('${actual}', String(nums[i]).padStart(2, '0')))
           break
         }
       }

package/src/stages/plan.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import path from 'path'
+import { getRule } from '../stage-contract-spec.js'
 
 // 从 plan-postcheck.js 重导出（保持向后兼容）
 export {
@@ -22,48 +23,17 @@ export function validateDesignForPlan(designContent) {
   const warnings = []
 
   if (!designContent || !designContent.trim()) {
-    return { ok: false, errors: ['design.md 内容为空'], warnings }
+    return { ok: false, errors: [getRule('plan.design-readiness').data.emptyMessage], warnings }
   }
 
-  const lower = designContent.toLowerCase()
-
-  // 检查 1: 必须包含目标/问题描述（error）
-  const hasGoal = /(^|\n)#{2,}\s*.*(目标|goal|objective|背景|background|问题|problem|purpose|目的)/i.test(designContent)
-  if (!hasGoal) {
-    errors.push('design.md 缺少「目标/背景/问题描述」章节 — plan 需要知道要达成什么')
-  }
-
-  // 检查 2: 必须包含范围/scope（error）
-  const hasScope = /(^|\n)#{2,}\s*.*(范围|scope|总体方案|方案|approach|solution|设计|design)/i.test(designContent)
-  if (!hasScope) {
-    errors.push('design.md 缺少「范围/总体方案/设计」章节 — plan 需要知道做什么和怎么做')
-  }
-
-  // 检查 3: 必须包含决策/方案选择（error）
-  const hasDecisions = /(^|\n)#{2,}\s*.*(决策|decision|选择|choice|方案选择)/i.test(designContent)
-  || /d-\d+@v\d+/i.test(designContent) // decisions.md 引用 ID
-  || /decisions?\.md/i.test(designContent) // 引用 decisions.md
-  if (!hasDecisions) {
-    errors.push('design.md 缺少「决策/方案选择」— plan 需要基于明确的技术决策来拆分任务')
-  }
-
-  // 检查 4 (warning): 缺非目标/non-goals
-  const hasNonGoals = /(^|\n)#{2,}\s*.*(非目标|non-goals?|不做|out of scope|不在范围)/i.test(designContent)
-  if (!hasNonGoals) {
-    warnings.push('design.md 缺少「非目标/Non-goals」— 建议明确不做什么，防止 scope creep')
-  }
-
-  // 检查 5 (warning): 缺约束/风险
-  const hasConstraints = /(^|\n)#{2,}\s*.*(约束|constraint|限制|limitation|风险|risk|trade-?off)/i.test(designContent)
-  if (!hasConstraints) {
-    warnings.push('design.md 缺少「约束/风险/Trade-off」— 建议记录已知约束和风险')
-  }
-
-  // 检查 6 (warning): 缺文件变更清单
-  const hasFileChanges = /文件变更|file change|变更清单|changed files/i.test(designContent)
-  || /^\|\s*(新增|修改|删除|new|modify|delete|update)\s*\|/im.test(designContent)
-  if (!hasFileChanges) {
-    warnings.push('design.md 缺少「文件变更清单」— 建议列出预期改动的文件')
+  // 6 章节就绪检查(patterns + message)从 manifest 同源(stage-contract-spec.js plan.design-readiness);
+  // 逐章节 test,patterns 数组任一命中即视为有该章节。算法等价旧内联正则(原 lower 变量未使用,已弃)。
+  const rule = getRule('plan.design-readiness')
+  for (const check of rule.data.checks) {
+    const matched = check.patterns.some(p => new RegExp(p.pattern, p.flags).test(designContent))
+    if (!matched) {
+      (check.severity === 'error' ? errors : warnings).push(check.message)
+    }
   }
 
   return { ok: errors.length === 0, errors, warnings }
@@ -357,15 +327,8 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 用 Agent tool 启动子代理（subagent_type: general），prompt 要点：
 1. 独立读取 {SPEC_ROOT}/changes/<change>/plan.md + design.md + tasks/*.md（不要让生成者喂结论给你，自己读原始文件）
 2. 执行上方审查清单，每条给 pass/gap/fail + 证据
-3. 输出 review.json 到 {SPEC_ROOT}/.runtime/stage-reviews/plan-{STAGE_REVIEW_RUN_ID}/review.json，字段：
-   - schemaVersion: 1
-   - reviewType: plan ; stage: plan
-   - specVerdict / qualityVerdict: pass | fail | cannot_verify
-   - reviewedFiles: [changes/<change>/plan.md]
-   - docHash: plan.md 内容的 sha256
-   - checklist: 每条 { item, result: pass|gap|fail, note }
-   - requiredEvidence: cannot_verify 时必填非空
-   - reviewerNotes: 说明
+3. 输出 review.json(CLI Stage Review Gate 将硬校验,契约如下 —— schema + 完整示例 + docHash 算法,照抄改值):
+{REVIEW_JSON_CONTRACT}
 4. verdict=fail 时在 reviewerNotes 写明阻断项
 
 ### 输出

package/src/stages/propose.js

@@ -143,7 +143,8 @@ export const definition = {
 ### 当前审查分级（CLI 按变更规模判定，占位符由 run.js 注入）
 tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 - tier=self：当前 agent 直接执行下方 checklist
-- tier=independent：必须用 Agent tool 启动一个独立的规范审查子代理（独立上下文，不共享你的分析），子代理执行下方 checklist 并输出 review.json 到 {SPEC_ROOT}/.runtime/stage-reviews/propose-{STAGE_REVIEW_RUN_ID}/review.json。字段：reviewType=proposal；reviewedFiles=[proposal.md, design.md, requirements.md, tasks.md]（相对 changes/<change>/）；docHash=proposal.md 的 sha256；specVerdict/qualityVerdict=pass|fail|cannot_verify；checklist 每条 pass|gap|fail。
+- tier=independent：必须用 Agent tool 启动一个独立的规范审查子代理（独立上下文，不共享你的分析），子代理执行下方 checklist 并输出 review.json。review.json 产物契约（CLI Stage Review Gate 将硬校验，schema + 完整示例 + docHash 算法如下，照抄改值）:
+{REVIEW_JSON_CONTRACT}
 
 ### 操作
 检查以下各项：

package/src/stages/scan.js

@@ -143,6 +143,8 @@ export const definition = {
 - 生成每份 scan 文档时，frontmatter 必须包含：
   \`\`\`yaml
   ---
+  author: <git 用户名（git config user.name 的输出，如 qinyi）>
+  created_at: <精确到秒的时间，如 2026-07-27 10:30:00>
   source_commit: <git-head-short>
   updated_at: <now-iso-datetime>
   generator: sillyspec-scan
@@ -159,7 +161,7 @@ export const definition = {
 - 断点续扫步骤列出的缺失文档列表
 - 环境探测结果摘要（如有 _env-detect.md，直接贴入）
 - **⚠️ 必须强调：子代理必须用 write 工具将文件写入磁盘**
-- **文件标题用中文**（sillyhub 平台解析识别用）：每份 scan 文档第一行用 # 中文名（English）格式：
+- **文件标题用中文**（sillyhub 平台解析识别用）：frontmatter 必须在文件最前（第 1 行 --- 起），frontmatter 结束的 --- 之后空一行，再写 # 中文名（English）作为标题。严禁把 # 标题放到 frontmatter 之前（否则 frontmatter 不在头部、Step11 检查项9 会报缺 author/created_at）。各文档标准标题格式：
   - STRUCTURE.md = # 目录结构（Structure）
   - CONVENTIONS.md = # 代码约定（Conventions）
   - ARCHITECTURE.md = # 架构（Architecture）

package/src/workflow.js

@@ -13,6 +13,7 @@ import { readFileSync, existsSync, readdirSync, writeFileSync, mkdirSync } from
 import { join, resolve, basename } from 'path'
 import jsYaml from 'js-yaml'
 import { WORKFLOW_STATUS } from './constants.js'
+import { contentNonEmpty, lineCount, missingSections, placeholderLineMatches } from './check-primitives.js'
 
 // ─── Workflow 加载 ───
 
@@ -174,7 +175,7 @@ function checkOutput(outputDef, projectName, cwd, specBase) {
       case 'no_empty_files': {
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
-          const empty = content.trim().length === 0
+          const empty = !contentNonEmpty(content)
           results.push({ passed: !empty, check: 'no_empty_files', detail: empty ? `文件为空: ${rawPath}` : '' })
         } else {
           results.push({ passed: false, check: 'no_empty_files', detail: `文件不存在: ${rawPath}` })
@@ -184,7 +185,7 @@ function checkOutput(outputDef, projectName, cwd, specBase) {
       case 'min_lines': {
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
-          const lines = content.split('\n').length
+          const lines = lineCount(content)
           const min = check.min || 1
           results.push({ passed: lines >= min, check: `min_lines(${min})`, detail: lines >= min ? '' : `文件只有 ${lines} 行，要求至少 ${min} 行: ${rawPath}` })
         } else {
@@ -196,7 +197,7 @@ function checkOutput(outputDef, projectName, cwd, specBase) {
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
           const sections = check.sections || []
-          const missing = sections.filter(s => !content.includes(`## ${s}`))
+          const missing = missingSections(content, sections)
           results.push({ passed: missing.length === 0, check: 'contains_sections', detail: missing.length > 0 ? `缺少章节: ${missing.join(', ')} — ${rawPath}` : '' })
         } else {
           results.push({ passed: false, check: 'contains_sections', detail: `文件不存在: ${rawPath}` })
@@ -206,12 +207,7 @@ function checkOutput(outputDef, projectName, cwd, specBase) {
       case 'no_placeholder': {
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
-          const patterns = check.patterns || ['待补充', 'TODO', 'TBD', '未分析', '根据项目情况', '根据实际情况', '按需填写']
-          // 只匹配独立成行的占位文本，不匹配行内引用
-          const lineMatches = patterns.filter(p => {
-            const regex = new RegExp(`^\\s*[-*]?\\s*${p}\\s*$`, 'm')
-            return regex.test(content)
-          })
+          const lineMatches = placeholderLineMatches(content, check.patterns)
           results.push({ passed: lineMatches.length === 0, check: 'no_placeholder', detail: lineMatches.length > 0 ? `包含占位文本: ${lineMatches.map(m => `"${m}"`).join(', ')} — ${rawPath}` : '' })
         } else {
           results.push({ passed: false, check: 'no_placeholder', detail: `文件不存在: ${rawPath}` })
@@ -355,7 +351,7 @@ function _checkWorkflow(wf, cwd, projectName, specBase) {
           let anyEmpty = false
           for (const f of files) {
             const content = readFileSync(join(scanDir, f), 'utf8')
-            if (content.trim().length === 0) {
+            if (!contentNonEmpty(content)) {
               const detail = `空文件: ${join(scanDir, f)}`
               workflowCheckResults.push({ type: 'no_empty_files', status: 'fail', detail })
               failures.push({ level: 'workflow', check: 'no_empty_files', message: detail })
@@ -396,7 +392,7 @@ function _checkWorkflow(wf, cwd, projectName, specBase) {
         const fullPath = join(effectiveBase, checkPath)
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
-          const lines = content.split('\n').length
+          const lines = lineCount(content)
           const min = check.min || 1
           if (lines < min) {
             const detail = `文件只有 ${lines} 行，要求至少 ${min} 行: ${checkPath}`
@@ -420,7 +416,7 @@ function _checkWorkflow(wf, cwd, projectName, specBase) {
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
           const sections = check.sections || []
-          const missing = sections.filter(s => !content.includes(`## ${s}`))
+          const missing = missingSections(content, sections)
           if (missing.length > 0) {
             const detail = `缺少章节: ${missing.join(', ')} — ${checkPath}`
             workflowCheckResults.push({ type: 'contains_sections', status: 'fail', detail })
@@ -442,11 +438,7 @@ function _checkWorkflow(wf, cwd, projectName, specBase) {
         const fullPath = join(effectiveBase, checkPath)
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, 'utf8')
-          const patterns = check.patterns || ['待补充', 'TODO', 'TBD', '未分析', '根据项目情况', '根据实际情况', '按需填写']
-          const lineMatches = patterns.filter(p => {
-            const regex = new RegExp(`^\\s*[-*]?\\s*${p}\\s*$`, 'm')
-            return regex.test(content)
-          })
+          const lineMatches = placeholderLineMatches(content, check.patterns)
           if (lineMatches.length > 0) {
             const detail = `包含占位文本: ${lineMatches.map(m => `"${m}"`).join(', ')} — ${checkPath}`
             workflowCheckResults.push({ type: 'no_placeholder', status: 'fail', detail })

package/src/worktree-apply.js

@@ -184,9 +184,17 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   }
 
   // --- 4.5 校验：主工作区 baseline 是否变化（防 execute 期间主工作区被修改）---
-  // 注意：必须和 computeBaselineHash (worktree.js) 使用相同的排除规则
+  // 注意：必须和 computeBaselineHash (worktree.js) 使用相同的排除规则。
+  // 排除非交付物的元数据/文档 churn（execute 自身改的 + 多操作者常改的 agent 指引/文档），
+  // 否则别人改 CLAUDE.md/docs/.claude → 整树 hash 变 → apply 误阻断（多操作者仓库高频踩坑）。
+  // 安全：放过它们不丢真冲突——下方 step5a(未提交∩changedFiles)+step5b(HEAD blob) 对交付文件
+  // 做精确 per-file 校验，不读这里的 exclude。
+  //   - .sillyspec/：plan/design 蓝图 + runtime 产物
+  //   - .claude/：agent 配置/skills/CLAUDE.md
+  //   - docs/：文档（deliverable 文档冲突由 step5a/5b 兜底）
+  //   - CLAUDE.md：根 agent 指引
   if (meta.baselineHash) {
-    const exclude = '-- . ":(exclude).sillyspec/"';
+    const exclude = '-- . ":(exclude).sillyspec/" ":(exclude).claude/" ":(exclude)docs/" ":(exclude)CLAUDE.md"';
     const staged = gitQuiet(projectRoot, `diff --cached ${exclude}`) || '';
     const unstaged = gitQuiet(projectRoot, `diff ${exclude}`) || '';
     const untracked = gitQuiet(projectRoot, `ls-files --others --exclude-standard ${exclude}`) || '';

package/src/worktree-deps.js

@@ -131,55 +131,137 @@ function tryInstall(cmd, cwd, timeout) {
   }
 }
 
+/** 目录是否含 nodejs 标记（package.json 或任一 lockfile）——识别 monorepo 里的 nodejs 子模块 */
+function hasNodeMarker(dir) {
+  if (!dir || !existsSync(dir)) return false;
+  if (existsSync(join(dir, 'package.json'))) return true;
+  return LOCKFILES.some(lf => existsSync(join(dir, lf)));
+}
+
+/**
+ * 从 local.yaml 提取 modules 块的 path 列表（generic monorepo 子模块路径）。
+ * 兼容 inline flow（`frontend: { path: "frontend/" }`）与 block（`frontend:\n    path: frontend/`）。
+ * 轻量正则，不引 yaml 依赖（与 extractUserInstall / scan-postcheck 风格一致）。
+ * 坑 execute-worktree-pnpm-monorepo-no-node-modules：generic 项目 worktree 子模块无 node_modules。
+ * @returns {string[]} 去重 + 去 trailing 斜杠的相对路径
+ */
+function extractModulePaths(yamlText) {
+  if (!yamlText) return [];
+  const idx = yamlText.search(/^modules:\s*$/m);
+  if (idx < 0) return [];
+  const nlIdx = yamlText.indexOf('\n', idx);
+  if (nlIdx < 0) return [];
+  let rest = yamlText.slice(nlIdx + 1);
+  const nextTop = rest.search(/^\S/m); // 下一个顶层 key（行首非空白）
+  const block = nextTop >= 0 ? rest.slice(0, nextTop) : rest;
+  const paths = [];
+  const re = /path:\s*["']?([^"'\s,}]+)/g;
+  let pm;
+  while ((pm = re.exec(block)) !== null) {
+    const p = pm[1].replace(/\/+$/, '').trim();
+    if (p && p !== '.') paths.push(p);
+  }
+  return [...new Set(paths)];
+}
+
+/**
+ * 对单个子模块目录 tryLink main 的 node_modules → wt 的 node_modules（modules 子模块专用）。
+ * 仅走 link 快路径（不 install——子模块 install 慢且易失败；lockfile 不一致时交给用户 pnpm install）。
+ * lockfile 一致才 link，避免误链不匹配的 deps。
+ */
+function linkOneDir(wtDir, mainDir) {
+  const mainNodeModules = join(mainDir, 'node_modules');
+  if (!existsSync(mainNodeModules)) return { status: 'skipped', reason: 'main 无 node_modules' };
+  const wtHash = lockfileHash(wtDir);
+  const mainHash = lockfileHash(mainDir);
+  if (wtHash && mainHash && wtHash !== mainHash) {
+    return { status: 'mismatch', reason: `lockfile 不一致 main=${mainHash} wt=${wtHash}` };
+  }
+  const r = tryLink(mainNodeModules, join(wtDir, 'node_modules'));
+  if (r.ok) return { status: 'linked', method: r.method };
+  return { status: 'failed', error: r.error };
+}
+
 /**
- * 供给依赖。返回 deps 状态对象（合并进 meta）。
+ * 供给依赖。返回 deps 状态对象（合并进 meta）。两段：
+ *   1. 根目录供给（原有逻辑：lockfile 一致 link / 不一致 install / generic→根 n/a）
+ *   2. modules 块的 nodejs 子模块 link（generic monorepo：根无 deps 但 frontend/daemon 等子模块需要）
+ * generic + 子模块 link 成功时，整体 depsStatus 从 n/a 升级为 linked（deps gate 不再误判 unknown 阻断）。
+ *
  * @param {string} worktreePath - worktree 根目录
  * @param {string} mainCwd - 主 checkout 根目录（node_modules 来源）
  * @param {{ specBase?: string, timeout?: number }} opts
- * @returns {{ depsStatus, depsMethod, depsSource, depsLockHash, depsCheckedAt, depsError? }}
+ * @returns {{ depsStatus, depsMethod, depsSource, depsLockHash, depsCheckedAt, depsError?, depsModules? }}
  */
 export function provisionDeps(worktreePath, mainCwd, opts = {}) {
   const { specBase = null, timeout = DEFAULT_TIMEOUT_MS } = opts;
   const depsCheckedAt = new Date().toISOString();
+  const yamlText = readLocalYaml(specBase, worktreePath);
   const wtHash = lockfileHash(worktreePath);
 
+  // ── 1. 根目录供给 ──
   const projectType = detectProjectType(worktreePath, specBase);
-  const userInstall = extractUserInstall(readLocalYaml(specBase, worktreePath));
+  const userInstall = extractUserInstall(yamlText);
   const installCmd = inferInstallCommand(projectType, worktreePath, userInstall);
 
-  // generic / 无可执行 install → n/a
+  let result;
   if (!installCmd) {
-    return { depsStatus: 'n/a', depsMethod: null, depsSource: null, depsLockHash: wtHash, depsCheckedAt };
+    // generic / 无可执行 install → 根无 deps 动作（n/a）；但下方 modules 子模块仍可能 link 升级
+    result = { depsStatus: 'n/a', depsMethod: null, depsSource: null, depsLockHash: wtHash };
+  } else {
+    // 快路径：main 有 node_modules 且 lockfile hash 一致 → junction/symlink
+    const mainNodeModules = mainCwd ? join(mainCwd, 'node_modules') : null;
+    const mainHash = lockfileHash(mainCwd);
+    let linked = false;
+    if (mainNodeModules && existsSync(mainNodeModules) && mainHash && wtHash && mainHash === wtHash) {
+      const linkResult = tryLink(mainNodeModules, join(worktreePath, 'node_modules'));
+      if (linkResult.ok) {
+        result = {
+          depsStatus: 'linked',
+          depsMethod: linkResult.method,
+          depsSource: linkResult.preexisting ? 'install' : 'main-checkout',
+          depsLockHash: wtHash,
+        };
+        linked = true;
+      }
+    }
+    if (!linked) {
+      // 兜底：install
+      const installResult = tryInstall(installCmd, worktreePath, timeout);
+      result = installResult.ok
+        ? { depsStatus: 'installed', depsMethod: 'install', depsSource: 'install', depsLockHash: wtHash }
+        : { depsStatus: 'failed', depsMethod: null, depsSource: null, depsLockHash: wtHash, depsError: installResult.error };
+    }
   }
+  result.depsCheckedAt = depsCheckedAt;
 
-  // 快路径：main 有 node_modules 且 lockfile hash 一致 → junction/symlink
-  const mainNodeModules = mainCwd ? join(mainCwd, 'node_modules') : null;
-  const mainHash = lockfileHash(mainCwd);
-  if (mainNodeModules && existsSync(mainNodeModules) && mainHash && wtHash && mainHash === wtHash) {
-    const linkResult = tryLink(mainNodeModules, join(worktreePath, 'node_modules'));
-    if (linkResult.ok) {
-      return {
-        depsStatus: 'linked',
-        depsMethod: linkResult.method,
-        depsSource: linkResult.preexisting ? 'install' : 'main-checkout',
-        depsLockHash: wtHash,
-        depsCheckedAt,
-      };
-    }
-    // link 失败 → 回退 install
+  // ── 2. modules 块的 nodejs 子模块 link（坑 execute-worktree-pnpm-monorepo-no-node-modules）──
+  // generic monorepo（如 multi-agent-platform）worktree 子模块 frontend/sillyhub-daemon 无 node_modules，
+  // 跑 pnpm test 失败。读 local.yaml modules 块，对 nodejs 子模块 tryLink main 的 node_modules。
+  const modulePaths = extractModulePaths(yamlText);
+  const moduleResults = [];
+  for (const mp of modulePaths) {
+    const wtDir = join(worktreePath, mp);
+    const mainDir = mainCwd ? join(mainCwd, mp) : null;
+    if (!existsSync(wtDir) || !mainDir || !hasNodeMarker(wtDir)) continue;
+    moduleResults.push({ path: mp, ...linkOneDir(wtDir, mainDir) });
   }
 
-  // 兜底：install
-  const installResult = tryInstall(installCmd, worktreePath, timeout);
-  if (installResult.ok) {
-    return { depsStatus: 'installed', depsMethod: 'install', depsSource: 'install', depsLockHash: wtHash, depsCheckedAt };
+  if (moduleResults.length > 0) {
+    result.depsModules = moduleResults;
+    const linkedModules = moduleResults.filter(m => m.status === 'linked');
+    if (linkedModules.length > 0 && result.depsStatus === 'n/a') {
+      // 标 generic 但子模块 link 成功 → 升级为 linked（deps gate 不再误判 unknown 阻断 execute）
+      result.depsStatus = 'linked';
+      result.depsMethod = linkedModules[0].method;
+      result.depsSource = 'main-checkout';
+    }
+    const failedModules = moduleResults.filter(m => m.status === 'failed');
+    if (failedModules.length > 0) {
+      const fmsg = failedModules.map(m => `${m.path}: ${m.error}`).join('; ');
+      result.depsError = result.depsError ? `${result.depsError}; ${fmsg}` : fmsg;
+    }
   }
-  return {
-    depsStatus: 'failed',
-    depsMethod: null,
-    depsSource: null,
-    depsLockHash: wtHash,
-    depsCheckedAt,
-    depsError: installResult.error,
-  };
+
+  return result;
 }