sillyspec 3.25.4 → 3.25.6

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
@@ -75,6 +75,32 @@ brainstorm 完成时按 design.md frontmatter 的 `scale` 分叉：
 
 > 规模由 AI 在 brainstorm 最后一步评估并写入 design.md frontmatter。判错可手动改 `scale` 后再跑相应阶段。
 
+### Stage Review Gate（brainstorm 末尾的 design review.json）
+
+brainstorm 在 `tier=independent` 规模下除 design.md 等四件套外，还需产出一个 stage 级 `review.json`，CLI `Stage Review Gate` 硬校验其 schema 与 `docHash` 真实性。
+
+- 路径：`.sillyspec/.runtime/stage-reviews/brainstorm-review-<stage-review-run-id>/review.json`（目录可能不存在需手建；run-id 由该步 `--done` prompt 输出指定）。marker 文件 `.runtime/current-stage-review-run-id-brainstorm-<变更名>`。
+- 字段（`schemaVersion:1`，`reviewType=design` —— 区别于 execute 的 `acceptance`）：
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "reviewType": "design",
+    "reviewedFiles": ["changes/<变更名>/design.md"],   // [0] 为主文档
+    "docHash": "<sha256(reviewedFiles[0] 文件内容，hex)>",
+    "specVerdict": "pass",       // pass | fail | cannot_verify
+    "qualityVerdict": "pass",    // pass | fail | cannot_verify
+    "checklist": [               // 扁平数组，逐条对照 design 章节核验
+      { "item": "背景与目标", "result": "pass", "note": "..." }   // result: pass | gap | fail
+    ],
+    "requiredEvidence": [],      // cannot_verify 时必填非空
+    "reviewerNotes": "..."
+  }
+  ```
+
+- `docHash` = `sha256(主审查文档内容)`（hex）—— brainstorm 主文档是 `design.md`（即 `reviewedFiles[0]`）。CLI 重算 sha256 比对，不符判伪造（fail-closed）。改 design.md 后须重算 docHash。`tier=self`（≤3 文件）降级为当前 agent 自审，不强制独立子代理。
+- 运行时 CLI 通过 `{REVIEW_JSON_CONTRACT}` 注入精确 schema+示例，以注入版为权威逐字模板。
+
 ## 铁律
 
 - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**

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

@@ -60,6 +60,58 @@ sillyspec worktree doctor --fix --change <变更名>
 
 execute 完成时，每个 task 必须有 `review.json` 且 verdict 通过，否则阻断完成。**例外**：task 在 `tasks/task-XX.md` frontmatter 声明 `low_risk: true`（type-only / 机械迁移等低逻辑风险）时，缺 review.json 只发 warning 不阻断。`cannot_verify` 的 task 会写入 `verify-required-evidence.json`，由 verify 阶段消费。
 
+#### task 级 review.json 契约（CLI 硬校验）
+
+- 路径：`.sillyspec/.runtime/execute-runs/<execute-run-id>/tasks/task-XX/review.json`（目录不存在需先建）。
+- `execute-run-id` 取自**第一次** `--done` prompt 输出（形如 `exec-2026-07-28-112833`），也写在 marker 文件 `.runtime/current-execute-run-id-<变更名>`。多个 run 时 gate 读最新 marker。
+- 字段（`schemaVersion:1`）：
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "task": "task-01",
+    "base": "<git-base-commit-hash>",
+    "head": "<git-head-commit-hash>",
+    "changedFiles": ["src/..."],
+    "specVerdict": "pass",        // pass | fail | cannot_verify
+    "qualityVerdict": "pass",     // pass | fail | cannot_verify
+    "reviewerNotes": "...",
+    "requiredEvidence": []        // cannot_verify 时必须非空
+  }
+  ```
+
+- `base` / `head` 必须是**真实 git commit**（`git rev-parse --verify`），否则判伪造并阻断。`changedFiles` 与实际 `git diff base..head` 完全不相交也判伪造。base..head 空 commit diff 但 working-tree 有未提交改动 → 视为有效改动（warning 不阻断）。
+- 后端 router task 另需在 `.sillyspec/.runtime/contract-artifacts/<task-name>/endpoints.json` 写 API 端点清单（扫 `@router.get/post/...`）。
+
+### Stage Review Gate（execute 末尾的 acceptance review.json）
+
+execute 还有**第二道**独立的 stage 级审查：除逐 task review.json 外，整个 execute 阶段完成还需一个 stage 级 `review.json`（在 "完成确认"/acceptance 步骤产出）。CLI `Stage Review Gate` 硬校验其 schema 与 `docHash` 真实性。
+
+- 路径：`.sillyspec/.runtime/stage-reviews/execute-review-<stage-review-run-id>/review.json`（目录可能不存在需手建；run-id 由该步 `--done` prompt 输出指定）。marker 文件 `.runtime/current-stage-review-run-id-execute-<变更名>`。
+- 字段（`schemaVersion:1`，`reviewType=acceptance` —— 区别于 brainstorm/plan/propose 的 `"design"`）：
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "reviewType": "acceptance",
+    "reviewedFiles": ["changes/<变更名>/design.md", "<可选追加 git diff 涉及的源码>"],
+    "docHash": "<sha256(reviewedFiles[0] 文件内容，hex)>",
+    "specVerdict": "pass",       // pass | fail | cannot_verify
+    "qualityVerdict": "pass",    // pass | fail | cannot_verify
+    "checklist": [               // 扁平数组（非按层嵌套！），逐条对照 design 章节 + FR/NFR/决策核验代码
+      { "item": "FR-01 排序", "result": "pass", "note": "..." }   // result: pass | gap | fail
+    ],
+    "requiredEvidence": [],      // cannot_verify 时必填非空
+    "reviewerNotes": "..."
+  }
+  ```
+
+- `docHash` = `sha256(主审查文档内容)`（hex）—— execute 主审查文档是 `design.md`，即 `reviewedFiles[0]`。CLI 会重算 sha256 比对，不符判伪造（fail-closed）；找不到主文档也 fail。**改 design.md 后须重算 docHash 再写**，可用 `sillyspec run execute --done` 触发的 prompt 注入版契约（`{REVIEW_JSON_CONTRACT}`）逐字改值。
+- `tier=independent` 时必须由独立 QA 子代理产出该 review.json（独立上下文，不共享实现者分析）；`tier=self`（变更 ≤3 文件）降级为当前 agent 自审。
+- 该 acceptance review 同时覆盖"代码审查"视角，后续代码审查步骤仅需轻量复审。
+
+> 运行时 CLI 会把精确 schema 表 + 完整 JSON 示例 + docHash 算法通过 `{REVIEW_JSON_CONTRACT}` 占位符注入到该步 prompt（源码 `src/stage-review.js: renderReviewJsonContract()`）。本段为常驻摘要；以运行时注入的契约为权威逐字模板。
+
 ## worktree 子命令（execute 相关）
 
 ```bash
@@ -80,6 +132,10 @@ plan → execute → verify
 
 execute 完成后（所有 Wave/task 完成 + Task Review Gate 通过），运行 `sillyspec run verify --change <变更名>` 验证。
 
+### 批量完成（一次 --done 收尾）
+
+当 `plan.md` 所有 task checkbox 已勾（人工勾或基于各 task `review.json` pass 由 CLI 自动勾）且代码客观核验通过（`checkExecuteCodeEvidence` 非"零变更"）时，任一 execute `--done` 会**一次性补完所有剩余 step** 直达阶段完成，不必逐次 +1 推进。日志会打印 `🚀 execute 批量完成：plan 全勾 + 代码核验通过，一次性补完 N 个剩余 step`。条件不满足（plan 未全勾 / 代码零变更）时仍按单步推进，要求补 review 后重跑 `--done` 直至满足。
+
 ## 铁律
 
 - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**

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

@@ -46,6 +46,32 @@ sillyspec run plan --done --answer "..." --output "..."    # 一步完成 wait+d
 
 plan 的步骤是动态的：`generate_plan`（生成分级计划）→ `review_plan`（审查计划，按规模分级：tier=self 当前 agent 自审 / tier=independent 启动独立审查子代理产出 stage review.json，避免生成+自审同一次输出的偏差）→ CLI 从 `plan.md` 解析出 task 自动插入"任务蓝图协调器"步骤（per-task）。这是正常行为，不要手动添加。
 
+### Stage Review Gate（plan 的 design review.json）
+
+`review_plan` 步骤在 `tier=independent` 时产出一个 stage 级 `review.json`，CLI `Stage Review Gate` 硬校验其 schema 与 `docHash` 真实性。
+
+- 路径：`.sillyspec/.runtime/stage-reviews/plan-review-<stage-review-run-id>/review.json`（目录可能不存在需手建；run-id 由该步 `--done` prompt 输出指定）。marker 文件 `.runtime/current-stage-review-run-id-plan-<变更名>`。
+- 字段（`schemaVersion:1`，`reviewType=plan` —— plan 阶段主审查文档是 `plan.md`；execute 阶段才是 `acceptance`）：
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "reviewType": "plan",
+    "reviewedFiles": ["changes/<变更名>/plan.md"],   // [0] 为主文档
+    "docHash": "<sha256(reviewedFiles[0] 文件内容，hex)>",
+    "specVerdict": "pass",       // pass | fail | cannot_verify
+    "qualityVerdict": "pass",    // pass | fail | cannot_verify
+    "checklist": [               // 扁平数组，逐条对照 plan 章节/Wave 结构/task 完整性核验
+      { "item": "Wave 分级合理", "result": "pass", "note": "..." }   // result: pass | gap | fail
+    ],
+    "requiredEvidence": [],      // cannot_verify 时必填非空
+    "reviewerNotes": "..."
+  }
+  ```
+
+- `docHash` = `sha256(主审查文档内容)`（hex）—— plan 主文档是 `plan.md`（`reviewedFiles[0]`）。CLI 重算 sha256 比对，不符判伪造（fail-closed）。改 plan.md 后须重算 docHash。`tier=self`（≤3 文件）降级为当前 agent 自审。
+- 运行时 CLI 通过 `{REVIEW_JSON_CONTRACT}` 注入精确 schema+示例，以注入版为权威逐字模板。
+
 ### 契约门控（阻断完成）
 
 - **plan 启动前**：CLI 校验 `design.md` 是否满足 plan 契约（缺文件变更清单/风险登记/自审章节会阻断）。若失败需先 `sillyspec run brainstorm --reopen --from-step N` 修订设计。

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

@@ -42,6 +42,32 @@ sillyspec run propose --reopen --from-step N   # 重新打开已完成阶段修
 
 propose 含自检步骤（按规模分级：tier=self 当前 agent 自审 / tier=independent 启动独立审查子代理产出 stage review.json），完成时校验四件套文档齐全 + 内容章节（如 proposal 的 Non-Goals、design 的文件变更清单/风险登记/自审）。缺失会阻断完成。
 
+### Stage Review Gate（propose 的 proposal review.json）
+
+propose 在 `tier=independent` 时产出一个 stage 级 `review.json`，CLI `Stage Review Gate` 硬校验其 schema 与 `docHash` 真实性。
+
+- 路径：`.sillyspec/.runtime/stage-reviews/propose-review-<stage-review-run-id>/review.json`（目录可能不存在需手建；run-id 由该步 `--done` prompt 输出指定）。marker 文件 `.runtime/current-stage-review-run-id-propose-<变更名>`。
+- 字段（`schemaVersion:1`，`reviewType=proposal` —— propose 阶段主审查文档是 `proposal.md`）：
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "reviewType": "proposal",
+    "reviewedFiles": ["changes/<变更名>/proposal.md"],   // [0] 为主文档
+    "docHash": "<sha256(reviewedFiles[0] 文件内容，hex)>",
+    "specVerdict": "pass",       // pass | fail | cannot_verify
+    "qualityVerdict": "pass",    // pass | fail | cannot_verify
+    "checklist": [               // 扁平数组，逐条对照 proposal 章节/Non-Goals 核验
+      { "item": "Non-Goals 明确", "result": "pass", "note": "..." }   // result: pass | gap | fail
+    ],
+    "requiredEvidence": [],      // cannot_verify 时必填非空
+    "reviewerNotes": "..."
+  }
+  ```
+
+- `docHash` = `sha256(主审查文档内容)`（hex）—— propose 主文档是 `proposal.md`（`reviewedFiles[0]`）。CLI 重算 sha256 比对，不符判伪造（fail-closed）。改 proposal.md 后须重算 docHash。`tier=self`（≤3 文件）降级为当前 agent 自审。
+- 运行时 CLI 通过 `{REVIEW_JSON_CONTRACT}` 注入精确 schema+示例，以注入版为权威逐字模板。
+
 ## 阶段流转
 
 ```

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.4",
+  "version": "3.25.6",
   "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)
 }
@@ -91,23 +128,45 @@ function isPathHeaderCell(c) {
 }
 
 /**
- * 从 design.md 解析文件变更清单。兼容两种真实写法：
+ * 路径合理性兜底：合法路径必含目录分隔 `/` 或扩展名点；
+ * 两者皆无时仅保留纯 ASCII 单词 token（Dockerfile / Makefile / LICENSE 这类无扩展名文件名），
+ * 丢弃含空格/中文的脏描述（如 design 表格第二列误写的「frontend 组件测试」「后端逻辑」）。
+ * 防止把自由文本当路径计入 fileCount，虚高 review-tier 分级（误推 independent）。
+ */
+function looksLikePath(p) {
+  if (!p) return false
+  if (p.includes('/') || p.includes('.')) return true
+  return /^[\w@-]+$/.test(p)
+}
+
+/**
+ * 「顺带修复」标记：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)
@@ -119,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
     }
 
@@ -140,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
       }
 
@@ -147,7 +220,14 @@ export function parseFileChangeList(designMdPath) {
       // 列定位兜底：取到纯操作词（表头未命中且列顺序异常）→ 跳过，避免把「修改」当路径
       if (/^(新增|修改|删除|重命名|new|modify|update|delete|create|rename)$/i.test(filePath)) continue
       if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
-      result.add(filePath)
+      if (!looksLikePath(filePath)) continue // 脏描述兜底：丢弃非路径自由文本（防虚高 fileCount）
+      // 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
     }
 
@@ -156,10 +236,32 @@ export function parseFileChangeList(designMdPath) {
     if (listItem) {
       const filePath = normalizePath(listItem[1])
       if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
-      if (listMode === 'exclude') result.delete(filePath)
-      else result.add(filePath)
+      if (!looksLikePath(filePath)) continue // 脏描述兜底
+      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/change-risk-profile.js

@@ -290,14 +290,49 @@ export const VERIFICATION_NEEDS = {
 export const RISK_LEVEL_CAUSES = {
   'deployment-critical':
     'design.md / plan.md 命中启动入口关键词（cli.ts / main.ts / server.(js|ts) / bootstrap / entrypoint）。' +
-    '注意：这是按 design/plan 里的措辞判定的，不一定代表你真改了启动入口；若属误判可在 design 中如实缩小范围，但不建议为绕门控而规避——危险链路该有真实启动证据。',
+    '注意：这是按 design/plan 里的措辞判定的，不一定代表你真改了启动入口；若属误判可在 design.md frontmatter 用 risk_level 显式声明真实等级（如 unit-sufficient）覆盖——不要靠删措辞绕门控，危险链路该有真实启动证据。',
   'integration-critical':
     'design.md / plan.md 命中跨进程/状态机关键词（daemon / backend / session / lease / lifecycle / heartbeat 等）。',
   'contract-required': 'design.md / plan.md 命中 API contract 关键词（api / client / contract / dto）。',
+  'explicit': 'design.md frontmatter 的 risk_level 显式声明（覆盖关键词判级）。',
+}
+
+/** design.md frontmatter 可显式声明的合法 risk_level 值（与 detectChangeRisk 判级结果同集合） */
+export const RISK_LEVELS = ['doc-only', 'unit-sufficient', 'contract-required', 'integration-critical', 'deployment-critical']
+
+/**
+ * 从 design.md 顶部 frontmatter 提取显式 risk_level 声明。
+ * 只认文档最开头 `---\n...\n---` 块内的 `risk_level: <level>` 单行（与 plan.md 的 plan_level 同款解析），
+ * 不扫正文——避免正文里讨论 risk_level 措辞时被误当声明。返回合法 level 或 null。
+ */
+export function extractExplicitRiskLevel(designContent = '') {
+  const fm = designContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!fm) return null
+  const line = fm[1].split('\n').map(l => l.trim()).find(l => l.startsWith('risk_level:'))
+  if (!line) return null
+  const value = line.slice('risk_level:'.length).trim().replace(/^["']|["']$/g, '').toLowerCase()
+  return RISK_LEVELS.includes(value) ? value : null
 }
 
 export function detectChangeRisk({ designContent = '', planContent = '', changedFiles = [] } = {}) {
   const triggers = []
+
+  // ── 显式豁免优先：design.md frontmatter 声明 risk_level → 以声明为准，跳过关键词判级 ──
+  // 历史教训：detectChangeRisk 是机械字面匹配，不认否定语境——design 写「本次不改动 daemon/session」
+  // 仍命中关键词被误判 integration/deployment-critical，强制要全套集成证据，对无状态后端变更误伤。
+  // 与其在正则层做脆弱的否定识别，不如给一条显式、诚实、可审计（落在 design frontmatter + verify-result）
+  // 的覆盖通道。声明仍走门控（结论 FAIL 仍拦），但豁免级（unit-sufficient 等）不再强制集成证据。
+  const explicit = extractExplicitRiskLevel(designContent)
+  if (explicit) {
+    const requiredVerification =
+      explicit === 'deployment-critical' ? ['unit_tests', 'contract_tests', 'real_daemon_backend_integration', 'runtime_log_evidence', 'real_startup_once'] :
+      explicit === 'integration-critical' ? ['unit_tests', 'contract_tests', 'real_daemon_backend_integration', 'runtime_log_evidence', 'terminal_state_assertion'] :
+      explicit === 'contract-required' ? ['unit_tests', 'contract_tests'] :
+      explicit === 'doc-only' ? ['static_check'] :
+      ['unit_tests']
+    return { level: explicit, triggers: ['risk_level (explicit)'], requiredVerification, explicit: true }
+  }
+
   const combined = [designContent, planContent].join('\n')
 
   for (const pattern of INTEGRATION_CRITICAL_PATTERNS) {

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 <模式>               显式指定流程模式
@@ -1226,6 +1226,9 @@ SillySpec modules — 模块文档管理
       lines.push('# module_paths:');
       lines.push('#   user-service: "user/"');
       lines.push('#   order-service: "order/"');
+      lines.push('# 已知预存失败（可选）：verify 实测时这些失败被豁免、不阻断归档；fail-safe 仅豁免能检测到的失败行');
+      lines.push('# known_failures:');
+      lines.push('#   - "tests/test_legacy.py::test_old"');
       const yamlText = lines.join('\n') + '\n';
 
       // 原子写（tmp + rename + Windows EPERM 重试），避免半截 local.yaml

package/src/machine-interface.js

@@ -225,7 +225,11 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot }
       const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName });
       const vtWarnings = [];
       if (vt.status === 'skipped') {
-        vtWarnings.push('⚠️ verify-test SKIPPED — gate 未核验测试（local.yaml 未配置 commands.test 或显式无测试）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL');
+        vtWarnings.push(`⚠️ verify-test SKIPPED — gate 未核验测试（${vt.reason || 'local.yaml 未配置 commands.test 或显式无测试'}）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL`);
+      }
+      // known_failures 豁免披露：本次 PASS 含豁免，driver 应提示人工复核清单是否过宽
+      if (vt.exemptedCount > 0) {
+        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）`);
       }
       // 全量 fallback 明示：跑了全量 commands.test 但非变更范围子集，失败可能含未变更
       // 模块的预存错误——driver 不应据 exit 0 判定本次变更范围已客观测试（见 3.24 verify 坑1）。

package/src/progress/stage-machine.js

@@ -287,22 +287,25 @@ export class StageMachine {
       }
     }
 
-    // 找到第一个 pending 主流程阶段
+    // 找主流程里第一个「未完成且上游已就绪」的阶段，推荐它作为下一步。
+    // 修两个缺陷（曾导致 brainstorm 完成后误推 archive）：
+    //   ① 原 steps.length>0 要求：plan/execute/verify 首次 run 前惰性未初始化(steps 空)被跳过；
+    //   ② 原 upstream 把 pending 当就绪：archive 的上游 plan/execute/verify 即便 pending 也算 ok。
+    //   叠加 → 循环跳过未初始化的中间阶段，漏到 archive(steps 非空)误推，违反流程顺序。
+    // 改为：不要求 steps(空=该开始了)；upstream 必须全 completed(pending 不算就绪)——
+    // archive 只在 scan/brainstorm/plan/execute/verify 全完成后才可能被推荐。
     for (const s of STAGE_ORDER) {
       const sd = data.stages[s];
-      if (sd && sd.status === 'pending' && sd.steps && sd.steps.length > 0) {
-        // 检查上游是否都 completed
-        const idx = STAGE_ORDER.indexOf(s);
-        const upstream = STAGE_ORDER.slice(0, idx);
-        const upstreamOk = upstream.every(us =>
-          data.stages[us]?.status === 'completed' || !data.stages[us] || data.stages[us].status === 'pending'
-        );
-        if (upstreamOk) {
-          return {
-            text: `可以开始 ${STAGE_LABELS[s] || s}。`,
-            command: `sillyspec run ${s}`,
-          };
-        }
+      if (!sd) continue;
+      if (sd.status === 'completed' || sd.status === 'skipped') continue;
+      const idx = STAGE_ORDER.indexOf(s);
+      const upstream = STAGE_ORDER.slice(0, idx);
+      const upstreamOk = upstream.every(us => data.stages[us]?.status === 'completed');
+      if (upstreamOk) {
+        return {
+          text: `可以开始 ${STAGE_LABELS[s] || s}。`,
+          command: `sillyspec run ${s}`,
+        };
       }
     }