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:
@@ -579,6 +579,22 @@ test suite still all-green; `cargo clippy --all-targets --
|
||||
-D warnings` passes; `cargo build --release` binary not
|
||||
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
|
||||
|
||||
Three guarantees throughout migration:
|
||||
|
||||
+1
-1
@@ -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-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-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 A–F; Phase F shipped "minimal", `parser.rs` retained as the router — see the ADR's Phase F implementation note)
|
||||
|
||||
@@ -6,8 +6,10 @@ deferred items. Eight focused commits, each a deliberate
|
||||
decision the user signed off on.
|
||||
|
||||
**Headline: the handoff-12 §2 catalogue is now empty of
|
||||
actionable items.** What remains are two flagged observations
|
||||
(§3) the user should rule on, plus the standing ADR roadmap.
|
||||
actionable items, and ADR-0024 is confirmed fully
|
||||
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
|
||||
|
||||
@@ -138,45 +140,71 @@ long internal space runs in double-quoted (`"…"`) values — use
|
||||
a block scalar or keep runs short.** A catalog comment in
|
||||
`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
|
||||
non-identity ranker. The user's stated ranker need (candidate
|
||||
ordering) is met by declaration-order preservation, not the
|
||||
ranker layer. So `Ranker`, `identity_ranker`, and the
|
||||
`candidates_at_cursor_with` variant are unused scaffolding. Per
|
||||
CLAUDE.md "don't remove without confirmation" they were left
|
||||
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.)
|
||||
non-identity ranker (the candidate-ordering need is met by
|
||||
declaration-order preservation). The user ruled: **keep it** —
|
||||
it is intentional scaffolding for future frequency / content-
|
||||
aware ranking (ADR-0024 §"out of scope" explicitly anticipates
|
||||
this). No longer an open question.
|
||||
|
||||
**3.2 `CommandNode.hint_mode` is now genuinely dead.** The
|
||||
per-command `hint_mode: Option<HintMode>` field predates the
|
||||
node-attached HintMode work; HintMode is now per-*node*
|
||||
(`Node::Hinted`), never per-command. The field is still
|
||||
`#[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).
|
||||
**3.2 `CommandNode.hint_mode` — REMOVED.** The per-command
|
||||
`hint_mode` field predated the node-attached HintMode work and
|
||||
was read by nothing. Removed (field + 20 `None` initialisers)
|
||||
in commit `6d2b929`.
|
||||
|
||||
## §4. Open items — standing roadmap (unchanged)
|
||||
## §4. What's next — the standing roadmap
|
||||
|
||||
handoff-12 §2's actionable backlog is cleared. What remains is
|
||||
the ADR roadmap in `CLAUDE.md` "Things deliberately deferred"
|
||||
(complex WHERE expressions, SQL advanced mode, indexes, m:n
|
||||
convenience, snapshot/replay/undo, tutorial system, etc.) and
|
||||
handoff-13's two accepted items:
|
||||
**handoff-12 §2's backlog is cleared, and ADR-0024 is
|
||||
confirmed fully implemented** (audited this session — Phases
|
||||
A–F done; Phase F shipped "minimal" with `parser.rs` retained
|
||||
as the router, now recorded in an ADR-0024 implementation
|
||||
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 10–14 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`**
|
||||
(handoff-13 §3) — the user accepted this; the matrix test
|
||||
`app_commands::partial_entry_word_classifies_as_definite_error_but_completes`
|
||||
documents it.
|
||||
(handoff-13 §3) — documented by the matrix test
|
||||
`app_commands::partial_entry_word_classifies_as_definite_error_but_completes`.
|
||||
- **Matrix scope** (handoff-13 §4) — cursor coverage is
|
||||
"meaningful transitions" not every byte offset; assertion (5)
|
||||
is parse-layer not a live dispatch differential. User
|
||||
accepted both.
|
||||
is parse-layer, not a live dispatch differential.
|
||||
|
||||
## §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.{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
|
||||
|
||||
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
|
||||
`Box::leak` arena's true cost, the Form C restructure twice)
|
||||
rather than deciding unilaterally.
|
||||
3. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored.
|
||||
4. **Run `cargo clippy --all-targets -- -D warnings`** — clean.
|
||||
5. **Resolve §3** — the two flagged dead-code items — with the
|
||||
user.
|
||||
6. Then the standing ADR roadmap (§4) is the next structural
|
||||
work; pick per the user's priorities.
|
||||
3. **Read `docs/requirements.md`** — reconciled this session;
|
||||
it is the authoritative "what's open" tracker (§4).
|
||||
4. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored.
|
||||
5. **Run `cargo clippy --all-targets -- -D warnings`** — clean.
|
||||
6. **Pick the next work from §4 / `requirements.md`** — but
|
||||
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
|
||||
|
||||
|
||||
+29
-14
@@ -26,9 +26,12 @@ repo is pushed).
|
||||
|
||||
## Test baseline
|
||||
|
||||
After B2/C2 (column drop / rename / change-type): **449
|
||||
passing, 0 failing, 0 skipped** (`cargo test`). Clippy clean
|
||||
with the nursery lint group enabled.
|
||||
After ADR-0024 full implementation + the handoff-14 cleanup
|
||||
pass: **1006 passing, 0 failing, 1 ignored** (`cargo test` —
|
||||
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`,
|
||||
`rebuild`, `export`, `import`, `seed`, `replay`, `undo`,
|
||||
`redo`, `mode`, `help`, `hint`, `quit`.
|
||||
*(Progress: `quit`/`q`, `mode simple|advanced`, `help` (basic
|
||||
listing), `save`, `save as`, `load`, `new`, `rebuild`,
|
||||
`export`, `import` all implemented (Iterations 4 + 5). `seed`
|
||||
in the seeding iteration; `replay` / `undo` / `redo` in the
|
||||
U-series; `hint` with H2.)*
|
||||
*(Progress: `quit`/`q`, `mode simple|advanced`, `help`,
|
||||
`save`, `save as`, `load`, `new`, `rebuild`, `export`,
|
||||
`import`, `replay` all implemented (Iterations 4 + 5;
|
||||
`replay` via ADR-0024 Phase E — see U4). `seed` in the
|
||||
seeding iteration; `undo` / `redo` in the U-series; `hint`
|
||||
with H2.)*
|
||||
|
||||
## DSL data commands
|
||||
|
||||
@@ -301,8 +305,12 @@ with the nursery lint group enabled.
|
||||
- [x] **U3** `history.log` records every successfully executed
|
||||
command in append-only form (Iteration 2). Format:
|
||||
`<ISO-8601 Z>|ok|<source>` per ADR-0015 §5.
|
||||
- [ ] **U4** `replay` runs commands from a `history.log` or
|
||||
`.commands` file.
|
||||
- [x] **U4** `replay` runs commands from a `history.log` or
|
||||
`.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)
|
||||
|
||||
@@ -350,14 +358,21 @@ with the nursery lint group enabled.
|
||||
separate effort from H1 (which targets database errors); it
|
||||
targets parser errors. Pending — multiple targeted fixes
|
||||
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
|
||||
input or the most recent error.
|
||||
- [ ] **H3** `help` provides general reference and per-command
|
||||
help.
|
||||
*(Progress: `help` app-level command lists currently-supported
|
||||
commands + DSL grammar reference + types, kept in sync with
|
||||
what's wired up. Per-command detail is the missing piece.)*
|
||||
*(Progress: the `help` command lists currently-supported
|
||||
commands + DSL grammar reference + types. As of ADR-0024
|
||||
§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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user