claude@clouddev1
888be16090
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.
166 lines
8.8 KiB
Markdown
166 lines
8.8 KiB
Markdown
# 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").
|