102 lines
5.7 KiB
Markdown
102 lines
5.7 KiB
Markdown
# 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.
|