@winspan/claude-forge 8.53.2 → 8.54.3

package/docs/implementation/fix-skills-data-and-set-leak-changelog-20260516-1300.md

@@ -1,104 +0,0 @@
-# Changelog: Official Skills 数据分离 + UserPromptHandler Set 内存泄漏修复
-
-**日期**: 2026-05-16
-**Spec**: `docs/design/fix-skills-data-and-set-leak-spec-20260516-1300.md`
-
----
-
-## 实际改动文件清单
-
-### 新建文件
-
-| 文件路径 | 行数 | 说明 |
-|----------|------|------|
-| `src/skills/official/official-harness-engineering.md` | 91 | Harness Engineering 方法论 |
-| `src/skills/official/official-spec-driven-design.md` | 28 | Spec-Driven Design |
-| `src/skills/official/official-architecture-decision.md` | 22 | ADR 模板（截断版，与原始 content 一致）|
-| `src/skills/official/official-api-design.md` | 19 | API 设计规范（截断版）|
-| `src/skills/official/official-db-schema-design.md` | 19 | DB Schema 设计（截断版）|
-| `src/skills/official/official-pr-review.md` | 32 | PR 审查清单（截断版）|
-| `src/skills/official/official-debug.md` | 18 | 调试工作流（截断版）|
-| `src/skills/official/official-performance-optimization.md` | 30 | 性能优化 |
-| `src/skills/official/official-security-hardening.md` | 27 | 安全加固（截断版）|
-| `src/skills/official/official-release-checklist.md` | 30 | 发布清单 |
-| `src/skills/official/official-doc-driven.md` | 28 | 文档驱动开发 |
-| `src/skills/official/planning-with-files.md` | 35 | Manus 风格任务规划（截断版）|
-| `src/skills/official/code-simplifier.md` | 17 | 代码简化（截断版）|
-| `src/skills/official/find-skills.md` | 24 | 技能发现（截断版）|
-| `src/skills/official/webapp-testing.md` | 12 | Web 应用测试（截断版）|
-| `src/skills/official/ui-ux-pro-max.md` | 19 | UI/UX 设计工具（截断版）|
-| `src/skills/official/official-bmad.md` | 90 | BMAD 方法论 |
-| `tests/unit/skills/official-skills-loader.test.ts` | 113 | loadOfficialSkills 单元测试（7 个 case）|
-
-### 修改文件
-
-| 文件路径 | 改动 | 说明 |
-|----------|------|------|
-| `src/skills/official-skills.ts` | -700行 +73行 | 删除 OFFICIAL_SKILLS 数组；保留 OfficialSkill 接口和 OFFICIAL_SKILL_KEYWORDS；新增 loadOfficialSkills(builtinDir) |
-| `src/skills/registry.ts` | +30行 | 新增 resolveBuiltinDir(); scan() 第 1 段改用 loadOfficialSkills; import 更新 |
-| `src/cli/commands/skills.ts` | +7行 | 移除 OFFICIAL_SKILLS import；新增 resolveBuiltinDir(); syncSkills 改用 loadOfficialSkills |
-| `src/daemon/handlers/user-prompt.ts` | +40行 | Set 改 Map<string,number>; 新增 MAX_INJECTION_KEYS=1000; hasInjected/markInjected 私有方法; clearSession 公共方法 |
-| `src/daemon/handlers/stop.ts` | +15行 | import UserPromptHandler 类型; 构造函数增加可选参数 userPromptHandler; Step 5 调用 clearSession |
-| `src/daemon/index.ts` | +5行 | 将 userPromptHandler 实例传入 StopHandler 构造函数 |
-| `package.json` | +1行 | build 脚本追加 `mkdir -p dist/skills/official && cp src/skills/official/*.md dist/skills/official/` |
-| `tests/unit/skill-registry.test.ts` | +2行 | 断言数量从 >= 16 改为 >= 17（两处） |
-| `tests/unit/handlers.test.ts` | +92行 | 新增 3 个 UserPromptHandler 测试 case |
-
----
-
-## 与 Spec 的偏差
-
-### 偏差 1：Skill 数量是 17，不是 19
-Spec 说"共 19 个 skill"，但 `OFFICIAL_SKILLS` 数组实际只有 17 个条目（缺少 `official-tdd` 和 `official-refactor`，这两个仅在 `OFFICIAL_SKILL_KEYWORDS` 中有 keyword 映射但没有对应的 skill 定义）。实际创建了 17 个 `.md` 文件。测试断言改为 `>= 17`。
-
-### 偏差 2：部分 skill 内容截断
-原始 `OFFICIAL_SKILLS` 数组中有 11 个 skill 的 `content` 字段以 `\`` 结尾（截断的 template literal）。这是源码的现有状态（非本次引入）。`.md` 文件完整保留了这些截断内容，与原有行为一致。这些截断是原始数据的一部分，不影响 skill 加载逻辑。
-
-### 偏差 3：registry.ts 中 skill 的 path 字段构造
-Spec 建议使用 `resolveBuiltinDir() + '/' + officialSkill.name + '.md'` 作为路径。实际实现中每次调用 `resolveBuiltinDir()` 会重新计算，考虑到这是纯计算无副作用，对性能无影响。若有性能顾虑可缓存该值（已注释在代码中作为 TODO）。
-
-### 偏差 4：loadOfficialSkills content 字段包含完整文件（含 frontmatter）
-Spec 中未明确 `content` 字段是否包含 frontmatter。registry 的现有用户 skill 逻辑（`body.trim()`）只包含 body。为保持与原有 OFFICIAL_SKILLS 行为一致（原 content 字段包含 frontmatter），`loadOfficialSkills` 返回的 `content` 字段设为完整文件内容（`raw`），而非仅 body。这样 skill 注入时内容与之前完全一致。
-
----
-
-## 测试结果
-
-### 执行的测试
-```
-npx vitest run tests/unit/skill-registry.test.ts --reporter=verbose
-npx vitest run tests/unit/skills/ --reporter=verbose
-npx vitest run tests/unit/handlers.test.ts --reporter=verbose
-npx tsc --noEmit
-npm test -- --reporter=dot
-```
-
-### 结果汇总
-
-| 测试文件 | 状态 | 测试数 |
-|----------|------|--------|
-| `tests/unit/skill-registry.test.ts` | 全部通过 | 6/6 |
-| `tests/unit/skills/registry-multiformat.test.ts` | 全部通过 | 27/27 |
-| `tests/unit/skills/official-skills-loader.test.ts` | 全部通过 | 7/7 |
-| `tests/unit/handlers.test.ts` | 全部通过 | 7/7（新增 3 个）|
-| `tests/unit/skills/invocation-guard-ttl.test.ts` | 全部通过 | — |
-| TypeScript (`tsc --noEmit`) | 无错误 | — |
-| 全量测试 (`npm test`) | 291/294 通过 | 2 文件失败 |
-
-### 预存在的失败（与本次改动无关）
-- `tests/unit/web/routes-tasks.test.ts`（2 个 case 失败）：UUID 格式验证错误，与 storage 层有关
-- `tests/unit/storage/sqlite-refactor-harness.test.ts`（1 个 case 失败）：`linkEventToTask` 相关，与 storage 层有关
-
-注：这两个测试文件在本次改动前就已失败（baseline 状态：3 文件 / 10 个 case 失败；本次改动后：2 文件 / 3 个 case 失败，即我们的改动无意中修复了 skill-registry 相关的计数断言问题）。
-
----
-
-## 已知风险 / TODO
-
-1. **content 字段含 frontmatter**：registry 的用户 skill 加载使用 `body.trim()`（不含 frontmatter），而 official skill 的 `content` 现在是完整文件内容（含 frontmatter）。两者行为不一致，但与原始 OFFICIAL_SKILLS 数组保持了向后兼容。如需统一，可在后续 PR 中对齐。
-
-2. **部分 skill 内容截断**：11 个 skill 的 body 内容被截断（原始代码如此）。这不是本次引入的问题。如需完整内容，需要重新补全对应的 `.md` 文件。
-
-3. **syncSkills 命令的 version 比较**：`skills sync` 命令从 `.md` frontmatter 读取版本号做比较。对于截断的 skill，version 字段在 frontmatter 中完整保留，此功能不受影响。
-
-4. **resolveBuiltinDir 每次重新计算**：scan() 中多次调用 resolveBuiltinDir()，可以在 scan 开始时缓存到局部变量（低优先级优化）。

package/docs/implementation/h1-storage-aggregation-changelog-20260518-1121.md

@@ -1,82 +0,0 @@
-# H1 实施 Changelog
-
-**Date**: 2026-05-18 11:21
-**Spec**: `docs/design/h1-storage-aggregation-spec-20260518-1121.md`
-**Status**: 完成
-
-## 完成清单
-
-- [x] Storage 新方法（7 个）：
-  - `aggregateRoutingStats({ since_ts, project_path? })` → `RoutingOperations`
-  - `aggregateRoutingTrendByDay({ since_ts })` → `RoutingOperations`
-  - `aggregateSkillInvocationsBySkill({ since, limit? })` → `SkillOperations`
-  - `getTask(taskId)` → `TaskOperations`
-  - `queryEventsByTaskId(taskId, opts?)` → `TaskOperations`
-  - `queryInjectionsByTaskId(taskId)` → `TaskOperations`
-  - `querySkillInvocationsByTaskWindow(taskId, now_ms?)` → `TaskOperations`
-- [x] sqlite.ts facade 转发已加（7 个方法）
-- [x] 索引新增：`idx_routing_events_type_ts` (schema.sql + base.ts runMigrations 同步)
-- [x] Storage 单元测试（3 文件）：
-  - `tests/unit/storage/routing-aggregates.test.ts`
-  - `tests/unit/storage/skills-aggregates.test.ts`
-  - `tests/unit/storage/tasks-getById-aggregates.test.ts`
-- [x] Routes 改造（3 文件）：
-  - `src/web/routes/rules.ts` — hit-rate 改用 `aggregateRoutingStats` + `aggregateSkillInvocationsBySkill`
-  - `src/web/routes/skill-stats.ts` — 5 个 endpoint 全部下沉到 SQL 聚合
-  - `src/web/routes/tasks.ts` — `/:taskId` PK 直查 + JOIN
-- [x] 路由测试新增：`tests/unit/web/routes-rules.test.ts`（之前缺口）
-
-## 关键代码定位
-
-### Storage 新方法
-- `src/core/storage/routing.ts` — `aggregateRoutingStats`、`aggregateRoutingTrendByDay`（4 条独立 prepared statement 走索引；trend 用 `strftime('%Y-%m-%d', ts/1000, 'unixepoch')`）
-- `src/core/storage/skills.ts` — `aggregateSkillInvocationsBySkill`（按 `total DESC`）
-- `src/core/storage/tasks.ts` — `getTask` / `queryEventsByTaskId` / `queryInjectionsByTaskId` / `querySkillInvocationsByTaskWindow`（后者用 `task_events` JOIN + `tasks.start_time/end_time` 转 ms 做窗口过滤）
-- `src/core/storage/sqlite.ts` — facade 转发 7 个方法
-- `src/core/storage/schema.sql` 末尾 + `src/core/storage/base.ts` runMigrations — `idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC)`
-
-### Route 改造点
-- `src/web/routes/rules.ts` — `queryRoutingEvents{limit:100000}` + `querySkillInvocations{limit:100000}` JS reduce → `aggregateRoutingStats` + `aggregateSkillInvocationsBySkill`
-- `src/web/routes/skill-stats.ts:16` — `/distribution`：`agg.by_type` + 三桶兜底
-- `src/web/routes/skill-stats.ts:33` — `/frequency`：`agg.by_skill_routed.map(...)`
-- `src/web/routes/skill-stats.ts:43` — `/trend`：`aggregateRoutingTrendByDay` + JS skillRate 计算
-- `src/web/routes/skill-stats.ts:59` — `/invocations`：`aggregateSkillInvocationsBySkill`，`total` 改为 sum 行 total
-- `src/web/routes/skill-stats.ts:76` — `/api/routing/stats`：`agg.obeyed/total/by_agent`
-- `src/web/routes/tasks.ts:59` — `/:taskId`：`getTask` + `queryEventsByTaskId` + `queryInjectionsByTaskId` + `querySkillInvocationsByTaskWindow` 取代旧四段全表扫
-
-## 测试结果
-
-| 维度 | 数值 |
-|------|------|
-| storage + web unit | 171 通过 / 1 失败（pre-existing） |
-| 全量 `npm test` | **417 通过 / 1 失败 / 418 总** |
-| `npx tsc --noEmit` | **0 errors** |
-
-### Pre-existing failure（与 H1 无关，main 分支既有）
-- `tests/unit/storage/sqlite-refactor-harness.test.ts > Task Operations > linkEventToTask associates events with tasks`
-  - 报错：`Invalid event data: ... event_id Invalid uuid`
-  - 原因：测试中传入的 `event_id` 不是 UUID 格式，与 `events.ts:73` 的 zod 校验不兼容
-  - 在 main 分支同样 fail，**未在本次任务范围**，未修
-
-## 超出 spec 的改动
-
-无。所有改动均严格按 spec 第 3 节执行。响应字段结构未变更（前端 React 组件契约保持）：
-- `/distribution` → `{ windowHours, distribution: [{type, count}] }` ✓
-- `/frequency` → `{ windowHours, frequency: [{name, count}] }` ✓
-- `/trend` → `{ windowHours, trend: [{day, skillRate}] }` ✓
-- `/invocations` → `{ days, total, invocations: [{skill_id, total, success, failed}] }` ✓
-- `/api/routing/stats` → `{ days, total, agentCalls, noAgent, agentRate, byAgent }` ✓
-- `/api/tasks/:taskId` → `{ task, userPrompts, injections, timeline, skillInvocations, artifacts }` ✓
-
-注：`/invocations` 的 `total` 字段语义不变（旧实现是 `invocations.length` = 原始记录数；新实现是 `sum(rows.total)` = 同样的原始记录数，因 GROUP BY skill_id 后各 group total 之和等于总行数）。
-
-## 已知问题
-
-- **Pre-existing**：`sqlite-refactor-harness.test.ts > linkEventToTask` — 与 H1 无关，main 分支同样失败。
-- 无其它已知问题。
-
-## 回滚提示
-
-纯增量改动。如需回滚：
-- revert `src/web/routes/{rules,skill-stats,tasks}.ts` 即可恢复旧行为
-- storage 新方法和索引保留无害（无人调用即无副作用）

package/docs/implementation/h2-final-changelog-20260518-1530.md

@@ -1,61 +0,0 @@
-# H2 完整实施 Changelog
-
-**Date**: 2026-05-18
-**Spec**: `docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md`
-**Status**: 全 4 Phase 完成
-**Workflow**: refactor-safe（safety-net → 新方法 → 替换 → 收尾）
-
-## 四阶段 commit 索引
-
-| Phase | Commit | 内容 |
-|---|---|---|
-| 1 | `0b494ed` | safety-net 17 test cases（web-stats / web-trace / stop-handler / web-analytics 增强） |
-| 2 | （上一 commit） | 20 个 Operations 新方法 + 44 个单测 + facade 转发 |
-| 3 | `bf3eb39` | 7 个调用方文件替换 db.prepare() → facade |
-| 4 | （本 commit） | getDatabase jsdoc 警告 + 总 changelog |
-
-## 累计影响
-
-- **改动 13 个 src 文件，新增 12 个测试文件**
-- **消除 27 处越权 SQL 直写**（spec 调研时 25 处 + 主线程封闭性扫描补 cli/commands/trace.ts 3 处）
-- **新增 20 个 Operations 方法**：EventOperations × 11 + SessionOperations × 4 + TaskOperations × 1 + SkillOperations × 4
-- **新增 61 个测试用例**：safety-net 17 + Operations 单测 44
-
-## 命名固化（H1 → H2 一致）
-
-- `aggregate*` 聚合（GROUP BY 类）
-- `count*` 计数
-- `query*` 列表查询
-- `get*` 单条查询
-
-## 关键决策
-
-1. **getDatabase 保留 public**（不改 protected）：架构非继承关系，protected 收益小风险大；改用 jsdoc `@internal` 标注 + CLAUDE.md 工作流提醒
-2. **SQL 行为零变更**：所有 SQL 直接搬入 Operations，不做"优化"，保证 safety-net 测试零回归
-3. **`LIKE '%error%'` 失败检测保留原 3 个 OR 条件**：与生产匹配
-4. **Phase 2 偏差**：`aggregateToolUsage` 缺 `until` 参数 → Phase 3 改用 `queryEventsByTimeRange + 内存聚合` 兜底，保留 `[since, until)` 语义
-
-## 测试结果（最终）
-
-- safety-net 集成测试：17/17 ✓
-- Operations 单测：44/44 ✓
-- 现有回归：541/542 通过
-- **唯一失败**：pre-existing `linkEventToTask` (Zod UUID 校验，与 H2 无关)
-- `npx tsc --noEmit`: 0 errors
-
-## 残留 `db.prepare` 检查
-
-```bash
-$ grep -rn "db\.prepare" src/web/ 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 处均为注释**，无 SQL 直写。
-
-## 后续 follow-up
-
-- **可选**：补完 `aggregateToolUsage` 的 `until` 参数支持，weekly-report 改回单条 SQL
-- **可选**：ESLint 规则禁止 `web/routes/` `web/analytics/` `daemon/handlers/` import storage 后调用 `getDatabase()`
-- **不建议**：把 `getDatabase` 改 protected（架构非继承）

package/docs/implementation/h2-phase1-safety-net-changelog-20260518-1450.md

@@ -1,70 +0,0 @@
-# H2 Phase 1 safety-net Changelog
-
-**Date**: 2026-05-18 14:50
-**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
-**Status**: Phase 1 完成（Phase 2-4 待后续）
-
-## 完成清单
-
-- [x] web-stats 集成测试 (`tests/integration/web-stats.integration.test.ts`, 4 cases)
-- [x] web-trace 集成测试 (`tests/integration/web-trace.integration.test.ts`, 6 cases — 全分支覆盖)
-- [x] stop-handler-behavior-summary 单测 (`tests/unit/daemon/stop-handler-behavior-summary.test.ts`, 5 cases)
-- [x] web-analytics 集成测试增强 (+2 value-level cases)
-
-## 关键代码定位
-
-| 测试文件 | 行号 | 内容 |
-|---|---|---|
-| `tests/integration/web-stats.integration.test.ts:38` | empty database 200 shape |
-| `tests/integration/web-stats.integration.test.ts:60` | totalEvents/totalSessions/toolUsage 聚合 |
-| `tests/integration/web-stats.integration.test.ts:83` | dailyActivity 字段形状 |
-| `tests/integration/web-stats.integration.test.ts:103` | skillInvocations 计数 |
-| `tests/integration/web-trace.integration.test.ts:84-118` | 4 个 4xx 错误分支 |
-| `tests/integration/web-trace.integration.test.ts:120-130` | 200 + 空 sessions[]（无 git note）|
-| `tests/integration/web-trace.integration.test.ts:132-167` | 200 + 完整 session 详情（含 event_breakdown）|
-| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:69` | 无事件时不附加 summary |
-| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:82` | tool-only summary |
-| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:110` | Agent 委托计数 + agent 名 |
-| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:141` | skill 调用计数 |
-| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:169` | session 隔离（不串扰）|
-| `tests/integration/web-analytics.integration.test.ts:92` | weekly report value 断言 |
-| `tests/integration/web-analytics.integration.test.ts:107` | insights summary.total = patterns.length |
-
-## 测试结果
-
-- **新增/增强 safety-net 测试**: 17 passed (4 stats + 6 trace + 5 stop + 2 analytics 增强)
-- **跨 Phase 1 范围全量**:
-  - `tests/integration/` + `tests/unit/daemon/`: 33 / 33 passed
-- **tsc**: 0 errors
-- **npm test 全量**: 497 / 498 passed (1 failed = pre-existing `linkEventToTask`)
-
-## 实施决策
-
-1. **trace 测试覆盖方案**：采用方案 A（tmp git repo）。在 `os.tmpdir()` 用 `execFileSync('git', ...)` 创建真实仓库 + 两次 commit + `git notes add`，覆盖：
-   - 缺 `?project` query → 400
-   - 相对路径 → 400
-   - 非 git 目录 → 400
-   - commit 不存在 → 404
-   - HEAD 有 commit 但无 note → 200 + 空 sessions[]
-   - 有 forge-session note + storage 有对应 events → 200 + 完整 session 详情（event_breakdown 等）
-   - **覆盖度高于 spec 最低要求**（spec 只要求 commit 不存在 4xx + 无 note 空 sessions 两条），实际跑得快且稳定。
-2. **stop-handler 测试路径调整**：spec 写 `src/tests/stop-handler-behavior-summary.test.ts`，但 `vitest.config.ts` 只包含 `tests/unit/**` 与 `tests/integration/**`。如放到 `src/tests/` 会被 collect 排除导致永远不跑。改放到 `tests/unit/daemon/stop-handler-behavior-summary.test.ts` 以确保实际生效，已在测试文件顶部 NOTE 注释中说明决策。
-3. **`generateBehaviorSummary` 私有方法访问**：经由 `handle()` 入口 + mock `ResumeManager.save` 捕获最终 resume content 进行断言。比反射访问私有方法更接近生产实际路径，且更稳健。
-4. **web-analytics 增强保守原则**：只加 2 个新 case（weekly value + insights consistency），不重写既有 shape 断言。所有原 case 仍保留并通过。
-5. **fixture 时间戳策略**：weekly-report 按 ISO week 范围过滤事件，所以 fixture 用 `new Date().toISOString()`（当下时间）确保进入 `weekOffset: 0` 窗口；stats endpoint 用 `date('now', '-7 days')`，同样满足。
-
-## 待 Phase 2 处理
-
-下一步 Phase 2（新增 ~20 个 Operations 方法）的提示：
-
-- Phase 2 应在 `src/core/storage/{events,sessions,tasks,skills}.ts` 加方法，**不删旧 SQL**，并行存在。
-- Phase 2 同时增加 4 个新单测文件：`tests/unit/storage/{event,session,skill}-operations-aggregates.test.ts`（spec 表 116 行所列）。
-- Phase 3 才会替换调用方（每文件 1 commit），届时本 Phase 1 的 safety-net 会兜底回归。
-- Phase 4 给 `getDatabase()` 加 jsdoc `@internal` 警告。
-- 改造涉及 `daemon/handlers/stop.ts` 时，本次新加的 `stop-handler-behavior-summary.test.ts` 5 个 case 是关键回归依据。
-- trace 测试包含一次真实 `git init`，单测耗时 ~600ms，未来 Phase 2/3 增加新测试时不必再做 git 操作。
-
-## 已知问题
-
-- **pre-existing 失败**：`SQLiteStorage - Characterization Tests (Pre-Refactor) > Task Operations > linkEventToTask associates events with tasks` —— Zod uuid 校验失败，与本 Phase 1 改动无关，按纪律不修。
-- **未覆盖**：`cli/commands/trace.ts` 3 段 SQL 暂无对应集成测试（spec 第 71 行已标注"可补"）。Phase 2/3 替换 CLI trace 时可考虑加 CLI smoke test，或先依赖 web-trace 同模式断言间接保护。

package/docs/implementation/h2-phase2-operations-changelog-20260518-1450.md

@@ -1,120 +0,0 @@
-# H2 Phase 2 Operations 新方法 Changelog
-
-**Date**: 2026-05-18 14:50 (Phase 2)
-**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
-**Status**: Phase 2 完成（Phase 3 待替换调用方）
-
-## 完成清单
-
-- [x] EventOperations 11 方法（events.ts）
-- [x] SessionOperations 4 方法（sessions.ts）
-- [x] TaskOperations 1 方法（tasks.ts）
-- [x] SkillOperations 4 方法（skills.ts）
-- [x] sqlite.ts facade 转发（20 个方法）
-- [x] 4 文件单测（44 个 case 全过）
-- [x] tsc 通过 0 errors
-- [x] 旧 SQL 并行存在（Phase 3 才替换）
-
-## 新增方法清单
-
-### EventOperations（src/core/storage/events.ts:179-358）
-
-| 方法 | SQL 来源 |
-|---|---|
-| `countAllEvents()` | stats.ts:13 |
-| `aggregateToolUsage({ since?, limit?, hook_type? })` | stats.ts:17-21 + weekly-report.ts:214-222 |
-| `aggregateDailyEventCounts({ since, until? })` | stats.ts:28-33 |
-| `aggregateHookTypeBySession(session_id)` | trace.ts:106-109 + cli/trace.ts:115 |
-| `aggregateAgentTypeBySession(session_id)` | trace.ts:111-116 + cli/trace.ts:124 + stop.ts:163-168 |
-| `aggregateToolUsageBySession(session_id)` | stop.ts:154-158 |
-| `countActiveDays({ since, until? })` | drift-detector.ts:154-157 |
-| `aggregateOverviewByRange({ since, until })` | weekly-report.ts:100-109 |
-| `queryDistinctProjects({ since, until })` | weekly-report.ts:111-116 |
-| `aggregateToolFailureRate({ since, until })` | weekly-report.ts:228-244（保留 3 OR LIKE 分支） |
-| `queryFileEditInputs({ since, until, tool_names })` | weekly-report.ts:261-268（内部 IN 展开） |
-| `queryEventsByTimeRange({ since, until? })` | anti-pattern-detector.ts:83-86 |
-
-### SessionOperations（src/core/storage/sessions.ts:107-178）
-
-| 方法 | SQL 来源 |
-|---|---|
-| `countAllSessions()` | stats.ts:14 |
-| `aggregateDailySessionCounts({ since, until? })` | stats.ts:35-40 |
-| `querySessionsByTimeRange({ since, until? })` | anti-pattern-detector.ts:104-114 |
-| `countSessionsByRange({ since, until? })` | drift-detector.ts:185-187 |
-
-### TaskOperations（src/core/storage/tasks.ts:120-131）
-
-| 方法 | SQL 来源 |
-|---|---|
-| `countTasksByRange({ since, until? })` | drift-detector.ts:190-192 + weekly-report.ts:118-122 |
-
-### SkillOperations（src/core/storage/skills.ts:203-232）
-
-| 方法 | SQL 来源 |
-|---|---|
-| `countAllSkillInvocations()` | stats.ts:50 |
-| `countSkillInvocationsBySession(session_id)` | stop.ts:176-178 |
-| `countDistinctSkillsSince(since_ms)` | drift-detector.ts:125-128 |
-| `queryDistinctSkillIdsBySession(session_id)` | trace.ts:118-120 + cli/trace.ts:135 |
-
-### sqlite.ts facade（src/core/storage/sqlite.ts:94-160）
-
-20 个方法签名严格按 spec，全部 `delegate to this.events / this.sessions / this.tasks / this.skills`。
-
-## 关键代码定位
-
-- `src/core/storage/events.ts:179-358` — EventOperations 11 新方法
-- `src/core/storage/sessions.ts:107-178` — SessionOperations 4 新方法
-- `src/core/storage/tasks.ts:120-131` — TaskOperations countTasksByRange
-- `src/core/storage/skills.ts:203-232` — SkillOperations 4 新方法
-- `src/core/storage/sqlite.ts:94-160` — facade 转发段
-
-## 测试结果
-
-- 新增单测: **44 passed / 44**
-  - event-operations-aggregates.test.ts: 23 tests
-  - session-operations-aggregates.test.ts: 9 tests
-  - task-operations-counts.test.ts: 3 tests
-  - skill-operations-counts.test.ts: 9 tests
-- 旧 storage 测试回归: 通过（除 pre-existing failure）
-- tsc: **0 errors**
-- npm test: **541 passed / 542**（仅 pre-existing `linkEventToTask` 失败）
-
-## 实施决策
-
-1. **LIKE '%error%' 失败检测保持原 SQL 三个 OR 分支**
-   - `tool_output LIKE '%"error"%' OR LIKE '%"is_error":true%' OR LIKE '%"isError":true%'`
-   - 测试覆盖三种 tool_output JSON 形态，确认全部命中
-
-2. **时间区间统一 `[since, until)` 半开半闭语义**
-   - 调用方负责 ISO 字符串构造（`new Date(since).toISOString()`）
-   - until 一律 `<`（与 weekly-report.ts 原 `start_time < ?` 一致）
-   - 与 stats.ts 原 `date('now', '-7 days')` 语义不同：新方法不再隐含 now()，调用方计算
-
-3. **`queryFileEditInputs` 内部展开 placeholders**
-   - tool_names 通过参数注入，避免外部拼 SQL
-   - 空 list 直接返回空数组（避免 `IN ()` SQL 错误）
-
-4. **`aggregateToolUsage` 合并 stats / weekly-report 两个用例**
-   - 通过 `hook_type` 可选过滤 + `since` 可选过滤兼顾两种调用
-   - `tool_name IS NOT NULL AND tool_name != ''` 始终生效（stats.ts 原行为）
-
-5. **`aggregateAgentTypeBySession` 与 `aggregateToolUsageBySession` 分离**
-   - 前者 `tool_name IN ('Agent','Task')` + json_extract subagent_type（stop.ts:163 / trace.ts:111）
-   - 后者纯 `tool_name IS NOT NULL`（stop.ts:154）
-   - 两段语义不同，分别封装
-
-## 待 Phase 3 处理
-
-- 替换 src/web/routes/stats.ts（5 段 SQL）
-- 替换 src/web/routes/trace.ts（3 段 SQL）
-- 替换 src/cli/commands/trace.ts（3 段 SQL）
-- 替换 src/daemon/handlers/stop.ts:154-178（3 段 SQL）
-- 替换 src/web/analytics/drift-detector.ts（4 段 SQL）
-- 替换 src/web/analytics/weekly-report.ts（6 段 SQL）
-- 替换 src/web/analytics/anti-pattern-detector.ts（2 段 SQL）
-
-## 已知问题
-
-- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` pre-existing 失败（与 Phase 2 改动无关，event_id 未传 UUID 导致 zod schema 拒收）

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

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

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

@@ -1,60 +0,0 @@
-# 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 没强制要求加，保持原状。