resolutionflow/.ai/HANDOFF.md

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.