[NOTICKET] docs: add checkpoint plan for 2026-06-17 sync

Shared work plan (Sofhia + Rifqi) from the 2026-06-11 checkpoint: locked
decisions, final tool-set mapping, ownership with task status, per-tool
contracts, timeline, open questions, and a dated progress snapshot
(registry trim KM-641, tool matrix, few-shot sync done).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CHECKPOINT_PLAN_2026-06-17.md

@@ -0,0 +1,134 @@
+# Checkpoint Plan — Wednesday, 17 June 2026
+
+Working plan for Sofhia & Rifqi based on the checkpoint with mas Harry on **Thursday, 11 June 2026**.
+Goal: everything below is **merged and demo-able before the next sync on Wednesday, 17 June (afternoon)**.
+
+**Updated at: Friday, 12 June 2026** (Sofhia)
+
+> Source of truth for decisions is the meeting itself. Note: the NotebookLM summary is **stale on two points** — Data Availability Check was *eliminated* as a tool, and Success Metrics was *folded into* the Problem Statement template. Do not build either as a standalone skill.
+
+---
+
+## 0. Progress (per Fri 12 Jun — Sofhia)
+
+Dated snapshot of what landed this session. Live task status (incl. what's left) lives in §2 Ownership — this section only records the deltas + traceability.
+
+- ✅ **Tool matrix** built (xlsx, all ~10 tools + status colours) — presentation material ready.
+- ✅ **Registry trimmed to 4 active analytics** (`KM-641`, commit `66e2e4d`): `ACTIVE_ANALYTICS_TOOLS` (descriptive, aggregate, correlation, trend) vs `DEFERRED_ANALYTICS_TOOLS` (comparison, contribution, profile, segment) — specs + compute fns kept, only registry exposure withheld. Tests 206 pass, ruff/mypy clean.
+- ✅ **Planner few-shot synced**: Example A `analyze_contribution` → `analyze_aggregate` (so few-shots don't reference a deferred tool). Name renames in `examples.py` still pending (Rifqi, §2).
+
+---
+
+## 1. Locked decisions (from the 2026-06-11 checkpoint)
+
+1. **Single chat page.** The separate interview/survey page is killed. Sidebar = Knowledge menu (connect/manage data) + Analysis menu (sessions).
+2. **Data-first hard gate.** Creating a new analysis requires **≥ 1 bound data source** (server-side rejection, no empty sessions). User provides title + optional short description.
+3. **Analysis State lives in the DB.** Per-analysis row: `user_id`, `data_source_ids[]`, `interview_status` (default `not_pass`), `report_status` (default `no_report` → `V1`, `V2`, …). Explicitly **NOT cached, NOT in Redis** — the Orchestrator reads it from Postgres every turn.
+4. **Skills, not agents.** No separate interview agent. The Orchestrator routes per user turn using the Analysis State; an analytical request still executes through the existing Planner → TaskRunner → Assembler spine (static plan, no mid-run LLM).
+5. **Interview = one skill: Problem Statement.** Success metrics become fields inside the PS template (what to increase/decrease + target). Data availability check is handled by the data-first creation gate + PS validation cross-checking fields against the bound catalog — not a separate tool.
+6. **Analytics focus = 4 tools:** descriptive, aggregate, correlation, trend. The other four composites (comparison, contribution, profile, segment) are **deprioritized, not deleted** — keep the code, just don't register them. If "comparison" returns later it should be a proper statistical **test**, not a generic compare.
+7. **`describe_source` merges into the listing tool** — one call returns sources *with* their schema/metadata, fewer tools for the planner.
+8. **Report = on-demand skill.** Renders from accumulated **AnalysisRecords + the Problem Statement** — never from chat history. Each generation snapshots the record IDs it used and bumps `report_status` to `V<n>`.
+9. **Help = deterministic guide.** No LLM: read Analysis State → tell the user the next required step. Callable in any state.
+10. **Redis Cloud free tier, TTL = 1 hour**, env shared in the team group — for retrieval/query caching only, never for state.
+
+### Final tool set (~10)
+
+| Checkpoint name | Maps to (current code) | Status |
+|---|---|---|
+| `knowledge_check` | new — list user's documents + metadata | to build |
+| `data_check` | `list_sources` + `describe_source` merged (catalog-backed) | merge + rename |
+| `knowledge_retrieve` | `retrieve_documents` | rename |
+| `data_retrieve` | `query_structured` (tabular: file + DB, both working) | rename |
+| `analyze_descriptive` | `src/tools/analytics/descriptive.py` | done |
+| `analyze_aggregate` | `src/tools/analytics/aggregation.py` | done |
+| `analyze_correlation` | `src/tools/analytics/relationship.py` | done |
+| `analyze_trend` | `src/tools/analytics/temporal.py` | done |
+| `problem_statement` | new — interview skill (**Harry**) | Harry |
+| `generate_report` | new — on-demand, versioned | to design |
+| `help` | new — deterministic state guide | to build |
+
+(`problem_statement`, `generate_report`, `help` live at the orchestrator level; the TaskRunner registry holds the 4 analytics + 4 data/knowledge tools. Unregister `analyze_comparison`, `analyze_contribution`, `analyze_profile`, `analyze_segment` from the planner-visible registry — keep the modules.)
+
+---
+
+## 2. Ownership
+
+### Sofhia
+- [x] 4 analytics tools: trim registry to 4 active, tests still pass after deprioritizing the other four. (`KM-641`, commit `66e2e4d`)
+- [ ] Data/knowledge tools: merge `describe_source` into `data_check`, rename `retrieve_documents` → `knowledge_retrieve`, `query_structured` → `data_retrieve`, build `knowledge_check`.
+- [ ] Co-design `generate_report` with Rifqi (see §3).
+- [x] Tool matrix (see §4).
+
+### Rifqi
+- [ ] **Redis Cloud free tier** (~30–50 MB): create instance, set TTL = 1 h, share env vars in the group. Unblocks everyone's local testing — do this first.
+- [ ] Co-design `generate_report` with Sofhia.
+- [ ] Verify planner tool list matches the trimmed registry (4 analytics + 4 data/knowledge) and few-shots don't reference removed tools.
+
+### Shared (Sofhia + Rifqi)
+- [ ] `generate_report` design + skeleton: input = AnalysisRecords for the session + Problem Statement from Analysis State; output = versioned artifact; bumps `report_status`. Agree on the contract even if rendering is stubbed for Wednesday.
+- [ ] `help` skill: deterministic — read Analysis State, return the next required step. Small, do it together or whoever finishes first.
+- [ ] Tool behavior smoke test end-to-end on an easy case (descriptive/aggregate path), per Harry's ask: "robust tools before agents."
+
+### Harry (dependencies — not ours, but we block on them)
+- `problem_statement` skill + PS template (incl. increase/decrease target fields).
+- Analysis State class + DB table, frontend analysis-builder step.
+- Merging our PRs (he auto-merges; he clones from latest after).
+
+---
+
+## 3. Per-tool behavior contract (how to build each one)
+
+Harry's framing: for every tool, define **goal / trigger / input / process / output**, and behave like a Claude-style skill — if a required argument is missing, respond with a polite feedback message asking for it (e.g. table/column name), never guess silently.
+
+- **`knowledge_check`** — "what documents do I have?" → list documents with name, type, uploaded-at.
+- **`data_check`** — "what data do I have?" → sources (file + DB) with schema/metadata from the data catalog, created/uploaded timestamps.
+- **`knowledge_retrieve`** — RAG over uploaded documents; returns passages with source attribution.
+- **`data_retrieve`** — query tabular data (file + DB) via QueryIR; output consumable by the `analyze_*` tools.
+- **`analyze_*` (4)** — require valid table/column references; if missing or wrong, return actionable feedback instead of guessing.
+- **`generate_report`** — on-demand only (never auto); post-pass gated; renders from AnalysisRecords + PS; snapshots record IDs; bumps version.
+- **`help`** — no LLM; state → next step. Repeating it is fine, that's its job.
+
+---
+
+## 4. Tool matrix (deliverable for the sync)
+
+Harry explicitly asked for a matrix covering every tool. Produce one sheet/markdown table with columns:
+
+`tool | goal | trigger (when the orchestrator calls it) | input | process | output | gated by interview_status? | status (done / in progress / planned)`
+
+Use the tool set table in §1 as the row list. This doubles as the presentation material on Wednesday.
+
+---
+
+## 5. Day-by-day
+
+| Day | Target |
+|---|---|
+| **Thu 11** | Checkpoint meeting + task split with Harry. |
+| **Fri 12 (today)** | ✅ Registry trimmed to 4 analytics + few-shot synced (Sofhia, KM-641). ✅ Tool matrix built. ⏳ Redis Cloud + env share (Rifqi). |
+| **Mon 15** | Data/knowledge tools done (`data_check` merge, renames, `knowledge_check`). `generate_report` contract agreed. |
+| **Tue 16** | `help` skill done. `generate_report` skeleton wired to AnalysisRecord. Tool matrix drafted. End-to-end smoke test on the easy path. |
+| **Wed 17 (AM)** | Buffer: fix fallout, finalize matrix, rehearse the demo flow. |
+| **Wed 17 (PM)** | **Sync with Harry.** |
+
+---
+
+## 6. Open questions to confirm with Harry on Wednesday
+
+1. **Gate scope.** Proposal: keep the fast path + exploration tools (`knowledge_check`, `data_check`, retrieves, `help`, arguably `descriptive`) available **pre-pass**; gate only the insight tools (correlation, trend, report). Hard-gating everything risks frustrating users who just want to look at their data.
+2. **Who flips `interview_status` to `pass`?** Proposal: a deterministic validator (PS template slots complete + fields cross-checked against the bound catalog) makes the call — the LLM conducts the conversation but never decides the pass. ("Conversational skin, deterministic skeleton.")
+3. **Skills vs spine — one sentence to lock in writing:** *"Skills are registry tools executed by the existing Planner → TaskRunner → Assembler spine; the Analysis State gate is a pre-check in the Orchestrator."* This keeps the new flow and the locked architecture fully compatible.
+4. `generate_report` invocation goes through the same gate (post-pass only) — confirm.
+
+---
+
+## 7. Definition of done for Wednesday
+
+- [ ] All team PRs merged; Harry unblocked on the Analysis State class.
+- [ ] Registry exposes exactly 4 analytics + 4 data/knowledge tools, all passing local tests.
+- [ ] Redis Cloud shared and working locally for all three of us (TTL 1 h).
+- [ ] `help` works against a (possibly stubbed) Analysis State.
+- [ ] `generate_report` contract written; skeleton callable.
+- [ ] Tool matrix ready to present.
+- [ ] One end-to-end happy path runs: create analysis (with data) → blocked pre-pass → interview stub passes → descriptive/aggregate answer → record persisted.