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
|
-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
@@ -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 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.
|
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
|
A–F 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 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`**
|
- **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
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user