docs(handoff): PR #193 all 10 review findings resolved + 2 decisions

Findings doc gets a per-finding RESOLUTION section; HANDOFF resume point moves to
"re-push + merge" and corrects the false Task 16/17 "done" record; CURRENT_TASK
updated; two architectural decisions logged (real ai_build columns replacing the
meta convention; ad-hoc walk restored); SESSION_LOG entry added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-09 15:56:03 -04:00
parent 9afaf37fb3
commit db446e1fd6
5 changed files with 129 additions and 24 deletions

View File

@@ -13,6 +13,58 @@
---
## 2026-06-09 — L1 ai_build context lives in columns, not a hidden `meta` walked_path entry
**Context:** PR #193 review found that the intake category was smuggled into the
ai_build session's `walked_path` as a fake `{"node_type":"meta","category":...}`
entry that every consumer had to remember to skip. Most didn't: it made an
otherwise-empty walk truthy (junk `pending` proposals reached the review queue),
pushed the depth cap off by one (counted as a real step), and rendered as a blank
row in the escalations UI. Compounding it, AI-generated nodes carried no `id`, but
the advance protocol keys on `node_id` — so the walk could never advance past the
first question (the headline feature was non-functional end-to-end).
**Decision:** Add real `category`, `problem_text`, and `pending_node` columns to
`l1_walk_sessions` (migration `61dda4f615c6`) and **delete the meta-entry convention
entirely**. Intake stores `category`/`problem_text` on the session; `/next-node`
reads them off the row (no ticket re-fetch, no walked_path scan). The server assigns
every node a `uuid4().hex[:8]` id (`ai_tree_builder._assign_id`) — never the model.
`pending_node` persists the served-but-unanswered node so a refresh / StrictMode
double-mount replays it instead of firing a fresh paid LLM call.
**Rejected:** Symptom-level strip-meta fixes (filter the meta entry at each consumer).
Smaller diff, but leaves the landmine convention in place for the next consumer to
trip over — contrary to the project principle (correct architecture over minimal diff).
Asking the LLM to invent node ids: not stable, not trustworthy.
**Consequences:** `walked_path` now holds only real steps. Adding a new consumer no
longer requires knowing about a hidden entry. `WalkSessionResponse` exposes
`category`/`problem_text` (escalations UI shows the real problem). The `meta`
node_type and `_strip_meta` are gone.
---
## 2026-06-09 — Keep the L1 ad-hoc walk fallback (don't drop it)
**Context:** The Phase 2A intake rewrite dropped the `else: start_adhoc_session(...)`
branch, leaving `start_adhoc_session` with zero callers and the out_of_scope prompt
offering only Escalate/Cancel — while `L1CategoriesPage` copy still promised "Disabled
categories fall back to an ad-hoc walk or escalation." A capability silently regressed.
**Decision:** Restore it (review Finding 5 option a). Intake honors `adhoc=True`
(a new `IntakeRequest` field → `"adhoc"` outcome) and the out_of_scope prompt gained a
"Walk it ad-hoc" button. This preserves the pre-existing free-form-walk capability and
keeps the settings copy honest.
**Rejected:** Dropping ad-hoc and fixing the copy. It removes a capability techs had,
for a problem class (out-of-scope) where a free-form walk is the natural fallback before
escalation. Cheaper, but a product regression dressed as cleanup.
**Consequences:** `start_adhoc_session` has a caller again. The walker renders adhoc
sessions via its existing non-ai_build branch (free-form notes, no AI tree).
---
## 2026-05-29 — Single source of truth for plan-tier taxonomy (derive admin UI + validation from `plan_limits`)
**Context:** A prod report ("AI sessions aren't working") traced to the owner account having no paid plan (AI is plan-gated), compounded by a real bug: the admin "Change Plan" dropdown ([`AccountDetailPage.tsx:443-445`](../frontend/src/pages/admin/AccountDetailPage.tsx)) still offered the dead `team` slug (renamed to `enterprise` in migration `4ce3e594cb87`, 2026-05-07) and omitted `starter`/`enterprise`. Selecting "Team" 400s against the hardcoded allow-list in [`admin.py:994`](../backend/app/api/endpoints/admin.py#L994). The dropdown was missed during the 2026-05-07 taxonomy reconciliation because the allowed-plan list is hand-duplicated across ≥6 backend + frontend sites. Second taxonomy-drift incident.