From 784373a254420bcd2851f9e48ae94904dff3612d Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Tue, 16 Jun 2026 14:41:28 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20handoff=2073=20=E2=80=94=20Ctrl-G=20dem?= =?UTF-8?q?o-mode=20F1=20alias=20(ADR-0047=20Amendment=201)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/handoff/20260616-handoff-73.md | 112 ++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/handoff/20260616-handoff-73.md diff --git a/docs/handoff/20260616-handoff-73.md b/docs/handoff/20260616-handoff-73.md new file mode 100644 index 0000000..e3dce65 --- /dev/null +++ b/docs/handoff/20260616-handoff-73.md @@ -0,0 +1,112 @@ +# Session handoff — 2026-06-16 (73) + +Short, focused handover. Continues from handoff-72 (which completed the +H2 hint-corpus verification pass). This session shipped one small +feature — a **`Ctrl-G` demo-mode alias for F1** — plus follow-on doc +hygiene. Commit `4016c3e`. + +## §1. State + +**Branch:** `main`, clean, all committed (local; **push pending** — your +step; the backlog now spans the CI merge, H2, the hint-corpus fixes, +handoffs 71/72/73, and this Ctrl-G commit). **2503 pass / 0 fail / 1 +ignored** (the long-standing `friendly` doctest), **clippy clean** +(nursery, all targets). Open Gitea issues unchanged: **#35–#38**. + +## §2. Why Ctrl-G (the problem) + +Casts are recorded with **`autocast`** (ADR-0047 demo mode: `--demo` / +`RDBMS_PLAYGROUND_DEMO`). The contextual hint overlay (ADR-0053 / H2) +opens on **F1** — but F1 reaches the app only as a terminal **escape +sequence** (`\eOP` / `\e[11~`), and **autocast cannot emit escape +sequences**. So the single most teaching-relevant overlay was +unreachable in recordings (and in presenter/teacher sessions, which also +run `--demo`). Same wall that pushed step-captions onto `Ctrl+]` (a +single control byte) rather than `Ctrl+!`. + +### Chord choice — why Ctrl-G, why not Ctrl-1 + +The user's first instinct was `Ctrl-1` (mnemonic, near F1). **Not +possible:** in a legacy terminal `Ctrl`+digit has no control byte — +`Ctrl-1` arrives as a bare `1` (would type "1" into the buffer). The +kitty keyboard protocol *would* encode it, but only as an escape +sequence (the very thing autocast can't send), and this app deliberately +does **not** push `KeyboardEnhancementFlags` (`runtime.rs` does only +`enable_raw_mode` + `EnterAlternateScreen`). So the usable space is +exactly **`Ctrl`+letter** (single legacy control bytes). After excluding +taken chords (`Ctrl-C` quit, `Ctrl-O` nav, `Ctrl+]` caption, +`Ctrl-A/E/W/K/U` readline per ADR-0049), byte-collisions +(`Ctrl-H/I/J/M/[`), flow-control (`Ctrl-S/Q`), and likely-future +(`Ctrl-R/P/N/Y/L/V`), **`Ctrl-G`** is the clean survivor (BEL/"abort" in +line editors — nothing destructive to shadow). + +## §3. What shipped (commit `4016c3e`) + +ADR-0047 **Amendment 1**. **In demo mode only**, `Ctrl-G` aliases F1: + +- Runs the *exact* F1 hint logic (`hint_key` guard in + `App::handle_key`, `src/app.rs` ~line 1226 — `key.code == F(1) || + (self.demo_mode && Ctrl-G)`), so live-input → form hint, empty input → + recent-error / getting-started. +- **Badges as `[F1]`** (not `[CTRL-G]`): `demo_badge_label` maps + `Ctrl-G → Some("[F1]")` (consulted only in demo mode — the caller + gates). So a recorded cast is **visually identical to a real F1 + press**. +- **Demo-gated:** the shipped keymap stays F1-only. Outside demo mode + `Ctrl-G` falls through to the inert catch-all (the `Char(c)` insert arm + excludes CONTROL, so no `g` is typed). +- The keybinding strip (ADR-0051) is **not** changed — F1 stays the + advertised key; `Ctrl-G` is a recorder aid and the badge already reads + `[F1]`. + +**Tests (test-first, `src/app.rs` Tier-1):** `ctrl_g_in_demo_mode_- +aliases_f1_on_input`, `…_on_empty_input`, `ctrl_g_outside_demo_mode_- +is_inert`, plus a `Ctrl-G → [F1]` assertion added to +`demo_badge_label_maps_the_invisible_keys`. All confirmed red→green; the +"inert" test passed on the pre-change code, proving the demo-gate. + +### Using it in a cast +With `--demo` active, send **`Ctrl-G`** in the autocast script wherever +you want the hint overlay to appear; the viewer sees the `[F1]` badge. + +## §4. Doc hygiene done alongside (same commit) + +- **ADR-0047 file:** removed two stray `` / `` lines + (tool-call residue accidentally committed when the ADR was authored). +- **CLAUDE.md "Things deliberately deferred":** dropped three **stale** + entries — **I1b** readline shortcuts (done, ADR-0049), **I3** tab + completion, and **I4** syntax highlighting (both done; requirements.md + even carries a 2026-06-07 reconciliation note that I3/I4 were + "shipped but marked not yet"). Only **I1** (multi-line input) remains — + it is genuinely still open (`[ ]` in requirements.md). *(This follows + the handoff-72 cleanup that removed the equally-stale m:n/C4 + + project-storage entries.)* + +## §5. Open / next (unchanged from handoff-72 §5) + +The hint corpus is trustworthy and the cast-F1 gap is closed. Roadmap: + +1. **Push** (your step). +2. **#35 (cargo fmt gate)** — precondition (CI merged) is met; the user + wants it done once, before first publication. Needs a `rustfmt.toml`- + vs-defaults decision first; tree is ~1800 hunks dirty. +3. Other open `requirements.md` items: **I1** multi-line input, **I5/B3** + in-flight cancellation, **TT4** PTY tier-4 (unwired), **DOC1**/**E2** + user docs (partial), **TT5** Windows-execution + Tier-4-in-CI, **D3** + packaging manifests. Design-first (`[~]`): **V4** session journal, + **TU1** tutorial, **C3a**, **V3**. +4. Hint follow-ups if wanted: **#36** `help` advanced-SQL, **#37** hint + clause-concepts, **#38** hint diagnostic route. + +## §6. How to take over + +1. Read handoffs 71 → 72 → 73, `CLAUDE.md`, `docs/requirements.md`. +2. Confirm green: `cargo test` (**2503 / 1 ignored**) + `cargo clippy + --all-targets` (clean). +3. For demo-mode / casting, read **ADR-0047** (+ its Amendment 1); for + the hint overlay it aliases, **ADR-0053**. +4. Workflow unchanged: phased, test-first, `/runda` + DA before commits, + ADR amendment + README index-upkeep for decided-area changes, confirm + commit messages with the user. +5. Consider a `cargo sweep` at this milestone (`target/` grows; see + CLAUDE.md "Build hygiene").