@winspan/claude-forge 8.53.2 → 8.54.4

package/docs/design/m2-m3-tool-input-spec-20260518-1425.md

@@ -1,131 +0,0 @@
-# M2 + M3: event tool_input 类型契约 Spec
-
-## 目标
-为 `ForgeEvent.tool_input` 建立可选字段类型契约消除 `as any` 泛滥；同时让 `event_id` 在 parser 层尊重外部传入，为 hook 端端到端去重铺路。
-
-## 调研结果
-
-### M2 使用统计（30 处含 `as any` 与 `as Record<string,unknown>`）
-
-| 工具 | 字段 | 使用点 |
-|---|---|---|
-| Bash | `command` | `web/routes/sessions.ts:95,97,223,225`; `anti-pattern-detector.ts:256,363`; `cli/commands/logs.ts:44`; `history-exporter.ts:103` |
-| Edit/Write | `file_path` | `sessions.ts:90,91,232,233`; `tasks.ts:161,163`; `anti-pattern-detector.ts:140,356`; `resume-manager.ts:118`; `cli/commands/logs.ts:45`; `weekly-report.ts:274` |
-| UserPromptSubmit fallback | `user_prompt` | `sessions.ts:82,83,159,164`; `tasks.ts:168,171`; `daemon/index.ts:161`; `storage/base.ts:253,257` |
-| Agent/Task | `subagent_type`, `name`, `prompt` | `web/routes/tasks.ts:125–129`; `daemon/handlers/post-tool-use.ts:29` |
-| Notebook | `notebook_path` | `weekly-report.ts:274` |
-
-### 使用模式
-**几乎全部是防御访问**：`(e.tool_input as any)?.command || ''`、`?.file_path`、`?? input?.command`。零处做 strict assert。
-真正窄化的两处（`post-tool-use.ts:29`、`web/routes/tasks.ts:111-131`）也是 `?` 容忍。
-
-### M3 event_id 流向
-- **Hook 端**：`pre-tool-use.sh`、`post-tool-use.sh` 等当前**不产生** `event_id`；payload 里无该字段。
-- **Queue 层**：`core/queue/index.ts:83` 已经写了 `event.event_id ?? randomUUID()`，文件名也依赖之。
-- **Storage 层**：`core/storage/events.ts:21` schema 已 `event_id: z.string().uuid().optional()`，`writeEvent` 也是 `event.event_id || randomUUID()`。**唯一断点**：`daemon/event-parser.ts:23` 无条件 `randomUUID()`，先于 storage，外部传入永远被覆盖。
-
-## 方案选择
-
-### M2：方案 B（lenient bag）+ 辅助 getter
-理由：
-1. 30+ 处使用全是 undefined-friendly，方案 A 需要给每个站点加 type guard，改动大且收益低（hook event 名不等于 tool 名，`Edit`/`Write`/`Bash` 都来自 `event.tool_name`，不是 `hook_type` discriminator）。
-2. Claude Code 的 tool 集合是开放的（未来还可能新增），union 难以穷举；bag + index signature 兼容前向。
-3. 已有 `anti-pattern-detector.ts:354-365` 的 `extractFilePath`/`extractBashCommand` 范式，扩展即可。
-
-### M3：保留 `event_id` 可选透传
-`event-parser.ts` 改为 `event_id: validated.event_id ?? randomUUID()`，schema 加 `event_id: z.string().uuid().optional()`。**不强制 hook 端立即生成**。
-
-## 类型设计
-
-```ts
-// core/types.ts 追加
-export interface ToolInputFields {
-  // Bash
-  command?: string;
-  description?: string;
-  // Edit / Write / Read / NotebookEdit
-  file_path?: string;
-  notebook_path?: string;
-  old_string?: string;
-  new_string?: string;
-  content?: string;
-  // Agent / Task
-  subagent_type?: string;
-  name?: string;
-  prompt?: string;
-  // UserPromptSubmit fallback envelope
-  user_prompt?: string;
-  // 兼容未来未知字段
-  [key: string]: unknown;
-}
-
-export interface ForgeEvent {
-  // ...
-  tool_input?: ToolInputFields;
-  tool_output?: Record<string, unknown>;
-  event_id?: string;
-}
-
-// helpers（放 core/event-fields.ts）
-export function getCommand(e: ForgeEvent): string | undefined {
-  const c = e.tool_input?.command;
-  return typeof c === 'string' ? c : undefined;
-}
-export function getFilePath(e: ForgeEvent): string | undefined {
-  const fp = e.tool_input?.file_path ?? e.tool_input?.notebook_path;
-  return typeof fp === 'string' && fp.length > 0 ? fp : undefined;
-}
-export function getUserPrompt(e: ForgeEvent): string | undefined {
-  return e.user_prompt ?? (typeof e.tool_input?.user_prompt === 'string' ? e.tool_input.user_prompt : undefined);
-}
-export function getSubagentType(e: ForgeEvent): string | undefined {
-  const s = e.tool_input?.subagent_type;
-  return typeof s === 'string' ? s : undefined;
-}
-```
-
-## 改造范围
-
-| 文件 | 改动点 | 行数 |
-|---|---|---|
-| `src/core/types.ts` | 加 `ToolInputFields`；改 `ForgeEvent.tool_input` 类型 | +25 |
-| `src/core/event-fields.ts`（新建）| 4 个 getter | +30 |
-| `src/daemon/event-parser.ts` | schema 加 `event_id.optional()`；`event_id ?? randomUUID()`；`tool_input as ToolInputFields` | ~4 |
-| `src/daemon/index.ts:161` | 改 `getUserPrompt(event)` | 1 |
-| `src/web/routes/sessions.ts` | 8 处 `(tool_input as any)?.X` → getter | ~10 |
-| `src/web/routes/tasks.ts` | 5 处 | ~6 |
-| `src/cli/commands/logs.ts:42-46` | 直接用 `e.tool_input?.command` 等 | 4 |
-| `src/web/analytics/anti-pattern-detector.ts` | `extractFilePath/Command` 内联或调 getter | 2 |
-| `src/daemon/handlers/post-tool-use.ts:29` | `getSubagentType(event)` | 1 |
-| `src/daemon/handlers/history-exporter.ts:102-103` | 直接 `.file_path / .command` | 2 |
-| `src/claudemd/resume-manager.ts:118` | 已经接近规范，去 `as string` | 1 |
-| `src/core/storage/events.ts` | `tool_input` 反序列化 cast 调整 | 1 |
-| `src/core/storage/tasks.ts:233` | 同上 | 1 |
-| `src/core/storage/base.ts:253,257` | SQL 不变（已用 json_extract）；无代码改动 | 0 |
-
-## 测试策略
-- **新增** `src/tests/event-fields.test.ts`：4 个 getter × {undefined, wrong type, valid} 共约 12 case。
-- **新增** `src/tests/event-parser.test.ts`：
-  - 无 `event_id` → 自动生成 UUID
-  - 传入 `event_id` (合法 UUID) → 透传
-  - `tool_input` 含 `command/file_path` → 落到 `ToolInputFields`
-- **回归**：`src/tests/events.test.ts`（若存在）补一条 `writeEvent` + parser 端到端 event_id 透传 + 重放 UNIQUE 拒收。
-- **集成**：现有 `tests/integration/*` 跑完无回归。
-
-## 风险与回滚
-- **风险 1**：`ToolInputFields` 加 `[key:string]: unknown` 等于半放弃严格性 — 接受，因为目标是消 `as any` 与统一访问入口，而非全量窄化。
-- **风险 2**：M3 让外部 event_id 入库后，若 hook 端误用非 UUID 字符串，zod `.uuid()` 会抛 → 由 parser 抛错入 daemon error 路径，与现有 schema 失败同语义。回滚：parser 单行还原 `randomUUID()`。
-- **回滚成本**：M2 是纯类型 + getter 替换，git revert 即可；M3 仅 2 行。
-
-## 实施顺序
-1. 新增 `core/types.ts` 类型 + `core/event-fields.ts` getter，先跑 `tsc --noEmit`（此时旧 `as any` 仍有效，无破坏）。
-2. 改 `daemon/event-parser.ts`（M3 + tool_input cast）；加 parser 测试。
-3. 逐文件替换 `as any`：`daemon/index.ts` → `cli/logs.ts` → `daemon/handlers/*` → `web/routes/sessions.ts` → `web/routes/tasks.ts` → `web/analytics/*` → `claudemd/resume-manager.ts`。每改一个跑 `tsc --noEmit`。
-4. 跑 `npm test`，确认 0 回归。
-5. 抓 hook 端 event_id 预生成作为后续 follow-up（**本 spec 不实施**）。
-
-## 命名遵循
-- Getter 用 `get*` 前缀（符合「获取单个资源用 `get`」约定）。
-- 类型用 PascalCase：`ToolInputFields`。
-- 文件 kebab-case：`event-fields.ts`。
-- 字段名沿用 hook 原始命名 (`file_path` / `command` / `subagent_type`)，不改 snake_case。

package/docs/design/m7-routing-event-association-spec-20260518-1545.md

@@ -1,103 +0,0 @@
-# M7: post-tool-use routing_event 关联修复 Spec
-
-## 目标
-
-修复 `PostToolUseHandler` 将 Agent 调用错误关联到已完成（`obeyed` 已填）的 routing_event 的时序错配 bug：把"最近一条"语义收紧为"最近一条 pending（`obeyed IS NULL`）"。
-
-## 数据流分析
-
-### routing_event 生命周期
-
-| T | 触发 | 操作 | 状态 |
-|---|---|---|---|
-| T0 | user prompt P1 | `UserPromptHandler` 写 routing_event#1 | `obeyed=NULL` |
-| T1 | Agent 调用 | `PostToolUseHandler` 取 most-recent → #1，update | `#1.obeyed=1` |
-| T2 | 普通工具（Read/Bash）| 不写 routing_event | `#1.obeyed=1` |
-| T3 | user prompt P2 | 写 routing_event#2 | `#2.obeyed=NULL`，#1 仍 obeyed=1 |
-| T4 | Agent 调用 | 取 most-recent → #2 | 正常 |
-
-### 现有读写点（routing_events）
-
-| 调用方 | 操作 | 方法 |
-|---|---|---|
-| `user-prompt.ts:120` | 每次 prompt insert，`obeyed=null` | `writeRoutingEvent` |
-| `post-tool-use.ts:33` | 取最近一条 | `getRecentRoutingEvent(sessionId)` |
-| `post-tool-use.ts:35` | 更新 obeyed/routed_to_* | `updateRoutingEvent(id, patch)` |
-| daemon 恢复 | 拉 pending（项目级） | `queryPendingRoutingEvents(ageMs)` |
-| 统计/聚合 | 只读 | `queryRoutingEvents`、`aggregate*` |
-
-## Bug 复现路径
-
-**真实错配场景**：同一 user prompt 内连续 2+ 个 Agent 调用。
-
-```
-T0  prompt P1 → write #1 (obeyed=NULL)
-T1  Agent#a 完成 → PostToolUse → getRecent → #1 → update {obeyed=1, routed_to_name='a'}
-T2  Agent#b 完成 → PostToolUse → getRecent → 仍是 #1 → update {obeyed=1, routed_to_name='b'}
-```
-
-后果：#1 的 `routed_to_name`、`first_tool_ts` 被第二个 Agent **覆盖**；第二个 Agent 调用**没有自己的归属 routing_event**，统计层缺数。
-
-**第二种错配**：跨 prompt 但中间 prompt 未走 UserPromptHandler（如 hook 失败 / daemon 重启后 buffer 丢失），下一个 Agent 仍会误关联到旧的 obeyed=1 的事件并把它再次覆盖。
-
-> review 描述的"覆盖未来不相关"其实是"覆盖过去已完成"语义，效果一致——丢失上次填充结果且当前调用无新行。
-
-## 方案对比
-
-| 维度 | A: `obeyed IS NULL` 过滤 | B: sessionKey in-mem cache | C: A + B 组合 |
-|---|---|---|---|
-| 实现复杂度 | 低（1 个 SQL 改/加方法）| 中（cache + 失效）| 中高 |
-| 跨进程/重启鲁棒 | 强（DB 真源）| 弱（cache 丢）| 强 |
-| 同 prompt 多 Agent 行为 | 第 2 个 Agent 找不到 pending → 跳过更新（数据丢失）| 同上，cache 也指向同一 id | 同上 |
-| 时序正确性 | 强 | 强（cache 命中时）| 强 |
-| 风险 | 同 prompt 多 Agent 漏记需另案 | daemon crash 丢 cache | 复杂度高于必要 |
-
-**推荐：方案 A**。理由：
-1. DB 是单一真源，无 cache 一致性问题。
-2. 同 prompt 多 Agent 场景下，方案 A 与 B 行为一致（都只命中一次），不构成 B 的优势。
-3. "同 prompt 多 Agent 都要记录"是 M7 范围外的功能扩展（应该在 PostToolUse 里 **insert** 新 routing_event 而非 update），不在此次修复内。
-
-## 改造点
-
-| 文件 | 改动 |
-|---|---|
-| `src/core/storage/routing.ts` | `getRecentRoutingEvent(sessionId)` SQL 加 `AND obeyed IS NULL`；或保留旧方法 + 新增 `getRecentPendingRoutingEvent(sessionId)`（推荐后者，向后兼容） |
-| `src/daemon/handlers/post-tool-use.ts:33` | 调用新方法 `getRecentPendingRoutingEvent` |
-| `src/core/storage/sqlite.ts` | facade 透传新方法 |
-| `tests/unit/storage/routing.test.ts`（如缺则新建）| 单测：3 个时序 case |
-| `tests/unit/daemon/post-tool-use.test.ts`（如缺则新建）| handler 行为测试 |
-
-## 测试策略
-
-**Storage 单测**（routing.test.ts）：
-- `getRecentPendingRoutingEvent` 返回最近 `obeyed IS NULL` 的行
-- 已存在 obeyed=1 在前 + 新 pending 在后 → 返回新 pending
-- 全部 obeyed 已填 → 返回 null（不误返）
-- 不同 session 隔离
-
-**Handler 单测**（post-tool-use.test.ts，新增）：
-- 时序 case 1（同 prompt 第 2 个 Agent）：第 1 个 update 成功，第 2 个找不到 pending → silently skip（assert：原 routing_event 不被二次覆盖）
-- 时序 case 2（跨 prompt）：每个 prompt 的 Agent 关联到自己的 event
-- 时序 case 3（无 routing_event）：handler 不抛错
-
-不需要集成测试（daemon 端到端已被 daemon 集成测试覆盖）。
-
-## 风险与回滚
-
-- **风险 1**：同 prompt 多 Agent 漏记 → 文档化为已知限制（M7 范围外）；后续可改为 PostToolUse insert 新行。
-- **风险 2**：旧库残留 obeyed=NULL 的 stale 行可能被新 prompt 的 Agent 错关 → 因为 ORDER BY ts DESC 限制 + session_id 过滤，最多影响"在该 session 内有非常老的孤儿 pending"的极端情况；可接受。
-- **回滚**：单 commit revert；新方法可保留无害。
-
-## 实施顺序
-
-1. routing.ts 新增 `getRecentPendingRoutingEvent`（SQL 加 `AND obeyed IS NULL`）
-2. sqlite.ts facade 透传
-3. routing.test.ts 加单测
-4. post-tool-use.ts 切换调用
-5. post-tool-use.test.ts 加 handler 单测
-6. `npx tsc --noEmit` + 相关 vitest
-
-## 命名遵循
-
-- `getRecentPendingRoutingEvent`（get 前缀，单个资源；与现有 `getRecentRoutingEvent`、`getExperimentAssignment` 对齐）
-- 不用 `queryRecentPending*`（query 前缀留给返回行集合的方法）

package/docs/design/project-path-gitroot-spec-20260518-1715.md

@@ -1,134 +0,0 @@
-# project-path git root 修复 Spec
-
-## 目标
-让 5 个 hook 在 IDE 调用时把 `cwd`（可能是任意子目录）上溯为 git 仓库根目录后再发给 daemon，从根上阻止子目录被生成 `.claude-forge/`。
-
-## 调研结果
-
-| 位置 | 现状 | 改造需求 |
-|---|---|---|
-| `src/hooks/pre-tool-use.sh:15-16` | `PROJECT_PATH=$(jq -r '.cwd'); fallback $PWD` | 套上 `resolve_project_path` |
-| `src/hooks/post-tool-use.sh:17-18` | 同上 | 同上 |
-| `src/hooks/user-prompt-submit.sh:15-16` | 同上 | 同上 |
-| `src/hooks/stop.sh:11-12` | 同上 + 未引用 hook-lib.sh | 先 source hook-lib.sh 再用函数 |
-| `src/hooks/notification.sh:13-14` | 同上 | 同上 |
-| `src/hooks/hook-lib.sh` | 已有 `send_event_or_enqueue` 公共函数 | **新增 `resolve_project_path`** |
-| `src/daemon/handlers/history-exporter.ts:24` | `path.join(project_path,'.claude-forge','history')` | 不动（hook 端已传 git root） |
-| `src/cli/commands/executions.ts:16,53,85` | `process.cwd()` 拼 `.claude-forge` | 新增 `resolveGitRoot()` helper |
-| `src/templates/template-manager.ts:82,89` | `initProject(_, projectPath)` 由调用方传入 | 调用方传 git root 即可（init CLI 自身改） |
-
-观察：`hook-lib.sh` 已存在公共函数集，`stop.sh` 是唯一未 source 它的 hook（手写 nc + socket），改造时顺手补齐一致性。
-
-## 方案选择
-
-| | A. Hook 端解析 git root | B. Daemon 端解析 | C. 完全消除目录 | D. 混合 hash |
-|---|---|---|---|---|
-| 改动面 | 5 hook + lib + CLI | 1 处 | 涉及多模块迁移 | A+ 存储改造 |
-| 性能 | bash 上溯（O(深度)，无子进程）| 每次 spawn `git` | 同 A | 同 A |
-| 下游受益 | 全部 | 仅 history-exporter | 全部但破坏可见性 | 全部 |
-| 老数据 | 兼容（新数据用新值）| 兼容 | 需迁移 | 需迁移 |
-| 风险 | 0 测试 hook 改动 | 子进程开销 | discoverability 破坏 | 引入新维度 |
-
-**推荐 A**：根因解决 + 保留用户在项目根 `ls` 即可看到 history 的可见性 + 不引入子进程开销。bash `while` 上溯零依赖，daemon / CLI 自动受益。
-
-## 改造范围（约 70 行）
-
-| 文件 | 行数 | 说明 |
-|---|---|---|
-| `src/hooks/hook-lib.sh` | +25 | 新增 `resolve_project_path` |
-| `src/hooks/pre-tool-use.sh` | -2 +1 | 替换两行 |
-| `src/hooks/post-tool-use.sh` | -2 +1 | 同上 |
-| `src/hooks/user-prompt-submit.sh` | -2 +1 | 同上 |
-| `src/hooks/stop.sh` | -2 +2 | 先 source hook-lib.sh，再用函数 |
-| `src/hooks/notification.sh` | -2 +1 | 同上 |
-| `src/cli/commands/executions.ts` | +8 | 新增 `resolveGitRoot()` 替换 3 处 `process.cwd()` |
-| `src/cli/commands/init.ts`（调用 template-manager 处，需 grep 确认）| +2 | 把传给 `initProject` 的 `projectPath` 改成 git root |
-| 新增 `tests/unit/hooks/resolve-project-path.test.sh`（或 vitest 调 bash）| ~40 | safety-net |
-| 新增 `tests/integration/hook-gitroot.integration.test.ts` | ~50 | 端到端 |
-
-## hook-lib.sh 公共函数设计
-
-```bash
-# resolve_project_path <input_cwd>
-# 从 input_cwd 上溯查找最近的 .git 目录，输出 git root。
-# 非 git 项目 / 上溯到根 / 输入为空 → 回退到 input_cwd（再回退到 $PWD）。
-# 防御：最多上溯 64 层，避免符号链接环。
-resolve_project_path() {
-  local dir="${1:-$PWD}"
-  [ -z "$dir" ] && dir="$PWD"
-
-  # 规整为绝对路径（不依赖 realpath）
-  case "$dir" in
-    /*) ;;
-    *)  dir="$PWD/$dir" ;;
-  esac
-
-  local guard=0
-  while [ "$dir" != "/" ] && [ "$dir" != "." ] && [ $guard -lt 64 ]; do
-    if [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then  # 后者兼容 git worktree
-      printf '%s' "$dir"
-      return 0
-    fi
-    dir=$(dirname "$dir")
-    guard=$((guard + 1))
-  done
-
-  # 未找到 → 回退到原 cwd
-  printf '%s' "${1:-$PWD}"
-}
-```
-
-调用方一行替换：
-```bash
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-```
-
-## CLI / daemon 端兼容
-
-**daemon 端**：不改。`history-exporter.ts:24` 信任传入的 `event.project_path`（hook 端已是 git root）。
-
-**CLI 端 `executions.ts`**：新增 helper（放 `src/core/utils/git.ts`）：
-```typescript
-export function resolveGitRoot(start = process.cwd()): string {
-  try {
-    return execSync('git rev-parse --show-toplevel', { cwd: start, stdio: ['ignore', 'pipe', 'ignore'] })
-      .toString().trim() || start;
-  } catch { return start; }
-}
-```
-三处 `path.join(process.cwd(), '.claude-forge', ...)` → `path.join(resolveGitRoot(), '.claude-forge', ...)`。
-
-**template-manager.ts**：函数本身签名不变（接收 `projectPath`），改 init 命令调用侧。
-
-## 测试策略
-
-- **safety-net (单测 bash 函数)**：构造 fixture `/tmp/forge-test/repo/.git/`，对 `resolve_project_path /tmp/forge-test/repo/a/b/c` 断言返回 git root；非 git 目录断言回退；空输入断言回退到 `$PWD`。
-- **集成**：vitest 起一个 daemon，构造 `cwd=fixture/sub/dir` 的 INPUT，跑 `pre-tool-use.sh`，从 daemon storage queryEvents 断言 `project_path === fixture` 而非子目录。
-- **回归**：现有 daemon 集成测试不需要改（hook 端透明改造）。
-- **CLI 端**：单测 `resolveGitRoot()` 在 git 仓 / 非 git 仓两种 cwd 下的返回值。
-
-## 风险与回滚
-
-- **`.git` 是文件（worktree）场景**：`[ -f "$dir/.git" ]` 已兼容。
-- **非 git 项目**：fallback 原 cwd，行为不变。
-- **monorepo 子模块各自 .git**：返回最近的 git root，符合预期。
-- **历史数据**：旧 sessions.project_path 仍是子目录路径，不做迁移；可选清单：列出 sessions 表去重 project_path，提供 `cf admin remap-project-path` 工具（非本次范围）。
-- **bash on Linux/macOS 差异**：用 POSIX 内建（`dirname` / `case`），不依赖 `realpath`。
-- **回滚**：还原 6 个文件即可，无 schema 变更。
-
-## 实施顺序（refactor-safe）
-
-1. **safety-net 阶段**：先写 `tests/unit/hooks/resolve-project-path.test.sh`（或 vitest 用 `child_process.execSync('bash -c "source hook-lib.sh && resolve_project_path ..."')`）和 `tests/integration/hook-gitroot.integration.test.ts`（先红）
-2. **lib 阶段**：在 `hook-lib.sh` 新增 `resolve_project_path` → 单测转绿
-3. **hook 改造**：5 个 hook 替换两行；`stop.sh` 同时改为 `source hook-lib.sh`（顺手补一致性）→ 集成测试转绿
-4. **CLI 阶段**：新增 `src/core/utils/git.ts::resolveGitRoot`，改 `executions.ts` 3 处 + `init` 调用侧
-5. **验证**：`npx tsc --noEmit` + `npm test` + 手工到 fixture 子目录跑 `cf executions list` 确认走 git root
-6. **release**：bump patch 版本，changelog 注明"hooks 解析 git root，不再在子目录生成 .claude-forge"
-
-## 命名遵循
-
-- bash 函数：`resolve_project_path`（snake_case，与 hook-lib 现有 `send_event_or_enqueue` / `_enqueue_event_bg` 一致）
-- TS 工具函数：`resolveGitRoot`（camelCase，`get` 前缀不适用因为这是计算非查询）
-- 新文件：`src/core/utils/git.ts`（kebab 化已为单词，遵循现有 `time.ts` / `session.ts`）
-- 测试文件：`tests/unit/hooks/resolve-project-path.test.sh` 或 `.test.ts`、`tests/integration/hook-gitroot.integration.test.ts`