@winspan/claude-forge 8.53.2 → 8.54.3

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

@@ -1,56 +0,0 @@
-# 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/claudemd-template-sync.md

@@ -1,54 +0,0 @@
-# Fix Report: claudemd-template-sync
-
-## Root Cause
-
-Template drift between `CLAUDE.md` (source of truth) and the `SWARM_PROTOCOL` constant embedded in `src/claudemd/claudemd-generator.ts`.
-
-Commit `34bb288` (v8.50.4) added the "工作流升级判定" section plus related updates to `CLAUDE.md`, but the generator's hardcoded template was never updated. As a result, `claude-forge claudemd init` on new projects would inject the stale template missing:
-
-1. Self-check item #4 (testing coverage < 50% trigger)
-2. Updated violation examples (daemon hotfix / Skills data separation / Hook queue)
-3. New Two-Phase Workflow title `(BMAD 默认路径)` with prerequisite note
-4. Entire "工作流升级判定" section: decision table, coverage quick-check command, module coverage status table, and past-violation reminder
-
-## Fix Points
-
-**File**: `src/claudemd/claudemd-generator.ts`
-**Lines changed**: 555–738 (the `SWARM_PROTOCOL` template string constant)
-
-Key changes applied:
-- Self-check expanded from 3 items to 4 (added "测试覆盖率 < 50%" trigger condition)
-- Violation examples updated to `harness-hotfix` / `refactor-safe` / `hybrid-feature-with-safety` pattern
-- Two-Phase Workflow title changed from `(Design-First)` to `(BMAD 默认路径)` + added prerequisite line
-- Inserted full "工作流升级判定" section between Agent 委托规则 and 并发规则
-- Removed stale hard-coded forge:resume block from template (resume blocks are daemon-managed at runtime, not part of the static template)
-
-## New Tests Added
-
-**File**: `tests/unit/claudemd-generator.test.ts`
-**Test count**: 8 characterization tests
-
-| Test | Assertion |
-|------|-----------|
-| 1 | Output contains `## 核心行为规则` |
-| 2 | Output contains `Two-Phase Workflow (BMAD 默认路径)` (new title) |
-| 3 | Output contains `工作流升级判定` |
-| 4 | Output contains `harness-hotfix` |
-| 5 | Output contains `refactor-safe` |
-| 6 | Output contains `测试覆盖率 < 50%` |
-| 7 | Output contains `## Agent 委托规则` |
-| 8 | Output does NOT contain `Two-Phase Workflow (Design-First)` (old title gone) |
-
-Safety-net red run: 6/8 tests failed against old template (correctly detected the bug).
-Fix green run: 8/8 tests pass.
-
-## Regression Test Results
-
-Full suite before fix: **3 test files failed, 9 tests failed**
-Full suite after fix: **2 test files failed, 3 tests failed**
-
-The 3 remaining failures (`routes-tasks.test.ts` ×2, `sqlite-refactor-harness.test.ts` ×1) are pre-existing failures caused by UUID validation on `event_id` — unrelated to this fix.
-
-TypeScript type check (`npx tsc --noEmit`): clean, no errors.
-
-Dist verification: `grep -c "工作流升级判定" dist/claudemd/claudemd-generator.js` → **3 matches** (section title, table header, column value).

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

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

@@ -1,58 +0,0 @@
-# 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-filter-pagination.md

@@ -1,80 +0,0 @@
-# Code Review — tasks-filter-pagination
-
-**Date**: 2026-05-18
-**Reviewer**: self (automated review)
-**Spec**: docs/design/tasks-list-filter-pagination-spec-20260518-0930.md
-
----
-
-## Acceptance Criteria Checklist (A1-A8)
-
-| # | Scenario | Implementation | Status |
-|---|----------|---------------|--------|
-| A1 | `GET /api/tasks?limit=10&offset=0` returns `{ items, total, has_more }` | `queryTasksFiltered` returns `TaskPage`, route returns JSON | DONE |
-| A2 | `?project=/path/foo` returns only that project's tasks | `WHERE s.project_path IN (?)` via JOIN | DONE |
-| A3 | `?project=a&project=b` OR relationship | `IN (?, ?)` clause with array | DONE |
-| A4 | `?from=...&to=...` start_time range filter | `t.start_time >= ?` / `<= ?` | DONE |
-| A5 | `?search=重构` title LIKE | `t.title LIKE ?` with `%...%` wrapping | DONE |
-| A6 | `?limit=201` clamps to 200 | Zod `.transform(v => Math.min(v, 200))` | DONE |
-| A7 | URL sync `?range=24h&search=build&page=1` survives refresh | `tasksStateToURL()` + `tasksURLToState()` in initTasksPage | DONE (manual E2E needed) |
-| A8 | Next page: offset increments, total constant | pagination buttons + offset calc | DONE |
-
----
-
-## Index Usage Evidence (EXPLAIN QUERY PLAN)
-
-### Without project filter (full table → ORDER BY)
-```
-SCAN t USING INDEX idx_tasks_start_time_session  ← composite index used
-SEARCH s USING INDEX sqlite_autoindex_sessions_1 (session_id=?)
-```
-Composite index `idx_tasks_start_time_session ON tasks(start_time DESC, session_id)` avoids sorting for the common no-filter case.
-
-### With project filter
-```
-SEARCH s USING INDEX idx_sessions_project (project_path=?)
-SEARCH t USING INDEX idx_tasks_session (session_id=?)
-USE TEMP B-TREE FOR ORDER BY
-```
-B-TREE sort occurs because the drive table is sessions (filtered by project). Acceptable for <10k rows.
-
----
-
-## Changed Files
-
-| File | Nature of change |
-|------|-----------------|
-| `src/core/storage/schema.sql` | Added `idx_tasks_start_time_session` composite index |
-| `src/core/storage/tasks.ts` | Added `queryTasksFiltered`, `queryTaskProjects`, `TaskFilter`, `TaskPage` types, `buildWhereConditions`, `mapRow` private helpers |
-| `src/core/storage/sqlite.ts` | Exposed `queryTasksFiltered`, `queryTaskProjects`; re-exported `TaskFilter`, `TaskPage` |
-| `src/web/routes/tasks.ts` | Full rewrite: Zod `TaskListQuery`, `/projects` sub-route, paginated list route, detail route unchanged |
-| `src/web/static/index.html` | Tasks sidebar nav item + `#page-tasks` HTML + `loadTasks` / `initTasksPage` / URL sync / debounce / drawer detail |
-| `tests/unit/web/routes-tasks.test.ts` | Fixed non-UUID event_ids; updated [CHAR] tests to new schema; added 14 new test cases |
-| `tests/integration/tasks-filter.integration.test.ts` | New: 10 integration tests against real SQLite |
-| `CLAUDE.md` | Fixed `前端: React + Vite + Recharts` → `原生 HTML + Vanilla JS（单文件 SPA），无打包` |
-| `src/claudemd/claudemd-generator.ts` | Same correction in SWARM_PROTOCOL template |
-
----
-
-## Breaking Change
-
-`GET /api/tasks` now returns `{ items, total, has_more }` instead of bare `Task[]`. Dashboard code (`loadDashboard`) doesn't call `/api/tasks` (only `/api/sessions`). No other callers found by grep. Scope: internal dashboard only.
-
----
-
-## Known Limitations / TODO
-
-1. **Frontend E2E (A7)** — URL state sync for range/search/page not covered by automated tests. Manual verification required against running daemon.
-2. **Title LIKE is case-insensitive for ASCII only** — CJK characters behave correctly in SQLite UTF-8, but no explicit test for mixed-case ASCII vs. UTF-8 mixes.
-3. **`/api/tasks/:taskId` still uses `queryTasks({limit:5000})`** — linear scan to find task by ID. Pre-existing issue, out of scope for this feature.
-4. **ISO 8601 string sort** — `from`/`to` params must use same precision (`.000Z`) as stored timestamps for exact boundary matching. Documented in test comments.
-5. **B-TREE sort overhead** — when filtering by project, SQLite uses a temp B-TREE for ORDER BY. Acceptable for <10k rows but would benefit from a covering index if the dataset grows.
-
----
-
-## Quality Assessment
-
-- BLOCKER issues: none
-- MAJOR issues: none
-- MINOR: `/api/tasks/:taskId` detail route still uses `queryTasks({limit:5000})` for task lookup — not introduced by this PR, pre-existing
-- NIT: `any` type in `userPrompts` map (`.tool_input as any`) — pre-existing, not introduced here

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

@@ -1,126 +0,0 @@
-# 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`)