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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user