diff --git a/docs/handoff/20260615-handoff-72.md b/docs/handoff/20260615-handoff-72.md new file mode 100644 index 0000000..c90b5be --- /dev/null +++ b/docs/handoff/20260615-handoff-72.md @@ -0,0 +1,113 @@ +# 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 ` 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): + +1. **Push** (your step) — this commit + the still-unpushed backlog from + handoffs 70/71 (the CI merge + all of H2). +2. **#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). +3. 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). +4. Hint follow-ups if wanted: **#37** clause-concept hints, **#38** + diagnostic route + `diagnostic.*` blocks, **#36** `help` advanced-SQL. + +## §6. How to take over + +1. Read handoffs 70 → 71 → 72, `CLAUDE.md`, `docs/requirements.md`. +2. Confirm green: `cargo test` (**2500 / 1 ignored**) + `cargo clippy + --all-targets` (clean). +3. 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. +4. Workflow unchanged: phased, test-first, `/runda` + DA before commits, + ADR amendment + README index-upkeep for decided-area changes, confirm + commit messages with the user. +5. Consider a `cargo sweep` at this milestone (`target/` grows; see + CLAUDE.md "Build hygiene").