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

## Status: backend complete (Tasks 1–12), frontend not started (Tasks 13–19)

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

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

## Resume point — Tasks 13–19 (all frontend + final)

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.

Frontend gate: `docker exec -w /app resolutionflow_frontend npx tsc -b` and
`docker exec -w /app resolutionflow_frontend npm run build` (per PROJECT_CONTEXT).

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

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