@winspan/claude-forge 8.51.1 → 8.54.3

package/docs/design/tasks-list-filter-pagination-spec-20260518-0930.md

@@ -1,208 +0,0 @@
-# Tasks 列表筛选 + 分页 — 设计 Spec
-
-**日期**: 2026-05-18
-**状态**: Draft（待用户 review）
-
----
-
-## 工作流路径
-
-**hybrid-feature-with-safety**
-
-**理由**：`src/web/routes/` 有 19 个路由文件，`tests/unit/web/` 仅 6 个测试文件，覆盖率约 **32%**（低于 50% 阈值）。实现阶段每个后端改动文件均需配套新增/扩展测试用例。前端为单 HTML 文件无组件测试，route + storage 层必须达到 80% 分支覆盖。
-
----
-
-## 1. 目标 + 成功标准
-
-让 `GET /api/tasks` 支持完整服务端筛选与分页；前端 tasks 视图新增筛选栏 + 分页组件，URL 同步状态。
-
-### 验收用例
-
-| # | 场景 | 期望 |
-|---|------|------|
-| A1 | `GET /api/tasks?limit=10&offset=0` | `{ items: [...10], total, has_more }` |
-| A2 | `GET /api/tasks?project=/path/foo` | 仅返回该 project_path 的 tasks |
-| A3 | `?project=a&project=b` | 两个项目 OR 关系 |
-| A4 | `?from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z` | start_time 范围过滤 |
-| A5 | `?search=重构` | title LIKE `%重构%` |
-| A6 | `?limit=201` | clamp 到 200 |
-| A7 | 前端选「24h」+ 搜索「build」 | URL: `?range=24h&search=build&page=1`，刷新保留 |
-| A8 | 点「下一页」 | offset 递增，total 不变 |
-
-**非目标**：FTS5 全文检索、status 多选、修改 `/api/tasks/:taskId` 详情接口。
-
----
-
-## 2. 后端设计
-
-### 2.1 Route 层 `src/web/routes/tasks.ts`
-
-**已有**：`limit`（默认 20）、`session`
-**待加**：`offset`、`project`（多值）、`from`、`to`、`search`，返回结构升级
-
-```
-QueryParams (Zod):
-  limit:   number, default 50, max 200, min 1
-  offset:  number, default 0, min 0
-  project: string | string[]    // 多值
-  from/to: ISO 8601 string, optional
-  search:  string, optional, maxLength 100
-  session: string, optional     // 保留
-```
-
-返回从 `Task[]` 升级为 `{ items, total, has_more }`。**破坏性变更**：内部 dashboard 无外部消费者，可接受。
-
-### 2.2 Storage 层 `src/core/storage/tasks.ts`
-
-**关键挑战**：`tasks` 表无 `project_path` 字段，需 JOIN `sessions` 表。
-
-```sql
--- 数据查询
-SELECT t.*, s.project_path
-FROM tasks t
-JOIN sessions s ON t.session_id = s.session_id
-WHERE
-  [t.session_id = ?]
-  [AND s.project_path IN (?, ?)]
-  [AND t.start_time >= ?]
-  [AND t.start_time <= ?]
-  [AND t.title LIKE ?]
-ORDER BY t.start_time DESC
-LIMIT ? OFFSET ?;
-
--- 总数查询：复用相同 WHERE，不带 LIMIT/OFFSET
-SELECT COUNT(*) FROM tasks t JOIN sessions s ON t.session_id = s.session_id WHERE [...];
-```
-
-`TaskRecord` 新增可选字段 `project_path?: string`。
-
-### 2.3 索引评估
-
-| 查询 | 现有 | 是否够 |
-|------|------|--------|
-| `ORDER BY start_time DESC` | `idx_tasks_start_time` | ✅ |
-| `WHERE session_id = ?` | `idx_tasks_session` | ✅ |
-| `WHERE s.project_path IN (...)` | `idx_sessions_project` | ✅ |
-| `WHERE t.title LIKE '%xxx%'` | 无 | ❌ 全表扫描，但数据量 <10k，可接受 |
-| `WHERE start_time BETWEEN ?` | `idx_tasks_start_time` | ✅ 范围扫描 |
-
-**新增**：`CREATE INDEX idx_tasks_start_time_session ON tasks(start_time DESC, session_id)`。
-**不引入 FTS5**（复杂度不值）。
-
-### 2.4 新 Endpoint `GET /api/tasks/projects`
-
-前端项目下拉需要"所有项目"列表：
-
-```sql
-SELECT DISTINCT s.project_path FROM sessions s JOIN tasks t ON t.session_id = s.session_id;
-```
-
----
-
-## 3. 前端设计
-
-### ⚠️ 重要发现
-
-调研显示前端是**原生 HTML + Vanilla JS**（`src/web/static/index.html` 单文件），不是 CLAUDE.md 描述的 React/Vite。当前页面切换通过 `nav(pageName)` + `id="page-xxx"` div 控制。
-
-> **请用户确认**：(a) spec 按 Vanilla JS 实施（与现状一致）；(b) 顺手迁移到 React（额外大改）；(c) CLAUDE.md 该改技术栈描述
-
-### 3.2 新增 `#page-tasks` 视图
-
-Sidebar 加 "Tasks" 导航项。
-
-```
-page-tasks
-├── .toolbar
-│   ├── #tasks-project-filter   (多选 select)
-│   ├── #tasks-range-filter     (1h/24h/7d/自定义)
-│   ├── #tasks-date-from/to     (datetime-local，自定义时显示)
-│   └── #tasks-search           (300ms 防抖)
-├── <table id="tasks-table">    时间 / 标题 / 项目 / 状态 / 事件数
-└── .pagination-bar
-    ├── "共 N 条，第 X-Y"
-    ├── 每页 [20/50/100]
-    └── [上一页] [下一页]
-```
-
-### 3.3 URL 状态同步
-
-`URLSearchParams` + `history.pushState`：
-
-| URL | 控件 |
-|-----|------|
-| `project` | 多选下拉（可重复） |
-| `range` | 1h/24h/7d/custom |
-| `from`/`to` | 自定义时间 |
-| `search` | 搜索框 |
-| `page` | offset = (page-1) * limit |
-| `size` | 20/50/100 |
-
-### 3.4 防抖
-
-搜索框 `oninput` → setTimeout 300ms → `loadTasks()`，每次键入重置。
-
----
-
-## 4. 改动文件清单
-
-| 文件 | 改动 | 行数 |
-|------|------|------|
-| `src/core/storage/tasks.ts` | 扩展 filter + COUNT + project_path | +40 |
-| `src/core/storage/schema.sql` | 加复合索引 | +2 |
-| `src/web/routes/tasks.ts` | Zod 解析 + 多参数 + 返回结构 + `/projects` 子路由 | +50 |
-| `src/web/static/index.html` | `#page-tasks` 视图 + JS 函数 + URL 同步 + 防抖 | +200 |
-| `tests/unit/web/routes-tasks.test.ts` | 扩展参数组合用例 | +80 |
-
----
-
-## 5. 风险点
-
-| 风险 | 缓解 |
-|------|------|
-| tasks 无 project_path，需 JOIN sessions | `TaskRecord` 加可选 `project_path?` |
-| 项目下拉数据来源 | 新增 `/api/tasks/projects` |
-| project_path 太长（绝对路径） | 截断显示最后 2 段，title 属性放完整 |
-| 返回结构破坏性变更 | 搜 index.html 所有 `/api/tasks` 调用点同步更新 |
-| LIKE 性能 | <10k 行可接受，不引入 FTS5 |
-| 前端无组件测试 | 仅 route 集成测试，前端 E2E 手工 |
-
----
-
-## 6. 测试策略
-
-### 单元测试 `tests/unit/web/routes-tasks.test.ts`
-
-- `project` 单值/多值（OR）
-- `from`/`to` 边界
-- `search` LIKE 匹配（SQLite ASCII 不区分大小写）
-- `limit` clamp
-- `offset` 分页 + `has_more` 准确
-- 返回结构 schema
-- `GET /api/tasks/projects` 去重
-
-### 集成测试
-
-新建 `tests/integration/tasks-filter.test.ts`，真实 SQLite 验证 JOIN + COUNT。
-
-### 前端 E2E
-
-按 A1-A8 在 dashboard 手工验证 + 截图。
-
----
-
-## 7. 执行步骤（自底向上）
-
-1. `schema.sql` — 加索引 `idx_tasks_start_time_session`
-2. `storage/tasks.ts` — 扩 filter / JOIN / COUNT / project_path
-3. Storage 单元测试
-4. `routes/tasks.ts` — Zod + 多参数 + 返回结构 + `/projects`
-5. Route 单元测试
-6. `index.html` — `#page-tasks` 视图 + JS + URL 同步 + 防抖
-7. `npm test` + `npx tsc --noEmit`
-8. 按 A1-A8 手工验收
-
----
-
-**Hybrid-feature-with-safety 工作流**：先 safety-net（扩展 routes-tasks 现有测试，锁定旧 `Task[]` 返回行为）→ design → implement → test → review

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 拒收）