From 888be1609070b00b4e16a799957850fe01132b90 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Mon, 15 Jun 2026 16:47:18 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20handoff=2070=20=E2=80=94=20ADR-0052=20f?= =?UTF-8?q?ollow-up=20+=20H2=20`hint`=20shipped=20(ADR-0053)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0052 vestigial-source unwind; H2 contextual hint (F1 keybinding + `hint` command) fully implemented Phases A–D, closing A1 + H2. 4 issues filed (#35–#38, incl. 3 hint/help deferrals). CI branch merged into main mid-session (D1 release work now on main). 2499 pass / 1 ignored, clippy clean. --- docs/handoff/20260615-handoff-70.md | 165 ++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/handoff/20260615-handoff-70.md diff --git a/docs/handoff/20260615-handoff-70.md b/docs/handoff/20260615-handoff-70.md new file mode 100644 index 0000000..4eeb078 --- /dev/null +++ b/docs/handoff/20260615-handoff-70.md @@ -0,0 +1,165 @@ +# Session handoff — 2026-06-15 (70) + +Seventieth handover. Continues from handoff-69 (which closed the last +four Gitea issues and left the tracker empty). This session did the +**ADR-0052 follow-up** (unwinding vestigial worker `source` plumbing), +then **designed and fully implemented H2 — the contextual `hint` +command + F1 keybinding (ADR-0053)** end to end (Phases A–D). The CI +branch was also merged into `main` mid-session (not my work — see §5). + +Net: **2 feature areas shipped, 1 new ADR (0053) + 1 ADR amendment +(0052), 4 new Gitea issues (#35–#38), the `hint` corpus (~57 teaching +blocks), and A1 + H2 closed in `requirements.md`.** + +## §1. State at handoff + +**Branch:** `main`. Working tree **clean**; all work committed. Commits +are local (push is the user's step). + +**Tests: 2499 passing / 0 failing / 0 skipped / 1 ignored** (the +long-standing `friendly` doctest). **Clippy clean** (nursery, all +targets). Breakdown: 1799 lib + 500 `it` + 200 typing-surface-matrix. + +**Open Gitea issues (4, all enhancement, all filed this session):** +- **#35** — enforce `cargo fmt` across the codebase (single reformat + + CI gate). The tree is *not* fmt-clean (~1800 pre-existing diffs); do it + once, coordinated with CI, before first publication. +- **#36** — `help` collapses advanced-SQL forms onto their simple sibling + (a `help`-list dedup artifact); they deserve distinct help content. +- **#37** — `hint` clause-concept hints (`on delete` actions, constraint + slots, `with pk`, cardinality) — a deferred `hint.concept.` + layer. +- **#38** — `hint` pre-submit-diagnostic route + the ~33 `diagnostic.*` + tier-3 blocks (deferred; `Diagnostic` carries no class key). + +## §2. ADR-0052 follow-up — vestigial worker `source` unwind (`e8fa859`) + +The first task from handoff-69 §3. ADR-0052 moved success-journaling out +of the worker, leaving the `source` that handlers threaded purely for the +old `history.log` write dead. **Bigger than the handoff estimated** (it +framed it as ~28 call-site edits): the cascade ran through ~30 worker +handlers + the `DescribeTable`/`QueryData`/`RunSelect` request fields + +their `DatabaseHandle` methods (~164 mostly-test call sites). Fully +unwound, compiler-guided, **no behaviour change** (journaling uses a +`source_for_journal` clone at the spawn, independent of the worker). The +only worker `source` left is the snapshot/undo label. Amended ADR-0052 +*Consequences* + README. (Two scope forks escalated + user-approved.) + +## §3. H2 — contextual `hint` (ADR-0053), Phases A–D — **shipped** + +The bulk of the session. ADR-0053 settles the `hint` slot ADR-0003 left +"ADR pending"; **closes A1** (all 15 app commands now exist) and +**requirements H2**. Read ADR-0053 before touching this area — it went +through three revisions and several user decisions. + +### The design (all user-chosen) +- **Two surfaces:** an **F1 keybinding** → tier-3 hint for the *live* + partial input (read-only overlay — never touches buffer/cursor/memo); + a submitted **`hint` command** → expands on the *most recent runtime + error*. No topic arg (contextual only; `help ` owns reference). +- **Tier-3 teaching layer** beneath the existing tier-1 (colour / error + headline) and tier-2 (ambient one-liner; the error `hint:` shown **by + default** since `Verbosity::Verbose` is the default). Each block is + `what` / `example` / `concept`, rendered as a `Hint` heading + aligned + labels. +- **Per-form keying** (Phase-B revision — the original per-node `hint_id` + was too coarse for multi-form commands like `add`/`drop`/`show`): a new + **`hint_ids: &[&str]`** field on `CommandNode` mirroring `usage_ids`, + resolved by `hint_key_for_input_in_mode` (reuses `usage_key`'s + form-word disambiguation + a mode-primary fallback for shared entry + words so advanced `insert` → `sql_insert`, simple → `insert`). +- **Comprehensive for v1 = command forms + 9 runtime error classes** + (the ~33 `diagnostic.*` classes were **deferred**, #38 — see §4). + +### Key files +- `src/dsl/command.rs` — `AppCommand::Hint`. +- `src/dsl/grammar/app.rs` — `HINT` node + `build_hint`. +- `src/dsl/grammar/mod.rs` — the `hint_ids` field, `hint_key_for_input_in_mode`, + the factored `pick_form_key`, and the two **comprehensiveness coverage + tests** (every node has a resolving `hint.cmd.*`; every runtime error + class has a `hint.err.*`). +- `src/app.rs` — F1 arm in `handle_key` (read-only overlay, placed before + the completion-memo clear); `note_hint_for_input` / `note_hint_for_recent_error` + / `note_getting_started` / `emit_tier3_block`; `last_error_hint_key` + state (set in `handle_dsl_failure`, cleared in `submit` for DSL + commands). +- `src/friendly/translate.rs` — `error_hint_class` (maps a `DbError` + + ctx to its `hint.err.`; mirrors `translate`'s dispatch — keep in + sync, unit-tested). +- `src/friendly/strings/en-US.yaml` + `keys.rs` — the corpus under + `hint.cmd.
` / `hint.err.` + `hint.block.*` labels + + `shortcut.hint`. +- `src/ui.rs` — ADR-0051 strip advertises **F1** (editing + default + states); 12 full-panel snapshots re-accepted. + +### Phases (one commit each unless noted) +- **A** (`050b363`) skeleton + tier-2 fallback; **B** (`4a5fd1b`) per-form + keying + 3 exemplars; **C** content in 5 batches (`4bdfce6` app, + `6429b56` DDL, `9c4d520` DML, `97970f2` advanced-SQL, `b6b98ad` runtime + errors) + `417cbc8` diagnostic deferral; **D** (`447112b`) coverage gate + + F1 strip + status flips; **/runda fix** (`329adfc`) — see §3.1. + +### 3.1 — what the final `/runda` caught (don't skip) +Per-batch substring tests masked a **presentation gap**: `emit_tier3_block` +was emitting three *bare, unlabelled* lines, deviating from the approved +exemplar format. Fixed to render a `Hint` heading + aligned `What:` / +`Example:` / `Concept:` lines, **locked by an `insta` snapshot** +(`hint_block_insert`). Also confirmed the `Next:` line (ADR D2 exemplar) +is correctly **omitted** — tier-2 ambient already owns live +position-awareness. Lesson for the next content/UI work: **add a rendered +snapshot early**; substring asserts don't see layout. + +## §4. Deferrals (all tracked, all user-confirmed) + +- **#38 diagnostic route + `diagnostic.*` blocks** — `Diagnostic` + (`walker/outcome.rs`) carries only its rendered `message`, not a class + key, so the F1 diagnostic route would need a `class` field threaded + through every diagnostic site (broad) for marginal value (tier-2 + already surfaces diagnostics; many duplicate runtime classes). F1 still + shows the useful command block when a diagnostic is present. +- **#37 clause-concept hints** — per-form is the right tier-3 granularity; + clause-level concepts are a separate `hint.concept.` layer for + later. +- **#36 `help` advanced-SQL** — out of H2's scope (touches shipped `help`). + +## §5. CI branch merged into `main` (not my work) + +Mid-session the **`ci` branch was merged** (commits `47a0816`, `138e766` ++ the `ci:`/`build:`/`docs(ci):` commits). `main` now carries a CI +pipeline, a nix flake, and **D1 cross-platform release builds** (matrix + +macOS), documented under a **new `docs/ci/adr/` namespace** (ci-001..003). +Implications for the roadmap: **D1 (cross-platform binaries) is now +substantially underway** — re-assess D1/D2/D3 status against what landed +before treating them as open. My H2 work is layered cleanly on top (all +green post-merge). + +## §6. Next session — start here + +1. **Push** (user step) — 30-odd local commits incl. the CI merge + all + of H2. +2. **Re-baseline the roadmap** against the merged CI work: D1/D2/D3 and + **TT5 CI** are partly/largely done now — read `docs/ci/adr/` and the + workflows before assuming they're open (handoff-69 §5 predates this). +3. **#35 (cargo fmt gate)** is the natural pairing with the now-merged CI + — the user wanted it done once, before first publication. +4. Other `requirements.md` open items (verify against CI merge first): + **TT4** PTY tier-4 (still unwired), **I1** multi-line input, **I5/B3** + in-flight cancellation, **V4** session journal (own ADR), **TU1** + tutorial system (own ADR). H2/A1 are now **done**. +5. The H2 deferrals (#36/#37/#38) are available if the user wants to + round out the hint/help surface. + +## §7. How to take over + +1. Read handoffs 68 → 69 → 70, `CLAUDE.md`, `docs/requirements.md`. +2. Confirm green: `cargo test` (expect **2499 pass / 1 ignored**) + + `cargo clippy --all-targets` (clean). +3. Read `docs/ci/adr/` (the merged CI work) before touching CI/release/D*. +4. For anything in the `hint` area, read **ADR-0053** first (3 revisions + + deferrals #37/#38). For journaling, ADR-0052 (+ its 2026-06-14 + follow-up note). +5. Project workflow unchanged: phased, test-first, `/runda` + DA before + commits, ADR amendment + README index-upkeep for decided-area changes, + confirm commit messages with the user. +6. Consider a `cargo sweep` at this milestone (`target/` grows; see + CLAUDE.md "Build hygiene").