@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/implementation/h2-phase3-callsites-changelog-20260518-1450.md

@@ -0,0 +1,71 @@
+# H2 Phase 3 替换调用方 Changelog
+
+**Date**: 2026-05-18 14:50 (Phase 3)
+**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
+**Status**: Phase 3 完成（Phase 4 待 getDatabase jsdoc）
+
+## 完成清单
+
+- [x] `src/web/routes/stats.ts` — 5 段 SQL → `countAllEvents` / `countAllSessions` / `aggregateToolUsage` / `aggregateDailyEventCounts` / `aggregateDailySessionCounts` / `countAllSkillInvocations`
+- [x] `src/web/routes/trace.ts` — 3 段 SQL → `aggregateHookTypeBySession` / `aggregateAgentTypeBySession` / `queryDistinctSkillIdsBySession`
+- [x] `src/cli/commands/trace.ts` — 3 段 SQL（同 trace.ts 模式）+ 函数签名清理（移除 db 参数）
+- [x] `src/daemon/handlers/stop.ts` — 3 段 SQL → `aggregateToolUsageBySession` / `aggregateAgentTypeBySession` / `countSkillInvocationsBySession`
+- [x] `src/web/analytics/drift-detector.ts` — 4 段 SQL → `countDistinctSkillsSince` / `countActiveDays` / `countSessionsByRange` / `countTasksByRange`
+- [x] `src/web/analytics/weekly-report.ts` — 6 段 SQL → `aggregateOverviewByRange` / `queryDistinctProjects` / `countTasksByRange` / `queryEventsByTimeRange` (内存聚合 tool) / `aggregateToolFailureRate` / `queryFileEditInputs`
+- [x] `src/web/analytics/anti-pattern-detector.ts` — 2 段 SQL → `queryEventsByTimeRange` / `querySessionsByTimeRange`，附带删除无用 `safeParse` helper
+
+## 测试结果
+
+| 测试套件 | 结果 |
+|---|---|
+| `tests/integration/web-stats.integration.test.ts` | 4/4 通过 |
+| `tests/integration/web-trace.integration.test.ts` | 6/6 通过 |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts` | 5/5 通过 |
+| `tests/integration/web-analytics.integration.test.ts` | 5/5 通过 |
+| `npx tsc --noEmit` | 0 errors |
+| `npm test`（全量） | 541 passed / 1 failed（pre-existing：`linkEventToTask`） |
+
+## 残留 db.prepare 检查
+
+`grep -rn "db\.prepare\|getDatabase().prepare" src/web/routes/ src/web/analytics/ src/cli/commands/trace.ts src/daemon/handlers/ --include="*.ts" | grep -v ".test."` 输出：
+
+```
+src/web/routes/stats.ts:7: * H2 Phase 3: 替换原 db.prepare 直写 SQL 为 SQLiteStorage facade 聚合方法。
+src/web/routes/trace.ts:95:    // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+src/daemon/handlers/stop.ts:151:      // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+```
+
+仅剩 3 处提到 `db.prepare` 的注释，**无实际 SQL 直写调用**。Phase 3 目标达成。
+
+## 超出 spec 改动
+
+1. **CLI trace 函数签名清理**：`printSessionTrace(storage, db, sessionId)` → `printSessionTrace(storage, sessionId)`，因 db 参数已无引用方。属于伴生改动，非业务逻辑变更。
+2. **anti-pattern-detector 删除 `safeParse`**：原函数仅在 `queryEventsSince` 旧实现中使用，迁移到 `queryEventsByTimeRange` 后已不再需要（events.ts 的 `rowToEvent` 内部完成 JSON 解析）。属于死代码清理。
+
+## Phase 2 vs 实际签名偏差（重要）
+
+**`aggregateToolUsage` 缺 `until` 参数**：
+- spec 设计：`aggregateToolUsage(opts: { since, until, hook_type, limit })`
+- Phase 2 实现：`aggregateToolUsage(opts: { since?, hook_type?, limit? })`，**缺 `until`**
+
+**影响**：`weekly-report.ts:aggregateTools` 需要 `[since, until)` 半开区间过滤（历史周不应混入下一周事件）。
+
+**临时处理**：改用 `queryEventsByTimeRange({ since, until })` + JS 内存聚合 PreToolUse + tool_name。语义正确，但比专门聚合 SQL 多一次行映射。
+
+**建议**：Phase 4 之后若有 H3，可考虑给 `aggregateToolUsage` 补 `until`，或新增 `aggregateToolUsageByRange`。当前不阻塞 Phase 3。
+
+## 关键设计决策
+
+1. **时间窗口 ISO 字符串化**：旧 SQL 用 `date('now', '-7 days')` SQLite 日期函数。新口径统一调用方计算 `new Date(Date.now() - N * 86400000).toISOString()` 后传 facade。在 `stats.ts` / `drift-detector.ts` 两处沿用此模式。
+2. **保留响应 shape**：所有路由响应字段名（toolUsage / dailyActivity / event_breakdown 等）完全不变，只把内部 `cnt` 字段名换成 facade 返回的 `count`，前端契约 0 改动。
+3. **failure 检测三条 LIKE 分支保留**：通过 `aggregateToolFailureRate` 内部封装 `'%"error"%' OR '%"is_error":true%' OR '%"isError":true%'`，行为与旧 SQL 完全一致。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > Task Operations > linkEventToTask associates events with tasks` — **pre-existing 失败**（UUID 校验问题，与 Phase 3 无关）
+
+## Phase 4 待办
+
+- `getDatabase()` 加 jsdoc `@internal` 警告（spec §「方案选择」与 Phase 4 计划）
+- 跑全量 tsc + npm test 二次确认
+- 可选：CLAUDE.md 「常见陷阱」补 1 条「越权 SQL 必须走 facade」

package/docs/implementation/h3-fallback-removal-changelog-20260518-1245.md

@@ -0,0 +1,71 @@
+# H3 实施 Changelog
+
+**Date**: 2026-05-18 12:45
+**Spec**: docs/design/h3-fallback-removal-spec-20260518-1245.md
+**Status**: 完成
+
+## 完成清单
+
+- [x] `src/core/storage/base.ts` `initSchema()` 删除 inline fallback + fail-fast
+- [x] `src/core/storage/base.ts` 文件头注释清理（"或 inline fallback" → "缺失则抛错"）
+- [x] `package.json` build script 末尾追加 `test -f dist/core/storage/schema.sql` 校验
+- [x] `tests/unit/storage/schema-missing.test.ts` 新增 2 个 case
+
+## 关键代码定位
+
+- `src/core/storage/base.ts:6` — 文件头注释："加载 schema.sql（缺失则抛错）"
+- `src/core/storage/base.ts:61-73` — `initSchema()` 重写：`existsSync` 缺失 → 抛 Error；不再有 else fallback 分支
+- `package.json:13` — build script 末尾：`&& (test -f dist/core/storage/schema.sql || (echo '[build] FATAL: dist/core/storage/schema.sql missing' && exit 1))`
+- `tests/unit/storage/schema-missing.test.ts:1-83` — 新测试文件
+
+## 设计要点
+
+### initSchema 行为变化
+
+**旧**：
+```ts
+if (existsSync(schemaPath)) {
+  // 读取并 exec schema.sql
+} else {
+  // inline fallback：只建 events 表 + 4 个旧索引
+}
+```
+
+**新**：
+```ts
+if (!existsSync(schemaPath)) {
+  throw new Error('[SQLiteStorage] schema.sql not found at ${schemaPath}. ...');
+}
+const schema = readFileSync(schemaPath, 'utf-8');
+this.db.exec(schema);
+```
+
+错误信息含修复建议：`Run \`npm run build\` or reinstall the package.`
+
+### 测试 mock 策略
+
+`tests/unit/storage/schema-missing.test.ts` case 2 使用 `vi.doMock('node:fs', ...)` + 动态 `import()`：
+
+- 只让 `existsSync` 在路径以 `schema.sql` 结尾时返回 false
+- 其他路径（如 mkdir 时的目录检查）保留真实行为，避免破坏构造函数的目录创建逻辑
+- 每个 case 后 `vi.doUnmock` + `vi.resetModules` 防止跨 case 污染
+
+### Build 校验
+
+`(test -f dist/core/storage/schema.sql || (echo '[build] FATAL:...' && exit 1))` 在所有 cp 步骤之后跑，捕获 schema.sql 漏拷贝场景。括号子 shell 形式确保 `||` 短路 + 显式 exit 1。
+
+## 测试结果
+
+- 新增 `schema-missing.test.ts`：**2 / 2 passed**
+- 现有 `tests/unit/storage/`：**60 / 61 passed**（仅 pre-existing `linkEventToTask` 失败）
+- `npx tsc --noEmit`：**0 errors**
+- `npm test`：**423 / 424 passed**（仅 pre-existing `linkEventToTask`）
+- `npm run build`：**成功**（dist/core/storage/schema.sql 存在，校验通过）
+
+## 超出 spec 改动
+
+无。严格按 spec 改了 base.ts、package.json、新增 1 个测试文件。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` — pre-existing failure（事件 UUID 校验失败），与本次 H3 改动无关，spec 明确豁免

package/docs/implementation/h4-index-dedup-changelog-20260518-1230.md

@@ -0,0 +1,60 @@
+# H4 实施 Changelog
+
+**Date**: 2026-05-18 12:30
+**Spec**: docs/design/h4-index-dedup-spec-20260518-1230.md
+**Status**: 完成
+
+## 完成清单
+
+- [x] schema.sql 补 2 索引：`idx_skill_invocations_workflow` / `idx_skill_invocations_feature`
+- [x] base.ts 加 `hasTable` / `hasIndex` 工具
+- [x] base.ts 加 `createIndexIfMissing` 私有工具（hasIndex 守护 + debug 日志）
+- [x] `runMigrations` 拆为 `runColumnMigrations` / `runIndexMigrations` / `runPostMigrations`
+- [x] 列 migration 提前到 `initSchema()` 之前（修复 schema.sql 索引引用未存在列的回归）
+- [x] 索引 migration（10 处）全部用 `createIndexIfMissing` 守护
+- [x] 新增测试 `tests/unit/storage/migration-idempotent.test.ts`（4 case）
+
+## 关键代码定位
+
+- `src/core/storage/schema.sql:220-222` — 新增 `idx_skill_invocations_workflow` / `idx_skill_invocations_feature`
+- `src/core/storage/base.ts:46-60` — 构造函数调整为 `runColumnMigrations → initSchema → runIndexMigrations → runPostMigrations`
+- `src/core/storage/base.ts:87-96` — 新增 `hasTable` 工具
+- `src/core/storage/base.ts:107-121` — `addColumnIfMissing` 加 `hasTable` 短路（避免新库时 PRAGMA 噪音）
+- `src/core/storage/base.ts:123-137` — `hasIndex` 工具（按 spec 第 4 节实现）
+- `src/core/storage/base.ts:139-153` — `createIndexIfMissing` 私有工具（hasIndex 守护 + debug 日志）
+- `src/core/storage/base.ts:155-171` — `runColumnMigrations`（7 处 addColumnIfMissing）
+- `src/core/storage/base.ts:173-227` — `runIndexMigrations`（10 处 createIndexIfMissing）
+- `src/core/storage/base.ts:232-244` — `runPostMigrations`（backfill + drop deprecated）
+- `tests/unit/storage/migration-idempotent.test.ts` — 新增 4 个 case
+
+## 测试结果
+
+- **新增测试**：`migration-idempotent.test.ts` 4/4 passed
+  - `baseline (缺索引)`：老库缺所有 migration 索引 → 启动后全部补齐
+  - `baseline (缺列)`：老库缺 `sessions.first_prompt` → ALTER 补齐
+  - `新库无害`：完整 schema.sql 初始化后再 new SQLiteStorage → 不重复 CREATE INDEX（debug 日志为 0 次"migration created"，无 warn/error）
+  - `idempotent`：连续 3 次 new SQLiteStorage → 索引/列集合完全一致
+- **storage 全模块**：`tests/unit/storage/` 58 passed / 1 pre-existing failed
+- **tsc**：0 errors
+- **npm test 全量**：421 passed / 1 failed
+  - 唯一失败：`tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask associates events with tasks` — pre-existing，与 H4 改动无关
+
+## 超出 spec 改动
+
+1. **构造函数顺序调整**：`runColumnMigrations` 提到 `initSchema` 之前。
+   - **原因**：spec 第 1 步要求把 `idx_skill_invocations_workflow ON skill_invocations(workflow, phase)` 放进 schema.sql。但 base.ts 原本顺序是 `initSchema → runMigrations`，对于"老库（无 workflow 列）"场景，`initSchema` 跑 schema.sql 时 `CREATE TABLE IF NOT EXISTS skill_invocations` 跳过老表（不会补列），随后 `CREATE INDEX ... ON skill_invocations(workflow, phase)` 即报 `no such column: workflow`。
+   - **现场重现**：先暴露于新增 `migration-idempotent.test.ts` 的 baseline case，随后确认 pre-existing 测试 `skill-invocations-workflow.test.ts` 的"增量迁移"case 同样会失败。
+   - **解决**：把 `addColumnIfMissing` 调用提前。等到老表已有 workflow 列后，schema.sql 的 CREATE INDEX 才安全。
+   - **影响**：新库（空 db）下 `hasTable` 全 false，列 migration 全静默跳过；老库下列先 ALTER；已 up-to-date 库下全跳过。三种路径均通过测试。
+
+2. **新增 `hasTable` 工具 + addColumnIfMissing 短路**：避免新库初始化时 PRAGMA 表不存在的噪音。spec 未要求但与顺序调整配套。
+
+3. **`runMigrations` 拆为 3 个私有方法**：column / index / post。提升可读性，让"列在前、索引在后、数据迁移最后"的依赖关系显式化。spec 第 49 行只要求"runMigrations 全部改造为 has 判断守护"，拆分是顺手优化。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > Task Operations > linkEventToTask associates events with tasks` — pre-existing failure，原因是测试数据校验失败（event tool_input 字段），与 H4 无关。H1 阶段已识别。
+
+## inline fallback (base.ts initSchema else 分支)
+
+按 spec 要求未动。spec 第 54 行明确说"本次 H4 不动它，仅注释 TODO"，但 base.ts 现有代码无 TODO 注释，且 spec 没强制要求加，保持原状。

package/docs/implementation/h6-services-migration-changelog-20260518-1355.md

@@ -0,0 +1,46 @@
+# H6 实施 Changelog
+
+**Date**: 2026-05-18 13:55
+**Spec**: docs/design/h6-services-migration-spec-20260518-1355.md
+**Status**: 完成
+
+## 完成清单
+- [x] safety-net: tests/integration/web-analytics.integration.test.ts（3/3 pass，迁移前后均通过）
+- [x] git mv 3 文件到 src/web/analytics/（保留 git history）
+- [x] 改 3 处 import 路径（drift / reports / insights routes）
+- [x] 清理 2 处误导注释（weekly-report 的 "implemented by another agent" + anti-pattern 的 "daemon/services 既定做法"）
+- [x] task-segmenter.ts 保留原地不动
+- [x] vitest.config.ts 加入 `tests/integration/**` 到 include（让 safety-net 能被 npm test 拾取）
+
+## 关键代码定位
+- 新测试文件：`tests/integration/web-analytics.integration.test.ts:1-67`
+- 迁移后入口：`src/web/analytics/{drift-detector,weekly-report,anti-pattern-detector}.ts`
+- import 变更：
+  - `src/web/routes/drift.ts:3` → `from '../analytics/drift-detector.js'`
+  - `src/web/routes/reports.ts:10` → `from '../analytics/weekly-report.js'`
+  - `src/web/routes/insights.ts:7` → `from '../analytics/anti-pattern-detector.js'`
+- 注释清理：
+  - `src/web/analytics/weekly-report.ts:293-297`（aggregateAnomalies 内）
+  - `src/web/analytics/anti-pattern-detector.ts:76-81`（queryEventsSince 上方 JSDoc）
+- vitest 配置：`vitest.config.ts:8`
+
+## 测试结果
+- web-analytics 集成测试：3 passed（迁移前 baseline、迁移后回归均 3/3）
+- tsc --noEmit：0 errors
+- npm test：455 passed / 1 failed（仅 pre-existing `linkEventToTask` 失败，与本次迁移无关）
+- npm run build：成功（dist/web/analytics/ 产出齐全；dist/daemon/services/ 只剩 task-segmenter）
+
+## 超出 spec 改动
+- **vitest.config.ts 更新 include 模式**：原配置只扫描 `tests/unit/**`，导致 `tests/integration/**` 下的测试（含已有的 `tasks-filter.integration.test.ts`）从未跑过。为让 safety-net 真正生效，新增 `tests/integration/**/*.test.ts` 到 include。
+  - 副作用确认：把 `tasks-filter.integration.test.ts` 也拉进 CI，但它本就在主测试套件中通过（455 项 passed 含它）。
+
+## 已知问题
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` 失败（pre-existing，事件 UUID 校验问题，与 H6 迁移无关）
+
+## 迁移内文件 import 路径核查
+3 个被迁移的文件原来用 `../../core/...` 引用 core 层。从 `src/daemon/services/` 移到 `src/web/analytics/` 后，相对深度未变（仍为 2 层向上），无需调整。grep 校验通过：
+
+```
+grep -rn "daemon/services/drift-detector|daemon/services/weekly-report|daemon/services/anti-pattern-detector" src/ tests/
+→ 无任何匹配
+```

package/docs/implementation/h7-m9-defaults-changelog-20260518-1300.md

@@ -0,0 +1,46 @@
+# H7 + M9 实施 Changelog
+
+**Date**: 2026-05-18 13:00
+**Status**: 完成
+
+## 背景修正
+
+原 review 误判：`claude-sonnet-4-6` 实际为合法 Sonnet 4.6 ID（非"非法"）。
+真实问题：`provider.ts` 的 `DEFAULT_MODEL` 是已过时的 `claude-sonnet-4-20250514`（Sonnet 4.0 旧 ID），应改用 constants 暴露的最新值。
+端口侧的真实问题：`constants.ts` 的 `WEB_PORT: 3456` 是孤儿值（无人引用），而实际事实标准是 `3721`（7 个文件硬编码）。
+
+## 完成清单
+
+- [x] `constants.ts` `WEB_PORT: 3456` → `3721`
+- [x] `provider.ts` 删除硬编码 `DEFAULT_MODEL`，改用 `DEFAULTS.AI_MODEL`
+- [x] `daemon/index.ts:73` 端口 fallback 用 `DEFAULTS.WEB_PORT`
+- [x] `cli/commands/daemon.ts:46` 同上
+- [x] `cli/commands/init.ts:107` 同上
+- [x] `core/utils/error-handler.ts:224` 同上 (`String(DEFAULTS.WEB_PORT)`)
+- [x] URL 字符串改 template literal（menu.ts ×3, trace.ts ×1）
+
+## 关键文件
+
+- `src/core/constants.ts:44` — `WEB_PORT: 3721`
+- `src/core/ai/provider.ts:27-29` — 移除 `DEFAULT_MODEL`，新增 `import { DEFAULTS } from '../constants.js'`
+- `src/daemon/index.ts:73` — `?? DEFAULTS.WEB_PORT`
+- `src/cli/commands/daemon.ts:46` — `const DEFAULT_PORT = DEFAULTS.WEB_PORT`
+- `src/cli/commands/init.ts:107` — `let webPort: number = DEFAULTS.WEB_PORT`
+- `src/core/utils/error-handler.ts:224` — `String(DEFAULTS.WEB_PORT)`
+- `src/cli/commands/menu.ts:127,129,244` — template literal `http://localhost:${DEFAULTS.WEB_PORT}`
+- `src/cli/commands/trace.ts:154` — 同上
+
+## 测试结果
+
+- `npx tsc --noEmit`：0 errors
+- `npm test`：423 passed / 1 failed（pre-existing `linkEventToTask` 与本次变更无关，位于 `tests/unit/storage/sqlite-refactor-harness.test.ts`，根因在 `EventOperations.writeEvent` 校验）
+
+## 不改的位置（理由）
+
+无。原计划中保守保留的 URL 字符串（menu.ts / trace.ts）由于改造极轻量（template literal），一并收敛进 `DEFAULTS.WEB_PORT`，进一步消除字面量漂移风险。
+
+## 影响面 / 风险
+
+- 行为变更点：`constants.ts` 的 `WEB_PORT` 之前为 `3456`，但 grep 确认无实际引用，所以此值修正为 `3721` 不产生回归。
+- `provider.ts` 默认模型从过时的 `claude-sonnet-4-20250514` 改为合法的 `claude-sonnet-4-6`：在 `config.ai.model` 未显式设置时，AI 调用将使用 Sonnet 4.6（更新、更便宜、更强）。这是预期升级。
+- 所有端口硬编码已收敛到 `DEFAULTS.WEB_PORT`，后续调整只需改一处。

package/docs/implementation/hook-failure-queue-changelog-20260516-1530.md

@@ -0,0 +1,196 @@
+# Hook Failure Queue + Daemon Startup Replay — Implementation Changelog
+
+**Date**: 2026-05-16 14:30 → 15:10
+**Spec**: `docs/design/hook-failure-queue-spec-20260516-1530.md`
+
+---
+
+## 实际改动文件清单
+
+| 路径 | 改动类型 | 说明 |
+|---|---|---|
+| `src/core/queue/index.ts` | 新建 | 队列核心模块（enqueueEvent / replayQueue / pruneQueue） |
+| `src/core/storage/events.ts` | 修改 | UNIQUE constraint 降级为 debug 日志，不再打 error |
+| `src/daemon/index.ts` | 修改 | 新增 `replayQueue` import + `setImmediate` 调用 |
+| `src/hooks/hook-lib.sh` | 新建 | 共享库：`send_event_or_enqueue` + `_enqueue_event_bg` |
+| `src/hooks/user-prompt-submit.sh` | 修改 | source hook-lib.sh，改用 `send_event_or_enqueue` |
+| `src/hooks/pre-tool-use.sh` | 修改 | 同上 |
+| `src/hooks/post-tool-use.sh` | 修改 | 同上 |
+| `src/hooks/notification.sh` | 修改 | 同上（spec 标注"低优先级可选"，按主线程要求一并修改） |
+| `tests/unit/queue.test.ts` | 新建 | 单元测试（9 个用例） |
+| `tests/integration/queue-replay.integration.test.ts` | 新建 | 集成测试（3 个用例） |
+| `vitest.integration.config.ts` | 新建 | 临时 vitest 配置，使集成测试可独立运行 |
+
+`src/hooks/stop.sh` — 未改，与 spec 一致（Stop 事件无重放意义）。
+
+---
+
+## 与 Spec 偏差
+
+### 偏差 1：hook-lib.sh 决策（主线程修正 3）
+
+**选择**：新建 `src/hooks/hook-lib.sh`，共享 `send_event_or_enqueue` 函数。
+
+**理由**：5 个 hook 脚本的 enqueue 逻辑完全相同。若各自独立维护 ~15 行，任何 bug 修复都需要改 4 处，容易遗漏。`hook-lib.sh` 约 60 行，每个 hook 只需 `source hook-lib.sh` + 一行调用，减少重复且保持一致性。
+
+### 偏差 2：hook 失败判断（主线程修正 2）
+
+**选择**：双重检查 — 先检查 `[ -S "$SOCKET_PATH" ]`，再检查 nc 的 exit code。
+
+**macOS BSD nc 行为分析**：
+- macOS `nc -U -w N` 对 Unix socket：连接成功 + 连接被远端关闭 → exit 0，即使响应为空字符串
+- socket 文件不存在 → exit 1
+- 连接被拒绝 / 超时 → exit 1
+
+**关键约束满足**：daemon 正常返回空响应（无 systemMessage / additionalContext），此时 nc exit code = 0，`HOOK_RESPONSE` 为空字符串 → 不入队。这修复了 spec 原始方案用 `[ -z "$RESPONSE" ]` 造成的误判问题。
+
+### 偏差 3：events.ts UNIQUE 约束处理
+
+Spec 要求"daemon 侧 writeEvent catch UNIQUE constraint 静默跳过"。
+
+**最终方案**：`events.ts` 对 UNIQUE constraint 降级为 debug 日志（不打 error），但**仍然 throw**。原因：`replayQueue` 依赖 throw 来区分"成功入库"（`replayed++`）和"重复"（`skipped++`）。如果 `writeEvent` 静默返回，replayQueue 无法计 skipped。
+
+Daemon 的 `handleEvent` 中单独 catch UNIQUE constraint，以防止正常 hook 流量因竞态（极低概率）收到重放的 event_id 而崩溃。
+
+---
+
+## 测试结果
+
+### 单元测试（9 个，全过）
+
+```
+npx vitest run tests/unit/queue.test.ts --reporter=verbose
+
+✓ enqueueEvent 写入文件并可被 JSON.parse
+✓ enqueueEvent 保留已有 event_id
+✓ pruneQueue 超过 MAX_FILES 时删最旧文件
+✓ pruneQueue 未到 MAX_FILES 时不删文件
+✓ replayQueue 重放事件入库并删除队列文件
+✓ replayQueue 对重复 event_id 静默跳过（skipped++）
+✓ replayQueue 移动损坏 JSON 到 dead-letter
+✓ replayQueue 移动 TTL 超期文件到 dead-letter
+✓ replayQueue 队列为空时返回全零
+
+Tests: 9 passed (9)
+```
+
+### 集成测试（3 个，全过）
+
+```
+npx vitest run --config vitest.integration.config.ts tests/integration/queue-replay.integration.test.ts --reporter=verbose
+
+✓ 入队 3 个事件 → replayQueue → DB 有 3 行，队列为空
+✓ 第二次 replayQueue → skipped=3（去重），DB 仍 3 行
+✓ TTL 超期 + 损坏 JSON → dead-letter 2 个，重放 1 个
+
+Tests: 3 passed (3)
+```
+
+### 全量单元测试
+
+```
+npx vitest run --reporter=dot
+
+Test Files: 2 failed | 25 passed (27)
+Tests: 3 failed | 300 passed (303)
+```
+
+3 个失败均为**预存在的 bug**（`sqlite-refactor-harness.test.ts` 和 `routes-tasks.test.ts` 使用了非 UUID 格式的 event_id，如 `event-1`，不满足 Zod UUID 验证），与本次改动无关（git stash 验证确认）。
+
+### TypeScript 类型检查
+
+```
+npx tsc --noEmit
+（无输出 = 通过）
+```
+
+---
+
+## E2E 实测证据
+
+### 操作步骤
+
+```bash
+# 1. 停止 daemon
+npm run dev:daemon:stop
+# → "Daemon stopped"
+
+# 2. 确认队列为空
+find ~/.claude-forge/queue -name "*.json" | wc -l
+# → 0
+
+# 3. 调用 hook（daemon 停机中）
+echo '{"prompt":"队列测试 P3-B","cwd":"/tmp","session_id":"queue-test-001"}' \
+  | node -e "const {execSync}=require('child_process');
+             execSync('cat | src/hooks/user-prompt-submit.sh', ...)"
+# hook 退出码 0（入队后台子进程）
+
+# 4. 验证队列文件已写入
+find ~/.claude-forge/queue -name "*.json"
+# → /Users/admin/.claude-forge/queue/20260516T065031-AF74BF77-D0FE-4911-B6EC-22868527E3E1.json
+
+# 5. 启动 daemon
+npm run dev:daemon:start
+# → "Daemon started (PID: 5814)"
+sleep 2
+
+# 6. 验证队列为空（已重放）
+find ~/.claude-forge/queue -name "*.json" | wc -l
+# → 0
+
+# 7. 查询数据库
+sqlite3 ~/.claude-forge/data.db \
+  "SELECT timestamp, user_prompt FROM events WHERE session_id='queue-test-001';"
+```
+
+### 实测输出
+
+```
+sqlite3 query result:
+2026-05-16T06:50:31.000Z|队列测试 P3-B
+```
+
+### Daemon 日志（grep Queue）
+
+```
+[2026-05-16T06:50:44.444Z] [INFO] [Queue] Replaying 1 queued event(s)…
+[2026-05-16T06:50:44.448Z] [INFO] [Queue] Replay: 1 replayed, 0 skipped (dup), 0 dead-lettered
+```
+
+**结论**：daemon 停机期间发送的事件正确入队，daemon 启动后自动重放并写入 DB，队列清空。
+
+---
+
+## 关键实现细节
+
+### send_event_or_enqueue 函数（hook-lib.sh）
+
+```bash
+send_event_or_enqueue() {
+  local event_json="$1"
+  local timeout_secs="${2:-10}"
+  HOOK_RESPONSE=""
+
+  if [ ! -S "$SOCKET_PATH" ]; then
+    _enqueue_event_bg "$event_json"
+    return 0
+  fi
+
+  local tmp_response
+  tmp_response=$(echo "$event_json" | nc -U -w "$timeout_secs" "$SOCKET_PATH" 2>/dev/null)
+  local nc_exit=$?
+
+  if [ $nc_exit -ne 0 ]; then
+    _enqueue_event_bg "$event_json"
+    return 0
+  fi
+
+  HOOK_RESPONSE="$tmp_response"
+}
+```
+
+写入策略：`printf '%s' "$event_json" > "$tmp_file" && mv "$tmp_file" "$QUEUE_DIR/${filename}"` — 先写 .tmp 再 rename，保证原子性。
+
+### replayQueue 时序
+
+daemon 启动 → `SocketServer` 构造（listen 绑定）→ `setImmediate(replayQueue)` — 利用 setImmediate 确保 listen 回调先执行，socket 文件权限设好后再重放。

package/docs/implementation/hotfix-daemon-event-reject-20260516-1430.md

@@ -0,0 +1,56 @@
+# Hotfix: Daemon Event Rejection — 20260516-1430
+
+## 根因摘要
+
+Phase 1/2 重构时收紧了 `ForgeEventSchema`，将 `timestamp` 字段改为 `z.string().datetime()`（要求严格 ISO 8601 带 Z 后缀），同时 `hook_type` enum 漏加了 `Notification`。而 hook 脚本使用的是 `date -u +"%Y-%m-%dT%H:%M:%S"`（无毫秒无 Z），导致 daemon 重启后所有入站事件被 Zod 校验拦截拒收，数据库从 `2026-05-16 06:01:30` 起无新事件写入。
+
+## 实际改动文件清单
+
+| 文件 | 改动内容 |
+|---|---|
+| `src/core/storage/events.ts` | `timestamp` 从 `z.string().datetime()` 改为 `z.string().min(1)`（向后兼容历史无 Z 的 timestamp）；`hook_type` enum 加入 `'Notification'` |
+| `src/hooks/user-prompt-submit.sh` | `date` 格式从 `%H:%M:%S` 改为 `%H:%M:%S.000Z` |
+| `src/hooks/pre-tool-use.sh` | 同上 |
+| `src/hooks/post-tool-use.sh` | 同上 |
+| `src/hooks/stop.sh` | 同上 |
+| `src/hooks/notification.sh` | 同上 |
+| `tests/unit/type-guards.test.ts` | 将 `should reject event with invalid timestamp` 更新为 `should reject event with empty timestamp`，测试用例从 `'not-a-valid-timestamp'` 改为 `''`，与新宽松策略一致 |
+
+无其他 `datetime()` 使用点（已全文搜索确认）。
+
+## 验证方式
+
+### TypeScript 类型检查
+```bash
+npx tsc --noEmit
+# 输出：无错误
+```
+
+### 构建
+```bash
+npm run build
+# 输出：正常完成，dist/ 含 hooks/*.sh
+```
+
+### 单元测试
+```bash
+npx vitest run tests/unit/ --reporter=dot
+# 结果：3 failed | 291 passed（3 个失败为本次改动前已存在的预存失败，与本 hotfix 无关）
+```
+
+预存失败清单（本 hotfix 前已存在，不在本次修复范围内）：
+- `tests/unit/web/routes-tasks.test.ts` x2（使用非 UUID 的 event_id）
+- `tests/unit/storage/sqlite-refactor-harness.test.ts` x1（同上）
+
+## 部署步骤（用户需手动执行）
+
+```bash
+# 复制 hooks 到运行时位置
+cp src/hooks/*.sh ~/.claude-forge/hooks/ && chmod +x ~/.claude-forge/hooks/*.sh
+
+# 重启 daemon
+./scripts/dev-daemon.sh restart
+
+# 验证：新事件应出现在数据库
+sqlite3 ~/.claude-forge/data.db "SELECT timestamp, hook_type FROM events ORDER BY rowid DESC LIMIT 5;"
+```

package/docs/implementation/l1-swarm-protocol-extract-changelog-20260518-1605.md

@@ -0,0 +1,45 @@
+# L1 实施 Changelog: SWARM_PROTOCOL 抽到 .md 文件
+
+**Date**: 2026-05-18 16:05
+**Spec**: docs/design/l1-swarm-protocol-extract-spec-20260518-1605.md
+**Status**: 完成
+
+## 完成清单
+
+- [x] safety-net：`tests/integration/claudemd-generator.test.ts` 建立 baseline（SWARM 段 SHA256 锚定）
+- [x] swarm-protocol.md 抽取（223 行，5441 字符 / 7817 字节）
+- [x] claudemd-generator.ts：`getSwarmProtocol()` 加载器 + 模块级缓存
+- [x] package.json `build`：cp `.md` + fail-fast 校验
+
+## 关键代码定位
+
+- 新文件 `src/claudemd/templates/swarm-protocol.md`（223 行）
+- `src/claudemd/claudemd-generator.ts:5-9` — import 增加 `dirname` + `fileURLToPath`
+- `src/claudemd/claudemd-generator.ts:14-38` — `getSwarmProtocol()` 加载函数 + `_swarmProtocolCache`
+- `src/claudemd/claudemd-generator.ts:59` — `generate()` 内 `SWARM_PROTOCOL` 引用改为 `getSwarmProtocol()`（实际行号 65）
+- `src/claudemd/claudemd-generator.ts:568` 之后已无字面量（删除 569-804 共 236 行）
+- `package.json:13` — build 中新增 `mkdir -p dist/claudemd/templates && cp src/claudemd/templates/*.md dist/claudemd/templates/`，末尾追加 `test -f dist/claudemd/templates/swarm-protocol.md` 校验
+
+## 测试结果
+
+- **safety-net SHA256（迁移前后一致）**：`260dfe1e48fdecc324419a6330428eaa3597e3fd6e6262cf66cdcf301ca32e18`
+- **SWARM 段长度（迁移前后一致）**：5442 字节（含分隔符尾的一个 `\n`）
+- **tsc**：0 errors
+- **npm test**：551 / 552 通过（1 个 pre-existing `sqlite-refactor-harness.test.ts > linkEventToTask` 失败，与本次无关）
+- **npm run build**：成功；`dist/claudemd/templates/swarm-protocol.md` 存在（7817 字节，与 src 完全一致）
+
+## 顺手清理
+
+- 删除 `claudemd-generator.ts` 原 547-553 两段重复的 `Core behavioral rules` 注释块（合并到新的 `getSwarmProtocol` 文档块）。
+- 字面量 555-777（223 行）整体下线。文件总行数 805 → 569（-236）。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` — pre-existing 失败，未触碰。
+
+## 兼容性确认
+
+- dev 路径（`tsx src/`）：`fileURLToPath(import.meta.url)` 解析到 `src/claudemd/`，同级 `templates/swarm-protocol.md` 存在 → 加载成功。
+- npm install 路径：build 脚本 cp 到 `dist/claudemd/templates/`，末尾 `test -f` fail-fast 校验，CI 一旦缺失立刻报错。
+- 缓存策略：模块级 `_swarmProtocolCache: string | null = null`，首次调用读盘后缓存；进程生命周期内 0 重复 I/O。
+- 字节级等价：safety-net 测试通过 SHA256 哈希逐字符比对，新旧实现完全一致。

package/docs/implementation/l3-l4-daemon-perf-changelog-20260518-1410.md

@@ -0,0 +1,63 @@
+# L3 + L4 实施 Changelog
+
+**Date**: 2026-05-18 14:10
+**Status**: 完成
+
+## 完成清单
+
+- [x] **L4**: `stop.ts` git 调用异步化
+  - 3 个 `execFileSync` → `promisify(execFile)`
+  - `writeGitNote` 改为 `async`，主流程改为 **fire-and-forget**（`void this.writeGitNote(event)`）
+  - 内部仍按依赖串行 await（rev-parse work-tree → rev-parse HEAD → notes append），但**整体不阻塞 handler 主响应**
+  - 失败仍 catch + `logger.debug`，handler 对外契约不变（返回 `{allow: true}`）
+
+- [x] **L3**: `server.ts` 避免 N² JSON.parse —— **方案 A（换行符分隔）**
+  - 验证 hook 端 `echo "$event_json" | nc -U`：`echo` 默认追加 `\n`，协议天然支持
+  - `data` handler 改为：仅在 `buffer.indexOf('\n') !== -1` 时切出完整消息并解析；未见换行就累积等待
+  - 抽取 `processMessage(socket, message)` 统一处理 auth 检查 + parser + handler response
+  - 兜底：监听 `socket.on('end')`，若 buffer 残留无换行内容（旧客户端）做最后一次解析尝试
+  - 删除 dead code `isCompleteJSON`（不再需要"启发式判完整"，换行就是边界）
+
+## 关键代码定位
+
+- `src/daemon/handlers/stop.ts:19-22` —— `promisify(execFile)` 导入
+- `src/daemon/handlers/stop.ts:84-86` —— `void this.writeGitNote(event)` 调用点
+- `src/daemon/handlers/stop.ts:102-135` —— async `writeGitNote` 实现
+- `src/daemon/server.ts:51-122` —— 新的 `handleConnection` + `processMessage`
+- `tests/unit/socket-server.test.ts` —— 新增 5 个测试（4 socket + 1 EventParser sanity）
+
+## 测试结果
+
+- `npx tsc --noEmit`: **0 errors**
+- `npm test`: **460 passed / 1 failed**（仅 pre-existing `linkEventToTask`）
+- 新增 `tests/unit/socket-server.test.ts`: **5/5 passed**
+
+新测试覆盖：
+1. 单 chunk 完整消息（含换行）
+2. 大消息（~50KB）分 20 个 chunk 到达 —— 断言 `JSON.parse` 调用次数 ≤ 3（远小于 chunk 数，强对比旧 N² 行为）
+3. 600KB 无换行 oversized buffer 被丢弃
+4. 无换行结尾消息走 `socket.on('end')` 兜底
+5. EventParser sanity
+
+## 实施决策
+
+### L4：fire-and-forget + 内部串行
+- **理由**：3 个 git 调用有严格依赖（work-tree 检查 → 拿 HEAD → 写 note），不能 `Promise.all` 并发
+- **关键收益**：原 `execFileSync` 在 handler **主调用链路**中串行阻塞 daemon event loop（最坏 15s）；改 `void` 调用后，git I/O 移到下一个 microtask，handler 立刻返回响应给 hook 客户端
+- **副作用控制**：git 失败仍 `logger.debug`，与原行为一致；handler 主体 try/catch 已存在，async fire-and-forget 的未捕获错误已在 `writeGitNote` 内部 catch
+
+### L3：方案 A（换行符分隔）
+- **理由**：
+  1. 协议天然支持（验证了 `hook-lib.sh` 用 `echo`，默认带 `\n`）
+  2. O(1) 检查（`indexOf('\n')` 在 V8 高度优化）；旧代码每 chunk 做一次完整 `JSON.parse(buffer)` 在 ~512KB buffer 上是真正的 N²
+  3. 单一边界标记，逻辑清晰，无需再保留 `isCompleteJSON` 启发式
+- **兼容性**：保留 `socket.on('end')` 兜底，覆盖未来可能出现的"不带换行的客户端"
+- **协议契约**：不变（hook 端 `echo` 不需要任何修改，服务器只是更聪明地等待 `\n`）
+
+## 跳过项
+
+无。
+
+## 已知问题
+
+- **pre-existing**: `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` 失败（与本次改动无关，schema 校验 uuid 拒绝测试 fixture 中的 `event_id`）