Session handoff — 2026-06-15 (72)

Short, focused handover. Continues from handoff-71, which asked the next session to run a systematic semantic verification pass over every hint block (handoff-70 shipped H2 / ADR-0053, but a user smoke-test found a wrong hint and implicated the whole corpus). That pass is now done. Four content errors fixed, a durable parse-guard added, two stale docs corrected. Commit 5a37437.

§1. State

Branch: main, clean, all committed (local; push pending — your step). 2500 pass / 0 fail / 1 ignored (the long-standing friendly doctest), clippy clean (nursery, all targets). The +1 vs handoff-71's 2499 is the new guard test. Open Gitea issues unchanged: #35–#38.

§2. The verification pass (commit `5a37437`)

Method: cross-checked every hint.cmd.* example against its parse.usage.* template, ground-truthed every concept claim against the authoritative ADR and a named existing test (not grep+extrapolation — the trap handoff-71 §3 warned about), and parse-validated all 49 command examples via a new guard.

Four content errors fixed (`src/friendly/strings/en-US.yaml`)

Block	Bug	Fix
`cmd.create_table`	Example `with pk id(serial), name(text), email(text)` declares a 3-column compound PK, not a PK + regular columns. Every `with pk` column is a key member — confirmed by the grammar test comment "Every `create table` column is a primary-key column" (`ddl.rs`), ADR-0005.	Single-column PK + `add column` for the rest; `what`/`concept` aligned.
`cmd.save`	`save as my-shop` does not parse — `build_save` yields `AppCommand::SaveAs` with no inline name; `save as` opens a path-entry modal (`iteration4b` tests).	Example → `save as`; `what` de-implied; added an accurate temp-vs-named-auto-save `concept`.
`cmd.import`	Target `shop-copy` does not parse — the `as <target>` slot is an `IdentSource::NewName` ident that tokenises only up to the hyphen. (The zip path is a BarePath and does accept hyphens, hence `export my-shop.zip` is fine.)	→ `shop_copy`.
`err.foreign_key.child_side.concept`	Offered `on delete set null/cascade` as the remedy — but `error_hint_class` maps child_side to insert/update violations; `on delete` governs the parent direction. The tier-1 hint (line 64) correctly omits it.	Corrected: parent must exist first; clarified `on delete` is the other direction.

Durable guard added

every_cmd_hint_example_parses_in_its_mode (src/dsl/grammar/mod.rs, in the hint_key_tests module). Catalog-driven — it iterates catalog().keys() for hint.cmd.*.example rather than the REGISTRY, so an orphaned/mis-keyed block can't slip past; floor-asserts ≥49 examples. Each parses in its taught mode (advanced for the SQL surface, simple otherwise). It caught the save and import errors test-first (red before the YAML fix). Registered the new hint.cmd.save.concept key in keys.rs (the keys_validate_against_catalog test requires every catalog key be declared).

Verified correct (not changed)

All other cmd/err blocks. Notably the guard-concept claims were each confirmed against a named runtime test, not assumed: drop_column_refuses_primary_key / …_column_in_a_relationship, drop_table_with_inbound_relationship_errors, add_not_null_column_without_default_to_populated_table_is_refused. The corrected create_table story stays coherent with the Customers- referencing examples (id serial PK → add column name/email → insert skips the auto id).

§3. Docs corrected (same commit)

Discovered while verifying create_m2n (which is implemented — db.rs::do_create_m2n_relationship + tests/it/m2n.rs):

CLAUDE.md carried two stale "deferred" claims, both already implemented. Removed/updated: (a) the at-a-glance project-format line said export/import (Iter 5) + --resume/input-history/migration (Iter 6) were "pending" — all [x] in requirements.md (ADR-0015); (b) the "Things deliberately deferred" list still had the m:n convenience (C4) bullet and the same project-storage bullet. requirements.md was already correct (C4 done 2026-06-10, ADR-0045), so only a verification-pass note was appended to its H2 entry.

§4. Scope note — what the guard does not do

The bug class here is semantic (an example that parses and runs but misrepresents the prose — e.g. create_table). The guard enforces only the syntactic floor: examples parse in their mode. It backstops future typos/clause-drift but cannot police meaning. Semantic correctness of the current corpus rests on this session's review (recorded in the commit + requirements.md H2). A stronger-but-brittler option was offered to the user and not built pending their call: per-form assertions that each example resolves to the expected command shape (e.g. create_table → single-column PK). hint.err.* examples are fix-recipe prose, not runnable, so they're verified by review only — inherent.

§5. Next session — start here

The hint corpus is now trustworthy. Open roadmap (verify against the CI merge first, per handoff-70 §5):

Push (your step) — this commit + the still-unpushed backlog from handoffs 70/71 (the CI merge + all of H2).
#35 (cargo fmt gate) — the natural pairing with the merged CI; the user wanted it done once, before first publication. The tree is not fmt-clean (~1800 pre-existing diffs).
Other requirements.md open items: TT4 PTY tier-4 (unwired), I1 multi-line input, I5/B3 in-flight cancellation, V4 session journal (own ADR), TU1 tutorial system (own ADR).
Hint follow-ups if wanted: #37 clause-concept hints, #38 diagnostic route + diagnostic.* blocks, #36 help advanced-SQL.

§6. How to take over

Read handoffs 70 → 71 → 72, CLAUDE.md, docs/requirements.md.
Confirm green: cargo test (2500 / 1 ignored) + cargo clippy --all-targets (clean).
For anything in the hint area, read ADR-0053 first. For the corpus, src/friendly/strings/en-US.yaml (hint.cmd.* / hint.err.*) is the content; the guard in src/dsl/grammar/mod.rs is the regression net.
Workflow unchanged: phased, test-first, /runda + DA before commits, ADR amendment + README index-upkeep for decided-area changes, confirm commit messages with the user.
Consider a cargo sweep at this milestone (target/ grows; see CLAUDE.md "Build hygiene").

6.4 KiB Raw Blame History Unescape Escape