sillyspec 3.25.0 → 3.25.2

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

@@ -51,9 +51,18 @@ sillyspec progress validate                    # 校验并修复
 sillyspec worktree doctor [--fix]              # worktree 健康检查 + 修复
 sillyspec doctor --align-execute-progress --change <name>          # 按 plan.md 声明对齐 execute 派生戳（dry-run，只报告将补哪些 step）
 sillyspec doctor --align-execute-progress --change <name> --confirm # 实际落盘：补 step 戳 + 置 execute stage status=completed
+sillyspec doctor --cleanup-remnant                                  # 扫描并报告 0 字节空占位 db（dry-run）
+sillyspec doctor --cleanup-remnant --confirm                        # 实际删除空占位 db（仅删 0 字节，不动有内容的 db）
+sillyspec doctor --dump-db --path <db 路径>                         # dump 指定 db 内容到文件（取证，查 stages/steps/changes 表）
+sillyspec doctor --json                                             # 结构化诊断 + 落盘 .sillyspec/.runtime/doctor-diagnosis.json
+sillyspec runtime list                                              # 枚举 .sillyspec/.runtime/ 下所有运行时产物（只读，看手上有哪些证据/状态文件）
 ```
 
 > `--align-execute-progress` 仅当 `plan.md` 所有 task checkbox 全勾时才对齐 execute 阶段进度戳。典型用于 worktree 已 cleanup（终态）但 execute 派生戳未盖上的死锁。默认 dry-run，加 `--confirm` 才写盘。doctor 信任 `plan.md` 声明、不复核代码，verify 阶段兜底。`--change` 缺省时按单活跃变更自动兜底。
+>
+> `--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` 程序化读取。
 
 ## 铁律
 

package/.playwright-mcp/console-2026-07-27T15-45-50-621Z.log

@@ -0,0 +1 @@
+[     809ms] [ERROR] Failed to load resource: the server responded with a status of 404 (File not found) @ http://localhost:8848/favicon.ico:0

package/.playwright-mcp/page-2026-07-27T15-45-51-459Z.yml

@@ -0,0 +1,144 @@
+- generic [active] [ref=e1]:
+  - banner [ref=e2]:
+    - generic [ref=e3]:
+      - generic [ref=e4]:
+        - text: Silly
+        - emphasis [ref=e5]: Spec
+      - generic [ref=e6]: Prompt Dossier
+    - generic [ref=e7]:
+      - text: ⌕
+      - textbox "搜索步骤名 / prompt 内容 / 占位符…" [ref=e8]
+    - generic [ref=e9]:
+      - generic [ref=e10]: 12 stages · 71 steps · 87k
+      - button "◐" [ref=e11] [cursor=pointer]
+  - generic [ref=e87]:
+    - navigation [ref=e88]:
+      - generic [ref=e89]:
+        - generic [ref=e90]:
+          - text: 主流程
+          - generic [ref=e91]: "4"
+        - generic [ref=e92] [cursor=pointer]:
+          - generic [ref=e93]: "01"
+          - generic [ref=e94]: 头脑风暴
+          - generic [ref=e95]: "8"
+        - generic [ref=e96] [cursor=pointer]:
+          - generic [ref=e97]: "02"
+          - generic [ref=e98]: 实现计划
+          - generic [ref=e99]: "5"
+        - generic [ref=e100] [cursor=pointer]:
+          - generic [ref=e101]: "03"
+          - generic [ref=e102]: 波次执行
+          - generic [ref=e103]: "12"
+        - generic [ref=e104] [cursor=pointer]:
+          - generic [ref=e105]: "04"
+          - generic [ref=e106]: 验证
+          - generic [ref=e107]: "7"
+      - generic [ref=e108]:
+        - generic [ref=e109]:
+          - text: 辅助
+          - generic [ref=e110]: "6"
+        - generic [ref=e111] [cursor=pointer]:
+          - generic [ref=e112]: "05"
+          - generic [ref=e113]: 项目扫描
+          - generic [ref=e114]: "11"
+        - generic [ref=e115] [cursor=pointer]:
+          - generic [ref=e116]: "06"
+          - generic [ref=e117]: 快速任务
+          - generic [ref=e118]: "3"
+        - generic [ref=e119] [cursor=pointer]:
+          - generic [ref=e120]: "07"
+          - generic [ref=e121]: 自由探索
+          - generic [ref=e122]: "1"
+        - generic [ref=e123] [cursor=pointer]:
+          - generic [ref=e124]: "08"
+          - generic [ref=e125]: 归档
+          - generic [ref=e126]: "5"
+        - generic [ref=e127] [cursor=pointer]:
+          - generic [ref=e128]: "09"
+          - generic [ref=e129]: 状态
+          - generic [ref=e130]: "3"
+        - generic [ref=e131] [cursor=pointer]:
+          - generic [ref=e132]: "10"
+          - generic [ref=e133]: 自检
+          - generic [ref=e134]: "5"
+      - generic [ref=e135]:
+        - generic [ref=e136]:
+          - text: 变体
+          - generic [ref=e137]: "1"
+        - generic [ref=e138] [cursor=pointer]:
+          - generic [ref=e139]: "11"
+          - generic [ref=e140]: 自动模式头脑风暴
+          - generic [ref=e141]: "4"
+      - generic [ref=e142]:
+        - generic [ref=e143]:
+          - text: 已废弃
+          - generic [ref=e144]: "1"
+        - generic [ref=e145] [cursor=pointer]:
+          - generic [ref=e146]: "12"
+          - generic [ref=e147]: propose · 已废弃
+          - generic [ref=e148]: "7"
+    - main [ref=e149]:
+      - generic [ref=e150]: 主流程 · STAGE 01
+      - heading "头脑风暴" [level=1] [ref=e151]
+      - paragraph [ref=e152]: 探索需求、分析技术方案、识别风险
+      - generic [ref=e153]:
+        - generic [ref=e154]: sourcesrc/stages/brainstorm.js
+        - generic [ref=e155]: persona资深架构师
+        - generic [ref=e156]: steps8
+      - generic [ref=e157]:
+        - button "全部展开" [ref=e158] [cursor=pointer]
+        - button "全部折叠" [ref=e159] [cursor=pointer]
+        - generic [ref=e160]: 8 STEPS
+      - generic [ref=e161]:
+        - article [ref=e162]:
+          - generic [ref=e163] [cursor=pointer]:
+            - generic [ref=e164]: 01 / 08
+            - generic [ref=e165]: 状态检查
+            - generic [ref=e166]: ▸
+        - article [ref=e167]:
+          - generic [ref=e168] [cursor=pointer]:
+            - generic [ref=e169]: 02 / 08
+            - generic [ref=e170]: 加载项目上下文
+            - generic [ref=e171]: ▸
+        - article [ref=e172]:
+          - generic [ref=e173] [cursor=pointer]:
+            - generic [ref=e174]: 03 / 08
+            - generic [ref=e175]: 对话式探索与需求澄清
+            - generic [ref=e176]:
+              - generic [ref=e177]: conditionalWait
+              - generic [ref=e178]: repeatable×8
+            - generic [ref=e179]: ▸
+        - article [ref=e180]:
+          - generic [ref=e181] [cursor=pointer]:
+            - generic [ref=e182]: 04 / 08
+            - generic [ref=e183]: 提出 2-3 种方案
+            - generic [ref=e184]: requiresWait
+            - generic [ref=e186]: ▸
+        - article [ref=e187]:
+          - generic [ref=e188] [cursor=pointer]:
+            - generic [ref=e189]: 05 / 08
+            - generic [ref=e190]: 分段展示设计
+            - generic [ref=e191]: requiresWait
+            - generic [ref=e193]: ▸
+        - article [ref=e194]:
+          - generic [ref=e195] [cursor=pointer]:
+            - generic [ref=e196]: 06 / 08
+            - generic [ref=e197]: 写设计文档并自审
+            - generic [ref=e198]: ▸
+        - article [ref=e199]:
+          - generic [ref=e200] [cursor=pointer]:
+            - generic [ref=e201]: 07 / 08
+            - generic [ref=e202]: Design Grill 交叉审查
+            - generic [ref=e203]: conditionalWait
+            - generic [ref=e205]: ▸
+        - article [ref=e206]:
+          - generic [ref=e207] [cursor=pointer]:
+            - generic [ref=e208]: 08 / 08
+            - generic [ref=e209]: 用户确认并生成规范文件
+            - generic [ref=e210]: requiresWait
+            - generic [ref=e212]: ▸
+  - contentinfo [ref=e213]:
+    - text: 数据机械提取自
+    - code [ref=e214]: src/stages/*.js
+    - text: · 单文件自包含 · file:// 可直接打开 · 生成命令：
+    - code [ref=e215]: node docs/prompt/_build-site.mjs

package/CLAUDE.md

@@ -20,3 +20,21 @@
 - [ ] 归档/清理流程描述与实际代码逻辑一致
 - [ ] 数据库 Schema 描述与 `src/db.js` 一致
 - [ ] 更新文档头部 `updated_at` 时间戳
+
+## 提示词文档同步（docs/prompt/）
+`docs/prompt/` 收录各阶段 CLI→Agent 的**逐步提示词原文**（人类可读 md 参考）。详见 `docs/prompt/README.md`。
+
+### 数据源关系（重要 — 避免双写漂移）
+- **唯一数据源 = `src/stages/*.js`**（`definition.steps[].prompt`，CLI 运行时读这里）+ `src/run/prompt.js`（注入框架：persona / 铁律 / 占位符替换 / 完成后执行命令模板）。
+- `docs/prompt/*.md` 是源码的**机械提取人类可读镜像**，由 `node docs/prompt/_extract.mjs` 一键再生（源码 → `_extracted.json` → md）。提取脚本对静态阶段直接读 `definition.steps`，对动态阶段（plan/execute）用示例输入跑 `buildPlanSteps`/`buildExecuteSteps` 得到真实 prompt。
+- **禁止手改 md 里的 prompt 原文**（下次提取会被覆盖，且与源码不一致）。要改提示词，改源码后重跑脚本。
+
+### 触发同步的改动
+- 修改 `src/stages/*.js`：`definition.steps[].prompt`、步骤名、步骤增删/重排、wait 配置、`_globalGuardrails`、title/description
+- 修改 `src/run/prompt.js`：persona / 铁律 / 占位符替换 / 完成后执行命令模板
+- 修改 `stage-review.js` / `review-tier.js` / `knowledge-match.js`：影响 `{REVIEW_JSON_CONTRACT}` / `{REVIEW_TIER}` / `{KNOWLEDGE_HIT_REPORT}` 等动态块
+
+### 同步步骤
+1. 改源码
+2. 运行 `node docs/prompt/_extract.mjs`（刷新 `docs/prompt/_extracted.json`）
+3. 按变动同步对应 `docs/prompt/<stage>.md`（prompt 正文以 `_extracted.json` 为准逐字替换）+ 必要时更新 `docs/prompt/README.md`（占位符总表 / persona 表 / CLI 注入框架）

package/package.json

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

package/src/change-risk-profile.js

@@ -251,6 +251,51 @@ export function detectRiskProfile({ designContent = '', planContent = '', change
  * 旧的 detectChangeRisk 接口保持向后兼容
  * @returns {{ level: string, triggers: string[], requiredVerification: string[] }}
  */
+// ============ 门控可执行化（A：报错说人话） ============
+//
+// 历史教训：integration-critical / deployment-critical 门控只报「缺少真实集成证据 / 需要真实
+// 启动验证证据」，agent 看不出具体缺哪一项、要写/做什么才算过，只能靠改结论文案撞墙。
+// 此处把每一项 requiredVerification 的需求（写什么 / 做什么）和判级原因显式导出，
+// 供 stage-contract 拼成可执行的报错信息。
+
+/** 每项 requiredVerification 的需求描述 + 字面期望 */
+export const VERIFICATION_NEEDS = {
+  unit_tests: {
+    desc: '单元测试（verify 必做；在 verify-result.md 写明测试套件与结果）',
+    literals: [],
+  },
+  contract_tests: {
+    desc: '契约测试（前后端/跨进程 API parity 对账，写明结论）',
+    literals: [],
+  },
+  real_daemon_backend_integration: {
+    desc: '真实 daemon↔backend 集成验证（非仅 mock 单测）。写「真实集成/端到端」的证据；',
+    literals: ['端到端', 'integration test', 'e2e test', 'daemon.*backend', '真实集成', 'runtime evidence', '运行时证据'],
+  },
+  runtime_log_evidence: {
+    desc: 'Runtime Evidence section + 指向真实日志/证据片段。',
+    literals: ['Runtime Evidence', '运行时证据', 'daemon log', '日志片段'],
+  },
+  real_startup_once: {
+    desc: '真实启动一次本变更触及的部署/启动入口（服务入口、CLI 主入口、守护进程等——须是本变更实际改动的那一类入口，不能拿无关进程的启动来凑数）。',
+    literals: ['启动.*一次', '实际.*启动', 'real startup', 'docker up', 'npm start', 'node server'],
+  },
+  terminal_state_assertion: {
+    desc: '终态断言（建议项，不阻断）：AgentRun running→completed/failed、session/lease end 状态同步。',
+    literals: ['terminal state', '终态', 'completed failed', 'session end', 'lease end'],
+  },
+}
+
+/** 风险分级的判定来源（命中关键词来源 = design.md / plan.md 内容，非改动文件本身） */
+export const RISK_LEVEL_CAUSES = {
+  'deployment-critical':
+    'design.md / plan.md 命中启动入口关键词（cli.ts / main.ts / server.(js|ts) / bootstrap / entrypoint）。' +
+    '注意：这是按 design/plan 里的措辞判定的，不一定代表你真改了启动入口；若属误判可在 design 中如实缩小范围，但不建议为绕门控而规避——危险链路该有真实启动证据。',
+  'integration-critical':
+    'design.md / plan.md 命中跨进程/状态机关键词（daemon / backend / session / lease / lifecycle / heartbeat 等）。',
+  'contract-required': 'design.md / plan.md 命中 API contract 关键词（api / client / contract / dto）。',
+}
+
 export function detectChangeRisk({ designContent = '', planContent = '', changedFiles = [] } = {}) {
   const triggers = []
   const combined = [designContent, planContent].join('\n')
@@ -308,6 +353,16 @@ export function checkIntegrationEvidence(verifyContent, requiredVerification) {
   const warnings = []
   const lower = verifyContent.toLowerCase()
 
+  // 字面证据正则从 VERIFICATION_NEEDS[k].literals 派生——与报错描述、prompt 事前契约严格同源,
+  // 杜绝历史上"描述说 A、正则查 B"的分叉(checkIntegrationEvidence 正则曾比 VERIFICATION_NEEDS
+  // 描述多匹配 集成测试/backend.*daemon/real.*integration 等)。literals 为空的 need
+  // (unit_tests/contract_tests)无字面校验,视为满足。
+  const hasEvidence = (k) => {
+    const n = VERIFICATION_NEEDS[k]
+    if (!n || !n.literals || n.literals.length === 0) return true
+    return new RegExp(n.literals.join('|'), 'i').test(lower)
+  }
+
   const needsIntegration = requiredVerification.includes('real_daemon_backend_integration')
   const needsLogEvidence = requiredVerification.includes('runtime_log_evidence')
   const needsTerminalState = requiredVerification.includes('terminal_state_assertion')
@@ -315,11 +370,7 @@ export function checkIntegrationEvidence(verifyContent, requiredVerification) {
 
   if (needsIntegration) {
     const hasMockOnly = /mock.*test.*passed|unit.*test.*passed/i.test(lower)
-    const hasIntegrationEvidence =
-      /集成测试|integration.*test|e2e.*test|端到端/i.test(lower) ||
-      /daemon.*backend|backend.*daemon|真实.*集成|real.*integration/i.test(lower) ||
-      /runtime.*evidence|运行时.*证据/i.test(lower)
-
+    const hasIntegrationEvidence = hasEvidence('real_daemon_backend_integration')
     if (!hasIntegrationEvidence && hasMockOnly) {
       errors.push('integration-critical 变更只提供了 mock 单测证据，缺少真实 daemon↔backend 集成验证')
     } else if (!hasIntegrationEvidence) {
@@ -328,25 +379,22 @@ export function checkIntegrationEvidence(verifyContent, requiredVerification) {
   }
 
   if (needsLogEvidence) {
-    const hasRuntimeSection = /runtime.*evidence|运行时.*证据|daemon.*log|日志.*片段/i.test(lower)
-    if (!hasRuntimeSection) {
+    if (!hasEvidence('runtime_log_evidence')) {
       errors.push('integration-critical 变更的 verify-result.md 缺少 Runtime Evidence section')
     }
   }
 
   if (needsTerminalState) {
-    const hasTerminalState = /terminal.*state|终态|running.*completed|completed.*failed|session.*end|lease.*end/i.test(lower)
-    if (!hasTerminalState) {
+    if (!hasEvidence('terminal_state_assertion')) {
       warnings.push('建议检查终态断言：AgentRun running→completed/failed、session end 状态同步')
     }
   }
 
   if (needsRealStartup) {
-    const hasStartupEvidence = /启动.*一次|real.*startup|实际.*启动|docker.*up|npm.*start|node.*server/i.test(lower)
-    if (!hasStartupEvidence) {
+    if (!hasEvidence('real_startup_once')) {
       errors.push('deployment-critical 变更需要真实启动验证证据')
     }
   }
 
   return { ok: errors.length === 0, errors, warnings }
-}
+}

package/src/check-primitives.js

@@ -0,0 +1,65 @@
+/**
+ * check-primitives.js — 共享的产物字面校验原语(纯函数)
+ *
+ * 从 workflow.js 的 checkOutput / _checkWorkflow 抽出,作为"何谓 contains_sections / min_lines /
+ * no_placeholder / no_empty_files"的**全仓单一语义源**。workflow 引擎与 stage-contract 引擎
+ * (stage-contract-engine.js)共用同一组谓词,杜绝"workflow 认 `## X` 子串、stage-contract 认别的"
+ * 这类判定分叉(本任务的"事前==事后"同源在原语层就成立)。
+ *
+ * 设计原则:纯文本判定,不碰 fs。调用方负责读文件 + CRLF 归一化后传入 content——
+ * 这样 Windows CRLF 差异在调用方收敛(plan-postcheck 已用 LF-normalizing reader),引擎拿到
+ * 什么判什么,不在原语层二次引入 readFileSync 差异(缺陷 windows-python-crlf-taskcard 的根因)。
+ */
+
+// no_placeholder 的默认占位词。与原 workflow.js checkOutput/_checkWorkflow 逐字一致——
+// 改动会破坏存量扫描文档的占位判定,属契约级常量。
+const DEFAULT_PLACEHOLDER_PATTERNS = [
+  '待补充', 'TODO', 'TBD', '未分析', '根据项目情况', '根据实际情况', '按需填写',
+]
+
+/** 内容非空(trim 后有字符)。用于 no_empty_files。 */
+export function contentNonEmpty(content) {
+  return typeof content === 'string' && content.trim().length > 0
+}
+
+/** 行数(split('\n'))。用于 min_lines 的 detail 文案与判定。 */
+export function lineCount(content) {
+  return typeof content === 'string' ? content.split('\n').length : 0
+}
+
+/** 行数 ≥ min。用于 min_lines 判定。 */
+export function meetsMinLines(content, min) {
+  return lineCount(content) >= min
+}
+
+/**
+ * 返回缺失的章节(sections 中未以 `## <section>` 子串出现的)。
+ * 用于 contains_sections——判定与原 workflow.js 逐字一致(`## ${s}` 前缀子串匹配)。
+ */
+export function missingSections(content, sections) {
+  if (typeof content !== 'string') return sections.slice()
+  return sections.filter(s => !content.includes(`## ${s}`))
+}
+
+/** 是否含全部章节(missingSections 为空的语法糖)。 */
+export function hasAllSections(content, sections) {
+  return missingSections(content, sections).length === 0
+}
+
+/**
+ * 返回命中的占位词(patterns 中匹配"独立成行"的)。
+ * 用于 no_placeholder——正则 `^\s*[-*]?\s*<p>\s*$`(m flag)与原 workflow.js 逐字一致。
+ * patterns 为空/未传时用 DEFAULT_PLACEHOLDER_PATTERNS(等价原 `check.patterns || [defaults]`)。
+ */
+export function placeholderLineMatches(content, patterns) {
+  if (typeof content !== 'string') return []
+  const pats = (patterns && patterns.length > 0) ? patterns : DEFAULT_PLACEHOLDER_PATTERNS
+  return pats.filter(p => new RegExp(`^\\s*[-*]?\\s*${p}\\s*$`, 'm').test(content))
+}
+
+/** 无占位词命中(placeholderLineMatches 为空的语法糖)。 */
+export function hasNoPlaceholderLine(content, patterns) {
+  return placeholderLineMatches(content, patterns).length === 0
+}
+
+export { DEFAULT_PLACEHOLDER_PATTERNS }

package/src/db.js

@@ -2,6 +2,11 @@ import initSqlJs from 'sql.js';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { basename, dirname, join } from 'path';
 
+// DB schema 版本（与 project.schema_version DEFAULT 对齐）。_createSchema 改动（加表/列/migration）时 bump，
+// 触发 .schema-version 戳失效 → 下次 init 重跑 _createSchema + _save（W4-H：高频读路径 gate/derive/status
+// 每次 new ProgressManager 都过 init，原无条件 _createSchema+_save 致每次整库 export+三段原子写）。
+const DB_SCHEMA_VERSION = 3;
+
 export class DB {
   constructor(dbPath) {
     this.dbPath = dbPath;
@@ -25,11 +30,21 @@ export class DB {
     this.db.run('PRAGMA foreign_keys = ON');
     this.db.run('PRAGMA synchronous = NORMAL');
 
-    // 5. 创建表结构
-    this._createSchema();
+    // 5. 创建表结构（仅当 schema 版本戳不匹配时——W4-H）：
+    //    schema 已最新则只 load 不写，省掉 _createSchema + _save 的整库 export + 三段原子写。
+    //    戳在但 db 缺表属"手动改 db"边角（SillySpec 不支持），_loadDatabase 的损坏检测兜底正常路径。
+    const versionPath = `${this.dbPath}.schema-version`;
+    let schemaCurrent = false;
+    try {
+      schemaCurrent = existsSync(versionPath)
+        && readFileSync(versionPath, 'utf8').trim() === String(DB_SCHEMA_VERSION);
+    } catch { /* 戳读取失败保守重跑 schema */ }
 
-    // 6. 保存到磁盘
-    this._save();
+    if (!schemaCurrent) {
+      this._createSchema();
+      this._save();
+      try { writeFileSync(versionPath, String(DB_SCHEMA_VERSION)); } catch { /* 戳写入失败不阻断，下次重跑 */ }
+    }
   }
 
   close() {
@@ -43,15 +58,20 @@ export class DB {
   transaction(fn) {
     if (!this.db) throw new Error('DB not initialized');
     this.db.run('BEGIN');
+    let result;
     try {
-      const result = fn(this.db);
+      result = fn(this.db);
       this.db.run('COMMIT');
-      this._save();
-      return result;
     } catch (err) {
-      this.db.run('ROLLBACK');
+      // fn 抛错或 COMMIT 失败：事务级回滚（此时事务确实活跃，ROLLBACK 有效）
+      try { this.db.run('ROLLBACK'); } catch { /* 事务可能已被 fn 内的错自动回滚 */ }
       throw err;
     }
+    // COMMIT 成功后才持久化。_save 失败时抛原生错（磁盘满/EPERM），不再被 catch 里
+    // 无效的 ROLLBACK 二级异常（"no transaction active"）掩盖——内存库已 commit，
+    // 下次 _save / close() 会落盘，调用方拿到的是准确的持久化错误而非被替换的误报。
+    this._save();
+    return result;
   }
 
   /** 获取底层 db 对象（供 progress.js 直接使用） */

package/src/hooks/worktree-guard.js

@@ -258,12 +258,19 @@ function queryDbFirstCell(cwd, sql) {
     "if(!fs.existsSync(dbPath))process.exit(0);" +
     "import(lib).then(async m=>{const SQL=await m.default();" +
     "const db=new SQL.Database(fs.readFileSync(dbPath));const r=db.exec(sql);" +
-    "if(r.length&&r[0].values.length)process.stdout.write(String(r[0].values[0][0]??''));db.close()}).catch(()=>{});"
+    "if(r.length&&r[0].values.length)process.stdout.write(String(r[0].values[0][0]??''));db.close()}).catch(e=>{process.stderr.write('hook db query failed: '+String(e&&e.message||e));process.exit(1)});"
   try {
     return execFileSync(process.execPath, ['-e', script], {
       encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
     }).trim() || null
-  } catch { return null }
+  } catch (e) {
+    // DB 查询失败（db 损坏 / sql.js resolve 失败 / 子进程超时）：降级返回 null，调用方
+    //（readCurrentStage 等）对 null 走 fail-closed。补 warn 让 doctor/agent 能看到根因，
+    // 而非完全静默（子进程把诊断写到了 stderr，execFileSync 抛错时挂在 e.stderr 上）。
+    const detail = (e && e.stderr ? String(e.stderr).trim() : '') || (e && e.message) || 'timeout/crash'
+    console.warn('⚠️ sillyspec.db 查询失败，hook 降级 fail-closed: ' + detail)
+    return null
+  }
 }
 
 export { queryDbFirstCell as _queryDbFirstCellForTest };