---
digest: >
  v0.31.6 makes Refinement shared project knowledge instead of journey-local
  database state. When a repository declares `docs/project/refinement/index.md`,
  that ordinary Markdown file becomes the sole authority for RS/CR focus,
  ordering, and status; linked documents preserve narrative and evidence, and
  Git supplies history, collaboration, conflict handling, and recovery. Builder
  surfaces and Pi/Gemini/Codex guidance now follow that authority without
  inspecting stale SQLite Workbench rows, while projects without the index keep
  the existing compatibility path. The release deliberately rejects automatic
  migration, dual-write, projection, and custom handoff machinery after
  archiving an earlier overbuilt implementation experiment.
---

# v0.31.6 — Document-First Refinement Authority

**Date:** 2026-08-03

## Highlights

- Adds `docs/project/refinement/index.md` as the canonical shared Refinement
  surface, with stable project-wide `RSNNN` and `CRNNN` identity, explicit
  ordering and focus, and ordinary linked Markdown documents for context,
  plans, evidence, and outcomes.
- Routes Builder Home, Orientation, Resume, and natural-language Refinement work
  to project files when the canonical index exists. The file-first runtime path
  does not request or display a legacy Workbench snapshot.
- Preserves the existing SQLite Workbench for projects without the canonical
  index. Migrations `015_create_builder_workbench` and
  `016_builder_workbench_display_codes` remain supported, with no implicit
  row inspection, migration, reconciliation, deletion, or dual-write.
- Defines a repair-and-report interaction rule: during already-authorized
  mutable work, Builder repairs deterministic, local, meaning-preserving
  document defects and reports them afterward; read-only requests remain
  read-only, and semantic choices stay with the Navigator.
- Records why the first DS12 implementation was abandoned. Its filesystem
  projection, mutation recovery, Git-coherence, and cross-clone handoff
  machinery remains available only in a verified private archive, not in the
  production architecture.
- Validated with 2,399 local unit/integration tests, green Python 3.10/3.12 and
  TypeScript CI, and an isolated staging smoke containing deliberately stale
  SQLite RS/CR canaries. Builder reported only the canonical file-authored
  RS001/CR001 and performed no mutation.

## Where We Started

The original Builder Workbench made Refinement a first-class work field, but it
stored shared meaning in a local SQLite database tied to one journey. That was
useful for one runtime session and weak as a project artifact: another clone or
collaborator could not recover the backlog by reading the repository.

DS12 initially answered that portability problem with a distributed protocol:
canonical filesystem artifacts projected into SQLite, mutation journals,
recovery paths, Git topology checks, remote evidence, and cross-clone handoff.
The implementation became technically coherent while drifting far beyond the
actual need. The work was archived before merge and the design was reset around
a smaller question: what is the least machinery required for Refinement to be
shared, inspectable, and durable?

## What Changed

The repository now carries a real document-first Workbench under
`docs/project/refinement/`. One root index owns the facts that must have exactly
one answer: current Refinement Story, current Change Request, backlog order, and
status. RS and CR documents intentionally do not compete for those fields; they
own the richer problem framing, plans, evidence, and outcomes. Stable IDs belong
to the project, not to a journey, database, user, or absolute filesystem path.

The contract was dogfooded before runtime routing changed. The project selected
RS001 and planned CR001 using files alone, proving that a fresh agent could
recover position without SQLite or conversation history. That dogfood also
captured CR004, a real Ariad defect where Plan materialization overwrites an
authored story index, without expanding DS12 to fix it opportunistically.

The legacy boundary is explicit. SQLite rows remain compatibility-only local
state. Their journey-scoped UUIDs, local display codes, different status
vocabulary, and compressed narrative do not form a deterministic lossless map
to project artifacts. Any future export must therefore be requested, previewed,
destination-bound, and confirmed; schema removal requires separate coordinated
Python/TypeScript version work.

Builder now enforces the authority choice by one explicit path check. If
`docs/project/refinement/index.md` exists, entry surfaces identify project files
and point to the relative index without loading the Workbench snapshot. The
skill reads the canonical documents for inspection and mutation. If the path is
absent, existing SQLite behavior remains available. An unreadable or ambiguous
canonical document never causes a silent fallback to local state.

The resulting architecture is intentionally ordinary: Markdown owns meaning,
Git owns history and collaboration, and the agent owns file reading and bounded
editing. No parser, watcher, projection, manifest, recovery journal, or custom
Git protocol was added.

## Conscious Exclusions

- **No automatic legacy migration.** Existing personal Workbench rows are not
  read, mapped, exported, reconciled, frozen, or deleted by this release.
- **No dual authority.** SQLite is not a cache or projection of the canonical
  documents, and file-first projects do not write both stores.
- **No Markdown runtime.** Python detects the explicit index path but does not
  parse RS/CR status into another cursor or persistence model.
- **Claude Builder skill parity remains separate.** Pi is the authored skill
  surface and Gemini CLI/Codex consume its shared `.agents` symlinks. Claude's
  independently tuned `mm-build` skill retains the previously documented
  Refinement parity gap; its generated plugin remains internally consistent.
- **Captured runtime findings remain separate work.** CR001, CR002, and CR004
  stay in the canonical Refinement backlog rather than being absorbed into the
  release.
- **No release authorization from project documents.** Refinement purpose,
  status, plans, or readiness never authorize commit, push, merge, publication,
  or release.

## What We Learned

The first implementation was not wrong because its pieces were careless. It was
wrong-sized because each possible failure mode became another protocol before
the basic document workflow had been proven. Archiving that work made the
learning durable without forcing its maintenance cost onto the product.

A shared artifact does not need a synchronization system when Git already owns
sharing and history. It needs a clear authority boundary, stable names, ordinary
links, and an agent that knows where to look. The smaller model also makes
failures easier to explain: repair a safe structural defect, ask when meaning is
ambiguous, and never hide uncertainty behind a fallback database.

## Next Horizon

The canonical backlog can now generate evidence through normal use. CR001 and
CR004 are the immediate visible runtime findings, but neither is promised by
this release. Lightweight structural automation, legacy export, and eventual
schema retirement remain conditional on repeated operational pain rather than
architectural anticipation.
