sillyspec 3.26.8 → 3.26.10

package/src/quicklog.js

@@ -81,9 +81,154 @@ 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 if (label === '审计') { /* D-8 advisory 行：只进 raw_block 不进结构化段（body_sections 不扩 schema），并阻断续行误挂 */ lastLabel = null; inFiles = false; 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 +361,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
@@ -327,7 +478,7 @@ function splitSingleLineFields(body) {
   return scanFields(body, findBoundaryLabel) ?? scanFields(body, (b, l, f) => b.indexOf(l, f))
 }
 
-function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes = []) {
+function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes = [], auditNotes = []) {
   const lines = content.split('\n')
   const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
   if (startIdx === -1) return null
@@ -393,6 +544,22 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
       lines.splice(after, 0, '')
     }
   }
+  // D-8 落盘（2026-08-18 修）：advisory 审计行（文档欠账 / 引用失效）写入条目尾部——修复
+  // quick-audit「欠账已记录（QUICKLOG reasons）」的不实承诺（原先纯 console 打印，事后不可审计；
+  // 两周实测需要分母：信号触发次数必须可追溯）。幂等：条目内已有 审计： 行则不重复写（--done 重跑安全）。
+  // 位置：结果块之后 / 条目尾部（重算边界，不吃上方 splice 的陈旧索引）。
+  if (auditNotes.length > 0) {
+    let entryEnd = -1
+    for (let i = startIdx + 1; i < lines.length; i++) {
+      if (lines[i].startsWith('## ')) { entryEnd = i; break }
+    }
+    if (entryEnd === -1) entryEnd = lines.length
+    if (!lines.slice(startIdx, entryEnd).some((l) => l.startsWith('审计：'))) {
+      let insertAt = entryEnd
+      while (insertAt - 1 > startIdx && lines[insertAt - 1].trim() === '') insertAt--
+      lines.splice(insertAt, 0, ...auditNotes.map((n) => `审计：${n}`))
+    }
+  }
   return lines.join('\n')
 }
 
@@ -441,6 +608,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 }
   })
 }
@@ -448,7 +631,7 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
 /**
  * 翻某 qlId 条目为「已完成」+ 追加结果 + 勾选关联 tasks.md。持锁。
  */
-export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [], changedFiles = [] } = {}) {
+export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [], changedFiles = [], auditNotes = [] } = {}) {
   const quicklogDir = join(specBase, 'quicklog')
   // 与 allocateQuicklogEntry 同源消毒：锁文件路径含 user（防穿越写，两入口必须一致否则锁不上同一文件）
   const user = sanitizeQuicklogUser(gitUser) || 'unknown'
@@ -464,17 +647,33 @@ 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 = ''
       try { content = readFileSync(filePath, 'utf8') } catch { continue }
-      const updated = flipEntryInContent(content, qlId, result, realFiles, fileNotes)
+      const updated = flipEntryInContent(content, qlId, result, realFiles, fileNotes,
+        Array.isArray(auditNotes) ? auditNotes.filter((n) => typeof n === 'string' && n.trim() !== '') : [])
       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 })
   }