docs: amend handoff 49 — record /runda round 2 closure

docs/handoff/20260528-handoff-49.md

@@ -1,25 +1,31 @@
 # Session handoff — 2026-05-28 (49)
 
-Forty-ninth handover. **ADR-0038 is done.** Every catalogue row of the
+Forty-ninth handover. **ADR-0038 is done** — and twice DA-audited.
-DSL → SQL teaching echo is implemented, every echo round-trips per
+Every catalogue row of the DSL → SQL teaching echo is implemented,
-line per the §1 copy-paste contract, every §6 category-3 line surfaces,
+every echo round-trips per line per the §1 copy-paste contract,
-and the §4 de-emphasised styled-runs rendering polish landed in
+every §6 category-3 line surfaces, the §4 de-emphasised styled-runs
-`2aab457`. Docs in sync. If you continue, pick a fresh feature; if
+rendering polish landed in `2aab457`, and a closing /runda Devil's-
-you're triaging, ADR-0038 won't surprise you.
+Advocate pass over the polish (`6840b92`) pinned three minor wiring
+gaps. Docs in sync. If you continue, pick a fresh feature; if you're
+triaging, ADR-0038 won't surprise you.
 
 ## §1. State at handoff
 
-**Branch:** `main`. **HEAD `2aab457`.** **Tests: 2019 passing, 0
+**Branch:** `main`. **HEAD `6840b92`.** **Tests: 2020 passing, 0
 failing, 0 skipped, 1 ignored.** **Clippy: clean**
 (`--all-targets -D warnings`, nursery).
 
 Commits since handoff-48's `df5c4e2`:
 
 ```
+6840b92 test: /runda round 2 — pin TeachingEcho kind + cat-3 prose wiring
+63b2927 docs: session handoff 49 — ADR-0038 done, M4 + ADR statuses in sync
 2aab457 feat: DSL→SQL teaching echo — §4 styled-runs polish (ADR-0038)
 ```
 
-(Plus this handoff + lockstep doc updates landing alongside it.)
+The first version of this handoff went out with `63b2927` at HEAD;
+this amendment (committed after `6840b92`) records the closing
+/runda round 2 below.
 
 ## §2. ADR-0038 — done
 
@@ -34,12 +40,77 @@ The feature shipped across **five** commits, the last of which is the
 | `e6ad1ae` | 3 | category-3 prose — `change column --dont-convert` *caveat* (the other two cat-3 lines were already in place via `client_side.*` keys) |
 | `2aab457` | 4 (polish) | §4 styled-runs rendering — `OutputKind::TeachingEcho` with dimmed prefix + advanced-mode lex of the SQL; `OutputStyleClass::Hint` for every cat-3 prose line |
 
-Plus the /runda DA cleanup at `5cb105b` (doc-drift + Bucket C
+Plus **two** /runda Devil's-Advocate passes — `5cb105b` after
-explicit tests).
+Phase 3 (doc-drift + Bucket C explicit no-echo tests) and
+`6840b92` after the polish (kind assertions on every echo arm +
+the broader-scope `client_side` notes pinning, see §3a below).
+Neither pass escalated.
 
 ADR-0037 and ADR-0038 both **Accepted** with implementation notes
 referencing every shipping commit.
 
+## §2a. /runda round 2 findings (closed by `6840b92`)
+
+A second Devil's-Advocate pass over the polish surfaced three
+test-coverage gaps the polish itself had left behind. All three were
+closed in `6840b92`; tests-only commit (+98 lines in `src/app.rs`),
+no production code touched.
+
+- **`bucket_a_success_events_render_the_teaching_echo_beneath_ok`** and
+  **`bucket_b_multi_line_echo_renders_one_line_per_statement_beneath_ok`**
+  only checked line *text*. After the polish, every echo line is
+  pushed via `push_teaching_echo` and carries
+  `OutputKind::TeachingEcho` — and the kind is what fires
+  `ui::render_output_line`'s dim-prefix + advanced-lex branch. A
+  regression to plain `System` would leave the text intact while
+  silently breaking the styling. The `assert_echo_beneath_ok`
+  helper now pins `kind == TeachingEcho` on every event arm the
+  bucket_a test covers (six arms in one shot); the bucket_b test
+  pins it on each of the three multi-statement lines.
+- **`add_column_client_side_notes_render_as_category_three_prose`**
+  (new) pins the broader-scope polish: `handle_dsl_add_column_success`'s
+  illuminating `client_side_notes` (shortid / serial auto-fill, per
+  `client_side.auto_fill_*` keys) now route through
+  `push_category_three_prose`, producing a System line with a
+  whole-text Hint span. The closely-related caveat path was already
+  pinned by `polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span`;
+  this completes the cat-3 prose coverage symmetrically.
+
+What the round-2 pass *verified clean* (no action needed) — kept
+here as a flight log so the next session doesn't re-walk the same
+ground:
+
+- All four `OutputKind` matches in `ui.rs` (tag_len, tag, Echo-
+  branch detection, body_style) handle the new variant; no other
+  code matches on `OutputKind`.
+- `OutputStyleClass::Hint` resolution works on both light + dark
+  (`hint_class_resolves_to_muted_foreground`).
+- ADR-0028 §7 OOS "no re-styling existing output" is not violated:
+  ADR-0038 takes ownership of styling its own cat-3 content; the
+  broader-scope was user-confirmed and recorded.
+- The hybrid styling (custom path for SQL via `lex_to_runs` +
+  `styled_runs` for prose) follows the precedent established by
+  `OutputKind::Echo` / ADR-0022 §5; ADR-0028 §5 anticipates this
+  ("any output line may now carry rich styling").
+- Replay bypass unchanged; no AI attribution anywhere; clippy clean.
+
+Acceptable observations the round-2 pass left *documented but not
+fixed* — none warranted escalation:
+
+- The `2aab457` commit message and the `en-US.yaml` comment overstate
+  the reason `TEACHING_ECHO_LABEL` became a const ("i18n template
+  couldn't provide that"). Reality: simpler + avoids resolving i18n
+  per render (a hot path). Historic — not amending; this handoff
+  is the more accurate forward-looking reference.
+- The two rendering-path tests
+  (`teaching_echo_line_renders_dim_prefix_and_lexed_sql`,
+  `category_three_prose_line_renders_all_dim`) only use the dark
+  theme; the rendering logic is theme-agnostic and the class
+  resolution is pinned for both, so this is pedantic-incomplete
+  rather than a real gap.
+- No full-pipeline integration test driving submit → spawn → render
+  (same observation as §4 below, restated for completeness).
+
 ## §3. What the polish (Phase 4) does, in shape
 
 Per ADR-0038 §4 + §6, the de-emphasised styled-runs treatment landed
@@ -84,17 +155,20 @@ prose line, matching §6's "de-emphasised prose line" wording.
 | `[client-side] --dont-convert kept …` | `push_category_three_prose` (caveat path) | `[system]` tag + whole-body dim |
 | structure render, row counts, etc. | `note_system` | unchanged |
 
-**Coverage:** four new tests pin the polish — `ui::tests::
+**Coverage:** four new tests landed with the polish itself
-teaching_echo_line_renders_dim_prefix_and_lexed_sql` (asserts the
+(`2aab457`) — `ui::tests::teaching_echo_line_renders_dim_prefix_and_lexed_sql`
-dim prefix span + keyword-coloured SQL spans confirm advanced-mode
+(asserts the dim prefix span + keyword-coloured SQL spans confirm
-lex), `ui::tests::category_three_prose_line_renders_all_dim`
+advanced-mode lex), `ui::tests::category_three_prose_line_renders_all_dim`
-(whole-text Hint coverage), `ui::tests::
+(whole-text Hint coverage), `ui::tests::hint_class_resolves_to_muted_foreground`
-hint_class_resolves_to_muted_foreground` (theme resolution across
+(theme resolution across both palettes), and
-both palettes), `app::tests::
+`app::tests::polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span`
-polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span`
+(App-side wiring kinds + styled_runs shape on the caveat path). The
-(App-side wiring kinds + styled_runs shape). The pre-existing echo
+pre-existing echo tests pass unchanged — the text content is
-tests pass unchanged — the text content is identical, only styling
+identical, only styling changed. The /runda round 2 (`6840b92`)
-changed.
+added three more (see §2a): kind assertions on every event arm
+covered by the bucket_a / bucket_b multi-statement tests, plus a
+focused test pinning the broader-scope `client_side_notes` →
+`push_category_three_prose` path on add column.
 
 ## §4. Notable observations carried over from handoff-48
 
@@ -144,7 +218,7 @@ Up to you. ADR-0038 won't pull on any more rope. Candidate features:
 
 - **Confirm every commit** (propose message, wait). **No AI attribution.**
 - **Test-first**; green + clippy-clean is the only acceptable end
-  state; current baseline **2019 / 0 / 1**.
+  state; current baseline **2020 / 0 / 1**.
 - **Keep docs lockstep**: ADR + `README.md` index + `requirements.md`.
   This session's polish commit ships alongside this handoff and the
   three doc-update edits (M4 / ADR-0038 Status / ADR-0037 + ADR-0038
@@ -158,7 +232,7 @@ Up to you. ADR-0038 won't pull on any more rope. Candidate features:
    tracks → the relevant ADR for whatever feature you pick up.
    ADR-0038 / ADR-0037 are done and well-documented; touch them only
    to amend if a real correction comes up.
-2. **Baseline:** `cargo test` (2019 / 0 / 1) + `cargo clippy
+2. **Baseline:** `cargo test` (2020 / 0 / 1) + `cargo clippy
    --all-targets -- -D warnings` (clean).
 3. **For a fresh feature**: write the ADR (or extend an existing
    one), run `/runda` over the design before building, then build