docs: record ADR-0024 completion, reconcile requirements.md + handoff-14

ADR-0024 audited as fully implemented. Amend the ADR with a "Phase F
minimal" implementation note (parser.rs retained as the router +
ParseError home) and update the README index line to match.

Reconcile docs/requirements.md against handoffs 10-14: refresh the
test baseline (449 -> 1006), mark U4 (replay) satisfied, correct the
A1 / H1a / H3 progress notes.

Amend handoff-14: §3 flagged items both resolved (ranker kept,
CommandNode.hint_mode removed); §4 rewritten as a concrete next-work
pointer at the reconciled requirements.md.
This commit is contained in:
claude@clouddev1
2026-05-15 23:03:18 +00:00
parent 6d2b92996d
commit 41043d686b
4 changed files with 125 additions and 53 deletions
@@ -579,6 +579,22 @@ test suite still all-green; `cargo clippy --all-targets --
-D warnings` passes; `cargo build --release` binary not -D warnings` passes; `cargo build --release` binary not
noticeably larger. noticeably larger.
**Implementation note (2026-05-15) — "Phase F minimal".**
Phase F shipped as planned with one deliberate deviation:
`dsl/parser.rs` was *retained*, not deleted. The chumsky +
lexer pipeline is gone (chumsky dependency removed; `lexer.rs`,
`keyword.rs`, `ident_slot.rs`, `usage.rs` all deleted; the
`parse.token.*` catalog entries collapsed), but `parser.rs`
remains as the thin router: it owns the public `parse_command`
/ `parse_command_with_schema` entry points and the `ParseError`
type, whose `{message, position, at_eof, expected}` shape
completion, hint rendering, and the input-renderer overlay all
depend on. Deleting the file would only scatter that surface
across `walker` / `dsl/mod.rs` for no functional gain. The
differential scaffolding was never built as a live harness —
it materialised as hand-curated expectation tests. `parser.rs`
documents this in its own module doc comment.
### Test discipline ### Test discipline
Three guarantees throughout migration: Three guarantees throughout migration:
+1 -1
View File
@@ -29,4 +29,4 @@ This directory contains the project's ADRs, recorded per
- [ADR-0021 — Parser-as-source-of-truth for H1a (per-command usage in parse errors)](0021-parser-as-source-of-truth-for-h1a.md) - [ADR-0021 — Parser-as-source-of-truth for H1a (per-command usage in parse errors)](0021-parser-as-source-of-truth-for-h1a.md)
- [ADR-0022 — Ambient typing assistance: colour, hint panel, completion (I3 + I4)](0022-ambient-typing-assistance.md) - [ADR-0022 — Ambient typing assistance: colour, hint panel, completion (I3 + I4)](0022-ambient-typing-assistance.md)
- [ADR-0023 — Unified declarative grammar tree](0023-unified-grammar-tree.md) — direction (superseded for execution detail by ADR-0024) - [ADR-0023 — Unified declarative grammar tree](0023-unified-grammar-tree.md) — direction (superseded for execution detail by ADR-0024)
- [ADR-0024 — Unified grammar tree: execution plan](0024-unified-grammar-tree-execution-plan.md) — **Accepted**, the executable spec - [ADR-0024 — Unified grammar tree: execution plan](0024-unified-grammar-tree-execution-plan.md) — **Accepted**, the executable spec — implemented (Phases AF; Phase F shipped "minimal", `parser.rs` retained as the router — see the ADR's Phase F implementation note)
+79 -38
View File
@@ -6,8 +6,10 @@ deferred items. Eight focused commits, each a deliberate
decision the user signed off on. decision the user signed off on.
**Headline: the handoff-12 §2 catalogue is now empty of **Headline: the handoff-12 §2 catalogue is now empty of
actionable items.** What remains are two flagged observations actionable items, and ADR-0024 is confirmed fully
(§3) the user should rule on, plus the standing ADR roadmap. implemented.** The two items §3 originally flagged are both
resolved. The next session's work is the product roadmap in
`docs/requirements.md` (reconciled this session) — see §4.
## State at handoff ## State at handoff
@@ -138,45 +140,71 @@ long internal space runs in double-quoted (`"…"`) values — use
a block scalar or keep runs short.** A catalog comment in a block scalar or keep runs short.** A catalog comment in
`en-US.yaml` records this. `en-US.yaml` records this.
## §3. CRITICAL: two flagged items needing a user decision ## §3. Flagged items — both now resolved
**3.1 The `Ranker` type is vestigial.** `completion::Ranker` / Both items this section originally flagged were ruled on by
the user after the main work:
**3.1 The `Ranker` type — KEEP.** `completion::Ranker` /
`candidates_at_cursor_with` have no production caller passing a `candidates_at_cursor_with` have no production caller passing a
non-identity ranker. The user's stated ranker need (candidate non-identity ranker (the candidate-ordering need is met by
ordering) is met by declaration-order preservation, not the declaration-order preservation). The user ruled: **keep it** —
ranker layer. So `Ranker`, `identity_ranker`, and the it is intentional scaffolding for future frequency / content-
`candidates_at_cursor_with` variant are unused scaffolding. Per aware ranking (ADR-0024 §"out of scope" explicitly anticipates
CLAUDE.md "don't remove without confirmation" they were left this). No longer an open question.
in. **Decide: remove them, or keep for a future frequency-
ranking feature?** (handoff-12 §2.1 listed the ranker as
"scaffolding-only … future work" — this is the same item, now
confirmed genuinely unused.)
**3.2 `CommandNode.hint_mode` is now genuinely dead.** The **3.2 `CommandNode.hint_mode` — REMOVED.** The per-command
per-command `hint_mode: Option<HintMode>` field predates the `hint_mode` field predated the node-attached HintMode work and
node-attached HintMode work; HintMode is now per-*node* was read by nothing. Removed (field + 20 `None` initialisers)
(`Node::Hinted`), never per-command. The field is still in commit `6d2b929`.
`#[allow(dead_code)]` and read by nothing. Removing it is a
safe mechanical edit across the 20 `CommandNode` declarations.
**Decide: remove it, or keep?** Not done this session (20-site
edit, separate from the HintMode mechanism change).
## §4. Open items — standing roadmap (unchanged) ## §4. What's next — the standing roadmap
handoff-12 §2's actionable backlog is cleared. What remains is **handoff-12 §2's backlog is cleared, and ADR-0024 is
the ADR roadmap in `CLAUDE.md` "Things deliberately deferred" confirmed fully implemented** (audited this session — Phases
(complex WHERE expressions, SQL advanced mode, indexes, m:n AF done; Phase F shipped "minimal" with `parser.rs` retained
convenience, snapshot/replay/undo, tutorial system, etc.) and as the router, now recorded in an ADR-0024 implementation
handoff-13's two accepted items: note). There is no migration or carry-forward debt left.
**The next session's work is the product roadmap, tracked in
`docs/requirements.md`** — reconciled this session against
what handoffs 1014 actually built (test baseline refreshed to
1006; `U4` replay marked satisfied; `A1` / `H1a` / `H3`
progress notes corrected). `requirements.md` is now the
trustworthy "what's open" tracker — read it, not the
(coarser) `CLAUDE.md` "Things deliberately deferred" list.
Notable open clusters in `requirements.md` (prioritisation is
a **user product decision** — do not pick unilaterally):
- **Indexes** (`C3` partial) — `add index` / `drop index`,
then `EXPLAIN QUERY PLAN` rendering (`QA1`). Self-contained.
- **Complex WHERE expressions** (`C5a`, `[~]`) — AND/OR /
comparison / LIKE in UPDATE/DELETE/show-data filters. Needs
an ADR. The bridge from DSL toward real SQL.
- **SQL in advanced mode** (`Q1`/`Q4`, `[~]`) — `sqlparser-rs`
+ a defined subset. Needs an ADR.
- **Snapshot / undo** (`U1`/`U2`) — designed in ADR-0006, not
built. (`replay`, `U4`, is now done.)
- **m:n convenience** (`C4`), **modify relationship** (`C3a`,
`[~]`), **table rename** (`C1`).
- **Friendly error layer** (`H1`) — partial; full SQL→English
translation pending. **Syntax-help in parse errors**
(`H1a`) — piecemeal so far.
- **Session log + Markdown export** (`V4`, `[~]`),
**multi-line input** (`I1`), **readline shortcuts**
(`I1b`), **seeding** (`SD1`), **CI** (`TT5`),
**tutorial system** (`TU1`, `[~]`).
Two handoff-13 items the user already **accepted** (not work,
just recorded):
- **Partial entry words classify as `DefiniteErrorAt`** - **Partial entry words classify as `DefiniteErrorAt`**
(handoff-13 §3) — the user accepted this; the matrix test (handoff-13 §3) — documented by the matrix test
`app_commands::partial_entry_word_classifies_as_definite_error_but_completes` `app_commands::partial_entry_word_classifies_as_definite_error_but_completes`.
documents it.
- **Matrix scope** (handoff-13 §4) — cursor coverage is - **Matrix scope** (handoff-13 §4) — cursor coverage is
"meaningful transitions" not every byte offset; assertion (5) "meaningful transitions" not every byte offset; assertion (5)
is parse-layer not a live dispatch differential. User is parse-layer, not a live dispatch differential.
accepted both.
## §5. Architectural delta (vs. handoff-13) ## §5. Architectural delta (vs. handoff-13)
@@ -217,6 +245,17 @@ handoff-13's two accepted items:
`help.intro` / `help.dsl_section` / `help.types_reference`, `help.intro` / `help.dsl_section` / `help.types_reference`,
`help.{app,ddl,data}.*` (×20). `help.{app,ddl,data}.*` (×20).
### Post-handoff cleanup (this section's work)
After the eight items above, three follow-ups landed:
- `CommandNode.hint_mode` field removed (commit `6d2b929`) —
see §3.2.
- ADR-0024 amended with a "Phase F minimal" implementation
note (`parser.rs` retained as the router); `docs/adr/README.md`
index line updated to match.
- `docs/requirements.md` reconciled — see §4.
## §6. How to take over ## §6. How to take over
1. **Read this file, then handoff-13, then 12** for the chain. 1. **Read this file, then handoff-13, then 12** for the chain.
@@ -224,12 +263,14 @@ handoff-13's two accepted items:
escalated every ambiguous fork (HintMode mechanism, the escalated every ambiguous fork (HintMode mechanism, the
`Box::leak` arena's true cost, the Form C restructure twice) `Box::leak` arena's true cost, the Form C restructure twice)
rather than deciding unilaterally. rather than deciding unilaterally.
3. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored. 3. **Read `docs/requirements.md`** — reconciled this session;
4. **Run `cargo clippy --all-targets -- -D warnings`** — clean. it is the authoritative "what's open" tracker (§4).
5. **Resolve §3** — the two flagged dead-code items — with the 4. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored.
user. 5. **Run `cargo clippy --all-targets -- -D warnings`** — clean.
6. Then the standing ADR roadmap (§4) is the next structural 6. **Pick the next work from §4 / `requirements.md`** — but
work; pick per the user's priorities. prioritisation is a user product decision; ask, don't
assume. handoff-12's backlog and ADR-0024 are both fully
done — there is no carry-forward debt.
### Note on the typing-surface matrix ### Note on the typing-surface matrix
+29 -14
View File
@@ -26,9 +26,12 @@ repo is pushed).
## Test baseline ## Test baseline
After B2/C2 (column drop / rename / change-type): **449 After ADR-0024 full implementation + the handoff-14 cleanup
passing, 0 failing, 0 skipped** (`cargo test`). Clippy clean pass: **1006 passing, 0 failing, 1 ignored** (`cargo test`
with the nursery lint group enabled. the one ignored test is a long-standing `` ```ignore ``
doc-test in `src/friendly/mod.rs`). Clippy clean with the
nursery lint group enabled. (Earlier reference point, after
B2/C2: 449 passing.)
--- ---
@@ -101,11 +104,12 @@ with the nursery lint group enabled.
available in both modes: `save`, `save as`, `load`, `new`, available in both modes: `save`, `save as`, `load`, `new`,
`rebuild`, `export`, `import`, `seed`, `replay`, `undo`, `rebuild`, `export`, `import`, `seed`, `replay`, `undo`,
`redo`, `mode`, `help`, `hint`, `quit`. `redo`, `mode`, `help`, `hint`, `quit`.
*(Progress: `quit`/`q`, `mode simple|advanced`, `help` (basic *(Progress: `quit`/`q`, `mode simple|advanced`, `help`,
listing), `save`, `save as`, `load`, `new`, `rebuild`, `save`, `save as`, `load`, `new`, `rebuild`, `export`,
`export`, `import` all implemented (Iterations 4 + 5). `seed` `import`, `replay` all implemented (Iterations 4 + 5;
in the seeding iteration; `replay` / `undo` / `redo` in the `replay` via ADR-0024 Phase E — see U4). `seed` in the
U-series; `hint` with H2.)* seeding iteration; `undo` / `redo` in the U-series; `hint`
with H2.)*
## DSL data commands ## DSL data commands
@@ -301,8 +305,12 @@ with the nursery lint group enabled.
- [x] **U3** `history.log` records every successfully executed - [x] **U3** `history.log` records every successfully executed
command in append-only form (Iteration 2). Format: command in append-only form (Iteration 2). Format:
`<ISO-8601 Z>|ok|<source>` per ADR-0015 §5. `<ISO-8601 Z>|ok|<source>` per ADR-0015 §5.
- [ ] **U4** `replay` runs commands from a `history.log` or - [x] **U4** `replay` runs commands from a `history.log` or
`.commands` file. `.commands` file. *(Implemented via ADR-0024 Phase E:
`runtime::run_replay` parses each non-blank, non-`#`-comment
line with the schema-aware parser and dispatches it through
the normal pipeline; stops at the first error, no rollback;
nested replay refused. Covered by `tests/replay_command.rs`.)*
## Sharing and export (per ADR-0007) ## Sharing and export (per ADR-0007)
@@ -350,14 +358,21 @@ with the nursery lint group enabled.
separate effort from H1 (which targets database errors); it separate effort from H1 (which targets database errors); it
targets parser errors. Pending — multiple targeted fixes targets parser errors. Pending — multiple targeted fixes
shipping piecemeal so far (e.g. `values` becoming optional in shipping piecemeal so far (e.g. `values` becoming optional in
INSERT removes one such case). INSERT removes one such case; ADR-0024's typed value slots
give per-column-type rejection wording; `insert into T (col)`
with no `values` clause now flags "looks like Form A — add
`values (...)`"). A systematic pass is still pending.
- [ ] **H2** `hint` provides contextual help for the current - [ ] **H2** `hint` provides contextual help for the current
input or the most recent error. input or the most recent error.
- [ ] **H3** `help` provides general reference and per-command - [ ] **H3** `help` provides general reference and per-command
help. help.
*(Progress: `help` app-level command lists currently-supported *(Progress: the `help` command lists currently-supported
commands + DSL grammar reference + types, kept in sync with commands + DSL grammar reference + types. As of ADR-0024
what's wired up. Per-command detail is the missing piece.)* §help_id it is assembled by iterating the command REGISTRY
and translating each `CommandNode.help_id`, so a new command
appears automatically. A general reference and `help
<command>`-style detailed per-command help are still the
missing pieces.)*
## CLI ## CLI