@winspan/claude-forge 8.39.0 → 8.50.6

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

@@ -0,0 +1,104 @@
+# 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/hook-failure-queue-changelog-20260516-1530.md

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

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