SDLC-SPDD storage v3 — one folder, one ledger, query don't bulk-read

Agent memory only works if humans can audit it and models don't have to read the whole repo every session. That was the gap in early SDLC-SPDD dogfood: progress mirrors beside the ledger, feature folders under agent-context/, and “just grep the lessons file” retrieval. Storage v3 — now on main in sdlc-spdd-orchestrator — collapses the layout, commits to one JSONL ledger, and treats everything else as query or projection.

One folder to install

Framework-owned paths live under a single home: <repo>/sdlc-spdd/. Requirements, canvases, harness skills, installed scripts, and committed memory sit together; runtime state stays gitignored under .sdlc/.

09-install-layout — what setup-agent-prompts.sh / upgrade-project.sh lay down.

Legacy sprawled installs (framework dirs at repo root) still resolve until you run sdlc-engine storage migrate --consolidate. New projects get the single-folder layout from day one.

Ledger-first memory

The committed system of record is one append-only file: spdd/memory/lessons.jsonl. Work claim/release events go to spdd/memory/registry.jsonl. Neither file is hand-edited — agents stage via sdlc.sh capture and promote via sdlc.sh accept at retro/sync.

05-storage-model — one ledger; sqlite and Guide are downstream.

Stage quietly, accept at the gate

Captures land in gitignored .sdlc/staged/lessons.jsonl during coding and review. Nothing hits the committed ledger until retro or sync runs accept — one batched promotion instead of capture noise in git history.

06-stage-then-accept — the quiet capture / loud accept split.

Projections you can rebuild

Optional backends — local SQLite (.sdlc/index.sqlite) and Guide DICE (Neo4j via orch-guide) — are regenerable projections of the same ledger. One write path; sdlc-engine context parity checks they still match.

08-projection-parity — if Guide is down, files still win.

Lifecycle with storage gates

The SPDD hybrid lifecycle (Initialize → Analysis → … → Retro → Sync) now has explicit storage checkpoints: analysis indexes land in staged memory; retro/sync accept promotes keepers before the next Work ID.

04-lifecycle-flow — when memory moves from hot session to durable ledger.

What sits inside the home folder

Adapters talk to Cursor/Copilot/Claude; the Python engine owns workflow, persistence config, and optional Guide ops; shell scripts remain the supported install path for consumers.

02-container — the moving parts after v3.

Mental model in one line: canvases and requirements are read directly; the lessons ledger is the committed record; Guide and SQLite are working stores you query on demand; captures stage quietly and accept at gates. Full spec: docs/storage-v3.md. All diagrams: docs/diagrams/.

What we shipped to get here

• PR #141 — storage v3 on main: single-folder install, JSONL ledger + registry, staged captures, test-suite restructure (unit / integration / e2e), migration tooling.
• Consumer matrix — live install scenarios green; two intentional skips where dogfood canvas is empty (documented, not failures).
• PR #148 (in flight) — ADF template library + Vue3 ops console rebased onto v3 paths; closes stale PR #115.

Try it

1. Read storage v3 and skim the PlantUML sources (./scripts/render-diagrams.sh regenerates SVG).
2. On an existing install: sdlc-engine storage status then migrate when ready.
3. Opt into Guide only when you want cross-work graph retrieval — file indexes remain the baseline.

— John · github.com/jmjava/sdlc-spdd-orchestrator