docs(handoff): Tasks 1-15 done (backend + frontend 13-15); resume at Task 16

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.ai/HANDOFF.md

@@ -9,72 +9,77 @@
 subagent-driven-development on branch `feat/l1-ai-tree-builder-phase-2a`
 (branched from `main` @ `87236b5`; **not pushed**, `main` untouched).
 
-## ⚠️ Tooling note (read first)
-This session repeatedly hit an unreliable **Bash output channel** — intermittently
-returns stale/cached output (e.g. a unique `echo` probe returned a prior `wc`
-result) or fabricated success. The **Read/Write/Edit channel stayed reliable.**
-Two derived lessons:
-- Run backend tests as `docker exec resolutionflow_backend pytest <path> --override-ini="addopts=" -q`.
-  Do **NOT** use `-p no:cov` — `pytest.ini` bakes `--cov` into `addopts`, so disabling
-  the cov plugin makes `--cov` an unrecognized arg and pytest exits non-zero **before
-  running**, which silently mislabels `&& echo PASS || echo FAIL` chains as failures.
-- After any Bash result that matters, cross-check against a `Read`/`grep` of the file.
-  If a probe returns stale output, **stop and recover the shell** before committing.
+## ⚠️ Tooling note (read first — why this session stopped at Task 15)
+The harness's **Bash output channel AND the Read tool both became intermittently
+unreliable** late in the session — returning stale/cached output and, critically,
+*fabricating plausible content* (a Read of `router.tsx` invented an `L1CategoriesPage`
+import on line 13 that does not exist; confirmed absent by `grep -c` = 0 and the page
+file not existing). Work stopped at Task 16 because authoring router/settings edits
+requires first reading those files accurately, and that could no longer be trusted.
+**On resume: confirm the shell is reliable** (write a unique sentinel to a file, read
+it back; cross-check any Read against `grep`). Verified facts in this doc were
+sentinel-confirmed.
 
-## Status: backend complete (Tasks 1–12), frontend not started (Tasks 13–19)
+Backend test invocation that works:
+`docker exec resolutionflow_backend pytest <path> --override-ini="addopts=" -q`
+Do **NOT** use `-p no:cov` — `pytest.ini` bakes `--cov` into `addopts`; disabling the
+cov plugin makes `--cov` unrecognized so pytest exits before running, silently turning
+`&& echo PASS || echo FAIL` chains into false FAILs (this cost ~an hour of confusion).
+Frontend gate via file-redirect:
+`docker exec -w /app resolutionflow_frontend sh -c 'npx tsc -b > /app/_o.txt 2>&1; echo EXIT=$? >> /app/_o.txt'`
+then Read `frontend/_o.txt` (frontend is bind-mounted at /app).
 
-**Tasks 1–12 — DONE & committed** (17 commits `16b9abf`…`04b5511`). Last reliable
-full run: **114 passed** across all 11 Phase 2A backend test files
-(test_l1_ai_build_model, test_account_l1_categories_column, test_flow_proposal_l1_source,
-test_l1_category_service, test_ai_tree_builder, test_match_or_build,
-test_l1_session_service, test_l1_endpoints, test_l1_api_ai_build, test_l1_categories_api,
-test_l1_ai_build_flow). 3 alembic migrations applied; head is `1fd88a68b145`.
+## Status: Tasks 1–15 DONE & committed. Tasks 16–19 remain (all frontend + final).
 
-What shipped backend-side:
-- Migrations/models: `ai_build` session kind; `accounts.enabled_l1_categories` (10-key
-  default); `FlowProposal.l1_session_id` (+ `source_session_id` nullable + exactly-one
-  CHECK), `FlowProposalSummary` schema made source_session_id optional + l1_session_id added.
-- Services: `l1_category_service` (defaults + hard floor + get/set), `ai_tree_builder`
-  (constrained node gen, validate, depth cap, `normalize_walked_path`, **skips `meta`
-  entries**), `match_or_build` (match→suggest→build bands; flow_id normalized to str),
-  `l1_session_service.start_ai_build_session` / `advance_ai_build` (records node incl.
-  `node_text`) / flywheel capture in `resolve` / engineer notify in `escalate`.
-- Notifications: `l1.session.escalated` event + link `/escalations` + body/title templates;
-  `_resolve_recipients` now treats an explicit empty `target_user_ids` as "no recipients".
-- API: `/l1/intake` dispatches via `match_or_build` (build seeds a hidden
-  `{"node_type":"meta","category":...}` walked_path entry); `POST /l1/sessions/{id}/next-node`;
-  `GET /l1/escalations` (require_engineer_or_admin); `GET|PATCH /accounts/me/l1-categories`;
-  `require_account_owner_or_admin` dep. Config action keys `l1_realtime_build`/`l1_classify`.
+**Backend (Tasks 1–12)** — 17 commits `16b9abf`…`04b5511` + handoff `fdac72e`.
+Last full run: **114 passed** across all 11 Phase 2A backend test files. 3 alembic
+migrations applied; head `1fd88a68b145`. Shipped: `ai_build` session kind;
+`accounts.enabled_l1_categories`; `FlowProposal.l1_session_id` (+ nullable
+source_session_id + exactly-one CHECK + schema made optional); `l1_category_service`;
+`ai_tree_builder` (constrained gen, validate, depth cap, `normalize_walked_path`,
+**skips `meta` entries**); `match_or_build` (bands; flow_id→str); session-service
+`start_ai_build_session`/`advance_ai_build` (stores `node_text`)/flywheel capture in
+`resolve`/engineer notify in `escalate`; `l1.session.escalated` notification (+ link
+`/escalations` + `_resolve_recipients` honors explicit empty list); API
+`/l1/intake` (dispatch; build seeds hidden `{"node_type":"meta","category":...}`
+walked_path entry), `POST /l1/sessions/{id}/next-node`, `GET /l1/escalations`,
+`GET|PATCH /accounts/me/l1-categories`, `require_account_owner_or_admin` dep.
 
-## Resume point — Tasks 13–19 (all frontend + final)
+**Frontend (Tasks 13–15) — committed, each tsc -b + eslint clean (sentinel-verified):**
+- `9c8f1e2` Task 13 — `types/l1.ts` (+ai_build, IntakeOutcome/Result, NearMiss, TreeNode,
+  NextNodeRequest/Result, L1Categories) + `api/l1.ts` (intake→IntakeResult; nextNode,
+  escalations, getCategories, setCategories). nextNode body carries `node_text`.
+- `7b1e44a` Task 14 — `L1Dashboard.tsx` dispatch on outcome (matched/build→walker;
+  suggest→use-flow/build-new; out_of_scope→escalate-without-walk prompt).
+- `a3f0c21` Task 15 — `L1WalkTreeVariant.tsx` renders ai_build nodes via /next-node +
+  disclaimer banner (`bg-warning/10` — note: `*-dim` tokens are NOT defined as
+  `--color-*-dim`, use `/10` opacity modifiers); `L1WalkPage.tsx` routes ai_build →
+  tree variant. NOT browser-verified (couldn't launch chromium / shell degraded).
 
-1. **Task 13 — frontend api/types.** `frontend/src/types/l1.ts` + `frontend/src/api/l1.ts`
-   are still **Phase-1 stubs** (api/l1.ts is a rough 36-line stub — read it carefully).
-   Add: `IntakeOutcome`/`IntakeResult` (outcome matched|suggest|out_of_scope|build,
-   optional session fields, near_miss, category), `TreeNode` union, `NextNodeResult`,
-   `L1Categories`; methods `nextNode`, `getCategories`, `setCategories`, `escalations`;
-   retype `intake` to `IntakeResult`. **Carry-forward:** `nextNode` body must include
-   `node_text` (the rendered node text — backend `advance_ai_build` stores it).
-2. **Task 14** — `L1Dashboard.tsx` dispatch on `outcome` (matched/build → walker;
-   suggest → prompt; out_of_scope → adhoc/escalate prompt).
-3. **Task 15** — `L1WalkTreeVariant.tsx` real node rendering via `/next-node` + disclaimer
-   banner; pass `node.text` as `node_text`; terminal nodes → existing Resolve/Escalate.
-4. **Task 16** — new `pages/account/L1CategoriesPage.tsx` + route + nav (owner/admin gated).
-5. **Task 17** — `ProposalDetail.tsx` L1-source block (branch on `l1_session_id`);
-   `EscalationQueuePage.tsx` L1-escalations section via `l1Api.escalations()`.
-6. **Task 18** — extend `frontend/e2e/l1-workspace.spec.ts` (network-stubbed); rely on CI
-   for the run (chromium can't launch here).
-7. **Task 19** — full backend suite + `tsc -b`/`npm run lint`/`npm run build`; migration
-   downgrade/upgrade roundtrip; push branch + open PR to `main` listing deferred items.
+## Resume point — Tasks 16–19
 
-Frontend gate: `docker exec -w /app resolutionflow_frontend npx tsc -b` and
-`docker exec -w /app resolutionflow_frontend npm run build` (per PROJECT_CONTEXT).
+16. **`pages/account/L1CategoriesPage.tsx`** (does NOT exist yet) — checkbox list of
+    `available` toggling `enabled` via `l1Api.getCategories/setCategories`; read-only
+    hard-floor list. Register lazy route under the `account` children in `router.tsx`
+    (the L1CategoriesPage import is NOT yet there — verify) and add a link card in
+    `AccountSettingsPage.tsx` (AccountLayout has no sidebar nav — see CLAUDE.md
+    "Account sub-page"). Gate visibility to owner/admin via `usePermissions`.
+17. **`ProposalDetail.tsx`** — branch on `l1_session_id` to show an L1-source block
+    instead of the `/pilot/{source_session_id}` link (add `l1_session_id?: string|null`
+    to its proposal type). **`EscalationQueuePage.tsx`** — add an "L1 escalations"
+    section via `l1Api.escalations()`.
+18. **`frontend/e2e/l1-workspace.spec.ts`** — network-stubbed AI-build flow; rely on CI
+    to run it (chromium can't launch here).
+19. **Final:** full backend suite + `tsc -b`/`npm run lint`/`npm run build`; migration
+    downgrade/upgrade roundtrip (head `1fd88a68b145`, down 3); push branch + open PR to
+    `main` listing deferred items (KB grounding/connectors, PSA reassign, escalation
+    package, AI chat handoff, proposal-matching). Then run requesting-code-review +
+    finishing-a-development-branch per the subagent-driven-development skill.
 
-**Working tree:** uncommitted at handoff time — only this `HANDOFF.md` edit (and possibly
-`backend/tests/test_l1_api_ai_build.py` if its last lint-clean edit wasn't committed; verify
-with `git status` once the shell recovers, then commit WIP).
+**Working tree:** clean except this HANDOFF.md edit (committing now). Temp `_*.txt`
+files under `frontend/` were scratch — delete any that remain.
 
-## Carry-forward (Phase O — separate, still user-side, gated on EIN)
-Phase O self-serve cutover (Stripe live-mode, apex DNS, Railway prod env, flag flip) remains
-the prior active task — all code blockers closed; blocked on user's EIN. See SESSION_LOG /
-git history for detail. Not touched this session.
+## Carry-forward (Phase O — separate, user-side, gated on EIN)
+Phase O self-serve cutover (Stripe live-mode, apex DNS, Railway prod env, flag flip)
+remains the prior active task; all code blockers closed, blocked on user's EIN. Not
+touched this session.