§1 — Why the index is a monolith

docs/state/reckon/index.json currently combines the active-sprint pointer, every sprint definition and item, milestones, timeline, blockers, project rollups, and one shared version counter. It is necessary today because those fields have no other canonical store, but it creates large MCP payloads and makes unrelated edits contend on the same optimistic-concurrency version.

The replacement must decompose state before deleting the index. Separate sprint files are the central change, accompanied by explicit homes for milestones, blockers, timeline events, and minimal project configuration. Plan lifecycle state remains in plan HTML.

A monolithic index split into separately versioned sprint files, milestone files, blockers, timeline, and a small project manifest.
Decomposition reduces payload size and edit contention while preserving a discoverable project view.

✓ landed 2026-07-29 §2 — Target resource model

Added independently versioned sprint, milestone, blocker, timeline, and identity-only project resources. This checkout migrated to seven resources while retaining the source index byte-for-byte; strict marker gating and rollback hardening landed in 40e6cd6, followed by legacy-precedence and activation-race closure in a837fc7. Full verified record.

✓ landed 2026-07-29 §3 — MCP and concurrency

Kept the three-tool MCP surface while adding symmetric typed reads/writes, composed compatibility reads, single-winner activation, and durable contained recovery journals. Forty-one project-state regressions are included in the 1,349-test passing full suite; targeted multiprocessing and executable SPA scenarios also pass. Evidence.

✓ landed 2026-07-29 §4 — Safe migration

Implemented snapshot → stage → validate → parity → source recheck → install → marker-last activation, with destination snapshots and full rollback on any pre-activation failure. Source and snapshot SHA-256 are f6aa91f66811…; parity SHA-256 is 11edeeebb748…. Static builds write a derived projection and live clients fail closed. Migration record.

§5 — Done-when

  1. Sprints are independently stored, versioned, discoverable, and editable.
  2. Milestones, blockers, timeline, and minimal project configuration have explicit non-monolithic stores.
  3. Project discovery composes a clear live view without persisting rollups.
  4. An idempotent migration proves state parity and preserves rollback evidence.
  5. Concurrent edits to different resources do not conflict; conflicting edits to one resource still return 412.
  6. The old index is retired only after fleet migration and audit pass.

§ Decisions

What format should each sprint resource use?

Semantic HTML keeps sprint state inspectable, versioned, and consistent with Reckon's HTML-first storage and existing document tooling.

How should the active sprint be selected?

Deriving the unique active sprint removes duplicated mutable state; audit enforces that at most one sprint is active.

What mutable state, if any, may remain in the project manifest?

The project manifest retains mount identity and presentation settings only; mutable sprint contents and computed rollups live in independently versioned resources.

§ Followups

Split project state into independently versioned resources

Design the resource grammar, lock storage decisions, and migrate the current index only after composed-state parity is proven.

Project: reckon
Plan:    distributed-sprint-state (http://localhost:8765/reckon/distributed-sprint-state.html)
Section: full plan
Tier:    opus

Context
  The project index is required today but combines unrelated mutable resources.
  Replace it safely with separate sprint and project-state files.

State to read
  docs/state/reckon/index.json, reckon/_schema.py, reckon/mcp.py
  reckon/_store.py, reckon/serve.py, skills/reckon-sprint/

Scope locks / constraints
  Do not delete the current index until migration parity and rollback are proven.

Done-when
  1. decomposed storage, migration and composed discovery land with concurrency tests
  2. tests still green
  3. followup written into plan + this followup marked resolved

Distributed storage landed in 44c39cc, independent review corrections landed in 40e6cd6, and final race/precedence corrections landed in a837fc7. Seven canary resources retain byte-identical source/snapshot f6aa91f66811… and parity 11edeeebb748…. The 41 project-state regressions are included in a 1,349-test passing full suite; targeted multiprocessing and executable SPA scenarios also pass. Marker-gated reads/writes, strict legacy index precedence, single-winner activation, fail-closed HTTP/MCP/SPA behavior, migration rollback, durable contained journals, strict references, and append-only history are verified. done — no followup here; downstream closure is already tracked by reckon-ci-build and mcp-readable-responses.