sillyspec 3.27.12 → 3.28.2

package/src/stage-review.js

@@ -69,9 +69,13 @@ export function renderReviewJsonContract({ stage, changeDir, reviewRunId, tier }
     '- **推荐**:docHash 先占位(如 `"TODO"`),review.json 写完后跑',
     '  `sillyspec register-stage-review --change <变更名> --stage ' + stageLbl + ' --refresh-hash`',
     '  —— CLI 重算真实 sha256 代填,verdict/checklist 原样保留;主文档改版后同样跑这条',
-    '  (多阶段联动用 `--all` 一次处理)。gate 拦 docHash 失配时也是同一条命令修复。',
+    '  (多阶段联动用 `--all` 一次处理)。',
+    '- **忘了跑也没关系**:' + mainDoc + ' 改版后 --done 的 gate 检测到 docHash 失配会**自动机械重算放行**',
+    '  (verdict 保留;结论是否仍适用于新文档需人工确认,reviewerNotes 会留审计行)。',
     '- 兜底手算口径(极端无 CLI 场景):node `crypto.createHash(\'sha256\').update(readFileSync(...))` (原始字节)/ `sha256sum <file>` 首列 hex。',
-    '- ⚠️ **review.json 写入后若 ' + mainDoc + ' 再被改,必须重算 docHash** —— gate 会重算 reviewedFiles[0] 的 sha256 比对,不符判伪造(历史翻车根因:design 改了 rev 后 docHash 仍是旧值)',
+    '- ⚠️ **review.json 写入后若 ' + mainDoc + ' 再被改,须重算 docHash** —— 忘算也没关系:gate 会自动机械重算放行,',
+    '  但那只是「机械对齐」;大幅改版(设计要点/接口变更)时审查结论可能已过时,应人工确认结论续用或重审,',
+    '  不要把自动放行当「新文档已审过」(历史翻车根因:design 改了 rev 后结论未复核)。',
     '',
     '### 完整 JSON 示例(照抄改值)',
     '```json',
@@ -212,7 +216,8 @@ export function verifyStageReviewDocHash(review, searchDirs) {
     if (claimed !== actualRaw.toLowerCase() && claimed !== actualLf.toLowerCase()) {
       errors.push(
         `docHash 与主审查文档 ${primaryRel} 的实际内容不匹配。` +
-        `若刚改过该文档（如 design 修订后忘重算），一键修复：` +
+        `若刚改过该文档（如 design 修订后忘重算），--done gate 会自动机械重算放行（verdict 保留）；` +
+        `本调用方未走自动刷新时可手动执行：` +
         `sillyspec register-stage-review --change <变更名> --stage <阶段> --refresh-hash` +
         `（CLI 重算 docHash 代填，verdict 保留；多阶段联动加 --all）；` +
         `若未改文档，则 review.json 疑似伪造（未真正读取文档）。`
@@ -412,6 +417,60 @@ export function validateStageReview(opts) {
   return { ok: errors.length === 0, errors, warnings, review: parsed }
 }
 
+/**
+ * validateStageReview 的 gate 时刻自动刷新包装（坑 stage-review-refresh-hash-manual-forget，
+ * 2026-09-04 用户实证③：design 每次改版都要手动重跑 register-stage-review --refresh-hash，
+ * 易忘——忘则 --done 被 docHash 失配拦一轮，纯机械损耗）。
+ *
+ * 语义与 --refresh-hash 完全同源：主文档改版后的 hash 机械重算，verdict/checklist/
+ * requiredEvidence 原样保留（结论是否仍适用由人工确认——reviewerNotes 追加审计行留痕）。
+ * 自动刷新不放宽防伪造边界：
+ *   - 真正判伪造/错位的「主文档在候选基准下均不存在」不触发自动刷新（仍 fail-closed）；
+ *   - schema 失败 / verdict=fail 不碰（照常阻断）；
+ *   - 写盘失败回落原失败结果（fail-closed，不静默放行）。
+ *
+ * @param {object} opts - 同 validateStageReview，另加 opts.autoRefresh（true 才尝试自动刷新）
+ * @returns {{ result: object, autoRefreshed: boolean, refreshedPath?: string, previousErrors?: string[] }}
+ */
+export function validateStageReviewWithAutoRefresh(opts) {
+  const result = validateStageReview(opts)
+  if (result.ok) return { result, autoRefreshed: false }
+  if (!opts.autoRefresh) return { result, autoRefreshed: false }
+  // 仅「docHash 与主审查文档 …不匹配」类错误才自动刷新；「均不存在」（路径伪造/基准错位）
+  // 与 schema/verdict 错误一律原样返回
+  const mismatchOnly = result.review
+    && Array.isArray(result.errors) && result.errors.length > 0
+    && result.errors.every(e => String(e).includes('docHash 与主审查文档'))
+  if (!mismatchOnly) return { result, autoRefreshed: false }
+
+  const reviewDir = join(opts.runtimeRoot, 'stage-reviews', `${opts.stage}-${opts.reviewRunId}`)
+  const reviewPath = join(reviewDir, 'review.json')
+  // 定位主文档并重算 hash（与 verifyStageReviewDocHash 同法：reviewedFiles[0] × searchDirs）
+  const primaryRel = Array.isArray(result.review.reviewedFiles) ? result.review.reviewedFiles[0] : null
+  let docHash = null
+  if (primaryRel) {
+    for (const base of (opts.searchDirs || [])) {
+      const abs = join(base, primaryRel)
+      if (existsSync(abs)) { docHash = computeDocHash(abs); break }
+    }
+  }
+  if (!docHash) return { result, autoRefreshed: false }
+
+  const refreshedAt = new Date().toISOString().slice(0, 19).replace('T', ' ')
+  const refreshed = {
+    ...result.review,
+    docHash,
+    reviewerNotes: `${result.review.reviewerNotes || ''}\ndocHash auto-refreshed at ${refreshedAt}（gate 检测主文档改版，机械重算；verdict 保留，结论是否仍适用需人工确认）`.trim(),
+  }
+  try {
+    writeFileSync(reviewPath, JSON.stringify(refreshed, null, 2) + '\n')
+  } catch {
+    return { result, autoRefreshed: false } // 写失败回落原失败结果，不静默放行
+  }
+  const recheck = validateStageReview(opts)
+  return { result: recheck, autoRefreshed: recheck.ok, refreshedPath: reviewPath, previousErrors: result.errors }
+}
+
 /**
  * 打印 stage review 校验结果
  * @param {{ ok: boolean, errors: string[], warnings: string[] }} result

package/src/stages/archive.js

@@ -186,14 +186,14 @@ created_at: <now-datetime>
     },
     {
       name: '更新路线图和提交',
-      prompt: `更新路线图并暂存变更。
+      prompt: `更新路线图并确认归档。
 
 ### 操作
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
-2. \`git add .sillyspec/changes/archive/\` — 暂存归档结果（archive/ 下仅本次归档新增，不会裹挟 changes/ 下其他活跃变更；不要 commit，由用户通过统一提交工具处理）
-3. \`git add .sillyspec/docs/<project>/modules/\` — 暂存模块文档更新（如有；精确到本次同步的模块文档，勿 add 整个 .sillyspec/docs/）
-4. \`git add .sillyspec/knowledge/decisions/\` — 暂存决策知识库更新（如有；decision-distill 步骤的提炼产物，精确到 decisions 子目录，勿 add 整个 .sillyspec/knowledge/；不要 commit，由用户通过统一提交工具处理）
-5. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+2. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+
+### 说明
+- **git 暂存已由 CLI 自动完成**（归档完成时自动 add：\`.sillyspec/changes/archive/\`、本次同步的模块文档、\`.sillyspec/knowledge/decisions/\`——未提交，由用户通过统一提交工具处理）——你不需要也不应该手动 git add
 
 ### 输出
 归档完成确认 + 累积规范统计`,

package/src/stages/brainstorm.js

@@ -7,21 +7,20 @@ export const definition = {
       name: '进度确认',
       // 重命名自「状态检查」（③ status 消歧）：老进度里的「状态检查」completed 由迁移逻辑承接，防 currentIdx 回跳
       migratedFrom: ['状态检查'],
-      prompt: `检查当前变更的进度状态（sillyspec.db）。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
+      prompt: `检查当前变更的进度状态（快照已由 CLI 注入，勿再跑 progress show——那是全量输出，浪费上下文；\`sillyspec status\` 是项目级快照，也不推进流程）。
+
+### 进度快照（CLI 注入）
+{PROGRESS_SNAPSHOT}
 
 ### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 "brainstorm"
-3. 如果有进行中的 brainstorm，提示选择继续或重新开始
-4. 如果未初始化，提示先运行 sillyspec init
-5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
+1. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change-a3f2b7c1\`），询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
+2. 如果快照显示阶段不符或未初始化，输出正确提示并停止
 
 ### 输出
 当前状态摘要（1-2 句话）
 
 ### 注意
-- 以 CLI 返回为准，不要自行推断阶段
-- 如果阶段不对，输出正确提示并停止
+- 以 CLI 注入快照为准，不要自行推断阶段
 - **不要用 mv 命令重命名变更目录**，必须使用 \`sillyspec change-rename\`，否则 DB 和目录会脱节`,
       outputHint: '状态摘要',
       optional: false
@@ -33,6 +32,7 @@ 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\`
 4. 棕地项目：读取 {SPEC_ROOT}/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
@@ -348,7 +348,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 +358,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,13 +220,14 @@ const fixedPrefix = [
   {
     name: '进度确认',
     migratedFrom: ['状态检查'],
-    prompt: `检查当前进度，确认可以执行 execute。用 \`sillyspec progress show\` 查流程进度，不要用 \`sillyspec status\`（项目级快照，不推进流程）。
+    prompt: `检查当前进度，确认可以执行 execute（快照已由 CLI 注入，勿再跑 progress show；\`sillyspec status\` 是项目级快照，也不推进流程）。
+
+### 进度快照（CLI 注入）
+{PROGRESS_SNAPSHOT}
 
 ### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 execute
-3. 如果不是 → 检查是否有未完成的 tasks.md
-4. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
+1. 如果快照显示不是 execute 阶段 → 检查是否有未完成的 tasks.md
+2. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
 
 ### 输出
 当前状态 + 执行范围确认`,
@@ -284,18 +285,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 +356,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 卡 §锚点定位），避免反复整读全文
@@ -1064,7 +1066,7 @@ ${crossLines}${crossWorktreeSection}${crossLegacySection}
 
 **回收跨仓 task（head 锡点，CLI 自动落盘，勿手写）：**
 - 子代理完成 commit 后，正常写 review.json（verdict/notes）并勾选 checkbox 即可。execute \`--done\` 时 CLI 自动对跨仓仓（worktree 模式=该仓 worktree，legacy=仓根）\`git rev-parse HEAD\` 写入该 task 卡 \`head_commit:\`（幂等，已存在不覆盖——你若手写了精确锚点则以你的为准）。
-- review.json 的 mechanics 字段（\`base\`/\`head\`/\`changedFiles\`）无需手算：\`base\` 取 task 卡 \`base_commit\`、\`head\` 取 task 卡 \`head_commit\`，写完跑 \`sillyspec backfill-reviews --change <变更名> --adopt\` 一键代填（verdict 保留）。
+- review.json 的 mechanics 字段（\`base\`/\`head\`/\`changedFiles\`/\`diffPaths\`）无需手算：\`base\` 取 task 卡 \`base_commit\`、\`head\` 取 task 卡 \`head_commit\`，写完跑 \`sillyspec backfill-reviews --change <变更名> --adopt\` 一键代填（verdict 保留）。
 `
   }
 
@@ -1243,9 +1245,13 @@ task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-X
  "qualityVerdict": "pass|fail|cannot_verify", "reviewerNotes": "评审说明",
  "requiredEvidence": [] }
 
+**base/head 两种取法（按提交模式选其一）：**
+- **per-task commit 模式**（默认，子代理每 task 一提交）：base=本 task 开始前的 commit，head=本 task 的 commit——base..head 天然就是本 task 的 diff，无需 diffPaths。
+- **统一 commit 模式**（主代理统一实现/收尾一次性 commit，全部 task 一个提交）：base=基线 commit（worktree meta 的 baseHash），head=统一 commit，并**必填 \`diffPaths\`（本 task 卡的 allowed_paths 原样数组）**——评审与 CLI 校验的 diff 都是 \`git diff base..head -- diffPaths\` 的路径限定切片，任务边界由 diffPaths 机器可验，不再只靠 changedFiles 归属说明。changedFiles 填切片内实际改动的文件。
+
 **评审铁律：**
 - 不信任 implementer 自报结果，对照 diff 和 task brief 验证
-- 只看当前 task 的 diff，不做全仓库漫游审查
+- 只看当前 task 的 diff（统一 commit 模式=路径限定切片），不做全仓库漫游审查
 - \`cannot_verify\` 只在确实无法验证且有待补充证据时使用，且 requiredEvidence 必须非空
 - \`sillyspec run execute --done\` 会校验所有 task 的 review.json，缺失或 fail 会阻断完成
 

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

@@ -134,7 +134,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 +416,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 +456,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 +505,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}