docs(handoff-78): record the #36 help fix and the value.rs DSL finding

docs/handoff/20260622-handoff-78.md

@@ -0,0 +1,101 @@
+# Session handoff — 2026-06-22 (78)
+
+Continues from handoff-77 (issue #39 + changelog rule). This chunk cleared
+**issue #36** — advanced-mode SQL forms now have distinct `help` content — the
+first of the enhancement issues the user is working through. Three issues remain
+open (#37, #38, #40).
+
+## §1. State
+
+**Branch `main`.** Work for #36 is staged but **not yet committed** at the time
+of writing (two commits proposed: a `feat(help)` for the change + a
+`docs(handoff-78)`). **Not pushed** — push is the user's step.
+
+**Test baseline: 2525 passed / 0 failed / 1 ignored** (was 2521; +4 new
+`help_command` integration tests). `clippy --all-targets -D warnings` +
+`fmt --check` clean. Issue #36 to be **closed** on commit.
+
+## §2. What shipped — issue #36
+
+**Problem.** The in-app `help` command gave no distinct content for the six
+advanced-mode SQL **DML/query** forms (`SELECT`, `WITH`, `SQL_INSERT`,
+`SQL_UPDATE`, `SQL_DELETE`, `EXPLAIN_SQL`): they carried `help_id: None` (a
+list-dedup shortcut), so `help select` / `help with` resolved to the
+unknown-topic note and `help insert` showed only the simple form. (The advanced
+SQL **DDL** forms already had `help.ddl.sql_*` pages, so the gap was
+inconsistent too.)
+
+**Decisions taken with the user** (three forks, all confirmed):
+1. `help <topic>` shows **both forms** for a shared entry word, mode-blind.
+2. `select` / `with` get `help_id`s and are **listed** too (consistent with the
+   already-listed SQL DDL forms).
+3. The `help` **list** is **split by mode** into "Simple-mode commands:" and
+   "Advanced-mode (SQL) commands:" sections — fixing a pre-existing header bug
+   (next item).
+
+**Fix (near-zero logic):**
+- Gave all six advanced forms distinct `help_id`s (`data.select`, `data.with`,
+  `data.sql_insert`, `data.sql_update`, `data.sql_delete`, `data.explain_sql`)
+  with hand-curated terse `help.data.*` catalog pages (`src/dsl/grammar/data.rs`,
+  `src/friendly/strings/en-US.yaml`). Distinct strings ⇒ the dedup invariant
+  (`no_two_registered_commands_share_a_help_id`) is untouched. `note_help_topic`
+  needed **no** change — the forms now resolve automatically (so `help insert`
+  shows the simple block + the `sql_insert` block, like `help create` already
+  did).
+- `note_help` (`src/app.rs`) now **groups by `CommandCategory`**: `app.*`
+  commands first (unlabelled, under the intro — they work in either mode), then
+  a simple-mode group and an advanced-mode (SQL) group. New catalog keys
+  `help.simple_section` / `help.advanced_section` replace the old
+  `help.dsl_section`.
+- Trimmed `help.data.explain`'s advanced lines (the `explain_sql` page now owns
+  that). Updated `src/friendly/keys.rs` (catalog-key registry) and the stale
+  `help_id`-rationale comments in `src/dsl/grammar/{mod,data}.rs`.
+
+**Copy-rule fix (bonus, in scope).** The old list header
+`"DSL data commands (in simple mode):"` violated the project copy rule (the
+banned word **"DSL"**) *and* mis-labelled the advanced SQL forms it already
+contained as "simple mode". The split headers fix both. Verified the full `help`
+output no longer contains "DSL".
+
+**Tests** (all four red→green): `help_command::{help_select_renders_the_sql_select_block,
+help_with_renders_the_cte_block, help_insert_shows_both_simple_and_sql_forms,
+help_list_splits_simple_and_advanced_sections}`. Rendered output eyeballed
+(alignment, both-forms, the three list groups).
+
+**Docs.** ADR-0024 **Amendment 1** (owns `help_id`); README index updated same
+edit; CHANGELOG `[Unreleased] → Added` entry (per handoff-77's new changelog
+rule — landed *with* the change this time).
+
+## §3. Copy-rule audit finding (flagged, NOT fixed) — needs a triage call
+
+The user asked for a "DSL" sweep of help/hint strings. Result: the only
+user-facing help/hint violation was the list header (fixed above). The other
+catalog "DSL" hits are comments / YAML keys (internal — the rule allows those).
+
+**One bonus finding outside help/hint, deliberately left for the user to
+triage:** `src/dsl/value.rs:106` returns the error message *"literal `blob`
+values are not supported in **DSL** yet"* — a likely user-facing copy-rule
+violation (and it also surfaces an internal term). Not touched (out of #36
+scope). **Decide: fix now / file an issue / leave.** Worth a quick check of
+whether that message reaches the user raw or is wrapped by the friendly layer.
+
+## §4. Open / follow-ups — three issues remain
+
+| # | One-line | read |
+| --- | --- | --- |
+| **#37** | Clause-concept hints (cursor inside `on delete …`, `with pk`, `1:n`/`m:n`, create-table constraint slots) — deferred ADR-0053 extension | **Medium scope, richest teaching value.** Likely an ADR-0053 amendment; read ADR-0053 first. |
+| **#38** | Pre-submit-diagnostic F1 route + ~33 `diagnostic.*` tier-3 blocks; needs a `class`/`message_key` threaded through every diagnostic site | **Broad mechanism, most marginal value.** Get the user's do/defer/close call before building. |
+| **#40** | Wire `CHANGELOG.md` into the winget release notes (`komac --release-notes-url`); ADR-0056 area | Filed handoff-77; independent release-pipeline work. |
+| (new?) | `value.rs:106` "DSL" copy-rule violation — see §3 | Not filed yet; awaiting the user's triage call. |
+
+**Suggested next:** #37 (highest on-mission value) → #38 (escalate do/defer/close
+first) → #40 (independent). Plus the §3 `value.rs` triage.
+
+## §5. Process pins
+
+- Test-first honoured: 4 help tests confirmed RED before the fix, GREEN after.
+- Written Devil's-Advocate pass on the implementation: no blocking findings
+  (the dedup invariant holds with distinct ids; `note_help_topic` unchanged;
+  category split verified in the rendered output).
+- Commits user-confirmed, no AI attribution, append-only, on `main`; push is the
+  user's step.