sillyspec 3.26.8 → 3.26.9

package/src/quicklog.js

@@ -81,9 +81,153 @@ export function sanitizeDesc(description) {
   return s.length > 120 ? s.slice(0, 120) + '…' : s
 }
 
+
+// ── 平台推送（best-effort，2026-08-16-change-center-quick-tab task-06 / D-003）──
+
+// 读 local.yaml platform 段（url+token）。quicklog 不 import sync.js（会拖 ProgressManager
+// 整链），自带同款轻量解析：只取 platform.url / platform.token 两键，与 parseSimpleYaml
+// 同风格（丢注释可接受——只读）。未连接返回 null（合法本地状态，静默跳过）。
+function _readPlatformConfig(specBase) {
+  try {
+    // specBase 即 <cwd>/.sillyspec（或平台 specRoot）；local.yaml 就在 spec 根下
+    const yamlPath = join(specBase, 'local.yaml')
+    if (!existsSync(yamlPath)) return null
+    const lines = readFileSync(yamlPath, 'utf8').split(/\r?\n/)
+    let inPlatform = false
+    const cfg = {}
+    for (const line of lines) {
+      if (!line.trim() || line.trim().startsWith('#')) continue
+      if (!/^\s/.test(line)) inPlatform = line.startsWith('platform:')
+      else if (inPlatform) {
+        const m = line.match(/^\s+(url|token)\s*:\s*(.*)$/)
+        if (m) {
+          let v = m[2].trim()
+          if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) v = v.slice(1, -1)
+          if (v) cfg[m[1]] = v
+        }
+      }
+    }
+    if (!cfg.url || !cfg.token) return null
+    return cfg
+  } catch {
+    return null
+  }
+}
+
+const PUSH_TIMEOUT_MS = 5_000
+
+// 从文件全文提取指定 qlId 的条目块（## 头到下一个 ## 头/文件尾）。null=未命中。
+// 与平台 quicklog_parser.py 同款切分口径（剥 \r），保证 CLI 推送的 raw_block 与平台解析一致。
+function extractRawBlock(content, qlId) {
+  if (!content) return null
+  const lines = content.split('\n')
+  const start = lines.findIndex(l => l.replace(/\r$/, '').startsWith(`## ${qlId} |`))
+  if (start === -1) return null
+  let end = lines.length
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].replace(/\r$/, '').startsWith('## ')) { end = i; break }
+  }
+  return lines.slice(start, end).map(l => l.replace(/\r$/, '')).join('\n').trimEnd()
+}
+
+// 落盘条目块 → 推送 payload（design §5.3：以落盘终态为准，不从入参拼）。
+// 宽松标签解析对齐平台：全半角冒号、多条状态行取最后、文件行单行/多行 bullet。
+function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_changes, fallback_title }) {
+  const payload = {
+    ql_id,
+    timestamp: null,
+    title: fallback_title || '(quick 任务)',
+    status,
+    status_note: null,
+    author_raw,
+    linked_changes: Array.isArray(linked_changes) ? linked_changes : [],
+    files: [],
+    body_sections: {},
+    raw_block: rawBlock,
+  }
+  if (!rawBlock) return payload
+  const lines = rawBlock.split('\n')
+  const header = lines[0] || ''
+  const parts = header.split('|').map(s => s.trim())
+  if (parts.length >= 3) {
+    payload.timestamp = parts[1] || null
+    payload.title = parts.slice(2).join('|').trim() || payload.title
+  }
+  const labelRe = /^(状态|关联变更|文件|需求|根因|方案|结果)\s*[：:]\s*(.*)$/
+  const bulletRe = /^-\s+(.*)$/
+  let inFiles = false
+  let inLinked = false
+  let lastLabel = null
+  let lastStatus = null
+  for (const line of lines.slice(1)) {
+    const stripped = line.trim()
+    if (!stripped) { inFiles = false; inLinked = false; continue }
+    const m = stripped.match(labelRe)
+    if (m) {
+      const [, label, value] = m
+      if (label === '状态') lastStatus = value
+      else if (label === '关联变更') { payload.linked_changes = value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean); inLinked = true; inFiles = false }
+      else if (label === '文件') { if (value) payload.files.push(...value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean).map(p => ({ path: p, note: null }))); inFiles = true; inLinked = false }
+      else { payload.body_sections[label] = value; lastLabel = label }
+      continue
+    }
+    if (bulletRe.test(stripped) && inFiles) {
+      payload.files.push({ path: stripped.replace(/^-\s+/, ''), note: null })
+      continue
+    }
+    if (bulletRe.test(stripped) && inLinked) {
+      payload.linked_changes.push(...stripped.replace(/^-\s+/, '').split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean))
+      continue
+    }
+    if (lastLabel) payload.body_sections[lastLabel] += '\n' + stripped
+  }
+  // 状态以落盘为准（flip 后是「已完成」或「已完成（括注）」）——多条取最后
+  if (lastStatus) {
+    payload.status = lastStatus.startsWith('已完成') ? 'completed'
+      : lastStatus.startsWith('已暂存') ? 'partial_done'
+      : lastStatus.startsWith('进行中') ? 'in_progress'
+      : status
+    const note = lastStatus.match(/（(.+)）$/)
+    payload.status_note = note ? note[1] : null
+  }
+  // 白名单正则对齐平台（^\d{4}-\d{2}-\d{2}- 才进列表，防自由文本进反向区块）
+  payload.linked_changes = payload.linked_changes.filter(c => /^\d{4}-\d{2}-\d{2}-/.test(c))
+  return payload
+}
+
+// 单条推送：payload 字段对齐平台 QuicklogEntryPushRequest（snake_case）。测试经 allocate/complete 间接触发。
+// 任何失败（无配置/网络/非 2xx/超时）静默 warn 一行不抛（FR-02 best-effort，quick 主流程零阻断）。
+async function pushQuicklogEntryToPlatform(specBase, entry) {
+  const cfg = _readPlatformConfig(specBase)
+  if (!cfg) {
+    if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn('[quicklog-push] 未配置 platform 段，跳过推送')
+    return false
+  }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), PUSH_TIMEOUT_MS)
+  try {
+    const res = await fetch(`${cfg.url.replace(/\/$/, '')}/api/quicklog-entries`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${cfg.token}` },
+      body: JSON.stringify(entry),
+      signal: controller.signal,
+    })
+    if (!res.ok) {
+      console.warn(`[quicklog-push] ${entry.ql_id} → ${res.status}（文件链路兜底，不影响本地记录）`)
+      return false
+    }
+    return true
+  } catch (err) {
+    console.warn(`[quicklog-push] ${entry.ql_id} 推送失败: ${err && err.name === 'AbortError' ? '超时' : (err.message || err)}（文件链路兜底）`)
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 // git user.name → 文件名安全形式：白名单保留字母数字._- 与中文等 Unicode 字，
 // 剥路径元字符（/ \ ..）与控制字符。防 QUICKLOG-<user>.md / 锁文件 / 轮转归档穿越写。
-export function sanitizeQuicklogUser(user) {
+function sanitizeQuicklogUser(user) {
   const s = String(user || '').replace(/[\\/\r\n\0]/g, '').replace(/\.{2,}/g, '.').trim()
   if (!s) return ''
   return s.length > 64 ? s.slice(0, 64) : s
@@ -216,7 +360,13 @@ function scanExisting(quicklogDir, today) {
   let maxSeq = 0
   const usedSuffix = new Set()
   const re = /^## ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})\b/gm
+  // E22c：轮转归档按文件名日期过滤——归档名 = QUICKLOG-<user>-<YYYY-MM-DD>.md（最后条目日期），
+  // 归档内全部条目 ≤ 名内日期；名内日期早于今天的归档不可能含当日条目，跳过读取
+  // （O(全历史归档) → O(当日文件)，consumer 已 10 归档文件 756KB 时免全量扫描）。
+  const todayDashed = today.length === 8 ? `${today.slice(0, 4)}-${today.slice(4, 6)}-${today.slice(6, 8)}` : today
   for (const f of listQuicklogFiles(quicklogDir)) {
+    const dm = f.match(/-(\d{4}-\d{2}-\d{2})\.md$/)
+    if (dm && dm[1] < todayDashed) continue // 早于今天的归档，必无当日条目
     let content = ''
     try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
     let m
@@ -441,6 +591,22 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
 
     for (const c of linked) appendTaskCheckbox(specBase, c, qlId, desc)
 
+    // 平台推送（task-06 / FR-02 / D-003）：锁外语义等同（推送不回写本地），但放锁内
+    // 保证「分配即推送」顺序一致；best-effort 失败不影响返回。
+    await pushQuicklogEntryToPlatform(specBase, {
+      ql_id: qlId,
+      timestamp: nowDatetime(),
+      title: desc,
+      status: 'in_progress',
+      status_note: null,
+      author_raw: user,
+      // 白名单正则对齐平台（^\d{4}-\d{2}-\d{2}- 才进列表；原文在 raw_block 不丢）
+      linked_changes: linked.filter(c => /^\d{4}-\d{2}-\d{2}-/.test(c)),
+      files: files.map(f => ({ path: f, note: null })),
+      body_sections: {},
+      raw_block: entry,
+    }).catch(() => {}) // pushQuicklogEntryToPlatform 自身已吞错；双保险防未来改动破坏 best-effort 契约
+
     return { qlId }
   })
 }
@@ -464,6 +630,8 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
 
   await withFileLock(lockPath, async () => {
     // 条目可能在主文件或轮转归档中
+    let updatedContent = null
+    let updatedFile = null
     for (const f of listQuicklogFiles(quicklogDir)) {
       const filePath = join(quicklogDir, f)
       let content = ''
@@ -471,10 +639,23 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
       const updated = flipEntryInContent(content, qlId, result, realFiles, fileNotes)
       if (updated !== null) {
         await writeAtomic(filePath, updated) // 命中处原子落盘（只改含目标条目的那一个文件）
+        updatedContent = updated
+        updatedFile = filePath
         break
       }
     }
     for (const c of linked) await checkTaskCheckbox(specBase, c, qlId)
+
+    // 平台推送（task-06 / FR-02 / D-003）：**以落盘终态为准**读回条目组装 payload
+    // （design §5.3：翻完成时标题行被 extractTitleFromResult 刷新，推送须与落盘一致，
+    // 不能用入参拼——标题/结果块/文件行都会在 flipEntryInContent 中重写）。
+    const rawBlock = extractRawBlock(updatedContent, qlId)
+    await pushQuicklogEntryToPlatform(specBase, buildPushPayloadFromRaw(rawBlock, {
+      ql_id: qlId,
+      author_raw: user,
+      status: 'completed',
+      linked_changes: linked,
+    })).catch(() => {})
   })
 }
 

package/src/run/command.js

@@ -19,7 +19,7 @@
  *     './run/shared.js' / './run/quick-audit.js' / './run/prompt.js' / './run/complete.js' /
  *     './run/stage.js' → './shared.js' 等同级
  */
-import { join, resolve, dirname } from 'node:path'
+import { basename, 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'
@@ -30,7 +30,8 @@ import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
 import { runStage } from './stage.js'
 import { sanitizeDesc } from '../quicklog.js'
 import { ProgressManager } from '../progress.js'
-import { validateChangeExists } from '../stage-contract.js'
+import { validateChangeExists, checkTransition } from '../stage-contract.js'
+import { READONLY_AUXILIARY_STAGES } from '../constants.js'
 import { stageRegistry, auxiliaryStages } from '../stages/index.js'
 import { definition as brainstormAutoDef } from '../stages/brainstorm-auto.js'
 import { setQuickFileNotes } from '../quicklog.js'
@@ -43,6 +44,7 @@ const VALUE_FLAGS = new Set([
   '--output', '--input', '--change', '--linked-changes',
   '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
   '--files', '--file-notes', '--from-step', '--mode', '--dir', '--confirm-mode',
+  '--base', // scan diff 基线 commit（吃值；只在 run scan --diff 转发路径消费）
 ])
 
 /**
@@ -145,7 +147,7 @@ sillyspec run ${stageName}${stage && stage.title ? ` — ${stage.title}` : ''}${
             --interactive --skip-approval --json(不支持)
   quick 专属: --linked-changes none|a,b --files a.js,b.js --allow-new
              --allow-delete --force-baseline --confirm --file-notes
-  scan  专属: --quick --standard --deep --force-rescan
+  scan  专属: --quick --standard --deep --force-rescan --diff [--base <commit>] [--full] [--report]
   archive专属: --confirm
 `)
 }
@@ -353,6 +355,24 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // scan diff 转发（D-001@v1：command.js 只认 --diff flag，等价 `sillyspec scan diff` 子命令；
+  // 裸 token `run scan diff` 不在此解析——那是 index.js 子命令拦截的职责，防 command.js 静默吞）。
+  // 纯只读比较：零会话/QUICKLOG 副作用，仅解析 --base/--full/--report 后转发 scan-diff 退出码。
+  if (stageName === 'scan' && flags.includes('--diff')) {
+    const { runScanDiff } = await import('../scan-diff.js')
+    const diffBaseIdx = flags.indexOf('--base')
+    const diffBase = diffBaseIdx >= 0 && flags[diffBaseIdx + 1] ? flags[diffBaseIdx + 1] : null
+    process.exitCode = runScanDiff({
+      projectRoot: cwd,
+      specBase,
+      projectName: basename(cwd),
+      base: diffBase,
+      full: flags.includes('--full'),
+      report: flags.includes('--report'),
+    })
+    return
+  }
+
   // 平台模式：首次接入时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
   // 只在「首次」执行一次——用 cwd 下的 .sillyspec-platform-cleaned 标记文件记录已处理，
@@ -491,6 +511,24 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // quick 关联变更存在性守卫（坑 quick-change-phantom-linked）：quick 的 --change/--linked-changes
+  // 被解析为关联变更后静默接受不存在的名字（quick 不建变更，链接幻影名必是笔误/语义误用——想给
+  // 会话起名却传了 --change），后果是 QUICKLOG 挂悬空关联污染 change 关联图谱 + --done 时 sessionId
+  // 走 fallback 可能命中他者会话。f70c9c3 只修了「建幻影目录」后果（appendTaskCheckbox 加
+  // existsSync 守卫），本守卫把误用拦在 flag 装载层。只校验 CLI 显式装载的 linkedChanges；
+  // 持久化 guard.json 复用（下方 run↔--done 之间变更可能被归档）与交互式选择（列表只列存在项）不检。
+  if (stageName === 'quick' && linkedChanges.length > 0) {
+    const missing = linkedChanges.filter(lc => lc !== 'none' && !existsSync(join(specRoot, 'changes', lc)))
+    if (missing.length > 0) {
+      console.error(`❌ quick 的 --change/--linked-changes 被当作「关联变更」处理，但以下变更不存在：${missing.join('、')}`)
+      console.error('   （quick 不创建变更，关联的变更必须预先存在）')
+      console.error('   - 想给会话起名：不要传 --change，sessionId 由 CLI 自动生成（后续 --done 用它）')
+      console.error('   - 想关联变更：修正拼写（.sillyspec/changes/ 下已存在的目录名），显式写法 --linked-changes <名>')
+      console.error('   - 想新建变更：quick 不建变更，走 brainstorm 完整流程')
+      process.exit(2)
+    }
+  }
+
   // 解析 --files a.js,b.js（quick 专用：显式声明 allowedFiles）
   // --files 是单值 flag，空格分隔的多文件只取首个致其余静默丢失（坑 quick-files-space-separated-silently-drops）。
   // detectSpaceSeparatedFiles 检测误用 → fail-loud 报错指明逗号用法（同 run --json :109 风格）。
@@ -534,6 +572,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--json', '--dir', '--help',
     '--reopen', '--from-step', '--mode',
     '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）
+    '--diff', '--base', '--full', '--report', // scan diff（D-001：command.js 只补 flag，裸 token 解析归 index.js 子命令拦截）
     '-h',
   ])
   for (let i = 0; i < flags.length; i++) {
@@ -658,6 +697,39 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
 
   let progress = pm.read(cwd, changeName)
 
+  // task-03 (D-005@v2 / FR-04): READONLY_AUXILIARY_STAGES（status/doctor）查询只读短路。
+  // 无显式写 flag 时在 registerChange / ensureStageSteps 之前拦截，零副作用：
+  //   - 目标 progress 不存在 → 提示「只读查询不建变更」exit 0（不 initChange、不建 default 行，治 8b）
+  //   - 目标 progress 存在 → 只读展示，不 seed steps、不刷新 lastActive、不 registerChange
+  //     （治 B7 多 agent 并发 lastActive 互相覆盖）
+  // 显式写意图不短路：doctor 写操作 flag（--cleanup-remnant / --align-execute-progress）与
+  // 步骤动作 flag（--done/--skip/--reset/--reopen/--wait/--continue）走原写路径；--status 本身
+  // 是只读查询，纳入短路。--fix 是 worktree doctor 的 flag 不在此列（design.md Phase 4）。
+  const READONLY_WRITE_ACTIONS = ['--cleanup-remnant', '--align-execute-progress', '--done', '--skip', '--reset', '--reopen', '--wait', '--continue']
+  if (READONLY_AUXILIARY_STAGES.includes(stageName) && !flags.some(f => READONLY_WRITE_ACTIONS.includes(f))) {
+    if (!progress) {
+      console.log('ℹ️ 未找到进度数据（只读查询不建变更）')
+      process.exit(0)
+    }
+    // 只读展示路径：复用阶段定义渲染当前步骤 prompt（outputStep 对 status/doctor 纯只读），
+    // 不落盘任何 progress 改动。--status 走现有 showStatus 展示。
+    const readOnlyChange = changeName || progress.currentChange || resolveChangeName(cwd, progress, specRoot)
+    if (isStatus) {
+      let nextSuggestion = null
+      try { nextSuggestion = pm._getNextSuggestion(progress) } catch { /* 读建议失败不阻断展示 */ }
+      return showStatus(progress, stageName, nextSuggestion)
+    }
+    const readonlySteps = await getStageSteps(stageName, cwd, progress, specRoot)
+    if (readonlySteps && readonlySteps.length > 0) {
+      // 已有进度（历史 seed 过）则渲染当前待办步；无进度从首步开始
+      const existingSteps = progress.stages?.[stageName]?.steps
+      const pendingIdx = existingSteps ? existingSteps.findIndex(s => s.status === 'pending' || s.status === 'in-progress') : -1
+      const stepIdx = pendingIdx !== -1 ? pendingIdx : 0
+      await outputStep(stageName, stepIdx, readonlySteps, cwd, readOnlyChange, progress.project || null, platformOpts)
+    }
+    return
+  }
+
   if (!progress) {
     // 如果指定了变更名或有变更目录，自动初始化变更的 progress
     const autoChange = changeName || resolveChangeNameAuto(cwd, specRoot)
@@ -703,6 +775,17 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
           console.error('   或先运行 sillyspec run brainstorm --change <变更名> 初始化。')
           process.exit(2) // 用法错（--done 找不到变更，未传 --change）→ exit 2
         }
+        // task-03 (D-006@v1 / FR-05): 无 --change 仅当无已存在活跃变更时 auto-create；
+        // 多活跃变更仓强制 --change（exit 2 引导），防 B8 幽灵变更。活跃变更数用 pm.listChanges
+        // （与 progress show 同源，DB changes 表 status='active'）。
+        const activeChanges = pm.listChanges(cwd)
+        if (activeChanges.length > 0) {
+          console.error(`❌ 已存在 ${activeChanges.length} 个活跃变更，run brainstorm 无 --change 不会自动创建新变更。`)
+          console.error(`   活跃变更：${activeChanges.join('、')}`)
+          console.error('   请用 --change <变更名> 指定要操作的变更，')
+          console.error('   或先归档/收尾现有活跃变更后重试。')
+          process.exit(2) // 用法错（多活跃变更未指定 --change）→ exit 2
+        }
         const date = new Date().toISOString().slice(0, 10)
         const autoName = `${date}-new-change-${randomBytes(4).toString('hex')}`
         console.log(`🔄 自动创建变更：${autoName}`)
@@ -883,6 +966,21 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
 
   // --done
   if (isDone) {
+    // task-03 (D-004@v1 / FR-02): --done 与 runStage（stage.js:35-45）同源状态转换守卫，
+    // 含 fromStageData 透传（让 scan failed_post_check 门控对 --done 同样生效）。
+    // auxiliary 的 --done 不受影响（checkTransition 对 auxiliary toStage 放行，见 stage-contract.js）。
+    // --skip-approval 绕过语义对齐 runStage（打错但放行）。
+    const prevStage = progress.currentStage || ''
+    const fromStageData = (progress.stages && prevStage && progress.stages[prevStage]) || undefined
+    const transition = checkTransition(prevStage, stageName, fromStageData ? { fromStageData } : {})
+    if (!transition.allowed) {
+      console.error(`❌ 阶段转换不允许: ${prevStage || '(起始)'} → ${stageName}`)
+      console.error(`   原因: ${transition.reason}`)
+      console.error(`   提示: 使用 --skip-approval 绕过（需明确意图）`)
+      if (!isSkipApproval) {
+        process.exit(1)
+      }
+    }
     const doneAnswer = getFlagValue('--answer')
     return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete })
   }

package/src/run/complete.js

@@ -24,7 +24,7 @@ import { triggerSync, WAIT_MARKER_RE, getStageSteps, formatWaitOptions, resolveR
 import { executeScanPreflight, executeScanPostcheck, computeScanProfile } from './scan-profile.js'
 import { executePlanPostcheck as runPlanPostcheckLib } from '../stages/plan-postcheck.js'
 import { outputStep } from './prompt.js'
-import { enforceDepsGate, enforceReviewJsonGate, completeStageGates, readDesignScale } from './gates.js'
+import { enforceDepsGate, enforceReviewJsonGate, enforceSymbolImpactGate, completeStageGates, readDesignScale } from './gates.js'
 import { handleArchiveConfirmStep, handlePlanGeneratePlanStep, handleScanProjectListStep, handleWorkflowPostCheck, handleQuickStageCompletion, handleExecuteWaveArtifact } from './complete-handlers.js'
 import { formatExecuteSummary } from '../worktree-apply.js'
 import { isEndToEndTaskText } from '../change-risk-profile.js'
@@ -160,6 +160,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // 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)
+  // 符号影响面报告硬门（ql-20260816-005-3d7f）：execute「加载上下文」步产出落盘核验——
+  // symbol-impact.md 存在 + plan 每 task 有结论行；防前缀步被一句「上下文在会话内」盖章跳过。
+  await enforceSymbolImpactGate(stageName, changeName, steps[currentIdx]?.name, specBase)
 
   // ── noAI 步骤硬门（坑 noai-done-bypass）：noAI 步骤的确定性校验不可被 --done 绕过 ──
   // 正常路径 agent 跑 `run <stage>` 推进到 noAI step 时，runStage 自动执行 _cliAction
@@ -323,6 +326,9 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       console.warn('⚠️ 阶段完成 ctx 构造失败，降级单仓 gate（' + (e && e.message ? e.message : e) + '）')
     }
     const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText, ctx: _completeCtx })
+    // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1，对齐 quick 审计 blocked→exit 1 惯例。
+    // 用 process.exitCode 而非 process.exit(1)：让回滚 pm._write + triggerSync 落盘完成后自然退出，保留失败现场。
+    if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
     if (_stageGatesResult) return _stageGatesResult
 
     // 完整流程 change title 刷新：proposal/design 落盘后（brainstorm/plan 完成），从 proposal 首个 #
@@ -805,6 +811,8 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
       console.warn('⚠️ 阶段完成 ctx 构造失败，降级单仓 gate（' + (e && e.message ? e.message : e) + '）')
     }
     const _stageGatesResult = await completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps: stageData.steps, currentIdx, outputText: null, ctx: _contCtx })
+    // task-04 / A5：gate 失败（stageCompleted===false）设进程退出码 1（与 completeStep 完成分支同语义）。
+    if (_stageGatesResult?.stageCompleted === false) process.exitCode = 1
     if (_stageGatesResult) return _stageGatesResult
     // 完整流程 change title 刷新（同 completeStep 完成分支，wait 解除后阶段完成也刷新）。
     if (changeName && !/^quick-[0-9a-f]{8}$/.test(changeName)) {

package/src/run/gates.js

@@ -27,6 +27,68 @@ import { handleScanStageCompleted, handleExecuteWorktreeCleanup } from './comple
 import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 
+/**
+ * 从 plan.md 提取全部 task id（task-XX）——符号影响面覆盖度校验用。
+ * 只认 checkbox 行 `- [ ] task-XX:` / `- [x] task-XX:`（与 execute.js parseWavesFromPlan 的
+ * 收容口径一致：### 标题式 task / 非 task 区 checkbox 不算），light plan 的 `## Tasks` 段同样收。
+ */
+function extractTaskIdsFromPlan(planContent) {
+  if (!planContent) return []
+  return [...String(planContent).matchAll(/^[-*]\s*\[[ x]\]\s*(?:.*\b)?task-(\d+)\b/gim)]
+    .map(m => `task-${m[1].padStart(2, '0')}`)
+}
+
+/**
+ * 符号影响面报告结构校验（纯函数）：execute「加载上下文」步的产出落盘核验。
+ *
+ * 治 persuasion-only 失效现场（ql-20260816-005-3d7f）：execute 前缀 4 步无任何 gate，agent 可
+ * <1s 连发 4 次 --done 盖章跳过，「符号影响面扫描」（execute.js 操作 11）被一句「上下文在会话内」
+ * 带过（输出契约只写「上下文摘要」，操作与输出脱节）。修法 = 报告落盘
+ * {SPEC_ROOT}/changes/<change>/symbol-impact.md + 本函数校验：plan.md 每个 task-XX 在报告中出现
+ * （逐 task 结论，「无签名级变更」也要显式写，治整体一句话带过）。语义质量（调用点找没找全）
+ * 仍归 agent，CLI 只核结构覆盖度——符合债单「persuasion-only → 补最小硬门」原则。
+ *
+ * @param {{reportContent: string|null, planContent: string|null}} params
+ * @returns {{ok: boolean, errors: string[]}}
+ */
+export function validateSymbolImpactReport({ reportContent, planContent }) {
+  const errors = []
+  if (!reportContent || !String(reportContent).trim()) {
+    return { ok: false, errors: ['symbol-impact.md 不存在或内容为空——「加载上下文」步的符号影响面报告必须落盘（逐 task 一行结论，「无签名级变更」也要显式写）'] }
+  }
+  const taskIds = extractTaskIdsFromPlan(planContent)
+  if (taskIds.length === 0) return { ok: true, errors } // plan 无 task 可列（默认兜底形态）→ 无可校验对象
+  const missing = taskIds.filter(id => !String(reportContent).includes(id))
+  for (const id of missing) {
+    errors.push(`${id} 未在 symbol-impact.md 中出现——每个 task 都要有一行结论（含「无签名级变更」的显式声明）`)
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+/**
+ * 符号影响面报告硬门：execute「加载上下文」步 --done 时校验 symbol-impact.md 落盘 + task 覆盖度。
+ * fail-closed：不通过 → 当前步标 blocked + exit 1（进度不推进）。非目标步骤/阶段直接放行。
+ */
+export async function enforceSymbolImpactGate(stageName, changeName, currentStepName, specBase) {
+  if (stageName !== 'execute') return
+  if (!currentStepName || !currentStepName.includes('加载上下文')) return
+  const planPath = join(specBase, 'changes', changeName || '', 'plan.md')
+  const reportPath = join(specBase, 'changes', changeName || '', 'symbol-impact.md')
+  if (!existsSync(planPath)) return // plan.md 缺失场景已有 plan 阶段 gate 把关，此处不重复拦
+  let planContent = ''
+  try { planContent = readFileSync(planPath, 'utf8') } catch { return }
+  let reportContent = null
+  try { reportContent = readFileSync(reportPath, 'utf8') } catch { /* 缺失由 validate 报 */ }
+  const result = validateSymbolImpactReport({ reportContent, planContent })
+  if (result.ok) return
+  console.error('❌ ── 符号影响面报告校验阻断（本次 --done 未完成，进度未推进）──')
+  console.error(`   「加载上下文」步的符号影响面检查报告未落盘或不完整：`)
+  console.error(`   期望路径：${reportPath}`)
+  for (const e of result.errors) console.error(`   • ${e}`)
+  console.error('   修复：按「加载上下文」步操作 11 完成符号影响面扫描，逐 task 写结论（无签名级变更也要显式写「无」），落盘后重跑 execute --done。')
+  process.exit(1)
+}
+
 /**
  * 判断当前 execute step 所在 wave 是否全部 task 都声明 no_deps_verify: true（D-006@v2）。
  * 仅 wave 执行步骤（名如 "Wave N 执行"）可 opt-out；非 wave 步骤恒返回 false（保守过门）。
@@ -379,7 +441,11 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           if (!executeRunId) {
             executeRunId = generateExecuteRunId()
             // 落盘（marker 缺失时 fallback 生成后写盘，保证后续 checkbox/gate 读到同一 ID）
-            try { mkdirSync(runtimeRoot, { recursive: true }); writeFileSync(runIdFile, executeRunId + '\n') } catch {}
+            // D-001#1 fallback 写入点：mkdir execute-runs/<runId>/tasks 先于 marker（不变量：
+            // marker 在则目录在）。不 try/catch——异常直穿外层 catch 走 fail-closed 阻断
+            //（gate 自身写 run 目录失败不能静默放行完成）。
+            mkdirSync(join(runtimeRoot, 'execute-runs', executeRunId, 'tasks'), { recursive: true })
+            writeFileSync(runIdFile, executeRunId + '\n')
           }
         }