sillyspec 3.27.6 → 3.27.7

package/.worktrees/dafc71ad/.husky/pre-push

@@ -0,0 +1,20 @@
+#!/bin/sh
+echo "🔧 pre-push: running lint + test + docs gate..."
+npm run lint --silent 2>&1
+if [ $? -ne 0 ]; then
+  echo "❌ pre-push: lint failed, aborting push"
+  exit 1
+fi
+npm test --silent 2>&1
+if [ $? -ne 0 ]; then
+  echo "❌ pre-push: test failed, aborting push"
+  exit 1
+fi
+# docs gate ratchet（doc-consistency-debt 第七节）：docs check 失效数 ≤ 基线放行。
+# 基线 .sillyspec/docs-check-baseline 缺失/损坏时 fail-closed exit 2 拦截。
+node bin/sillyspec.js docs gate 2>&1
+if [ $? -ne 0 ]; then
+  echo "❌ pre-push: docs gate failed, aborting push"
+  exit 1
+fi
+echo "✅ pre-push: lint + test + docs gate passed"

package/.worktrees/dafc71ad/README.md

@@ -0,0 +1,203 @@
+<p align="center">
+  <img src="logo.jpg" width="96" />
+</p>
+
+<h1 align="center">SillySpec</h1>
+
+<p align="center">规范驱动开发工具包 · 流程状态机，让 AI 严格按步骤来</p>
+
+<p align="center">
+  融合 Superpowers + OpenSpec + GSD，从「你说要啥」到「代码能跑」的完整流程<br>
+  兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini
+</p>
+
+<p align="center">
+  📖 <a href="https://sillyspec.ppdmq.top/">在线文档</a> &nbsp;·&nbsp; 🐙 <a href="https://github.com/q512426816/sillyspec">GitHub</a>
+</p>
+
+---
+
+> 💡 **核心理念：Code is Cheap, Context is Expensive.**
+>
+> 文档是核心资产，代码是文档的产物。没有文档就没有代码——文档是 AI 的记忆，是团队协作的基础，是后续维护的唯一依据。
+
+## 它解决什么问题
+
+AI agent（Claude Code / Cursor 等）直接上手编码时，容易跳过需求澄清、方案设计、任务拆解这些关键步骤，产出偏离预期、且无法审计。
+
+SillySpec 把一个变更的完整生命周期固化为一组**强制阶段**——每个阶段都有明确的入口契约、产物文件名和门禁校验，AI 必须按状态机推进，不能跳步、不能偷工。进度、决策、产物全部持久化到 SQLite，可审计、可回溯、可断点恢复。
+
+## 快速开始
+
+需要 Node.js >= 22.13，一条命令完成初始化：
+
+```bash
+npx sillyspec init
+```
+
+首次运行会自动安装 CLI，并检测你正在使用的 AI 工具。之后 `/sillyspec:brainstorm`、`sillyspec progress show` 等命令即可直接使用。
+
+**指定 AI 工具：**
+
+| 工具 | `--tool` | 产物位置 |
+|---|---|---|
+| Claude Code（推荐） | `claude` | `.claude/skills/sillyspec-*/` |
+| Cursor | `cursor` | `.cursor/skills/sillyspec-*/` |
+| OpenAI Codex | `codex` | `AGENTS.md` |
+| OpenCode | `opencode` | `INSTRUCTIONS.md` |
+| OpenClaw | `openclaw` | `.openclaw/skills/sillyspec-*/` |
+| Gemini | `gemini` | `GEMINI.md` |
+
+```bash
+npx sillyspec init --tool claude      # 指定工具
+npx sillyspec init --dir /path/to/x   # 指定项目目录
+npx sillyspec init --interactive      # 完整引导
+```
+
+
+## 平台支持
+
+SillySpec 进度库使用 SQLite 持久化（基于 Node.js 内置的 `node:sqlite` 模块，纯 JS 无原生编译依赖）。
+
+- **Node.js 版本要求 >= 22.13.0**：`node:sqlite` 自 v22.13.0 起免 `--experimental-sqlite` flag 直接可用。支持 Linux x64、macOS x64 / arm64、Windows x64 等所有 Node.js 官方支持平台。
+- **零编译安装**：`node:sqlite` 是 Node.js 内置模块（官方预编译发行，非纯 JS 实现），不依赖 node-gyp / C++ 工具链或任何第三方原生绑定，npm install 即装即用，无平台编译失败风险。
+
+## 从哪里开始
+
+| 场景 | 命令 |
+|---|---|
+| 全自动，一句话到代码 | `/sillyspec:auto <需求描述>` |
+| 全新项目（空目录） | `/sillyspec:init` |
+| 已有代码的项目 | `/sillyspec:scan` |
+| 多项目工作区 | `/sillyspec:workspace` |
+| 随时自由思考 | `/sillyspec:explore "想法"` |
+
+## 完整工作流
+
+```
+绿地：init  → brainstorm → plan → execute → [verify] → archive
+棕地：scan  → brainstorm → plan → execute →  verify  → archive
+全自动：auto（自动推进全部阶段，支持用户确认门控）
+大模块：brainstorm（多图）→ 拆分 → MASTER.md → 逐 stage 全流程 → archive
+```
+
+**也可以跳过完整流程：**
+
+- 小改动：`/sillyspec:quick "修复 xxx"`
+- 不确定做什么：`/sillyspec:explore`
+- 中断恢复：`/sillyspec:resume`
+- 不知道下一步：`/sillyspec:continue`
+
+## 命令一览
+
+### 核心流程
+
+| 命令 | 用途 |
+|---|---|
+| `/sillyspec:init` | 绿地项目：深度提问 → 需求文档 → 路线图 |
+| `/sillyspec:scan` | 棕地项目：扫描代码库，生成 7 份架构文档 + 模块映射 |
+| `/sillyspec:brainstorm` | 需求探索 + 规范生成：产出 design.md + tasks.md |
+| `/sillyspec:plan` | 实现计划：文件路径 + 任务描述 + Wave 拓扑分组 |
+| `/sillyspec:execute` | TDD 执行：子代理并行 + worktree 隔离 |
+| `/sillyspec:verify` | 验证：对照规范 + 测试套件 + 代码审查 |
+| `/sillyspec:archive` | 归档：规范沉淀到 knowledge/ |
+| `/sillyspec:auto` | 全自动推进全部阶段 |
+
+### 辅助工具
+
+| 命令 | 用途 |
+|---|---|
+| `/sillyspec:status` · `/sillyspec:state` | 查看进度 / 当前工作状态 |
+| `/sillyspec:continue` | 自动判断并执行下一步 |
+| `/sillyspec:explore` | 自由思考：画图、讨论、调研、HTML 原型 |
+| `/sillyspec:quick` | 快速模式：跳过完整流程 |
+| `/sillyspec:resume` | 恢复工作（支持大模块阶段进度） |
+| `/sillyspec:doctor` | 项目自检与状态修复 |
+| `/sillyspec:commit` | 智能提交 |
+| `/sillyspec:workspace` | 多项目工作区管理 |
+| `/sillyspec:export` | 导出成功方案为可复用模板 |
+
+## CLI 命令
+
+```bash
+sillyspec run <stage>            执行阶段（auto/brainstorm/plan/execute/verify/archive/scan/quick/explore）
+sillyspec run <stage> --done     完成当前步骤并推进到下一步
+sillyspec run <stage> --status   查看阶段进度
+sillyspec progress show          显示当前项目状态
+sillyspec init                   初始化（零交互，自动检测工具）
+sillyspec setup                  安装推荐 MCP 工具（交互式）
+sillyspec setup --list           查看已安装 MCP 状态
+sillyspec doctor                 全量自检 + 修复进度
+```
+
+## 核心特性
+
+- **规范驱动** — 所有代码产出先有设计文档支撑，文档是 AI 的记忆
+- **阶段状态机** — 以 stage + step 粒度强制流转，sillyspec.db（SQLite）单一进度源记录状态
+- **TDD 强制** — execute 阶段先写测试再写实现
+- **子代理并行** — 同一 Wave 内任务并行执行，加快交付
+- **Worktree 隔离** — execute 在独立 git worktree 中工作，不污染主分支
+- **拓扑排序 Wave** — plan 阶段按蓝图依赖关系自动重排 Wave 分组
+- **进度持久化** — SQLite（node:sqlite）持久化，支持断点恢复
+- **模块文档** — 模块级知识库，AI 执行时按需加载相关上下文
+- **浏览器自动化** — 可选 MCP（Playwright / Chrome DevTools），供集成/E2E 冒烟验证
+- **平台同步** — 可选对接 SillyHub，文档同步 + 团队审批 + 本地 agent 会话日志路径主动上报（平台会话展示本地 agent 完整日志；支持 Claude Code / Codex / ZCode 自动探测，其他 CLI 用 `SILLYSPEC_AGENT_LOG` 显式指定）
+
+## 可靠性保障
+
+SillySpec 不只是 prompt，还有硬校验兜底：
+
+- **锚定确认** — 各阶段执行前必须逐个确认读过规范文件
+- **Hard Gate 自检** — 关键命令生成文件后强制自检格式，不通过则修正
+- **postcheck 识别偷懒** — 自动识别占位符、fallback、未分析等 AI 偷懒模式
+- **归档确认** — archive 操作前展示内容等待用户确认
+
+## 防幻觉机制
+
+| 环节 | 机制 |
+|---|---|
+| scan | 强制扫描代码库结构 / 约定 / 集成 / 测试 / 债务，生成 7 份文档 |
+| brainstorm | 必须读 ARCHITECTURE.md 数据模型，支持原型图分析 |
+| execute | 写代码前强制读现有源码，禁止编造方法调用 |
+| 全流程 | postcheck + 硬门兜底 |
+
+## MCP 增强
+
+通过 `sillyspec setup` 一键安装 MCP 工具，增强 AI 能力：
+
+- **Context7** — 查询最新库文档和 API 参考
+- **Chrome DevTools** — 浏览器自动化，支持 E2E 验证
+
+## 目录结构
+
+```
+sillyspec/
+├── bin/sillyspec.js          # CLI 入口（shebang）
+├── src/
+│   ├── index.js              # 命令分发
+│   ├── run.js + run/         # 阶段状态机引擎（barrel + 实现模块）
+│   ├── init.js / setup.js    # 初始化 + MCP 工具安装
+│   ├── progress.js / db.js   # SQLite 进度存储（facade + 实现）
+│   ├── sync.js               # SillyHub 平台同步
+│   ├── workflow.js           # 工作流编排 + postcheck
+│   ├── worktree*.js          # worktree 隔离执行
+│   ├── dispatch/             # 任务派发（本地 agent / SillyHub MCP）
+│   ├── sillyhub-mcp/         # SillyHub MCP 客户端
+│   ├── hooks/                # worktree 守卫等钩子
+│   └── stages/               # 各阶段定义（scan/brainstorm/plan/execute/verify/...）
+├── templates/workflows/      # 工作流定义（scan-docs / archive-impact）
+├── test/                     # 原生 node:test 测试套件
+├── packages/dashboard/       # 独立可视化面板子包
+├── SKILL.md                  # 技能描述
+└── README.md
+```
+
+## 致谢
+
+- [Superpowers](https://github.com/obra/superpowers) — 工程纪律
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — 需求管理
+- [GSD](https://github.com/gsd-build/get-shit-done) — 上下文工程
+
+## License
+
+MIT

package/.worktrees/dafc71ad/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sillyspec
+description: "规范驱动开发工具包。绿地用 /sillyspec:init，棕地用 /sillyspec:scan，全自动用 /sillyspec:auto。完整流程：scan → brainstorm → plan → execute → verify → archive。支持 TDD、子代理并行、worktree 隔离、E2E 验证。兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini。"
+---
+
+# SillySpec
+
+从"你说要啥"到"代码能跑"的规范驱动开发工具包。
+Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini 通用。
+
+## 快速开始
+
+| 场景 | 命令 |
+|---|---|
+| 全自动流程 | `/sillyspec:auto <需求描述>` |
+| 全新项目（空目录） | `/sillyspec:init` |
+| 已有代码的项目 | `/sillyspec:scan` |
+| 多项目工作区 | `/sillyspec:workspace` |
+| 自由思考 | `/sillyspec:explore` |
+
+## 完整工作流
+
+```
+绿地：init → brainstorm → plan → execute → verify → archive
+棕地：scan → brainstorm → plan → execute → verify → archive
+全自动：auto（自动推进全部阶段，支持用户确认门控）
+```
+
+## 核心命令
+
+| 命令 | 用途 |
+|---|---|
+| `/sillyspec:auto` | 全自动推进全部流程 |
+| `/sillyspec:init` | 绿地项目初始化 |
+| `/sillyspec:scan` | 棕地项目扫描（生成 7 份文档） |
+| `/sillyspec:brainstorm` | 需求探索 + 生成设计文档 |
+| `/sillyspec:plan` | 编写实现计划（Wave 分组 + 拓扑排序） |
+| `/sillyspec:execute` | TDD 执行 + 子代理并行 |
+| `/sillyspec:verify` | 验证（测试 + 代码审查 + E2E） |
+| `/sillyspec:archive` | 归档变更 |
+
+## 辅助命令
+
+| 命令 | 用途 |
+|---|---|
+| `/sillyspec:status` · `/sillyspec:state` | 查看项目进度和状态 |
+| `/sillyspec:continue` | 自动判断并执行下一步 |
+| `/sillyspec:explore` | 自由思考模式 |
+| `/sillyspec:quick` | 快速任务，跳过完整流程 |
+| `/sillyspec:resume` | 恢复工作 |
+| `/sillyspec:doctor` | 项目自检 |
+| `/sillyspec:commit` | 智能提交 |
+| `/sillyspec:knowledge` | 知识库检索 / 沉淀 |
+| `/sillyspec:export` | 导出成功方案为可复用模板 |
+| `/sillyspec:workspace` | 多项目工作区管理 |
+
+## CLI 命令
+
+```bash
+sillyspec run auto            全自动推进全部流程
+sillyspec run scan            执行代码扫描阶段
+sillyspec run brainstorm      执行需求探索阶段
+sillyspec run plan            执行实现计划阶段
+sillyspec run execute         执行开发阶段（子代理并行 + worktree 隔离）
+sillyspec run verify          执行验证阶段
+sillyspec run archive         执行归档阶段
+sillyspec run quick           快速任务
+sillyspec run explore         自由探索
+sillyspec progress show       显示当前项目状态
+sillyspec setup               安装推荐 MCP 工具
+sillyspec init                初始化（零交互，自动检测工具）
+```
+
+## 核心特性
+
+- **规范驱动** — 所有代码产出先有设计文档支撑，文档是 AI 的记忆
+- **TDD 强制** — execute 阶段强制先写测试再写实现
+- **子代理并行** — 同一 Wave 内任务并行执行，加快交付
+- **Worktree 隔离** — execute 在独立 worktree 中工作，不污染主分支
+- **拓扑排序 Wave** — plan 阶段根据蓝图依赖关系自动重排 Wave 分组
+- **E2E 验证** — 内置 E2E 测试流程，支持 Playwright / 浏览器 MCP
+- **模块文档** — 支持模块级知识库，AI 执行时按需加载相关模块上下文
+- **进度管理** — SQLite 持久化进度，断点恢复
+- **MCP 增强** — 一键安装 Context7、Chrome DevTools、PinchTab
+
+## MCP 工具
+
+```bash
+sillyspec setup              安装全部推荐 MCP
+sillyspec setup --list       查看已安装 MCP 状态
+```

package/.worktrees/dafc71ad/analysis.md

@@ -0,0 +1,366 @@
+# SillySpec 项目架构分析报告
+
+> 分析时间：2026-08-26  
+> 分析范围：SillySpec v3.27.6 工作区全量代码
+
+---
+
+## 1. 项目概述
+
+| 维度 | 描述 |
+|------|------|
+| **类型** | CLI 工具 + 流程状态机 |
+| **技术栈** | Node.js (ESM, ≥22.13)、SQLite (node:sqlite 内置)、npm |
+| **用途** | 规范驱动开发工具包——让 AI Agent 严格按步骤执行变更流程 |
+| **核心理念** | "Code is Cheap, Context is Expensive." 文档是核心资产，代码是文档的产物 |
+| **兼容工具** | Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini |
+| **发布形态** | npm 包（`npx sillyspec init`），全局 CLI + 项目本地 `.sillyspec/` 进度库 |
+
+**定位**：SillySpec 不是给人直接使用的产品，也不是处理业务逻辑的工具——它是给 AI Agent 调用的 CLI 流程控制器。Agent 通过 CLI 告诉它"我在哪"，它告诉 Agent"下一步做什么"；Agent 执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。
+
+---
+
+## 2. 目录结构与模块划分
+
+```
+sillyspec/
+├── bin/sillyspec.js           # CLI 入口（2行，import src/index.js）
+├── src/                        # 核心源码
+│   ├── index.js                # CLI 主入口（163KB，命令解析 + 分发 + init/setup）
+│   ├── progress.js             # ProgressManager facade（60KB，进度恢复管理）
+│   ├── progress/               # progress 子模块（W6 重构拆分）
+│   │   ├── change-registry.js  # 变更注册表
+│   │   ├── consistency-doctor.js # 一致性诊断
+│   │   ├── shared.js           # 共享常量/类型
+│   │   ├── stage-machine.js    # 阶段状态机
+│   │   └── step-store.js       # 步骤存储
+│   ├── run.js                  # barrel re-export（W6 Step8 后退化）
+│   ├── run/                    # run 子模块（W6 重构拆分）
+│   │   ├── command.js          # 命令分发层（runCommand 主入口）
+│   │   ├── stage.js            # 阶段执行主干（runStage）
+│   │   ├── complete.js         # 步骤完成/skip/wait/continue
+│   │   ├── complete-handlers.js # 阶段完成处理器
+│   │   ├── gates.js            # 阶段完成校验 gate 级联
+│   │   ├── prompt.js           # prompt 渲染 + 占位符替换
+│   │   ├── shared.js           # run 层共享工具函数
+│   │   ├── quick-audit.js      # quick 模式审计
+│   │   ├── scan-profile.js     # scan profile 裁剪
+│   │   ├── concurrent-detect.js # 并发变更检测
+│   │   ├── multi-repo-context.js # 多仓上下文
+│   │   └── next.js             # 状态探测 + 下一步建议
+│   ├── stages/                 # 阶段定义（每个阶段一个文件）
+│   │   ├── index.js            # 阶段注册表
+│   │   ├── brainstorm.js       # 需求澄清/方案设计
+│   │   ├── brainstorm-auto.js  # 自动 brainstorm
+│   │   ├── plan.js             # 实现计划拆解
+│   │   ├── plan-postcheck.js   # plan 产物后检
+│   │   ├── execute.js          # 代码实现
+│   │   ├── verify.js           # 验证
+│   │   ├── archive.js          # 归档
+│   │   ├── quick.js            # 快速变更（≤3文件）
+│   │   ├── scan.js             # 项目扫描
+│   │   ├── explore.js          # 自由探索
+│   │   ├── status.js           # 状态查看
+│   │   ├── doctor.js           # 状态修复
+│   │   └── knowledge.js        # 知识库管理
+│   ├── db.js                   # SQLite 数据库层（DB 类）
+│   ├── db-engine.js            # 数据库引擎抽象（node:sqlite / fallback）
+│   ├── stage-contract.js       # 阶段协议（转换规则 + 校验器）
+│   ├── stage-contract-engine.js # 规则引擎
+│   ├── stage-contract-spec.js  # 规则规范定义
+│   ├── stage-review.js         # 阶段审查
+│   ├── task-review.js          # 任务审查
+│   ├── quicklog.js             # quick 变更日志
+│   ├── sync.js                 # 平台同步（77KB，最大单文件）
+│   ├── worktree.js             # git worktree 管理（98KB）
+│   ├── worktree-apply.js       # worktree 变更应用（93KB）
+│   ├── worktree-deps.js        # worktree 依赖管理
+│   ├── workflow.js             # workflow 引擎
+│   ├── init.js                 # 项目初始化
+│   ├── setup.js                # MCP 工具安装
+│   ├── config-schema.js        # 配置 schema
+│   ├── config-cat.js           # 配置读取
+│   ├── contract-matrix.js      # 合约矩阵
+│   ├── change-list.js          # 变更列表
+│   ├── change-risk-profile.js  # 变更风险画像
+│   ├── classify-change.js      # 变更分类
+│   ├── commit-suggest.js       # 智能提交建议
+│   ├── modules.js              # 模块管理
+│   ├── module-resolve.js       # 模块解析
+│   ├── module-impact.js        # 模块影响分析
+│   ├── docs-check.js           # 文档一致性检查
+│   ├── docs-debt.js            # 文档债务追踪
+│   ├── docs-gate.js            # 文档门控
+│   ├── verify-postcheck.js     # verify 后检（85KB）
+│   ├── verify-probes.js        # verify 机械探针
+│   ├── doctor-diagnostics.js   # doctor 诊断
+│   ├── scan-diff.js            # scan 漂移检测
+│   ├── scan-postcheck.js       # scan 后检
+│   ├── scan-staleness.js       # scan 过时检测
+│   ├── agent-session-log.js    # agent 会话日志
+│   ├── machine-interface.js    # 机器接口
+│   ├── foreign-declared.js     # 外部声明
+│   ├── knowledge-match.js      # 知识匹配
+│   ├── decision-distill.js     # 决策蒸馏
+│   ├── endpoint-extractor.js   # 端点提取
+│   ├── hooks/                  # git hooks
+│   │   ├── worktree-guard.js   # worktree 守卫 hook
+│   │   ├── claude-pre-tool-use.cjs # Claude 工具使用前 hook
+│   │   └── backends/           # hook 后端实现
+│   ├── dispatch/               # SillyHub 派发
+│   │   ├── probe.js            # 能力探测
+│   │   ├── strategy.js         # 策略生成
+│   │   └── backends/           # 派发后端
+│   ├── sillyhub-mcp/           # SillyHub MCP 客户端
+│   │   ├── client.js           # MCP 客户端
+│   │   └── config.js           # MCP 配置
+│   ├── fs-atomic.js            # 原子文件写入
+│   ├── git-helper.js           # git 辅助函数
+│   ├── constants.js            # 全局常量/枚举
+│   ├── datetime.js             # 时间工具
+│   ├── version.js              # 版本读取
+│   ├── local-detect.js         # 本地配置检测
+│   ├── local-register.js       # 本地注册
+│   ├── migrate.js              # 数据迁移
+│   ├── taskcard.js             # 任务卡片
+│   ├── taskcard-placeholders.js # 任务卡片占位符
+│   ├── plan-adopt-waves.js     # plan wave 合并
+│   ├── spec-dir-typo.js        # spec-dir 拼写建议
+│   ├── spec-sync.js            # spec 同步
+│   ├── check-primitives.js     # 检查原语
+│   ├── quick-recommend.js      # quick 推荐
+│   └── review-tier.js          # 审查层级
+├── test/                       # 测试（200+ 文件，.mjs）
+│   ├── run-tests.mjs           # 测试运行器
+│   ├── check-syntax.mjs        # lint 检查
+│   └── *.test.mjs              # 各模块测试
+├── docs/                       # 文档
+│   ├── prompt/                 # 阶段提示词镜像
+│   ├── sillyspec/              # SillySpec 相关文档
+│   └── *.md                    # 各类设计/协议文档
+├── templates/                  # 初始化模板
+│   ├── claude-instruction.md   # Claude 指令模板
+│   ├── prompts/                # 提示词模板
+│   └── workflows/              # workflow 模板
+├── eval/                       # 评估框架
+├── packages/                   # 子包
+│   └── dashboard/              # 仪表盘
+├── .claude/                    # Claude Code 配置
+│   └── skills/                 # SillySpec 技能定义
+├── .husky/                     # git hooks
+├── .sillyspec/                 # 本项目自身的 SillySpec 进度库
+├── package.json                # 项目配置
+└── CLAUDE.md                   # Claude Code 指引
+```
+
+---
+
+## 3. 核心功能模块说明
+
+### 3.1 阶段状态机（Stage State Machine）
+
+SillySpec 的核心是一个**强制阶段状态机**，将变更生命周期固化为一组不可跳过的阶段：
+
+```
+绿地：init → brainstorm → plan → execute → [verify] → archive
+棕地：scan → brainstorm → plan → execute → verify → archive
+快速：quick（≤3 文件的简化流程）
+```
+
+**阶段注册表**（`src/stages/index.js`）定义了所有阶段：
+- **主流阶段**（需按顺序）：brainstorm → plan → execute → verify
+- **辅助阶段**（可独立执行）：scan, quick, explore, archive, status, doctor
+
+**阶段协议**（`src/stage-contract.js`）强制执行：
+- 允许的前置阶段（不能跳步）
+- 必须的产出文件（每个阶段必须生成特定文件）
+- 校验器（completeStep 后必须过 validator）
+- 后续阶段（不能乱序）
+
+### 3.2 进度管理（Progress Management）
+
+**ProgressManager**（`src/progress.js` + `src/progress/`）是进度恢复的核心：
+- 使用 **SQLite**（`node:sqlite` 内置模块）持久化所有状态
+- 数据库位置：`.sillyspec/.runtime/sillyspec.db`
+- 支持多变更并行（每个变更有独立的 stage/step 状态）
+- 子模块拆分（W6 重构）：
+  - `change-registry.js`：变更注册表
+  - `stage-machine.js`：阶段状态机逻辑
+  - `step-store.js`：步骤存储
+  - `consistency-doctor.js`：一致性诊断
+
+### 3.3 Run 引擎（Run Engine）
+
+**Run 引擎**（`src/run/`）是 CLI 命令执行的核心：
+- `command.js`：命令分发层（runCommand 主入口）
+- `stage.js`：阶段执行主干（runStage）
+- `complete.js`：步骤完成/skip/wait/continue
+- `gates.js`：阶段完成校验 gate 级联
+- `prompt.js`：prompt 渲染 + 占位符替换
+- `shared.js`：run 层共享工具函数
+
+### 3.4 Worktree 管理
+
+**Worktree 管理**（`src/worktree.js` + `src/worktree-apply.js` + `src/worktree-deps.js`）：
+- 为 execute 阶段创建隔离的 git worktree
+- 支持变更应用（apply）到主工作区
+- 依赖管理（node_modules junction/provision）
+- 并发安全（多 agent 同时操作）
+
+### 3.5 平台同步（Platform Sync）
+
+**平台同步**（`src/sync.js`，77KB）：
+- 与 SillyHub 平台通信
+- 进度同步（push/pull）
+- 冲突检测与解决
+- 平台指针管理（pointer）
+
+### 3.6 文档检查（Docs Check）
+
+**文档检查**（`src/docs-check.js` + `src/docs-debt.js` + `src/docs-gate.js`）：
+- 校验文档与代码的一致性
+- 追踪文档债务
+- 门控机制（文档不通过不允许推进）
+
+### 3.7 Workflow 引擎
+
+**Workflow 引擎**（`src/workflow.js`）：
+- 加载 `.sillyspec/workflows/*.yaml` 定义
+- 运行 post_check 验证产物
+- 按角色定位失败 + 生成重试 prompt
+
+### 3.8 Quick 模式
+
+**Quick 模式**（`src/stages/quick.js` + `src/run/quick-audit.js`）：
+- 针对 ≤3 文件的小变更的简化流程
+- 跳过 brainstorm/plan，直接 execute → verify
+- 审计机制（边界保护、文件声明）
+
+---
+
+## 4. 代码组织方式与设计模式
+
+### 4.1 模块组织
+
+- **ESM 模块**（`"type": "module"`）：全程使用 ES Module
+- **barrel re-export**：`run.js` 作为 barrel 保留外部 import 契约
+- **子模块拆分**（W6 重构）：`progress.js` → `progress/`、`run.js` → `run/`
+- **动态 import**：避免循环依赖 + 懒加载优化启动性能
+
+### 4.2 设计模式
+
+1. **状态机模式**：阶段转换由 `stage-contract.js` 严格控制
+2. **门控模式**（Gate）：`gates.js` 实现阶段完成校验级联
+3. **Facade 模式**：`progress.js` 作为 facade 转发到子模块
+4. **Barrel 模式**：`run.js` + `stages/index.js` 作为统一导出
+5. **Registry 模式**：`stageRegistry` 注册所有阶段定义
+6. **Fail-Closed 模式**：平台指针/声明缺失时拒绝回退（防状态分裂）
+7. **原子写入**：`fs-atomic.js` 实现跨平台原子文件写入
+8. **工厂模式**：`DB` 类根据环境选择 node:sqlite 或 fallback
+
+### 4.3 关键设计决策
+
+- **SQLite 作为唯一状态源**：进度、决策、产物全部持久化到 SQLite
+- **node:sqlite 内置模块**：零编译依赖，跨平台一致
+- **Worktree 隔离**：execute 阶段在独立 worktree 中操作，避免污染主工作区
+- **CLI 驱动**：所有逻辑通过 CLI 命令暴露，Agent 通过 CLI 交互
+- **文档驱动**：文档是核心资产，代码是文档的产物
+
+---
+
+## 5. 依赖关系与配置
+
+### 5.1 运行时依赖（6个，极简）
+
+| 依赖 | 用途 |
+|------|------|
+| `@inquirer/prompts` | 交互式 prompt（init/setup） |
+| `chalk` | 终端着色 |
+| `chokidar` | 文件监控 |
+| `js-yaml` | YAML 解析（workflow/config） |
+| `open` | 打开浏览器 |
+| `ora` | 终端 spinner |
+| `ws` | WebSocket（SillyHub 通信） |
+
+### 5.2 开发依赖
+
+- 无（`package.json` 中无 `devDependencies`）
+- 测试使用 Node.js 内置 test runner
+- lint 使用自定义 `test/check-syntax.mjs`
+
+### 5.3 Node.js 要求
+
+- **≥ 22.13.0**：`node:sqlite` 自 v22.13.0 起免 flag 直接可用
+- 支持 Linux x64、macOS x64/arm64、Windows x64
+
+### 5.4 配置文件
+
+| 文件 | 用途 |
+|------|------|
+| `package.json` | 项目配置、脚本、依赖 |
+| `.npmignore` | npm 发布排除 |
+| `.gitignore` | git 忽略 |
+| `.gitattributes` | git 属性（CRLF 处理） |
+| `.sillyspec/` | 本项目自身的 SillySpec 进度库 |
+| `.claude/` | Claude Code 配置 + skills |
+| `.husky/` | git hooks（pre-push） |
+
+---
+
+## 6. 总结与关键发现
+
+### 6.1 架构特点
+
+1. **极简依赖**：仅 7 个运行时依赖，核心能力靠 Node.js 内置模块（node:sqlite, child_process, fs, path）
+2. **自举（Dogfood）**：SillySpec 使用自身管理开发流程（`.sillyspec/` 进度库）
+3. **Agent-Native**：专为 AI Agent 设计，CLI 是唯一交互界面
+4. **文档驱动**：强制文档先行，代码是文档的产物
+5. **状态机强制**：阶段转换由合约严格控制，Agent 不能跳步
+
+### 6.2 代码规模
+
+| 指标 | 数值 |
+|------|------|
+| `src/` 文件数 | ~70+ |
+| `src/` 总大小 | ~1.5MB |
+| `test/` 文件数 | ~200+ |
+| 最大单文件 | `sync.js` (77KB), `worktree.js` (98KB), `verify-postcheck.js` (85KB) |
+| 测试覆盖 | 全量（每个模块都有对应测试） |
+
+### 6.3 关键模块依赖关系
+
+```
+index.js (CLI 入口)
+  → run/command.js (命令分发)
+    → run/stage.js (阶段执行)
+      → stages/*.js (阶段定义)
+      → stage-contract.js (阶段协议)
+      → progress.js (进度管理)
+        → progress/*.js (子模块)
+          → db.js (SQLite)
+            → db-engine.js (引擎抽象)
+    → run/complete.js (步骤完成)
+      → run/gates.js (校验门控)
+    → run/prompt.js (prompt 渲染)
+  → init.js (初始化)
+  → setup.js (MCP 安装)
+```
+
+### 6.4 值得关注的设计
+
+1. **worktree 隔离**：execute 阶段在独立 worktree 中操作，支持多 agent 并发
+2. **平台指针 fail-closed**：防止状态分裂（本地/平台双写）
+3. **阶段合约**：强制执行阶段转换规则，防止 Agent 跳步
+4. **quick 模式**：为小变更提供简化路径，平衡规范与效率
+5. **平台同步**：支持 SillyHub 集成，实现多项目协作
+
+### 6.5 潜在改进点
+
+1. **大文件拆分**：`sync.js` (77KB)、`worktree.js` (98KB)、`verify-postcheck.js` (85KB) 等文件较大，可考虑进一步拆分
+2. **循环依赖**：部分模块使用动态 import 避免循环，可考虑重构消除
+3. **测试隔离**：测试使用 `.sillyspec/` 目录，需确保测试间隔离
+4. **跨平台兼容**：Windows 路径/CRLF 处理是持续挑战
+
+---
+
+*分析完成。本报告基于 SillySpec v3.27.6 工作区全量代码静态分析。*