sillyspec 3.27.11 → 3.28.0

package/.worktrees/e58fcc4c/architecture-analysis.md

@@ -1,503 +0,0 @@
-# SillySpec 项目架构分析报告
-
-> 分析时间：2026-08-26（更新版）
-> 项目版本：3.27.6（从 package.json 确认）
-> 分析范围：全量代码库（worktree e58fcc4c）
-> 前版：2026-08-25 v3.27.5 分析基础上更新
-
----
-
-## 1. 项目定位与概述
-
-SillySpec 是一个**给 AI Agent 调用的 CLI 流程状态机**，让 AI 严格按步骤来执行文档驱动开发。它不是给人类直接使用的产品，而是 Agent（如 Claude Code、Cursor）的流程控制器——Agent 通过 CLI 告诉它"我在哪"，它告诉 Agent"下一步做什么"；Agent 执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。
-
-核心理念：**Spec-Driven Development（规范驱动开发）**——先有文档（brainstorm → design → plan），再写代码（execute），再验证（verify），最后归档（archive）。
-
----
-
-## 2. 整体架构设计
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        CLI Entry (bin/sillyspec.js)             │
-│                         → src/index.js (主路由)                  │
-└──────────────┬──────────────────────────────┬───────────────────┘
-               │                              │
-    ┌──────────▼──────────┐       ┌───────────▼──────────┐
-    │  阶段执行引擎         │       │  子命令路由             │
-    │  src/run/            │       │  progress / worktree  │
-    │  command→stage→      │       │  gate / derive /      │
-    │  prompt→complete     │       │  docs / knowledge /   │
-    └──────────┬───────────┘       │  workspace / dashboard │
-               │                   └───────────┬───────────┘
-    ┌──────────▼───────────┐       ┌───────────▼───────────┐
-    │  阶段定义层            │       │  状态管理层             │
-    │  src/stages/*.js     │       │  src/progress.js       │
-    │  (10 个阶段)          │       │  src/progress/*.js     │
-    └──────────┬───────────┘       │  (facade + 4 submod)   │
-               │                   └───────────┬───────────┘
-               │                               │
-    ┌──────────▼───────────────────────────────▼───────────┐
-    │                    数据层                               │
-    │  src/db.js (node:sqlite) → sillyspec.db              │
-    │  src/db-engine.js (引擎抽象)                           │
-    │  .sillyspec/.runtime/sillyspec.db (SQLite WAL)        │
-    └──────────────────────────────────────────────────────┘
-```
-
-### 2.1 架构分层（自顶向下）
-
-| 层级 | 职责 | 关键文件 |
-|------|------|---------|
-| **CLI 入口层** | 参数解析、路由分发、全局 flag 处理 | `bin/sillyspec.js`, `src/index.js` |
-| **命令分发层** | runCommand 主入口、auto 模式、stage 路由 | `src/run/command.js` |
-| **阶段执行层** | step prompt 渲染、complete 校验、wait/continue | `src/run/stage.js`, `src/run/prompt.js`, `src/run/complete.js` |
-| **阶段定义层** | 10 个阶段的 steps/prompt/校验器 | `src/stages/*.js` |
-| **协议校验层** | StageContract 状态机、gate/derive 机器接口 | `src/stage-contract.js`, `src/machine-interface.js` |
-| **状态管理层** | ProgressManager facade + 4 个子模块 | `src/progress.js`, `src/progress/*.js` |
-| **数据持久化层** | SQLite WAL 数据库、原子写、备份恢复 | `src/db.js`, `src/db-engine.js`, `src/fs-atomic.js` |
-| **辅助基础设施** | git 操作、平台同步、worktree 隔离、dashboard | `src/git-helper.js`, `src/sync.js`, `src/worktree*.js` |
-
----
-
-## 3. 技术栈选择
-
-### 3.1 运行时
-
-| 技术 | 版本要求 | 选型理由 |
-|------|---------|---------|
-| **Node.js** | ≥ 22.13.0 | 使用 `node:sqlite` 内置模块（22.5+ stable），无需 WASM/sql.js；原生 SQLite 性能 + 真 WAL |
-| **ES Modules** | `"type": "module"` | 全量 ESM，动态 import 实现懒加载优化（E22 启动性能） |
-
-### 3.2 数据库
-
-| 技术 | 选型理由 |
-|------|---------|
-| **node:sqlite (DatabaseSync)** | Node 22 内置原生 SQLite 绑定，同步 API 简化状态管理；真 WAL 支持并发读写；.bak 损坏自动回退 |
-| **WAL 模式** | `journal_mode=WAL` + `busy_timeout=5000` + `synchronous=NORMAL`，兼顾性能与安全 |
-| **Schema 版本管理** | `DB_SCHEMA_VERSION=5` + `.schema-version` 戳，避免每次启动重建表 |
-
-历史：v1/v2 使用 `progress.json` 文件，v3 全量迁移至 SQLite。
-
-### 3.3 外部依赖（7 个，极度精简）
-
-| 依赖 | 用途 | 选型理由 |
-|------|------|---------|
-| `@inquirer/prompts` | 交互式用户输入 | 标准 Node 交互 prompt 库 |
-| `chalk` | 终端彩色输出 | CLI 美化 |
-| `chokidar` | 文件系统监控 | dashboard 实时更新 |
-| `js-yaml` | YAML 解析/序列化 | local.yaml / 项目配置 / module-map |
-| `open` | 打开浏览器 | dashboard 自动打开 |
-| `ora` | 终端 spinner | 长操作进度提示 |
-| `ws` | WebSocket | dashboard 实时通信 |
-
-### 3.4 测试/构建
-
-| 技术 | 说明 |
-|------|------|
-| 自研测试运行器 | `test/run-tests.mjs`（无 jest/vitest 依赖，自研轻量 runner） |
-| 自研 lint | `test/check-syntax.mjs`（自研语法检查，非 eslint） |
-| 零构建步骤 | 纯 ESM 直接运行，无 tsc/webpack/rollup |
-
----
-
-## 4. 核心功能模块划分
-
-### 4.1 阶段系统（Stage System）— 核心流程引擎
-
-10 个阶段注册在 `src/stages/index.js`，分为两类：
-
-#### 主流程阶段（必须按序）
-| 阶段 | 文件 | 职责 |
-|------|------|------|
-| **brainstorm** | `brainstorm.js` | 需求澄清 → 产出 proposal/design/tasks |
-| **plan** | `plan.js` | 任务拆解 → 产出 plan.md + tasks.md（Wave 分组） |
-| **execute** | `execute.js` | 按 plan 执行代码 → 产出 per-task review.json |
-| **verify** | `verify.js` | 验证实现符合 design → 产出 verify-result.md |
-| **brainstorm-auto** | `brainstorm-auto.js` | brainstorm 自动模式变体 |
-
-#### 辅助阶段（可在无活跃变更时执行）
-| 阶段 | 文件 | 职责 |
-|------|------|------|
-| **quick** | `quick.js` | 快速任务（≤3 文件），跳过完整流程 |
-| **scan** | `scan.js` | 代码库扫描 → 产出架构/约定/结构文档 |
-| **explore** | `explore.js` | 自由讨论/调研，不修改文件 |
-| **archive** | `archive.js` | 归档已完成变更 → archive 目录 |
-| **status** | `status.js` | 查看当前进度 |
-| **doctor** | `doctor.js` | 进度库健康检查 + 修复 |
-
-### 4.2 状态管理子系统
-
-**ProgressManager**（`src/progress.js`）是 facade，委托 4 个子模块：
-
-| 子模块 | 文件 | 职责 |
-|--------|------|------|
-| `ChangeRegistry` | `progress/change-registry.js` | 变更注册/查询/归档（active/archived 状态管理） |
-| `StageMachine` | `progress/stage-machine.js` | 阶段状态机（pending→in_progress→completed 转换规则） |
-| `StepStore` | `progress/step-store.js` | 步骤级 CRUD（每个阶段的 steps 状态） |
-| `ConsistencyDoctor` | `progress/consistency-doctor.js` | 一致性检查与修复 |
-
-### 4.3 运行时子系统（src/run/）
-
-| 模块 | 文件 | 职责 |
-|------|------|------|
-| **command** | `command.js` | runCommand 主入口、flag 解析、stage 路由、auto 模式 |
-| **prompt** | `prompt.js` | prompt 渲染引擎（persona/铁律/占位符替换/完成后命令模板） |
-| **stage** | `stage.js` | 单阶段执行器（遍历 steps → outputStep） |
-| **complete** | `complete.js` | 步骤完成处理（--done/--skip/--wait/--continue） |
-| **complete-handlers** | `complete-handlers.js` | 各阶段特化的完成处理器 |
-| **gates** | `gates.js` | 门控引擎（Stage Review Gate / Task Review Gate / symbol-impact） |
-| **shared** | `shared.js` | 共享工具（resolveSpecDir / git / worktree drift 检测等） |
-| **quick-audit** | `quick-audit.js` | quick 完成审计（边界文件检测/归属） |
-| **scan-profile** | `scan-profile.js` | scan 规模判定（quick/standard/deep 三档） |
-| **concurrent-detect** | `concurrent-detect.js` | 并发变更检测 |
-| **multi-repo-context** | `multi-repo-context.js` | 跨仓上下文构造 |
-| **next** | `next.js` | 项目状态探测（下一步命令建议） |
-
-### 4.4 协议与门控子系统
-
-| 模块 | 文件 | 职责 |
-|------|------|------|
-| **StageContract** | `stage-contract.js` | 阶段合约（前置条件/产出校验/状态转换） |
-| **stage-contract-engine** | `stage-contract-engine.js` | 合约规则引擎 |
-| **stage-contract-spec** | `stage-contract-spec.js` | 合约规则定义 |
-| **MachineInterface** | `machine-interface.js` | 机器接口 v1（gate/derive JSON envelope） |
-| **task-review** | `task-review.js` | per-task review.json 生成/校验/adopt |
-| **stage-review** | `stage-review.js` | stage 级 review.json 注册/刷新 |
-
-### 4.5 Worktree 隔离子系统
-
-| 模块 | 文件 | 职责 |
-|------|------|------|
-| **WorktreeManager** | `worktree.js` | worktree 创建/清理/doctor |
-| **worktree-apply** | `worktree-apply.js` | 校验 + 应用变更到主工作区（含 merge fallback） |
-| **worktree-guard** | `hooks/worktree-guard.js` | pre-push hook 拦截未合并 worktree |
-
-### 4.6 平台集成（SillyHub）
-
-| 模块 | 文件 | 职责 |
-|------|------|------|
-| **sync** | `sync.js` | 进度库 ↔ 平台双向同步 |
-| **dispatch** | `dispatch/` | SillyHub MCP 派发（probe + strategy） |
-| **sillyhub-mcp** | `sillyhub-mcp/` | MCP client/config |
-| **platform-pointer** | (in progress.js) | 平台指针管理（fail-closed 设计） |
-
-### 4.7 辅助工具集
-
-| 模块 | 文件 | 职责 |
-|------|------|------|
-| **docs-check** | `docs-check.js` | 文档 file:line 引用校验 + 自动重锚 |
-| **docs-gate** | `docs-gate.js` | 文档质量门控（pre-push 第三道关） |
-| **knowledge** | `stages/knowledge.js` + `knowledge-match.js` | 知识库搜索/校验/提议 |
-| **commit-suggest** | `commit-suggest.js` | 智能提交建议（conventional commit） |
-| **module-impact** | `module-impact.js` | 模块影响矩阵骨架生成 |
-| **endpoint-extractor** | `endpoint-extractor.js` | 后端路由静态扫描（FastAPI/Express/Spring） |
-| **quicklog** | `quicklog.js` | QUICKLOG 管理 |
-| **workspace** | `workspace.js` | 多项目工作区管理 |
-| **dashboard** | `packages/dashboard/` | Web Dashboard（Vite + WebSocket 实时） |
-
----
-
-## 5. 代码组织结构
-
-```
-sillyspec/
-├── bin/sillyspec.js              # CLI 入口（2 行，import src/index.js）
-├── src/
-│   ├── index.js                  # 主路由（2854 行，CLI arg 解析 + 子命令分发）
-│   ├── run.js                    # barrel（重导出 run/* 子模块）
-│   ├── run/                      # 运行时子系统（12 个文件）
-│   │   ├── command.js            # runCommand 主入口
-│   │   ├── prompt.js             # prompt 渲染引擎
-│   │   ├── stage.js              # 阶段执行器
-│   │   ├── complete.js           # 步骤完成处理
-│   │   ├── complete-handlers.js  # 阶段特化完成器
-│   │   ├── gates.js              # 门控引擎
-│   │   ├── shared.js             # 共享工具（最大文件）
-│   │   ├── quick-audit.js        # quick 审计
-│   │   ├── scan-profile.js       # scan 规模判定
-│   │   ├── concurrent-detect.js  # 并发检测
-│   │   ├── multi-repo-context.js # 跨仓上下文
-│   │   └── next.js               # 状态探测
-│   ├── stages/                   # 阶段定义（10 个）
-│   │   ├── index.js              # 阶段注册表
-│   │   ├── brainstorm.js         # brainstorm 定义
-│   │   ├── plan.js               # plan 定义
-│   │   ├── execute.js            # execute 定义
-│   │   ├── verify.js             # verify 定义
-│   │   ├── quick.js              # quick 定义（最大阶段文件）
-│   │   ├── scan.js               # scan 定义
-│   │   ├── explore.js            # explore 定义
-│   │   ├── archive.js            # archive 定义
-│   │   ├── status.js             # status 定义
-│   │   ├── doctor.js             # doctor 定义
-│   │   ├── knowledge.js          # knowledge 命令
-│   │   ├── plan-postcheck.js     # plan 后置校验
-│   │   ├── brainstorm-auto.js    # 自动 brainstorm
-│   │   └── cmd-existence.js      # 命令存在性校验
-│   ├── progress.js               # ProgressManager facade
-│   ├── progress/                 # 进度子模块
-│   │   ├── change-registry.js    # 变更注册
-│   │   ├── stage-machine.js      # 阶段状态机
-│   │   ├── step-store.js         # 步骤存储
-│   │   ├── consistency-doctor.js # 一致性修复
-│   │   └── shared.js             # 共享常量/类型
-│   ├── db.js                     # SQLite 数据库管理
-│   ├── db-engine.js              # 数据库引擎抽象
-│   ├── stage-contract.js         # 阶段合约
-│   ├── stage-contract-engine.js  # 合约规则引擎
-│   ├── stage-contract-spec.js    # 合约规则定义
-│   ├── machine-interface.js      # 机器接口（gate/derive）
-│   ├── worktree.js               # worktree 管理
-│   ├── worktree-apply.js         # worktree 应用
-│   ├── sync.js                   # 平台同步
-│   ├── dispatch/                 # SillyHub 派发
-│   │   ├── probe.js
-│   │   ├── strategy.js
-│   │   └── backends/
-│   │       ├── local-agent.js
-│   │       └── sillyhub-mcp.js
-│   ├── sillyhub-mcp/             # MCP 集成
-│   ├── hooks/
-│   │   └── worktree-guard.js     # pre-push hook
-│   ├── fs-atomic.js              # 原子写工具
-│   ├── git-helper.js             # git 操作封装
-│   ├── init.js                   # init 命令
-│   ├── setup.js                  # setup 命令
-│   ├── quicklog.js               # QUICKLOG 管理
-│   ├── commit-suggest.js         # 提交建议
-│   ├── docs-check.js             # 文档引用校验
-│   ├── docs-gate.js              # 文档门控
-│   ├── docs-debt.js              # 文档债管理
-│   ├── knowledge-match.js        # 知识库匹配
-│   ├── module-impact.js          # 模块影响分析
-│   ├── module-resolve.js         # 模块解析
-│   ├── modules.js                # 模块管理
-│   ├── endpoint-extractor.js     # 端点提取
-│   ├── config-cat.js             # 配置查看
-│   ├── config-schema.js          # 配置 schema
-│   ├── local-detect.js           # 本地配置检测
-│   ├── local-register.js         # 本地注册
-│   ├── doctor-diagnostics.js     # 诊断工具
-│   ├── classify-change.js        # 变更分类
-│   ├── change-risk-profile.js    # 变更风险分析
-│   ├── change-list.js            # 变更文件列表
-│   ├── verify-postcheck.js       # verify 后置校验
-│   ├── scan-postcheck.js         # scan 后置校验
-│   ├── scan-diff.js              # scan 漂移检测
-│   ├── scan-staleness.js         # scan 过期检测
-│   ├── plan-adopt-waves.js       # plan Wave 重排
-│   ├── task-review.js            # task review 管理
-│   ├── stage-review.js           # stage review 管理
-│   ├── verify-probes.js          # verify 机械探针
-│   ├── machine-interface.js      # 机器接口
-│   └── ...
-├── packages/
-│   └── dashboard/                # Web Dashboard
-│       ├── server/               # Node.js 后端（Express + WebSocket）
-│       ├── src/                  # Vue.js 前端
-│       └── dist/                 # 构建产物
-├── test/                         # 测试（~250 个 .test.mjs 文件）
-├── docs/                         # 文档
-│   ├── prompt/                   # 阶段提示词原文
-│   └── sillyspec/                # 项目文档
-├── templates/                    # 模板文件
-├── eval/                         # 评估工具
-└── .claude/
-    └── skills/                   # Claude Code SKILL 定义
-```
-
----
-
-## 6. 关键设计模式与架构决策
-
-### 6.1 状态机模式（Stage Machine）
-
-核心设计：阶段转换由 `StageContract` 严格控制，不允许跳跃。
-
-```
-brainstorm → plan → execute → verify → archive
-                                      ↑
-quick (辅助，可随时) ─────────────────┘
-scan (辅助，独立) 
-explore (辅助，独立)
-```
-
-每个阶段有：
-- `allowedFrom`: 允许的前置阶段
-- `validators`: 校验器数组（产出文件存在性、内容完整性等）
-- `steps[]`: 步骤定义（每个 step 有 prompt + outputHint + optional 标记）
-
-### 6.2 门控模式（Gate Pattern）
-
-**Stage Review Gate**: 每个主流程阶段完成后，检查 stage 级 review.json
-**Task Review Gate**: execute 阶段每个 task 完成后，检查 per-task review.json
-**Docs Gate**: pre-push 时检查文档引用有效性
-
-所有 gate 遵循：**fail-closed**（无法判断时拒绝通过）+ **只读语义**（不修改状态）
-
-### 6.3 Machine Interface（机器接口）
-
-把人类可读的校验输出抽象为机器可消费的 JSON envelope：
-- `runGate(stage, change)` → 判断阶段能否标记完成
-- `runDerive(facet, change)` → 查询特定事实的真实状态
-- 退出码三段：0=通过 / 1=阻断 / 2=无法核验
-
-### 6.4 Worktree 隔离（execute 阶段）
-
-execute 阶段在独立 git worktree 中运行，避免并行变更冲突：
-- `worktree create` → 创建隔离工作区
-- `worktree apply` → 校验 + 合并回主工作区
-- `worktree cleanup` → 清理
-
-支持三种模式：`worktree`（标准 git worktree）/ `native-worktree`（原生）/ `in-place-fallback`（降级就地执行）
-
-### 6.5 平台指针（Platform Pointer）
-
-fail-closed 设计：平台声明接管时，指针缺失则拒绝回退到本地模式
-- `.sillyspec-platform.json` 平台指针
-- `*-managed` 接管声明文件
-- 成对存在，成对删除
-
-### 6.6 懒加载优化（E22）
-
-`src/index.js` 对轻路径（--version/help）不做重 import，progress.js 和 run/shared.js 链在 main() 早退后才动态加载，省 ~78ms 启动税。
-
-### 6.7 原子写 + 并发安全
-
-- `fs-atomic.js`: 写临时文件 → renameSync 覆盖（Windows EPERM 重试机制）
-- `db.js`: WAL 模式 + `busy_timeout=5000` + 应用层 `MAX_BUSY_RETRIES=3` 退避
-- 主仓 apply 互斥锁（`withMainRepoLock`）
-
----
-
-## 7. 数据存储结构
-
-```
-.sillyspec/
-├── .runtime/
-│   └── sillyspec.db              # SQLite 数据库（权威状态源）
-├── changes/
-│   └── <change-name>/
-│       ├── design.md             # 设计文档
-│       ├── plan.md               # 实现计划
-│       ├── tasks.md              # 任务注册表
-│       ├── verify-result.md      # 验证报告
-│       ├── symbol-impact.md      # 符号影响分析
-│       ├── module-impact.md      # 模块影响矩阵
-│       └── tasks/
-│           └── task-01.md        # per-task 卡片
-├── docs/
-│   └── <project>/
-│       ├── scan/                 # scan 产出文档
-│       │   ├── ARCHITECTURE.md
-│       │   ├── CONVENTIONS.md
-│       │   ├── STRUCTURE.md
-│       │   ├── INTEGRATIONS.md
-│       │   ├── TESTING.md
-│       │   ├── CONCERNS.md
-│       │   └── PROJECT.md
-│       └── modules/              # 模块文档
-│           ├── _module-map.yaml
-│           └── <module>.md
-├── knowledge/                    # 知识库
-├── projects/                     # 多项目工作区配置
-├── archive/                      # 已归档变更
-├── quicklog/                     # QUICKLOG
-├── local.yaml                    # 本地配置
-└── docs-check-baseline           # 文档检查基线
-```
-
----
-
-## 8. 测试架构
-
-- **310 个测试文件**（`.test.mjs`），自研测试运行器 `test/run-tests.mjs`，总计 ~53,600 行测试代码
-- **测试/源码比 ≈ 1.07:1**（~50K 源码 vs ~54K 测试），覆盖率极高
-- 覆盖面：CLI 端到端（子进程模式）、单元测试、集成测试
-- 测试模式：`seed-real-steps`（CLI 子进程 seed 真实步骤）+ 直接 import 测试
-- 特殊测试：flaky 测试隔离（`--spec-dir` 隔离防文件锁竞争）、跨仓测试、平台同步测试
-
----
-
-## 9. 关键配置文件
-
-| 文件 | 用途 |
-|------|------|
-| `package.json` | 项目元数据、依赖、脚本 |
-| `.sillyspec/local.yaml` | 本地配置（构建命令、测试命令、docs-check 路径等） |
-| `.sillyspec/.runtime/sillyspec.db` | 权威状态数据库 |
-| `.sillyspec-platform.json` | 平台指针 |
-| `.claude/skills/` | Claude Code SKILL 定义 |
-| `.husky/pre-push` | Git pre-push hook（worktree guard + docs gate） |
-
----
-
-## 10. 代码规模统计（2026-08-26 更新）
-
-| 区域 | 文件数 | 总行数 |
-|------|--------|--------|
-| `src/` 根模块 | 62 | ~29,400 |
-| `src/run/` | 12 | ~9,500 |
-| `src/stages/` | 15 | ~6,800 |
-| `src/progress/` | 5 | ~1,600 |
-| `src/hooks/` | 2 | ~1,000 |
-| `src/dispatch/` | 4 | ~1,100 |
-| `src/sillyhub-mcp/` | 2 | ~900 |
-| **源码总计** | **~102** | **~50,300** |
-| `test/` | 310 | ~53,600 |
-| `docs/` | ~25 | ~50,000+ |
-
-### Top 10 最大源码文件
-
-| 文件 | 行数 | 职责 |
-|------|------|------|
-| `src/index.js` | 2,854 | CLI 主入口/路由 |
-| `src/worktree.js` | 1,849 | worktree 管理 |
-| `src/verify-postcheck.js` | 1,718 | verify 后置校验 |
-| `src/worktree-apply.js` | 1,611 | worktree 变更应用 |
-| `src/task-review.js` | 1,498 | 任务审查 |
-| `src/sync.js` | 1,470 | 平台同步 |
-| `src/progress.js` | 1,304 | ProgressManager facade |
-| `src/doctor-diagnostics.js` | 1,099 | 诊断工具 |
-| `src/stage-contract.js` | 948 | 阶段合约 |
-| `src/quicklog.js` | 883 | quick 日志 |
-
-### Top 5 最大阶段定义
-
-| 文件 | 行数 | 阶段 |
-|------|------|------|
-| `plan-postcheck.js` | 1,398 | plan 后置校验 |
-| `execute.js` | 1,277 | execute 定义 |
-| `plan.js` | 655 | plan 定义 |
-| `brainstorm.js` | 624 | brainstorm 定义 |
-| `scan.js` | 608 | scan 定义 |
-
----
-
-## 11. 风险与观察
-
-1. **src/index.js 过大**：2854 行的主路由文件，承载了所有子命令的 flag 解析和分发逻辑。虽然已有 W6 重构将 run.js 抽为 barrel，但 index.js 本身仍是单体。
-
-2. **自研测试/ lint 工具**：未使用社区标准工具（jest/vitest/eslint），维护成本自担，但换来了零依赖的轻量启动。
-
-3. **平台集成复杂度**：SillyHub 集成（sync/dispatch/mcp/pointer）引入了大量 fail-closed 守卫和并发安全逻辑，是 bug 高发区（从 MEMORY.md 的大量 worktree/sync 相关经验可见）。
-
-4. **Windows 兼容性**：多个 MEMORY 条目记录了 Windows 特有问题（rename EPERM、CRLF、路径分隔符），代码中已有针对性处理但仍需持续关注。
-
-5. **测试覆盖广度**：310 个测试文件覆盖了极广的功能面，但部分测试有 flaky 问题（worktree/git 操作的时序敏感性）。Windows 环境下尤为突出（CRLF、文件锁、路径长度）。
-
-6. **MEMORY.md 经验库庞大**：~60+ 条踩坑记录，涵盖并发冲突、CRLF 污染、Windows rename EPERM、worktree drift、平台指针成对删除等。这既是项目成熟度的体现（大量实战经验沉淀），也是复杂度的信号——每个坑位都是潜在的回归风险点。
-
-7. **文档驱动开发的执行成本**：CLAUDE.md 中 20 条核心规则 + 多个同步检查清单（文件生命周期同步、提示词同步、.claude/skills 同步），每次改动 `src/stages/` 需同步 3-4 处文档。文档一致性债（`doc-consistency-debt.md` 25KB）说明执行同步的实际率不高。
-
-8. **平台集成仍在演进**：从 `MEMORY.md` 可见 `platform-pointer`、`platform-sync`、`sillyhub-mcp` 相关经验占 ~15 条，说明平台化是当前活跃开发方向，但 fail-closed 守卫和并发安全逻辑仍在持续加固中。
-
-9. **run/ 子模块间耦合度**：`command.js`（1641 行）直接 import 了 8 个同级/上级模块，`shared.js`（1562 行）被几乎所有 run/ 子模块依赖。shared.js 承载了过多职责（resolveSpecDir、git 操作、drift 检测、并发检测、platform managed 检查等），是潜在的循环依赖热点。
-
-10. **Claude Code Skills 生态**：21 个 SKILL.md 覆盖了所有阶段 + auto/commit/continue/export/resume/workspace 等组合模式，形成了完整的 AI Agent 操作手册。SKILL 作为 npm 包的一部分随 `sillyspec init` 复制到用户项目，是传播的关键载体。
-
----
-
-*报告产出路径：`architecture-analysis.md`（工作区根目录）*
-*最后更新：2026-08-26*`

package/.worktrees/e58fcc4c/bin/sillyspec.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import '../src/index.js';

package/.worktrees/e58fcc4c/eval/README.md

@@ -1,86 +0,0 @@
-# SillySpec A/B 评测
-
-客观量化回答一个问题：**同一个 agent，走 SillySpec 流程（B 臂）比裸跑（A 臂）到底好多少？**
-
-- 同任务、同模型、同判分脚本（每任务一个 `verify.mjs`，退出码 0 = 通过），唯一变量是「有没有 SillySpec」。
-- 产出：分臂通过率 + Wilson 95% 置信区间、Δ(B−A) 区间、flaky 剔除、token/费用/耗时、基线回归对比。
-- 所有结果落 SQLite（`eval/results/eval.db`），可审计、可复跑。
-
-## 快速开始
-
-```bash
-node eval/run.mjs --dry-run        # ① 零 token：假 agent 验证整条管道（先跑这个）
-node eval/run.mjs --preflight      # ② 零 token：检查 Node 版本与 agent CLI 可用
-node eval/run.mjs --pilot          # ③ 真跑：前 20 个任务 × 双臂（从这里开始烧 token）
-node eval/run.mjs --report         # 查看报告
-node eval/run.mjs --set-baseline   # 成绩满意后固化为回归基线（发版前对比）
-```
-
-npm 快捷方式：`npm run eval:dry`、`npm run eval:pilot`。
-
-## 认证与 apikey（重要）
-
-**不需要把 apikey 配置在本评测的任何脚本或配置文件里。**
-
-CLI 适配器只是以子进程方式调起你本机的 headless agent CLI（默认 `claude -p`，可换 zcode / codex 等），认证完全沿用该 CLI 自己的登录态或它读取的环境变量——你之前怎么用它，评测就怎么用。评测脚本不接管、不存储、不转发任何密钥，`eval.config.json` 可以安全提交。
-
-前置条件只有一条：目标 agent CLI 已安装、已登录、终端里能跑通。拿不准就先 `node eval/run.mjs --preflight`。
-
-未来若要接裸 API（如 GLM 的 OpenAI 兼容端点）跑自研 agent 循环，那才需要环境变量方式的 key（同样是环境变量，不进脚本）——届时新增一个 adapter 即可。
-
-## 命令一览
-
-| 命令 | 用途 | token 消耗 |
-|---|---|---|
-| `--dry-run[=mixed\|pass\|fail]` | 假 agent 跑管道（mixed 会确定性制造两臂差异） | 0 |
-| `--preflight` | Node 版本 + agent CLI 探活 | 0 |
-| `--pilot` | 前 20 任务双臂真跑 | 真实消耗 |
-| `--task <id>` / `--arm A\|B` / `--sample N` | 收窄范围 | 按范围 |
-| `--rerun-failed` | 只重跑上轮 fail/timeout/error | 定向，省钱 |
-| `--force` | 忽略缓存强制重跑 | 按范围 |
-| `--report [--dry-run]` | 报告（CI / Δ / flaky / 基线） | 0 |
-| `--set-baseline` | 固化当前成绩为回归基线 | 0 |
-
-## 省 token 机制（内建）
-
-1. **缓存**：同 `(config_hash, task, arm)` 已有 pass/fail 终态自动跳过；改了提示词/流程/任务内容会换 hash，只重跑受影响部分。
-2. **定向重跑**：`--rerun-failed` 不碰已通过的任务。
-3. **双重熔断**：单任务 agent 超时（`adapter.timeoutMs`）+ 判分超时（`verifyTimeoutMs`），死循环烧不穿。
-4. **dry-run / preflight 全零 token**，烧钱的大跑之前管道一定先验通。
-
-## 任务格式
-
-每个任务一个目录，四件套：
-
-```
-eval/tasks/001-slugify/
-├── task.json     # id / instruction（两臂收到同一份需求文本）
-├── verify.mjs    # 判分：以被测工作目录为 cwd 执行，退出码 0 = 通过
-├── files/        # 工作副本脚手架（复制后交给 agent；棕地任务在这里放待改代码）
-└── solution/     # 参考解（仅 dry-run 假 agent 使用，不参与指纹）
-```
-
-写任务的要点：instruction 必须无歧义（判分才有唯一正确解）；verify 只看行为不看出身。当前 3 个种子任务偏小（用于验管道），正式 pilot 前应扩充到 20+，并逐步引入更贴近 SillySpec 甜区的中等规模功能任务。后续如需对接 Terminal-Bench 2.0 等外部任务源，写一个「外部任务 → 本格式」的导入器即可，编排与报告层不用动。
-
-## 配置（eval.config.json）
-
-- `arms.A / arms.B`：两臂的 `setup`（agent 进场前执行的命令，B 臂默认 `npx sillyspec init`；dry-run 跳过）与 `promptTemplate`（`{instruction}` 占位）。
-- `adapter`：`command` 数组 + `stdin: "prompt"`（prompt 走 stdin，规避跨平台引号问题；也可在 command 里用 `{prompt}` 占位改为参数注入）；`{workdir}` / `{maxTurns}` 占位可用；`parseStdoutJson: true` 时尽力从 stdout JSON 提取 token/费用（提不到记 null，不瞎填）。
-- 换被测 agent：改 `adapter.tool` + `adapter.command`（如 zcode / codex 的 headless 形式），两臂 prompt 模板不用动。
-
-## 目录
-
-```
-eval/
-├── run.mjs            # 入口
-├── eval.config.json   # 配置（无密钥，可提交）
-├── lib/               # 编排/报告/适配器/DB
-├── tasks/             # 任务集
-└── results/           # 运行产物（eval.db / 工作副本 / 日志 / baseline.json）——已 gitignore
-```
-
-## 已知边界
-
-- 通过率只统计 pass/fail；timeout / error（agent 崩溃、臂 setup 失败）单列不计入分母，避免把管道故障算成 agent 失败。
-- 同任务同臂多次运行结果摇摆会被标记 flaky 并从通过率剔除——放量前建议每任务跑 2 次，flaky 高说明任务本身不稳定，先修任务。
-- 单臂 n < 30 时报告会提示区间仅供方向参考。

package/.worktrees/e58fcc4c/eval/eval.config.json

@@ -1,28 +0,0 @@
-{
-  "tasksDir": "./tasks",
-  "resultsDir": "./results",
-  "defaultSample": 20,
-  "verifyTimeoutMs": 120000,
-  "regressionThresholdPp": 5,
-  "arms": {
-    "A": {
-      "label": "裸agent",
-      "setup": [],
-      "promptTemplate": "你在当前目录工作，直接完成以下需求（不要提问，直接实现，确保代码可运行）：\n\n{instruction}"
-    },
-    "B": {
-      "label": "SillySpec",
-      "setup": ["npx sillyspec init --dir {workdir} --tool {tool}"],
-      "promptTemplate": "当前项目已安装 SillySpec 工作流。请按 SillySpec 流程完成以下需求（小任务走 quick 模式），完成后确保代码可运行：\n\n{instruction}"
-    }
-  },
-  "adapter": {
-    "type": "cli",
-    "tool": "claude",
-    "command": ["claude", "-p", "--output-format", "json", "--max-turns", "{maxTurns}"],
-    "stdin": "prompt",
-    "timeoutMs": 900000,
-    "maxTurns": 60,
-    "parseStdoutJson": true
-  }
-}