Guided-flow engine — status, ship checklist, backlog (ADR-0169)

Consolidated handoff after the build + live-dogfood + polish arc.

• Status: built · live-verified · gated off · ready for review/rollout
• Date: 2026-07-04

---

What’s built (13-commit stack on feat/…, all gated off)

PR	Slice
#376	Vertical persona template gallery + ADR-0167/0168 + CONTEXT glossary + moat/positioning
#377	ADR-0169 engine design
#378	toolsEnabled enforcement (legacy-default → inherit-all fallback)
#379	Engine core — state machine + updateFlow tool
#380	personas.flow column + migration 0072 + guidedFlows flag + prompt guidance
#381	Activation in /api/chat + real-DB integration test
#382	Completed-flow meter (audit-derived)
#383	Persona flow API (self-serve config)
#384	Tenant usage endpoint
+fixes	dogfood/polish fixes (below), the /flow-test demo page

Runs only when guidedFlows (default false) is on AND a persona has a flow AND the turn is conversation-backed. Merging changes nothing until enabled.

What’s verified (live, on demo)

Drove the flow end-to-end on app-demo.puccha.ai / demo-kb: elicits (asks use-case + team size) → recommends the right package, consistently (Team ฿7,900, no drift to Growth) → full formatted reply → completes + bills once (metered=1, one flow.completed audit). Grounded in real pricing, never invents.

5 bugs the dogfood found (unit/integration tests mock tool calls, so all were invisible), all fixed

1. toolChoice:'none' (retrieve-then-read) suppressed updateFlow → flow stalled at eliciting.
2. Haiku wouldn’t call updateFlow → imperative front-loaded guidance.
3. Haiku won’t emit a structured Draft → server-side completion (deliver a substantive reply in drafting = flow complete).
4. Cross-turn package drift (Growth vs Team) → consistency anchor (recommend from collected slots + prior recommendation).
5. Replies truncated on low-maxTokens plans → floor output budget at 1200 for active flows. Plus polish: crisper turn-1 elicitation; card-like markdown rendering on the test page.

⚠️ Ship checklist (order matters)

1. Apply migration 0072 to dev ✅ / uat ⬜ / prod ⬜ — BEFORE the code deploys. resolvePersona SELECTs the flow column, so any env running the code without the column has broken chat. CI does not run migrations.
2. Merge #376/#377/#378 (independent) + the chain #379 → #380 → #381 → #382 → #383 → #384 in order.
3. Verify chat is unchanged post-deploy (everything’s gated off).
4. Enable guidedFlows for a tenant (flag-version data for Business+, or a per-tenant override) + give a persona a flow (runbook SQL) → dogfood → promote.
5. Remove/keep the /flow-test route — it’s non-prod-gated (404s in prod) but is demo-only; drop it before it’s permanent.

Runbook with exact SQL: guided-flow-dev-enablement.md. Onboarding + worked example: guided-flow-onboarding-playbook.md.

Phase-2 backlog (none block a demo)

• Structured Card system — typed draft fields per draftKind + native renderers (widget cards, LINE Flex). Hard part: Haiku’s unreliable structured output → likely needs draft schema + validation + retry, or a second extraction step, or Sonnet for the draft step. (Today: draft = text summary; test page renders markdown.)
• Turn-1 elicitation — Haiku still prepends a greeting before asking; acceptable but could be crisper.
• maxTokens-for-flows — done (floor 1200); revisit per draftKind.
• Persona config UI form — thin client on the flow API (#383); needs live visual QA.
• Completed-flow add-on billing — wire countCompletedFlows (#382/#384) into PLAN_META allowance/overage + the usage tile.
• External-API tools (live availability/booking) — deferred httpTool + tenant_integrations; a later ADR.

Demo environment note

app-demo.puccha.ai currently runs this unmerged branch (deployed --branch=main so login works). Demo’s nightly reset clears data, not deployed code — redeploy main to restore demo when done testing.