docs: handoff 73 — Ctrl-G demo-mode F1 alias (ADR-0047 Amendment 1)

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 `</content>` / `</invoke>` 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").