savepoint 1.0.4 → 1.0.6

package/.savepoint/releases/v1/epics/_archived/E02-data-model/Design.md

@@ -1,142 +0,0 @@
----
-type: epic-design
-status: audited
-audited: 2026-04-27
----
-
-# Epic E02: data-model
-
-## Context Budget
-
-For implementation tasks in this epic, read only:
-
-- `.savepoint/router.md`
-- this epic `Design.md`
-- the active task file
-- directly touched source/test files
-
-Read `.savepoint/Design.md` only if the task changes architecture. Read `.savepoint/releases/v1/PRD.md`, prior epic docs, audit proposals, or `.savepoint/visual-identity.md` only when the active task explicitly requires them.
-
-## Purpose
-
-Build the core file-backed model for releases, epics, tasks, statuses, dependencies, and project configuration. This epic gives later CLI and TUI work a typed domain layer instead of each command parsing markdown independently.
-
-## What this epic adds
-
-- Typed models for releases, epics, tasks, task statuses, dependency IDs, config, and router state.
-- Markdown frontmatter parsing for task and planning files.
-- Readers for `.savepoint/releases/{release}/PRD.md`, epic `Design.md`, and task files.
-- Status transition validation for `planned`, `in_progress`, and `done`, with legacy `backlog` and `review` normalized on read.
-- Dependency resolution, missing dependency detection, and cycle detection.
-- Shared filesystem helpers for scoped `.savepoint` reads.
-- Unit tests for parsing, validation, dependency logic, and state transitions.
-
-## Implementation strategy
-
-- Use structured parsers for YAML/frontmatter and Markdown boundaries.
-- Keep domain types and validation pure; filesystem reads belong in `src/fs/*` and `src/readers/*`.
-- Keep writes out of scope except temporary test fixtures.
-- Make ID parsing understand prefixed epic and task IDs such as `E02-data-model/T001-readers`.
-- Return boundary errors that include the path and reason without forcing callers to parse error text.
-
-## Components and files
-
-Expected files introduced or extended by this epic:
-
-| Path                    | Purpose                                             |
-| ----------------------- | --------------------------------------------------- |
-| `src/domain/status.ts`  | Status values and transition rules.                 |
-| `src/domain/ids.ts`     | Release, epic, and task ID parsing/formatting.      |
-| `src/domain/task.ts`    | Task frontmatter and task document types.           |
-| `src/domain/release.ts` | Release PRD metadata types.                         |
-| `src/domain/config.ts`  | `config.yml` type and defaults.                     |
-| `src/fs/markdown.ts`    | Markdown/frontmatter read helpers.                  |
-| `src/fs/project.ts`     | Project root and `.savepoint` path helpers.         |
-| `src/readers/*.ts`      | Release, epic, task, router, and config readers.    |
-| `src/validation/*.ts`   | Status, dependency, duplicate ID, and cycle checks. |
-| `test/**/*.test.ts`     | Unit tests for the model and validation behavior.   |
-
-## Architectural delta
-
-Before this epic, Savepoint has only a package scaffold. After this epic, it has a reusable domain and read-only persistence layer for the file-based state machine.
-
-This epic intentionally avoids write operations except where tests create fixtures. Writes belong to later command/TUI/audit work once behavior exists.
-
-## Boundaries
-
-In scope:
-
-- Parse markdown frontmatter with clear boundary errors.
-- Model task dependencies using repo-relative task IDs.
-- Detect cycles and broken dependencies.
-- Expose pure validation functions usable by CLI, TUI, audit, and doctor.
-
-Out of scope:
-
-- Creating or editing tasks.
-- Rendering any TUI.
-- Implementing command dispatch.
-- Running quality gates.
-- Writing audit proposals.
-
-## Quality gates
-
-- Branching parser and validator logic must have unit tests.
-- Fixture files should be small and local to tests.
-- Errors should identify the file path and failure reason.
-
-## Design constraints
-
-- Prefer structured parsers over ad hoc string splitting.
-- Keep filesystem access at boundaries; domain validation should be pure.
-- Use one source of truth for status transitions and dependency rules.
-
-## Implemented as
-
-Implemented on 2026-04-27 across tasks T001-T007. The read-only data model landed with focused unit tests and passing mechanical gates after formatting the E02 task markdown.
-
-**Implemented components:**
-
-| Path                             | Result                                                                  |
-| -------------------------------- | ----------------------------------------------------------------------- |
-| `src/domain/ids.ts`              | Release, epic, and full task ID parsing plus formatting helpers.        |
-| `src/domain/status.ts`           | Canonical task status values and transition validation.                 |
-| `src/domain/task.ts`             | Task frontmatter and task document validation.                          |
-| `src/domain/release.ts`          | Release PRD frontmatter validation.                                     |
-| `src/domain/epic.ts`             | Epic Design frontmatter validation.                                     |
-| `src/domain/router.ts`           | Router state value and Current state validation.                        |
-| `src/domain/config.ts`           | Config defaults and merge behavior.                                     |
-| `src/fs/markdown.ts`             | Structured YAML frontmatter parsing with path-aware boundary errors.    |
-| `src/fs/project.ts`              | `.savepoint` root discovery and scoped path construction.               |
-| `src/readers/*.ts`               | Read-only release, epic, router, config, and task-set readers.          |
-| `src/validation/dependencies.ts` | Duplicate task ID, missing dependency, and cycle detection.             |
-| `test/**/*.test.ts`              | Branch coverage for parser, reader, status, config, and graph behavior. |
-
-**Deviations from original design:**
-
-| Item                          | Deviation            | Reason / follow-up                                                                      |
-| ----------------------------- | -------------------- | --------------------------------------------------------------------------------------- |
-| `done` status transitions     | Fixed during audit   | `done -> review` is allowed so completed work can be reopened for audit-stale rechecks. |
-| Config accent validation      | Fixed during audit   | Non-string custom accent values are ignored before merging defaults.                    |
-| Audit snapshot/router flip    | Manual               | Expected until E07 implements the audit CLI pipeline.                                   |
-| `.claude/settings.local.json` | Local untracked file | Decide whether to add `.claude/` to `.gitignore` before commit.                         |
-
-**Quality gates:**
-
-| Gate                   | Result                                                                                   |
-| ---------------------- | ---------------------------------------------------------------------------------------- |
-| `npm run build`        | Passed.                                                                                  |
-| `npm run typecheck`    | Passed.                                                                                  |
-| `npm run lint`         | Passed.                                                                                  |
-| `npm run format:check` | Passed after formatting E02 task markdown.                                               |
-| `npm test`             | Passed outside sandbox: 16 test files, 176 tests. Sandbox run hit esbuild `spawn EPERM`. |
-
-## Close Criteria
-
-- All `E02-data-model` tasks are `done`.
-- `npm run build`, `npm run typecheck`, `npm run lint`, `npm run format:check`, and `npm test` pass.
-- Tests cover parser errors, valid documents, invalid statuses, allowed and disallowed status transitions, missing dependencies, duplicate IDs, and dependency cycles.
-- Audit snapshot exists at `.savepoint/audit/E02-data-model/snapshot.md`.
-- Audit proposals are accepted, rejected, or explicitly carried forward.
-- This epic `Design.md` has `status: audited`.
-- Router points to the next epic state.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T001-domain-ids-status.md

@@ -1,27 +0,0 @@
----
-id: E02-data-model/T001-domain-ids-status
-status: done
-objective: "Define pure domain primitives for release, epic, task IDs, task statuses, and allowed status transitions."
-depends_on: []
----
-
-# T001: Domain IDs and Statuses
-
-## Scope
-
-Introduce the core domain types and validation helpers that later readers and validators can share.
-
-## Acceptance Criteria
-
-- Release, epic, and task ID parsing accepts the E02 design's expected ID shapes.
-- Task status values are represented from one source of truth.
-- Status transition validation covers allowed and disallowed transitions.
-- Branching validation behavior has focused unit tests.
-
-## Implementation Plan
-
-- [x] Inspect existing package/test conventions needed to place domain modules and focused unit tests.
-- [x] Add pure ID parsing and formatting helpers for release IDs, epic IDs, task numbers, and full task IDs.
-- [x] Add task status constants/types and one transition rule table for `backlog`, `planned`, `in_progress`, `review`, and `done`.
-- [x] Add validation helpers that return typed success/failure results without filesystem access.
-- [x] Add unit tests for valid and invalid ID shapes plus allowed and disallowed status transitions.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T002-markdown-frontmatter-boundary.md

@@ -1,28 +0,0 @@
----
-id: E02-data-model/T002-markdown-frontmatter-boundary
-status: done
-objective: "Add scoped markdown/frontmatter read helpers that return typed boundary errors with file path and reason."
-depends_on:
-  - E02-data-model/T001-domain-ids-status
----
-
-# T002: Markdown Frontmatter Boundary
-
-## Scope
-
-Create the filesystem boundary for reading markdown documents with structured frontmatter parsing.
-
-## Acceptance Criteria
-
-- Markdown documents can be read from scoped project paths.
-- Frontmatter is parsed with a structured YAML/frontmatter parser.
-- Missing, malformed, or invalid frontmatter returns errors that include path and reason.
-- Parser success and failure branches have focused unit tests.
-
-## Implementation Plan
-
-- [x] Review the T001 domain result/error style and existing test fixture conventions.
-- [x] Add a scoped project path helper for locating `.savepoint` documents without exposing arbitrary filesystem reads.
-- [x] Add a markdown/frontmatter reader that uses a structured parser and preserves markdown body content.
-- [x] Define path-aware boundary errors for missing files, missing frontmatter, malformed frontmatter, and schema rejection.
-- [x] Add focused unit tests for successful reads and each parser/boundary failure branch using small temporary fixtures.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T003-task-documents.md

@@ -1,29 +0,0 @@
----
-id: E02-data-model/T003-task-documents
-status: done
-objective: "Parse task markdown files into typed task documents with validated IDs, statuses, objectives, and dependency IDs."
-depends_on:
-  - E02-data-model/T001-domain-ids-status
-  - E02-data-model/T002-markdown-frontmatter-boundary
----
-
-# T003: Task Documents
-
-## Scope
-
-Build the task reader and task document model on top of the markdown/frontmatter boundary.
-
-## Acceptance Criteria
-
-- Task frontmatter maps into a typed task document.
-- Invalid task IDs, statuses, objectives, or dependency IDs are rejected with path-aware errors.
-- Markdown body content remains available to callers.
-- Valid and invalid task document cases have focused unit tests.
-
-## Implementation Plan
-
-- [x] Reuse the T001 ID/status validators and the T002 markdown/frontmatter boundary as the only parsing inputs.
-- [x] Define the typed task frontmatter and task document model, including validated dependency IDs and markdown body.
-- [x] Implement task document parsing that rejects invalid IDs, statuses, missing objectives, and malformed `depends_on` values with path-aware errors.
-- [x] Keep task parsing read-only and separate pure frontmatter validation from filesystem access.
-- [x] Add focused unit tests for valid task files and each invalid frontmatter branch.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T004-release-epic-router-config-readers.md

@@ -1,30 +0,0 @@
----
-id: E02-data-model/T004-release-epic-router-config-readers
-status: done
-objective: "Add read-only models and readers for release PRDs, epic designs, router state, and project configuration."
-depends_on:
-  - E02-data-model/T001-domain-ids-status
-  - E02-data-model/T002-markdown-frontmatter-boundary
----
-
-# T004: Release, Epic, Router, and Config Readers
-
-## Scope
-
-Expose typed read-only access for the remaining Savepoint planning documents and config state.
-
-## Acceptance Criteria
-
-- Release PRD, epic Design, router state, and config data have typed models.
-- Readers keep filesystem access at the boundary.
-- Config defaults are applied from one place.
-- Missing or malformed input returns path-aware boundary errors.
-- Reader branches and config default behavior have focused unit tests.
-
-## Implementation Plan
-
-- [x] Reuse the T001 domain primitives and T002 markdown/frontmatter boundary for all document reads.
-- [x] Define typed models for release PRD metadata, epic Design metadata, router state, and project config defaults.
-- [x] Implement read-only readers that keep path resolution and file IO at the boundary.
-- [x] Apply config defaults from one exported source of truth before returning typed config data.
-- [x] Add focused unit tests for valid reads, malformed or missing input, router-state validation, and config default behavior.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T005-dependency-validation.md

@@ -1,29 +0,0 @@
----
-id: E02-data-model/T005-dependency-validation
-status: done
-objective: "Validate task dependency graphs for missing dependencies, duplicate IDs, and cycles using pure domain functions."
-depends_on:
-  - E02-data-model/T003-task-documents
----
-
-# T005: Dependency Validation
-
-## Scope
-
-Implement dependency resolution and graph validation over parsed task documents.
-
-## Acceptance Criteria
-
-- Missing dependency IDs are reported with the dependent task ID.
-- Duplicate task IDs are detected.
-- Dependency cycles are detected and reported with enough IDs to explain the cycle.
-- Validation functions are pure and do not read files.
-- Missing dependency, duplicate ID, and cycle branches have focused unit tests.
-
-## Implementation Plan
-
-- [x] Build on the T003 task document model and keep validation functions independent of filesystem access.
-- [x] Implement duplicate task ID detection over a task document collection.
-- [x] Implement missing dependency detection that reports the dependent task ID and unresolved dependency ID.
-- [x] Implement dependency cycle detection that returns enough task IDs to explain the cycle.
-- [x] Add focused unit tests for valid graphs, missing dependencies, duplicate IDs, simple cycles, and longer cycles.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T006-epic-task-set-reader.md

@@ -1,29 +0,0 @@
----
-id: E02-data-model/T006-epic-task-set-reader
-status: done
-objective: "Read an epic task directory into a validated task set using the task reader and dependency validation."
-depends_on:
-  - E02-data-model/T003-task-documents
-  - E02-data-model/T005-dependency-validation
----
-
-# T006: Epic Task Set Reader
-
-## Scope
-
-Connect the file-backed task reader to dependency validation for an entire epic's task directory.
-
-## Acceptance Criteria
-
-- An epic task directory is read into a typed task set.
-- Dependency validation runs after all task files are parsed.
-- File boundary errors and graph validation errors remain distinguishable.
-- Valid task sets and invalid graph cases have focused unit tests with small fixtures.
-
-## Implementation Plan
-
-- [x] Reuse the T003 task reader and T005 dependency validation without duplicating parsing or graph logic.
-- [x] Add an epic task directory reader that discovers task markdown files and parses each into typed task documents.
-- [x] Run dependency validation only after all readable task files have been parsed.
-- [x] Return distinguishable results for file boundary failures versus dependency graph validation failures.
-- [x] Add focused fixture tests for a valid task set, parse failures, missing dependencies, duplicate IDs, and cycles.

package/.savepoint/releases/v1/epics/_archived/E02-data-model/tasks/T007-quality-gates.md

@@ -1,31 +0,0 @@
----
-id: E02-data-model/T007-quality-gates
-status: done
-objective: "Run and fix the E02 data-model quality gates so the read-only domain layer is buildable and covered."
-depends_on:
-  - E02-data-model/T004-release-epic-router-config-readers
-  - E02-data-model/T006-epic-task-set-reader
----
-
-# T007: Quality Gates
-
-## Scope
-
-Close the epic implementation by running the required checks and making any small fixes needed by the data-model work.
-
-## Acceptance Criteria
-
-- `npm run build` passes.
-- `npm run typecheck` passes.
-- `npm run lint` passes.
-- `npm run format:check` passes.
-- `npm test` passes.
-- E02 parser, validator, reader, and transition test coverage matches the epic Design close criteria.
-
-## Implementation Plan
-
-- [x] Run `npm run build` and fix any compile or packaging failures introduced by E02.
-- [x] Run `npm run typecheck` and fix strict TypeScript issues without weakening domain types.
-- [x] Run `npm run lint` and fix lint findings without broad refactors.
-- [x] Run `npm run format:check` and apply formatting only where needed.
-- [x] Run `npm test` and add or adjust focused tests until E02 close-criteria coverage is represented.

package/.savepoint/releases/v1/epics/_archived/E02-domain-phase-model/Design.md

@@ -1,40 +0,0 @@
----
- type: epic-design
- status: planned
- ---
-
- # Epic E02: Domain Phase Model
-
- ## Purpose
-
- Extend the domain layer to support the build/test/audit phase model within the `in_progress` status. Simplify the config model to theme-only and collapse the router state machine from 6 to 3 states.
-
- ## What this epic adds
-
- - `TaskPhase` type with constants and transition rules.
- - Phase validation in task frontmatter parsing.
- - Phase-to-accent color mapping for TUI rendering.
- - Simplified config model (theme-only, no quality gates or audit config).
- - Collapsed router domain (3 states: planning, building, reviewing).
-
- ## Definition of Done
-
- - `status.ts` defines `TaskPhase`, phase transitions, and `PHASE_ACCENTS`.
- - `task.ts` validates `phase?: TaskPhase` in frontmatter.
- - `config.ts` contains only `ThemeConfig` and `SavepointConfig` (no quality_gates, audit, verify_strict).
- - `router.ts` defines 3 states (`planning`, `building`, `reviewing`).
- - All existing domain tests compile and pass (or are updated).
- - No references to old 6-state model remain in domain code.
-
- ## Components and files
-
- | Path | Purpose |
- |------|---------|
- | `src/domain/status.ts` | TaskPhase type, phase transitions, accent mapping |
- | `src/domain/task.ts` | Phase frontmatter field and validation |
- | `src/domain/config.ts` | Simplified theme-only config model |
- | `src/domain/router.ts` | 3-state router domain |
- | `test/domain/status.test.ts` | Phase transition tests |
- | `test/domain/task.test.ts` | Phase frontmatter validation tests |
- | `test/domain/config.test.ts` | Simplified config tests |
- | `test/domain/router.test.ts` | 3-state router tests |

package/.savepoint/releases/v1/epics/_archived/E02-domain-phase-model/tasks/T001-phase-types.md

@@ -1,27 +0,0 @@
----
-id: E02-domain-phase-model/T001-phase-types
-status: planned
-objective: "Add TaskPhase type, constants, transitions, and accent color mapping to status.ts"
-depends_on: []
----
-
-# T001: Phase Types
-
-## Acceptance Criteria
-
-- `status.ts` exports `TaskPhase` type (`build | test | audit`).
-- Phase order constant exists: `['build', 'test', 'audit']`.
-- `getNextPhase(current)` and `getPreviousPhase(current)` functions exist.
-- `PHASE_ACCENTS` maps each phase to a hex color string.
-- Phase transition validation: `isPhaseTransitionAllowed(from, to)` returns boolean.
-- All phase functions have unit tests.
-
-## Implementation Plan
-
-- [ ] Read existing `status.ts` to understand current structure.
-- [ ] Add `TaskPhase` type and `TASK_PHASES` constant array.
-- [ ] Add `getNextPhase` and `getPreviousPhase` helpers.
-- [ ] Add `PHASE_ACCENTS` mapping.
-- [ ] Add `isPhaseTransitionAllowed` with no-skipping rule.
-- [ ] Write/update `test/domain/status.test.ts` with phase tests.
-- [ ] Run `npm test` and verify phase tests pass.

package/.savepoint/releases/v1/epics/_archived/E02-domain-phase-model/tasks/T002-phase-frontmatter.md

@@ -1,25 +0,0 @@
----
-id: E02-domain-phase-model/T002-phase-frontmatter
-status: planned
-objective: "Add phase field to TaskFrontmatter and update validation in task.ts"
-depends_on: [E02-domain-phase-model/T001-phase-types]
----
-
-# T002: Phase Frontmatter
-
-## Acceptance Criteria
-
-- `TaskFrontmatter` interface includes optional `phase?: TaskPhase`.
-- `validateTaskFrontmatter` accepts and validates `phase` as optional string.
-- Invalid phase values are rejected with clear error messages.
-- `phase` is absent when `status` is not `in_progress`.
-- All task validation tests pass.
-
-## Implementation Plan
-
-- [ ] Read existing `task.ts` and `test/domain/task.test.ts`.
-- [ ] Add `phase?: TaskPhase` to `TaskFrontmatter` interface.
-- [ ] Update `validateTaskFrontmatter` to parse optional `phase` field.
-- [ ] Validate that phase is one of `build`, `test`, `audit` if present.
-- [ ] Update `test/domain/task.test.ts` with phase validation cases.
-- [ ] Run `npm test` and verify.

package/.savepoint/releases/v1/epics/_archived/E02-domain-phase-model/tasks/T003-simplify-config.md

@@ -1,26 +0,0 @@
----
-id: E02-domain-phase-model/T003-simplify-config
-status: planned
-objective: "Remove quality_gates, audit, verify_strict from config model; keep theme only"
-depends_on: []
----
-
-# T003: Simplify Config
-
-## Acceptance Criteria
-
-- `config.ts` contains only `ThemeConfig` and a minimal `SavepointConfig` wrapper.
-- `CONFIG_DEFAULTS` has no `quality_gates`, `audit`, or `verify_strict` fields.
-- `applyConfigDefaults` only processes theme keys.
-- `readers/config.ts` still reads and returns a valid config (theme defaults if missing).
-- All config tests pass.
-
-## Implementation Plan
-
-- [ ] Read existing `config.ts` and `test/domain/config.test.ts`.
-- [ ] Remove `QualityGates`, `AuditConfig` interfaces.
-- [ ] Remove `quality_gates`, `audit`, `verify_strict` from `SavepointConfig`.
-- [ ] Update `CONFIG_DEFAULTS` to theme-only.
-- [ ] Simplify `applyConfigDefaults` to only handle theme fields.
-- [ ] Update `test/domain/config.test.ts`.
-- [ ] Run `npm test`.

package/.savepoint/releases/v1/epics/_archived/E02-domain-phase-model/tasks/T004-simplify-router-domain.md

@@ -1,24 +0,0 @@
----
-id: E02-domain-phase-model/T004-simplify-router-domain
-status: planned
-objective: "Collapse router states from 6 to 3 in router.ts"
-depends_on: []
----
-
-# T004: Simplify Router Domain
-
-## Acceptance Criteria
-
-- `router.ts` defines 3 states: `planning`, `building`, `reviewing`.
-- `isRouterStateValue` validates only the 3 states.
-- `validateRouterState` accepts the 3-state model.
-- `RouterState` interface unchanged (still has `state`, `release`, `epic`, `task`, `next_action`).
-- All router tests pass.
-
-## Implementation Plan
-
-- [ ] Read existing `router.ts` and `test/domain/router.test.ts`.
-- [ ] Replace `ROUTER_STATES` array with 3 states.
-- [ ] Update `isRouterStateValue` and `validateRouterState`.
-- [ ] Update `test/domain/router.test.ts` with 3-state cases.
-- [ ] Run `npm test`.

package/.savepoint/releases/v1/epics/_archived/E03-cli-foundation/Design.md

@@ -1,122 +0,0 @@
----
-type: epic-design
-status: audited
----
-
-# Epic E03: cli-foundation
-
-## Context Budget
-
-For implementation tasks in this epic, read only:
-
-- `.savepoint/router.md`
-- this epic `Design.md`
-- the active task file
-- directly touched source/test files
-
-Read `.savepoint/Design.md` only if the task changes architecture. Read `.savepoint/releases/v1/PRD.md`, prior epic docs, audit proposals, or `.savepoint/visual-identity.md` only when the active task explicitly requires them.
-
-For E03 specifically, do not preload E02 source files, E02 audit proposals, `.savepoint/PRD.md`, or `.savepoint/releases/v1/PRD.md` during implementation. The CLI foundation should use the command contract in this file and the active task as its source of truth.
-
-## Purpose
-
-Introduce the real `savepoint` command shell: argument parsing, command dispatch, help/version output, exit codes, and terminal capability detection. This epic wires a command framework around stub command handlers so later epics can fill behavior without changing the CLI contract.
-
-## What this epic adds
-
-- Command dispatch for `init`, `board`, `audit`, and `doctor`.
-- Top-level `--help` and `--version`.
-- Command-level help text.
-- Unknown command and unknown flag handling.
-- Exit code conventions.
-- TTY and color capability detection helpers.
-- A testable CLI runner separated from process globals.
-
-## Implementation strategy
-
-- Use a small local parser instead of a CLI framework unless implementation proves it would reduce code.
-- Treat the allowed commands as a closed set: `init`, `board`, `audit`, `doctor`.
-- Treat allowed global flags as a closed set: `--help`, `-h`, `--version`, `-v`.
-- Keep command stubs shallow. They should return deterministic "not implemented yet" results and exit codes without reading or writing project files.
-- Keep process globals in `src/cli.ts`; tests should exercise `runCli()` with injected argv, streams, and environment.
-
-## Components and files
-
-Expected files introduced or extended by this epic:
-
-| Path                     | Purpose                                             |
-| ------------------------ | --------------------------------------------------- |
-| `src/cli.ts`             | Process entrypoint that invokes the CLI runner.     |
-| `src/cli/run.ts`         | Testable command runner.                            |
-| `src/cli/args.ts`        | Argument parsing and normalization.                 |
-| `src/cli/help.ts`        | Help text generation.                               |
-| `src/cli/exit-codes.ts`  | Shared exit code constants.                         |
-| `src/cli/environment.ts` | TTY, color, and platform detection.                 |
-| `src/commands/*.ts`      | Stub command modules for the fixed command surface. |
-| `test/cli/**/*.test.ts`  | CLI parser and dispatch tests.                      |
-
-## Architectural delta
-
-Before this epic, the binary is a placeholder. After this epic, `savepoint` has a stable command boundary with stubbed behaviors behind it.
-
-The command layer should not introduce data-model behavior. Commands that need project data stay as deterministic stubs until a later epic owns the data model.
-
-## Implemented As
-
-- `src/cli.ts` now isolates process globals and delegates to `runCli()`.
-- `src/cli/args.ts` implements the closed parser contract for bare invocation, global help/version flags, known commands, unknown top-level commands, and unknown top-level flags.
-- `src/cli/run.ts` wires parser output to help, version output, command-level help, command stubs, and usage errors.
-- `src/cli/help.ts` provides deterministic top-level and command-level help text.
-- `src/cli/environment.ts` provides injectable TTY, color, and platform detection.
-- `src/cli/exit-codes.ts` centralizes success, usage-error, and not-implemented exit codes.
-- `src/commands/init.ts`, `src/commands/board.ts`, `src/commands/audit.ts`, and `src/commands/doctor.ts` return deterministic not-yet-implemented results with no project filesystem side effects.
-- `src/commands/result.ts` was added as the shared command-result type used by the command stubs.
-- Focused tests were added under `test/cli/` for parsing, help text, terminal environment detection, command stubs, and runner dispatch.
-- The audit snapshot was generated manually because `savepoint audit` is still a stub.
-- During audit closeout, command-level unknown flags were fixed to return a usage error instead of dispatching command stubs.
-- The audit workflow was updated for future epics to prefer a single delta-shaped proposal bundle over four separate proposal files.
-
-Design delta notes:
-
-- The planned `src/commands/*.ts` component was implemented as one module per command plus a small shared `result.ts`.
-- The epic design table originally described command modules as the "five-command surface"; the implemented command surface has four commands plus top-level global help/version flags, matching the rest of the design.
-- Command behavior remains stubbed by design. Later epics own real `init`, `board`, `audit`, and `doctor` behavior.
-
-## Boundaries
-
-In scope:
-
-- Preserve the exact v1 CLI surface from the project Design.
-- Make bare `savepoint` print help.
-- Make command stubs return clear "not implemented yet" output where necessary.
-- Keep command functions testable without spawning Node processes.
-
-Out of scope:
-
-- Implementing `init`, `board`, `audit`, or `doctor` behavior.
-- Adding extra commands such as `task new`, `plan`, or `status`.
-- TUI rendering.
-- Project file writes.
-
-## Quality gates
-
-- Tests must cover bare invocation, help, version, unknown commands, unknown flags, and each command dispatch path.
-- CLI behavior should be deterministic with injected `argv`, `stdin`, `stdout`, `stderr`, and environment data.
-- Every branch in argument parsing and command dispatch must have a focused test.
-- During individual implementation tasks, run the focused `test/cli/**/*.test.ts` files for touched behavior first. Run the full gate suite at task closeout when practical, and always in the final E03 quality-gates task.
-
-## Design constraints
-
-- Keep process I/O at the entrypoint boundary.
-- Avoid a heavy CLI framework unless it materially reduces complexity.
-- Command names are fixed: `init`, `board`, `audit`, `doctor`.
-
-## Close Criteria
-
-- All `E03-cli-foundation` tasks are `done`.
-- `npm run build`, `npm run typecheck`, `npm run lint`, `npm run format:check`, and `npm test` pass.
-- CLI branch tests cover bare invocation, help, version, unknown commands, unknown flags, and each command dispatch path.
-- Audit snapshot exists at `.savepoint/audit/E03-cli-foundation/snapshot.md`.
-- Audit proposals are accepted, rejected, or explicitly carried forward.
-- This epic `Design.md` has `status: audited`.
-- Router points to the next epic state.

package/.savepoint/releases/v1/epics/_archived/E03-cli-foundation/tasks/T001-argument-parser-contract.md

@@ -1,28 +0,0 @@
----
-id: E03-cli-foundation/T001-argument-parser-contract
-status: done
-objective: "Define the closed CLI argument parser and exit-code contract for the v1 command surface."
-depends_on: []
----
-
-# T001: Argument Parser Contract
-
-## Scope
-
-Create the argument parsing foundation for `savepoint` without wiring command behavior yet. This task owns the closed set of global flags, command names, parser result shapes, and shared exit-code constants.
-
-## Implementation Plan
-
-- [x] Read `.savepoint/router.md`, this epic `Design.md`, this task file, and the directly touched CLI/test files.
-- [x] Add `src/cli/exit-codes.ts` with named exit-code constants for success, usage errors, and not-yet-implemented command stubs.
-- [x] Add `src/cli/args.ts` with typed parser results for bare invocation, global help/version flags, command invocation, unknown commands, and unknown flags.
-- [x] Keep allowed commands closed to `init`, `board`, `audit`, and `doctor`.
-- [x] Treat `--help`, `-h`, `--version`, and `-v` as the only allowed global flags.
-- [x] Add focused parser tests covering bare invocation, each global flag alias, each known command, unknown command, and unknown flag branches.
-- [x] Run the focused parser test file.
-
-## Acceptance Criteria
-
-- The parser is deterministic from an injected `argv` array.
-- Unknown commands and unknown flags are represented as typed parser results, not thrown exceptions.
-- Every parser branch introduced by this task has a focused test.