Project storage runtime: ADR-0015 + ADR-0004/0007 amendments

Designs track-2 lifecycle and persistence end-to-end: per-command
write-through to db+yaml+csv+history.log gated by the combined db
persistence logic with commit-db-last ordering; existence-only load
with explicit rebuild command; --resume CLI flag backed by
<data-root>/last_project; in-TUI list-with-browse picker; lock file
for single-instance enforcement; fatal-banner-then-quit failure
model (with --resume making restart cheap); fatal CSV row-load
errors with full diagnosis; YYYYMMDD-word-word-word temp naming
with display-name prettifier; collision-checked names for both
temp and user-supplied projects. Project name lives only on the
filesystem (not duplicated in YAML). ADR-0004 and ADR-0007 amended
in place. requirements.md and CLAUDE.md updated; OOS-6 (global
rolling history) tracked as deferred.
This commit is contained in:
claude@clouddev1
2026-05-07 19:53:47 +00:00
parent bfdf350ac8
commit 4fca862c6c
6 changed files with 663 additions and 17 deletions
+39 -1
View File
@@ -2,7 +2,10 @@
## Status
Accepted
Accepted. Amended by [ADR-0015](0015-project-storage-runtime.md) —
see the "Amendments" section at the end of this file for the
specifics; the rest of this ADR remains the canonical reference
for the project file format.
## Context
@@ -62,3 +65,38 @@ A project is a directory containing:
- The `version` field opens the door to format migrations as the
app evolves; old projects load by running registered migrators
in sequence.
## Amendments
### Amendment 1 — runtime data flow ([ADR-0015](0015-project-storage-runtime.md))
The phrase "`playground.db` is a derived artifact" describes a
*recovery* property: the database can always be reconstructed
from `project.yaml` + `data/`. It does not describe runtime
data flow.
At write time, all persistence targets (the SQLite database,
`project.yaml`, the relevant `data/<table>.csv` files, and
`history.log`) share a single source — the user's command — and
are written alongside one another in a defined order (see
ADR-0015 §6). None of the text files is "downstream" of the
database at write time.
### Amendment 2 — `.db` rebuild trigger ([ADR-0015](0015-project-storage-runtime.md))
The "rebuild with confirmation when `.db` exists" semantics in
the original Decision section are replaced by a simpler model:
- On load, if `playground.db` exists, it is opened as-is.
- On load, if `playground.db` is missing, it is rebuilt
silently from `project.yaml` + `data/`.
- A new app-level command, `rebuild`, explicitly discards the
current `playground.db` and reconstructs it from the text
sources, with a confirmation prompt and a summary of what
will be reconstructed.
The application does not attempt to detect drift between the
database and the text sources automatically. `rebuild` is the
explicit user-driven path for cases where drift exists (git
pull over an existing `.db`, hand edits to YAML/CSV, recovery
after a rare failure described in ADR-0015 §6).