@winspan/claude-forge 8.53.2 → 8.54.3

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

@@ -1,109 +0,0 @@
-# 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

@@ -1,82 +0,0 @@
-# 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

@@ -1,204 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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`