# 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.