@winspan/claude-forge 8.53.2 → 8.54.3

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

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

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

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

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

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

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

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

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

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

@@ -1,43 +0,0 @@
-# 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']`，调用方零改动。