@winspan/claude-forge 8.50.6 → 8.51.1

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，与本次改动无关

package/docs/implementation/task-active-gc-changelog-20260518-1745.md

@@ -0,0 +1,35 @@
+# task active GC 修复 Changelog
+
+**Date**: 2026-05-18 17:45
+**Spec**: docs/design/task-active-gc-spec-20260518-1745.md
+**Status**: 完成
+
+## 完成清单
+- [x] storage completeStaleActiveTasks
+- [x] sqlite facade 转发
+- [x] task-segmenter completeCurrentTask recover fallback
+- [x] daemon staleTaskGcInterval (5 分钟一次，idle 10 分钟阈值)
+- [x] shutdown clearInterval
+- [x] 单测 4 case + recover fallback 3 case
+
+## 关键代码定位
+
+- `src/core/storage/tasks.ts:144-155` — `completeStaleActiveTasks` 方法
+- `src/core/storage/sqlite.ts:183-185` — facade 代理方法
+- `src/daemon/services/task-segmenter.ts:78` — `completeCurrentTask` recover fallback
+- `src/daemon/index.ts:118-131` — `staleTaskGcInterval` 注册（STALE_TASK_GC_INTERVAL=5min，STALE_TASK_IDLE_MINUTES=10）
+- `src/daemon/index.ts:251` — `clearInterval(staleTaskGcInterval)` 在 shutdown 中
+
+## 测试结果
+- tsc: 0 errors
+- npm test: 565 passed / 1 failed (pre-existing `linkEventToTask` in sqlite-refactor-harness.test.ts)
+- 新增测试: 7 cases all passed (4 storage GC + 3 segmenter recover)
+
+## 验证 bug 修复
+
+- 场景 A（ESC 中断，Stop hook 不触发）：5 分钟 GC 轮询后自动将 idle > 10 分钟的 active task 转 completed
+- 场景 B（daemon 重启后 Stop hook 触发但 Map 空）：completeCurrentTask recover fallback 从 DB 恢复并关闭任务
+- 场景 C（用户永不再 prompt 旧 session）：GC 兜底，idle 10 分钟后自动关闭
+
+## 已知问题
+- `linkEventToTask` pre-existing failure in `sqlite-refactor-harness.test.ts` — 与本次改动无关

package/docs/implementation/task-title-summary-changelog-20260518-1130.md

@@ -0,0 +1,39 @@
+# Changelog: task-title-summary — 2026-05-18 11:30
+
+## Summary
+
+Frontend-only fix: Tasks list and TaskDetail header now display the human-readable
+`<summary>` extracted from `<task-notification>` XML titles instead of the raw blob.
+
+## Files Changed
+
+### New
+
+- `web/src/utils/task-title.ts` — pure helper `normalizeTaskTitle(title)`
+- `tests/unit/web/task-title-contract.test.ts` — 19 contract tests (TDD, written before implementation)
+- `docs/reviews/task-title-summary.md` — fix report
+
+### Modified
+
+- `web/src/pages/Tasks.tsx`
+  - Import `normalizeTaskTitle` from `../utils/task-title`
+  - Line 340: `{task.title}` → `{normalizeTaskTitle(task.title)}`
+
+- `web/src/pages/TaskDetail.tsx`
+  - Import `normalizeTaskTitle` from `../utils/task-title`
+  - Line 205: `{data.title}` → `{normalizeTaskTitle(data.title)}`
+
+## Constraints Respected
+
+- Backend untouched (task-segmenter, routes/tasks.ts, storage)
+- No new npm dependencies
+- TypeScript strict — zero errors
+- Pure function, no React dependency
+- Pre-existing test failure (sqlite-refactor-harness / uuid) is unrelated and pre-dates this change
+
+## Workflow
+
+harness-hotfix: safety-net → fix → verify
+- safety-net: wrote 19 failing contract tests
+- fix: implemented normalizeTaskTitle, wired into Tasks.tsx + TaskDetail.tsx, all 19 tests green
+- verify: web build ✓, tsc --noEmit ✓ (both root + web), 378/379 tests pass

package/docs/implementation/tasks-detail-back-loses-filters-changelog-20260518-1100.md

@@ -0,0 +1,22 @@
+# Changelog: tasks-detail-back-loses-filters
+
+**Date**: 2026-05-18 11:00
+**Harness workflow**: safety-net → fix → verify
+**skill_invoke**: MCP not invoked (direct execution per harness instructions)
+
+---
+
+## 2026-05-18
+
+- **10:06** Safety-net established — created `tests/unit/web/navigation-back-contract.test.ts` with 21 characterization tests locking the `resolveBackTo` fallback and happy-path behaviours before any code was changed.
+
+- **10:08** Fix applied:
+  - Created `web/src/utils/navigation.ts` — exports `resolveBackTo(state: unknown, fallback='/tasks'): string` with strict type narrowing (no `as any`).
+  - `web/src/pages/Tasks.tsx` — added `useLocation` import; passed `{ state: { from: location.pathname + location.search } }` on task navigation.
+  - `web/src/pages/TaskDetail.tsx` — added `useLocation` + `resolveBackTo` imports; computed `backTo = resolveBackTo(location.state)`; replaced both absolute `<Link to="/tasks">` (error branch + success branch) with `<Link to={backTo}>`.
+
+- **10:09** Verification:
+  - `web npm run build`: clean (tsc + vite, 0 errors).
+  - `npx tsc --noEmit` (root + web): 0 errors.
+  - Full test suite: 359/360 pass; 1 pre-existing failure in `sqlite-refactor-harness.test.ts` (confirmed present before our changes via `git stash` baseline run).
+  - Fix report written to `docs/reviews/tasks-detail-back-loses-filters.md`.

package/docs/implementation/tasks-page-white-screen-hotfix-changelog-20260518-1015.md

@@ -0,0 +1,56 @@
+# Changelog: Tasks Page White Screen Hotfix
+
+**Date**: 2026-05-18 10:15
+**Bug slug**: tasks-page-white-screen
+**Workflow**: harness-hotfix (safety-net → fix → verify)
+
+## Phase 1: safety-net
+
+Created `tests/unit/web/tasks-component-contract.test.ts` with 15 characterization tests:
+- Documents the broken consumer behaviour (TypeError on `.filter` of `TaskPage` object)
+- Locks the correct `{ items, total, has_more }` API contract
+- Tests pagination parameter logic
+
+All 15 tests pass immediately (they lock current correct contract + document the defect pattern).
+
+## Phase 2: fix
+
+### Files Modified
+
+**`web/src/pages/Tasks.tsx`** — full rewrite
+- Fixed `fetchTasks` return type from `Task[]` to `TaskPage`
+- Destructure `data.items`, `data.total`, `data.has_more` correctly
+- Added URL sync via `useSearchParams` (page, size, project, preset, from, to, search)
+- Added project multi-select dropdown (fetches `/api/tasks/projects`)
+- Added time presets (1h / 24h / 7d)
+- Added pagination controls (prev/next + page size selector 20/50/100)
+- Added "共 N 条" total count display
+- Added `shortPath()` helper to truncate project paths to last 2 segments
+- Tailwind utility classes only, no inline styles
+
+**`CLAUDE.md`** (line 184)
+- Changed: `原生 HTML + Vanilla JS（单文件 SPA），无打包`
+- To: `React 18 + Vite + Tailwind + react-router-dom + react-query + Recharts（\`web/\` 目录，build 后被 cp 到 dist/web/static/）`
+
+**`src/claudemd/claudemd-generator.ts`** (line 737)
+- Same correction in embedded template, backtick escaped to `\`` to avoid breaking the template literal
+
+### No Backend Changes
+
+`App.tsx` already had correct `<Route path="tasks">` config.
+`Layout.tsx` already had Tasks nav item with `ListTodo` icon.
+All backend routes (`/api/tasks`, `/api/tasks/projects`) were correct and untouched.
+
+## Phase 3: verify
+
+- `web/` TypeScript: clean
+- Root TypeScript: clean (after escaping backtick in template literal)
+- `web/npm run build`: success, `Tasks-D98y3WV2.js` chunk produced
+- Root `npm run build`: success, chunk copied to `dist/web/static/assets/`
+- Test results: 338/339 pass (1 pre-existing failure in sqlite-refactor-harness, unrelated)
+- `curl http://127.0.0.1:3721/` → 200 OK, HTML contains 8 vite/module references
+- API response confirmed: `{"items":[...],"total":393,"has_more":true}`
+
+## Action Required
+
+Run `./scripts/dev-daemon.sh restart` to serve the updated bundle.

package/docs/reviews/task-title-summary.md

@@ -0,0 +1,92 @@
+# Fix Report: task-title-summary
+
+**Bug slug**: `task-title-summary`
+**Date**: 2026-05-18
+**Workflow**: harness-hotfix (safety-net → fix → verify)
+
+---
+
+## Root Cause
+
+Sub-agent completion callbacks are pushed to the session as a `UserPromptSubmit`
+event whose content is the raw `<task-notification>` XML blob. The
+`task-segmenter` uses the first user-prompt content as the task `title`, so
+tasks spawned from these callbacks end up with a title like:
+
+```
+<task-notification>
+<task-id>aefe161c…</task-id>
+…
+<summary>Agent "Hotfix Tasks 返回丢筛选" completed</summary>
+…
+</task-notification>
+```
+
+The frontend rendered the literal XML string in both the Tasks list (`h3`) and
+the TaskDetail header (`h1`), making the task unrecognisable.
+
+**Backend was intentionally left unchanged** — the raw XML is the ground truth.
+The fix lives entirely in the frontend presentation layer.
+
+---
+
+## Fix Points
+
+| File | Change |
+|------|--------|
+| `web/src/utils/task-title.ts` | **New file** — pure helper `normalizeTaskTitle()` |
+| `web/src/pages/Tasks.tsx` | Import + wrap `{task.title}` → `{normalizeTaskTitle(task.title)}` in list `<h3>` |
+| `web/src/pages/TaskDetail.tsx` | Import + wrap `{data.title}` → `{normalizeTaskTitle(data.title)}` in detail `<h1>` |
+
+### `normalizeTaskTitle` logic (MAX_LEN = 80)
+
+1. `null / undefined / whitespace` → `"(无标题)"`
+2. Title starts with `<task-notification>`:
+   - Has `<summary>` with non-blank content → extract, trim, truncate + `…` if > 80 chars
+   - No `<summary>` or blank → `"(子任务回调)"`
+3. Regular title → trim, truncate + `…` if > 80 chars
+
+---
+
+## New Tests
+
+File: `tests/unit/web/task-title-contract.test.ts`
+
+**19 test cases** covering:
+
+| Group | Cases |
+|-------|-------|
+| Passthrough | normal title, English title, whitespace trim |
+| Fallback | empty string, whitespace-only, null, undefined |
+| XML extraction | full blob, missing summary, bare tag, emoji+Chinese, quotes, first-match-wins |
+| Truncation | summary > 80, summary = 80, plain title > 80, plain title = 80 |
+| Summary whitespace | padded summary, whitespace-only summary |
+
+---
+
+## Regression / Build Verification
+
+```
+Tests:  19 passed (task-title-contract.test.ts — all green)
+Suite:  378 passed, 1 pre-existing failure (sqlite-refactor-harness / uuid validation,
+        unrelated to this change, present before this fix)
+
+web build:   ✓ built in 2.50s (no errors)
+  new chunk: dist/assets/task-title-Bc8tnLXB.js (0.36 kB gzip: 0.30 kB)
+  Tasks chunk hash: Tasks-C8JHCGTC.js
+  TaskDetail chunk hash: TaskDetail-DYEk8pNw.js
+
+TypeScript:  npx tsc --noEmit → 0 errors (root)
+             npx tsc --noEmit → 0 errors (web/)
+```
+
+---
+
+## Notes
+
+- `normalizeTaskTitle` is a pure function with zero React dependency — safe to
+  test in Node environment without jsdom.
+- The helper intentionally **does not** modify stored data. Backend titles remain
+  unchanged; this is purely a display-layer normalisation.
+- The first `<summary>` match is used defensively in case of malformed XML with
+  duplicate tags.

package/docs/reviews/tasks-detail-back-loses-filters.md

@@ -0,0 +1,58 @@
+# Fix Report: tasks-detail-back-loses-filters
+
+**Date**: 2026-05-18
+**Workflow**: harness-hotfix (safety-net → fix → verify)
+
+---
+
+## Root Cause
+
+`TaskDetail.tsx` used `<Link to="/tasks">` — a hard absolute path — for both the
+error-state and success-state "back" buttons (lines 161 and 195 of the original
+file).  React Router resolves this to `/tasks` with no query string, discarding
+whatever filter state the user had on the Tasks page.
+
+Concretely: a user at `/tasks?project=foo&page=2` clicks a task, lands on
+`/tasks/<id>`, then clicks "返回" → router navigates to `/tasks` (no `?project=foo&page=2`).
+`useSearchParams()` returns empty values, so the Tasks page re-renders showing
+all tasks from page 1.
+
+---
+
+## Fix Points
+
+| File | Change |
+|------|--------|
+| `web/src/utils/navigation.ts` (new) | Pure function `resolveBackTo(state, fallback='/tasks'): string` with full type narrowing — no `as any`. |
+| `web/src/pages/Tasks.tsx` | Added `useLocation` import. Added `const location = useLocation()` in component body. Changed `navigate(\`/tasks/${task.id}\`)` to `navigate(\`/tasks/${task.id}\`, { state: { from: location.pathname + location.search } })`. |
+| `web/src/pages/TaskDetail.tsx` | Added `useLocation` + `resolveBackTo` imports. Added `const location = useLocation()` and `const backTo = resolveBackTo(location.state)` in component body. Replaced both `<Link to="/tasks">` with `<Link to={backTo}>` (error branch line ~161, success branch line ~195). |
+
+---
+
+## New Tests
+
+**File**: `tests/unit/web/navigation-back-contract.test.ts`
+
+21 contract tests across 4 suites:
+
+1. **fallback path** (7 tests) — `state` is `null`, `undefined`, `{}`, `{ from: undefined }`, `{ from: '' }`, custom fallback with `null`, custom fallback with `{}`.
+2. **happy path** (5 tests) — `state.from` carries full query string with project filter, page number, preset, search; plain `/tasks` (no query string).
+3. **type safety** (6 tests) — `state.from` is number, array, object, `null`; `state` itself is a number or string — all fall back gracefully.
+4. **navigation state construction** (3 tests) — verifies the `location.pathname + location.search` encoding round-trips without mutation; handles empty search string.
+
+Tests import from the real `web/src/utils/navigation.ts` module.
+
+---
+
+## Regression Test Results
+
+| Run | Files | Tests | Failures |
+|-----|-------|-------|---------|
+| Pre-change baseline | 1 failed / 29 passed | 1 failed / 359 passed | `sqlite-refactor-harness.test.ts` (pre-existing, unrelated) |
+| Post-fix | 1 failed / 29 passed | 1 failed / 359 passed | same pre-existing failure only |
+
+- `npm run build` (web/): clean — 0 TypeScript errors, 0 Vite errors
+- `npx tsc --noEmit` (project root): 0 errors
+- `npx tsc --noEmit` (web/): 0 errors (run as part of `npm run build`)
+- New safety-net: 21/21 pass
+- Existing tasks contract: 15/15 pass (no regression)

package/docs/reviews/tasks-page-white-screen-hotfix.md

@@ -0,0 +1,126 @@
+# Hotfix Report: Tasks Page White Screen
+
+**Bug slug**: tasks-page-white-screen
+**Date**: 2026-05-18
+**Severity**: P0 (production white screen on Tasks nav item click)
+
+---
+
+## Root Cause
+
+### Error Chain
+
+1. `web/src/App.tsx:12` lazy-imports `./pages/Tasks`
+2. `Tasks.tsx` (pre-fix) called `GET /api/tasks` and did `return res.json()` — treating the response body as `Task[]`
+3. `GET /api/tasks` actually returns `{ items: Task[], total: number, has_more: boolean }` — a paginated wrapper (`TaskPage`), not a bare array
+4. The component called `tasks.filter(...)` on the `TaskPage` object, which has no `.filter` method → `TypeError: tasks.filter is not a function`
+5. React's error boundary was not configured → unhandled `TypeError` inside `<Suspense>` → white screen
+
+### Why This Shape Mismatch Existed
+
+The backend `/api/tasks` route was upgraded (v8.50.6 implementation task `tasks-filter-pagination`) to add filter + pagination support, returning `{ items, total, has_more }`. The `Tasks.tsx` component was a pre-existing stub that was never updated to consume the new paginated shape.
+
+### Why v8.50.6 Spec Walked Off Target
+
+The planner agent generating the v8.50.6 spec analyzed `src/web/routes/tasks.ts` (backend) but did not inspect `web/src/pages/Tasks.tsx` (frontend). It documented the backend correctly but left the frontend in an inconsistent state. Additionally, `CLAUDE.md` was incorrectly updated to say the frontend uses "原生 HTML + Vanilla JS" (Vanilla JS) rather than React + Vite — this misdirected future agents away from looking in `web/`.
+
+**How to avoid next time**:
+- When modifying a backend API shape, always grep for frontend consumers in `web/src/` before closing the task
+- `CLAUDE.md` tech stack description is a critical navigation signal for agents — any incorrect entry should be treated as a P1 issue
+- Add a CI check or spec gate: "if API response shape changes, verify frontend page component is updated"
+
+---
+
+## Fix Points
+
+### Modified Files
+
+| File | Lines | Change |
+|------|-------|--------|
+| `web/src/pages/Tasks.tsx` | full rewrite (~290 lines) | Fix `fetchTasks` to return `TaskPage`, destructure `items`/`total`/`has_more`, add pagination + project filter + time presets + URL sync via `useSearchParams` |
+| `CLAUDE.md` | line 184 | Restore frontend description to React 18 + Vite + Tailwind + react-router-dom + react-query + Recharts |
+| `src/claudemd/claudemd-generator.ts` | line 737 | Same correction in the embedded template (escaped backtick) |
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+| `tests/unit/web/tasks-component-contract.test.ts` | Safety-net: 15 tests locking the `{ items, total, has_more }` API contract and documenting the broken consumer behaviour |
+
+### Key Code Fix
+
+Before (broken):
+```typescript
+async function fetchTasks(): Promise<Task[]> {
+  const res = await fetch('/api/tasks')
+  if (!res.ok) throw new Error('Failed to fetch tasks')
+  return res.json()           // returns TaskPage object, not Task[]
+}
+// ...
+const { data: tasks } = useQuery({ queryFn: fetchTasks })
+tasks.filter(...)             // TypeError: tasks.filter is not a function
+```
+
+After (fixed):
+```typescript
+async function fetchTasks(params: URLSearchParams): Promise<TaskPage> {
+  const res = await fetch(`/api/tasks?${params.toString()}`)
+  if (!res.ok) throw new Error('Failed to fetch tasks')
+  return res.json() as Promise<TaskPage>
+}
+// ...
+const { data } = useQuery({ queryFn: () => fetchTasks(queryParams) })
+const tasks = data?.items ?? []   // correct: array from paginated wrapper
+const total = data?.total ?? 0
+```
+
+---
+
+## New Tests (Safety-Net)
+
+File: `tests/unit/web/tasks-component-contract.test.ts`
+
+15 tests in 4 groups:
+1. **API response shape** (5 tests) — asserts `{ items, total, has_more }` structure
+2. **[CHAR] broken consumer** (2 tests) — documents the pre-fix white screen defect: `consumeTasksResponseBROKEN` returns object not array, `.filter()` throws `TypeError`
+3. **Correct consumer** (5 tests) — contract the fix satisfies: array extraction, field access, empty page
+4. **Pagination parameters** (3 tests) — default limit 50, valid page sizes [20, 50, 100], offset formula
+
+---
+
+## Regression Test Results
+
+```
+Test Files  1 failed | 28 passed (29)
+Tests       1 failed | 338 passed (339)
+```
+
+The 1 pre-existing failure (`sqlite-refactor-harness.test.ts:166 linkEventToTask`) was present before this hotfix and is unrelated (UUID validation in test fixture). 15 new safety-net tests all pass.
+
+---
+
+## Build Evidence
+
+```
+web/dist/assets/Tasks-D98y3WV2.js      (3.xx kB — new chunk)
+dist/web/static/assets/Tasks-D98y3WV2.js (copied to production path)
+```
+
+`curl -sI http://127.0.0.1:3721/` → `200 OK`
+`curl -s http://127.0.0.1:3721/ | grep -c "vite|module"` → `8` (React app, not vanilla HTML)
+`curl -s "http://127.0.0.1:3721/api/tasks?limit=1"` → `{"items":[...],"total":393,"has_more":true}`
+
+---
+
+## Verification Checklist
+
+- [x] `web/` TypeScript: `npx tsc --noEmit` → 0 errors
+- [x] Root TypeScript: `npx tsc --noEmit` → 0 errors
+- [x] `web/npm run build` → succeeds, Tasks chunk present
+- [x] Root `npm run build` → succeeds, chunk copied to `dist/web/static/assets/`
+- [x] Safety-net tests: 15/15 pass
+- [x] Full suite: 338/339 pass (pre-existing failure unrelated)
+- [x] `curl http://127.0.0.1:3721/` → 200 OK, HTML contains vite module references
+- [x] API returns `{ items, total, has_more }` shape confirmed
+- [x] `CLAUDE.md` and `claudemd-generator.ts` frontend description corrected
+- [ ] Daemon restart (requires manual: `./scripts/dev-daemon.sh restart`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winspan/claude-forge",
-  "version": "8.50.6",
+  "version": "8.51.1",
   "description": "SDLC intelligent orchestration engine for Claude Code",
   "main": "dist/cli/index.js",
   "type": "module",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "prebuild": "rm -rf dist",
-    "build": "tsc && mkdir -p dist/hooks && cp -r src/hooks/* dist/hooks/ && chmod +x dist/hooks/*.sh && chmod +x dist/cli/index.js && cp src/core/storage/schema.sql dist/core/storage/schema.sql && mkdir -p dist/daemon/launchd && cp src/daemon/launchd/*.template dist/daemon/launchd/ && mkdir -p dist/skills/official && cp src/skills/official/*.md dist/skills/official/ && mkdir -p dist/web/static && cp -r web/dist/* dist/web/static/ 2>/dev/null || cp src/web/static/index.html dist/web/static/ && cp -r src/web/static/vendor dist/web/static/ 2>/dev/null || true",
+    "build": "tsc && mkdir -p dist/hooks && cp -r src/hooks/* dist/hooks/ && chmod +x dist/hooks/*.sh && chmod +x dist/cli/index.js && cp src/core/storage/schema.sql dist/core/storage/schema.sql && mkdir -p dist/daemon/launchd && cp src/daemon/launchd/*.template dist/daemon/launchd/ && mkdir -p dist/skills/official && cp src/skills/official/*.md dist/skills/official/ && mkdir -p dist/claudemd/templates && cp src/claudemd/templates/*.md dist/claudemd/templates/ && mkdir -p dist/web/static && cp -r web/dist/* dist/web/static/ 2>/dev/null || cp src/web/static/index.html dist/web/static/ && cp -r src/web/static/vendor dist/web/static/ 2>/dev/null || true && (test -f dist/core/storage/schema.sql || (echo '[build] FATAL: dist/core/storage/schema.sql missing' && exit 1)) && (test -f dist/claudemd/templates/swarm-protocol.md || (echo '[build] FATAL: dist/claudemd/templates/swarm-protocol.md missing' && exit 1))",
     "test": "vitest run",
     "test:watch": "vitest",
     "dev:daemon": "./scripts/dev-daemon.sh",