docs: handoff 72 — H2 hint corpus verified (4 fixes + parse guard)

2026-06-15 19:03:13 +00:00
parent 5a37437055
commit 1660a6a17c
1 changed files with 113 additions and 0 deletions
@@ -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 <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):
 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").