sillyspec 3.25.1 → 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.1",
+  "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/index.js

@@ -16,6 +16,8 @@ import { detectLocalYaml } from './local-detect.js';
 
 // ── CLI 入口 ──
 
+// did-you-mean 从 ./run/shared.js 复用（命令级 + flag 级 typo 建议）。
+import { didYouMean, assertSafeChangeName } from './run/shared.js'
 function printUsage() {
   console.log(`
 SillySpec CLI — 规范驱动开发工具包
@@ -73,11 +75,20 @@ SillySpec CLI — 规范驱动开发工具包
     doctor [--fix] [--stale-hours N]    健康检查 + 修复
 
   sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
+  sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
 
-  sillyspec workflow check <name> [--project <p>] [--change <c>] [--json]
+  sillyspec workflow check <name> [--project <p>] [--change <c>] [--json] [--save]
+                                      全局 workflow 校验（--save 归档到 .sillyspec/.runtime/workflow-runs/）
   sillyspec workflow list
   sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
   sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
+
+  sillyspec doctor [子命令]            进度库健康检查 + 修复（顶层命令，非 worktree doctor）
+    （无子命令）                       跑诊断，列出问题
+    --align-execute-progress [--change <名>] [--confirm]   基于 plan.md 对齐 execute 派生戳（默认 dry-run）
+    --cleanup-remnant [--confirm]      删除 0 字节空占位 db（默认 dry-run，仅 --confirm 落盘）
+    --dump-db --path <db 路径>         dump 指定 db 内容到文件（取证用）
+    --json                             结构化诊断 + 落盘 .sillyspec/.runtime/doctor-diagnosis.json
   sillyspec modules <rebuild | status | migrate>
   sillyspec change-rename <旧变更名> <新变更名>
   sillyspec knowledge <search --query "..." --limit N
@@ -175,6 +186,13 @@ async function main() {
     }
   }
 
+  // F3：--interactive（全局 flag，被上面吞进 interactive 变量）与 --non-interactive（透传到 filteredArgs）
+  // 语义相反，同时给是矛盾。在此层检测（command.js 看不到 --interactive）。
+  if (interactive && filteredArgs.includes('--non-interactive')) {
+    console.error('❌ --non-interactive 与 --interactive 互斥（一个禁用交互、一个强制交互），请只保留一个。');
+    process.exit(2);
+  }
+
   const command = filteredArgs[0];
   // 支持 sillyspec init /path/to/project 语法：如果第二个参数看起来像路径，当作 targetDir
   if (command === 'init' && filteredArgs[1] && !filteredArgs[1].startsWith('-')) {
@@ -233,9 +251,19 @@ async function main() {
         case 'show':
           pm.show(progDir, progChangeName);
           break;
-        case 'check':
-          await pm.checkConsistency(progDir, progChangeName);
+        case 'check': {
+          const result = await pm.checkConsistency(progDir, progChangeName);
+          // checkConsistency 只返回 {ok, issues, warnings}，不打印——必须在此输出，
+          // 否则 agent 跑只读健康检查得到一片寂静，无法分辨「正常」还是「已损坏」。
+          if (!result || result.ok) {
+            console.log(`✅ 状态一致性检查通过${progChangeName ? `（变更 ${progChangeName}）` : '（所有变更）'}`);
+          } else {
+            console.error(`❌ 状态一致性检查发现问题（${result.issues?.length || 0} 项）：`);
+            for (const issue of (result.issues || [])) console.error(`   - ${issue}`);
+            console.error(`   修复：sillyspec progress repair${progChangeName ? ` --change ${progChangeName}` : ''}（先 dry-run 看可修项，加 --apply 执行）`);
+          }
           break;
+        }
         case 'repair': {
           const repairApply = filteredArgs.includes('--apply');
           await pm.repairConsistency(progDir, { apply: repairApply, changeName: progChangeName });
@@ -610,6 +638,9 @@ SillySpec worktree — git worktree 隔离管理
             console.error('❌ 用法: sillyspec worktree create <change-name> [--base <branch>]');
             process.exit(1);
           }
+          // F6 路径穿越消毒：worktree 名用于分支名 + worktree 目录，含 ../ 会逃出 .sillyspec/worktrees/。
+          try { assertSafeChangeName(wtName, 'worktree 变更名'); }
+          catch (e) { console.error(`❌ ${e.message}`); process.exit(2); }
           const baseIdx = args.indexOf('--base');
           const base = baseIdx >= 0 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
           try {
@@ -662,7 +693,14 @@ SillySpec worktree — git worktree 隔离管理
           } else if (result.merged) {
             console.log(`✅ 已通过 git merge 应用变更（baseline 漂移降级，引入合并提交）${result.mergeSummary ? '：' + result.mergeSummary : ''}`);
           } else {
-            console.log(`✅ 已应用 ${result.changedFiles.length} 个文件变更`);
+            console.log(`✅ 已应用 ${result.changedFiles.length} 个文件变更：`);
+            for (const f of result.changedFiles) {
+              console.log(`   ${f}`);
+            }
+            // filterDeliverableFiles 一刀切排除 .sillyspec/ + meta.json：
+            // 模块文档/变更文档等不会 auto-apply 到主工作区。须告知 agent，
+            // 否则它期望这些文件落地却找不到（memory: worktree-apply-excludes-module-docs）。
+            console.log(`   ℹ️  注：.sillyspec/ 下的文件（模块文档/变更文档等）按规则不自动 apply，如需请手动从 worktree 分支或 dangling commit 取（git show sillyspec/${wtName}:<path>）。`);
           }
           if (result.warnings && result.warnings.length > 0) {
             for (const w of result.warnings) {
@@ -708,7 +746,9 @@ SillySpec worktree — git worktree 隔离管理
             if (applyResult.errors.length > 0) {
               console.error('❌ apply 失败:', applyResult.errors.join('; '));
             } else {
-              console.log(`✅ 已自动应用 ${applyResult.changedFiles.length} 个文件变更`);
+              console.log(`✅ 已自动应用 ${applyResult.changedFiles.length} 个文件变更：`);
+              for (const f of applyResult.changedFiles) console.log(`   ${f}`);
+              console.log(`   ℹ️  注：.sillyspec/ 下的文件按规则不自动 apply，如需请手动从分支取（git show sillyspec/${wtName}:<path>）。`);
             }
           } else {
             console.log('Action: blocked');
@@ -970,6 +1010,14 @@ SillySpec platform — SillyHub 平台同步
         console.error('❌ 用法: sillyspec change-rename <旧变更名> <新变更名>');
         process.exit(1);
       }
+      // F6 路径穿越消毒：renameChange 会 mv changes/<old> → changes/<new>，名含 ../ 会逃出 changes/。
+      try {
+        assertSafeChangeName(oldName, '旧变更名');
+        assertSafeChangeName(newName, '新变更名');
+      } catch (e) {
+        console.error(`❌ ${e.message}`);
+        process.exit(2);
+      }
       const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
       await pm.renameChange(dir, oldName, newName);
       break;
@@ -1100,7 +1148,11 @@ SillySpec workflow — 工作流管理
         }
         process.exit(result.status === 'pass' ? 0 : 1);
       } else {
+        const wfSubs = ['check', 'list'];
+        const sug = didYouMean(wfSub, wfSubs);
         console.error(`❌ 未知子命令: workflow ${wfSub}`);
+        if (sug) console.error(`   你是想输入「workflow ${sug}」吗？`);
+        console.error(`   可用子命令：${wfSubs.join(' | ')}（运行 sillyspec workflow 查看用法）`);
         process.exit(1);
       }
       break;
@@ -1128,7 +1180,11 @@ SillySpec modules — 模块文档管理
         const { migrateModuleDocs } = await import('./modules.js');
         await migrateModuleDocs(dir);
       } else {
+        const modSubs = ['rebuild', 'status', 'migrate'];
+        const sug = didYouMean(modulesSub, modSubs);
         console.error(`❌ 未知子命令: modules ${modulesSub}`);
+        if (sug) console.error(`   你是想输入「modules ${sug}」吗？`);
+        console.error(`   可用子命令：${modSubs.join(' | ')}（运行 sillyspec modules 查看用法）`);
         process.exit(1);
       }
       break;
@@ -1180,10 +1236,83 @@ SillySpec modules — 模块文档管理
       console.log(`   路径: ${localYamlPath}`);
       break;
     }
-    default:
+    case 'runtime': {
+      // D2：.runtime/ 产物索引。CLI 往 .runtime/ 写各种证据/状态文件（db、doctor-diagnosis、
+      // workflow-runs、gate-status、user-inputs…），却没有命令让 agent 一眼看到「我手上有哪些产物」。
+      // 多会话/压缩后尤其痛：上轮写的证据文件，下轮不知去哪找。纯只读枚举，不写盘。
+      const runtimeSubCmd = filteredArgs[1];
+      if (runtimeSubCmd && runtimeSubCmd !== 'list') {
+        const sug = didYouMean(runtimeSubCmd, ['list']);
+        console.error(`❌ 未知子命令: runtime ${runtimeSubCmd}`);
+        if (sug) console.error(`   你是想输入「runtime ${sug}」吗？`);
+        console.error('用法: sillyspec runtime list   枚举 .sillyspec/.runtime/ 产物（只读）');
+        process.exit(2);
+      }
+      const specRoot = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const runtimeDir = join(specRoot, '.runtime');
+      if (!existsSync(runtimeDir)) {
+        if (json) { console.log(JSON.stringify({ runtimeDir, exists: false, artifacts: [] }, null, 2)); break; }
+        console.log(`📭 无 .runtime/ 目录（${runtimeDir}）——尚未产生任何运行时产物。`);
+        break;
+      }
+      // 已知产物 → 用途说明。agent 据此判断每份产物能否作为证据/该读哪个。
+      const KNOWN = {
+        'sillyspec.db': '进度库 SQLite（stages/steps/changes 表）',
+        'sillyspec.db.bak': '进度库备份（写前快照）',
+        'sillyspec.db.schema-version': '进度库 schema 版本标记',
+        'doctor-diagnosis.json': 'doctor --json 结构化诊断快照',
+        'doctor-dumps': 'doctor --dump-db 取证输出目录',
+        'workflow-runs': 'workflow check --save 归档目录',
+        'gate-status.json': '门控结果缓存',
+        'scan-guard.json': 'scan 覆盖保护记录',
+        'quick-sessions': 'quick 会话记录目录',
+        'quick-guard.json': 'quick baseline 守卫（旧位置）',
+        'worktrees': 'worktree meta（hooks 侧）',
+        'user-inputs.md': '步骤输出/输入历史追加日志',
+        'current-quick-run-id': '当前 quick sessionId 指针（--done 无 --change 时 fallback）',
+        'scan-runs': '平台模式 scan/workflow 取证目录',
+        'artifacts': '派生产物目录（init 预建）',
+        'contract-artifacts': 'execute endpoint 契约产物（verify 阶段读取）',
+        'history': '历史记录目录（init 预建）',
+        'logs': '日志目录（init 预建）',
+        'templates': '工作流模板目录（init 预建）',
+      };
+      let entries;
+      try {
+        entries = readdirSync(runtimeDir, { withFileTypes: true });
+      } catch (e) {
+        console.error(`❌ 读取 .runtime/ 失败: ${e.message}`);
+        process.exit(1);
+      }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      if (json) {
+        console.log(JSON.stringify({
+          runtimeDir, exists: true,
+          artifacts: entries.map(e => ({ name: e.name, type: e.isDirectory() ? 'dir' : 'file', desc: KNOWN[e.name] || null })),
+        }, null, 2));
+        break;
+      }
+      console.log(`📂 .runtime/ 产物（${runtimeDir}）`);
+      if (entries.length === 0) { console.log('   （空目录）'); break; }
+      for (const e of entries) {
+        const kind = e.isDirectory() ? '📁' : '📄';
+        const desc = KNOWN[e.name] ? `  — ${KNOWN[e.name]}` : '';
+        console.log(`   ${kind} ${e.name}${desc}`);
+      }
+      const unknown = entries.filter(e => !KNOWN[e.name]);
+      if (unknown.length > 0) {
+        console.log(`\n   （${unknown.length} 项未登记：${unknown.map(e => e.name).join(', ')}）`);
+      }
+      break;
+    }
+    default: {
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'local', 'workflow', 'gate', 'derive', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
+      if (suggestion) console.error(`   你是想输入「${suggestion}」吗？`);
       printUsage();
       process.exit(1);
+    }
   }
 }