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
+36 -4
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 sharing and export.
## Context
@@ -23,9 +26,11 @@ mechanisms:
1. **`export` command.**
- Available as an app-level command in both input modes
(ADR-0003).
- Produces a single zip file containing `project.yaml`,
`data/`, and `history.log`, **excluding** `playground.db`
(the recipient rebuilds it on open per ADR-0004).
- Produces a single zip file containing `project.yaml` and
`data/`, **excluding** `playground.db` (the recipient
rebuilds it on open per ADR-0004) and **excluding**
`history.log` (the user's working log is private; see
Amendment 1 below).
- Default output path is the parent directory of the project.
- Default filename:
`YYYYMMDD-<projectname>-export-<sequence>.zip`, where
@@ -46,6 +51,33 @@ mechanisms:
If real-world usage later reveals friction these mechanisms cannot
solve, a publish feature can be revisited as a separate ADR.
## Amendments
### Amendment 1 — `history.log` excluded from export ([ADR-0015](0015-project-storage-runtime.md))
The export zip's contents are now `project.yaml` + `data/`
only. Both `playground.db` (always derived) and `history.log`
(the user's private working log) are excluded.
Rationale: the history captures every successful command the
user has run in the project, including exploratory or
embarrassing detours. Sharing it by default is wrong — users
will share more than they intend. A user who *does* want to
share their session log can attach `history.log` separately
or re-export with a future flag if real demand emerges.
The `.gitignore` template (Decision item 2) is **not**
updated to exclude `history.log`. The template's purpose is
to give a sensible default for committing a project to git,
which is a different question from "what gets shared in an
export zip." Some users will want their working log in
version control (lessons, audits, reproducible
problem-reports); others won't. We don't make that call for
them — the user decides whether `history.log` belongs in
their git history. The export zip remains the
auto-curated-for-strangers artifact; the gitignore remains
neutral on `history.log`.
## Consequences
- Zero server-side surface area, zero accounts, zero hosting