Handoff doc + CLAUDE.md and requirements.md refresh

Adds docs/handoff/20260508-handoff-2.md describing the state at
the end of this session: ADR-0015 designed, Iterations 1-4 of
track 2 shipped (file-backed projects with auto-named [temp]
dirs, per-command write-through, rebuild from text on missing
.db, save/save as/new/load/rebuild commands with modal dialogs
and project switching), plus the cleanup pass (--help, in-app
help, post-rebuild message, unmodified-temp cleanup) and the
safety hardening of safely_delete_temp_project. Lists the
next-up moves (Iteration 5: export/import, Iteration 6:
--resume + persistent input history + migration scaffold) and
an end-to-end smoke test.

requirements.md: marks P1-P5, P-NAME-1/2/3, F1, F2, U3, L1 as
[x] with iteration references; adds P-CLEAN-1 for the safe
cleanup; updates A1, I2, H3, L1a progress notes.

CLAUDE.md: updates the project-storage decisions and
deferred-items entry to reflect what's now live vs. still
pending.
This commit is contained in:
claude@clouddev1
2026-05-08 07:07:38 +00:00
parent 58a964da8c
commit ca71184678
3 changed files with 537 additions and 58 deletions
+62 -49
View File
@@ -74,10 +74,11 @@ against it.
end), Ctrl-U (delete to start). Pending.
- [ ] **I2** Persistent navigable input history (project-scoped,
with a global rolling history also available).
*(Progress: in-memory navigable history (Up/Down arrows, draft
preservation, dedup of consecutive duplicates) is implemented;
persistence across sessions arrives with track 2's project
storage.)*
*(Progress: in-memory navigable history is implemented; the
on-disk record is `history.log` (Iteration 2). What's still
missing for I2 is hydrating the navigable history from
`history.log` on project open — Iteration 6. Global rolling
history deferred per OOS-6 / N4.)*
- [ ] **I3** Tab completion for app commands, DSL keywords, table
names, column names, and SQL keywords.
- [ ] **I4** Syntax highlighting for both the DSL and SQL.
@@ -102,10 +103,11 @@ against it.
available in both modes: `save`, `save as`, `load`, `new`,
`rebuild`, `export`, `import`, `seed`, `replay`, `undo`,
`redo`, `mode`, `help`, `hint`, `quit`.
*(Progress: `quit`/`q` and `mode simple|advanced` implemented;
the rest land alongside the features they belong to — `save`,
`load`, `new`, `rebuild`, `export`, `import` in track 2
(ADR-0015), `seed` in the seeding iteration, etc.)*
*(Progress: `quit`/`q`, `mode simple|advanced`, `help` (basic
listing), `save`, `save as`, `load`, `new`, `rebuild` all
implemented (Iteration 4). `export` / `import` land in track
2's Iteration 5; `seed` in the seeding iteration; `replay` /
`undo` / `redo` in the U-series; `hint` with H2.)*
## DSL data commands
@@ -232,46 +234,51 @@ against it.
## Project lifecycle (per ADR-0004)
- [ ] **P1** An auto-named temporary project is created on
startup unless a project is specified, and stored in a
platform-standard path
(e.g. `~/.rdbms-playground/projects/temp-<name>`).
- [ ] **P2** `save` elevates a temp project to a named project at
a chosen location.
- [ ] **P3** Project is always saved as changes occur — there is
no manual dirty state.
- [ ] **P4** `load` opens a picker listing temp projects with
timestamps, with the option to browse to an arbitrary location.
- [ ] **P5** `playground.db` is a derived artifact: rebuilt
silently when missing; rebuilt explicitly via the new
`rebuild` app-level command, which prompts with a change
summary before reconstructing from `project.yaml` + `data/`
(per ADR-0004 amendment 2 and ADR-0015 §7).
- [ ] **P-NAME-1** Temp project directory naming pattern:
`<YYYYMMDD>-<word>-<word>-<word>` from a built-in wordlist
(ADR-0015 §2). Date-sortable; collisions checked against
existing folders and the slug is regenerated on the rare
collision. User-supplied save names that already exist as
folders are refused with a friendly error.
- [ ] **P-NAME-2** Display-name prettifier converts a project
directory name to a human-readable display name: strip a
leading `YYYYMMDD-` for temp projects; split kebab / snake /
camel; title-case each word (ADR-0015 §2).
- [ ] **P-NAME-3** The current project's display name is shown
in the UI status bar at all times, prefixed with `Project:`
(ADR-0015 §2).
- [x] **P1** Auto-named temp project on startup under
`<data-root>/projects/`. OS-standard data root via
`directories` crate; `--data-dir` overrides (Iteration 1).
- [x] **P2** `save` / `save as` elevate / copy + switch
(Iteration 4b). `save` on a named project reports
"already auto-saved".
- [x] **P3** Auto-save: per-command write-through to YAML +
CSV + `history.log` inside the SQLite tx with
commit-db-last ordering (Iteration 2). No dirty state.
- [x] **P4** `load` opens an in-TUI picker, sorted newest
first, with `[TEMP]` markers and a `b`-to-browse path-entry
sub-mode (Iteration 4b).
- [x] **P5** Existence-only load + explicit `rebuild`
command with confirmation modal (Iterations 3 + 4a).
- [x] **P-NAME-1** Temp project directory naming pattern:
`<YYYYMMDD>-[temp]-<word>-<word>-<word>` from a 161-word
built-in list (Iterations 1 + 4b). Bracketed `[temp]`
marker is unambiguous against user-named projects because
`validate_user_name` rejects brackets.
- [x] **P-NAME-2** Display-name prettifier strips
`YYYYMMDD-` AND `[temp]-`; splits kebab / snake / camel;
title-cases each word.
- [x] **P-NAME-3** Status bar shows
`Project: [TEMP] <name>` for temp projects,
`Project: <name>` for named.
- [x] **P-CLEAN-1** Unmodified empty temp projects are
auto-deleted on switch and quit, gated by
`safely_delete_temp_project`'s stacked guards
(containment, symlink rejection, `[temp]` marker, contents
allowlist).
## Project file format (per ADR-0004)
- [ ] **F1** `project.yaml` with `version` field carries schema,
relationships, and project metadata; `data/<table>.csv` carries
table data (UTF-8, header row, RFC 4180).
- [ ] **F2** A `.gitignore` template (excluding `playground.db`)
is created in each new project.
- [ ] **F3** Project file format includes a registered-migrator
mechanism so older `version` values load cleanly as the format
evolves. (Exercised once `version` increments past 1; the
mechanism itself is built in v1.)
- [x] **F1** `project.yaml` with `version: 1` field carries
schema (ordered tables + columns), relationships, and
`created_at`. `data/<table>.csv` carries table data (UTF-8,
header row, RFC 4180; NULL distinct from empty string)
(Iteration 2). Empty tables produce no CSV.
- [x] **F2** `.gitignore` template (`/playground.db`,
`/.rdbms-playground.lock`, `/project.yaml.v*.bak`) created
in each new project (Iteration 1). Per ADR-0007 amendment
1, `history.log` is NOT in the template — user decides
whether to commit it.
- [ ] **F3** Migration framework — pending Iteration 6.
Scaffold (no migrators yet) is the v1 deliverable.
## Undo and replay (per ADR-0006)
@@ -280,8 +287,9 @@ against it.
- [ ] **U2** `undo` restores the most recent snapshot; `redo`
re-applies; both prompt for confirmation showing the snapshot
timestamp and a summary of the changes that will be discarded.
- [ ] **U3** `history.log` records every successfully executed
command in append-only form.
- [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.
@@ -330,15 +338,20 @@ against it.
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.)*
## CLI
- [ ] **L1** Load a project via a positional CLI argument.
- [x] **L1** Load a project via a positional CLI argument
(Iteration 1). Plus `--data-dir` to override the data root
and `--help` / `-h` for the usage banner.
- [ ] **L1a** `--resume` CLI flag opens the most recently used
project (path tracked in `<data-root>/last_project`). Errors
cleanly if no previous project exists or the recorded path is
gone; mutually exclusive with a positional path argument
(ADR-0015 §7).
(ADR-0015 §7). Pending Iteration 6.
- [~] **L2** Submit a command alongside project load — deferred,
not v1.