sillyspec 3.28.0 → 3.28.3

package/src/stages/brainstorm.js

@@ -7,23 +7,13 @@ export const definition = {
       name: '进度确认',
       // 重命名自「状态检查」（③ status 消歧）：老进度里的「状态检查」completed 由迁移逻辑承接，防 currentIdx 回跳
       migratedFrom: ['状态检查'],
-      prompt: `检查当前变更的进度状态（sillyspec.db）。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
-
-### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 "brainstorm"
-3. 如果有进行中的 brainstorm，提示选择继续或重新开始
-4. 如果未初始化，提示先运行 sillyspec init
-5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
-
-### 输出
-当前状态摘要（1-2 句话）
-
-### 注意
-- 以 CLI 返回为准，不要自行推断阶段
-- 如果阶段不对，输出正确提示并停止
-- **不要用 mv 命令重命名变更目录**，必须使用 \`sillyspec change-rename\`，否则 DB 和目录会脱节`,
-      outputHint: '状态摘要',
+      // noAI 化（2026-09-07）：快照本就 CLI 注入、阶段路由由 run 落定、变更名自动生成检测为机械
+      // 正则（命中只打印 rename 建议，agent 在工具结果可见、可在后续步骤交互改名）——省一轮
+      // 复述往返。步骤名保持不变（存量进度库按名匹配迁移）。
+      noAI: true,
+      _cliAction: 'progressConfirm',
+      prompt: '',
+      outputHint: '状态摘要（CLI 快照输出）',
       optional: false
     },
     {
@@ -33,8 +23,10 @@ export const definition = {
 ### 操作
 1. 读取项目总览 \`{SPEC_ROOT}/docs/<project>/scan/PROJECT.md\` + 共享规范 + 子项目上下文
    - 漂移事实（CLI 算）：{SCAN_STALENESS}
+   - 机械事实底稿（CLI 注入，无 scan 底稿则为空）：{SCAN_FACTS}
 2. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`
-3. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`
+3. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 4. 棕地项目：读取 {SPEC_ROOT}/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
 5. **加载模块索引**：读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（如存在）
    - 这一步是高频操作，_module-map.yaml 回答"哪个文件属于哪个模块、模块之间怎么依赖"
@@ -348,7 +340,7 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
 ### 操作
 1. 确认变更目录存在：\`mkdir -p {SPEC_ROOT}/changes/<change-name>\`（Windows 用 \`mkdir {SPEC_ROOT}/changes\\<变更名>\` 或 PowerShell \`New-Item -ItemType Directory -Force -Path {SPEC_ROOT}/changes/<change-name>\`）
    - 变更名格式必须为 \`YYYY-MM-DD-<简短描述>\`（如 \`2026-05-13-user-auth\`）
-2. 将确认的设计写入 \`{SPEC_ROOT}/changes/<change-name>/design.md\`
+2. 将确认的设计写入 \`{SPEC_ROOT}/changes/<change-name>/design.md\`——优先跑 \`sillyspec design-init --change <change-name>\` 生成骨架再填散文（决策追踪表已按 decisions.md 当前版本预填，逐行补覆盖点后把「待确认」改「已覆盖」；文件清单表骨架就位）；存量手写路径仍合法（design-init 对已存在的 design.md 不覆盖）
 3. 对账整理 \`{SPEC_ROOT}/changes/<change-name>/decisions.md\`（「对话式探索」「提出方案」步已按增量规则随答落盘，本步做对账而非从零写入）：
    - decisions.md 是本次变更的决策台账，不是长期术语表
    - 只记录有实现/验收影响的决策，闲聊和低风险偏好不记录
@@ -358,7 +350,7 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - 每条记录必须包含：type、status、source、question、answer、normalized_requirement、impacts、evidence、priority
    - 九字段之外可另加四个可选字段，按需填写、不强制全填（旧格式决策记录缺这些字段不受影响）：
      - 锚点：决策落点的主文件，格式 <src 路径>:<行号或符号>（status=confirmed 时必填）
-     - 模块域：决策涉及的模块 ID，取自 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`，可多个、用逗号分隔
+     - 模块域：决策涉及的模块 ID，取自 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`，可多个、用逗号分隔；规划中的新模块用 NEW:模块名 前缀声明（冒号后不加空格——\`NEW:foo\` 合法、\`NEW: foo\` 属书写错误），「生成规范文件」步 --done 的模块域核验会豁免 NEW 前缀并在模块落地后补录
      - 否决理由：一句话说明为何否决（status=rejected 时必填）
      - 复潮条件：什么前提下可重新考虑该决策（status=rejected 时必填）
    - 长期术语只在 archive/scan 时再提升到 \`{SPEC_ROOT}/docs/<project>/glossary.md\`

package/src/stages/execute.js

@@ -220,17 +220,12 @@ const fixedPrefix = [
   {
     name: '进度确认',
     migratedFrom: ['状态检查'],
-    prompt: `检查当前进度，确认可以执行 execute。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
-
-### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 execute
-3. 如果不是 → 检查是否有未完成的 tasks.md
-4. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
-
-### 输出
-当前状态 + 执行范围确认`,
-    outputHint: '当前状态 + 执行范围',
+    // noAI 化（2026-09-07）：快照复述/阶段检查机械化（progressConfirm 补 tasks 勾选计数）；
+    // 执行范围是会话层信息（$ARGUMENTS 不经 CLI），以用户会话指定为准。步骤名不变。
+    noAI: true,
+    _cliAction: 'progressConfirm',
+    prompt: '',
+    outputHint: '当前状态 + 执行范围（CLI 快照输出）',
     optional: false
   },
   {
@@ -241,7 +236,8 @@ const fixedPrefix = [
 1. 读取 tasks.md（任务注册表与勾选唯一真相；plan.md 只提供 Wave 分组/依赖结构——Wave 段下为纯 ID 引用行）
 2. 读取 design.md（技术方案）
 3. 读取 CONVENTIONS.md、ARCHITECTURE.md
-4. 读取 local.yaml（构建命令）；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+4. 构建命令（CLI 自 local.yaml 注入，勿再读文件；未配置时按注入说明跑 local detect）：
+{LOCAL_COMMANDS}
 5. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）
 
 ### 模块文档加载（细粒度卡优先——CLI 已按 tasks 卡 allowed_paths 级联匹配）
@@ -284,18 +280,19 @@ const fixedPrefix = [
   },
   {
     name: '确认 worktree 路径',
-    prompt: `确认当前 worktree 状态，提取隔离路径。
+    prompt: `确认当前 worktree 状态（meta 已由 CLI 注入，勿再跑 worktree meta）。
+
+### worktree 快照（CLI 注入）
+{WORKTREE_META}
 
 ### 操作
-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 拦。**Python 项目注意**：worktree 自建 .venv 只含 pyproject 声明依赖，pytest 等 dev 工具可能缺失——优先在 worktree 内补装（\`uv sync --group dev\` / \`uv pip install pytest\`），**不要回退用主仓 venv 跑测试**（主仓 venv 加载的可能是主仓代码而非 worktree 代码，环境不一致会掩真 bug）
+1. **确认工具链可用**：worktree 内项目工具链（lint/format/test 二进制，如 ruff / prettier / uv）可能不全——对本次会用到的工具先跑一次 \`--version\` 确认；缺失则按项目方式安装（Python 项目 \`uv tool install ruff\` / \`uv sync\`，Node 项目 node_modules 已由 CLI 链接主仓）。不要等到 commit 才发现二进制不在 PATH 被 hook 拦。**Python 项目注意**：worktree 自建 .venv 只含 pyproject 声明依赖，pytest 等 dev 工具可能缺失——优先在 worktree 内补装（\`uv sync --group dev\` / \`uv pip install pytest\`），**不要回退用主仓 venv 跑测试**（主仓 venv 加载的可能是主仓代码而非 worktree 代码，环境不一致会掩真 bug）
+2. **涉及后端端点的变更拍基线**：跑 \`sillyspec endpoints baseline --change <change-name>\` 拍变更前基线（幂等，已拍过会跳过；在 worktree 内跑即可——CLI 自动把扫描根与落点锚定主仓）——归档时用于计算端点增删
 
 ### 铁律
 - **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
-- **后续所有子代理的 cwd 必须设为该 worktree 路径**
-- 如果 meta.json 不存在（说明创建失败），停止并报错
+- **后续所有子代理的 cwd 必须设为快照中的 worktreePath**
+- 快照显示 meta 不可读（说明创建失败）→ 停止并报错
 - **不要自行检查 git dirty/uncommitted 状态来判断是否可以进入 worktree，CLI 已自动处理**
 
 ### 输出
@@ -354,7 +351,7 @@ tier: {REVIEW_TIER}（{REVIEW_TIER_REASON}）
   3. 组装行为（全量测试/构建/启动通过——单 task 测试全绿 ≠ 组装正确）
 
   **产物唯一化（省重复消耗）**：本步逐项对照结论**只落盘一份**——直接写进 review.json 的 \`checklist\` 数组（item=设计要点/FR/决策，note=实现状态 ✅/⚠️/❌ + 偏差说明 + commit 锚点），reviewerNotes 写汇总。**不要**另写独立的 design-check.md 长文（同一份 design×diff 二次消费；2026-08-22 实测该重复一遍 ≈8 分钟全量重读）。
-  **gate 重试修复**：review.json 落盘后若后续 gate 报 docHash 失配 / 路径错，跑 \`sillyspec register-stage-review --change <变更名> --stage execute --refresh-hash\` 一键重算修复——**不要重做审查**（重做=同一材料第三遍）。
+  **gate 重试修复**：review.json 落盘后若 design.md 又有改版，gate 会**自动机械重算 docHash 放行**（verdict/checklist 保留，结论是否仍适用于新文档需人工确认）——**不要重做审查**（重做=同一材料第三遍）；主文档路径错/缺失不会被自动修复，按 gate 报错修正 reviewedFiles[0]，或跑 \`sillyspec register-stage-review --change <变更名> --stage execute --refresh-hash\`。
 
 ### 操作
 1. 读取 design.md（技术方案）——按章节精准读（design-check 对照表可借 tasks 卡 §锚点定位），避免反复整读全文
@@ -376,7 +373,8 @@ review.json 已落盘（checklist=逐项核验表）+ checklist 摘要与偏差
 本步骤由当前 agent 执行，不需要启动独立子代理。
 
 ### 操作
-1. 读取 local.yaml 获取构建和测试命令；若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
+1. 构建命令（CLI 自 local.yaml 注入，勿再读文件；未配置时按注入说明跑 local detect）：
+{LOCAL_COMMANDS}
 2. 运行测试套件（单元测试、集成测试）
 3. 运行 lint 检查 **+ 格式化**：凡变更涉及的源码，既跑 lint check 也跑 formatter（如 \`ruff format\` / \`prettier --write\` / \`black\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截
 4. 如果有测试失败 → 分析原因，标注是代码问题还是测试本身的问题

package/src/stages/plan-postcheck.js

@@ -94,6 +94,68 @@ export function parseAllowedPaths(content) {
   return []
 }
 
+/**
+ * 解析 task-NN.md frontmatter 的 target_files 字段（对账意图声明，design 总体方案 Wave 1 / X-10）。
+ *
+ * 与 parseAllowedPaths 同族的列表解析（inline [] + 顶格/缩进块列表双形态、CRLF 入口归一），
+ * 但语义相反——**严格模式**：allowed_paths 是 worktree 写入守卫的白名单（目录前缀 / glob /
+ * 引号皆合法、pathMatches 容差匹配）；target_files 是 verify 对账（task-04 reconcileTargetFiles）
+ * 用的逐文件精确意图声明——白名单容差若用于对账，目录前缀会把整目录算成「预期」使 scope
+ * creep 检出恒空（D-002）。故此处不剥引号、不放行通配，非法形态记入 entry.invalid 交
+ * validateTargetFiles 报 ERROR。解析器纯函数无 IO、不 throw——依赖链已核实无环
+ * （verify-postcheck → plan-postcheck 单向），供对账侧跨文件 import 复用。
+ *
+ * 条目格式：`[NEW:]<仓根相对精确文件路径>`，NEW: 前缀 = 当前不存在的待建文件。
+ * 非列表形态（标量 / 未闭合）与 parseAllowedPaths 家族同口径视同未声明（missing），
+ * 走调用方的汇总 WARNING 信号，不在解析器内造第三种状态。
+ *
+ * @param {string} content - task 文件内容（同 parseAllowedPaths：frontmatter 自提取）
+ * @returns {{ entries: Array<{raw: string, isNew: boolean, path: string, invalid: string|null}>, missing: boolean }}
+ *   raw = 条目原文（含 NEW: 前缀）；path = 剥 NEW: 与 ./ 前缀、反斜杠归一正斜杠的路径；
+ *   invalid = 非法形态原因（null = 合法）；missing = 字段缺失或空列表（存量卡兼容口径）
+ */
+export function parseTargetFiles(content) {
+  content = content.replace(/\r\n/g, '\n') // 同 parseAllowedPaths：入口归一，保护喂原始 CRLF 的外部调用方（task-04）
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!fmMatch) return { entries: [], missing: true }
+  const fm = fmMatch[1]
+  let raws = null
+  const inlineMatch = fm.match(/target_files:[ \t]*\[([^\]]*)\]/)
+  if (inlineMatch) {
+    raws = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean)
+  } else {
+    // 块列表 [ \t]*\n 不吃换行（坑6① 家族教训：\s* 贪婪吞顶格列表导致静默判空）
+    const blockMatch = fm.match(/target_files:[ \t]*\n((?:[ \t]*-[ \t]+.+\n?)+)/)
+    if (blockMatch) {
+      raws = blockMatch[1].match(/[ \t]*-[ \t]+(.+)/g)
+        ?.map(s => s.replace(/^[ \t]*-[ \t]+/, '').trim()).filter(Boolean) || []
+    }
+  }
+  if (raws === null || raws.length === 0) return { entries: [], missing: true }
+
+  const entries = raws.map(raw => {
+    let path = raw
+    let isNew = false
+    if (path.startsWith('NEW:')) { isNew = true; path = path.slice('NEW:'.length).trim() }
+    // 路径归一正斜杠（design 数据流标注）——UNC `\\srv\x` 归一后 `//srv/x` 恰落入下方绝对路径判定
+    path = path.replace(/\\/g, '/')
+    // 剥 ./ 前缀（P1 修复，2026-09-07）：声明 `./src/a.js` vs actual `src/a.js` 曾字面失配落②类假红
+    // （normalizeReconcilePath 只归一 actual 侧）——此处的单源归一同时覆盖 plan 校验与 verify 对账。
+    // (\./)+ 贪婪多层：`././src/a.js` 双前缀也归一到层底（对抗复审 Q-1，actual 侧 git 路径永远干净）。
+    path = path.replace(/^(\.\/)+/, '')
+    // 严格形态判定（X-10：每条 = 精确文件路径，禁 glob/目录前缀/引号/绝对路径）。
+    // 只记原因不 throw：解析器供对账复用，非法条目的处置（ERROR）归 plan-postcheck 校验层
+    let invalid = null
+    if (path === '') invalid = '剥 NEW: / ./ 前缀后为空'
+    else if (/[*?]/.test(path)) invalid = '含通配符（* 或 ?）——target_files 须逐文件精确声明，禁 glob（目录级覆盖会令 verify 对账的 scope creep 检出失效）'
+    else if (path.endsWith('/')) invalid = '以 / 结尾（目录前缀）——须精确到文件'
+    else if (/["'`]/.test(path)) invalid = '含引号/反引号——须裸路径书写（严格口径拒容差，防对账字面不匹配）'
+    else if (path.startsWith('/') || /^[A-Za-z]:/.test(path)) invalid = '是绝对路径——须写仓根相对路径'
+    return { raw, isNew, path, invalid }
+  })
+  return { entries, missing: false }
+}
+
 /**
  * 从 task-NN.md frontmatter 解析标量字段（repo / base_commit / head_commit）。
  * 复用 parseTaskContracts 的 frontmatter 提取 + js-yaml load 模式（标量可选字段，正则对引号/空值脆弱）。
@@ -985,6 +1047,122 @@ export function validateDesignFileCoverage(changeDir) {
   return { ok: errors.length === 0, errors, warnings, designFiles, uncovered }
 }
 
+/**
+ * 流程产物前缀（target_files 不该声明的路径域）。
+ * 与 worktree-apply filterDeliverableFiles 同口径硬编码——不 import 复用是因为
+ * worktree-apply → plan-postcheck 已有依赖边（line 21 parseAllowedPaths），反向 import 成环。
+ * 注意 .sillyspec/docs/ 不在此列：dogfood 模块文档 = 交付物（D-2 keepSillyspecDocs），
+ * 声明它是合法的（verify 对账也保留 docs 路径）。
+ */
+const TARGET_FILES_PROCESS_PREFIXES = ['.sillyspec/changes/', '.sillyspec/.runtime/', '.sillyspec/quicklog/']
+
+/**
+ * task 卡 target_files 声明核验器（plan-postcheck 第 7 项检查，P3a Wave 1 / X-10 / X-13）。
+ *
+ * 修复场景（design 背景）：plan 侧「计划动了不存在的文件」类幻觉此前零核验，agent 写出
+ * 幻觉路径要到 execute 子代理落盘失败才暴露。此处逐条机器核验意图声明，把幻觉/格式问题
+ * 拦在 plan --done；同时为 task-04 verify 对账提供可信的声明侧（对账复用 parseTargetFiles）。
+ *
+ * 分级口径：
+ *   ERROR：格式非法（glob/目录前缀/引号/绝对路径——parseTargetFiles.invalid）；幻觉路径
+ *          （repoRoot 下不存在且未加 NEW: 前缀）。
+ *   WARNING（不阻断，存量兼容）：字段缺失**每变更汇总一条**（X-13：每卡一条会被存量卡
+ *          噪音淹没）；已存在文件带 NEW: 前缀（应去前缀）；流程产物路径；越出该卡
+ *          allowed_paths 白名单（提前暴露到 apply Gate1 才发现的越权，X-5）；design 清单外
+ *          路径（声明与 design 漂移提示）；跨仓卡剔除提示（路径相对其声明仓根，主仓核验
+ *          恒假误报，与对账侧 D-004 同口径剔除）。
+ *
+ * fail-open 边界：tasks/ 目录缺失或无卡（同既有检查行为）；design.md 缺失/无清单章节
+ * （缺清单 error 归 validateDesignFileCoverage 把关，不重复）；卡无 allowed_paths
+ * （feasibility 已报 error，跳过交叉防双重噪音）；repoRoot 缺省（纯函数测试场景）跳过存在性。
+ *
+ * @param {string} changeDir - 变更目录（读 tasks/ 卡与 design.md 清单）
+ * @param {string|null} [repoRoot=null] - 主仓根目录（target_files 存在性基准）
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateTargetFiles(changeDir, repoRoot = 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 }
+  }
+
+  // design 清单交叉用清单（双交叉之一）：与 validateDesignFileCoverage 同源解析（含按仓分段、
+  // .sillyspec/docs 交付物口径），design 缺失/无清单 → 空列表 → 交叉自动跳过。检查间不共享
+  // 解析结果（各检查独立只读 changeDir 产物），重复解析是聚合架构的既定代价。
+  const designFiles = parseDesignCoverageByRepo(pJoin(changeDir, 'design.md')).allFiles
+
+  let missingCount = 0
+  for (const file of taskFiles) {
+    const content = readFileSync(pJoin(tasksDir, file), 'utf8')
+    if (!/^---\n([\s\S]*?)\n---/.test(content)) continue // feasibility 已报 frontmatter 缺失，不重复
+    const taskId = parseTaskId(content, file) || file
+    const label = `${taskId} (${file})`
+
+    // 跨仓卡剔除：其 target_files 相对声明仓根，主仓 repoRoot 下 existsSync 恒假 → 全员
+    // 误报幻觉路径。verify 对账（task-04）同口径剔除（D-004），此处只提示不核验
+    const repo = parseRepo(content)
+    if (repo) {
+      warnings.push(`${label}: 跨仓卡（repo: ${repo}）不参与主仓 target_files 核验——跨仓对账不在本变更范围，声明留待后续分期`)
+      continue
+    }
+
+    const { entries, missing } = parseTargetFiles(content)
+    if (missing) { missingCount++; continue }
+
+    const allowedPaths = parseAllowedPaths(content)
+    for (const e of entries) {
+      if (e.invalid) {
+        errors.push(`${label}: target_files「${e.raw}」格式非法——${e.invalid}。修复：改写为仓根相对的精确文件路径；当前不存在的文件加 NEW: 前缀（如 NEW:src/new.js）`)
+        continue
+      }
+      // 流程产物：声明了也对不上账（verify 对账 filterDeliverableFiles 同口径会滤掉），
+      // 且 changes/ 下路径属流程自产文件、不该是对账意图。提示后跳过后续核验（存在性/交叉
+      // 对流程产物无意义，只会叠加噪音）
+      if (TARGET_FILES_PROCESS_PREFIXES.some(p => e.path.startsWith(p)) || e.path === 'meta.json') {
+        warnings.push(`${label}: target_files「${e.raw}」是流程产物路径——流程产物不进 target_files 声明（verify 对账同口径会将其滤掉，声明了也对不上账）`)
+        continue
+      }
+      // 存在性：非 NEW 且不存在 = 幻觉路径（ERROR，本检查核心价值）；NEW 且已存在 = 前缀误用（WARNING）
+      if (repoRoot) {
+        const fileExists = existsSync(pJoin(repoRoot, e.path))
+        if (!e.isNew && !fileExists) {
+          errors.push(`${label}: target_files「${e.raw}」在仓库中不存在且未加 NEW: 前缀——幻觉路径。修复：核对真实路径；确属新建文件则写 NEW:${e.path}`)
+          continue // 路径本身不成立，allowed_paths/design 交叉对它无意义
+        }
+        if (e.isNew && fileExists) {
+          warnings.push(`${label}: target_files「${e.raw}」已存在于仓库——NEW: 前缀仅用于当前不存在的文件，应去前缀`)
+        }
+      }
+      // allowed_paths 交叉（双交叉之二，X-5）：声明文件不在该卡白名单 → execute worktree
+      // 写入守卫（apply Gate1）才暴露越权，此处提前到 plan 提示补白名单（容差匹配：目录
+      // 前缀/glob 的 allowed_paths 可覆盖精确 target_file，与 coverage 对账同 pathMatches 语义）
+      if (allowedPaths.length > 0 && !allowedPaths.some(ap => pathMatches(e.path, ap))) {
+        warnings.push(`${label}: target_files「${e.path}」不在本卡 allowed_paths 白名单内——execute 写入守卫会拦（apply Gate1 才暴露越权）。修复：补进 allowed_paths（目录前缀/glob 写法均可）或修正 target_files`)
+      }
+      // design 清单交叉：声明与 design 漂移提示（design 清单是覆盖对账的基准，target_files
+      // 声明清单外文件 = 两份意图清单分叉的早期信号）
+      if (designFiles.length > 0 && !designFiles.some(dp => pathMatches(e.path, dp))) {
+        warnings.push(`${label}: target_files「${e.path}」不在 design.md 文件变更清单内——请对齐（补 design 清单条目或修正声明），防声明与 design 漂移`)
+      }
+    }
+  }
+
+  // 字段缺失汇总（X-13）：每变更一条而非每卡一条——存量卡大量无此字段，每卡一条 WARNING
+  // 会淹没真正有价值的交叉警告；汇总粒度保信号可见又不阻断存量变更
+  if (missingCount > 0) {
+    warnings.push(`${missingCount} 张 task 卡未声明 target_files（存量卡可忽略——verify 对账将跳过；新卡请补：每条为仓根相对精确文件路径，不存在的文件加 NEW: 前缀）`)
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
 /**
  * Plan 可行性校验器（本地代码证明 execute 前置条件）
  * 检查 TaskCard 的完整性和可行性
@@ -1236,7 +1414,7 @@ export async function executePlanPostcheck(context) {
 
   console.log(`  📂 变更目录: ${changeDir}`)
 
-  // ── 报错聚合（坑6③）：六个检查全部跑完后统一输出全部失败项，一轮 --done 暴露全部问题，
+  // ── 报错聚合（坑6③）：七个检查全部跑完后统一输出全部失败项，一轮 --done 暴露全部问题，
   // 不再「失败一个抛一个、修一个冒一个」的迭代盲盒。各检查相互独立（都只读 changeDir 产物），
   // 前置检查失败不使后续检查失真——唯一例外是 tasks/ 目录缺失时后续检查都无意义，仍提前短路。
   const failures = [] // { name, errors, hint }
@@ -1333,6 +1511,21 @@ export async function executePlanPostcheck(context) {
     }
   }
 
+  // ── 1f. task 卡 target_files 声明核验（P3a Wave 1）──
+  // 对账意图声明的 plan 期机器核验：幻觉路径 / 非法格式 → error 硬拦（消灭「计划动不存在
+  // 文件」的幻觉出口）；存量卡缺字段仅每变更一条汇总 WARNING（X-13，不阻断零红门禁）。
+  // 核验通过 = task-04 verify 对账的声明侧可信（对账 import parseTargetFiles 同源解析）。
+  // 追加在既有 6 项之后，不触碰其语义与顺序；本检查同样独立、只读 changeDir 产物。
+  const targetFiles = validateTargetFiles(changeDir, context.cwd)
+  if (targetFiles.errors.length > 0) {
+    failures.push({
+      name: 'task 卡 target_files 声明核验（幻觉路径/非法格式）',
+      errors: targetFiles.errors,
+      hint: '修复方式：核对仓库真实路径——已存在文件裸写、新建文件加 NEW: 前缀；每条须为仓根相对的精确文件路径（禁 glob/目录前缀/引号/绝对路径）。',
+    })
+  }
+  printSectionWarnings('target_files 声明', targetFiles.warnings)
+
   // ── 聚合输出：一轮 --done 暴露全部失败项（坑6③）──
   if (failures.length > 0) {
     console.error(`\n❌ plan postcheck 失败（${failures.length} 类问题，已全部列出——一次修复后重跑，无需逐个迭代）：`)

package/src/stages/plan.js

@@ -63,7 +63,8 @@ const stepClassify = {
    - 如果发现 priority=P0/P1 且 status=unresolved/blocking 的决策，停止生成计划，要求先回到 brainstorm 的 Design Grill 修正
    - 如果发现 superseded 决策，只引用最新版本，不引用旧版本
 5. 读取 CONVENTIONS.md、ARCHITECTURE.md（技术栈含在 ARCHITECTURE.md）
-6. 读取 local.yaml 获取构建/测试命令
+6. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 7. 读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（不存在则跳过）
    - 根据 design.md 的文件变更清单匹配模块
    - 读取匹配到的模块文档
@@ -134,7 +135,7 @@ const stepGeneratePlan = {
 1. 读取 plan.md frontmatter 的 \`plan_level:\` 字段（上一步已落盘为持久锚点；文件不存在或无该字段时回退读上一步输出的分类结果）
 2. 读取 tasks.md 和 design.md 了解需求范围
 3. 按 plan_level 选择对应模板输出
-4. **写回任务清单**：把展开后的任务清单写回 tasks.md（checkbox 行 \`- [ ] task-XX: 一句话任务名\`，可附 \`[model:xxx]\`/\`(depends_on: task-01,02)\` 行内标注）。**写回规则（D-002@v1）**：保留 frontmatter/中文标题/所有非 task-XX 行（quick 挂载的 ql-xxx 勾选行、注记等逐行保留），仅重写 task-XX checkbox 行集合——防摧毁 quick 挂载条目
+4. **写回任务清单**：把展开后的任务清单写回 tasks.md（checkbox 行 \`- [ ] task-XX: 一句话任务名\`，可附 \`[model:xxx]\`/\`(depends_on: task-01,02)\` 行内标注）。**写回规则（D-002@v1）**：保留 frontmatter/中文标题/所有非 task-XX 行（quick 挂载的 ql-xxx 勾选行、注记等逐行保留），仅重写 task-XX checkbox 行集合——防摧毁 quick 挂载条目。**展开任务时为每个 task 确定 target_files**（该 task 计划要改动的文件清单，随下一步「生成 TaskCard」按统一格式落进卡 frontmatter 的 target_files 字段）：每项为精确仓根相对路径（✅ \`src/foo.js\`），计划新建的文件加 \`NEW:\` 前缀（✅ \`NEW:src/bar.js\`）；❌ 禁 glob（\`src/**\`）/目录前缀（\`src/dir/\`）/绝对路径。target_files 与 allowed_paths 语义不同：前者=计划要动的具体文件，后者=权限范围
 5. 保存 plan.md（审查在下一步"审查计划"独立进行，不在本步自审——避免生成与自审同一次输出）；frontmatter 保留 plan_level 字段不删。**plan.md Wave 段下任务一律纯 ID 引用行**（\`- task-XX\`，不重抄任务名——任务名唯一真相在 tasks.md，重抄即双写漂移）
 
 > ⚠️ **Wave 段格式铁律（踩坑：旧先例 \`- [ ] task-XX: 描述\` 格式会导致 postcheck 告警）：**
@@ -416,6 +417,8 @@ decision_ids: [D-XXX@vN]
 repo: <repo-key>                          # 可选。仅跨仓 task 填：local.yaml repos: 注册的仓 key（缺省=main，主仓 task 省略此行）
 allowed_paths:                            # ⚠️ 路径相对 repo 声明的仓根（跨仓=跨仓仓根，主仓=主仓根），禁止带仓库名前缀/绝对路径
   - frontend/src/lib/errors.ts
+target_files:                             # 可选。本 task 计划要改动的文件清单（文件级意图，供对账；与 allowed_paths 语义不同——那是权限范围）。骨架已预置 [] 占位行，无明确意图保留 [] 不动
+  - src/foo.js                            # ✅ 精确仓根相对路径（口径同 allowed_paths）；计划新建文件加 NEW: 前缀（NEW:src/bar.js）。❌ 禁 glob（src/**）/目录前缀（src/dir/）/绝对路径
 provides:                              # 可选。仅当本 task 给其他 task 提供接口/DTO/响应时填
   - contract: <DTO或响应类型名>          # 如 DaemonRuntimeRead
     fields: [field_a, field_b]
@@ -454,6 +457,8 @@ related_tests:                           # 可选。当本 task 改动会导致
 
 ⚠️ **TaskCard 必备字段（缺一 postcheck 直接阻断）：** id、title（英文）、**title_zh（中文标题，必填）**、allowed_paths、goal、implementation、acceptance、verify、constraints。骨架已由 taskcard CLI 预生成（含 title_zh 占位），子代理只需 Edit 填值，不要删除任何必备字段。
 
+可选字段 **target_files**（本 task 计划要改动的文件清单；骨架已预置 \`target_files: []\` 占位行，按任务计划 Edit 填值，无明确文件级意图保留 []）：✅ 精确仓根相对路径 \`src/foo.js\`、计划新建文件 \`NEW:src/bar.js\`；❌ \`src/**\`（glob）、\`src/dir/\`（目录前缀）、绝对路径。语义区分：target_files=计划要动的具体文件，allowed_paths=权限范围。
+
 ## 任务清单
 ${taskList}
 
@@ -501,7 +506,7 @@ TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML
 1. 读取 ${changeDir}/design.md 和 ${changeDir}/plan.md 了解整体上下文
 2. 读取本 batch 涉及的相关源文件
 3. **骨架已由主 agent 预生成**（\`${changeDir}/tasks/task-NN.md\` 已存在，LF 行尾 + 闭合 frontmatter + 硬校验 9 字段齐全）。**禁止再运行 \`sillyspec taskcard\` CLI**——并行子代理各起 CLI 进程会撞进度库 SQLite 锁（2026-08-25 实证）；若发现本 batch 某卡骨架缺失，报告主 agent 补跑，不要自己跑
-4. 用 Edit tool 逐卡填充骨架占位符（allowed_paths/goal/implementation/acceptance/verify/constraints 等）。**禁止用 Write 整文件重写**——手写整卡是 CRLF 行尾/漏闭合 --- /漏硬校验字段三类 postcheck 拒绝的根源，骨架 + Edit 从源头消灭
+4. 用 Edit tool 逐卡填充骨架占位符（allowed_paths/target_files/goal/implementation/acceptance/verify/constraints 等）。**禁止用 Write 整文件重写**——手写整卡是 CRLF 行尾/漏闭合 --- /漏硬校验字段三类 postcheck 拒绝的根源，骨架 + Edit 从源头消灭
 5. 骨架字段含义与可选字段（provides/expects_from/related_tests，按需插进 frontmatter）参考下述模板：
 
 ${taskcardTemplate}

package/src/stages/quick.js

@@ -23,7 +23,8 @@ step 3 --done 审计会把 src 核心文件（CLI / 状态机 / 注入框架等
 2. 理解任务：模糊则问一个问题确认
 3. 加载项目信息：\`cat {SPEC_ROOT}/projects/*.yaml 2>/dev/null\`（了解项目结构和技术栈）
 4. 加载上下文：\`cat {SPEC_ROOT}/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
-5. 加载本地配置：\`cat {SPEC_ROOT}/local.yaml 2>/dev/null\`（构建命令、测试命令、环境变量等）
+5. 构建命令（CLI 自 local.yaml 注入，勿再读文件）：
+{LOCAL_COMMANDS}
 6. 若有关联变更，加载每个变更的设计文档：\`cat {SPEC_ROOT}/changes/<c>/design.md 2>/dev/null\`（理解设计意图）
 7. 如有需要，查询知识库：\`cat {SPEC_ROOT}/knowledge/INDEX.md 2>/dev/null\`
 
@@ -121,7 +122,8 @@ sillyspec run quick --done --change <id> --req "…" --cause "…" --solution "
 3. 【--done 后】核对 QUICKLOG 标题（CLI 已从「需求：」自动提取，仅弱标题才手改）→ 若改了再 \`git add\`
 
 ### 操作
-1. 查看 \`git status --porcelain\`，确认只包含本次 quick 相关文件
+1. 工作区脏文件（CLI 注入，勿重跑 \`git status\`）——确认只包含本次 quick 相关文件，无关改动不暂存：
+{GIT_DIRTY}
 2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）
    - 禁止使用 \`git add -A\`
    - 不要暂存 quick 开始前就已存在的无关改动