From 64818c08f66be5ef3d92f232537e6e71796284e7 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Mon, 22 Jun 2026 19:01:27 +0000 Subject: [PATCH] docs(handoff-78): record the #36 help fix and the value.rs DSL finding --- docs/handoff/20260622-handoff-78.md | 101 ++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/handoff/20260622-handoff-78.md diff --git a/docs/handoff/20260622-handoff-78.md b/docs/handoff/20260622-handoff-78.md new file mode 100644 index 0000000..54ac467 --- /dev/null +++ b/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 ` 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.