@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/design/h4-index-dedup-spec-20260518-1230.md

@@ -0,0 +1,109 @@
+# H4: DB 索引/列去重 Spec
+
+## 目标
+消除 `schema.sql` 与 `base.ts::runMigrations` 之间的索引/列重复定义，让 schema.sql 成为新库权威源，runMigrations 只承担"存量库补齐"的职责，并保持 idempotent。
+
+## 涉及文件
+- `src/core/storage/schema.sql`（权威 schema，新库初始化）
+- `src/core/storage/base.ts`（migration 入口，存量库补齐）
+
+## 重复清单
+
+| 名称 | schema.sql | base.ts | 类型 | 备注 |
+|------|------------|---------|------|------|
+| `first_prompt` | L55 | L99 | column | schema 已含，migration 仍 ALTER |
+| `skill_confidence` | L139 | L101 | column | 同上 |
+| `skill_source` | L140 | L102 | column | 同上 |
+| `workflow` | L178 | L104 | column | 同上 |
+| `phase` | L179 | L105 | column | 同上 |
+| `feature_slug` | L180 | L106 | column | 同上 |
+| `artifact_path` | L181 | L107 | column | 同上 |
+| `idx_sessions_start_time` | L66 | L119 | index | 双写 |
+| `idx_events_session_ts` | L198 | L127 | index | 双写 |
+| `idx_routing_events_session_ts` | L199 | L128 | index | 双写 |
+| `idx_skill_invocations_session_ts` | L200 | L129 | index | 双写 |
+| `idx_routing_events_obeyed_ts` | L205 | L138 | index | 双写 |
+| `idx_events_session_hook` | L211 | L139 | index | 双写 |
+| `idx_injections_session_handler` | L214 | L140 | index | 双写 |
+| `idx_routing_events_type_ts` | L217 | L141 | index | 双写（H1 新增）|
+| `idx_skill_invocations_workflow` | 缺 | L111 | index | **仅 migration**，应补到 schema |
+| `idx_skill_invocations_feature` | 缺 | L112 | index | 同上 |
+
+## 设计方案
+
+### 决策：方案 B（保留 idempotent 双写 + 显式 has 判断）
+
+**理由**：
+- 简单删 base.ts 的 `CREATE INDEX IF NOT EXISTS` 会导致存量库（旧版未跑过 H1 migration 的用户）永远缺索引；migration 必须保留补齐能力。
+- 不能依赖"新装用户走 schema.sql、老用户走 migration"——同一份 base.ts 两端都跑。
+- 索引层面 `CREATE INDEX IF NOT EXISTS` 本身已 idempotent，"双写"代价仅是一次 PRAGMA 查表，可接受。
+- 列层面 ALTER TABLE 无 IF NOT EXISTS，必须靠 `hasColumn`（已存在）守护。
+
+### 选定方案的详细做法
+
+1. **schema.sql** 补两条缺失的索引：
+   - `idx_skill_invocations_workflow ON skill_invocations(workflow, phase)`
+   - `idx_skill_invocations_feature ON skill_invocations(feature_slug)`
+   这样新库一次成型，migration 块只是"防御性补齐"。
+
+2. **base.ts::runMigrations** 全部改造为 has 判断守护：
+   - 列：维持 `addColumnIfMissing`（已有 hasColumn）。
+   - 索引：新增 `hasIndex(name)` 工具；每个 migration 索引创建前先判断 `if (!this.hasIndex(name)) exec(...)`，跳过则记一行 debug 日志。
+   - 目的不是性能（CREATE INDEX IF NOT EXISTS 已便宜），而是让"哪些索引由 migration 补齐"显式可读、便于日后裁剪。
+
+3. **删除 inline fallback**（base.ts L57-72）—— 如果 schema.sql 缺失，应直接抛错而不是用残缺 schema 启动；保留只会埋坑。可在 spec 里建议但放在 H4 之外。**本次 H4 不动它**，仅注释 TODO。
+
+### 新增工具函数（base.ts）
+
+```ts
+protected hasIndex(name: string): boolean {
+  try {
+    const row = this.db
+      .prepare(`SELECT name FROM sqlite_master WHERE type='index' AND name = ?`)
+      .get(name);
+    return !!row;
+  } catch { return false; }
+}
+```
+
+注：`pragma_index_list(table)` 需要知道表名，而 `sqlite_master` 直接按索引名查更简单。
+
+## 测试策略
+
+新增 `tests/unit/storage/migration-idempotent.test.ts`：
+
+1. **baseline（旧库补齐）**：
+   - 建临时 db，先 exec 一份"H1 之前的旧 schema"（手写删掉 `idx_routing_events_type_ts` 等）+ 缺 `first_prompt` 列。
+   - 用 `new SQLiteStorage(path)` 启动，断言所有重复清单中的索引/列都已存在（`sqlite_master` + `PRAGMA table_info`）。
+
+2. **新库无害**：
+   - 临时 db 走完整 `schema.sql` 初始化。
+   - 再实例化一次 SQLiteStorage，断言 migration 不抛错、不重复创建（spy `db.exec` 调用次数或检查 logger.warn 无输出）。
+
+3. **idempotent（多次启动）**：
+   - 同一 db 连续 `new SQLiteStorage()` 3 次。
+   - 断言索引数量、列数量两次之间相等；断言 logger 无 error/warn。
+
+4. **现有测试回归**：跑 `npx vitest run src/tests/storage*.test.ts` 与 `tests/unit/storage/`。
+
+## 实施顺序
+
+1. schema.sql 补 `idx_skill_invocations_workflow` / `idx_skill_invocations_feature`
+2. base.ts 加 `hasIndex`
+3. base.ts::runMigrations 所有 `CREATE INDEX IF NOT EXISTS` 用 `if (!this.hasIndex(...))` 守护
+4. 新增 `tests/unit/storage/migration-idempotent.test.ts`
+5. 跑 `npx vitest run tests/unit/storage` + `npx tsc --noEmit`
+6. 跑全量 `npm test`
+
+## 风险与回滚
+
+- **风险**：存量数据库（线上用户）必须能补齐 → baseline 测试是硬门槛，CI 必跑。
+- **风险**：`hasIndex` 名字查询不区分表（同名索引理论上不会跨表，SQLite 索引名全局唯一）—— 实际安全。
+- **回滚**：所有改动局限在 schema.sql + base.ts + 1 个新测试，`git revert` 单 commit 即可。
+- **不动 inline fallback**：H4 范围之外，避免一次改太多。
+
+## 命名遵循
+
+- `hasIndex` / `hasColumn`：has 前缀 → 符合 CLAUDE.md "布尔值用 is/has/should 前缀"。
+- 测试文件名 `migration-idempotent.test.ts`：kebab-case + `.test.ts` → 符合命名规范。
+- 工具函数 `hasIndex` 与已有 `hasColumn` 并列，对称命名。

package/docs/design/h6-services-migration-spec-20260518-1355.md

@@ -0,0 +1,82 @@
+# H6: daemon/services analytics 类迁移 Spec
+
+## 目标
+将 3 个纯查询/聚合类从 `src/daemon/services/` 迁出，纠正位置错配，使依赖图反映真实调用方向（仅 web 层使用）。
+
+## 调研结果
+
+### 调用链
+| 类 | 文件 | daemon 调用 | web 调用 | cli 调用 |
+|---|---|---|---|---|
+| DriftDetector | `src/daemon/services/drift-detector.ts` | 0 | `web/routes/drift.ts:3,21` | 0 |
+| WeeklyReportGenerator | `src/daemon/services/weekly-report.ts`（注意：非 `weekly-report-generator.ts`） | 0 | `web/routes/reports.ts:10,20` | 0 |
+| AntiPatternDetector | `src/daemon/services/anti-pattern-detector.ts` | 0 | `web/routes/insights.ts:4,7,25` | 0 |
+
+`src/daemon/{index,handlers,pipeline}` 全无引用。同目录的 `task-segmenter.ts` 是真 daemon 服务（`daemon/index.ts:28,105` + `handlers/stop.ts:14,27`），**留在原地**。
+
+### 依赖关系
+3 个文件 imports 仅有：
+- `core/storage/sqlite` (SQLiteStorage 类型)
+- `core/storage/sessions` (SessionSummary 类型，仅 anti-pattern)
+- `core/types` (ForgeEvent，仅 anti-pattern)
+- `node:crypto`（标准库）
+
+**零 daemon 内部依赖** → 无反向依赖风险。注意 `weekly-report.ts:20` 构造时还接收 `skillRegistry`（来自 `web/routes/reports.ts` 的 ctx），但类型来源属 core 层，安全。
+
+### 现有测试
+- 单元测试：**无**（3 个文件 + 3 个调用方 routes 均无 `.test.ts`）
+- 集成测试覆盖路由：**无**（`tests/` 下无 drift/report/insight/anti-pattern 测试）
+- 现有 web 路由测试：sessions/stats/skill-stats/events/auth/tasks/rules（均不覆盖本次迁移路径）
+
+## 目标目录决策
+
+**推荐：`src/web/analytics/`**
+
+理由：
+1. 实际调用方 100% 是 `web/routes/`，符合"用在哪放在哪"
+2. 当前无 cli/daemon 消费，提升到 core 是过度设计；未来若 cli 需要再上提成本低
+3. 与同层模块 `web/routes/`、`web/static/` 平行，依赖方向天然向下（web → core）
+
+## 改造范围
+
+| 操作 | 来源 → 目标 / 修改点 |
+|---|---|
+| git mv | `src/daemon/services/drift-detector.ts` → `src/web/analytics/drift-detector.ts` |
+| git mv | `src/daemon/services/weekly-report.ts` → `src/web/analytics/weekly-report.ts` |
+| git mv | `src/daemon/services/anti-pattern-detector.ts` → `src/web/analytics/anti-pattern-detector.ts` |
+| 改 import | `src/web/routes/drift.ts:3` → `'../analytics/drift-detector.js'` |
+| 改 import | `src/web/routes/reports.ts:10` → `'../analytics/weekly-report.js'` |
+| 改 import | `src/web/routes/insights.ts:7` → `'../analytics/anti-pattern-detector.js'` |
+| 清理注释 | `weekly-report.ts:294`、`anti-pattern-detector.ts:80` 引用"daemon/services 既定做法"的文字 |
+| barrel | **不建** `index.ts`（仅 3 个文件、3 个调用方，barrel 收益低） |
+| 保留 | `src/daemon/services/task-segmenter.ts` 原地不动 |
+
+## 测试策略
+
+- **safety-net（必做）**：迁移前补一个最小集成测试 baseline
+  - `tests/integration/web-analytics.integration.test.ts`：分别 GET `/api/drift`、`/api/reports/weekly`、`/api/insights`，断言 200 + 关键字段存在（不校验业务正确性，只校验 wiring 没断）
+- **回归**：`npx tsc --noEmit` + `npm test` 全量
+- **手测**：`./scripts/dev-daemon.sh restart` 后 `curl` 3 个 endpoint
+
+## 风险与回滚
+
+- 风险 1：dist/ 残留旧路径 → `npm run build` 前清理 `dist/daemon/services/{drift,weekly,anti}*`
+- 风险 2：第三方/外部脚本 import 旧路径 → 已 grep 确认仅 src/ 内部使用，无外部入口
+- 风险 3：`weekly-report.ts:294` 注释提到 anti-pattern-detector 协作历史，迁移后描述失真（仅文档影响）
+- 回滚：`git mv` 保留 history，单 commit 完成；失败 `git revert <hash>` 即可
+
+## 实施顺序
+
+1. 补 safety-net 集成测试（独立 commit，验证当前 main 通过）
+2. `mkdir -p src/web/analytics`
+3. `git mv` 3 个文件（一个 commit）
+4. 改 3 处 import + 清理 2 处误导注释（同 commit 或下一 commit）
+5. `npx tsc --noEmit` → `npm test` → daemon 重启 + curl 三 endpoint
+6. 提交 PR / push
+
+## 命名遵循
+
+- 文件名 kebab-case ✓（保持原名）
+- 类名 PascalCase ✓（无改动）
+- 目录 `web/analytics/` 全小写 ✓
+- 注意：源文件叫 `weekly-report.ts` 而非任务描述里写的 `weekly-report-generator.ts`，spec 以实际文件名为准

package/docs/design/hook-failure-queue-spec-20260516-1530.md

@@ -0,0 +1,204 @@
+# Hook 失败缓冲队列 + Daemon 启动重放 — Spec
+
+**日期**: 2026-05-16
+**状态**: Draft（待用户 review）
+
+---
+
+## 一、目标 + 成功标准
+
+**核心目标**：实现「至少一次」事件交付，消除 daemon 重启窗口期的静默丢失。
+
+| 成功标准 | 验收方式 |
+|---|---|
+| daemon 停机 30 秒内，5 条 UserPromptSubmit 全部最终入库 | 集成测试：停 daemon → 发 5 事件 → 启动 daemon → 查 DB |
+| 队列目录不超过 500 个文件 / 7 天 | 单元测试：写 600 个文件后调 prune，剩余 ≤500 |
+| hook 总执行时间不超过 1 秒 | 脚本计时测试（`time` 命令） |
+| 重放不产生重复入库 | 集成测试：手动写重复 event_id → 验证 DB 只有一条 |
+
+**非目标**：已丢失的历史事件（本次故障之前）、跨机器同步、daemon 运行期间的网络抖动（nc 有超时保护，不属于失败场景）。
+
+---
+
+## 二、设计决策
+
+### 决策 1：队列存储格式 — per-event 独立文件
+
+**选择**：`~/.claude-forge/queue/<timestamp>-<uuid>.json` 每个事件一个文件。
+
+**理由**：
+1. 完全避免并发写冲突：5 个 hook bash 进程写不同文件名，无锁需求
+2. 原子性：`bash` 的 `echo > file` 对新建文件是原子操作（内核 create + write）
+3. 删除操作幂等：`rm -f file` 不会影响其他事件；追加模式下误删一行会破坏整个 jsonl
+
+**否决方案**：append-only jsonl —— bash 并发 `>>` 在 chunk > PIPE_BUF(512B) 时会产生交错写，且部分行损坏会影响整个文件解析。
+
+### 决策 2：队列目录位置 — `~/.claude-forge/queue/`
+
+**理由**：
+1. 与 `daemon.sock`、`data.db`、`daemon.token` 同目录，路径计算逻辑统一
+2. `expandPath` 工具已有 `~/.claude-forge/` 展开支持
+3. daemon 启动时已有 `mkdirSync` 保证父目录存在，子目录只需 `mkdir -p queue`
+
+### 决策 3：触发投递条件 — daemon 启动时一次性扫描
+
+**理由**：
+1. 失败窗口期（daemon 重启）是短暂的，启动一次扫描即可覆盖
+2. 不需要额外的 watcher 进程/定时器，降低复杂度
+3. 重放完成后队列目录为空，无持续扫描开销
+
+### 决策 4：去重策略 — `event_id` 数据库唯一索引（已存在）+ catch ignore
+
+**理由**：
+1. `events.event_id TEXT PRIMARY KEY` 已存在，无需额外工作
+2. daemon 侧只需在 `writeEvent` 的 catch 中识别 `UNIQUE constraint failed` 并静默跳过，其他错误仍 re-throw
+3. 避免内存 LRU 在 daemon 重启时丢失已处理记录的风险
+
+### 决策 5：容量保护 — 500 文件上限 + 7 天 TTL，过期写入 dead-letter
+
+- 写入前检查：队列文件数 ≥ 500，**丢弃最旧的超额文件**
+- TTL：daemon 启动重放时，跳过 > 7 天的文件，移入 `~/.claude-forge/queue/dead/`
+- dead-letter 目录不自动清理，供人工审查
+
+### 决策 6：hook 脚本写队列方式 — fork 子进程同步写
+
+**方式**：在 `nc` 失败后，用 `( ... ) &` 后台子进程写文件，主进程立即 `exit 0`。
+
+**理由**：
+1. 主进程不阻塞，子进程独立 fork 不受父退出影响
+2. bash 原生支持，比 nohup/setsid 简单
+3. 单文件写入 syscall < 5ms，子进程开销可忽略
+
+---
+
+## 三、改动文件清单
+
+| 路径 | 改动类型 | 概述 |
+|---|---|---|
+| `src/hooks/user-prompt-submit.sh` | 修改 | nc 失败后 fork 子进程写队列文件 |
+| `src/hooks/pre-tool-use.sh` | 修改 | 同上，补充 socket 存在检测 |
+| `src/hooks/post-tool-use.sh` | 修改 | 同上 |
+| `src/hooks/notification.sh` | 修改 | 同上（低优先级，可选） |
+| `src/hooks/stop.sh` | **不改** | Stop 事件无重放意义 |
+| `src/core/queue/index.ts` | 新建 | 队列读写、prune、重放逻辑 |
+| `src/daemon/index.ts` | 修改 | Step 8 之后插入 `replayQueue()` 调用 |
+| `src/core/storage/events.ts` | 修改 | `writeEvent` catch 中识别并忽略 UNIQUE 冲突 |
+| `src/tests/queue.test.ts` | 新建 | 单元测试 |
+| `tests/integration/queue-replay.integration.test.ts` | 新建 | 集成测试 |
+
+---
+
+## 四、模块设计
+
+### `src/core/queue/index.ts` 接口
+
+```
+QUEUE_DIR = ~/.claude-forge/queue/
+DEAD_DIR  = ~/.claude-forge/queue/dead/
+MAX_FILES = 500
+TTL_DAYS  = 7
+
+enqueueEvent(event: ForgeEvent): void
+  - 文件名：<iso-timestamp>-<event_id>.json
+  - 写入前 prune：目录文件数 >= MAX_FILES 删最旧
+
+replayQueue(storage: SQLiteStorage): Promise<{ replayed, skipped, dead }>
+  - 读 QUEUE_DIR 下所有 *.json
+  - TTL > 7 天 → 移入 DEAD_DIR
+  - JSON.parse → storage.writeEvent
+  - UNIQUE constraint → skipped++（去重）
+  - 成功入库 → rm 文件 → replayed++
+  - JSON 损坏 → 移入 DEAD_DIR → dead++
+
+pruneQueue(): void  // 内部使用
+```
+
+### `src/daemon/index.ts` 改动
+
+在 socket `listen` 回调内（`logger.info('Socket 服务器已监听')` 之后）追加：
+
+```
+replayQueue(storage).then(({ replayed, skipped, dead }) => {
+  logger.info(`[Queue] Replay: ${replayed} replayed, ${skipped} skipped (dup), ${dead} dead-lettered`);
+});
+```
+
+### Hook 脚本改动模式
+
+```bash
+# 当前：
+RESPONSE=$(echo "$EVENT" | nc -U -w 10 "$SOCKET_PATH" 2>/dev/null)
+
+# 新增：nc 失败或 RESPONSE 为空时 fork 写队列
+if [ -z "$RESPONSE" ]; then
+  (
+    QUEUE_DIR="$HOME/.claude-forge/queue"
+    mkdir -p "$QUEUE_DIR"
+    TS=$(date -u +"%Y%m%dT%H%M%S")
+    UUID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo "$$-$RANDOM")
+    echo "$EVENT" > "$QUEUE_DIR/${TS}-${UUID}.json"
+  ) &
+fi
+```
+
+注意：macOS BSD `date` 不支持 `%N` 毫秒，所以 timestamp 用秒精度 + UUID 兜底唯一性。
+
+---
+
+## 五、风险点
+
+| 风险 | 概率 | 缓解方案 |
+|---|---|---|
+| 5 hook 同时写同名文件 | 低 | 文件名含 UUID（uuidgen），冲突 < 1/10^12 |
+| JSON 文件写一半被截断 | 低 | replayQueue catch JSON.parse → dead-letter |
+| daemon 重放时 socket 刚启动又挂掉 | 极低 | 每文件独立 try/catch，单失败不中断 |
+| queue 文件含旧 `_auth` token | 必然发生 | 重放走 `storage.writeEvent`，不经 socket 认证，Zod schema strip 自动剥离 |
+| 历史已丢失数据 | 已发生 | 本次范围外；可手动从 `~/.claude/projects/*/*.jsonl` 回填 |
+
+---
+
+## 六、测试策略
+
+### 单元测试 `src/tests/queue.test.ts`
+
+| 用例 | 验证点 |
+|---|---|
+| enqueueEvent 写入 | 文件存在，内容可 JSON.parse |
+| 超过 500 文件 prune 删最旧 | 写 510 个 → 文件数 = 500 |
+| replayQueue 成功 → 文件删除 | mock writeEvent 成功 → 文件消失 |
+| UNIQUE 冲突 → 文件删 + skipped++ | mock 抛 UNIQUE → skipped=1 |
+| JSON 损坏 → 移入 dead | 非法 JSON → dead 目录有 |
+| TTL 超期 → 移入 dead | mtime 8 天前 → dead 目录有 |
+
+### 集成测试 `tests/integration/queue-replay.integration.test.ts`
+
+1. 启动 daemon → 停止 daemon
+2. `enqueueEvent` 写入 3 个 ForgeEvent
+3. 重启 daemon
+4. 查 DB：3 条事件在 events 表
+5. 验证 queue/ 为空
+6. 第二次重启验证去重（skipped=3）
+
+### E2E 验证
+
+```bash
+./scripts/dev-daemon.sh restart &
+echo '{"session_id":"test","cwd":"/tmp"}' | bash src/hooks/user-prompt-submit.sh
+sqlite3 ~/.claude-forge/data.db "SELECT count(*) FROM events WHERE session_id='test';"
+# 期望：1
+```
+
+---
+
+## 七、执行步骤（自底向上）
+
+| # | 步骤 | 文件 |
+|---|---|---|
+| 1 | 实现队列模块（enqueueEvent + replayQueue + pruneQueue） | `src/core/queue/index.ts` |
+| 2 | 单元测试 queue.test.ts 全过 | `src/tests/queue.test.ts` |
+| 3 | `events.ts writeEvent` catch UNIQUE constraint 静默忽略 | `src/core/storage/events.ts` |
+| 4 | daemon/index.ts 调用 replayQueue（socket ready 后） | `src/daemon/index.ts` |
+| 5 | 修改 3 个 hook（user-prompt-submit、pre-tool-use、post-tool-use） | `src/hooks/*.sh` |
+| 6 | 集成测试通过 | `tests/integration/queue-replay.integration.test.ts` |
+| 7 | E2E：dev-daemon.sh restart 期间发事件验证 | 手工 + changelog |
+| 8 | 部署：cp hook 到 ~/.claude-forge/hooks/ + 重启 daemon | 手工 |

package/docs/design/l1-swarm-protocol-extract-spec-20260518-1605.md

@@ -0,0 +1,106 @@
+# L1: SWARM_PROTOCOL 字面量抽到 .md 文件 Spec
+
+## 目标
+
+把 `src/claudemd/claudemd-generator.ts` 中 223 行的 `SWARM_PROTOCOL` 字符串字面量抽到 `src/claudemd/templates/swarm-protocol.md`，build 时 cp 到 dist/，加载方式对齐 H3 `schema.sql` 的 fail-fast 模式。
+
+## 调研结果
+
+### 当前位置
+
+- `src/claudemd/claudemd-generator.ts:555-777`（`const SWARM_PROTOCOL = `...`;`）
+- 内容：223 行 markdown，含转义反引号
+- 唯一使用点：第 59 行 `const full = SWARM_PROTOCOL + '\n\n' + projectContent;`（`generate()` 方法内）
+- 上方有两段重复注释（547-553），可顺手清理
+
+### 加载先例
+
+1. **`src/core/storage/base.ts:61-73`（H3 schema.sql）**：`fileURLToPath(import.meta.url)` + `dirname` 解析同级目录，`existsSync` 校验，缺失抛 `[SQLiteStorage] schema.sql not found at ...`。ESM 兼容，dev/npm 一致。
+2. **`src/skills/registry.ts:46-49` + `src/skills/official-skills.ts:52-55`（skills/official）**：同样 `fileURLToPath(import.meta.url)`。
+
+### 现有测试
+
+- `tests/integration/` 与 `src/tests/` 均无 `claudemd-generator` 测试 → **零覆盖**，必须先建 safety-net。
+
+## 设计方案
+
+### 文件位置
+
+- 新建 `src/claudemd/templates/swarm-protocol.md`（kebab-case，内容为现 555-777 行的原文，去掉 JS 反引号转义）
+
+### claudemd-generator.ts 改造
+
+```text
+- 删除 const SWARM_PROTOCOL = `...`;（555-777）
+- 删除上方 547-553 重复注释块
+- 新增模块级函数 getSwarmProtocol(): string
+  · const thisDir = dirname(fileURLToPath(import.meta.url))
+  · const p = join(thisDir, 'templates', 'swarm-protocol.md')
+  · 若 !existsSync(p) 抛 `[ClaudeMdGenerator] swarm-protocol.md not found at ${p}. Run npm run build or reinstall.`
+  · readFileSync(p, 'utf-8')
+- 一级缓存：模块级 let cached: string | null = null（避免每次 generate 都读盘）
+- 第 59 行：const full = getSwarmProtocol() + '\n\n' + projectContent;
+- 顶部 import 加 fileURLToPath（node:url）、dirname（已从 node:path 导入需补 dirname）
+```
+
+命名 `get` 前缀（获取单一资源）。
+
+### package.json build 改造
+
+在现有 `build` 命令中追加：
+
+```bash
+mkdir -p dist/claudemd/templates && cp src/claudemd/templates/*.md dist/claudemd/templates/
+```
+
+末尾 fail-fast 校验追加：
+
+```bash
+&& (test -f dist/claudemd/templates/swarm-protocol.md || (echo '[build] FATAL: dist/claudemd/templates/swarm-protocol.md missing' && exit 1))
+```
+
+与现有 `dist/core/storage/schema.sql` 校验风格保持一致。
+
+## 测试策略
+
+### safety-net（必做，先行）
+
+新增 `tests/integration/claudemd-generator.test.ts`：
+
+1. **Baseline 测试（迁移前跑通）**：
+   - mock `ClaudeProvider.complete` 抛错（走 fallback 路径），调 `generator.generate(tmpDir)`
+   - 断言输出包含 SWARM_PROTOCOL 关键字段：`# claude-forge 工作区规范`、`## 自检`、`Two-Phase Workflow`、`harness-hotfix`、`refactor-safe`、`hybrid-feature-with-safety`
+   - 断言总行数 ≥ 200
+2. **快照锚点**：保存 SWARM 段的 SHA256 或长度，迁移后断言不变
+
+### 回归
+
+- 迁移完成后重跑 safety-net，断言行为完全一致（同一 hash / 同一行数 / 同一关键字）
+- `npx tsc --noEmit`
+- `npm test`
+- 手测：`npm run build` 后 `ls dist/claudemd/templates/swarm-protocol.md`
+
+## 风险与回滚
+
+| 风险 | 缓解 |
+|---|---|
+| dev 跑 `tsx src/` 时 dist 不存在 | `fileURLToPath(import.meta.url)` 解析到 `src/claudemd/`，同级 `templates/` 在 src 下存在，dev 路径天然兼容 |
+| npm 安装包 cp 失败 | build 末尾 `test -f` 校验，CI 失败而非运行时炸 |
+| .md 内反引号转义遗漏 | safety-net 哈希比对会发现 |
+| 模块级缓存导致测试串扰 | 暴露 `__resetCache()` 仅 test 用，或不缓存（223 行读盘成本可忽略） |
+
+**回滚**：单 commit revert 即可（generator.ts + package.json + 新 .md 文件）。
+
+## 实施顺序
+
+1. 补 `tests/integration/claudemd-generator.test.ts`（safety-net，**当前字面量实现下跑绿**）
+2. 创建 `src/claudemd/templates/swarm-protocol.md`（复制 555-777 原文，去 JS 转义）
+3. 改 `claudemd-generator.ts`：加 `getSwarmProtocol()`，删字面量与重复注释
+4. 改 `package.json` build：cp + fail-fast 校验
+5. 跑 `npm run build && npm test && npx tsc --noEmit`，对比 safety-net hash
+
+## 命名遵循
+
+- 文件 kebab-case：`swarm-protocol.md`、`claudemd-generator.test.ts`
+- 加载函数 `get` 前缀：`getSwarmProtocol()`
+- 错误前缀 `[ClaudeMdGenerator]`，与 `[SQLiteStorage]` 风格一致

package/docs/design/m10-forge-paths-spec-20260518-1320.md

@@ -0,0 +1,121 @@
+# M10: ~/.claude-forge 子路径硬编码收敛 Spec
+
+## 目标
+把 `~/.claude-forge/<子路径>` 的硬编码（共 7 类、20+ 处）统一收敛到 `src/core/constants.ts` 的 `FORGE_PATHS`，消除 `path.join(homedir(), '.claude-forge', ...)` 重复并降低未来路径变更的成本。
+
+## 调研结果
+
+### 子路径分组（仅 `~/.claude-forge/` 下的真实文件路径）
+
+| 子路径 | 引用文件:行 | 总次数 | 现有 FORGE_PATHS |
+|---|---|---|---|
+| `daemon.token` | lifecycle.ts:9; cli/mcp.ts:45; auth-middleware.ts:18 | 3 | 否 |
+| `daemon.pid` | lifecycle.ts:10; cli/daemon.ts:45; cli/status.ts:8; cli/mcp.ts:86 | 4 | 否 |
+| `daemon.sock` | lifecycle.ts:52 | 1（外加 error-handler.ts:239 的"forge.sock"字面量提示文本，**待统一**） | 否 |
+| `daemon.log` / `daemon-stdout.log` / `daemon-stderr.log` | cli/daemon.ts:47,48,115 | 3 | 否 |
+| `hooks/` | cli/init/hook-manager.ts:8 | 1 | 否 |
+| `queue/` + `queue/dead/` | core/queue/index.ts:26-28 | 2 | 否 |
+| `routing.yaml` | web/routes/types.ts:37 | 1 | 否 |
+| `backups/skills` | web/routes/skills.ts:208,235,279,321; web/routes/types.ts:32 | 5 | 否 |
+| `backups/routing` | web/routes/types.ts:38 | 1 | 否 |
+| `data.db` (字面量) | cli/stats.ts:21 | 1 | **已有但未用** → 改为 `FORGE_PATHS.database()` |
+
+### 不属于 FORGE_PATHS 的引用（保留硬编码）
+
+- `process.cwd() + '.claude-forge/executions/by-route'`（cli/executions.ts:16,53,85）— **项目级目录**，不是 `~/.claude-forge`
+- `project_path + '.claude-forge/history'`（daemon/handlers/history-exporter.ts:24）— 同上
+- `templates/template-manager.ts:88`（在项目 `projectPath` 下创建 `.claude-forge`）— 项目级
+- `cli/init/hook-manager.ts:34`（substring 匹配字符串，非路径拼接）
+- `error-handler.ts` 内所有 `~/.claude-forge/...` 是**面向用户的提示文本**，建议保留字符串字面量（用户阅读），但 `forge.sock` 与代码中 `daemon.sock` 不一致 → 顺手修一下
+- `claudemd-generator.ts:751` 与 `:211` 是模板内嵌字符串
+
+## FORGE_PATHS 扩展设计
+
+```ts
+export const FORGE_PATHS = {
+  home: () => FORGE_HOME,
+  config: () => join(FORGE_HOME, 'config.yaml'),
+  database: () => join(FORGE_HOME, 'data.db'),
+  logs: () => join(FORGE_HOME, 'logs'),
+
+  // ── Daemon runtime files ────────────────────────────────
+  daemonSocket: () => join(FORGE_HOME, 'daemon.sock'),
+  daemonPid:    () => join(FORGE_HOME, 'daemon.pid'),
+  daemonToken:  () => join(FORGE_HOME, 'daemon.token'),
+  daemonLog:    () => join(FORGE_HOME, 'daemon.log'),
+  daemonStdout: () => join(FORGE_HOME, 'daemon-stdout.log'),
+  daemonStderr: () => join(FORGE_HOME, 'daemon-stderr.log'),
+
+  // ── Subdirs ─────────────────────────────────────────────
+  hooks:        () => join(FORGE_HOME, 'hooks'),
+  queue:        () => join(FORGE_HOME, 'queue'),
+  queueDead:    () => join(FORGE_HOME, 'queue', 'dead'),
+
+  // ── Patchable targets ───────────────────────────────────
+  routingYaml:  () => join(FORGE_HOME, 'routing.yaml'),
+  backups:      (kind: 'skills' | 'routing') => join(FORGE_HOME, 'backups', kind),
+} as const;
+```
+
+### 关键决策
+
+1. **`backups(kind)` 参数化 vs 分开**：选**参数化**。理由：`backups` 的两个子目录有共同语义（patch 系统的备份根），且 `resolvePatchTarget` 内已经按 `targetType` 分支。`kind` 用字面量联合类型，越界编译期就报错。
+2. **`daemonLog`/`daemonStdout`/`daemonStderr` 三个独立方法 vs 一个 `daemonLog(channel)`**：选**独立方法**。理由：三者在调用点完全分离（stdout/stderr 仅用于 launchd 重定向，daemon.log 是 logger 输出），不存在动态选择场景。
+3. **动态参数（sessionId 等）不纳入**：`history-exporter` 是 `project_path` 拼接，**不属于** `~/.claude-forge`，本次范围外。
+4. **`error-handler.ts` 的字符串字面量**：保留 `~/.claude-forge/...` 字符串（面向用户阅读），但把 `forge.sock` 改成 `daemon.sock` 与代码一致（顺手修，1 行）。
+
+## 改造范围（按文件）
+
+| 文件 | 改动点 | 影响行数 |
+|---|---|---|
+| `src/core/constants.ts` | 扩展 FORGE_PATHS（11 个新方法）| +12 |
+| `src/daemon/lifecycle.ts` | TOKEN_FILE/PID_FILE 改 FORGE_PATHS；getSocketPath 复用 daemonSocket | ~5 |
+| `src/cli/commands/daemon.ts` | PID_FILE/STDOUT_LOG/STDERR_LOG + line 115 logFile | 4 |
+| `src/cli/commands/status.ts` | PID_FILE（注意：与 lifecycle.ts 重复，可考虑后续从 lifecycle 复用，但本次保持就地替换）| 1 |
+| `src/cli/commands/mcp.ts` | tokenPath:45, pid:86 | 2 |
+| `src/cli/commands/stats.ts` | dbPath:21 改 `FORGE_PATHS.database()` | 1 |
+| `src/cli/init/hook-manager.ts` | HOOKS_DIR 改 `FORGE_PATHS.hooks()` | 1 |
+| `src/core/queue/index.ts` | FORGE_DIR/QUEUE_DIR/DEAD_DIR | 3 |
+| `src/web/auth-middleware.ts` | TOKEN_FILE | 1 |
+| `src/web/routes/types.ts` | resolvePatchTarget 4 处路径 | 4 |
+| `src/web/routes/skills.ts` | backupDir × 4 处 | 4 |
+| `src/core/utils/error-handler.ts` | `forge.sock` → `daemon.sock`（一致性修复）| 1 |
+
+**合计：约 39 处替换、12 文件**。无字符串模板 `${homedir()}/.claude-forge/...` 形式（已用 grep 验证）。所有调用点都是 `path.join(homedir(), '.claude-forge', ...)`，机械替换安全。
+
+## 测试策略
+
+1. **新增** `tests/unit/core/forge-paths.test.ts`：
+   - 每个方法返回值以 `FORGE_HOME` 为前缀
+   - `backups('skills')` / `backups('routing')` 返回正确子路径
+   - 类型层面（编译期）拒绝 `backups('invalid')`
+2. **回归**：
+   - `tests/unit/core/queue/*`（queue 模块已有测试）
+   - 单元测试全量 `npx vitest run`
+   - `npx tsc --noEmit`
+3. **手测**：`./scripts/dev-daemon.sh restart` 验证 pid/token/socket 文件生成
+
+## 风险与回滚
+
+- **路径值不变**：FORGE_PATHS 只是函数封装，运行时返回值与原硬编码完全一致 → 已运行的 daemon、已存在的 token/pid/db 文件不受影响
+- **回滚**：单次 PR、git revert 即可
+- **测试覆盖**：daemon/handlers 部分零测试（CLAUDE.md 提示），本次不修改 handler 逻辑，仅替换路径常量，风险面小；但**因为涉及 `src/daemon/lifecycle.ts`（无单元测试）和 `src/web/routes/`（中等覆盖）**，按 CLAUDE.md「工作流升级判定」表，建议走 `refactor-safe`（safety-net 阶段先补 `forge-paths.test.ts` + 跑现有 queue/storage 测试作为安全网）
+- **launchd plist**：未涉及 plist 模板路径（plist 是绝对路径生成时拼接，不在 FORGE_PATHS 范围）
+
+## 实施顺序（给 coder agent）
+
+1. **safety-net**：新增 `tests/unit/core/forge-paths.test.ts`（先写好测试，让其通过当前 FORGE_PATHS）；跑一遍 `npx vitest run tests/unit/core` 与 `npx tsc --noEmit` 作为基线
+2. **扩展 FORGE_PATHS**：编辑 `src/core/constants.ts` 添加 11 个方法；补全 forge-paths.test.ts 对新方法的断言
+3. **分组替换**（每组完成后跑 `npx tsc --noEmit`）：
+   - Group A：daemon 运行时文件（lifecycle / daemon / status / mcp / auth-middleware）
+   - Group B：queue（core/queue/index.ts）
+   - Group C：hooks（hook-manager.ts）
+   - Group D：web patch（types.ts + skills.ts × 4）
+   - Group E：stats.ts + error-handler.ts 文案修复
+4. **全量验证**：`npm test` + `npm run build` + `./scripts/dev-daemon.sh restart` 验证 daemon 正常起停
+
+## 命名遵循
+
+- 方法名 camelCase：`daemonSocket`, `daemonPid`, `routingYaml`, `queueDead` ✓（与现有 `home/config/database/logs` 一致）
+- 常量名 UPPER_SNAKE_CASE：`FORGE_PATHS`, `FORGE_HOME` ✓
+- 测试文件位置：`tests/unit/core/forge-paths.test.ts`