sillyspec 3.25.5 → 3.25.6

package/.claude/skills/sillyspec-brainstorm/SKILL.md

@@ -48,7 +48,7 @@ sillyspec run brainstorm --done --answer "..." --output "..."    # 一步完成
 
 某些步骤（如"对话式探索与需求澄清"）需要用户输入。两种方式：
 
-> 自动去重：若前置 step 已对同一问题（waitReason 归一化后相同，如"确认设计方案" vs "最终确认设计方案"）确认过，后续重复 wait 会自动跳过，无需再 `--wait`。
+> 自动去重：若前置 step 已对同一问题（waitReason 归一化后相同）确认过，后续重复 wait 会自动跳过，无需再 `--wait`。
 
 - **方式一（推荐）**：AI 自行与用户交互后，一步完成：
   ```bash

package/.claude/skills/sillyspec-scan/SKILL.md

@@ -38,22 +38,27 @@ sillyspec run scan --reset                     # 重置阶段（从头开始）
 
 | 参数 | 说明 |
 |---|---|
-| `--deep` | 强制 deep 扫描 profile（完整流程，不按规模裁剪） |
+| `--quick` | 强制 quick profile（快速接入，仅 4 份核心文档，0 子代理） |
+| `--standard` | 强制 standard profile（压缩步骤，最多 1 子代理） |
+| `--deep` | 强制 deep profile（完整流程，不按规模裁剪） |
 | `--force-rescan` | 覆盖已有 scan 文档的保护（默认覆盖需 source_commit/updated_at 匹配） |
 
-### scanProfile（按项目规模自动裁剪）
+### scanProfile（显式选择优先，否则按规模自动裁剪）
 
-CLI 根据源码规模自动选择 profile，无需手动指定：
+可用 `--quick` / `--standard` / `--deep` **显式指定 profile**（三档互斥，优先于自动判定）。
+不带 flag 时 CLI 按源码规模自动选择：
 
 | profile | 触发条件 | 行为 |
 |---|---|---|
-| quick | ≤30 文件 且 ≤80KB 且 ≤3 项目 | 3 步，0 子代理，5 份核心文档 |
-| standard | ≤200 文件 且 ≤800KB | 压缩步骤，最多 1 子代理 |
-| deep | 大项目或 `--deep` | 完整流程 |
+| quick | `--quick` 或 ≤30 文件 且 ≤80KB 且 ≤3 项目 | 3 步，0 子代理，4 份核心文档 |
+| standard | `--standard` 或 ≤200 文件 且 ≤800KB | 压缩步骤，最多 1 子代理 |
+| deep | `--deep` 或 大项目 | 完整流程 |
+
+> **平台快速接入**：对大项目用 `sillyspec run scan --quick`（含平台参数 `--spec-root`/`--workspace-id`/`--scan-run-id`）只生成 4 份核心文档完成接入，后续 `sillyspec run scan --deep` 覆盖升级为完整 7 份。quick 文档 frontmatter 标 `scan_depth: quick`，深度扫描识别后允许覆盖。
 
 ### post-check
 
-scan 完成时 CLI 自动校验 7 份文档齐全。缺失会设状态为 `failed_post_check`，阻断进入主流程下游（brainstorm/plan 等），需修复后重跑 scan。
+scan 完成时 CLI **按 profile 校验文档齐全**：quick 模式只要求 4 份核心文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE），standard/deep 要求完整 7 份。缺失会设状态为 `failed_post_check`，阻断进入主流程下游（brainstorm/plan 等），需修复后重跑 scan。quick 模式带一条 informational warning（`quick_profile_notice`），状态落 `completed_with_warnings`，不阻断完成。
 
 ## 阶段流转
 

package/.claude/skills/sillyspec-verify/SKILL.md

@@ -43,7 +43,7 @@ verify 是只读阶段（**禁止改代码/改 git 状态**，只检查 + 写报
 
 - **必须产出 `verify-result.md`**——不存在则阻断完成（不能跳过报告直接 `--done`）
 - **结论为 `FAIL` 则阻断完成**——不能带着 FAIL 标记 verify 完成
-- **`integration-critical` / `deployment-critical` 变更**（design/plan 含 daemon/session/lease/lifecycle 等关键词）：结论 PASS WITH NOTES 降级为 FAIL，必须有真实集成证据（Runtime Evidence section）
+- **`integration-critical` / `deployment-critical` 变更**（design/plan 含 daemon/session/lease/lifecycle 等关键词）：结论 PASS WITH NOTES 降级为 FAIL，必须有真实集成证据（Runtime Evidence section）——该证据为 Agent 自报告，CLI 仅校验其字面存在、不独立运行时核验，须真实执行过
 - `verify-required-evidence.json`（execute 写入）中每条 missing evidence → 阻断
 
 被阻断时 CLI 打印 ❌ 校验失败，不会提示"验证通过"。修复 `verify-result.md` 后重新 `--done`。
@@ -59,7 +59,7 @@ PASS / PASS WITH NOTES / FAIL      ← 必须有结论章节（标题含"结论/
 ## 探针结果
 ## 测试结果
 ## 变更风险等级
-## Runtime Evidence（integration/deployment-critical 必填）
+## Runtime Evidence（integration/deployment-critical 必填；自报告，CLI 仅字面校验、不独立核验）
 ```
 
 ## 阶段流转

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.25.5",
+  "version": "3.25.6",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/change-list.js

@@ -81,6 +81,43 @@ const FILE_LIST_SECTION_RE = /^#{2,3}\s*(?:\d+[.)]\s*)?(文件变更清单|变
  */
 const EXCLUDE_SUBSECTION_RE = /不修改|不变|保留|无变更|未变更|不改动|暂不|暂缓|暂定|待定|后续|未改|无需|不涉及/
 
+/**
+ * operation 词→归一化标签。design 清单「操作」列 cell 与分类列表子标题共用。
+ * 用途：verify 删除探针对账——声明「新增/修改」却整文件删除 = 高风险信号。
+ */
+const OP_KEYWORDS = [
+  { re: /^(新增|新建|创建|添加|add|new|create)$/i, op: '新增' },
+  { re: /^(修改|更新|调整|改动|变更|重写|modify|update|change)$/i, op: '修改' },
+  { re: /^(删除|移除|去掉|remove|delete|drop)$/i, op: '删除' },
+  { re: /^(重命名|改名|rename|move)$/i, op: '重命名' },
+]
+function classifyOperation(raw) {
+  if (!raw) return null
+  const hit = OP_KEYWORDS.find(k => k.re.test(raw.trim()))
+  return hit ? hit.op : null
+}
+
+/**
+ * 分类列表子标题 → operation（`### 删除文件` → '删除'）。不命中返回 null。
+ * ⚠️ 调用方必须先判 EXCLUDE_SUBSECTION_RE：「### 不修改文件」含「修改」二字，
+ *    会被此处误匹配为「修改」——exclude 永远优先，命中 exclude 不跑 OP 映射。
+ */
+const OP_SUBSECTION_RE = [
+  { re: /新增|新建|创建/, op: '新增' },
+  { re: /修改|更新|改动|重写/, op: '修改' },
+  { re: /删除|移除|去掉/, op: '删除' },
+  { re: /重命名|改名/, op: '重命名' },
+]
+function classifySubsectionOp(title) {
+  const hit = OP_SUBSECTION_RE.find(k => k.re.test(title))
+  return hit ? hit.op : null
+}
+
+/** 表头列定位：cell 整体匹配操作类列名（与 isPathHeaderCell 对偶，用于定位 operation 列） */
+function isOperationHeaderCell(c) {
+  return /^(操作|类型|变更类型|改动类型|变更|operation|type|action|op)$/i.test(c)
+}
+
 function isPlaceholder(p) {
   return !p || p === '—' || p === '-' || /^(n\/?a|无|none|-+)$/i.test(p)
 }
@@ -103,23 +140,33 @@ function looksLikePath(p) {
 }
 
 /**
- * 从 design.md 解析文件变更清单。兼容两种真实写法：
+ * 「顺带修复」标记：design §6 清单里标注的、不属本次变更 task 边界但合规修的预存债文件
+ * （CLAUDE.md 规则20 鼓励）。assess 的 allowed_paths 校验对 incidental 文件豁免（坑
+ * worktree-execute-apply-friction 坑1/4）。标记载体：表格「说明」列写「顺带修复：xxx」，
+ * 或路径 cell / 列表项的括号注释「（顺带修复）」。
+ */
+const INCIDENTAL_RE = /顺带修复|附带修复|顺带|drive-?by|incidental/i
+
+/**
+ * 从 design.md 解析文件变更清单（含 incidental 标记）。兼容两种真实写法：
  *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
  *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
  * 表头列顺序自适应（定位「文件/路径/file/path」列，列顺序写反时不会把操作名当路径）；
  * 忽略 `.sillyspec/` 与占位符（`—`/`-`/`N/A`/`无`）；「不修改/暂缓」子段下的路径会被排除；
- * CRLF 容错。
+ * CRLF 容错。incidental 嗅探：表格非路径列（说明列）+ 路径 cell 原始值（剥注释前的括号内容）+ 列表项原文。
+ *
+ * 内核函数：parseFileChangeList（Set 包装，向后兼容）与 parseFileChangeListDetailed 共用，
+ * 单一真相源，避免两处各自重写清单解析漂移。
  * @param {string} designMdPath - design.md 文件路径
- * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
+ * @returns {Array<{ path: string, operation: string|null, incidental: boolean }>}（顺序按首次出现，exclude 子段移除）
  */
-export function parseFileChangeList(designMdPath) {
-  const result = new Set()
-  if (!designMdPath || !existsSync(designMdPath)) return result
+function _parseFileListDetailed(designMdPath) {
+  if (!designMdPath || !existsSync(designMdPath)) return []
 
   const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
 
   const sectionMatch = content.match(FILE_LIST_SECTION_RE)
-  if (!sectionMatch) return result
+  if (!sectionMatch) return []
 
   // 从标题后开始，截取到下一个 ## 标题或文件末尾
   const afterSection = content.slice(sectionMatch.index + sectionMatch[0].length)
@@ -131,13 +178,24 @@ export function parseFileChangeList(designMdPath) {
   const lines = relevantContent.split('\n')
   let headerSkipped = false
   let pathColIdx = 1            // 默认第 2 列；解析表头后可重定位
+  let opColIdx = -1             // 操作列下标（表头扫描后定位；-1 = 无操作列 → operation=null）
   let listMode = 'include'      // include | exclude（分类列表子段）
+  let currentOp = null          // 分类列表子标题推导的 operation（表格模式不用）
+  const entries = new Map()     // path -> { path, operation, incidental }（exclude 子段 delete）
 
   for (const line of lines) {
     // 分类列表子标题：### 新增文件 / ### 修改文件 / ### 不修改文件
     const subHeader = line.match(/^###\s+(.+?)\s*$/)
     if (subHeader) {
-      listMode = EXCLUDE_SUBSECTION_RE.test(subHeader[1]) ? 'exclude' : 'include'
+      // ⚠️ EXCLUDE 优先：「### 不修改文件」含「修改」二字，会被 classifySubsectionOp 误匹配。
+      //    先判 exclude 词集，命中则 exclude 且 currentOp=null，绝不跑 OP 映射。
+      if (EXCLUDE_SUBSECTION_RE.test(subHeader[1])) {
+        listMode = 'exclude'
+        currentOp = null
+      } else {
+        listMode = 'include'
+        currentOp = classifySubsectionOp(subHeader[1])
+      }
       continue
     }
 
@@ -152,6 +210,9 @@ export function parseFileChangeList(designMdPath) {
         // 表头列定位：找「文件/路径/file/path」列，找不到保持默认第 2 列
         const idx = cells.findIndex(isPathHeaderCell)
         if (idx >= 0) pathColIdx = idx
+        // 操作列定位：非路径列里找操作类列名（「操作/类型/operation」），找不到 opColIdx 保持 -1
+        const opIdx = cells.findIndex((c, i) => i !== pathColIdx && isOperationHeaderCell(c))
+        if (opIdx >= 0) opColIdx = opIdx
         continue
       }
 
@@ -160,7 +221,13 @@ export function parseFileChangeList(designMdPath) {
       if (/^(新增|修改|删除|重命名|new|modify|update|delete|create|rename)$/i.test(filePath)) continue
       if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
       if (!looksLikePath(filePath)) continue // 脏描述兜底：丢弃非路径自由文本（防虚高 fileCount）
-      result.add(filePath)
+      // operation：操作列 cell 分类（无操作列 → null）
+      const operation = opColIdx >= 0 ? classifyOperation(cells[opColIdx] || '') : null
+      // incidental：说明列（非路径列的所有 cell）+ 路径 cell 原始值（剥注释前的括号内容）
+      const incidental = cells.some((c, i) => i !== pathColIdx && INCIDENTAL_RE.test(c))
+        || INCIDENTAL_RE.test(cells[pathColIdx] || '')
+      if (listMode === 'exclude') { entries.delete(filePath); continue }
+      entries.set(filePath, { path: filePath, operation, incidental })
       continue
     }
 
@@ -170,10 +237,31 @@ export function parseFileChangeList(designMdPath) {
       const filePath = normalizePath(listItem[1])
       if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
       if (!looksLikePath(filePath)) continue // 脏描述兜底
-      if (listMode === 'exclude') result.delete(filePath)
-      else result.add(filePath)
+      const incidental = INCIDENTAL_RE.test(listItem[1])
+      if (listMode === 'exclude') { entries.delete(filePath); continue }
+      entries.set(filePath, { path: filePath, operation: currentOp, incidental })
     }
   }
 
-  return result
+  return [...entries.values()]
+}
+
+/**
+ * 从 design.md 解析文件变更清单（路径集合，向后兼容）。
+ * @param {string} designMdPath - design.md 文件路径
+ * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
+ */
+export function parseFileChangeList(designMdPath) {
+  return new Set(_parseFileListDetailed(designMdPath).map(e => e.path))
+}
+
+/**
+ * 从 design.md 解析文件变更清单（含 operation + incidental 标记）。
+ * operation 供 verify 删除探针对账（声明「新增/修改」却整文件删除 = 高风险）；
+ * incidental 供 assess allowed_paths 豁免。
+ * @param {string} designMdPath - design.md 文件路径
+ * @returns {Array<{ path: string, operation: string|null, incidental: boolean }>}
+ */
+export function parseFileChangeListDetailed(designMdPath) {
+  return _parseFileListDetailed(designMdPath)
 }

package/src/constants.js

@@ -81,6 +81,17 @@ export const SCAN_REQUIRED_DOCS = Object.freeze([
   'PROJECT.md',
 ])
 
+// ── scan quick profile 必需文档子集（4 份核心文档）──
+// quick 档（--quick 显式 或 小项目自动判定）只生成这 4 份；scan-postcheck 按 profile 取清单：
+// mode==='quick' → SCAN_REQUIRED_DOCS_QUICK，否则 → SCAN_REQUIRED_DOCS（7 份）。
+// 由 scan-postcheck.js + complete-handlers.js 透传的 scanProfile.mode 决定取哪份。
+export const SCAN_REQUIRED_DOCS_QUICK = Object.freeze([
+  'PROJECT.md',
+  'ARCHITECTURE.md',
+  'CONVENTIONS.md',
+  'STRUCTURE.md',
+])
+
 // ── 辅助 stage 清单（stage-contract 转移规则 与 stages/index 注册表 共用单一真相源）──
 // 曾在 stage-contract.js 与 stages/index.js 逐字重复定义，新增/调整辅助 stage 需同步改两处
 // 易分叉。现收敛一处。（注意：主流程序 STAGE_ORDER/mainFlowStages/flowStages 语义不同、

package/src/index.js

@@ -54,7 +54,7 @@ SillySpec CLI — 规范驱动开发工具包
              --allow-new                 允许新增文件（默认禁止）
              --force-baseline            允许覆盖 baseline 受保护文件
              --confirm                   完成时确认接受变更审计
-    scan:    --deep                      强制 deep 扫描 profile
+    scan:    --quick | --standard | --deep   显式选择 profile（优先于规模自动判定；三档互斥）
              --force-rescan              覆盖已有 scan 文档保护
     archive: --confirm                   归档确认（必须）
     auto:    --mode <模式>               显式指定流程模式

package/src/run/command.js

@@ -23,7 +23,7 @@ import { join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -195,6 +195,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     console.error('   这些动作互斥，请只保留其中一个再重试。')
     process.exit(2)
   }
+  // scan profile flag 互斥：--quick/--standard/--deep 同时给≥2 个语义矛盾（computeScanProfile
+  // 只取首个命中、其余静默忽略 → agent 以为生效的其实没生效，与 STEP_ACTIONS 同类风险）。
+  const PROFILE_FLAGS = [
+    ['--quick', flags.includes('--quick'), 'quick profile（快速接入，4 份核心文档）'],
+    ['--standard', flags.includes('--standard'), 'standard profile（压缩步骤）'],
+    ['--deep', flags.includes('--deep'), 'deep profile（完整扫描）'],
+  ]
+  const activeProfiles = PROFILE_FLAGS.filter(([, v]) => v)
+  if (activeProfiles.length >= 2) {
+    console.error('❌ scan profile 参数冲突（同时只能指定一个）：')
+    for (const [name, , desc] of activeProfiles) console.error(`   ${name} — ${desc}`)
+    console.error('   这三档互斥，请只保留其中一个再重试。')
+    process.exit(2)
+  }
   // 注：--non-interactive 与 --interactive 的冲突在 index.js 检测（--interactive 被 index.js
   // 作为全局 flag 吞掉、不透传到此处，故 isInteractive 在此恒为 false）。
   const waitReason = getFlagValue('--reason')
@@ -279,6 +293,17 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // runCommand 后续所有 .sillyspec/ 操作必须用 specBase
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
+  // 漂移提醒:cwd 祖先链 ≥2 个 .sillyspec = monorepo 多实例,当前命中的「最近」实例
+  // 可能不是用户意图的项目(如 cd 进被独立 scan 的子项目跑测试后忘回根)。
+  // 平台模式 / 显式 --spec-dir 跳过(已明确指定,无歧义)。仅提醒不阻断。
+  if (!platformOpts.specRoot && !specDir) {
+    const ancestorCount = countAncestorSpecDirs(cwd)
+    if (ancestorCount >= 2) {
+      console.warn(`⚠️  检测到祖先链有 ${ancestorCount} 个 .sillyspec 实例(monorepo 多实例),当前使用: ${specBase}`)
+      console.warn(`    若意图是另一个项目:cd 回该项目根,或用 --spec-dir <根>/.sillyspec 显式指定。`)
+    }
+  }
+
   // 平台模式：首次接入时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
   // 只在「首次」执行一次——用 cwd 下的 .sillyspec-platform-cleaned 标记文件记录已处理，
@@ -437,7 +462,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--files', '--allow-new', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
     '--reopen', '--from-step', '--mode',
-    '--deep', // F1: scan-profile.js 从 argv 读 --deep，文档化(index.js help)但此前 knownFlags 漏列→被拒
+    '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）
   ])
   for (let i = 0; i < flags.length; i++) {
     const f = flags[i]
@@ -497,6 +522,21 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2) // 用法错（execute 必须显式 --change）→ exit 2
   }
 
+  // worktree 副本漂移硬守卫(坑 worktree-execute-spec-drift):specBase 命中 worktree 内 .sillyspec
+  // checkout 副本 → 进度/产出会写分裂库。必须在 validateChangeExists 之前——副本里 change 目录真实
+  // 存在,存在性校验会被骗放行。覆盖 plan/execute/verify/archive(validateChangeExists 同 Set):
+  // 都要求 change 已存在、都被副本骗、都写 .sillyspec 资产(archive 尤甚:在副本里移动 change+commit)。
+  // 平台模式/显式 --spec-dir 跳过(已明确指定,与 line~285 warn / ~529 quick 守卫条件对齐)。
+  if (!platformOpts.specRoot && !specDir
+      && ['plan', 'execute', 'verify', 'archive'].includes(stageName)) {
+    const wt = detectWorktreeSpecDrift(specBase)
+    if (wt) {
+      console.error(`❌ ${wt.message}`)
+      console.error(`   当前 cwd=${cwd}，命中的 spec=${specBase}。`)
+      process.exit(2) // 环境错（cwd/spec 漂移）→ exit 2
+    }
+  }
+
   // --change 变更名存在性校验（治 cwd 漂移误匹配，缺陷 execute-in-place-windows-pitfalls 坑5）：
   // 必须在 pm.read/initChange 之前——initChange 会为 --change 指定的新名字创建 changes/ 目录，
   // 校验若在其后则目录已存在、永远通过。用原始 changeName（--change 参数），覆盖 plan/execute/
@@ -509,6 +549,21 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2) // 环境错（cwd/spec 漂移）→ exit 2
   }
 
+  // quick 专用 cwd 漂移 fail-fast 守卫（坑 quick-cwd-drift-splits-specdir）：
+  // quick 被 validateChangeExists 的 sessionId 豁免（quick-<8hex> 不在 changes/ 下），漂移时除上方
+  // countAncestorSpecDirs 的 warn 外无硬守卫 → 无声分裂（progress/artifact/QUICKLOG 落子项目、根
+  // 会话停滞）。这里补：当前 specBase 无本 session guard、但祖先链别处有 = 跨 specDir 漂移 → fail-fast。
+  // 平台模式/显式 --spec-dir 跳过（specBase 已明确，与 line~285 warn 条件对齐）。
+  if (stageName === 'quick' && changeName && /^quick-[0-9a-f]{8}$/.test(changeName)
+      && !platformOpts.specRoot && !specDir) {
+    const drift = detectQuickSessionDrift(cwd, specBase, changeName)
+    if (drift) {
+      console.error(`❌ ${drift.message}`)
+      console.error(`   当前 cwd=${cwd}，命中的 spec=${specBase}。`)
+      process.exit(2) // 环境错（cwd/spec 漂移）→ exit 2
+    }
+  }
+
   let progress = await pm.read(cwd, changeName)
 
   if (!progress) {

package/src/run/complete-handlers.js

@@ -769,6 +769,9 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
         source_commit_error: sourceCommit === null ? (sourceCommitError || 'unknown') : undefined,
         generated_at: new Date().toISOString(),
         schema_version: 1,
+        scan_profile: stageData.scanProfile
+          ? { mode: stageData.scanProfile.mode, reason: stageData.scanProfile.reason }
+          : null,
         postcheck_result_path: null,
         workflow_runs_dir: platformOpts.runtimeRoot
           ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown', 'workflow-runs')
@@ -797,6 +800,7 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
           projectListParsed: stageData.scanMeta?.projectListParsed ?? null,
           manifestWritten: stageData.scanMeta?.manifestWritten ?? null,
         },
+        scanProfile: stageData.scanProfile || null,
       })
       printScanPostCheckResult(postResult)
 
@@ -871,7 +875,7 @@ export async function handleScanStageCompleted({ stageName, currentIdx, cwd, pro
   // 非 platform 模式 scan 也做轻量 post-check + 结构化输出
   if (stageName === 'scan' && !platformOpts.specRoot && !platformOpts.runtimeRoot) {
     const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('../scan-postcheck.js')
-    const postResult = runScanPostCheck({ cwd, specDir: null, outputText })
+    const postResult = runScanPostCheck({ cwd, specDir: null, outputText, scanProfile: stageData.scanProfile || null })
     printScanPostCheckResult(postResult)
     // 结构化结果写入 .sillyspec/.runtime/
     const structured = formatStructuredResult(postResult, { source_root: cwd })

package/src/run/complete.js

@@ -18,7 +18,7 @@ import { join } from 'node:path'
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, appendFileSync, statSync } from 'node:fs'
 import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions } from './shared.js'
 import { outputStep } from './prompt.js'
-import { enforceDepsGate, runStageCompletionGates } from './gates.js'
+import { enforceDepsGate, enforceReviewJsonGate, runStageCompletionGates } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact, handleExecuteWorktreeCleanup, handleScanStageCompleted } from './complete-handlers.js'
 import { stageRegistry } from '../stages/index.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
@@ -174,6 +174,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 
   // ── execute deps 验证硬门（change 2026-06-28-worktree-deps-provision）──
   await enforceDepsGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
+  // review.json 字段硬门（坑 review-json-field-gap）：已勾 [x] task 的 review.json 必须 schema 完整，
+  // 提前到每次 --done 校验（而非等 Task Review Gate 在整阶段收尾才暴露，迫使用户事后批量补）。
+  await enforceReviewJsonGate(stageName, cwd, changeName, steps[currentIdx], steps, currentIdx, specBase, platformOpts)
 
   steps[currentIdx].status = 'completed'
   steps[currentIdx].completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
@@ -226,6 +229,22 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     if (_bf.batched && _bf.aligned > 0) {
       console.log(`\n🚀 execute 批量完成：plan 全勾 + 代码核验通过，一次性补完 ${_bf.aligned} 个剩余 step → 进入阶段完成分支`)
     }
+
+    // per-task review 草稿兜底（坑 worktree-execute-apply-friction 坑2）：主 agent 直接实现模式
+    // 无子代理 review 落盘 → Task Review Gate 报缺 review.json 阻断。每次 execute --done 跑（幂等，
+    // 已存在跳过），据 git diff base..head 按 allowed_paths 归属生成 cannot_verify 草稿，进 gate 前就位。
+    try {
+      const { generateTaskReviewDrafts } = await import('../task-review.js')
+      const _drafts = await generateTaskReviewDrafts({ changeName, cwd, platformOpts })
+      if (_drafts.generated > 0) {
+        console.log('   📄 自动补写 ' + _drafts.generated + ' 个 per-task review.json 草稿（cannot_verify，主 agent 实现模式兜底，需 agent 复核后升级为 pass/fail）')
+        if (_drafts.unattributed && _drafts.unattributed.length > 0) {
+          console.warn('   ⚠️ ' + _drafts.unattributed.length + ' 个变更文件未归属任何 task（顺带修复/非源码），草稿未覆盖：' + _drafts.unattributed.join(', '))
+        }
+      }
+    } catch (e) {
+      console.warn('   ⚠️ per-task review 草稿生成失败（不阻断 execute 完成）：' + (e && e.message ? e.message : e))
+    }
   }
 
   const nextPendingIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')

package/src/run/gates.js

@@ -96,6 +96,39 @@ export async function enforceDepsGate(stageName, cwd, changeName, step, steps, c
   }
   process.exit(1)
 }
+
+/**
+ * execute --done 硬门：已勾 [x] task 的 review.json 必须 schema 完整（坑 review-json-field-gap）。
+ *
+ * Task Review Gate（validateTaskReviews）只在 execute 整阶段完成时跑（complete.js 阶段完成分支的
+ * actualCompleted===actualTotal 守卫），单 task --done 不校验 → 子代理勾 checkbox 却漏写/漏字段
+ * review.json，要到收尾才暴露，用户被迫事后批量补。本门提前到每次 --done：校验 plan 里所有已勾
+ * task 的 review.json，缺字段/不存在/JSON 坏 → 置 step=blocked + exit(1)，与 enforceDepsGate 同范式。
+ * 未勾 task 不校验（还没做）。平台模式/无 marker/无 plan 时放行（下游 Task Review Gate 兜底）。
+ */
+export async function enforceReviewJsonGate(stageName, cwd, changeName, step, steps, currentIdx, specBase, platformOpts) {
+  if (stageName !== 'execute' || !changeName) return true
+  const runtimeRoot = platformOpts?.runtimeRoot || join(specBase, '.runtime')
+  const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+  const planPath = join(specBase, 'changes', changeName, 'plan.md')
+  if (!existsSync(runIdFile) || !existsSync(planPath)) return true
+  const executeRunId = readFileSync(runIdFile, 'utf8').trim()
+  const planContent = readFileSync(planPath, 'utf8')
+  const { validateCheckedTaskReviews } = await import('../task-review.js')
+  const result = validateCheckedTaskReviews({ planContent, runtimeRoot, executeRunId })
+  if (result.ok) return true
+  if (steps && steps[currentIdx]) steps[currentIdx].status = 'blocked'
+  console.error('❌ ── review.json 字段校验阻断（本次 --done 未完成，进度未推进）──')
+  console.error('   已勾选 [x] 的 task review.json 不完整（铁律：勾 checkbox 前必须先写完整 review.json）:')
+  for (const f of result.failures) {
+    const kindLabel = f.kind === 'missing' ? 'review.json 不存在' : (f.kind === 'parseError' ? 'JSON 解析失败' : '字段缺失')
+    console.error(`   • ${f.taskId}（${kindLabel}）: ${f.reviewPath}`)
+    for (const e of f.errors) console.error(`       - ${e}`)
+  }
+  console.error('   修复：补全上述 review.json 字段后重跑 execute --done。')
+  process.exit(1)
+}
+
 /**
  * 阶段完成校验失败时回滚状态。
  *
@@ -183,6 +216,10 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     const { runVerifyParityCheck, printVerifyParityCheck } = await import('../verify-postcheck.js')
     const parityCheck = runVerifyParityCheck({ cwd, specBase, changeName, runtimeRoot: platformOpts?.runtimeRoot })
     printVerifyParityCheck(parityCheck)
+    // ── 删除探针（advisory，不阻断）：切斯特顿栅栏护栏，用 git 事实对账静默删除代码 ──
+    const { runVerifyDeletionCheck, printVerifyDeletionCheck } = await import('../verify-postcheck.js')
+    const deletionCheck = runVerifyDeletionCheck({ cwd, specBase, changeName })
+    printVerifyDeletionCheck(deletionCheck)
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
   }
 

package/src/run/quick-audit.js

@@ -34,7 +34,14 @@ export function printQuickAuditReview(review) {
       console.warn(`   - ${r}`)
     }
   } else {
-    console.log(`\n✅ quick 变更边界审计 — SAFE (变更 ${review.changedFiles.length} 个文件)`)
+    // 区分「本轮新增」（changedFiles，已扣前序 baseline）vs「累计暂存」（stagedTotal，全部未提交）。
+    // 仅当存在前序 baseline 残留（累计 > 本轮新增）时才追加括注，避免普通场景冗余。
+    const stagedTotal = typeof review.stagedTotal === 'number' ? review.stagedTotal : review.changedFiles.length
+    if (stagedTotal > review.changedFiles.length) {
+      console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件；累计暂存 ${stagedTotal} 个，含前序 baseline ${stagedTotal - review.changedFiles.length} 个未计入本轮)`)
+    } else {
+      console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件)`)
+    }
   }
 }
 

package/src/run/scan-profile.js

@@ -15,23 +15,36 @@ import { safeGit } from './shared.js'
 /**
  * 估算源码规模（文件数 + 字节数）—— 跨平台 Node 遍历，替代 Unix `find`（原生 Windows 无 find，
  * 原 find 失效会让所有 Windows 项目永远 fallback 到 standard profile）。
- * 扩展名与排除目录与原 find 命令逐字一致；maxFiles 封顶避免超大仓库遍历过久
- * （超限时 fileCount 已远超 quick/standard 阈值，不影响 profile 判定）。
+ * 扩展名限定源码后缀；skipDirs 排除依赖/构建产物/覆盖率等非源码目录；maxFiles 封顶避免超大仓库遍历过久
+ * （超限时 fileCount 已远超 quick/standard 阈值，不影响 profile 判定）；maxDepth 兜底防极深嵌套产物。
  */
-export function estimateSourceSize(cwd, maxFiles = 5000) {
+export function estimateSourceSize(cwd, maxFiles = 5000, maxDepth = 6) {
   const sourceExts = new Set(['.js','.ts','.tsx','.py','.java','.go','.rs','.rb','.php','.c','.cpp','.h','.jsx','.vue','.svelte'])
-  const skipDirs = new Set(['node_modules','.git','dist','build','__pycache__','.sillyspec','.claude'])
+  // skipDirs：排除依赖、版本控制、构建产物、覆盖率、临时目录等非源码目录。
+  // 原清单只排了 node_modules/.git/dist/build 等，漏了 .next/.nuxt/coverage/.svelte-kit 等构建产物，
+  // 导致带构建产物的小项目被产物里的海量 .js 拉高 fileCount/sourceBytes → 误判 deep。
+  const skipDirs = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', 'target',
+    '__pycache__', '.venv', 'venv',
+    '.next', '.nuxt', '.output', '.svelte-kit', '.astro', '.turbo', '.parcel-cache',
+    'coverage', '.nyc_output', '.vitest', '.cache',
+    'vendor', 'bower_components',
+    'dist-types',
+    '.sillyspec', '.claude',
+    'tmp', 'temp', '.tmp', 'logs',
+  ])
   let fileCount = 0
   let sourceBytes = 0
-  const stack = [cwd]
+  // stack 存 [dir, depth]：maxDepth 兜底，防极深嵌套的产物/生成目录在 skipDirs 漏网时被全遍历。
+  const stack = [[cwd, 0]]
   while (stack.length) {
-    const dir = stack.pop()
+    const [dir, depth] = stack.pop()
     let entries
     try { entries = readdirSync(dir, { withFileTypes: true }) }
     catch { continue }
     for (const e of entries) {
       if (e.isDirectory()) {
-        if (!skipDirs.has(e.name)) stack.push(join(dir, e.name))
+        if (!skipDirs.has(e.name) && depth < maxDepth) stack.push([join(dir, e.name), depth + 1])
       } else if (e.isFile() && sourceExts.has(extname(e.name))) {
         fileCount++
         try { sourceBytes += statSync(join(dir, e.name)).size } catch {}
@@ -49,8 +62,14 @@ export function estimateSourceSize(cwd, maxFiles = 5000) {
  * deep:    大项目或 --deep → 完整流程
  */
 export function computeScanProfile(cwd, platformOpts) {
-  // --deep 标志强制 deep
+  // 显式 profile flag 优先于自动判定（三档互斥由 command.js 检测；此处取首个命中即可）
   const flags = process.argv.slice(2)
+  if (flags.includes('--quick')) {
+    return { mode: 'quick', reason: '用户指定 --quick', maxAgentCalls: 0, maxDocs: 5 }
+  }
+  if (flags.includes('--standard')) {
+    return { mode: 'standard', reason: '用户指定 --standard', maxAgentCalls: 1, maxDocs: 8 }
+  }
   if (flags.includes('--deep')) {
     return { mode: 'deep', reason: '用户指定 --deep', maxAgentCalls: 4, maxDocs: 99 }
   }
@@ -115,7 +134,7 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
       status: 'pending',
       prompt: `## Quick Scan — 核心文档生成
 
-项目规模较小（quick profile），请一次性生成所有核心文档。
+当前为 quick profile（小项目自动判定 或 用户显式 --quick），一次性生成核心文档用于快速接入。
 
 ### 操作
 1. 读取项目结构和关键文件（package.json / pyproject.toml / README / 入口文件）
@@ -126,7 +145,7 @@ export function applyScanProfileSteps(stageData, profile, cwd, platformOpts) {
    - **STRUCTURE.md** — 目录树 + 模块说明
 3. 如发现子项目，注册到 \`{PROJECTS_ROOT}/\` 下
 
-每份文档头必须包含 frontmatter：\`author\` 和 \`created_at\`。
+每份文档 frontmatter 必须包含：\`author\`、\`created_at\`、\`scan_depth: quick\`（标记快速接入的浅层版本；后续深度扫描 --deep 会识别此标记并覆盖升级为完整文档）。
 
 ### ⛔ 硬约束
 - **严禁使用子代理（Agent/Task 工具）。** 所有文档在一个 turn 内完成。