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):

help <topic> shows both forms for a shared entry word, mode-blind.
select / with get help_ids and are listed too (consistent with the already-listed SQL DDL forms).
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_ids (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.

5.7 KiB Raw Blame History