<!-- Keep under ~2K tokens. Old handoffs live in SESSION_LOG.md. Do not let this file accumulate history. -->

# HANDOFF.md

**Last updated:** 2026-05-30

**Active task:** Executing the **L1 AI Tree Builder Phase 2A** plan
(`docs/superpowers/plans/2026-05-29-l1-ai-tree-builder-phase-2a.md`, 19 tasks) via
subagent-driven-development on branch `feat/l1-ai-tree-builder-phase-2a`
(branched from `main` @ `87236b5`; **not pushed**, `main` untouched).

## ⚠️ 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.

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).

## Status: Tasks 1–15 DONE & committed. Tasks 16–19 remain (all frontend + final).

**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.

**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).

## Resume point — Tasks 16–19

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:** clean except this HANDOFF.md edit (committing now). Temp `_*.txt`
files under `frontend/` were scratch — delete any that remain.

## 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.