sillyspec 3.25.9 → 3.25.11

package/src/stages/cmd-existence.js

@@ -0,0 +1,145 @@
+/**
+ * cmd-existence.js — 共享命令存在性校验 helper（H2）
+ *
+ * 抽自 scan-postcheck.js:118-158 的 `npm run <script>` 存在性判定，扩展到 pnpm/yarn，
+ * 并感知 monorepo 子目录（`cd <subdir> &&` 前缀 或 local.yaml `modules` 块定位）。
+ *
+ * 严重度由调用方决定（D-04 同 helper 双严重度）：
+ *   - scan-postcheck 调用时维持 warning（local.yaml 命令误报不阻断 init）
+ *   - plan-postcheck 调用时升 error（plan 阶段命令更结构化可硬阻断）
+ *
+ * 仅校验 `npm|pnpm|yarn run <script>` 这一类可静态对账的命令；
+ * install / typecheck / npx / uv run 等直接包管理器调用不在范围（沿用 scan-postcheck:126-129 注释立场）。
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+// 提取 `npm|pnpm|yarn run <script>` 命令。
+// 对齐 scan-postcheck:136 的 `/npm run (\S+)/g`，扩展包管理器 + 容忍多空白。
+// 捕获组 1 = 包管理器（npm|pnpm|yarn），捕获组 2 = script 名。
+const SCRIPT_CMD_RE = /(npm|pnpm|yarn)\s+run\s+(\S+)/g
+
+// 识别紧贴命令前的 `cd <subdir> &&` 前缀（anchored at end of the slice before the command）。
+// subdir token 不含空白与 & ; | 等分隔符；末尾的 `&&` 可带任意空白后接命令。
+const CD_PREFIX_RE = /cd\s+([^\s&;|()]+)\s*&&\s*$/
+
+/**
+ * 读取 package.json 的 scripts 字段。
+ * @param {string} pkgPath
+ * @returns {{ status: 'ok'|'missing'|'unreadable'|'no-scripts', scripts: object|null }}
+ *   - ok          : 文件存在且 JSON 解析成功，含 scripts 对象
+ *   - missing     : 文件不存在
+ *   - unreadable  : 文件存在但 JSON 解析失败（与 scan-postcheck:147 try/catch 一致，不抛）
+ *   - no-scripts  : 解析成功但无 scripts 字段（视作 script 不存在）
+ */
+function readScripts(pkgPath) {
+  if (!existsSync(pkgPath)) return { status: 'missing', scripts: null }
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    if (pkg && typeof pkg === 'object' && pkg.scripts && typeof pkg.scripts === 'object') {
+      return { status: 'ok', scripts: pkg.scripts }
+    }
+    return { status: 'no-scripts', scripts: null }
+  } catch {
+    return { status: 'unreadable', scripts: null }
+  }
+}
+
+/**
+ * 为单条命令计算候选 package.json 路径列表。
+ *
+ * 规则（blueprint task-02 + design §5 H2）：
+ *   - 有 `cd <subdir> &&` 前缀 → 仅查 `<projectRoot>/<subdir>/package.json`（cd 锁定子目录，不回退根）
+ *   - 无前缀 + modules 块提供 → 查每个 module.path 的子包 + 根 package.json（多候选任一命中即视为存在）
+ *   - 无前缀 + 无 modules → 仅查 `<projectRoot>/package.json`
+ *
+ * @param {string} text 全文
+ * @param {number} matchIndex 当前命令在 text 中的起始位置
+ * @param {string} projectRoot
+ * @param {object|null|undefined} modules local.yaml modules 块（{ name: { path, test } }）
+ * @returns {string[]} 候选 package.json 绝对路径列表（至少 1 个）
+ */
+function resolveCandidates(text, matchIndex, projectRoot, modules) {
+  const before = text.slice(0, matchIndex)
+  const cdMatch = before.match(CD_PREFIX_RE)
+  if (cdMatch) {
+    const subdir = cdMatch[1].replace(/^["']|["']$/g, '')
+    return [join(projectRoot, subdir, 'package.json')]
+  }
+  if (modules && typeof modules === 'object') {
+    const candidates = []
+    for (const [, mod] of Object.entries(modules)) {
+      if (mod && typeof mod === 'object' && typeof mod.path === 'string' && mod.path.trim() !== '') {
+        candidates.push(join(projectRoot, mod.path, 'package.json'))
+      }
+    }
+    candidates.push(join(projectRoot, 'package.json'))
+    return candidates
+  }
+  return [join(projectRoot, 'package.json')]
+}
+
+/**
+ * 校验文本中所有 `npm|pnpm|yarn run <script>` 命令在 package.json scripts 中存在（monorepo 感知）。
+ *
+ * @param {string} text 待校验文本（local.yaml 内容 / TaskCard verify+implementation 字段等）
+ * @param {{ projectRoot: string, modules?: object|null }} opts
+ *   - projectRoot : 项目根目录绝对路径
+ *   - modules     : local.yaml modules 块（可选），结构如 `{ frontend: { path: "frontend/", test: "..." } }`
+ * @returns {{ invalid: Array<{ cmd: string, reason: string }>, checked: number }}
+ *   - invalid : 找不到 script 的命令列表，每项含 { cmd, reason }；reason 区分
+ *               「package.json 不存在」「package.json 解析失败」「package.json 无 <script> script」
+ *   - checked : 从 text 提取到的命令总数（含合法与非法）
+ */
+export function validateScriptCommands(text, { projectRoot, modules } = {}) {
+  const invalid = []
+  if (!text || typeof text !== 'string') {
+    return { invalid, checked: 0 }
+  }
+
+  const matches = [...text.matchAll(SCRIPT_CMD_RE)]
+  const checked = matches.length
+
+  for (const m of matches) {
+    const pm = m[1]
+    const scriptName = m[2]
+    const cmd = `${pm} run ${scriptName}`
+
+    const candidates = resolveCandidates(text, m.index ?? 0, projectRoot, modules)
+
+    let found = false
+    let existedAny = false // 至少一个候选文件存在且可解析（ok 或 no-scripts）
+    let parseFailedAny = false // 至少一个候选文件解析失败（unreadable）
+    for (const pkgPath of candidates) {
+      const result = readScripts(pkgPath)
+      if (result.status === 'ok') {
+        existedAny = true
+        if (Object.prototype.hasOwnProperty.call(result.scripts, scriptName)) {
+          found = true
+          break
+        }
+      } else if (result.status === 'no-scripts') {
+        existedAny = true
+        // scripts 字段缺失 → 该候选肯定不含此 script，继续看其他候选
+      } else if (result.status === 'unreadable') {
+        parseFailedAny = true
+      }
+      // missing → 既不算 existed 也不算 parseFailed
+    }
+
+    if (!found) {
+      let reason
+      if (!existedAny && parseFailedAny) {
+        reason = `package.json 解析失败: ${candidates.join(', ')}`
+      } else if (!existedAny) {
+        reason = `package.json 不存在: ${candidates.join(', ')}`
+      } else {
+        reason = `package.json 无 ${scriptName} script`
+      }
+      invalid.push({ cmd, reason })
+    }
+  }
+
+  return { invalid, checked }
+}

package/src/stages/doctor.js

@@ -63,15 +63,21 @@ if [ ! -f "$DB_FILE" ]; then echo "⚠️ sillyspec.db 不存在"; exit 0; fi
 node -e "
 const fs = require('fs');
 const dir = '.sillyspec/changes';
-if (!fs.existsSync(dir)) { console.log('ℹ️ changes/ 目录不存在'); process.exit(0); }
-const subs = fs.readdirSync(dir).filter(f => fs.statSync(dir+'/'+f).isDirectory());
-if (subs.length === 0) { console.log('ℹ️ 无变更目录'); process.exit(0); }
+const subs = fs.existsSync(dir) ? fs.readdirSync(dir).filter(f => { try { return fs.statSync(dir+'/'+f).isDirectory(); } catch { return false; } }) : [];
 const { execSync } = require('child_process');
 let known;
 try { const rows = execSync('sqlite3 -json \".sillyspec/.runtime/sillyspec.db\" \"SELECT name FROM changes WHERE status=\\\"active\\\"\"', {encoding:'utf8'}).trim(); known = new Set(JSON.parse(rows).map(r => r.name)); } catch { known = new Set(); }
 subs.forEach(s => {
   console.log(known.has(s) ? '✅ ' + s + ' — 已关联' : '⚠️ ' + s + ' — 孤儿目录（可清理）');
 });
+// 反向检查（multi-agent-review Q1）：DB active 且匹配 quick-<hex> 但无目录 → 僵尸 quick 会话
+// （quick 收尾未注销，active 行累积污染 listChanges/doctor）。新代码已修收尾，此项清理历史残留。
+const QUICK_RE = /^quick-[0-9a-f]{8}$/;
+const zombieQuick = [...known].filter(n => QUICK_RE.test(n) && !subs.includes(n));
+if (zombieQuick.length > 0) {
+  console.log('⚠️ 检测到 ' + zombieQuick.length + ' 个僵尸 quick 会话（DB active 但无目录）:');
+  zombieQuick.forEach(n => console.log('   - ' + n));
+}
 "
 \`\`\`
 
@@ -131,9 +137,6 @@ else
   echo ""
   echo "ℹ️ sillyspec.db 不存在（尚未初始化）"
 fi
-else
-  echo "ℹ️ gate-status.json 不存在（尚未进入 execute 阶段）"
-fi
 \`\`\`\n
 ### 输出
 汇总所有检查结果，按以下格式：

package/src/stages/execute.js

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, readdirSync } from 'fs'
 import path from 'path'
 import { buildContractMatrix, buildConsumerInjection, buildContractFieldInjection } from '../contract-matrix.js'
 import { getRule } from '../stage-contract-spec.js'
+import { renderDispatchInstruction } from '../dispatch/strategy.js'
+import { isPathASupported } from '../dispatch/backends/sillyhub-mcp.js'
 
 /**
  * 校验 plan.md 是否满足 execute 执行契约
@@ -163,6 +165,7 @@ const fixedPrefix = [
 1. 运行 \`sillyspec worktree meta <change-name>\` 读取 meta.json
 2. 从输出中提取 worktreePath、branch、mode 字段
 3. 确认 worktree 目录存在（如果是 worktree/native-worktree 模式）
+4. **确认工具链可用**：worktree 内项目工具链（lint/format/test 二进制，如 ruff / prettier / uv）可能不全——对本次会用到的工具先跑一次 \`--version\` 确认；缺失则按项目方式安装（Python 项目 \`uv tool install ruff\` / \`uv sync\`，Node 项目 node_modules 已由 CLI 链接主仓）。不要等到 commit 才发现二进制不在 PATH 被 hook 拦
 
 ### 铁律
 - **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
@@ -173,7 +176,7 @@ const fixedPrefix = [
 ### 输出
 worktree 路径 + 分支名 + 模式
 
-"`,
+`,
     outputHint: 'worktree 路径 + 分支名 + 模式',
     optional: false
   },
@@ -183,17 +186,9 @@ worktree 路径 + 分支名 + 模式
 
 ### 操作
 1. 从 plan 中解析 Wave 分组和任务列表
-2. 根据任务描述关键词为每个 Task 建议模型：
-   - 架构/复杂推理 → 最强模型
-   - 常规实现 → 中等模型
-   - 简单修改 → 快速模型
-   - 文档/写作 → 写作模型
-3. 用户在 tasks.md 中的 [model:xxx] 标签优先
-4. 读取 \`--confirm-mode\` 参数（由 CLI 传入，不需要询问用户）：
-   - wave — 每个 Wave 完成后展示结果（默认）
-   - task — 每个 Task 完成后展示结果
-   - auto — 全部自动执行
-5. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
+2. 模型档位：若 tasks.md 中某 task 标注了 [model:xxx]，启动该 task 子代理时按标签选模型（档位由 plan 阶段或用户在 tasks.md 显式标注，execute 不在此自动建议——关键词→档位无统一映射，自动建议反而易误导）
+3. 确认频率：默认每个 Wave 完成后展示结果（wave 模式）；用户口头指定按 Task 展示或全自动时遵从
+4. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
 
 ### 知识命中报告
 {KNOWLEDGE_HIT_REPORT}
@@ -202,8 +197,7 @@ worktree 路径 + 分支名 + 模式
 如无命中条目（Status: no matches），跳过本节。
 
 ### 铁律
-- **不要询问用户确认频率**，确认模式由 CLI \`--confirm-mode\` 参数决定
-- 如果未检测到 \`--confirm-mode\`，默认使用 wave 模式`,
+- **不要询问用户确认频率**，默认 wave 模式；用户已明确口头指定时遵从其指定`,
     outputHint: 'Wave 分组 + 模型分配',
     optional: false
   }
@@ -245,10 +239,13 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 ### 操作
 1. 读取 local.yaml 获取构建和测试命令
 2. 运行测试套件（单元测试、集成测试）
-3. 运行 lint 检查
+3. 运行 lint 检查 **+ 格式化**：凡变更涉及的源码，既跑 lint check 也跑 formatter（如 \`ruff format\` / \`prettier --write\` / \`black\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截
 4. 如果有测试失败 → 分析原因，标注是代码问题还是测试本身的问题
 5. 汇总测试结果
 
+### 铁律
+- 长测试/构建/lint 命令必须**前台同步执行**，禁止 run_in_background:true / & / nohup / disown——后台任务易被会话生命周期回收导致中断无果
+
 ### 输出
 测试结果摘要：通过/失败/跳过数量 + 失败项分析`,
     outputHint: '测试结果摘要',
@@ -286,7 +283,7 @@ const fixedSuffix = [
     prompt: `检查本轮执行产生的新知识。
 
 ### 操作
-1. 检查 \.sillyspec/knowledge/uncategorized.md\` 中待确认条目
+1. 检查 \`.sillyspec/knowledge/uncategorized.md\` 中待确认条目
 2. 如有 → 提示用户审阅
 3. 用户确认后改为 [已确认]，可归类到专题文件
 
@@ -445,10 +442,27 @@ function parseWavesFromPlan(planContent) {
   return waves
 }
 
+/**
+ * 同步判定派发后端模式（不发网络，零回归关键）— task-07
+ *
+ * stub 下 isPathASupported()=false → 有配置也只 local-fallback（加提示），不注入完整 SillyHub 指令。
+ * 现有测试套件都不设 SILLYHUB_MCP_URL/TOKEN → 默认返回 'local' → buildWavePrompt 不注入派发段，
+ * 输出与改前字节一致（零回归，D-005）。
+ *
+ * @returns {'local' | 'local-fallback' | 'sillyhub'}
+ *   - local：无 MCP 配置（零回归，与现状一致）
+ *   - local-fallback：有配置但路径A 未落地（isPathASupported()=false），派发仍走 Local + 短提示
+ *   - sillyhub：有配置且路径A 落地（isPathASupported()=true），注入完整 SillyHub 派发指令
+ */
+export function getDispatchMode() {
+  const hasConfig = !!(process.env.SILLYHUB_MCP_URL && process.env.SILLYHUB_MCP_TOKEN)
+  if (!hasConfig) return 'local'
+  return isPathASupported() ? 'sillyhub' : 'local-fallback'
+}
 /**
  * 为 Wave 生成 prompt（强制子代理执行）
  */
-function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
+export function buildWavePrompt(wave, waveIndex, changeDir, worktreePath, options = {}) {
   // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
   let contractInjection = ''
   let prototypeInjection = ''
@@ -563,6 +577,32 @@ ${prototypes.map(p => `- \`${path.join(protoRelDir, p)}\``).join('\n')}
 `
     : ''
 
+  // ── 派发后端段注入（task-07，D-006 / D-007 / D-008 接入）──
+  // 同步判定（不发网络，零回归关键）：local（无 MCP 配置）→ dispatchSection='' → 本 prompt 与改前
+  // 字节一致；sillyhub（配置 + 路径A 落地）→ 注入完整 SillyHub 派发指令（一 Wave 一 mission /
+  // dispatch_worker / 轮询 list_workers / 超时 kill lease 防双写 / 回收 + Local 兜底）；local-fallback
+  // （配置但路径A 未落地）→ 短提示，派发仍走 Local（与默认行为一致）。worktreePath 为空时不注入
+  // （无 worktree 无谓派发指令）。测试/调用方可经 options.dispatchMode 覆盖，避免 env 污染。
+  const dispatchMode = options.dispatchMode || getDispatchMode()
+  let dispatchSection = ''
+  if (worktreePath && dispatchMode === 'sillyhub') {
+    // 路径A 落地后：注入完整 SillyHub 派发指令（renderDispatchInstruction 已含 Local 兜底全文）
+    const contract = {
+      brief: '本 Wave 任务（见上方任务摘要与 tasks/task-XX.md）',
+      worktreePath,
+      branch: options.branch || '<未提供 branch>',
+      allowedPaths: [],
+      readOnly: false,
+      runId: '{EXECUTE_RUN_ID}',   // 占位符，prompt.js 注入阶段替换为真实 run id
+    }
+    const { instruction } = renderDispatchInstruction(contract, { available: true })
+    dispatchSection = `\n### 派发后端：SillyHub MCP（探测可用，一 Wave 一 mission）\n\n本次 Wave 派发经 SillyHub MCP。按以下派发指令执行（含 create_mission / dispatch_worker / 轮询 list_workers / 超时 kill lease 防双写 / 回收 + Local 兜底）：\n\n${instruction}\n`
+  } else if (worktreePath && dispatchMode === 'local-fallback') {
+    // 有 MCP 配置但路径A 未落地：加短提示，派发仍走 Local（与默认行为一致）
+    dispatchSection = `\n### 派发后端提示：SillyHub MCP 已配置但路径A 未落地\n\n检测到 \`SILLYHUB_MCP_URL\`/\`SILLYHUB_MCP_TOKEN\`，但 SillyHub \`dispatch_worker\` 尚不支持 \`worktree_path\`（路径A 跨仓未落地）。本次派发走 Local（本机 Agent tool），与默认行为一致——上方「执行方式」与「工作目录」段适用。\n`
+  }
+  // dispatchMode === 'local'（无配置）或 worktreePath 为空 → dispatchSection = '' → 输出与改前字节一致（零回归）
+
   return `## Wave ${waveIndex}: 执行以下任务
 
 ## 执行方式（必须严格遵守）
@@ -575,7 +615,7 @@ ${prototypes.map(p => `- \`${path.join(protoRelDir, p)}\``).join('\n')}
 3. 勾选 plan.md 中的 checkbox
 4. 记录改动文件和测试结果
 
-${worktreeSection}
+${worktreeSection}${dispatchSection}
 ### 任务摘要（按需读取完整蓝图）
 为每个任务启动子代理时，**只需告知任务目标和蓝图文件路径，让子代理按需读取**：
 
@@ -616,6 +656,7 @@ ${taskList}
    - 用户明确要求编译时
 4. 每个任务完成后：
    - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
+   - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
    - 记录改动文件和测试结果
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
 
@@ -654,7 +695,7 @@ task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-X
    - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
    - 将端点清单写入 {SPEC_ROOT}/.runtime/contract-artifacts/<task-name>/endpoints.json
    - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
-"`
+`
 }
 
 /**
@@ -690,7 +731,7 @@ export function buildExecuteSteps(planFilePath = null, options = {}) {
   const waveSteps = waves.map((wave, i) => ({
     name: `Wave ${i + 1} 执行`,
     mode: 'implementation',
-    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath),
+    prompt: buildWavePrompt(wave, i + 1, changeDir, worktreePath, { dispatchMode: options.dispatchMode, branch: options.branch }),
     outputHint: `Wave ${i + 1} 执行结果`,
     optional: false
   }))

package/src/stages/plan-postcheck.js

@@ -18,6 +18,7 @@ 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'
+import { validateScriptCommands } from './cmd-existence.js'
 
 // ═══════════════════════════════════════════════════════════════
 // 解析工具（从 plan.js 迁移）
@@ -417,6 +418,100 @@ export function validateCrossTaskContracts(changeDir) {
   return { ok: errors.length === 0, errors, warnings }
 }
 
+/**
+ * 从 local.yaml 文本解析 modules 块（monorepo 子包定位）。
+ *
+ * 与 verify-postcheck.extractModules 同风格（轻量行扫描，不引 yaml 依赖），不复用是为避免
+ * plan-postcheck → verify-postcheck → contract-matrix → plan-postcheck 的循环导入。
+ * 只取 path 字段（test 字段此处用不到），结构 { name: { path } }。
+ *
+ *   modules:
+ *     backend: { path: "backend/", test: "cd backend && uv run pytest" }
+ *
+ * @param {string} yamlText
+ * @returns {Record<string, {path:string}>|null} 无 modules 块或无有效条目 → null
+ */
+export function parseLocalYamlModules(yamlText) {
+  if (!yamlText) return null
+  const lines = yamlText.split('\n')
+  let startIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (/^modules:\s*(?:#.*)?$/.test(lines[i])) { startIdx = i; break }
+  }
+  if (startIdx === -1) return null
+  const modules = {}
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i]
+    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 rest = entry[2] || ''
+    // path 值：带引号或不带引号（flow mapping），取第一个匹配
+    const pathMatch = rest.match(/path:\s*"([^"]+)"/) || rest.match(/path:\s*([^,\s}]+)/)
+    if (pathMatch) modules[entry[1]] = { path: pathMatch[1] }
+  }
+  return Object.keys(modules).length > 0 ? modules : null
+}
+
+/**
+ * TaskCard 命令存在性校验器（调共享 validateScriptCommands，硬阻断）。
+ *
+ * 修复场景（design D-04 / 问题 3）：TaskCard verify/implementation 写 `pnpm gen:types`
+ * 但根 package.json 无此 script（实际在 monorepo 子包 packages 目录下），plan 阶段零校验
+ * → execute 子代理跑死命令。scan-postcheck 的命令校验只看 local.yaml 且维持 warning；
+ * 本函数对 TaskCard 升 error（同 helper、严重度由调用方定）。
+ *
+ * modules 从 local.yaml 提取（monorepo 子包感知）：无 modules 块时仅查根 package.json
+ * （与 scan-postcheck 历史行为一致）；有 modules 块时多候选子包 package.json 任一命中即通过。
+ *
+ * @param {string} changeDir - 变更目录
+ * @param {string} projectRoot - 项目根目录（package.json 查找基准）
+ * @param {object|null} modules - local.yaml modules 块（{ name: { path } }），可选
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateTaskCommands(changeDir, projectRoot, modules = null) {
+  const errors = []
+  const warnings = []
+
+  const tasksDir = pJoin(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) {
+    return { ok: true, errors, warnings }
+  }
+  const taskFiles = readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))
+  if (taskFiles.length === 0) {
+    return { ok: true, errors, warnings }
+  }
+
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    const taskId = parseTaskId(content, file) || file
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+    if (!fmMatch) continue // feasibility 已报 frontmatter 缺失，不重复
+    let fm
+    try {
+      fm = jsYaml.load(fmMatch[1]) || {}
+    } catch {
+      continue // 非法 YAML 由 feasibility 处理，不重复
+    }
+
+    // 合并 verify + implementation 文本（命令可能出现在任一字段）
+    const verifyText = typeof fm.verify === 'string' ? fm.verify : ''
+    const implText = typeof fm.implementation === 'string' ? fm.implementation : ''
+    const text = `${verifyText}\n${implText}`
+    if (!text.trim()) continue
+
+    const { invalid } = validateScriptCommands(text, { projectRoot, modules })
+    for (const inv of invalid) {
+      errors.push(`${taskId}: ${inv.cmd} 命令不存在（${inv.reason}）`)
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
 // 路径容差匹配（normalizePath / globMatch / pathMatches）复用自 change-list.js，
 // design 清单解析与 allowed_paths 对账共用同一套匹配语义，避免两处逻辑漂移。
 
@@ -571,6 +666,44 @@ export function validatePlanFeasibility(changeDir, projectRoot = null) {
     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))
+
+    // 6. acceptance best-effort 字段 grep（D-05 软约束，warning 不阻断）
+    // 从 acceptance 文本提取 snake_case/camelCase 标识符，grep allowed_paths 指向的源文件；
+    // 找不到 → warning（给 LLM 审查提线索，不阻断 execute）。宁漏不噪：只取 snake/camel，
+    // 正则天然避开命令（无 _ 或大写）/路径（无 /）/中文；glob allowed_path / 目录 / 不存在文件一律跳过。
+    if (projectRoot && hasAcceptance && allowedPaths.length > 0) {
+      let acceptanceText = ''
+      try {
+        const fmObj = jsYaml.load(fm) || {}
+        if (typeof fmObj.acceptance === 'string') acceptanceText = fmObj.acceptance
+        else if (Array.isArray(fmObj.acceptance)) acceptanceText = fmObj.acceptance.join('\n')
+      } catch {
+        // frontmatter 非法 YAML（feasibility 未对 fm 做 YAML 解析，可能字面合法但语义复杂）→ 跳过 best-effort
+      }
+      if (acceptanceText) {
+        const IDENT_RE = /(?<![A-Za-z])[a-z]+(?:_[a-z]+)+|(?<![A-Za-z])[a-z]+(?:[A-Z][a-z]+)+/g
+        const idents = [...new Set(acceptanceText.match(IDENT_RE) || [])]
+        if (idents.length > 0) {
+          const readableFiles = []
+          for (const ap of allowedPaths) {
+            if (ap.includes('*')) continue // glob，跳过（best-effort，不展开）
+            try {
+              readableFiles.push(readFileSync(pJoin(projectRoot, ap), 'utf8'))
+            } catch {
+              // 目录 / 不存在 / 不可读 → 跳过（feasibility 3 已对不存在文件提示 warning）
+            }
+          }
+          // 至少读到一个源文件才比对，避免「全没读到 → 全部标识符误报」噪声
+          if (readableFiles.length > 0) {
+            for (const ident of idents) {
+              if (!readableFiles.some(c => c.includes(ident))) {
+                warnings.push(`${taskId}: acceptance 提到 ${ident} 但 allowed_paths 源文件未命中`)
+              }
+            }
+          }
+        }
+      }
+    }
   }
 
   // 4b. depends_on 引用存在性
@@ -711,6 +844,25 @@ export async function executePlanPostcheck(context) {
     throw new Error('planPostcheck: cross-task contract check failed')
   }
 
+  // ── 1c-b. TaskCard 命令存在性校验 ──
+  // TaskCard verify/implementation 的 `npm|pnpm|yarn run <script>` 必须在 package.json
+  // scripts 中存在（monorepo 子包感知——读 local.yaml modules 块定位）。
+  // invalid → error 硬阻断，避免 execute 子代理跑死命令（design D-04 / 问题 3）。
+  // modules 块可选：无块时仅查根 package.json（与 scan-postcheck 历史行为一致）。
+  const localYamlPath = pJoin(specDir, 'local.yaml')
+  let taskModules = null
+  if (existsSync(localYamlPath)) {
+    taskModules = parseLocalYamlModules(readFileSync(localYamlPath, 'utf8'))
+  }
+  const taskCmds = validateTaskCommands(changeDir, context.cwd, taskModules)
+  if (taskCmds.errors.length > 0) {
+    console.error('\n❌ TaskCard 命令存在性校验失败（verify/implementation 的 npm/pnpm/yarn run <script> 不存在）：')
+    for (const err of taskCmds.errors) console.error(`   - ${err}`)
+    console.error('\n   修复方式：要么在 package.json scripts 补上缺失命令（monorepo 注意子包路径），')
+    console.error('   要么修正 TaskCard 的 verify/implementation（确认命令是否真实、是否需 cd 子包）。')
+    throw new Error('planPostcheck: task command existence check failed')
+  }
+
   // ── 1d. design 文件覆盖对账 ──
   // design.md 清单中的每个源码文件必须被某 task 的 allowed_paths 覆盖，
   // 否则 execute 子代理无权改它 → 漏改（典型表现：「页面还是错的」）。

package/src/stages/plan.js

@@ -198,7 +198,7 @@ light 计划的约束：
 - **禁止**泛泛风险分析（如"需要充分测试"）
 - **禁止**放实现细节（函数签名、代码示例）
 - 来源/目标直接引用已有文档，不重新生成
-- 如果存在 decisions.md，所有当前版本 D-xxx@vN 必须在 Tasks 或覆盖矩阵中出现
+- 如果存在 decisions.md，所有当前版本 D-xxx@vN 必须在 Tasks 或覆盖矩阵中出现（CLI 只校验 D-xxx@vN ID 字面出现在 plan.md，warning 不阻断；矩阵结构供人类追溯，CLI 不校验 D→FR→task 映射完整性）
 - 如果存在 P0/P1 unresolved blocker，不生成 plan.md
 - 任务列表控制在 10 条以内
 - **任务必须使用 checkbox 格式**（\`- [ ] task-XX:\`），不要用纯编号列表（\`1. 2.\`），execute 阶段依赖此格式解析任务
@@ -256,7 +256,7 @@ full 计划的约束：
 - Mermaid 依赖关系图**仅当依赖关系非平凡时生成**（线性依赖或全并行时不生成）
 - **Wave 下的 checkbox 行必须保留**（execute 阶段解析依赖 \`- [ ] task-XX:\` 格式）
 - plan.md 包含 Wave 分组 + 任务总表 + 关键路径 + 全局验收标准，**不放实现细节**
-- 如果存在 decisions.md，plan.md 必须包含当前版本 D-xxx@vN/FR-xxx 覆盖矩阵
+- 如果存在 decisions.md，plan.md 建议包含当前版本 D-xxx@vN/FR-xxx 覆盖矩阵（CLI 只校验 D-xxx@vN/FR-xxx ID 字面出现在 plan.md，warning 不阻断；矩阵的 D→FR→task 映射完整性供人类追溯，CLI 不校验——勿以为画了矩阵就被结构校验）
 - 如果存在 P0/P1 unresolved blocker，不生成 plan.md，输出阻塞清单
 - 实现细节写到后续的 tasks/task-NN.md 中
 - 每个任务编号格式：task-01、task-02 ...
@@ -308,8 +308,17 @@ plan_level + 计划内容（审查在下一步独立进行）`,
 const stepReviewPlan = {
   id: 'review_plan',
   name: '审查计划',
+  conditionalWait: true,
+  waitReason: '等待用户确认计划后进入执行',
+  waitOptions: ['确认，进入执行', '需要调整'],
   prompt: `对上一步生成的 plan.md 做审查。生成与审查分离——不在生成 plan 的同一上下文里自审，避免确认偏差。
 
+### 执行前确认门（plan_level=full 时）
+plan.md 审查通过后、进入 execute 前，若 plan_level=full（跨模块/大变更），必须先向用户展示计划摘要并等待确认，不要让 AI 默认共识擅自开工：
+- 展示：Wave 分组 + task 总数 + 关键 allowed_paths 边界 + 依赖说明（一两屏内，不贴全文）
+- 调用：\`sillyspec run plan --wait --reason "等待用户确认计划" --options "确认，进入执行,需要调整" --output "计划摘要"\`
+- 用户确认后再 --done；plan_level=none/light（小变更）无需等待，正常完成即可
+
 ### 当前审查分级（CLI 按变更规模判定，占位符由 run.js 注入）
 tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 - tier=self：当前 agent 直接执行下方审查清单（小变更，独立审查仪式成本 > 收益）
@@ -323,7 +332,8 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
 - [ ] 不存在 P0/P1 unresolved blocker 残留
 - [ ] 没有实现细节泄漏到 plan.md（接口签名/代码示例应在 tasks/task-NN.md）
 - [ ] 关键路径与 Wave 依赖合理（无循环依赖、无遗漏前置）
-- [ ] 连带测试归属：改共享/被多 task 依赖源文件的 task 是否在 related_tests 声明了会失效的既有测试、且路径在 allowed_paths 内（或由独立测试 task 覆盖）？（漏声明 = execute 阶段测试债、主代理事后兜底）
+- [ ] 连带测试归属：本批改动是否会导致既有测试断言失效（改共享/被多 task 依赖源文件、改被测试精确匹配的值如 UI 文案/按钮文本/错误信息/常量/枚举字面量、改函数签名或返回结构等单文件场景）？此类 task 是否在 related_tests 声明了失效测试、且路径在 allowed_paths 内（或由独立测试 task 覆盖）？（漏声明 = execute 阶段测试债、主代理事后兜底）
+- [ ] acceptance 字段对照实际 schema/类型源文件核验存在性与形态，不凭 design.md 文字臆断（plan-postcheck best-effort grep 会给 allowed_paths 源文件未命中的 snake_case/camelCase 标识符提 warning，此处是语义层复查；臆断 = execute 阶段返工）
 
 ### tier=independent 时：启动 plan-review 子代理
 用 Agent tool 启动子代理（subagent_type: general），prompt 要点：
@@ -403,37 +413,12 @@ verify:
 constraints:
   - 边界约束 1（如：不加测试）
   - 边界约束 2（如：不修改传入参数）
-related_tests:                           # 可选。仅当本 task 改共享/被多 task 依赖的源文件时填
+related_tests:                           # 可选。当本 task 改动会导致既有测试断言失效时填（共享源文件/UI文案/常量/签名变更等，判据=测试是否失败非文件是否共享）
   - path: frontend/src/lib/errors.test.ts # 因本次改动断言失效的既有测试文件
     reason: 旧断言假设单例，改归属键后需同步
 ---
 
-TaskCard 格式规则（必须严格遵守）：
-- 总长度 20~40 行，不要写成长文档
-- frontmatter 只含必要字段，不加 estimated_hours
-- goal: 一句话，用 > 多行字符串
-- implementation: 列表，每条一个具体步骤
-- acceptance: 列表，每条可独立验证（不是表格）
-- verify: 列表，实际可执行的命令
-- constraints: 列表，明确边界（含 brownfield 兼容、异常处理）
-- 不需要：修改文件章节、覆盖来源章节、接口定义章节、TDD 步骤章节、参考章节
-- frontmatter 必须以三减号结尾闭合（开头和结尾各一行 ---）。缺结尾会让 postcheck 提取不到 frontmatter，误报「字段缺失 / allowed_paths 为空」
-- allowed_paths 用块式写法（键名换行后每项一行「  - 路径」），不要用流式方括号 [path]——块式与所有校验器一致最稳
-- implementation / acceptance / constraints / verify 的每条列表项是 YAML plain scalar，避免以下特殊字符触发 ScannerError：
-  - 冒号+空格（如代码签名 provider_id:str、queryUsage(id:string)）会被当映射键报 mapping values are not allowed here——去掉冒号后空格或改成中文描述
-  - 花括号且内部含冒号或引号（如 JS 对象、JS 模板字面量）会报 expected block end——改用不含这些字符的中文描述
-  - 引号不成对会报扫描错误
-  - 注：goal 用 > 折叠标量可容忍花括号，goal 里写占位符不炸；只有上述 plain scalar 列表项需注意
-- provides / expects_from 是可选字段：仅当跨 task 契约（一个 task 的接口/DTO/响应被另一个 task 消费）时才填，单 task 或无对外接口场景留空即可
-- 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
-- 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状
-- related_tests 是可选字段：仅当本 task 改共享源文件（被既有测试引用、或被多 task 依赖）时填，列出会因本次改动断言失效的既有测试文件 + 为何失效。关键：这些测试路径必须同时写进本 task 的 allowed_paths（否则子代理被 allowed_paths 铁律锁死、改不了测试 → 退化成主代理事后兜底）；若测试由独立的测试 task 负责，则在该测试 task 的 allowed_paths 覆盖、本字段留空
-- 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
-- **保存前格式自检**（plan-postcheck 会硬校验，不通过到 Step 4 会批量报错，先在这里逐条自查）：
-  - frontmatter 字段齐全：id、title、title_zh、author、created_at、priority、depends_on、blocks、allowed_paths、goal、implementation、acceptance、verify、constraints
-  - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
-  - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
-- 写完后用 Write tool 保存到文件
+{{include: taskcard-rules}}
 \`\`\``
   }).join('\n\n')
 
@@ -470,7 +455,7 @@ ${subagentPrompts}
   - allowed_paths 有无冲突
   - depends_on 与 plan.md Wave 分组是否一致
   - provides/expects_from 契约自洽：每个 expects_from[provider].needs 字段都在该 provider task 的 provides.fields 里（plan-postcheck 会硬校验，这里提前自查）
-  - related_tests（若填）的测试路径是否都在本 task 或某 task 的 allowed_paths 内（否则子代理无权改 → execute 测试债、主代理事后兜底）
+  - related_tests 判据 = 是否有既有测试因本次改动而失败（非「源文件是否共享」；UI 文案/常量/签名变更等单文件场景也算）；若填，测试路径必须都在本 task 或某 task 的 allowed_paths 内（否则子代理无权改 → execute 测试债、主代理事后兜底）
   - 如发现矛盾，列出问题清单，不要自动修复`
 
   return {

package/src/stages/quick.js

@@ -10,7 +10,7 @@ export const definition = {
 
 ### 📌 本 quick 会话 sessionId: <quick-session-id>
 - CLI 是短进程，run 与 done 是独立进程，sessionId 靠 --change 跨进程传递
-- **完成每个 step 必须带 --change <quick-session-id>**（命令由 CLI 在下方注入）；多会话并发时不带会命中他者会话状态（不带时 fallback 读 current-quick-run-id，单会话兼容；多会话不可靠）
+- **完成每个 step 必须带 --change <quick-session-id>**（命令由 CLI 在下方注入）；多会话并发时不带会命中他者会话状态
 
 ### 操作
 1. 检查关联变更（\`<linked-changes>\`，逗号分隔的变更名列表；显示「（无）」= 不关联变更），确定记录方式