sillyspec 3.26.7 → 3.26.9

package/src/progress/stage-machine.js

@@ -275,7 +275,10 @@ export class StageMachine {
     }
 
     // 找到第一个有 pending/waiting/failed 步骤的 in-progress 阶段
+    // C14b：排除 scan（同下方主流程推荐循环）——scan 是 auxiliary，中途未完成时恒处
+    // STAGE_ORDER 首位且 in-progress，会把「下一步」劫持为 scan，掩盖主流程真实待办。
     for (const s of STAGE_ORDER) {
+      if (s === 'scan') continue
       const sd = data.stages[s];
       if (!sd) continue;
       if (sd.status === 'in-progress' && sd.steps) {

package/src/progress.js

@@ -20,26 +20,21 @@ import { ChangeRegistry } from './progress/change-registry.js';
 import { StepStore } from './progress/step-store.js';
 import { StageMachine } from './progress/stage-machine.js';
 import { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './progress/shared.js';
+// resolveSpecDir 单一真相源在 src/run/shared.js（含 home 拒绝守卫，坑 cwd-correction-home-collision
+// 根治：home 下 .sillyspec 恒不命中，防 smoke/临时目录污染自我延续）。此处 re-export 保持
+// 既有 import 路径兼容；run/shared.js 对 progress.js 只有动态 import，无静态循环。
+import { resolveSpecDir } from './run/shared.js';
+import { checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './run/shared.js';
+export { resolveSpecDir };
 
 // 默认规范目录名（相对于 cwd）
 // SPEC_DIR_NAME → ./progress/shared.js（W6 Step9d）
 const RUNTIME_SUBDIR = '.runtime';
 
 /**
- * 向上查找含 .sillyspec 目录的祖先目录，类似 git 找 .git 的逻辑。
- * 找到则返回 <祖先>/.sillyspec，否则 fallback 到 <cwd>/.sillyspec。
+ * 向上查找含 .sillyspec 目录的祖先目录——实现已收敛至 src/run/shared.js（单一真相源，
+ * 含 home 拒绝守卫），此处 re-export。见顶部 import 说明。
  */
-export function resolveSpecDir(startDir) {
-  let dir = resolve(startDir);
-  while (true) {
-    const candidate = join(dir, SPEC_DIR_NAME);
-    if (existsSync(candidate)) return candidate;
-    const parent = dirname(dir);
-    if (parent === dir) break; // 到达根目录
-    dir = parent;
-  }
-  return join(resolve(startDir), SPEC_DIR_NAME);
-}
 
 /**
  * 平台指针不可达错误。pointer 存在但失效时抛出，阻止静默回退到本地孤儿 db。
@@ -59,6 +54,26 @@ export class PointerUnreachableError extends Error {
   }
 }
 
+/**
+ * 平台接管声明生效错误（指针缺失但声明存在）。fail-closed 入口一：
+ * 防指针被 cleanup/STALE 清理或项目挪动后裸调静默建本地进度库（状态分裂根因）。
+ *
+ * ⚠️ 不覆写 this.name（保持父类的 'PointerUnreachableError'）——CLI 顶层 catch 按
+ * err?.name === 'PointerUnreachableError' 严格字符串匹配（index.js），子类改名会
+ * 落通用错误分支打 stack noise。靠 message 首行"平台接管声明生效"区分场景。
+ */
+export class PlatformManagedError extends PointerUnreachableError {
+  constructor({ declarationPath, specRoot }) {
+    super({
+      pointerPath: declarationPath,
+      specRoot,
+      reason: `平台接管声明生效——本项目已由平台托管，但恢复指针缺失（可能被 platform pointer --cleanup 清理或项目目录被移动），拒绝静默回退本地模式`,
+      hint: `① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录`,
+    });
+    this.declarationPath = declarationPath;
+  }
+}
+
 /**
  * 平台感知的 specDir 解析（fail-closed，所有 CLI 子命令统一入口）。
  *
@@ -75,6 +90,15 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
   if (explicitSpecDir) return resolve(explicitSpecDir);
   const pointerPath = join(resolve(cwd), '.sillyspec-platform.json');
   if (!existsSync(pointerPath)) {
+    // 指针缺失：查平台接管声明（fail-closed 入口一）。声明存在 = 项目进过平台模式，
+    // 指针丢失不该静默当纯本地项目处理（会建本地进度库 → 状态分裂）。
+    const decl = checkPlatformManaged(cwd);
+    if (decl) {
+      throw new PlatformManagedError({
+        declarationPath: join(resolve(cwd), PLATFORM_MANAGED_FILENAME),
+        specRoot: decl.specRoot,
+      });
+    }
     return resolveSpecDir(cwd);
   }
   // pointer 存在 = 进过平台模式，严格校验，不静默回退

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,18 +19,19 @@
  *     './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'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 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 转发路径消费）
 ])
 
 /**
@@ -125,6 +127,31 @@ export async function ensureStageSteps(progress, stageName, cwd, specDir = null)
   return false
 }
 
+/**
+ * run <stage> --help/-h 的用法帮助（runCommand 内 --help 短路调用）。
+ * 只打印不落盘：帮助查询不该有副作用（建会话/写 QUICKLOG）。
+ */
+function printStageUsage(stageName) {
+  const stage = stageRegistry[stageName]
+  console.log(`
+sillyspec run ${stageName}${stage && stage.title ? ` — ${stage.title}` : ''}${stage && stage.description ? `\n  ${stage.description}` : ''}
+
+用法:
+  sillyspec run ${stageName}                    开始/继续该阶段（输出下一步 prompt）
+  sillyspec run ${stageName} --status           查看阶段进度
+  sillyspec run ${stageName} --done --output "摘要" [--input "用户原话"]   完成当前步骤
+  sillyspec run ${stageName} --change <名>      指定变更（多活跃变更必填）
+
+  通用参数: --done --output --input --status --skip --reset --reopen --from-step
+            --wait --continue --answer --change --spec-dir --non-interactive
+            --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 --diff [--base <commit>] [--full] [--report]
+  archive专属: --confirm
+`)
+}
+
 /**
  * sillyspec run <stage> 主命令
  */
@@ -289,31 +316,27 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
     }
   }
+  // ── 平台接管声明 fail-closed（入口二，D-B@v2）──
+  // runCommand 有独立指针恢复链（不经 resolvePlatformSpecDir），指针缺失时若不在此
+  // 封堵，run/quick/scan 等全部 stage 命令会静默落本地库（与入口一行为分裂）。
+  // 触发条件：命令行没传平台参数 + 指针与 platform-scan.json 皆未命中 + 接管声明存在。
+  // 显式 --spec-dir/--spec-root 传参时 platformOpts.specRoot 已赋值，天然不进此分支（逃生口）。
+  if (!platformOpts.specRoot && !platformOpts.runtimeRoot && !platformFileExists) {
+    const decl = checkPlatformManaged(cwd)
+    if (decl) {
+      console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
+      console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+      console.error('   恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录。')
+      // exit(1) 而非邻近环境错的 exit(2)：这是"状态保护阻断"（对齐 PointerUnreachableError
+      // 顶层 catch 语义），非"用法/环境错"——见 design.md §5.3 v2 复审观察 (a)
+      process.exit(1)
+    }
+  }
   // 持久化 platformOpts
-  // 在 specRoot/.runtime/ 写主文件，同时在 cwd/.sillyspec/.runtime/ 写恢复指针
+  // 在 specRoot/.runtime/ 写主文件，同时在 cwd 下写恢复指针
+  // （writePlatformPointer 收敛双写逻辑，cmdInit 平台模式共用，防两处字段漂移）
   if (platformOpts.specRoot || platformOpts.runtimeRoot) {
-    try {
-      const { mkdirSync, writeFileSync } = await import('fs')
-      mkdirSync(join(specRoot, '.runtime'), { recursive: true })
-      writeFileSync(platformOptsFile, JSON.stringify({
-        specRoot: platformOpts.specRoot,
-        runtimeRoot: platformOpts.runtimeRoot,
-        workspaceId: platformOpts.workspaceId,
-        scanRunId: platformOpts.scanRunId,
-        savedAt: new Date().toISOString(),
-      }, null, 2) + '\n')
-      // 恢复指针：在 cwd 下写 .sillyspec-platform.json（不在 .sillyspec 内，不污染源码结构）
-      // 供后续 --done（不带 --spec-root）找到 specDir
-      writeFileSync(join(cwd, '.sillyspec-platform.json'), JSON.stringify({
-        specRoot: platformOpts.specRoot,
-        runtimeRoot: platformOpts.runtimeRoot,
-        workspaceId: platformOpts.workspaceId,
-        scanRunId: platformOpts.scanRunId,
-        savedAt: new Date().toISOString(),
-      }, null, 2) + '\n')
-    } catch {
-      // 静默失败，不影响主流程
-    }
+    writePlatformPointer(cwd, platformOpts)
   }
 
   // 统一规范基路径：平台模式用 specRoot，本地模式用 cwd/.sillyspec
@@ -332,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 标记文件记录已处理，
@@ -470,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 风格）。
@@ -513,6 +572,8 @@ 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++) {
     const f = flags[i]
@@ -531,6 +592,14 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // ── --help/-h 短路：flag 校验通过后、任何副作用（cwd 纠正/会话创建/QUICKLOG 落盘）之前 ──
+  // --help 此前在 knownFlags 白名单里被静默吞掉，run quick --help 会误开 quick 会话+写骨架
+  // 条目（查询意图不该有副作用）；-h 更是被当未知参数 exit 2。帮助查询 = 用法展示 = 退出 0。
+  if (flags.includes('--help') || flags.includes('-h')) {
+    printStageUsage(stageName)
+    process.exit(0)
+  }
+
   const isAuxiliary = auxiliaryStages.includes(stageName)
   // scan 元数据追踪（存储在 stageData.scanMeta 中，completeStep 通过 progress 访问）
 
@@ -628,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)
@@ -673,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}`)
@@ -853,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 })
   }