sillyspec 3.25.9 → 3.25.11

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

@@ -59,24 +59,19 @@ sillyspec run auto --input "<用户需求>" [--mode <模式>]
 | `--spec-dir <path>` | 指定规范目录 |
 | `--non-interactive` | CI/脚本下禁用交互 |
 
-## 阶段审核门控
+## 阶段审核门控（Stage Review Gate）
 
-**brainstorm 完成后**，评估需求复杂度（基于 design.md 的模块拆分、批量操作、多角色交互特征）：
+审核发生在 brainstorm / plan / execute 各阶段的 review 步骤，**分级由 CLI 按变更规模自动判定**（不是 agent 凭关键词或复杂度启发式判断）：
 
-| 复杂度 | 审核策略 |
-|--------|---------|
-| 简单（无拆分、无批量） | 不审核，直接进入 plan |
-| 中等（有拆分或批量） | 启动 1 个审核子代理（QA 视角）审查 design.md |
-| 复杂（拆分 + 批量/多角色） | 启动 2-3 个审核子代理多角度审查 |
+- **tier=self**（变更 ≤3 文件）：当前 agent 自审，直接产 review.json。
+- **tier=independent**（变更 >3 文件）：必须派发**独立 QA 子代理**（独立上下文，不共享实现者分析）产 review.json。
 
-多角度审核子代理分工：
-- **架构师** — 设计合理性、技术选型 trade-off、模块划分
-- **安全专家** — 安全隐患、权限设计、数据校验
-- **QA 专家** — 需求覆盖率、边界场景、验收标准
+CLI 会在 review 步骤注入：完整 JSON schema 表 + 示例 + docHash 算法 + 自动决策 checklist（AC-001 起，逐条核验公共 API / schema / 鉴权 / 文件边界 / 依赖 / 核心模块 / 兼容性 / 业务等维度）。你按**实际注入的契约与 tier 指令**执行：
 
-审核流程：暂停提示复杂度 → 用户确认 → 启动子代理读 design/requirements/tasks → 汇总问题 → 询问是否修改 → 需要则修复重审，不需要则进下一阶段。
+- checklist 全 ✅ 且方案唯一合理 → AUTO_DECIDED，推进下一阶段
+- checklist 有 ❌（影响架构/数据/接口/权限/兼容性/业务）→ 暂停，用 AskUserQuestion 让用户选择
 
-**plan 完成后**，同样评估复杂度启动审核（项目经理审拆解粒度、工程师审可行性、QA 审验收标准）。
+**不要**自行编造"简单/中等/复杂 → N 个审核子代理"规则——审核子代理数量由 tier 决定（self=0 额外子代理，independent=1 个独立 QA），不是复杂度启发式；以 CLI 实际注入的 tier 与 checklist 为准。
 
 ## 关键规则
 

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

@@ -50,16 +50,18 @@ sillyspec run brainstorm --done --answer "..." --output "..."    # 一步完成
 
 > 自动去重：若前置 step 已对同一问题（waitReason 归一化后相同）确认过，后续重复 wait 会自动跳过，无需再 `--wait`。
 
-- **方式一（推荐）**：AI 自行与用户交互后，一步完成：
-  ```bash
-  sillyspec run brainstorm --done --change <名> --answer "用户回答" --output "需求已澄清"
-  ```
-- **方式二**：分步——先 `--wait` 记录等待，再 `--continue --answer`，最后 `--done`：
+- **方式一（推荐）**：分步——先 `--wait` 记录等待，让用户亲眼看到 CLI 打出的选项再作答，再 `--continue --answer`，最后 `--done`：
   ```bash
   sillyspec run brainstorm --wait --change <名> --reason "等待用户回答" --output "探索问题"
   sillyspec run brainstorm --continue --answer "用户回答" --change <名>
   sillyspec run brainstorm --done --change <名> --output "需求已澄清"
   ```
+- **方式二**：AI 自行与用户交互后，一步完成（仅在用户已在对话中明确给出答案、无需再走 CLI 等待展示时用）：
+  ```bash
+  sillyspec run brainstorm --done --change <名> --answer "用户回答" --output "需求已澄清"
+  ```
+
+> ⚠️ 两种方式都要求 `--answer` 是**用户真实的回答**，不是你替用户编的回答。`requiresWait` 门只校验 `--answer` 非空，挡不住「AI 伪造用户回答」——所以对方案选择/设计确认这类关键决策，优先用方式一让用户亲手作答，而不是 AI 中继一句话带过。
 
 ## 阶段流转
 
@@ -99,7 +101,7 @@ brainstorm 在 `tier=independent` 规模下除 design.md 等四件套外，还
   ```
 
 - `docHash` = `sha256(主审查文档内容)`（hex）—— brainstorm 主文档是 `design.md`（即 `reviewedFiles[0]`）。CLI 重算 sha256 比对，不符判伪造（fail-closed）。改 design.md 后须重算 docHash。`tier=self`（≤3 文件）降级为当前 agent 自审，不强制独立子代理。
-- 运行时 CLI 通过 `{REVIEW_JSON_CONTRACT}` 注入精确 schema+示例，以注入版为权威逐字模板。
+- 运行时 CLI 会把精确 schema 表 + 完整 JSON 示例 + docHash 算法注入到该步 prompt，以你实际收到的注入版契约为权威逐字模板。
 
 ## 铁律
 

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

@@ -16,15 +16,15 @@ description: 自动判断并执行下一步
 
 2. .sillyspec/changes/ 有进行中的变更？
    2a. 没有任何文件 → 提示检查 proposal 是否需要完善
-   2b. 没有 design.md → 提示补充 design
-   2c. 没有 tasks.md → 执行 /sillyspec:propose（补全规范）
+   2b. 没有 design.md → 提示补充 design（运行 /sillyspec:brainstorm 推进到设计产物步）
+   2c. 没有 tasks.md → 执行 /sillyspec:brainstorm（规范文件 proposal/requirements/tasks 由 brainstorm 末步生成）
    2d. 有 tasks.md 但没有 plan.md → 执行 /sillyspec:plan
    2e. tasks.md 有未完成项 + 有计划文件 → 执行 /sillyspec:execute
    2f. tasks.md 全完成 + 没验证 → 执行 /sillyspec:verify
    2g. 已验证通过 → 执行 /sillyspec:archive
 
 3. 有设计文档但没有对应变更？
-   → 提示运行 /sillyspec:propose <name>
+   → 提示运行 /sillyspec:brainstorm（基于设计文档建立变更并生成规范文件）
 
 4. 有 .sillyspec/docs/*/scan/ 但没有进行中的工作？
    → 提示运行 /sillyspec:brainstorm "你的想法"

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

@@ -62,7 +62,7 @@ sillyspec runtime list                                              # 枚举 .si
 >
 > `--cleanup-remnant` 清理 init/平台切换残留的 0 字节空 db（占位但无数据）。默认 dry-run 只报告，`--confirm` 才删。绝不删有内容的 db。
 >
-> `runtime list` 是只读枚举：列出 `.sillyspec/.runtime/` 下的 db、doctor-diagnosis.json、workflow-runs/、gate-status.json、user-inputs.md 等产物及用途。多会话/压缩后想知道「我手上有哪些证据文件」时用。加 `--json` 程序化读取。
+> `runtime list` 是只读枚举：列出 `.sillyspec/.runtime/` 下的 db、doctor-diagnosis.json、workflow-runs/、user-inputs.md 等产物及用途。多会话/压缩后想知道「我手上有哪些证据文件」时用。加 `--json` 程序化读取。
 
 ## 铁律
 

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

@@ -42,7 +42,7 @@ sillyspec run execute --reopen --from-step N   # 重新打开已完成阶段修
 - worktree 路径在步骤 prompt 中输出（`worktreePath`），后续子代理的 cwd 必须设为该路径
 - **禁止跳过 worktree 或在主仓库直接写代码**
 - worktree 创建失败时 CLI 报错退出，排查后重试
-- dirty 状态/未提交文件**不影响** worktree 创建和进入，直接按 CLI 输出的路径操作，不要自行检查 git 状态
+- worktree 创建/进入不依赖工作区 git 状态（dirty/未提交文件均可）：直接按 CLI 输出的路径操作，无需自行检查 git 状态；`sillyspec worktree apply` 步以命令实际输出为准（apply 会校验 dirty，按输出处理）
 - create 时若检测到 base 落后/分叉 `origin/<默认分支>`，CLI 会醒目报告（⚠️「落后 N 个 commit」+ 对齐命令），**不阻断** execute。看到此报告时评估是否提示用户先对齐 main，但**不要自行 fetch/ff**——对齐是用户/主仓库的显式动作
 
 ### 依赖门控（depsStatus）
@@ -88,7 +88,7 @@ execute 完成时，每个 task 必须有 `review.json` 且 verdict 通过，否
 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"`）：
+- 字段（`schemaVersion:1`，`reviewType=acceptance` —— 区别于 brainstorm/plan 的 `"design"`）：
 
   ```json
   {
@@ -106,11 +106,17 @@ execute 还有**第二道**独立的 stage 级审查：除逐 task review.json
   }
   ```
 
-- `docHash` = `sha256(主审查文档内容)`（hex）—— execute 主审查文档是 `design.md`，即 `reviewedFiles[0]`。CLI 会重算 sha256 比对，不符判伪造（fail-closed）；找不到主文档也 fail。**改 design.md 后须重算 docHash 再写**，可用 `sillyspec run execute --done` 触发的 prompt 注入版契约（`{REVIEW_JSON_CONTRACT}`）逐字改值。
+- `docHash` = `sha256(主审查文档内容)`（hex）—— execute 主审查文档是 `design.md`，即 `reviewedFiles[0]`。CLI 会重算 sha256 比对，不符判伪造（fail-closed）；找不到主文档也 fail。**改 design.md 后须重算 docHash 再写**，可用 `sillyspec run execute --done` 触发的 prompt 注入版契约（运行时注入的 schema 表 + JSON 示例 + docHash 算法）逐字改值。
 - `tier=independent` 时必须由独立 QA 子代理产出该 review.json（独立上下文，不共享实现者分析）；`tier=self`（变更 ≤3 文件）降级为当前 agent 自审。
 - 该 acceptance review 同时覆盖"代码审查"视角，后续代码审查步骤仅需轻量复审。
 
-> 运行时 CLI 会把精确 schema 表 + 完整 JSON 示例 + docHash 算法通过 `{REVIEW_JSON_CONTRACT}` 占位符注入到该步 prompt（源码 `src/stage-review.js: renderReviewJsonContract()`）。本段为常驻摘要；以运行时注入的契约为权威逐字模板。
+> 运行时 CLI 会把精确 schema 表 + 完整 JSON 示例 + docHash 算法注入到该步 prompt。本段为常驻摘要；以你实际收到的注入版契约为权威逐字模板。
+
+## 派发模式（SillyHub MCP，可选）
+
+`execute` Wave 内的子代理默认用本机 Agent tool 执行。若消费方配置了 SillyHub MCP（`SILLYHUB_MCP_URL` / `SILLYHUB_MCP_TOKEN`），Wave 步骤 prompt 运行时可能注入一段 SillyHub 派发指令——**出现就照其中的指令执行**（创建 mission / dispatch_worker / 轮询结果 / 本机兜底），**没出现就用本机 Agent tool**。未配置 MCP 时完全不注入，行为与无此机制一致。
+
+可选：`sillyspec dispatch probe` 查看 SillyHub 是否可用。
 
 ## worktree 子命令（execute 相关）
 

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

@@ -70,7 +70,7 @@ plan 的步骤是动态的：`generate_plan`（生成分级计划）→ `review_
   ```
 
 - `docHash` = `sha256(主审查文档内容)`（hex）—— plan 主文档是 `plan.md`（`reviewedFiles[0]`）。CLI 重算 sha256 比对，不符判伪造（fail-closed）。改 plan.md 后须重算 docHash。`tier=self`（≤3 文件）降级为当前 agent 自审。
-- 运行时 CLI 通过 `{REVIEW_JSON_CONTRACT}` 注入精确 schema+示例，以注入版为权威逐字模板。
+- 运行时 CLI 会把精确 schema 表 + 完整 JSON 示例 + docHash 算法注入到该步 prompt，以你实际收到的注入版契约为权威逐字模板。
 
 ### 契约门控（阻断完成）
 

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

@@ -44,7 +44,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）——该证据为 Agent 自报告，CLI 仅校验其字面存在、不独立运行时核验，须真实执行过
-- `verify-required-evidence.json`（execute 写入）中每条 missing evidence → 阻断
+- `verify-required-evidence.json`（execute 写入，schema `{items:[{task,verdict,evidence:[]}]}`）中 cannot_verify 任务未在 verify-result.md 体现 → **advisory warn（不阻断归档）**；evidence 是否真满足（satisfied/missing/partial）由 agent 在 verify-result.md 自报告，CLI 只查任务被提及、不替你语义判定。结论能否 PASS 由你诚实判定（有 missing evidence 不应 PASS）。
 
 被阻断时 CLI 打印 ❌ 校验失败，不会提示"验证通过"。修复 `verify-result.md` 后重新 `--done`。
 

package/README.md

@@ -57,6 +57,15 @@ npx sillyspec init --interactive      # 完整引导
 
 > 💡 启动 AI 时推荐使用跳过权限模式（如 `claude --dangerously-skip-permissions`）。SillySpec 会频繁执行 git、文件读写、校验脚本等操作，逐个批准会打断节奏——这也是 GSD / OpenSpec 的预期使用方式。
 
+## 平台支持
+
+SillySpec 进度库使用 SQLite 持久化（基于 better-sqlite3 原生绑定）。安装支持情况如下：
+
+- **主流平台（prebuilt 零编译安装）**：Node.js >= 18 的 Linux x64、macOS x64 / macOS arm64、Windows x64。安装时直接下载预编译二进制，无需本地 C++ 工具链。
+- **边缘平台不保证**：Alpine（musl libc）、Windows arm64、BSD 等平台可能没有对应的 prebuilt 二进制，安装时可能触发 node-gyp 从源码编译（此时需要本机具备 C++ 编译工具链）。
+
+如遇边缘平台编译失败，建议在受支持的平台或容器（如 Debian/Ubuntu 基镜像）中运行。
+
 ## 从哪里开始
 
 | 场景 | 命令 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.25.9",
+  "version": "3.25.11",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -29,12 +29,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.10.1",
+    "better-sqlite3": "^11.0.0",
     "chalk": "^5.6.2",
     "chokidar": "^4.0",
     "js-yaml": "^4.2.0",
     "open": "^10.1",
     "ora": "^9.3.0",
-    "sql.js": "^1.14.1",
     "ws": "^8.18"
   }
 }

package/src/change-list.js

@@ -152,7 +152,7 @@ const INCIDENTAL_RE = /顺带修复|附带修复|顺带|drive-?by|incidental/i
  *   ① 表格：`| 操作 | 文件路径 | 说明 |`（brainstorm 模板默认）
  *   ② 分类列表：`### 新增文件` / `### 修改文件` / `### 不修改文件` 下的 `- path`
  * 表头列顺序自适应（定位「文件/路径/file/path」列，列顺序写反时不会把操作名当路径）；
- * 忽略 `.sillyspec/` 与占位符（`—`/`-`/`N/A`/`无`）；「不修改/暂缓」子段下的路径会被排除；
+ * 忽略 `.sillyspec/`（keepSillyspecDocs=true 时保留 `.sillyspec/docs/`）与占位符（`—`/`-`/`N/A`/`无`）；「不修改/暂缓」子段下的路径会被排除；
  * CRLF 容错。incidental 嗅探：表格非路径列（说明列）+ 路径 cell 原始值（剥注释前的括号内容）+ 列表项原文。
  *
  * 内核函数：parseFileChangeList（Set 包装，向后兼容）与 parseFileChangeListDetailed 共用，
@@ -160,7 +160,7 @@ const INCIDENTAL_RE = /顺带修复|附带修复|顺带|drive-?by|incidental/i
  * @param {string} designMdPath - design.md 文件路径
  * @returns {Array<{ path: string, operation: string|null, incidental: boolean }>}（顺序按首次出现，exclude 子段移除）
  */
-function _parseFileListDetailed(designMdPath) {
+function _parseFileListDetailed(designMdPath, { keepSillyspecDocs = false } = {}) {
   if (!designMdPath || !existsSync(designMdPath)) return []
 
   const content = readFileSync(designMdPath, 'utf8').replace(/\r\n/g, '\n')
@@ -219,7 +219,7 @@ function _parseFileListDetailed(designMdPath) {
       const filePath = normalizePath(cells[pathColIdx] || '')
       // 列定位兜底：取到纯操作词（表头未命中且列顺序异常）→ 跳过，避免把「修改」当路径
       if (/^(新增|修改|删除|重命名|new|modify|update|delete|create|rename)$/i.test(filePath)) continue
-      if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
+      if (isPlaceholder(filePath) || (filePath.startsWith('.sillyspec/') && !(keepSillyspecDocs && filePath.startsWith('.sillyspec/docs/')))) continue
       if (!looksLikePath(filePath)) continue // 脏描述兜底：丢弃非路径自由文本（防虚高 fileCount）
       // operation：操作列 cell 分类（无操作列 → null）
       const operation = opColIdx >= 0 ? classifyOperation(cells[opColIdx] || '') : null
@@ -235,7 +235,7 @@ function _parseFileListDetailed(designMdPath) {
     const listItem = line.match(/^\s*-\s+(.+)/)
     if (listItem) {
       const filePath = normalizePath(listItem[1])
-      if (isPlaceholder(filePath) || filePath.startsWith('.sillyspec/')) continue
+      if (isPlaceholder(filePath) || (filePath.startsWith('.sillyspec/') && !(keepSillyspecDocs && filePath.startsWith('.sillyspec/docs/')))) continue
       if (!looksLikePath(filePath)) continue // 脏描述兜底
       const incidental = INCIDENTAL_RE.test(listItem[1])
       if (listMode === 'exclude') { entries.delete(filePath); continue }
@@ -249,10 +249,12 @@ function _parseFileListDetailed(designMdPath) {
 /**
  * 从 design.md 解析文件变更清单（路径集合，向后兼容）。
  * @param {string} designMdPath - design.md 文件路径
+ * @param {string} designMdPath - design.md 文件路径
+ * @param {{ keepSillyspecDocs?: boolean }} [opts] - keepSillyspecDocs=true 时保留 `.sillyspec/docs/`（dogfood 模块文档=交付物，apply gate 需识别；默认 false 跳过全部 .sillyspec/ 保持 fileCount 判档不变）
  * @returns {Set<string>} 文件路径集合（相对路径，如 "src/worktree.js"）
  */
-export function parseFileChangeList(designMdPath) {
-  return new Set(_parseFileListDetailed(designMdPath).map(e => e.path))
+export function parseFileChangeList(designMdPath, opts) {
+  return new Set(_parseFileListDetailed(designMdPath, opts).map(e => e.path))
 }
 
 /**
@@ -260,8 +262,9 @@ export function parseFileChangeList(designMdPath) {
  * operation 供 verify 删除探针对账（声明「新增/修改」却整文件删除 = 高风险）；
  * incidental 供 assess allowed_paths 豁免。
  * @param {string} designMdPath - design.md 文件路径
+ * @param {{ keepSillyspecDocs?: boolean }} [opts] - 同 parseFileChangeList
  * @returns {Array<{ path: string, operation: string|null, incidental: boolean }>}
  */
-export function parseFileChangeListDetailed(designMdPath) {
-  return _parseFileListDetailed(designMdPath)
+export function parseFileChangeListDetailed(designMdPath, opts) {
+  return _parseFileListDetailed(designMdPath, opts)
 }

package/src/change-risk-profile.js

@@ -92,6 +92,28 @@ export const INTEGRATION_FILE_PATTERNS = [
   /startup/i,
 ]
 
+/**
+ * task 级「端到端/deployment-critical」文本判定（execute 批量完成 autoCheckPlanFromReviews 用）。
+ *
+ * 聚焦需要真实集成/启动验证的 task，区别于 change 级 INTEGRATION_CRITICAL_PATTERNS（含 backend/session
+ * 等泛词——task 级用会误伤普通后端 task）。命中端到端集成语义（端到端/真实集成/daemon↔backend/
+ * integration test/e2e）或部署启动入口（cli.ts/main.ts/entrypoint/server/bootstrap/startup/docker）。
+ * 坑 execute-batch-complete-endtoend-checkbox：这类 task 的 review cannot_verify 不算 checked，
+ * 阻断 execute 批量完成（必须 pass），防端到端未真验就被批量放行（verify integration-evidence 兜底外的
+ * execute 侧前置门）。
+ * @param {string} text task 描述文本（plan.md task 行 + tasks/task-XX.md 内容）
+ * @returns {boolean}
+ */
+const END_TO_END_TASK_KEYWORDS = [
+  /端到端/, /真实集成/, /daemon.*backend/i, /integration\s*test/i, /e2e\s*test/i,
+  /runtime\s*evidence/i, /运行时证据/,
+  /\bcli\.ts\b/i, /\bmain\.ts\b/i, /\bentrypoint\b/i, /\bserver\.(js|ts)\b/i,
+  /\bbootstrap\b/i, /\bstartup\b/i, /启动/, /\bdockerfile\b/i, /\bdocker.?compose\b/i,
+]
+export function isEndToEndTaskText(text = '') {
+  return END_TO_END_TASK_KEYWORDS.some(re => re.test(text))
+}
+
 // ============ 核心检测函数 ============
 
 /**