diff --git a/docs/handoff/20260528-handoff-49.md b/docs/handoff/20260528-handoff-49.md index 30e90b5..2c820b9 100644 --- a/docs/handoff/20260528-handoff-49.md +++ b/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 -DSL → SQL teaching echo is implemented, every echo round-trips per -line per the §1 copy-paste contract, every §6 category-3 line surfaces, -and the §4 de-emphasised styled-runs rendering polish landed in -`2aab457`. Docs in sync. If you continue, pick a fresh feature; if -you're triaging, ADR-0038 won't surprise you. +Forty-ninth handover. **ADR-0038 is done** — and twice DA-audited. +Every catalogue row of the DSL → SQL teaching echo is implemented, +every echo round-trips per line per the §1 copy-paste contract, +every §6 category-3 line surfaces, the §4 de-emphasised styled-runs +rendering polish landed in `2aab457`, and a closing /runda Devil's- +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 -explicit tests). +Plus **two** /runda Devil's-Advocate passes — `5cb105b` after +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:: -teaching_echo_line_renders_dim_prefix_and_lexed_sql` (asserts the -dim prefix span + keyword-coloured SQL spans confirm advanced-mode -lex), `ui::tests::category_three_prose_line_renders_all_dim` -(whole-text Hint coverage), `ui::tests:: -hint_class_resolves_to_muted_foreground` (theme resolution across -both palettes), `app::tests:: -polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span` -(App-side wiring kinds + styled_runs shape). The pre-existing echo -tests pass unchanged — the text content is identical, only styling -changed. +**Coverage:** four new tests landed with the polish itself +(`2aab457`) — `ui::tests::teaching_echo_line_renders_dim_prefix_and_lexed_sql` +(asserts the dim prefix span + keyword-coloured SQL spans confirm +advanced-mode lex), `ui::tests::category_three_prose_line_renders_all_dim` +(whole-text Hint coverage), `ui::tests::hint_class_resolves_to_muted_foreground` +(theme resolution across both palettes), and +`app::tests::polished_echo_carries_teaching_echo_kind_and_caveat_a_hint_span` +(App-side wiring kinds + styled_runs shape on the caveat path). The +pre-existing echo tests pass unchanged — the text content is +identical, only styling changed. The /runda round 2 (`6840b92`) +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