# 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.<topic>`
  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 <topic>` 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.<class>`; mirrors `translate`'s dispatch — keep in
  sync, unit-tested).
- `src/friendly/strings/en-US.yaml` + `keys.rs` — the corpus under
  `hint.cmd.<form>` / `hint.err.<class>` + `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.<topic>` 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").