savepoint 1.0.0

package/.savepoint/audit/E01-scaffolding/proposals/Design.md

@@ -0,0 +1,210 @@
+---
+type: project-design
+status: active
+last_audited: E01-scaffolding (2026-04-27)
+---
+
+# Savepoint — System Architecture
+
+> Project-level architecture. Audit-kept fresh: every epic's audit step merges its delta into this document.
+>
+> **Visual identity** lives separately in `.savepoint/visual-identity.md` and is loaded only for TUI/theme/visual tasks.
+
+## 1. Architecture model
+
+- **File-only.** No MCP server in v1. Agents read and edit Markdown + YAML files directly using their native file tools.
+- **Agent-agnostic via the Router Pattern:**
+  1. `AGENTS.md` at the project root (spec-compliant; readable by all major coding agents).
+  2. `AGENTS.md` routes the agent into `.savepoint/router.md` (the state-machine file).
+  3. `.savepoint/router.md` conditionally points the agent at the next template prompt based on project state.
+  4. Templates contain **embedded HTML-comment instructions** (`<!-- AGENT: ... -->`) the agent follows verbatim.
+- **Token-efficiency principle.**
+  - Cold session bootstrap: ~5–7K tokens (one-time per conversation).
+  - Per-task incremental: <2KB.
+  - Audit: 5–15KB.
+  - Anything that breaks these bounds violates the wedge.
+
+## 2. Directory layout
+
+```
+<project-root>/
+├── AGENTS.md                       ← uppercase, spec-standard, agent entry point
+└── .savepoint/
+    ├── PRD.md                      ← project vision (rare changes)
+    ├── Design.md                   ← project architecture (this file)
+    ├── visual-identity.md          ← design system; loaded conditionally for TUI work
+    ├── router.md                   ← state-machine routing
+    ├── config.yml                  ← theme, quality_gates, verify_strict
+    ├── audit/
+    │   └── {E##-epic}/
+    │       ├── snapshot.md
+    │       └── proposals/
+    └── releases/
+        └── v1/
+            ├── PRD.md              ← release-scoped PRD
+            └── epics/
+                └── E##-{epic-name}/
+                    ├── Design.md   ← epic delta
+                    └── tasks/
+                        └── T001-slug.md
+```
+
+- `AGENTS.md` is at root (uppercase, cross-vendor spec).
+- `Design.md` lives in `.savepoint/` (working doc, not public-facing).
+- `visual-identity.md` is conditional — only loaded by router for TUI/theme/visual tasks.
+- **Subtasks are inline checklists** inside the task `.md` — never separate files.
+- Epic folders are prefixed for navigation (`E01-scaffolding/`). Task files and IDs are prefixed the same way (`T001-package-baseline.md`).
+
+## 3. Hierarchy semantics
+
+| Level        | Definition                                                                             |
+| ------------ | -------------------------------------------------------------------------------------- |
+| **Release**  | The thing being built. One PRD per release. v1 = MVP.                                  |
+| **Epic**     | A major feature within a release. Has its own Design.md (delta from project Design).   |
+| **Task**     | Independently buildable. Objective-led. **Requires implementation plan before build.** |
+| **Sub-task** | Inline checklist item — _evidence of the implementation plan_, not standalone work.    |
+
+## 4. Status model & gates
+
+Five statuses, with explicit gates:
+
+| Status        | Meaning                           | Entry gate                                    |
+| ------------- | --------------------------------- | --------------------------------------------- |
+| `backlog`     | Task exists, no plan              | created                                       |
+| `planned`     | Implementation plan written       | plan section non-empty                        |
+| `in_progress` | AI building                       | all `depends_on` are `done`                   |
+| `review`      | Build done, awaiting verification | all sub-tasks checked off                     |
+| `done`        | Verified, locked                  | assertion + (configurable) quality gates pass |
+
+- `blocked` is a **flag**, not a status — `in_progress` + `blocked: "reason"` is valid.
+- Reverts allowed; reverting from `done` warns about audit staleness.
+- **Verification mode is configurable per project** (`verify_strict: true|false`). Default: `false` (vibe-coder soft mode).
+
+## 5. Dependencies
+
+- Declared in YAML frontmatter: `depends_on: [E##-epic/T###-task-id, ...]` (repo-relative IDs).
+- Cross-epic deps allowed but warned (signal that epic boundaries may be wrong).
+- TUI shows blocked tasks as visually locked.
+- `savepoint doctor` detects cycles.
+
+## 6. CLI surface (5 commands, no more)
+
+| Command                | Purpose                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `savepoint init`       | Scaffold `.savepoint/`, print magic prompt to stdout + clipboard                  |
+| `savepoint board`      | Launch TUI; auto-falls-back to plain table on non-TTY                             |
+| `savepoint audit`      | Run audit pipeline (`--skip --reason`, `--epic`)                                  |
+| `savepoint doctor`     | Integrity check + ad-hoc quality-gate run + Layer-2 prompt for AI semantic review |
+| `--version` / `--help` | Standard                                                                          |
+
+- Bare `savepoint` prints help.
+- **Explicitly rejected:** `task new`, `epic new`, `release new`, `plan`, `next`, `status`, `task done`. All are file edits or TUI actions.
+- **Agents must not run `savepoint` commands.** Stated in AGENTS.md.
+
+**Names:** npm package `savepoint`; binary `savepoint`. No `vk` alias.
+
+## 7. Audit pipeline (6 steps)
+
+```
+0. Quality Gates  — CLI runs configured commands. Halts on failure if block_on_failure: true.
+1. Snapshot       — CLI writes file tree (gitignore-respecting) + changed-files list. NO code contents.
+2. Diff Brief     — State flips to audit_pending: {E##-epic}. Magic prompt printed to user.
+3. Reconcile      — Agent reads epic Design + snapshot + scoped code. Writes proposed updates to
+                    .savepoint/audit/{E##-epic}/proposals/.
+4. Review         — TUI shows side-by-side per-proposal diff. Approve / reject / edit each.
+5. Commit         — Approved proposals overwrite live files. Epic gets status: audited. Next epic unlocks.
+```
+
+- **First epic = E01-scaffolding by convention.** First audit establishes the baseline. ✓ _E01-scaffolding audited 2026-04-27._
+- `audit_pending` is a **hard gate**: next epic's tasks cannot enter `in_progress` until prior epic is `audited`.
+- **High-divergence guard:** if a proposal changes >50% of the live file, TUI requires extra confirmation (threshold tunable in `config.yml`).
+- **Skip allowed** via `savepoint audit --skip --reason "..."`. Logged to `.savepoint/audit-log.md`. Permanent `⚠ skipped` badge in TUI.
+- **Codebase Map** auto-generated in `AGENTS.md` between markers — one line per top-level module pointing to its epic Design.
+
+### Quality gates (audit step 0)
+
+```yaml
+# .savepoint/config.yml
+quality_gates:
+  lint: "<command>" # null to disable
+  typecheck: "<command>"
+  test: "<command>"
+  block_on_failure: true
+```
+
+Three layers:
+
+- **Layer 1 (mechanical):** user's chosen linter (we recommend, don't ship). TS: `eslint` + `dependency-cruiser`. Python: `radon` + `pylint`. Go: `gocyclo` + `staticcheck`. **Cross-language fallback:** `lizard`.
+- **Layer 2 (AI semantic review):** baked into the audit reconcile prompt. Outputs `quality-review.md` proposal. **Advisory, not blocking.**
+- **Layer 3:** `savepoint doctor` runs Layer 1 + prints Layer 2 prompt for ad-hoc use.
+
+## 8. TUI
+
+**Theming:** Atari-Noir is the default theme. **For full design tokens, palette, and rendering rules, see `.savepoint/visual-identity.md`** (loaded conditionally for TUI tasks). Live values in `config.yml` `theme:` section.
+
+Acknowledged terminal limits: fonts, scanlines, glows, letter-spacing, mouse-driven motion don't translate. Lean on color discipline + box-drawing geometry + uppercase headings.
+
+**Render fallbacks:** 256-color → 16-color hard-coded → `NO_COLOR=1` monochrome with glyphs → non-TTY plain table.
+
+**Layout:** single screen — header (release/epic context) + 5-column Kanban + detail pane.
+
+**Keybindings:** arrow + vim. `space`/`enter`/`e`/`r`/`R`/`E`/`A`/`q`. **No file watching MVP** (manual `r` refresh).
+
+**Out of MVP:** file watching, drag-and-drop, multi-select, search, inline editing.
+
+## 9. Concurrency
+
+- **mtime-based optimistic concurrency.** TUI reads mtime, re-stats before write, prompts "Reload? [Y/n]" on conflict.
+- Agents edit freely; the TUI defers.
+- **No lockfile.**
+
+## 10. Release versioning (PRDs)
+
+- Sequential integer (`v1`, `v2`). Optional `name` in YAML.
+- `savepoint doctor` warns when creating `v2` while `v1` has un-audited epics.
+
+## 11. Failure modes
+
+All routed through `savepoint doctor`. Doctor diagnoses and proposes; never auto-destructive.
+
+| Failure                                      | Behavior                                                    |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| Corrupt YAML                                 | Doctor flags file:line. TUI marks `⚠ corrupt`, refuses ops. |
+| Missing dep                                  | Doctor flags. TUI shows `⚠ broken dep`.                     |
+| Dependency cycle                             | Doctor refuses to start either side; prints cycle path.     |
+| Duplicate task ID                            | Doctor flags.                                               |
+| Audit proposals without `audit_pending` flag | Doctor offers cleanup or restore.                           |
+| Task in nonexistent epic                     | Doctor moves to `.savepoint/orphans/`.                      |
+| Missing `config.yml`                         | All commands except `init` refuse.                          |
+| Unknown CLI flag                             | Show help, exit 1.                                          |
+
+## 12. Distribution & build
+
+- **License:** MIT.
+- **Install:** primary `npx savepoint init`, persistent `npm i -g savepoint` → `savepoint`.
+- **Runtime:** Node 20.10+ LTS, ESM-only, no native deps. macOS / Linux / Windows-Terminal.
+- **Repo:** single package. TypeScript strict. `tsup` build → `dist/`. Bin `dist/cli.js` shebanged.
+- **No telemetry.** Ever.
+- **Baseline scaffold:** established in epic `E01-scaffolding` (2026-04-27). Package name `savepoint`, version `0.1.0`. Build, typecheck, lint, format, and test gates all pass.
+
+## 13. Testing
+
+| Layer                                                    | Tool                             | Coverage                                                               |
+| -------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| Unit: file ops, YAML, frontmatter, snapshot gen          | `vitest`                         | High                                                                   |
+| Unit: state transitions, dep resolution, cycle detection | `vitest`                         | High                                                                   |
+| Integration: CLI commands in temp dirs                   | `vitest` + `tmp`                 | Medium                                                                 |
+| TUI reducers (state, isolated from rendering)            | `vitest` + `ink-testing-library` | Medium                                                                 |
+| TUI rendering (snapshot tests)                           | —                                | **None.** Brittle.                                                     |
+| End-to-end with real AI agents                           | Manual matrix                    | Pre-release: `[Claude, Cursor, Gemini, Aider]` × `[init, plan, audit]` |
+
+~70% line coverage target; behavior coverage prioritized.
+
+## 14. Package versioning
+
+- `0.1.0` — first public release: scaffolding, status model, CLI, basic TUI, audit (no AI semantic review).
+- `0.2.0` — AI semantic review + broader quality-gate language presets.
+- `0.3.0` — file watching, search.
+- `1.0.0` — MCP server + production stability.
+
+Strict semver. Pre-1.0 minors may break.

package/.savepoint/audit/E01-scaffolding/proposals/epic-Design.md

@@ -0,0 +1,117 @@
+---
+type: epic-design
+status: audited
+audited: 2026-04-27
+---
+
+# Epic E01: scaffolding
+
+## Purpose
+
+Create the minimum production-ready TypeScript package foundation for `savepoint`, including build, test, lint, formatting, package metadata, and source tree conventions. This epic establishes the first auditable codebase baseline without implementing user-facing Savepoint behavior.
+
+## What this epic adds
+
+- A single-package Node 20.10+ TypeScript project using ESM.
+- npm package metadata for package name `savepoint` and binary name `savepoint`.
+- A `tsup` build that emits `dist/cli.js` with a Node shebang.
+- Strict TypeScript configuration.
+- Vitest test setup for future unit and integration tests.
+- ESLint and Prettier configuration for mechanical quality gates.
+- A minimal source layout that future epics can extend.
+- Baseline npm scripts for build, typecheck, lint, format check, and test.
+- Root documentation and ignore files needed for ordinary OSS development.
+
+## Components and files
+
+Expected files introduced by this epic:
+
+| Path                 | Purpose                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| `package.json`       | Package metadata, bin mapping, scripts, dependencies, files allowlist.   |
+| `package-lock.json`  | Locked dependency graph for repeatable installs.                         |
+| `tsconfig.json`      | Strict TypeScript compiler settings for ESM Node output.                 |
+| `tsup.config.ts`     | Build entry and output configuration.                                    |
+| `vitest.config.ts`   | Test runner configuration.                                               |
+| `eslint.config.js`   | Flat ESLint config for TypeScript.                                       |
+| `.prettierrc.json`   | Formatting rules.                                                        |
+| `.gitignore`         | Ignore generated artifacts and local environment files.                  |
+| `README.md`          | Minimal development README until release docs expand it.                 |
+| `LICENSE`            | MIT license placeholder for the package.                                 |
+| `src/cli.ts`         | Minimal executable entrypoint that prints help/version placeholder text. |
+| `src/version.ts`     | Single source for the package version used by the placeholder CLI.       |
+| `test/smoke.test.ts` | Baseline test proving the test runner and exported constants work.       |
+
+## Architectural delta
+
+Before this epic, the repository contains only planning markdown and Savepoint workflow metadata. After this epic, it becomes an installable npm package skeleton with a compilable CLI entrypoint.
+
+This does not add the actual Savepoint command system. The placeholder `src/cli.ts` exists only to validate packaging, shebang output, and the future binary surface. Real command dispatch belongs to `cli-foundation`.
+
+## Boundaries
+
+In scope:
+
+- Configure the repo as an ESM-only TypeScript package.
+- Make `npm run build`, `npm run typecheck`, `npm run lint`, and `npm test` meaningful.
+- Keep runtime code minimal and dependency-light.
+- Use package and binary name `savepoint`.
+
+Out of scope:
+
+- Argument parsing beyond placeholder help/version output.
+- Reading or writing `.savepoint` project files.
+- Implementing `init`, `board`, `audit`, or `doctor`.
+- Ink, React, TUI rendering, theming, or visual identity work.
+- Template content or Router Pattern prompt assets.
+- Release publishing automation beyond package metadata basics.
+
+## Quality gates
+
+The scaffold supports these commands:
+
+```bash
+npm run build
+npm run typecheck
+npm run lint
+npm run format:check
+npm test
+```
+
+## Design constraints
+
+- Keep files small and obvious; no framework or architecture abstractions before there is behavior to organize.
+- Use strict typing from the first commit.
+- Avoid `any`.
+- Keep config conventional enough that a vibe coder can recognize and modify it.
+- Do not add native dependencies.
+- Do not add telemetry, update checks, analytics, or postinstall scripts.
+
+## Open decisions
+
+- The exact dependency versions are implementation details, but they should be current stable versions compatible with Node 20.10+.
+- `README.md` should stay intentionally sparse in this epic; fuller public-facing docs belong to `docs-and-packaging`.
+
+## Implemented as
+
+Implemented on 2026-04-27 across tasks T001–T005. All quality gates pass.
+
+**Deviations from original design:**
+
+| Item                         | Deviation                | Reason                                                                                                                                                                                     |
+| ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `vitest.config.js`           | Extra file not in design | `npm test` requires `--configLoader runner` pointing at a `.js` config on Windows; `.ts` config cannot be loaded directly in this execution path                                           |
+| `scripts/vitest-preload.cjs` | Extra file not in design | Windows runner executes a `net use` child_process call during Vitest startup; this CJS preload stubs that call and also stubs esbuild transforms to avoid a secondary Windows compat issue |
+| `.prettierignore`            | Extra file not in design | Standard convention; consistent with `.gitignore` exclusions                                                                                                                               |
+
+**Dependency versions (pinned):**
+
+| Package             | Version |
+| ------------------- | ------- |
+| `typescript`        | ^5.8.3  |
+| `tsup`              | ^8.5.1  |
+| `vitest`            | ^3.2.4  |
+| `eslint`            | ^9.33.0 |
+| `typescript-eslint` | ^8.39.0 |
+| `prettier`          | ^3.6.2  |
+| `@types/node`       | ^24.1.0 |

package/.savepoint/audit/E01-scaffolding/proposals/quality-review.md

@@ -0,0 +1,101 @@
+---
+type: quality-review
+epic: E01-scaffolding
+reviewed: 2026-04-27
+advisory: true
+---
+
+# Quality Review: E01-scaffolding
+
+Semantic review of the scaffolded source against the 10 Code Style rules from `AGENTS.md`. Advisory only — no blocking issues.
+
+---
+
+## Rule-by-rule findings
+
+### 1. One job per file ✓
+
+`src/cli.ts` handles argument dispatch and output. `src/version.ts` is a single export. No file does two things.
+
+### 2. One-sentence rule ✓
+
+`printHelp()` — prints the placeholder help banner. `main()` — dispatches on argv and calls the appropriate output function. Both are one-sentence describable.
+
+### 3. Test what branches ⚠ advisory
+
+`src/cli.ts` has a branch on `command === "--version"`. The smoke test in `test/smoke.test.ts` only covers `src/version.ts`. The CLI dispatch logic is untested.
+
+This is acceptable at scaffold stage — the branches contain only placeholder output and will be replaced in `cli-foundation`. Flag for that epic: when real dispatch lands, cover every branch.
+
+### 4. Types are documentation ✓
+
+No `any` anywhere in source or test. Return types are declared (`void`). ESLint is configured to error on `@typescript-eslint/no-explicit-any`.
+
+### 5. Build, don't speculate ✓
+
+No abstraction layers, registries, or plugin systems. Placeholder CLI is minimal: two functions and a `main()` call. Nothing exists for hypothetical future behavior.
+
+### 6. Errors at boundaries ✓ (n/a at scaffold)
+
+No real system boundaries in placeholder code. The CLI entrypoint reads only `process.argv`, which cannot throw. Acceptable for a placeholder.
+
+### 7. One source of truth ✓
+
+Version string is declared once in `src/version.ts` and imported by `src/cli.ts`. `package.json` also contains `"version": "0.1.0"` — this is expected (npm requires it there), not a violation. When the CLI reads its own version at runtime, it imports from `src/version.ts`, not from `package.json` directly.
+
+> **Recommendation for `cli-foundation`:** consider whether `version.ts` should derive from `package.json` at build time (via `tsup` banner injection or a build-time const) to eliminate the manual sync requirement. Not urgent at `0.1.0`.
+
+### 8. Comments explain WHY ✓
+
+No comments in any source file. Config files have no inline comments. Good.
+
+### 9. Content in data files ✓ (n/a at scaffold)
+
+No user-facing content exists yet. Config is in conventional JSON/TS config files.
+
+### 10. Small diffs ✓
+
+Epic split into 5 tasks with clear separation: package metadata → TypeScript build → test runner → lint/format → verification. Each task touched a minimal set of files with declared dependencies.
+
+---
+
+## Structural observations
+
+### Dual vitest config files
+
+`vitest.config.ts` and `vitest.config.js` are identical. The `.js` variant is the one actually used by `npm test` (required for `--configLoader runner`). The `.ts` variant is unused but exists as the "source of truth" for IDE tooling and type checking.
+
+**Recommendation:** document this in a comment in `vitest.config.ts`, or remove it and keep only `.js`. The dual-file situation will confuse future contributors who edit `.ts` expecting it to take effect.
+
+### scripts/vitest-preload.cjs complexity
+
+The preload script stubs two unrelated things: a `net use` child_process call (Windows network drive detection in Vitest's environment) and `esbuild.transform`/`transformSync` (a secondary Windows compat issue). The stubs are correct and well-structured.
+
+**Recommendation:** add a single-line comment per stub explaining the specific Windows issue being worked around (bug reference or symptom description). The WHY is not obvious — a future contributor would not know whether these stubs are still needed after a Vitest upgrade.
+
+### test/smoke.test.ts include pattern
+
+`vitest.config.js` uses `include: ["test/**/*.test.js"]` but the actual test file is `smoke.test.ts`. This works because Vitest transforms TypeScript to JS before matching, but the pattern is misleading.
+
+**Recommendation:** change include to `["test/**/*.test.ts"]` to match what actually exists in the repo.
+
+---
+
+## Must Fix Before Close
+
+None.
+
+## Carry Forward
+
+- Add CLI branch tests when real dispatch is implemented in `E03-cli-foundation`.
+- Decide in `E03-cli-foundation` whether `src/version.ts` should derive from `package.json`.
+
+## Already Fixed
+
+- `vitest.config.ts` now documents the dual-config setup.
+- `scripts/vitest-preload.cjs` now explains the Windows `net use` and esbuild workarounds.
+- Vitest include patterns now match `test/**/*.test.ts`.
+
+## Summary
+
+No blocking issues remain for `E01-scaffolding`.

package/.savepoint/audit/E01-scaffolding/snapshot.md

@@ -0,0 +1,54 @@
+---
+type: audit-snapshot
+epic: E01-scaffolding
+created: 2026-04-27
+---
+
+# Audit Snapshot: E01-scaffolding
+
+All files are new — this is the first auditable baseline.
+
+## Source file tree
+
+```
+src/
+  cli.ts                    — CLI entrypoint; placeholder help/version output
+  version.ts                — single export for package version string
+test/
+  smoke.test.ts             — Vitest smoke test asserting exported version
+scripts/
+  vitest-preload.cjs        — Windows runner workaround (stubs net use + esbuild)
+```
+
+## Config / metadata files
+
+| Path                | Purpose                                                            |
+| ------------------- | ------------------------------------------------------------------ |
+| `package.json`      | Package name, bin mapping, scripts, devDependencies                |
+| `package-lock.json` | Locked dependency graph                                            |
+| `tsconfig.json`     | Strict NodeNext TypeScript compiler settings                       |
+| `tsup.config.ts`    | Build entry and output config (ESM, node20)                        |
+| `vitest.config.ts`  | Vitest config (TypeScript source)                                  |
+| `vitest.config.js`  | Vitest config (JS copy used by npm test via --configLoader runner) |
+| `eslint.config.js`  | Flat ESLint config — rejects `any` in TypeScript                   |
+| `.prettierrc.json`  | Prettier rules (double quotes, trailing commas)                    |
+| `.prettierignore`   | Excludes dist/, coverage/, node_modules/ from formatting           |
+| `.gitignore`        | Excludes generated artifacts and local env files                   |
+| `README.md`         | Minimal development README                                         |
+| `LICENSE`           | MIT license                                                        |
+
+## Quality gates (all passed)
+
+- `npm run build` ✓
+- `npm run typecheck` ✓
+- `npm run lint` ✓
+- `npm run format:check` ✓
+- `npm test` ✓
+
+## Deviations from epic Design
+
+| Item                         | Status | Note                                                                        |
+| ---------------------------- | ------ | --------------------------------------------------------------------------- |
+| `vitest.config.js`           | extra  | Duplicate of `.ts` variant; required for `--configLoader runner` on Windows |
+| `scripts/vitest-preload.cjs` | extra  | Windows-specific: stubs `net use` child_process call and esbuild transforms |
+| `.prettierignore`            | extra  | Not listed in Design but conventional; consistent with `.gitignore`         |

package/.savepoint/audit/E02-data-model/snapshot.md

@@ -0,0 +1,128 @@
+---
+type: audit-snapshot
+epic: E02-data-model
+created: 2026-04-27
+manual: true
+---
+
+# Audit Snapshot: E02-data-model
+
+Manual snapshot generated because `savepoint audit` is not implemented yet.
+
+## Source file tree
+
+```
+src/
+  domain/
+    config.ts       - config defaults and typed project config model
+    epic.ts         - epic Design frontmatter model
+    ids.ts          - release, epic, and task ID parsing/formatting
+    release.ts      - release PRD frontmatter model
+    router.ts       - router state model and validation
+    status.ts       - task status values and transition validation
+    task.ts         - task frontmatter and document validation
+  fs/
+    markdown.ts     - markdown/frontmatter read boundary with path-aware errors
+    project.ts      - .savepoint root and scoped path helpers
+  readers/
+    config.ts       - read-only config.yml reader
+    epic.ts         - read-only epic Design reader
+    release.ts      - read-only release PRD reader
+    router.ts       - read-only router Current state reader
+    tasks.ts        - epic task-set reader with graph validation
+  validation/
+    dependencies.ts - duplicate ID, missing dependency, and cycle detection
+test/
+  domain/           - unit tests for config, epic, IDs, release, router, status, task
+  fs/               - unit tests for markdown and project helpers
+  readers/          - unit tests for config, epic, release, router, task-set readers
+  validation/       - unit tests for dependency graph validation
+```
+
+## Config / metadata changes
+
+| Path                     | Purpose                                                        |
+| ------------------------ | -------------------------------------------------------------- |
+| `package.json`           | Adds `js-yaml` runtime dependency and `@types/js-yaml`.        |
+| `package-lock.json`      | Locks the new YAML parser dependency graph.                    |
+| `.prettierignore`        | Excludes `.claude/` from Prettier traversal.                   |
+| `.savepoint/router.md`   | Manually advances E02 to `audit-pending`.                      |
+| `AGENTS.md`              | Workflow text was tightened during E02 planning/building.      |
+| `README.md`              | Marketing/readme copy changed outside the E02 runtime layer.   |
+| `.savepoint/metrics/*`   | Context-benchmark notes changed outside the E02 runtime layer. |
+| `E02-data-model/tasks/*` | Seven planned and completed E02 task files.                    |
+
+## Changed files
+
+Tracked modified files:
+
+- `.prettierignore`
+- `.savepoint/metrics/context-bench.md`
+- `.savepoint/router.md`
+- `AGENTS.md`
+- `README.md`
+- `package-lock.json`
+- `package.json`
+
+New E02 files:
+
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T001-domain-ids-status.md`
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T002-markdown-frontmatter-boundary.md`
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T003-task-documents.md`
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T004-release-epic-router-config-readers.md`
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T005-dependency-validation.md`
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T006-epic-task-set-reader.md`
+- `.savepoint/releases/v1/epics/E02-data-model/tasks/T007-quality-gates.md`
+- `src/domain/config.ts`
+- `src/domain/epic.ts`
+- `src/domain/ids.ts`
+- `src/domain/release.ts`
+- `src/domain/router.ts`
+- `src/domain/status.ts`
+- `src/domain/task.ts`
+- `src/fs/markdown.ts`
+- `src/fs/project.ts`
+- `src/readers/config.ts`
+- `src/readers/epic.ts`
+- `src/readers/release.ts`
+- `src/readers/router.ts`
+- `src/readers/tasks.ts`
+- `src/validation/dependencies.ts`
+- `test/domain/config.test.ts`
+- `test/domain/epic.test.ts`
+- `test/domain/ids.test.ts`
+- `test/domain/release.test.ts`
+- `test/domain/router.test.ts`
+- `test/domain/status.test.ts`
+- `test/domain/task.test.ts`
+- `test/fs/markdown.test.ts`
+- `test/fs/project.test.ts`
+- `test/readers/config.test.ts`
+- `test/readers/epic.test.ts`
+- `test/readers/release.test.ts`
+- `test/readers/router.test.ts`
+- `test/readers/tasks.test.ts`
+- `test/validation/dependencies.test.ts`
+
+Local untracked file outside E02 scope:
+
+- `.claude/settings.local.json`
+
+## Quality gates
+
+- `npm run build` passed.
+- `npm run typecheck` passed.
+- `npm run lint` passed.
+- `npm run format:check` initially failed on E02 task markdown; after Prettier formatting, it passed.
+- `npm test` passed outside the sandbox: 16 files, 176 tests. Inside the sandbox it failed with `spawn EPERM` while Vitest/esbuild tried to start a child process.
+
+## Deviations from epic Design
+
+| Item                  | Status | Note                                                                                        |
+| --------------------- | ------ | ------------------------------------------------------------------------------------------- |
+| Audit snapshot        | manual | Generated by the agent because the E07 audit CLI does not exist yet.                        |
+| Router state          | manual | Advanced directly to `audit-pending` for E02 because the CLI transition does not exist yet. |
+| `done` transitions    | fixed  | `done -> review` is allowed so completed work can be reopened for audit-stale rechecks.     |
+| Config accent values  | fixed  | Config defaults ignore non-string custom accent values before merging.                      |
+| README/metrics edits  | extra  | Present in working tree but not part of the E02 data-model runtime layer.                   |
+| `.claude/` local file | extra  | Local untracked settings are ignored by Prettier but not by Git.                            |