@winspan/claude-forge 8.50.6 → 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/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`）

package/docs/implementation/l6-l8-final-cleanup-changelog-20260518-1640.md

@@ -0,0 +1,38 @@
+# L6 + L8 最终扫尾 Changelog
+
+**Date**: 2026-05-18 16:40
+**Status**: 完成
+
+## 完成清单
+
+- [x] L6: setLogLevel env 解析移到 logger 模块加载
+- [x] L8: token_usage FK 注释补充
+
+## 关键代码定位
+
+- `src/core/utils/logger.ts:5-22` — 新增 `getLogLevelFromEnv()`，模块加载时初始化 `currentLevel`
+- `src/daemon/index.ts:23` / `src/daemon/index.ts:60-63` — 删除手动 env 解析与 setLogLevel 调用，import 收窄为 `logger`
+- `src/core/storage/schema.sql:16-18` / `src/core/storage/schema.sql:20` / `src/core/storage/schema.sql:153-163` —
+  - header 关系图增加 `token_usage` 章节
+  - "Why no FK" 注释主语扩展为 routing_events / skill_invocations / token_usage
+  - token_usage.session_id 字段处补充内联注释（与 routing_events / skill_invocations 同口径）
+
+## 测试结果
+
+- tsc: 0 errors
+- npm test: 551 / 552 通过（1 个 pre-existing 失败：`tests/unit/storage/sqlite-refactor-harness.test.ts` 的 `writeEvent` Invalid uuid 校验失败，与本次改动无关）
+
+## 实施决策
+
+- **L6**：采用「模块加载时一次性读取 env + `getLogLevelFromEnv()` 辅助函数」混合方案。
+  - 顶层 `let currentLevel: LogLevel = getLogLevelFromEnv();` 在模块首次 import 时执行一次。
+  - 由于 logger 模块当前无单元测试（`find src/tests tests/unit -name "logger.test.ts"` 为空），顶层副作用不会破坏测试 mock。
+  - 保留 `setLogLevel()` 导出函数以便测试或运行时覆写（向后兼容）。
+  - daemon/index.ts 不再需要重复 env 解析；其它入口（CLI、web）若 import logger 自动享受同样行为，无需改动。
+- **L8**：纯文档/注释级补充，零 SQL 行为变更。
+  - 沿用 routing_events / skill_invocations 已有的 "logical ref，no FK due to write-order race" 表述。
+  - 同时更新文件头的表关系图，保持单一信息源。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts:166` — `writeEvent Invalid uuid` 断言失败（pre-existing，与 `linkEventToTask` 重构 harness 同一组），本次未修复，按指令不扩大范围。

package/docs/implementation/m1-m4-m5-l7-cleanup-changelog-20260518-1310.md

@@ -0,0 +1,58 @@
+# M1 + M4 + M5 + L7 清理 Changelog
+
+**Date**: 2026-05-18 13:10
+**Status**: 完成
+
+## 完成清单
+- [x] M4: events.ts 删 UpsertCapableEmitter 重复声明
+- [x] L7: types.ts 删 ForgeEvent.pipeline_id 死字段（顺带删除 BaseEvent.pipeline_id）
+- [x] M1: truncateField 抽到 web/routes/_helpers.ts
+- [x] M5: user-prompt.ts 改用 LRUCache（保持两个独立实例）
+
+## 关键代码定位
+
+### M4 — UpsertCapableEmitter 去重
+- `src/core/storage/events.ts:19-22`（旧 L19-21 + 空行）— 删除
+- `src/core/storage/events.ts:57-59` — 保留（更靠近使用点 L64 constructor）
+
+### L7 — pipeline_id 死代码清理
+- `src/core/types.ts:34` — 删除 `ForgeEvent.pipeline_id?`
+- `src/core/types.ts:43` — 删除 `BaseEvent.pipeline_id?`
+- 全量 grep 验证：`pipeline_id` 仅在 types.ts 中出现，无任何运行时引用，无 schema 字段、无注释、无解析逻辑。直接清理。
+
+### M1 — truncateField 抽取
+- 新建 `src/web/routes/_helpers.ts` — 导出 `truncateField(obj, maxLen=300, arrayLimit=10)`
+  - 增加 `arrayLimit` 参数以兼容两个调用点的不同行为（tasks: 10, sessions: 5）
+  - 类型从 `any` 升为 `unknown` + `Record<string, unknown>`
+- `src/web/routes/tasks.ts:1-4` — 新 import `truncateField from './_helpers.js'`
+- `src/web/routes/tasks.ts` — 移除本地 `truncateField` 闭包定义（原 L87-99），调用点保持不变（默认参数 300/10 与原一致）
+- `src/web/routes/sessions.ts:1-3` — 新 import
+- `src/web/routes/sessions.ts` — 移除本地 `truncateField`（原 L189-201），两个调用点显式传 `(toolInput, 200, 5)` / `(toolOutput, 200, 5)` 以保留原有行为
+
+### M5 — LRUCache 替换手写 LRU
+- `src/core/utils/lru-cache.ts:39-45` — 新增 `delete(key)` 方法（必须，否则 clearSession 无法实现）
+- `src/daemon/handlers/user-prompt.ts:10` — 新 import `LRUCache`
+- `src/daemon/handlers/user-prompt.ts:19-25` — 字段替换：
+  - `resumeInjected: Map<string, number>` → `LRUCache<string, number>(1000)`
+  - `conventionInjected: Map<string, number>` → `LRUCache<string, number>(1000)`
+- `src/daemon/handlers/user-prompt.ts:markInjected` — 从 17 行手写 LRU 缩减为单行 `cache.set(key, Date.now())`
+- `src/daemon/handlers/user-prompt.ts:hasInjected` / `clearSession` — 签名从 `Map` 改为 `LRUCache`，行为一致
+
+### M5 设计决策：不合并键集合
+两个 Map 虽然 key 类型相同（`sessionKey`），但语义独立：
+- `resumeInjected` 控制 resume context 注入；同时还会触发 `resume.clear()`
+- `conventionInjected` 控制 project guidance 注入
+
+如果合并成单一键集合，会丧失"同一 session 各自独立标记是否注入过"的语义。保留两个独立 LRUCache 实例最安全，不扩大改动范围。
+
+## 测试结果
+- `npx tsc --noEmit`: **0 errors**
+- `npm test`: **423 passed / 1 failed**
+  - 失败项：`tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask associates events with tasks`
+  - 失败原因：pre-existing UUID 校验问题，与本次清理无关
+
+## 跳过项
+无
+
+## 已知问题
+- pre-existing `linkEventToTask` test failure（与本次清理无关）

package/docs/implementation/m10-forge-paths-changelog-20260518-1320.md

@@ -0,0 +1,60 @@
+# M10 实施 Changelog
+
+**Date**: 2026-05-18 13:20
+**Spec**: docs/design/m10-forge-paths-spec-20260518-1320.md
+**Status**: 完成
+
+## 完成清单
+- [x] safety-net: tests/unit/core/forge-paths.test.ts（16 个断言）
+- [x] FORGE_PATHS 扩展 11 方法（daemonSocket/Pid/Token/Log/Stdout/Stderr, hooks, queue, queueDead, routingYaml, backups(kind)）
+- [x] Group A: daemon 运行时（lifecycle / cli/daemon / cli/status / cli/mcp / web/auth-middleware）
+- [x] Group B: queue（core/queue/index.ts）
+- [x] Group C: hooks（cli/init/hook-manager.ts）
+- [x] Group D: web patch（web/routes/types.ts + web/routes/skills.ts × 4 处）
+- [x] Group E: cli/stats.ts + error-handler.ts 文案 `forge.sock` → `daemon.sock`
+
+## 关键代码定位
+
+**FORGE_PATHS 扩展**：
+- `src/core/constants.ts:9-31` — 新增 11 个方法
+- `tests/unit/core/forge-paths.test.ts` — 新增测试文件，16 个用例
+
+**Group A（daemon 运行时）**：
+- `src/daemon/lifecycle.ts:8-10` — TOKEN_FILE/PID_FILE 改用 FORGE_PATHS；`getSocketPath` (L51) 复用 daemonSocket
+- `src/cli/commands/daemon.ts:34,44-47,114` — PID_FILE/STDOUT_LOG/STDERR_LOG/logFile，并移除未用的 FORGE_HOME import
+- `src/cli/commands/status.ts:5-8` — PID_FILE 改 FORGE_PATHS.daemonPid()；移除 FORGE_HOME import
+- `src/cli/commands/mcp.ts:17-22,45,86` — tokenPath / daemon.pid 路径；移除 homedir/join import
+- `src/web/auth-middleware.ts:13-17` — TOKEN_FILE 改 FORGE_PATHS.daemonToken()；移除 path import
+
+**Group B（queue）**：
+- `src/core/queue/index.ts:16-27` — QUEUE_DIR/DEAD_DIR 改 FORGE_PATHS；移除 homedir import 与未用的 FORGE_DIR 常量
+
+**Group C（hooks）**：
+- `src/cli/init/hook-manager.ts:4,8` — HOOKS_DIR 改 FORGE_PATHS.hooks()
+
+**Group D（web patch）**：
+- `src/web/routes/types.ts:11,30-39` — resolvePatchTarget 中 4 处路径全部改 FORGE_PATHS
+- `src/web/routes/skills.ts:7,208,235,279,321` — backupDir × 4 处统一 → FORGE_PATHS.backups('skills')
+
+**Group E（其它）**：
+- `src/cli/commands/stats.ts:10-21` — dbPath 改 FORGE_PATHS.database()；移除 path/homedir import
+- `src/core/utils/error-handler.ts:239` — 提示文本 `forge.sock` → `daemon.sock`
+
+## 测试结果
+
+```
+forge-paths.test.ts:    16/16 passed
+tests/unit/core/ + storage/ + queue: 85/86 passed（1 pre-existing linkEventToTask）
+npm test 全量:          439/440 passed（1 pre-existing linkEventToTask）
+npx tsc --noEmit:       0 errors
+npm run build:          成功
+```
+
+## 超出 spec 改动
+
+无。严格按 spec 12 文件机械替换。附带顺手清理（与 spec 风险一致）：
+- 删除替换后未引用的 import（`homedir`、`path`、`FORGE_HOME`、`FORGE_DIR` 常量）以保持文件干净，不引入新逻辑。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts` > `linkEventToTask associates events with tasks` 失败 — pre-existing UUID 校验问题，与 M10 改动无关（spec 已明示）。

package/docs/implementation/m2-m3-tool-input-changelog-20260518-1425.md

@@ -0,0 +1,43 @@
+# M2 + M3 实施 Changelog
+
+**Date**: 2026-05-18 14:25
+**Spec**: docs/design/m2-m3-tool-input-spec-20260518-1425.md
+**Status**: 完成
+
+## 完成清单
+- [x] M3: `event-parser.ts` 改为 `event_id: validated.event_id ?? randomUUID()`，schema 加 `event_id: z.string().uuid().optional()`
+- [x] M2: `ToolInputFields` 接口 + 4 个 getter（`getCommand` / `getFilePath` / `getUserPrompt` / `getSubagentType`）
+- [x] 替换所有 `(tool_input as any)` / `(tool_input as Record<string,unknown>)` 使用点（10 处源文件）
+- [x] 新增 `tests/unit/event-fields.test.ts`（15 cases）
+- [x] 新增 `tests/unit/event-parser.test.ts`（5 cases）
+
+## 关键代码定位
+- `src/core/types.ts:25-61` — `ToolInputFields` 接口 + `ForgeEvent.tool_input: ToolInputFields | undefined`
+- `src/core/event-fields.ts:1-32` — 4 个 getter
+- `src/daemon/event-parser.ts:16,23,29` — M3 schema + event_id 透传 + `as ToolInputFields` cast
+- `src/web/routes/sessions.ts:4,82-100,158-167,222-234` — sessions 路由 getter 化（8 处）
+- `src/web/routes/tasks.ts:5,111-131,156-172` — tasks 路由 getter 化（5 处）
+- `src/web/analytics/anti-pattern-detector.ts:95,354-364` — helpers 签名调整为 `ForgeEvent['tool_input']`，line 95 显式 cast
+- `src/daemon/handlers/post-tool-use.ts:5,29` — `getSubagentType(event)`
+- `src/daemon/handlers/history-exporter.ts:102` — 去掉 `as Record<string, unknown>` cast
+- `src/cli/commands/logs.ts:43` — 去掉 `as Record<string, unknown>` cast
+- `src/claudemd/resume-manager.ts:118` — 去掉 `as string` cast，改 `typeof === 'string'` 守卫
+- `src/daemon/index.ts:39-40,161` — import + 改用 `getUserPrompt(event)`
+
+## 测试结果
+- `tests/unit/event-fields.test.ts`: 15 / 15 passed
+- `tests/unit/event-parser.test.ts`: 5 / 5 passed
+- `npx tsc --noEmit`: 0 errors
+- `npm test --reporter=dot`: **480 / 481 passed**（唯一失败为 pre-existing `linkEventToTask`，spec 第 5 项明确豁免）
+
+## 顺手发现的额外 as any（如有）
+无新增。`src/web/routes/sessions.ts:188-190` 的 `tool_input as any` 同步消除；`tool_output as any` 保留 1 处（`?.error` 防御访问，超出本 spec 范围）。
+
+## 已知问题
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` 失败：pre-existing，spec 已豁免；根因是测试构造的 event_id 不是 UUID，与本次 M3 schema 收紧无关（写入端 `writeEvent` 早已校验 UUID）。
+- `tests/unit/web/routes-tasks.test.ts` 在全量并行跑时偶发首例 404（B 路径下 `getStorage()` 状态同步问题），单独跑 21/21 全过；非本次回归。
+
+## 设计要点
+- `ToolInputFields` 加 `[key: string]: unknown` 索引签名：兼顾 forward-compat 与窄化收益（spec 风险 1 已确认接受）。
+- M3 让 hook 端可选自带 `event_id`：未带时 parser 兜底 `randomUUID()`，与 queue / storage 层 `event.event_id ?? randomUUID()` 形成端到端去重链路（hook 端真正生成 event_id 是后续 follow-up）。
+- `anti-pattern-detector.ts` 走保守路径：保留 `extractFilePath` / `extractBashCommand` 私有签名，只调整参数类型为 `ForgeEvent['tool_input']`，调用方零改动。