@winspan/claude-forge 8.41.0 → 8.51.0

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

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

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

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

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

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

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

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

package/docs/implementation/m6-m8-naming-shutdown-changelog-20260518-1340.md

@@ -0,0 +1,56 @@
+# M6 + M8 实施 Changelog
+
+**Date**: 2026-05-18 13:40
+**Status**: 完成
+
+## 完成清单
+
+- [x] M8: daemon shutdown 加 clearInterval
+- [x] M6: `recordTokenUsage` → `writeTokenUsage`
+- [x] M6: `findPendingRoutingEvents` → `queryPendingRoutingEvents`
+- [x] M6: `fetchEventsSince` → `queryEventsSince`（顺手 `fetchSessionsSince` → `querySessionsSince`）
+
+## 关键代码定位
+
+### M8: daemon shutdown clearInterval
+
+- `src/daemon/index.ts:111-119` — `setInterval` 返回值保存到 `maintenanceInterval` 常量
+- `src/daemon/index.ts:254` — `shutdown()` 中新增 `clearInterval(maintenanceInterval)`，置于 webServer.stop 之前、process.exit 之前
+
+### M6: `recordTokenUsage` → `writeTokenUsage`
+
+- `src/core/storage/token-usage.ts:13` — `TokenUsageOperations.writeTokenUsage`（定义）
+- `src/core/storage/sqlite.ts:186-188` — facade 转发更新（含 `Parameters<...>` 泛型引用同步）
+- `src/core/utils/token-tracker.ts:36` — 业务调用方
+- `tests/unit/token-usage.test.ts` — 6 处调用点（replace_all）
+- `tests/unit/storage/sqlite-refactor-harness.test.ts:231-246` — 测试调用 + test name 同步更新
+
+### M6: `findPendingRoutingEvents` → `queryPendingRoutingEvents`
+
+- `src/core/storage/routing.ts:130` — `RoutingOperations.queryPendingRoutingEvents`（定义）
+- `src/core/storage/sqlite.ts:167-169` — facade 转发更新
+
+无外部调用方（grep 仅命中定义与 facade）。
+
+### M6: `fetchEventsSince` / `fetchSessionsSince` → `queryEventsSince` / `querySessionsSince`
+
+- `src/daemon/services/anti-pattern-detector.ts:58-59` — 内部调用点
+- `src/daemon/services/anti-pattern-detector.ts:82` — `private queryEventsSince`
+- `src/daemon/services/anti-pattern-detector.ts:102` — `private querySessionsSince`
+
+均为私有方法，无类外引用。
+
+## 测试结果
+
+- `npx tsc --noEmit` → **0 errors**
+- `npx vitest run tests/unit/storage/ tests/unit/token-usage.test.ts --reporter=dot` → 67 passed / 1 failed（pre-existing `linkEventToTask`）
+- `npm test -- --reporter=dot` → 439 passed / 1 failed（同一 pre-existing 失败）
+
+## 顺手发现的其它命名违规
+
+- `fetchSessionsSince`（在 anti-pattern-detector.ts，与 `fetchEventsSince` 配对）一并改为 `querySessionsSince`。
+- 未发现其它 `findXxx`/`fetchYyy`/`retrieveZzz` 违规（grep 已扫过 src/ tests/）。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts` 中 `linkEventToTask associates events with tasks` 用例 pre-existing 失败（writeEvent 校验抛错），与本次改名无关。

package/docs/implementation/m7-routing-association-changelog-20260518-1545.md

@@ -0,0 +1,69 @@
+# M7 实施 Changelog
+
+**Date**: 2026-05-18 15:45
+**Spec**: docs/design/m7-routing-event-association-spec-20260518-1545.md
+**Status**: 完成
+
+## 完成清单
+- [x] routing.ts 加 getRecentPendingRoutingEvent
+- [x] sqlite.ts facade 透传
+- [x] storage 单测 5 case（4 必需 + 1 legacy 行为锁定）
+- [x] post-tool-use.ts 切换调用
+- [x] handler 单测 3 case
+- [x] 文档化已知限制
+
+## 关键代码定位
+
+- 新方法实现：`src/core/storage/routing.ts:148-170`
+- Facade 透传：`src/core/storage/sqlite.ts:225-227`
+- Handler 切换：`src/daemon/handlers/post-tool-use.ts:32-36`
+- Storage 单测：`tests/unit/storage/routing.test.ts:1-112`
+- Handler 单测：`tests/unit/daemon/post-tool-use.test.ts:1-119`
+
+## 测试结果
+
+- **新增 storage 测试**：5/5 passed
+  - case 1: 旧 obeyed=1 + 新 pending → 返回新 pending
+  - case 2: 全部 obeyed=1 → 返回 null
+  - case 3: session 隔离
+  - case 4: 单条 pending → 返回该条
+  - bonus: legacy `getRecentRoutingEvent` 行为锁定（仍返回 most-recent，不受 obeyed 影响）
+- **新增 handler 测试**：3/3 passed
+  - case 1（核心 bug 验证）：同 prompt 第 2 个 Agent 不二次覆盖原 routing_event
+  - case 2: 跨 prompt 各自关联
+  - case 3: 无 routing_event 不抛错
+- **tsc --noEmit**：0 errors
+- **npm test 全量**：549 passed / 1 failed = 549/550
+  - 唯一失败 `linkEventToTask associates events with tasks`，与 M7 无关（spec 第 86 行已标注 pre-existing）
+
+## 实施细节
+
+### 向后兼容策略
+
+- **保留** 旧 `getRecentRoutingEvent`（无 `obeyed IS NULL` 过滤）不动
+- **新增** `getRecentPendingRoutingEvent`（带 `obeyed IS NULL` 过滤）
+- Handler 仅切换到新方法；其他调用方（如有）维持旧语义
+
+### Bug 修复验证
+
+handler 单测 case 1 直接复现了 spec 描述的"同 prompt 多 Agent 覆盖"场景：
+
+```ts
+// Before M7: Agent#2 也会拿到 routing_event#1 → routed_to_name 被覆盖为 'coder'
+// After M7:  Agent#2 拿不到 pending（#1 已 obeyed=1）→ 不再触碰 #1
+expect(rowsAfter2[0].routed_to_name).toBe('researcher'); // NOT 'coder'
+expect(rowsAfter2[0].first_tool_ts).toBe(firstToolTs);    // 不被 stomp
+```
+
+## 已知限制（文档化）
+
+- **同 prompt 多 Agent 漏记**：第 2+ 个 Agent 在 M7 修复后会被 silently skip（找不到 pending）。
+  - 影响：该 Agent 调用在 routing_events 表中没有归属行。
+  - 不在 M7 范围内：要彻底解决须把 PostToolUse 改为 **INSERT** 新行（而非 UPDATE），属功能扩展。
+  - 与 M7 前的对比：M7 前是"覆盖原行"（数据丢失 + 错配），M7 后是"放弃记录"（数据缺失但不错配）。语义更可控。
+
+- **旧库残留 obeyed=NULL 的 stale 行**：若 session 内存在非常老的孤儿 pending（如旧 daemon crash 留下），可能被新 prompt 的 Agent 错关联。受 `ORDER BY ts DESC + session_id` 限制，影响面极小，可接受。
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask associates events with tasks` 失败为 pre-existing，与 M7 无关，未触碰。

package/docs/implementation/project-path-gitroot-changelog-20260518-1715.md

@@ -0,0 +1,63 @@
+# project-path git root 修复 Changelog
+
+**Date**: 2026-05-18 17:15
+**Spec**: docs/design/project-path-gitroot-spec-20260518-1715.md
+**Status**: 完成
+
+## 完成清单
+
+- [x] hook-lib.sh `resolve_project_path` — 已由前序 agent 完成
+- [x] pre-tool-use.sh 改造 — 已由前序 agent 完成
+- [x] post-tool-use.sh 改造 — 已由前序 agent 完成
+- [x] user-prompt-submit.sh 改造 — 已由前序 agent 完成
+- [x] notification.sh 改造 — 已由前序 agent 完成
+- [x] stop.sh 改造 — 本次完成（source hook-lib.sh 方案 + 替换 nc 为 send_event_or_enqueue）
+- [x] `src/core/utils/git.ts` — 本次新建
+- [x] `src/cli/commands/executions.ts` 3 处 `process.cwd()` → `resolveGitRoot()`
+- [△] `src/cli/commands/init.ts` — 未改，见下方原因
+- [x] 安全网单测（7 case 全过），扩展现有 `tests/unit/hooks/resolve-project-path.test.ts`
+- [△] 集成测试 — 降级方案：扩展现有单测（case 6/7），不新建独立 integration 文件
+
+## 关键代码定位
+
+| 文件 | 行 | 说明 |
+|------|-----|------|
+| `src/hooks/hook-lib.sh:26-48` | — | `resolve_project_path` 函数体 |
+| `src/hooks/stop.sh:5` | 5 | `source hook-lib.sh` 新增 |
+| `src/hooks/stop.sh:13-14` | 13-14 | `RAW_CWD` + `resolve_project_path` 替换原两行 |
+| `src/hooks/stop.sh:29-30` | 29-30 | `send_event_or_enqueue` 替换原 `nc` 调用 |
+| `src/core/utils/git.ts:1-20` | — | `resolveGitRoot()` TS helper |
+| `src/cli/commands/executions.ts:5` | 5 | import `resolveGitRoot` |
+| `src/cli/commands/executions.ts:16,53,85` | 16,53,85 | 3 处 `process.cwd()` → `resolveGitRoot()` |
+| `tests/unit/hooks/resolve-project-path.test.ts:99-117` | 99-117 | case 6/7 新增 |
+
+## 测试结果
+
+- `tsc --noEmit`: 0 errors
+- `npm test`: 558 passed / 1 failed（pre-existing: `linkEventToTask` in sqlite-refactor-harness.test.ts）
+- hook 单测: 7 / 7 passed（含 2 个新增 case）
+- `npm run build`: 成功
+
+## 实施决策
+
+### stop.sh: source 方案（非 inline）
+
+`stop.sh` 原来手写 `nc` 直连 socket，未 source `hook-lib.sh`。本次采用 source 方案：
+- 在文件顶部加 `source "$(dirname "$0")/hook-lib.sh"`，与其他 4 个 hook 保持一致性
+- 同时将 `nc` 调用替换为 `send_event_or_enqueue`，获得"daemon 停机时自动入队"的能力
+- stop.sh 在 daemon 运行时由 hook 调用，`$(dirname "$0")` 指向已安装的 hook 目录，路径可达
+
+### 集成测试降级方案
+
+选择"扩展现有单测"（case 6/7）而非新建独立 integration 文件：
+- case 6 模拟 hook INPUT JSON 中 cwd 指向嵌套子目录的场景
+- case 7 模拟 hook INPUT cwd 为空时 fallback 到 shell $PWD 的场景
+- 覆盖核心路径，避免端到端测试引入 daemon 启动复杂度
+
+### init.ts: 未改
+
+`init.ts` 不操作项目级路径（`.claude-forge/` 子目录）。它只操作全局 `FORGE_HOME`（`~/.claude-forge/`）和 Claude Code 的全局 settings.json。`initProject` / `template-manager` 调用不在 init.ts 中出现。无需修改。
+
+## 已知问题
+
+- `linkEventToTask` 测试失败为 pre-existing，与本次改动无关