Status Tracking + Guided Flows Implementation Plan

Spec: docs/superpowers/specs/2026-07-18-public-conversation-features.md (features 3 & 4).
Features 1 (clarify-before-answer) and 2 (English mode) shipped 2026-07-18 with TDD; this plan covers the remaining two.

⚠️ Discovery 2026-07-18: Feature 3 (gated-SQL status tracking) DROPPED for PP/Apostille

Efran asked "what would the public ask about PP/Apostille that they can't do
themselves?" The evidence says: very little that a gated-SQL status lookup
would serve. The public RAG corpus already documents the self-service
reality:

• PT Perorangan (PP) — the citizen applicant submits from their own AHU
  Online account and sees a live status dashboard (Draft → Sudah Bayar →
  Dikirim → Menunggu Konfirmasi → Sertifikat Terbit) and downloads the
  certificate themselves (corpus: "STATUS PERMOHONAN PT PERORANGAN DAN
  ARTINYA").
• Apostille — LOGIN at elayanan.ahu.go.id, submit, get an AP-/LGL-
  number, track in-account, collect at Kanwil (corpus: "ALUR PERMOHONAN
  APOSTILLE"). The only genuinely-public (no-login) lookup — certificate
  authenticity by QR / cert number — already exists as an official AHU
  public page ("VERIFIKASI KEASLIAN SERTIFIKAT APOSTILLE").

So a chatbot per-application status lookup would (a) duplicate the applicant's
own portal dashboard, worse; (b) require re-implementing identity verification
to prove they own application #X — a PII/security burden the portal already
solved with login; (c) need PP/Apostille DBs wired to the public agent, which
they are NOT (verified: app/config.yaml connects only ahu-badan-hukum +
internal dash). Near-zero marginal value at real cost. Dropped.

The real public gap is entirely informational (pre-application clarity, status
interpretation, troubleshooting) → served by RAG + the guided flows /
status-meaning explainer in Feature 4, which the corpus already covers ~90%.

Feature 3 tasks below are retained only for historical context / the SABH
pesan-nama demo rule (which pre-exists); do not build gated-SQL status tracking
for PP or Apostille.

Key scoping fact (verified 2026-07-18): the public agent's app/config.yaml connects ONLY ahu-badan-hukum (SABH MySQL) + the internal dash Postgres. There is NO PP (ahu-ptp) or Apostille DB connection (a commented-out ahu-billing-simpadhu block exists as a template).

Feature 3 — Application status tracking (public, gated)

Task 3.1: Identify status-bearing tables/columns

• Sources: docs/knowledge-sources/agent_business_knowledge.py, gen_help_chunks.json, and ahu-codebase/ahu-online/protected/modules/sabh (models for transaksi/permohonan status enums).
• Deliverable: table name(s) + status/tanggal columns + identifier column (nomor transaksi/voucher) + PIC columns (nama_pemohon, email_pemohon or equivalent) for: pendirian PT status; (if present in SABH) perubahan status.
• Record enum→label mapping (status codes → human copy) in the rule body.

Task 3.2: Business-rule seed templates

• File: apps/internal-web/src/app/api/admin/knowledge/seed-templates/route.ts — add status_pendirian_pt (and any sibling flows found in 3.1) following the existing verify_pesan_nama template shape: trigger phrases → ask for identifier → verify PIC via WHERE-only fields → reveal ONLY status/tanggal/tahap columns.
• Rules must state: PIC fields never displayed; single-row lookup allowed only because the table is pre_aggregated-listed; refuse when verification fails.

Task 3.3: Policy defaults

• infra/policy/policy_defaults_shared.json (consumed by both apps/public-web/src/lib/orchestrator/policy/defaults.ts and apps/public-agent/dash/policy/defaults.py): add the status tables to allowed_tables + pre_aggregated_tables; add PIC/status-adjacent PII columns to disallowed_columns if not already.
• Tests: extend apps/public-web/tests/orchestrator/sql-guard.test.ts (single-row lookup on the new table passes; PII column selection still fails) and apps/public-agent/tests/policy/ equivalents (these need Postgres — Docker/ship-time).

Task 3.4: Planner routing

• steps/plan.ts prompt: status-tracking questions ("cek status permohonan/transaksi …") are NOT identity refusals — route to public_data; the agent's business rule handles verification. Add a routing example.
• Test: plan-refusal-codes.test.ts sibling case — a status question with a stubbed plan reply routes rather than refuses (prompt-level; assert the system prompt contains the routing rule).

Task 3.5: Evals + verification

• apps/public-agent/dash/evals/ahu_test_cases.py: one case per new rule (rubric: MUST verify PIC before reveal; MUST NOT echo other rows).
• Staging E2E after deploy: real status question through /tanya (temp session), verify gated flow.

Feature 4 — Guided procedural flows / wizard (public)

Task 4.1: Flow content (PP first)

• Author flow articles: pendaftaran-pp (PP registration, PP-priority), apostille-permohonan, pendirian-pt — numbered steps, one action per step, official links (SIMPADHU/AHU Online), prerequisites per step.
• Ingest via the existing knowledge path (docs/knowledge-sources/ runbook + admin ingest); NO ai-ahu-rag repo changes.

Task 4.2: Compose flow-mode instruction

• steps/compose.ts: when tool results contain a flow article marker ([FLOW: prefix in the article body), instruct: present the CURRENT step only ("Langkah N dari M"), end with the next action. Bilingual via existing lang opt.
• Emit a trailing machine line SUGGEST: ["…","…"] (strict format) the orchestrator strips from content.
• Tests in steps.test.ts: flow marker → stepwise instruction present; SUGGEST line never reaches delta events.

Task 4.3: Suggestions SSE event

• sse.ts: suggestions(items, id) event; orchestrate parses the compose SUGGEST line → emits after references. Checkpointed like other frames (SSE-resume safe).
• packages/streams chat-types: add { type: "suggestions"; items: string[] } StreamEvent; NativeProvider maps it (verify against the orchestrator SSE consumer path used by /tanya — TanyaStream).
• Tests: orchestrate test (mock compose yields SUGGEST) → event: suggestions frame emitted, content clean.

Task 4.4: Chips UI

• SuggestedFollowups.tsx: prefer server-provided suggestions from the latest assistant message (new suggestions?: string[] on Message) over static category chips; fallback unchanged.
• Component test (existing chat test setup) + visual check via staging.

Ship checklist (both features)

• pnpm check + agent pytest green; mirrors byte-identical; spec/plan/completion notes; deploy via build-and-ship → deploy-staging; staging E2E; ROADMAP updated.