sillyspec 3.25.5 → 3.25.7

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

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

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

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

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

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

package/package.json

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

package/src/change-list.js

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

package/src/constants.js

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

package/src/index.js

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

package/src/init.js

@@ -123,6 +123,70 @@ function injectInstructions(tool, projectDir) {
   writeFileSync(filePath, content.trimEnd() + '\n\n' + INJECTION_CONTENT);
 }
 
+// ── 注入 CLAUDE.md（claude，版本感知幂等）──
+// 与 codex/gemini/opencode 不同：claude 需要完整 CLAUDE.md 模板 + 版本感知三态。
+// 故 claude 不进 INSTRUCTION_TOOLS，单独走此函数（design: 2026-08-02-init-claude-md）。
+const CLAUDE_TEMPLATE_PATH = join(__dirname, '..', 'templates', 'claude-instruction.md');
+
+/**
+ * 为 Claude Code 注入 CLAUDE.md（版本感知幂等）。
+ * - 不存在：写完整模板（templates/claude-instruction.md）+ 顶部版本注释
+ * - 存在无标记：追加受管段（INJECTION_CONTENT）+ 版本块标记
+ * - 存在同版本标记：跳过
+ * - 存在异版本标记：追加态刷新块 / 完整态仅 stderr 提示
+ * @param {string} projectDir - 源码项目根
+ */
+export function injectClaudeInstructions(projectDir) {
+  const filePath = join(projectDir, 'CLAUDE.md');
+  const version = getVersion();
+  // 完整态顶部注释（新文件首行，轻量、不限制后续编辑）
+  const fullHeader = `<!-- SillySpec v${version} — 由 sillyspec init 生成，可自由编辑；重跑 init 同版本不更新 -->`;
+  // 追加态受管段（包版本块标记，明确"勿手动编辑此段"）
+  const appendBlock =
+    `<!-- SillySpec v${version} START — 由 sillyspec init 注入，勿手动编辑此段 -->\n` +
+    INJECTION_CONTENT.trimEnd() +
+    `\n<!-- SillySpec END -->`;
+
+  // 状态 1：文件不存在 → 写完整模板 + 顶部版本注释
+  if (!existsSync(filePath)) {
+    let template = '';
+    try {
+      template = readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8');
+    } catch {
+      console.error(`❌ [sillyspec] 未找到 Claude 模板：${CLAUDE_TEMPLATE_PATH}`);
+      return;
+    }
+    writeFileSync(filePath, fullHeader + '\n' + template);
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已生成（SillySpec v${version}）`));
+    return;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+
+  // 无任何 `<!-- SillySpec v` 标记 → 状态 2：追加受管段（原文字节保留）
+  const markMatch = content.match(/<!-- SillySpec v(\S+)/);
+  if (!markMatch) {
+    writeFileSync(filePath, content.trimEnd() + '\n\n' + appendBlock + '\n');
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已追加 SillySpec 受管段（v${version}）`));
+    return;
+  }
+
+  const existingVersion = markMatch[1];
+  // 状态 3：同版本 → 跳过（幂等，不写）
+  if (existingVersion === version) return;
+
+  // 状态 4：异版本（升级）。区分追加态（有 START...END 块）/ 完整态（仅顶部注释）。
+  const startBlockRe = /<!-- SillySpec v\S+\s+START[\s\S]*?<!-- SillySpec END -->/;
+  if (startBlockRe.test(content)) {
+    // 4a：追加态 → 用当前版本受管段替换该块（块外用户内容字节保留）
+    writeFileSync(filePath, content.replace(startBlockRe, appendBlock));
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 受管段已升级（v${existingVersion} → v${version}）`));
+  } else {
+    // 4b：完整态 → 不覆盖（保留用户改动），仅 stderr 打印升级提示
+    console.error(`⚠️ [sillyspec] SillySpec 升级 v${existingVersion}→v${version}，CLAUDE.md 未自动更新（保留你的改动）。如需采用新模板：备份后删除 CLAUDE.md 再跑 sillyspec init。`);
+  }
+}
+
 // ── 检测工具 ──
 
 function detectTools(projectDir) {
@@ -273,6 +337,11 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
     }
   }
 
+  // 注入 CLAUDE.md（claude，版本感知幂等三态四分支；claude 不进 INSTRUCTION_TOOLS）
+  if (tools.includes('claude')) {
+    injectClaudeInstructions(projectDir);
+  }
+
   // 复制 skills 到各工具目录
   const skillToolDirs = {
     claude: '.claude/skills',

package/src/quicklog.js

@@ -81,6 +81,36 @@ function sanitizeDesc(description) {
   return s.length > 120 ? s.slice(0, 120) + '…' : s
 }
 
+// 从关联变更的 proposal/design 提取首个 # 标题（去「提案书（Proposal）— / 设计文档（Design）—」固定前缀）。
+// 让 quick --linked-changes 启动时（用户常不带 --input）也能拿到语义标题，而非 (quick 任务) 占位。
+// 读不到任何标题返回 ''（调用方再回退占位符，保持向后兼容）。
+export function deriveTitleFromLinkedChange(specBase, change) {
+  if (!change) return ''
+  for (const f of ['proposal.md', 'design.md']) {
+    let content
+    try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
+    const m = content.match(/^#\s+(.+?)\s*$/m)
+    if (!m) continue
+    const raw = m[1].trim()
+    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc
+    const dash = raw.match(/[—-]\s*(.+)$/)
+    return dash ? dash[1].trim() : raw
+  }
+  return ''
+}
+
+// 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
+// （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
+function extractTitleFromResult(result) {
+  if (!result) return ''
+  const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
+  if (!m) return ''
+  let t = m[1].replace(/[，。；,;].*$/, '').trim() // 截到首个标点，取核心句
+  if (!t) return ''
+  if (t.length > 80) t = t.slice(0, 80) + '…'
+  return t
+}
+
 function sanitizeResult(resultText) {
   // 保留换行：结果块支持字段化结构（需求：/根因：/方案：/结果：...）。多行时 flipEntryInContent
   // 写成字段块（追加在「状态：」行下方），不是单条「结果：<长行>」。仅去首尾空白。
@@ -189,10 +219,13 @@ function tasksPath(specBase, change) {
   return join(specBase, 'changes', change, 'tasks.md')
 }
 
-// 追加未勾选 task；幂等（已含同 qlId 则跳过）
+// 追加未勾选 task；幂等（已含同 qlId 则跳过）。
+// 关联变更目录不存在（笔误 / 未建 / 仅作标签关联）→ 不 fabricate stub 目录（历史坑 quick-change-phantom：
+// mkdirSync 硬造 changes/<名>/tasks.md，致 quick --done 边界审计自造自拦 BLOCK）。关联仍记入
+// QUICKLOG「关联变更」行（allocateQuicklogEntry 独立写入，不依赖本函数）。
 function appendTaskCheckbox(specBase, change, qlId, desc) {
   const dir = join(specBase, 'changes', change)
-  mkdirSync(dir, { recursive: true })
+  if (!existsSync(dir)) return
   const p = tasksPath(specBase, change)
   let content = existsSync(p) ? readFileSync(p, 'utf8') : ''
   if (content.includes(qlId)) return
@@ -219,6 +252,12 @@ function flipEntryInContent(content, qlId, result, changedFiles = []) {
   const lines = content.split('\n')
   const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
   if (startIdx === -1) return null
+  // 翻完成时若能从结果提取「需求：」摘要，刷新标题行（覆盖启动时的占位/弱标题）
+  const newTitle = extractTitleFromResult(result)
+  if (newTitle) {
+    const headerCore = lines[startIdx].match(/^(## \S+ \| [^|]+ \| )/)
+    if (headerCore) lines[startIdx] = headerCore[1] + newTitle
+  }
   let endIdx = lines.length
   for (let i = startIdx + 1; i < lines.length; i++) {
     if (lines[i].startsWith('## ')) { endIdx = i; break }

package/src/run/command.js

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

package/src/run/complete-handlers.js

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