sillyspec 3.25.4 → 3.25.6

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) {
@@ -884,7 +939,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     // Auto 模式下 brainstorm 使用 artifact-first 步骤
     if (stage === 'brainstorm') {
       const existingSteps = progress.stages?.brainstorm?.steps
-      const isAutoModeSteps = existingSteps?.length === 4 && existingSteps?.[0]?.name === '状态检查与上下文加载'
+      const isAutoModeSteps = existingSteps?.length === 4 && existingSteps?.[0]?.name === '进度确认与上下文加载'
       if (!isAutoModeSteps) {
         if (!progress.stages) progress.stages = {}
         progress.stages.brainstorm = {

package/src/run/complete-handlers.js

@@ -29,6 +29,7 @@ import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview } from './quick-audit.js'
 import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
+import { archiveDestDirName } from '../stage-contract.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -101,7 +102,8 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
   const archiveDir = join(changesDir, 'archive')
   const srcDir = join(changesDir, archiveChangeName)
   const date = new Date().toISOString().slice(0, 10)
-  const destDir = join(archiveDir, `${date}-${archiveChangeName}`)
+  const destName = archiveDestDirName(date, archiveChangeName)
+  const destDir = join(archiveDir, destName)
 
   if (!existsSync(srcDir)) {
     console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
@@ -157,7 +159,7 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
     console.warn(`⚠️  归档 worktree 清理失败（不阻断归档）: ${e.message}`)
   }
 
-  console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
+  console.log(`📦 已归档：${archiveChangeName} → archive/${destName}/`)
   return destDir
 }
 /**
@@ -767,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')
@@ -795,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)
 
@@ -869,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})
@@ -211,6 +214,39 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // execute Wave artifact（W6 Step6c 抽至 complete-handlers.js handleExecuteWaveArtifact）
   await handleExecuteWaveArtifact({ stageName, steps, currentIdx, changeName, specBase, cwd })
 
+  // execute 批量完成检测：plan 全勾 + 代码客观核验通过 → 剩余 step 一次性标 completed，
+  // 使本次 --done 直接进入阶段完成分支（治"3 Wave 做完仍逐次 +1、需重走 7 次 --done"）。
+  // 先按 review.json pass 自动勾 plan checkbox（复用 continueStep 同源逻辑），再判批量条件。
+  if (stageName === 'execute' && changeName) {
+    const _ac = await autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts })
+    if (_ac.autoChecked) {
+      console.log(`   ✅ 自动勾选 ${_ac.checkedCount} 个 task checkbox（基于 review.json pass）`)
+    }
+    if (_ac.skippedCount > 0) {
+      console.warn(`   ⚠️ ${_ac.skippedCount} 个 task 未勾（review.json 缺失/fail）→ 批量完成条件不满足，仍按单步推进`)
+    }
+    const _bf = await detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBase, steps })
+    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')
 
   if (nextPendingIdx === -1) {
@@ -349,6 +385,92 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 }
 
 // ── Step 调度兄弟函数（W6 Step7b-2 从 run.js 搬入：skip/wait/continue + formatWaitHistory）──
+/**
+ * plan.md checkbox 自动勾选：execute 完成 + 各 task review.json 双 verdict 非 fail → 自动勾选。
+ * 治本于"plan 全靠手动勾、易遗漏"——以 review.json pass 为客观依据勾选。供 continueStep 完成段
+ * 与 completeStep 的 execute 批量完成检测复用（避免两处复制）。
+ *
+ * @returns {{autoChecked:boolean, checkedCount:number, skippedCount:number, planTotal:number, planChecked:number}}
+ *   planTotal/planChecked 在调用方于本函数之后用 readPlanCheckboxStatus 重读（勾选已落盘）。
+ */
+async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
+  if (stageName !== 'execute' || !changeName) {
+    return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
+  }
+  try {
+    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const changeDir = join(specBaseLc, 'changes', changeName)
+    const planPath = join(changeDir, 'plan.md')
+    const runtimeRoot = platformOpts?.runtimeRoot || join(specBaseLc, '.runtime')
+    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    if (!existsSync(planPath) || !existsSync(runIdFile)) {
+      return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
+    }
+    const executeRunId = readFileSync(runIdFile, 'utf8').trim()
+    const planContent = readFileSync(planPath, 'utf8')
+    const { readReview } = await import('../task-review.js')
+    let checkedCount = 0
+    let skippedCount = 0
+    const updated = planContent.replace(/^(\s*[-*]\s*\[)\s(\]\s*task-\d+)/gim, (match, p1, p2) => {
+      const taskNum = match.match(/task-(\d+)/)[1].padStart(2, '0')
+      const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', `task-${taskNum}`, 'review.json')
+      const r = readReview(reviewPath)
+      if (r.ok && r.review?.specVerdict !== 'fail' && r.review?.qualityVerdict !== 'fail') {
+        checkedCount++
+        return `${p1}x${p2}`   // 勾选
+      }
+      skippedCount++
+      return match              // 不勾
+    })
+    if (checkedCount > 0) {
+      writeFileSync(planPath, updated)
+    }
+    return { autoChecked: checkedCount > 0, checkedCount, skippedCount }
+  } catch {
+    return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
+  }
+}
+
+/**
+ * execute 批量完成检测：plan.md 所有 task checkbox 已勾 + 代码客观核验非零变更 →
+ * 把剩余 pending/in-progress step 一次性标 completed，使 completeStep 本次 --done 即进入阶段完成
+ * 分支（而非逐次 +1）。治"3 Wave 全做完仍显示未开工、需重走 7 次 --done"。
+ * 复用现成能力：readPlanCheckboxStatus（plan 勾选状态）+ checkExecuteCodeEvidence（代码客观核验，
+ * 与 doctor --align-execute-progress 同源，D-002/D-004）。仅在 stageName==='execute' && changeName 触发。
+ *
+ * 安全门：plan 零 checkbox / 未全勾 / 代码零变更（unchanged）均不批量——信任 plan 声明但用代码核验兜底。
+ * @returns {Promise<{batched:boolean, aligned:number, reason?:string}>}
+ */
+async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBase, steps }) {
+  if (stageName !== 'execute' || !changeName) return { batched: false, aligned: 0 }
+  try {
+    const changeDir = join(specBase, 'changes', changeName)
+    const { total: planTotal, checked: planChecked } = pm.readPlanCheckboxStatus(changeDir)
+    if (planTotal === 0) return { batched: false, aligned: 0, reason: 'plan.md 无 task checkbox' }
+    if (planChecked < planTotal) {
+      return { batched: false, aligned: 0, reason: `plan 未全勾（${planChecked}/${planTotal}）` }
+    }
+    // plan 全勾 → 代码客观核验（防 plan 被手动勾伪造导致空完成）
+    const { checkExecuteCodeEvidence } = await import('../stage-contract.js')
+    const evidence = checkExecuteCodeEvidence(cwd, changeName)
+    if (evidence.status === 'unchanged') {
+      return { batched: false, aligned: 0, reason: `代码零变更（${evidence.detail}）` }
+    }
+    const now = new Date().toLocaleString('zh-CN', { hour12: false })
+    let aligned = 0
+    for (const step of steps) {
+      if (step.status === 'pending' || step.status === 'in-progress') {
+        step.status = 'completed'
+        step.completedAt = now
+        aligned++
+      }
+    }
+    return { batched: true, aligned }
+  } catch {
+    return { batched: false, aligned: 0 }
+  }
+}
+
 function formatWaitHistory(step) {
   const answers = Array.isArray(step.waitAnswers) ? step.waitAnswers : []
   if (answers.length === 0) return null
@@ -621,38 +743,13 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
         console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
         console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)
         // plan.md checkbox auto-check：execute 完成 + review.json pass → 自动勾选（治本，比警告可靠）
-        try {
-          const specBaseLc = platformOpts.specRoot || join(cwd, '.sillyspec')
-          const changeDir = join(specBaseLc, 'changes', changeName)
-          const planPath = join(changeDir, 'plan.md')
-          const runtimeRoot = platformOpts.runtimeRoot || join(specBaseLc, '.runtime')
-          const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
-          if (existsSync(planPath) && existsSync(runIdFile)) {
-            const executeRunId = readFileSync(runIdFile, 'utf8').trim()
-            const planContent = readFileSync(planPath, 'utf8')
-            const { readReview } = await import('../task-review.js')
-            let checkedCount = 0
-            let skippedCount = 0
-            const updated = planContent.replace(/^(\s*[-*]\s*\[)\s(\]\s*task-\d+)/gim, (match, p1, p2) => {
-              const taskNum = match.match(/task-(\d+)/)[1].padStart(2, '0')
-              const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', `task-${taskNum}`, 'review.json')
-              const r = readReview(reviewPath)
-              if (r.ok && r.review?.specVerdict !== 'fail' && r.review?.qualityVerdict !== 'fail') {
-                checkedCount++
-                return `${p1}x${p2}`   // 勾选
-              }
-              skippedCount++
-              return match              // 不勾
-            })
-            if (checkedCount > 0) {
-              writeFileSync(planPath, updated)
-              console.log(`   ✅ 自动勾选 ${checkedCount} 个 task checkbox（基于 review.json pass）`)
-            }
-            if (skippedCount > 0) {
-              console.warn(`   ⚠️ ${skippedCount} 个 task 未勾（review.json 缺失/fail）→ archive 会拦。补 review 后重跑 execute --done 触发自动勾`)
-            }
-          }
-        } catch {}
+        const _ac = await autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts })
+        if (_ac.autoChecked) {
+          console.log(`   ✅ 自动勾选 ${_ac.checkedCount} 个 task checkbox（基于 review.json pass）`)
+        }
+        if (_ac.skippedCount > 0) {
+          console.warn(`   ⚠️ ${_ac.skippedCount} 个 task 未勾（review.json 缺失/fail）→ archive 会拦。补 review 后重跑 execute --done 触发自动勾`)
+        }
       }
     }
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }

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/prompt.js

@@ -517,6 +517,26 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // archive Step1「任务完成度检查」客观真相源注入：以 review.json verdict 算完成度，
+  // 替代「机械数 plan.md checkbox」（checkbox 依赖 autoCheckPlanFromReviews 回填，runId marker /
+  // review 缺失时回填静默 no-op，会停在未勾态导致完成度失真 → archive 误判「全未完成」）。
+  // summarizeTaskCompletion 内部已 fail-safe 降级（无 plan / 无 runId → checkbox 统计 + 标注 source），
+  // 此处仅兜底注入异常，绝不阻断 archive。
+  if (stageName === 'archive' && promptText.includes('{TASK_COMPLETION_REPORT}')) {
+    try {
+      const { summarizeTaskCompletion } = await import('../task-review.js')
+      const tcrSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+      const tcrRuntimeRoot = platformOpts?.runtimeRoot || join(tcrSpecBase, '.runtime')
+      const tcrChangeDir = changeName ? join(tcrSpecBase, 'changes', changeName) : null
+      const summary = tcrChangeDir
+        ? summarizeTaskCompletion({ changeDir: tcrChangeDir, runtimeRoot: tcrRuntimeRoot, changeName })
+        : null
+      promptText = promptText.split('{TASK_COMPLETION_REPORT}').join(summary ? summary.report : '（无法计算完成度：变更目录缺失）')
+    } catch (e) {
+      promptText = promptText.split('{TASK_COMPLETION_REPORT}').join('（完成度计算异常：' + e.message + '，请手动核对 plan.md 与 .runtime/execute-runs/*/tasks/task-NN/review.json）')
+    }
+  }
+
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
     const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')

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 内完成。