sillyspec 3.27.12 → 3.28.2

package/src/stages/scan.js

@@ -5,35 +5,13 @@ export const definition = {
   auxiliary: true,
   steps: [
     {
+      // noAI 化（2026-09-05 ①）：ls 级探测不值一整轮 agent 往返——CLI 直跑（scanDetectProjects），
+      // 只打印建议不注册（原红线语义不变）。步骤名保持不变（存量进度库按名匹配迁移）。
       name: '探测项目结构并建议子项目',
-      prompt: `扫描项目顶层目录结构，自动发现可能的子项目，**需用户确认后才创建 projects 配置**。
-
-### 操作
-1. 列出项目顶层目录：\`ls -d */ 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '.sillyspec'\`
-2. 对每个顶层目录，快速判断是否为独立项目（检查 package.json / pom.xml / build.gradle / pyproject.toml / go.mod 等构建文件）
-3. 对每个疑似独立项目，检测技术栈：\`cat <dir>/package.json 2>/dev/null | head -5\` 或类似
-4. 对比 \`{PROJECTS_ROOT}/\` 已有配置，找出未注册的子项目
-
-### 判断标准（满足任一即为子项目）
-- 有独立的构建文件（package.json, pom.xml, build.gradle, pyproject.toml 等）
-- 有独立的源码目录结构（src/, app/, lib/ 等）
-- 有独立的测试目录（test/, tests/, __tests__/ 等）
-- 不是 .git / node_modules / .sillyspec / dist / build 等工具目录
-
-### 输出格式
-列出发现的可能子项目列表，每个含：
-- 目录名
-- 技术栈（如 Next.js + TypeScript、FastAPI + Python）
-- 是否已注册到 projects/
-- 建议：注册 / 跳过
-
-### ⛔ 红线
-- **不要自动创建 projects 配置文件**，只列出建议供用户确认
-- **不要修改任何文件**，只做探测和报告
-
-### 输出
-子项目建议列表（含技术栈和注册状态）`,
-      outputHint: '子项目建议列表',
+      noAI: true,
+      _cliAction: 'scanDetectProjects',
+      prompt: '',
+      outputHint: '子项目建议列表（CLI 探测输出）',
       optional: false
     },
     {
@@ -90,34 +68,34 @@ export const definition = {
     {
       name: '构建环境探测',
       perProject: true,
-      prompt: `探测当前项目的构建环境和依赖。
+      prompt: `生成事实底稿（机械事实由 CLI 预咀嚼）+ 补充机器拿不到的线索。
 
 ### 操作
 对扫描列表中的每个项目重复以下操作：
-1. 进入项目目录（子项目用其 path，如 \`packages/dashboard/\`）
-2. \`cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null\`
-3. \`find <project-dir> -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null\`
-4. 结果保存到 \`{DOCS_ROOT}/scan/_env-detect.md\`（临时文件，扫描完删除）
+1. **先跑 CLI 确定性抽取**（端点/依赖/脚本/源码规模/git 基线，零 AI token）：
+   \`sillyspec scan facts\`（主项目；子项目加 \`--path <仓库相对路径> --project <项目名>\`）。
+   产物落 \`{DOCS_ROOT}/scan/_facts.md\`——后续所有子代理共享这一份底稿，**不要重复 grep 发现这些事实**。
+2. 补充机器拿不到的线索（保持精简）：README / CI 配置里的构建与测试命令、特殊环境要求、
+   配置文件要点（\`cat <project-dir>/*.config.* 2>/dev/null | head -80\`），
+   追加写入 \`{DOCS_ROOT}/scan/_env-detect.md\`（临时文件，扫描完删除）。
+
+### ⛔ 红线
+- **禁止自己 grep/rg 重新发现端点、路由、依赖清单**——以 \`_facts.md\` 为准；发现与源码冲突时以底稿为准并在文档中标注差异
+- 只读探测，不修改任何源文件
 
 ### 输出
-每个项目的环境探测结果摘要`,
-      outputHint: '环境探测摘要',
+每个项目的 _facts.md 状态（类型/依赖数/端点数）+ 补充线索摘要`,
+      outputHint: '_facts.md 状态 + 环境探测补充摘要',
       optional: false
     },
     {
+      // noAI 化（2026-09-05 ①）：existsSync×7 的机械检查——CLI 一次遍历全部已注册项目（scanResumeCheck）。
+      // 不再 perProject（单次 CLI 调用覆盖多项目，注册表步数不变仍为 11）。
       name: '断点续扫检测',
-      perProject: true,
-      prompt: `检测当前项目已有扫描文档，列出缺失的。
-
-### 操作
-对扫描列表中的每个项目分别执行：
-1. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
-   路径：\`{DOCS_ROOT}/scan/<DOC>.md\`
-2. 列出已有 ✅ 和缺失 ⬜
-
-### 输出
-每个项目的已有/缺失文档列表`,
-      outputHint: '断点续扫状态',
+      noAI: true,
+      _cliAction: 'scanResumeCheck',
+      prompt: '',
+      outputHint: '各项目已有/缺失文档清单（CLI 输出）',
       optional: false
     },
     {
@@ -134,8 +112,8 @@ export const definition = {
    a. 将 \`<project>\` 替换为实际项目名，得到该项目的目标文件路径
    b. 为每个角色启动独立子代理（可并行），每个子代理负责 1-2 份文档
    c. 子代理的搜索范围限定在该项目目录内（子项目如 \`packages/dashboard/\`，不要搜索主项目源码）
-   d. 子代理直接用 grep/rg 搜索源码并写入文件，结果不回传到你的上下文
-   e. 等待该项目所有子代理完成后，验证文件是否生成且非空
+   d. 子代理在**事实底稿覆盖范围内的机械事实**（端点/依赖/规模）直接消费注入的 \`_facts.md\`，不重新 grep 发现；底稿之外的架构理解仍用 grep/rg 搜索源码并写入文件，结果不回传到你的上下文
+   e. 等待该项目所有子代理完成后，直接进入下一项目——产物存在性/引用有效性由第 3 步 workflow check 与 postcheck **机器校验**，不要自己读回文件核对
    f. 该项目完成后，继续下一个项目
 3. 所有项目完成后，运行以下命令检查产物：
    \`sillyspec workflow check scan-docs --project <project>\`（CLI 子命令，任意项目根可用）
@@ -144,19 +122,9 @@ export const definition = {
 
 ### 覆盖保护
 - **scan_depth: quick 的浅层文档允许覆盖升级**：读取旧 frontmatter 时，若旧文档含 scan_depth: quick（由 --quick 快速接入生成的浅层版本），即使其 source_commit 与当前 HEAD 一致、updated_at 未变，也允许覆盖重写——深度扫描的目的就是把它升级为完整文档。
-- 生成每份 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
-  ---
-  \`\`\`
-  （\`<git-head-short>\` / \`<now-iso-datetime>\` 两占位符由 CLI 注入 prompt 时自动替换为当前 HEAD 短哈希与时间——照 prompt 里已替换的真实值抄写，勿自跑 git rev-parse；漏 header 事后 \`sillyspec scan-fix-headers\` 一键补 author/created_at）
+- **frontmatter 由 CLI 自动写入（2026-09-05 ②）：子代理不写 frontmatter、不跑 git 取值**。文档正文第 1 行直接写中文标题；终检步骤（scanFinalize）的 CLI 会按需注入 author / created_at / source_commit / updated_at / generator，只补缺不覆盖。
 - 覆盖已有 scan 文档前先读取旧 frontmatter；如果旧文档的 \`source_commit\` 与当前 HEAD 不一致，或旧文档 \`updated_at\` 晚于本次 scan 开始时间，不要覆盖。
-- 如果用户明确传入 \`--force-rescan\`，允许覆盖，但仍需写入新的 \`source_commit\` 和 \`updated_at\`。
+- 如果用户明确传入 \`--force-rescan\`，允许覆盖（新 frontmatter 仍由 CLI 注入）。
 
 ### 子代理上下文注入
 启动每个子代理前，将以下信息拼入子代理 prompt：
@@ -164,9 +132,10 @@ export const definition = {
 - 目标文件路径（从 workflow YAML 中 \`<project>\` 替换后的路径）
 - 检查要求（从 workflow YAML 中该角色的 checks）
 - 断点续扫步骤列出的缺失文档列表
-- 环境探测结果摘要（如有 _env-detect.md，直接贴入）
+- **事实底稿 \`{DOCS_ROOT}/scan/_facts.md\` 全文直接贴入**（CLI 确定性抽取的端点/依赖/规模清单——子代理**禁止重新 grep 发现**这些机械事实，只做解读与成文；INTEGRATIONS/ARCHITECTURE 中的端点与集成条目必须与底稿一致，并直接使用底稿里的 file:line 引用）
+- 环境探测补充摘要（如有 _env-detect.md，直接贴入）
 - **⚠️ 必须强调：子代理必须用 write 工具将文件写入磁盘**
-- **文件标题用中文**（sillyhub 平台解析识别用）：frontmatter 必须在文件最前（第 1 行 --- 起），frontmatter 结束的 --- 之后空一行，再写 # 中文名（English）作为标题。严禁把 # 标题放到 frontmatter 之前（否则 frontmatter 不在头部、「检查产物完整性」步的 frontmatter 检查会报缺 author/created_at）。各文档标准标题格式：
+- **文件标题用中文**（sillyhub 平台解析识别用）：正文第 1 行写 # 中文名（English）作为标题（CLI 会把 frontmatter 自动插到标题之前，你不用管）。各文档标准标题格式：
   - STRUCTURE.md = # 目录结构（Structure）
   - CONVENTIONS.md = # 代码约定（Conventions）
   - ARCHITECTURE.md = # 架构（Architecture）
@@ -174,6 +143,11 @@ export const definition = {
   - CONCERNS.md = # 关注点（Concerns）
   - INTEGRATIONS.md = # 集成（Integrations）
   - PROJECT.md = # 项目（Project）
+- **事实引用纪律**：子代理写入文档的关键事实（模块职责、技术栈组件、外部集成、核心命令）必须带反引号包裹的 path:line 引用（如 \`src/db.js:42\`），且引用必须真实——CLI postcheck 会逐条核验 file:line，失效引用产生 warning。**禁止猜行号**：不确定时只写文件路径不写行号；无法确证的结论标「待确认」，不写成事实。
+
+### 收敛规则（防打转）
+- \`sillyspec workflow check scan-docs\` 报告失败项后，**只修复报告点名的角色/文件对应的问题**，不要重写未失败的文档
+- 每轮修复后重跑检查，跟踪失败项数量：连续两轮失败项数量没有下降 → 停止重试，在 --output 里如实报告未解决的失败项与已尝试的修复，等待人工决策。**禁止为通过检查而编造内容或降低文档质量**
 
 ### 完成后
 列出每个项目的 7 份文档状态：
@@ -562,46 +536,14 @@ INDEX.md 维护索引，格式（每行：关键词1|关键词2 → [条目名](
       optional: false
     },
     {
+      // noAI 化（2026-09-05 ①②）：原 40 行自检 prompt 的职责全部机器化——
+      // 文档存在性/header/路径污染/API 错误信号 → runScanPostCheck；frontmatter → stampScanDocHeaders；
+      // _env-detect 清理 + 非平台 git add → CLI 直做。failed_post_check 时 throw 保持 step pending。
       name: '自检和提交',
-      perProject: true,
-      prompt: `验证当前项目的扫描完整性，清理并提交。
-
-### 操作
-对扫描列表中的每个项目分别执行：
-1. 检查 7 份 scan 文档是否全部生成（\`{DOCS_ROOT}/scan/\`）
-2. 检查模块文档状态（\`{DOCS_ROOT}/modules/\`）
-3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
-4. 检查 flows/ 和 glossary.md 是否已生成（如有）
-5. 清理：\`rm -f {DOCS_ROOT}/scan/_env-detect.md\`
-6. 如果非平台模式：\`git add {DOCS_ROOT}/ {KNOWLEDGE_ROOT}/\` — 暂存本次扫描产物（scan 文档 / 模块文档 / flows / glossary / knowledge；勿用 .sillyspec/ 整目录——会裹挟 changes/ 下其他活跃变更；不要 commit，由用户通过统一提交工具处理）。如果平台模式：跳过 git add（specRoot 不在 sourceRoot 的 git repo 内）。
-
-### ⛔ 路径合规检查（平台模式下必须执行）
-7. 确认所有文档都写入 \`{DOCS_ROOT}/\`（spec-root 下），**而非源码目录下的 .sillyspec/**
-8. 检查是否出现 tool_use_error 或 API Error 未恢复
-9. 检查 7 份文档 header 是否包含 author 和 created_at
-10. 复查 detect 核验结果——commands 键已由 detect 核验 scripts 存在性，agent 无需重复核验或标 unavailable，仅确认 local.yaml 与 detect 产出一致
-
-### ⛔ API 错误处理
-- 遇到 API Error 529（服务过载）或 rate_limit 时，**停止当前操作并报告**，不要自动重试
-- 遇到 tool_use_error 时，记录错误信息并跳过该文件/操作，继续处理下一项
-- 如果连续 3 次操作失败，输出失败摘要并停止
-
-### ⛔ 最终状态判定
-如果出现以下**任意**情况，最终状态**不能**写"全部通过"，只能写 \`completed_with_warnings\` 或 \`failed_post_check\`：
-- 源码目录下存在 docs（路径合规检查失败）
-- source_commit 为 null
-- Write 工具出现过失败
-- API Error 529 或 rate_limit
-- fallback / retry / skipped validation
-- 文档引用不存在的文件或模块
-- 文档内容包含 .sillyspec/ 等工具目录的扫描结果
-
-### 输出
-每个项目的扫描完整性报告（必须包含路径合规检查结果和最终状态）
-
-### 注意
-- ❌ 修改代码 / 编造路径 / 读源码全文`,
-      outputHint: '自检报告',
+      noAI: true,
+      _cliAction: 'scanFinalize',
+      prompt: '',
+      outputHint: 'CLI 终检报告（frontmatter 注入 + postcheck + 清理 + 暂存）',
       optional: false
     }
   ]

package/src/stages/verify.js

@@ -47,13 +47,13 @@ export const definition = {
       migratedFrom: ['状态检查'],
       prompt: `> 💡 先说清楚：\`sillyspec run verify\`（不带 --done）**只下发执行指令，不会替你跑测试/构建**——真正的测试由 CLI 在最后 --done 时统一执行（local.yaml 的 commands.test，同步对账可能耗时较长）；「运行测试和质量扫描」那步**不需要你重复手动跑全量**（避免与 CLI 对账重复耗时），只做 lint/静态检查 + 可选快速冒烟。别以为敲了 run verify 就自动验证了。
 
-检查当前进度，确认可以执行 verify。
+检查当前进度，确认可以执行 verify（快照已由 CLI 注入，勿再跑 progress show；\`sillyspec status\` 是项目级快照，也不推进流程）。
 
-> ⚠️ 本步用 \`sillyspec progress show\` 查**流程进度**（推进工作流用），不要用 \`sillyspec status\`（那是**项目级快照**，只读、不推进流程，是另一条命令）。
+### 进度快照（CLI 注入）
+{PROGRESS_SNAPSHOT}
 
 ### 操作
-1. 运行 \`sillyspec progress show\`
-2. 确认 currentStage 为 "verify"
+1. 如果快照显示阶段不符，输出正确提示并停止
 
 ### 输出
 当前进度摘要`,
@@ -214,9 +214,11 @@ export const definition = {
    你只需：在 verify-result.md 的「变更风险等级」section 如实记录变更性质；若变更涉及 daemon/backend 跨进程、session/lease/lifecycle 状态机、或部署启动路径，在「Runtime Evidence」section 提供真实集成证据（启动命令、daemon↔backend 调用与日志关键片段、终态断言）。
    - **集成证据是自报告、CLI 不独立运行时核验**：「Runtime Evidence」由你如实填写，CLI 只校验其**字面存在**（是否含关键词），**不会替你启动 daemon、打真实请求或跑迁移**——它是否名副其实取决于你是否实跑过。务必实跑后据实填写，不得凭堆关键词通过门控。（测试套件对账另算：commands.test 由 CLI 真实执行，那块谎报无效。）
 
-3. **生成 verify-result.md 骨架（勿从零手写）**：先跑 \`sillyspec verify-probes --change <change-name> --init\`——一条命令生成九章节骨架（已存在不覆盖），其中**探针结果章节已机械预填**（探针 1 的 TODO/FIXME 命中清单、探针 3 的测试覆盖、探针 5 的 API 契约对账表、探针 6 的删除对账三态判定），文件落 \`{SPEC_ROOT}/changes/<change-name>/verify-result.md\`（CLI 替换出的**主仓绝对路径**；若当前 cwd 在 worktree 内也绝不落 worktree 副本——CLI 校验读主仓，副本随 worktree 清理蒸发）。你只需把各 \`<!--TODO-->\` 占位替换为语义结论；半语义探针（2 关键词覆盖 / 4 决策追踪）与断言抽查、集成盲区标注由你补在对应 TODO 处
-4. 给出结论：PASS / PASS WITH NOTES / FAIL（受风险门控约束）——**结论必须写明 PASS/FAIL 字样，留「待填」会被 gate 判不过**
-5. **核对 module-impact.md**（若 \`{SPEC_ROOT}/changes/<change>/module-impact.md\` 存在）：对照本次实际代码变更（git diff）与 module-impact.md 的模块影响矩阵，发现不一致（漏标受影响模块 / 影响类型错误 / 实际未触碰的模块被误标）则在 verify-result.md 标注。module-impact 由 plan 首版生成、execute 各 Wave 更新，verify 是最后一次核对机会（archive 仅终审不再生成）。这是 advisory 核对（不阻断 verify 完成），但 module-impact 与实际严重背离应记为风险。
+3. **生成 verify-result.md 骨架（勿从零手写）**：先跑 \`sillyspec verify-probes --change <change-name> --init\`——一条命令生成十章节骨架（已存在不覆盖），其中**探针结果章节已机械预填**（探针 1 的 TODO/FIXME 命中清单、探针 3 的测试覆盖、探针 5 的 API 契约对账表、探针 6 的删除对账三态判定），文件落 \`{SPEC_ROOT}/changes/<change-name>/verify-result.md\`（CLI 替换出的**主仓绝对路径**；若当前 cwd 在 worktree 内也绝不落 worktree 副本——CLI 校验读主仓，副本随 worktree 清理蒸发）。你只需把各 \`<!--TODO-->\` 占位替换为语义结论；半语义探针（2 关键词覆盖 / 4 决策追踪）与断言抽查、集成盲区标注由你补在对应 TODO 处
+4. **预填探针段不可篡改或删除**：verify \`--done\` gate 会重跑探针对比 verify-result.md 正文，不符即拦（ERROR）；对探针结果有异议只能在预填段旁追加说明，不得改写原文
+5. **verify-facts.json 为机器底稿，勿手改**：防篡改对比的基准是正文，改底稿无意义
+6. 给出结论：PASS / PASS WITH NOTES / FAIL（受风险门控约束）——**结论必须写明 PASS/FAIL 字样，留「待填」会被 gate 判不过**
+7. **核对 module-impact.md**（若 \`{SPEC_ROOT}/changes/<change>/module-impact.md\` 存在）：对照本次实际代码变更（git diff）与 module-impact.md 的模块影响矩阵，发现不一致（漏标受影响模块 / 影响类型错误 / 实际未触碰的模块被误标）则在 verify-result.md 标注。module-impact 由 plan 首版生成、execute 各 Wave 更新，verify 是最后一次核对机会（archive 仅终审不再生成）。这是 advisory 核对（不阻断 verify 完成），但 module-impact 与实际严重背离应记为风险。
 
 ### verify-result.md 章节结构（骨架已含，占位替换即可）
 

package/src/sync.js

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, chmodSync, rmSync } from 'fs';
+import { createHash } from 'crypto';
 import { writeAtomicSync } from './fs-atomic.js';
 import { join, dirname, basename, isAbsolute, relative } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
@@ -1545,6 +1546,97 @@ export class SyncManager {
     return { ok: true, pulled: true, specDir, specVersion };
   }
 
+  /**
+   * spec 树 take-platform 落地（坑 spec-sync-conflict-no-take-platform，2026-09-03 用户实证
+   * 「冲突没有接受服务器版本选项」）：拉平台整树 bundle（GET /changes/-/spec-bundle，与
+   * pullSpecBundle 同端点同鉴权），但**只覆盖冲突文件列出的路径**——不整树替换，本会话/
+   * 他端的其他本地改动不动。服务器已无该路径（远端删除）→ 删本地对应文件。
+   *
+   * 覆盖后同步刷新内容基线快照（spec-sync-base.json）中被覆盖路径的 hash：下次
+   * syncSpecTree 的 dropFollowServerUpdates 判「本地未改动」不再回推——take-platform =
+   * 服务器胜出，本地内容即服务器内容，回推同值无害但走基线豁免更干净。
+   *
+   * fail-closed：路径越界（../、绝对路径）逐条跳过计入 skipped 不中断其余；bundle 拉取/
+   * 解析失败整体 ok:false（本地不动）。
+   * @param {string} specDir spec 树根
+   * @param {string[]} paths 冲突路径（POSIX 相对 specDir，来自冲突文件 conflicting_paths）
+   * @returns {Promise<{ok: boolean, overwritten?: number, removed?: number, skipped?: string[], reason?: string}>}
+   */
+  async _takePlatformSpecPaths(specDir, paths) {
+    const platform = this._getPlatform();
+    if (!platform) return { ok: false, reason: '未连接平台（take-platform 需拉平台 bundle）' };
+    if (!Array.isArray(paths) || paths.length === 0) return { ok: false, reason: '冲突文件缺 conflicting_paths，无可接受路径' };
+
+    const bundleUrl = `${platform.url}/api/changes/-/spec-bundle`;
+    let res;
+    try {
+      res = await fetch(bundleUrl, {
+        headers: { Authorization: `Bearer ${platform.token}` },
+        // 大树/慢网同 pullSpecBundle 口径（审计 B2），不与外部熔断组合（resolve 是用户显式动作）
+        signal: AbortSignal.timeout(PULL_BUNDLE_TIMEOUT_MS),
+      });
+    } catch (err) {
+      const why = (err.name === 'AbortError' || err.name === 'TimeoutError') ? `下载超时/中断（${PULL_BUNDLE_TIMEOUT_MS / 1000}s 上限）` : err.message;
+      return { ok: false, reason: `拉取 spec bundle 失败: ${why}` };
+    }
+    if (!res.ok) {
+      const why = res.status === 404 ? '平台工作区尚无 spec 内容（HTTP 404）' : `HTTP ${res.status}`;
+      return { ok: false, reason: `拉取 spec bundle 失败: ${why}` };
+    }
+    let tarBuf;
+    try { tarBuf = Buffer.from(await res.arrayBuffer()); }
+    catch (err) { return { ok: false, reason: `读取 spec bundle 失败: ${err.message}` }; }
+    let entries;
+    try { entries = _parseSpecTar(tarBuf); }
+    catch (err) { return { ok: false, reason: `spec bundle 无效: ${err.message}` }; }
+
+    const serverFiles = new Map();
+    for (const e of entries) {
+      if (e.isDir || e.name === 'PLATFORM-BUNDLE.json') continue;
+      serverFiles.set(e.name.replace(/^\.\//, ''), e.data);
+    }
+
+    const normalized = [...new Set(paths.map((p) => String(p).replace(/\\/g, '/')).filter(Boolean))];
+    let overwritten = 0;
+    let removed = 0;
+    const skipped = [];
+    for (const p of normalized) {
+      try {
+        _assertSafeTarName(p, specDir);
+        const data = serverFiles.get(p);
+        if (data !== undefined) {
+          const full = join(specDir, p);
+          mkdirSync(dirname(full), { recursive: true });
+          writeFileSync(full, data);
+          overwritten++;
+        } else if (existsSync(join(specDir, p))) {
+          // 服务器已无该文件（远端删除）→ 接受服务器 = 删本地
+          rmSync(join(specDir, p), { force: true });
+          removed++;
+        }
+      } catch {
+        skipped.push(p);
+      }
+    }
+
+    // 基线快照刷新（best-effort）：被覆盖路径回写当前盘面 hash（= 服务器内容 hash）、被删
+    // 路径移除条目——下次同步这些路径按「本地未改动」豁免回推（take-platform 语义闭环）。
+    try {
+      const baseFile = join(specDir, '.runtime', 'spec-sync-base.json');
+      let base = null;
+      try { base = JSON.parse(readFileSync(baseFile, 'utf8')); } catch { base = null; }
+      const hashes = base && typeof base.hashes === 'object' ? base.hashes : {};
+      for (const p of normalized) {
+        try { hashes[p] = createHash('sha256').update(readFileSync(join(specDir, p))).digest('hex'); }
+        catch { delete hashes[p]; }
+      }
+      mkdirSync(join(specDir, '.runtime'), { recursive: true });
+      writeFileSync(baseFile, JSON.stringify({ ts: Date.now(), hashes }, null, 2) + '\n', 'utf8');
+    } catch { /* 快照失败只损失下次的防回推精度，覆盖结果本身已成立 */ }
+
+    return { ok: true, overwritten, removed, skipped };
+  }
+
   /**
    * 冲突解决三选一（task-13 / D-002 / D-010 / D-013 / FR-05）。
    * 读 task-12 写的 sync-conflict-<change>.json，按 mode 处理后必清冲突文件防累积（R-04 / constraints）。
@@ -1636,9 +1728,11 @@ export class SyncManager {
     let specOutcome = null;
     if (specCf && mode === 'keep-local') {
       // keep-local = 本地胜出：重新 GET 清单重定 base 后 POST 本地内容（last-writer-wins），
-      // 成功清冲突文件闭环；仍冲突（平台又有更新）保留文件待下次裁决
+      // 成功清冲突文件闭环；仍冲突（平台又有更新）保留文件待下次裁决。
+      // forcePush（坑 quicksync-conflict-granularity）：用户显式裁决后本地意志高于
+      // 「未改动跟随服务器」语义——强制重推不得被内容基线/mtime 防回推过滤削掉。
       try {
-        const r = await syncSpecTree(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), this._getPlatform(), changeName);
+        const r = await syncSpecTree(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), this._getPlatform(), changeName, { forcePush: true });
         if (!r.conflict) {
           this.clearSpecConflictFile(changeName);
           specOutcome = { ok: true, resolved: true, reason: 'spec 树已以本地为准重定基线重推，冲突闭环' };
@@ -1649,8 +1743,32 @@ export class SyncManager {
         specOutcome = { ok: false, resolved: false, reason: `spec 树重推异常: ${err.message}` };
       }
     } else if (specCf && mode === 'take-platform') {
-      // fail-closed：平台无文件下载端点，无法把服务器内容写回本地——明确报错指路，不清文件
-      specOutcome = { ok: false, resolved: false, reason: 'spec 树冲突不支持 take-platform（平台无文件下载端点，无法把服务器内容写回本地）：请手动对齐本地文件后跑 --keep-local' };
+      // spec 树 take-platform（坑 spec-sync-conflict-no-take-platform，2026-09-03 用户实证反馈
+      // 「冲突没有接受服务器版本选项」）：平台已有 CLI 可用的整树下载端点（GET /changes/-/
+      // spec-bundle，X2 task-08）——拉 bundle 只覆盖冲突文件列出的路径（不整树替换，本地其他
+      // 改动不动），基线快照同步刷新防回推，清冲突文件闭环。此前 fail-closed 报「平台无文件
+      // 下载端点」是端点落地前的旧事实。
+      try {
+        const specDir = safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec');
+        const paths = Array.isArray(specCf.conflicting_paths) && specCf.conflicting_paths.length > 0
+          ? specCf.conflicting_paths
+          : Object.keys(specCf.server_versions || {});
+        const r = await this._takePlatformSpecPaths(specDir, paths);
+        if (r.ok) {
+          this.clearSpecConflictFile(changeName);
+          const skippedNote = r.skipped && r.skipped.length > 0
+            ? `，${r.skipped.length} 个路径异常跳过（${r.skipped.slice(0, 3).join(', ')}${r.skipped.length > 3 ? ' 等' : ''}）`
+            : '';
+          specOutcome = {
+            ok: true, resolved: true,
+            reason: `spec 树已接受服务器版本：覆盖 ${r.overwritten} 个冲突文件${r.removed > 0 ? `、删除 ${r.removed} 个（服务器已删）` : ''}${skippedNote}，本地改动已放弃`,
+          };
+        } else {
+          specOutcome = { ok: false, resolved: false, reason: `spec 树 take-platform 失败: ${r.reason}（可重试；或手动对齐本地文件后 --keep-local）` };
+        }
+      } catch (err) {
+        specOutcome = { ok: false, resolved: false, reason: `spec 树 take-platform 异常: ${err.message}` };
+      }
     }
 
     // ── abort：两类标记一并清（本地 DB 与文件均不变，下次 push/pull 重新检测）──

package/src/task-review.js

@@ -244,6 +244,19 @@ export function validateReviewSchema(review) {
     errors.push('缺少 head 字段（git commit hash）')
   }
 
+  // diffPaths（可选，统一 commit 模式）：路径限定评审范围。主代理统一 commit（全部 task 一个
+  // commit）下 per-task 提交区间不存在，base..head 只能取整变更区间——diffPaths=本 task 的
+  // allowed_paths，评审/校验 diff 收窄为 git diff base..head -- diffPaths 的路径限定切片
+  // （坑 task-review-unified-commit-scope，2026-09-01 实证：此前任务边界只靠 changedFiles
+  // 「归属说明」，gate 无法机器验证本 task 切片非空）。缺省=不过滤（per-task commit 模式
+  // base..head 本就是任务区间，行为零变化）。
+  if (review.diffPaths !== undefined) {
+    if (!Array.isArray(review.diffPaths) || review.diffPaths.length === 0
+        || !review.diffPaths.every(p => typeof p === 'string' && p.trim())) {
+      errors.push('diffPaths（若提供）应为非空字符串数组（路径限定评审范围，统一 commit 模式填本 task 的 allowed_paths；per-task commit 模式无需此字段）')
+    }
+  }
+
   return { ok: errors.length === 0, errors }
 }
 
@@ -499,7 +512,10 @@ export function validateTaskReviews(opts) {
             errors.push(`${taskId}: 纯验证 task（task_type: verification）零 diff 合法，但 review 缺 requiredEvidence（须披露验证区间/命令/结论出处）——声明不能替代披露`)
           }
         } else {
-          errors.push(`${taskId}: base..head（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}）无任何代码变更 — 评审了一个零改动的任务，review 疑似伪造`)
+          const scopeNote = Array.isArray(review.diffPaths) && review.diffPaths.length > 0
+            ? `（diffPaths 路径限定切片为空——统一 commit 模式下 diffPaths 应为本 task 的 allowed_paths；task 确未实现请把 verdict 回 fail）`
+            : ''
+          errors.push(`${taskId}: base..head（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}）无任何代码变更 — 评审了一个零改动的任务，review 疑似伪造${scopeNote}`)
           continue
         }
       }
@@ -590,6 +606,8 @@ function parsePorcelainFiles(statusOut) {
  *   1. base/head 必须是仓库中可解析的真实 commit
  *   2. base..head 的 diff 不能为空（评审一个零改动的"任务"无意义）
  *   3. review.changedFiles（如提供）必须与实际 diff 文件有交集
+ * 带 diffPaths（统一 commit 模式）时 2/3 在 `base..head -- diffPaths` 的路径限定切片上跑
+ * （坑 task-review-unified-commit-scope）：整变更区间下机器可验「本 task 切片非空」。
  *
  * git 环境不可用（非 git 仓库 / git 缺失）时返回 unavailable，由调用方降级为
  * warning——不因环境问题误杀，但记录在输出中。
@@ -694,9 +712,23 @@ export function verifyReviewGitEvidence(review, gitDir, cache = null) {
   } catch {}
   diffFiles = [...new Set(diffFiles)].filter(Boolean)
 
+  // ── diffPaths 路径限定切片（坑 task-review-unified-commit-scope，2026-09-01 实证）──
+  // 主代理统一 commit（全部 task 一个 commit）下 per-task 提交区间不存在，10 个 task 的
+  // review 只能共用同一对 base..head（整变更区间）——任务边界此前只靠 changedFiles「归属
+  // 说明」，本函数无法机器验证「本 task 的切片非空」。diffPaths（=task 的 allowed_paths）
+  // 把 emptyDiff/交叉比对收窄到切片：统一 commit 模式成为一等公民（per-task commit 模式
+  // 不填 diffPaths，行为零变化）。切片在 commit diff ∪ working-tree 并集之后过滤（与
+  // 归属口径同源：generateTaskReviewDrafts 的 allowed_paths 过滤用 pathMatches）。
+  const scopePaths = Array.isArray(review.diffPaths) && review.diffPaths.length > 0
+    ? review.diffPaths.filter(p => typeof p === 'string' && p.trim())
+    : null
+  const scopeNote = scopePaths ? `，diffPaths 切片 ${scopePaths.length} 路径` : ''
+  if (scopePaths) diffFiles = diffFiles.filter(f => scopePaths.some(p => pathMatches(f, p)))
+
   const emptyDiff = diffFiles.length === 0
 
-  // changedFiles 交叉比对：完全不相交 = review 描述的改动与实际 diff 无关（diffFiles 已含 working-tree）
+  // changedFiles 交叉比对：完全不相交 = review 描述的改动与实际 diff 无关（diffFiles 已含 working-tree，
+  // 有 diffPaths 时已收窄为路径限定切片）
   if (!emptyDiff && Array.isArray(review.changedFiles) && review.changedFiles.length > 0) {
     // 注记剥离（坑 changedfiles-annotation-suffix-mismatch，2026-08-22 实证：changedFiles 带
     // 「src/a.js（新增）」类注记后缀被判完全不相交，agent 用正则修还贪婪吞了路径段两轮才对）。
@@ -715,8 +747,9 @@ export function verifyReviewGitEvidence(review, gitDir, cache = null) {
       return diffSet.has(nf) || diffFiles.some(d => d.endsWith(nf) || nf.endsWith(d))
     })
     if (!hasOverlap) {
-      errors.push(`changedFiles 与实际 git diff（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}，${diffFiles.length} 个文件）完全不相交 — review 内容与代码变更无关。` +
-        `检查：changedFiles 必须是纯文件路径（注记/说明写 reviewerNotes，不拼进路径数组）；路径拼写与 diff 对照`)
+      errors.push(`changedFiles 与实际 git diff（${review.base.slice(0, 8)}..${review.head.slice(0, 8)}${scopeNote}，${diffFiles.length} 个文件）完全不相交 — review 内容与代码变更无关。` +
+        `检查：changedFiles 必须是纯文件路径（注记/说明写 reviewerNotes，不拼进路径数组）；路径拼写与 diff 对照` +
+        (scopePaths ? `；diffPaths 是否覆盖了 changedFiles 所在路径（切片按 diffPaths 过滤）` : ''))
     }
   }
 
@@ -1218,6 +1251,11 @@ export async function generateTaskReviewDrafts({ changeName, cwd, platformOpts =
       base: taskBase,
       head: taskHead,
       changedFiles: taskChangedFiles,
+      // 统一 commit 模式（坑 task-review-unified-commit-scope）：base..head 是整变更区间时，
+      // diffPaths 把证据校验切片收窄到本 task 的 allowed_paths。仅在有归属切片时带
+      // （无归属草稿 changedFiles 为空，带 diffPaths 会让切片空 → emptyDiff 误判伪造，
+      // 与「留给 agent 复核升级」的草稿语义冲突）。
+      ...(allowedPaths.length > 0 ? { diffPaths: allowedPaths } : {}),
       specVerdict: 'cannot_verify',
       qualityVerdict: 'cannot_verify',
       requiredEvidence: ['auto-generated draft: 待 agent 对照 ' + taskId + ' brief + diff 复核后升级为 pass/fail'],
@@ -1378,6 +1416,14 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
     merged.base = taskBase
     merged.head = taskHead
     merged.changedFiles = taskChangedFiles
+    // diffPaths（统一 commit 模式，坑 task-review-unified-commit-scope）：与草稿同口径——仅
+    // 有归属切片（taskChangedFiles 非空）时带 allowed_paths，空归属不带（防切片恒空 →
+    // emptyDiff 误判伪造）。
+    if (taskChangedFiles.length > 0 && allowedPaths.length > 0) {
+      merged.diffPaths = allowedPaths
+    } else {
+      delete merged.diffPaths
+    }
     if (draftRepo) merged.repo = draftRepo
 
     let verdictTouched = false
@@ -1403,6 +1449,7 @@ export async function adoptTaskReviewMechanics({ changeName, cwd, platformOpts =
       || prev.base !== merged.base
       || prev.head !== merged.head
       || JSON.stringify(prev.changedFiles ?? null) !== JSON.stringify(merged.changedFiles)
+      || JSON.stringify(prev.diffPaths ?? null) !== JSON.stringify(merged.diffPaths ?? null)
       || prev.repo !== merged.repo
 
     try {

package/src/taskcard.js

@@ -55,7 +55,9 @@ function yamlScalar(v) {
  *
  * 硬校验 9 字段（plan-postcheck feasibility）+ 规范字段全部就位，占位符由子代理 Edit 填充；
  * 可选字段（provides/expects_from/related_tests）默认不生成——缩小 YAML 出错面，何时加的
- * 判据写在文件尾注释（规则详情见 templates/prompts/taskcard-rules.md）。
+ * 判据写在文件尾注释（规则详情见 templates/prompts/taskcard-rules.md）。例外：target_files
+ * 预置空占位注释行（[] + 行内 # 注释）——占位符硬拦基于 taskcard-placeholders.js 的封闭
+ * 字面清单，本行值与注释刻意不含任何占位标记字面量，不会被 plan --done 拦截。
  * 字符串只含 \n：writeFileSync 直写不经任何行尾转换，Windows 下天然 LF 安全。
  * title/title_zh/author 经 yamlScalar 转义（自由文本防 YAML 指示符炸解析）。
  *
@@ -99,6 +101,7 @@ requirement_ids: ${fm.requirement_ids}
 decision_ids: ${fm.decision_ids}
 allowed_paths:
   - src/example/file.ts
+target_files: []  # 可选：本 task 计划改动的文件（对账用精确路径清单，格式见下方注释；不填保留 []）
 goal: >
   一句话说明这个 task 要做什么、为什么。
 implementation:
@@ -119,6 +122,10 @@ constraints:
      勿用 Write 整文件重写——会引入 CRLF 行尾/漏闭合 ---/漏字段回归。
      ⚠️ plan --done 硬校验会拦截未替换的占位符（FR-XX / D-XXX / src/example/file.ts /
      一句话说明这个 task / 具体步骤 1 / 可验证的验收条件 1 / 边界约束 1）——占位符视同缺字段。
+     target_files 格式（可选，对账用精确文件级意图声明，与 allowed_paths 语义不同）：
+                    精确文件路径（仓根相对、正斜杠），当前不存在、将由本 task 新建的文件加
+                    NEW: 前缀（如 NEW:src/foo.js）；禁 glob（src/**）、禁目录前缀（src/dir/）、
+                    禁绝对路径；无明确文件级意图时保留 [] 占位行不动。
      可选字段按需插进上方 frontmatter（规则见 taskcard-rules）：
      repo:          仅跨仓 task 填（local.yaml repos: 注册的仓 key；缺省=main。allowed_paths 相对该仓根写，
                     禁止带仓库名前缀/绝对路径——review 对账按仓根相对路径匹配，带前缀永不命中）