sillyspec 3.25.3 → 3.25.5

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

@@ -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-quick/SKILL.md

@@ -87,7 +87,8 @@ sillyspec run quick --files src/phone.ts,src/phone.test.ts
 - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
 - quick 直接在主工作区改代码（不创建 worktree），范围必须小且明确
 - 完成后立即 `--done`，不跳过
-- QUICKLOG 记录由 **CLI 接管**：启动时 CLI 自动分配 ql-ID 并在 `.sillyspec/quicklog/QUICKLOG-<user>.md` 写「进行中」条目（含关联变更 tasks.md），完成时 CLI 自动翻「已完成」并勾选 task。**你无需手写 QUICKLOG / tasks.md**，只需用注入的 `<quicklog-id>` 在模块文档变更索引引用
+- QUICKLOG 记录的**骨架由 CLI 接管**：启动时 CLI 自动分配 ql-ID 并在 `.sillyspec/quicklog/QUICKLOG-<user>.md` 写「进行中」条目（含关联变更 tasks.md），`--done` 时 CLI 自动翻「已完成」+ 勾选 task + 回填文件路径。ql-ID 分配/状态/task 你无需手写，只需用注入的 `<quicklog-id>` 在模块文档变更索引引用
+- **QUICKLOG 正文精修（`--done` 后必做，不可跳过）**：CLI 落盘的是简版骨架（标题可能是 `(quick 任务)`、文件是单行逗号无括注），**不合格**。`--done` 成功后必须立即编辑本次 `<quicklog-id>` 条目，手动精修成丰富格式：① 标题改真实需求摘要（禁 `(quick 任务)`）；② 文件改多行 bullet、每行带关键改动括注（禁 `（见实际改动）` 或无括注纯路径）；③ 正文 `需求：`/`根因：`/`方案：`/`结果：` 四段逐项充实（禁只留一段「结果：」）。参照同文件早期丰富条目。一条 quick = 一条独立 ql，不追加到旧条目
 - **最后一步 `--done --output` 必须按结构化结果模板给全四字段**（逐项一句话）：`需求：… 根因：… 方案：… 结果：…`。这是 QUICKLOG「结果：」归档的唯一来源；CLI 校验缺字段会拒绝 `--done`（exit 1），补全后重跑即可。前两个 step 的 `--output` 是中间摘要，不用此模板
 - **禁止**在没有运行 CLI 的情况下自行决定流程
 

package/package.json

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

package/src/change-list.js

@@ -90,6 +90,18 @@ function isPathHeaderCell(c) {
   return /^(文件路径|文件名|文件|路径|filepath|filename|file\s*path|path)$/i.test(c)
 }
 
+/**
+ * 路径合理性兜底：合法路径必含目录分隔 `/` 或扩展名点；
+ * 两者皆无时仅保留纯 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.md 解析文件变更清单。兼容两种真实写法：
  *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
@@ -147,6 +159,7 @@ 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)
       continue
     }
@@ -156,6 +169,7 @@ export function parseFileChangeList(designMdPath) {
     if (listItem) {
       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)
     }

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/index.js

@@ -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}`,
+        };
       }
     }
 

package/src/run/command.js

@@ -884,7 +884,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
     // Auto 模式下 brainstorm 使用 artifact-first 步骤
     if (stage === 'brainstorm') {
       const existingSteps = progress.stages?.brainstorm?.steps
-      const isAutoModeSteps = existingSteps?.length === 4 && existingSteps?.[0]?.name === '状态检查与上下文加载'
+      const isAutoModeSteps = existingSteps?.length === 4 && existingSteps?.[0]?.name === '进度确认与上下文加载'
       if (!isAutoModeSteps) {
         if (!progress.stages) progress.stages = {}
         progress.stages.brainstorm = {

package/src/run/complete-handlers.js

@@ -29,6 +29,7 @@ import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview } from './quick-audit.js'
 import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
+import { archiveDestDirName } from '../stage-contract.js'
 
 /**
  * 清洗项目名：只保留 ASCII 字母/数字/横线/下划线/点，过滤中文和特殊字符。
@@ -101,7 +102,8 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
   const archiveDir = join(changesDir, 'archive')
   const srcDir = join(changesDir, archiveChangeName)
   const date = new Date().toISOString().slice(0, 10)
-  const destDir = join(archiveDir, `${date}-${archiveChangeName}`)
+  const destName = archiveDestDirName(date, archiveChangeName)
+  const destDir = join(archiveDir, destName)
 
   if (!existsSync(srcDir)) {
     console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
@@ -157,7 +159,7 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
     console.warn(`⚠️  归档 worktree 清理失败（不阻断归档）: ${e.message}`)
   }
 
-  console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
+  console.log(`📦 已归档：${archiveChangeName} → archive/${destName}/`)
   return destDir
 }
 /**

package/src/run/complete.js

@@ -211,6 +211,23 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   // execute Wave artifact（W6 Step6c 抽至 complete-handlers.js handleExecuteWaveArtifact）
   await handleExecuteWaveArtifact({ stageName, steps, currentIdx, changeName, specBase, cwd })
 
+  // execute 批量完成检测：plan 全勾 + 代码客观核验通过 → 剩余 step 一次性标 completed，
+  // 使本次 --done 直接进入阶段完成分支（治"3 Wave 做完仍逐次 +1、需重走 7 次 --done"）。
+  // 先按 review.json pass 自动勾 plan checkbox（复用 continueStep 同源逻辑），再判批量条件。
+  if (stageName === 'execute' && changeName) {
+    const _ac = await autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts })
+    if (_ac.autoChecked) {
+      console.log(`   ✅ 自动勾选 ${_ac.checkedCount} 个 task checkbox（基于 review.json pass）`)
+    }
+    if (_ac.skippedCount > 0) {
+      console.warn(`   ⚠️ ${_ac.skippedCount} 个 task 未勾（review.json 缺失/fail）→ 批量完成条件不满足，仍按单步推进`)
+    }
+    const _bf = await detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBase, steps })
+    if (_bf.batched && _bf.aligned > 0) {
+      console.log(`\n🚀 execute 批量完成：plan 全勾 + 代码核验通过，一次性补完 ${_bf.aligned} 个剩余 step → 进入阶段完成分支`)
+    }
+  }
+
   const nextPendingIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
 
   if (nextPendingIdx === -1) {
@@ -349,6 +366,92 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
 }
 
 // ── Step 调度兄弟函数（W6 Step7b-2 从 run.js 搬入：skip/wait/continue + formatWaitHistory）──
+/**
+ * plan.md checkbox 自动勾选：execute 完成 + 各 task review.json 双 verdict 非 fail → 自动勾选。
+ * 治本于"plan 全靠手动勾、易遗漏"——以 review.json pass 为客观依据勾选。供 continueStep 完成段
+ * 与 completeStep 的 execute 批量完成检测复用（避免两处复制）。
+ *
+ * @returns {{autoChecked:boolean, checkedCount:number, skippedCount:number, planTotal:number, planChecked:number}}
+ *   planTotal/planChecked 在调用方于本函数之后用 readPlanCheckboxStatus 重读（勾选已落盘）。
+ */
+async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts }) {
+  if (stageName !== 'execute' || !changeName) {
+    return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
+  }
+  try {
+    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const changeDir = join(specBaseLc, 'changes', changeName)
+    const planPath = join(changeDir, 'plan.md')
+    const runtimeRoot = platformOpts?.runtimeRoot || join(specBaseLc, '.runtime')
+    const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
+    if (!existsSync(planPath) || !existsSync(runIdFile)) {
+      return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
+    }
+    const executeRunId = readFileSync(runIdFile, 'utf8').trim()
+    const planContent = readFileSync(planPath, 'utf8')
+    const { readReview } = await import('../task-review.js')
+    let checkedCount = 0
+    let skippedCount = 0
+    const updated = planContent.replace(/^(\s*[-*]\s*\[)\s(\]\s*task-\d+)/gim, (match, p1, p2) => {
+      const taskNum = match.match(/task-(\d+)/)[1].padStart(2, '0')
+      const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', `task-${taskNum}`, 'review.json')
+      const r = readReview(reviewPath)
+      if (r.ok && r.review?.specVerdict !== 'fail' && r.review?.qualityVerdict !== 'fail') {
+        checkedCount++
+        return `${p1}x${p2}`   // 勾选
+      }
+      skippedCount++
+      return match              // 不勾
+    })
+    if (checkedCount > 0) {
+      writeFileSync(planPath, updated)
+    }
+    return { autoChecked: checkedCount > 0, checkedCount, skippedCount }
+  } catch {
+    return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
+  }
+}
+
+/**
+ * execute 批量完成检测：plan.md 所有 task checkbox 已勾 + 代码客观核验非零变更 →
+ * 把剩余 pending/in-progress step 一次性标 completed，使 completeStep 本次 --done 即进入阶段完成
+ * 分支（而非逐次 +1）。治"3 Wave 全做完仍显示未开工、需重走 7 次 --done"。
+ * 复用现成能力：readPlanCheckboxStatus（plan 勾选状态）+ checkExecuteCodeEvidence（代码客观核验，
+ * 与 doctor --align-execute-progress 同源，D-002/D-004）。仅在 stageName==='execute' && changeName 触发。
+ *
+ * 安全门：plan 零 checkbox / 未全勾 / 代码零变更（unchanged）均不批量——信任 plan 声明但用代码核验兜底。
+ * @returns {Promise<{batched:boolean, aligned:number, reason?:string}>}
+ */
+async function detectExecuteBatchFinish({ pm, stageName, changeName, cwd, specBase, steps }) {
+  if (stageName !== 'execute' || !changeName) return { batched: false, aligned: 0 }
+  try {
+    const changeDir = join(specBase, 'changes', changeName)
+    const { total: planTotal, checked: planChecked } = pm.readPlanCheckboxStatus(changeDir)
+    if (planTotal === 0) return { batched: false, aligned: 0, reason: 'plan.md 无 task checkbox' }
+    if (planChecked < planTotal) {
+      return { batched: false, aligned: 0, reason: `plan 未全勾（${planChecked}/${planTotal}）` }
+    }
+    // plan 全勾 → 代码客观核验（防 plan 被手动勾伪造导致空完成）
+    const { checkExecuteCodeEvidence } = await import('../stage-contract.js')
+    const evidence = checkExecuteCodeEvidence(cwd, changeName)
+    if (evidence.status === 'unchanged') {
+      return { batched: false, aligned: 0, reason: `代码零变更（${evidence.detail}）` }
+    }
+    const now = new Date().toLocaleString('zh-CN', { hour12: false })
+    let aligned = 0
+    for (const step of steps) {
+      if (step.status === 'pending' || step.status === 'in-progress') {
+        step.status = 'completed'
+        step.completedAt = now
+        aligned++
+      }
+    }
+    return { batched: true, aligned }
+  } catch {
+    return { batched: false, aligned: 0 }
+  }
+}
+
 function formatWaitHistory(step) {
   const answers = Array.isArray(step.waitAnswers) ? step.waitAnswers : []
   if (answers.length === 0) return null
@@ -621,38 +724,13 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
         console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
         console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)
         // plan.md checkbox auto-check：execute 完成 + review.json pass → 自动勾选（治本，比警告可靠）
-        try {
-          const specBaseLc = platformOpts.specRoot || join(cwd, '.sillyspec')
-          const changeDir = join(specBaseLc, 'changes', changeName)
-          const planPath = join(changeDir, 'plan.md')
-          const runtimeRoot = platformOpts.runtimeRoot || join(specBaseLc, '.runtime')
-          const runIdFile = join(runtimeRoot, `current-execute-run-id-${changeName}`)
-          if (existsSync(planPath) && existsSync(runIdFile)) {
-            const executeRunId = readFileSync(runIdFile, 'utf8').trim()
-            const planContent = readFileSync(planPath, 'utf8')
-            const { readReview } = await import('../task-review.js')
-            let checkedCount = 0
-            let skippedCount = 0
-            const updated = planContent.replace(/^(\s*[-*]\s*\[)\s(\]\s*task-\d+)/gim, (match, p1, p2) => {
-              const taskNum = match.match(/task-(\d+)/)[1].padStart(2, '0')
-              const reviewPath = join(runtimeRoot, 'execute-runs', executeRunId, 'tasks', `task-${taskNum}`, 'review.json')
-              const r = readReview(reviewPath)
-              if (r.ok && r.review?.specVerdict !== 'fail' && r.review?.qualityVerdict !== 'fail') {
-                checkedCount++
-                return `${p1}x${p2}`   // 勾选
-              }
-              skippedCount++
-              return match              // 不勾
-            })
-            if (checkedCount > 0) {
-              writeFileSync(planPath, updated)
-              console.log(`   ✅ 自动勾选 ${checkedCount} 个 task checkbox（基于 review.json pass）`)
-            }
-            if (skippedCount > 0) {
-              console.warn(`   ⚠️ ${skippedCount} 个 task 未勾（review.json 缺失/fail）→ archive 会拦。补 review 后重跑 execute --done 触发自动勾`)
-            }
-          }
-        } catch {}
+        const _ac = await autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOpts })
+        if (_ac.autoChecked) {
+          console.log(`   ✅ 自动勾选 ${_ac.checkedCount} 个 task checkbox（基于 review.json pass）`)
+        }
+        if (_ac.skippedCount > 0) {
+          console.warn(`   ⚠️ ${_ac.skippedCount} 个 task 未勾（review.json 缺失/fail）→ archive 会拦。补 review 后重跑 execute --done 触发自动勾`)
+        }
       }
     }
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }

package/src/run/prompt.js

@@ -517,6 +517,26 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // archive Step1「任务完成度检查」客观真相源注入：以 review.json verdict 算完成度，
+  // 替代「机械数 plan.md checkbox」（checkbox 依赖 autoCheckPlanFromReviews 回填，runId marker /
+  // review 缺失时回填静默 no-op，会停在未勾态导致完成度失真 → archive 误判「全未完成」）。
+  // summarizeTaskCompletion 内部已 fail-safe 降级（无 plan / 无 runId → checkbox 统计 + 标注 source），
+  // 此处仅兜底注入异常，绝不阻断 archive。
+  if (stageName === 'archive' && promptText.includes('{TASK_COMPLETION_REPORT}')) {
+    try {
+      const { summarizeTaskCompletion } = await import('../task-review.js')
+      const tcrSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+      const tcrRuntimeRoot = platformOpts?.runtimeRoot || join(tcrSpecBase, '.runtime')
+      const tcrChangeDir = changeName ? join(tcrSpecBase, 'changes', changeName) : null
+      const summary = tcrChangeDir
+        ? summarizeTaskCompletion({ changeDir: tcrChangeDir, runtimeRoot: tcrRuntimeRoot, changeName })
+        : null
+      promptText = promptText.split('{TASK_COMPLETION_REPORT}').join(summary ? summary.report : '（无法计算完成度：变更目录缺失）')
+    } catch (e) {
+      promptText = promptText.split('{TASK_COMPLETION_REPORT}').join('（完成度计算异常：' + e.message + '，请手动核对 plan.md 与 .runtime/execute-runs/*/tasks/task-NN/review.json）')
+    }
+  }
+
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
     const effectiveSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')