mirror-mind 0.0.1 → 0.33.0

package/docs/releases/v0.31.3.md

@@ -0,0 +1,142 @@
+---
+digest: >
+  v0.31.3 is a maintenance patch that makes the Ariad Delivery Story plan
+  lifecycle's artifacts trustworthy. The `ARTIFACTS_MATERIALIZED` surface claimed
+  an `index.md` update and a `test-guide.md` creation that `plan-delivery-story`
+  never wrote (AF-002, AF-006), and the DS `plan.md` was both thinner than the
+  method's own `plan_contract` and regenerated on approval, silently overwriting
+  authored planning work (AF-003). The release drives the surface from the
+  writer's real result, materializes the full package without clobbering
+  authored content, scaffolds every `plan_contract` section, and — after a
+  six-lens technical review chose pure-preserve over a surgical status patcher —
+  removes mutable status from the document so approval preserves the authored
+  plan instead of rewriting it. Approval now also flags any contract section left
+  unfilled. The recurring decision: never duplicate state that already has a
+  source of truth, and let a test guard any place two artifacts must agree.
+---
+
+# v0.31.3 — Ariad DS-Plan Artifact Integrity
+
+**Date:** 2026-07-22
+
+## Highlights
+
+- Fixes phantom `ARTIFACTS_MATERIALIZED` rows: `plan-delivery-story` and
+  `approve-delivery-story-plan` reported an `index.md` update and a
+  `test-guide.md` creation that never touched disk (AF-002, AF-006). The surface
+  is now built from the writer's real return manifest, so every reported path
+  exists with a truthful `created`/`existing` label.
+- Materializes the full Delivery Story package: `plan.md` is upserted, while
+  `index.md` and `test-guide.md` are scaffolded only when absent, so
+  hand-authored or Expand-generated content is never overwritten.
+- Scaffolds every `plan_contract` required output in `plan.md` — Scope,
+  Non-Goals, Acceptance Behavior, Validation Route, and Implementation Contract —
+  guarded by a contract-drift test so the template and the method's declared
+  contract cannot silently diverge (AF-003).
+- Makes the authored plan durable: mutable status (`Status`, Approval Gate,
+  Boundary) was removed from the `plan.md` template, and
+  `approve-delivery-story-plan` now preserves the document instead of
+  regenerating it. Approval state lives only in the Builder delivery cursor and
+  the `DELIVERY_STORY_PLAN_CHECKPOINT` surface.
+- Adds a non-blocking completeness advisory: approval lists any contract section
+  still carrying its scaffold `Pending` placeholder under "Sections still
+  pending".
+- Records conscious exclusions: approval warns rather than hard-blocks on
+  unfilled sections, and the artifact-path code-segment sanitization (D-012)
+  remains open.
+
+## Where We Started
+
+A separate Builder session planning Delivery Story DS-37 noticed that the
+DS-plan lifecycle's `ARTIFACTS_MATERIALIZED` surface listed three artifacts —
+`index.md`, `plan.md`, `test-guide.md` — while only `plan.md` ever reached disk.
+On every `plan-delivery-story` and `approve-delivery-story-plan` call the surface
+claimed a `test-guide.md` that did not exist and an `index.md` "update" that
+never happened. Deterministic Ariad surfaces exist precisely so the Navigator can
+trust them instead of inferring state from prose, and the surface is also
+rendered verbatim into the agent's own context on resume — so a phantom artifact
+does not merely mislead a human, it poisons the model's ground truth. These
+became AF-002 and AF-006 in the Ariad dogfooding ledger.
+
+The same ledger carried AF-003: the generated `plan.md` held only metadata, an
+objective, and a child list — none of the `plan_contract` outputs the method
+itself declares. Every Delivery Story plan was born structurally incomplete
+relative to the runtime's own contract.
+
+## What Changed
+
+The surface bug was fixed first, and its root cause set the theme for the whole
+release: two sources of truth. The writer wrote files; the reporter independently
+re-derived what it *assumed* had been written. Any time two code paths compute
+the same fact separately, they drift. The fix made the writer return exactly what
+it did and had the surface render that manifest — collapsing the entire
+surface-not-equal-disk class for DS-plan. Materialization also became
+no-clobber: `index.md` and `test-guide.md` are scaffolded only when absent, and a
+preserved file is reported with the established `existing` status rather than a
+false "updated".
+
+AF-003 then unfolded in three moves, each pulled and reviewed in turn. First, the
+`plan.md` template gained a scaffolded section for every `plan_contract` output,
+with a contract-drift test that reads the live method definition and fails if the
+template ever falls behind. Grounding that change surfaced a design fork the
+handoff had not: because `approve-delivery-story-plan` regenerated `plan.md` from
+the report, anything a driver authored into those new sections would be clobbered
+on approval — the same failure class as the phantom artifacts, one file over.
+
+That fork went to a six-lens technical review — quality-assurance drafting, then
+engineer, database-architect, devops-engineer, ai-engineer, prompt-engineer, and
+security-engineer. The review converged, against the original surgical-patch
+lean, on **pure-preserve**: rather than teach approval to rewrite the document
+carefully, stop duplicating mutable state into it at all. Mutable status was
+removed from the `plan.md` template — the delivery cursor and the checkpoint
+surface already own approval state — and approval now preserves the file. The
+authored plan survives byte-for-byte, with no markdown parser, no anchor-collision
+seam, and no new failure surface. A final increment made approval list any
+section still left as a `Pending` placeholder, so an incomplete plan cannot pass
+approval unnoticed, while leaving the Navigator free to approve a deliberately
+thin plan.
+
+Throughout, the section definitions were consolidated into a single source used
+by both the renderer and the completeness detector, so they cannot drift — the
+same principle that fixed the original surface bug, applied to the document
+itself.
+
+## Conscious Exclusions
+
+- **Warn, not block.** Approval surfaces unfilled sections but does not refuse
+  approval. Ariad checkpoints inform; the Navigator retains authority to approve
+  a plan with legitimately thin sections. A hard-block or soft-block mode is left
+  as a future increment.
+- **No content-diff on `updated`.** `plan.md` is labeled `updated` by prior
+  existence rather than a byte-level diff. It is genuinely rewritten on
+  `plan-delivery-story`, so the label is truthful; reporting `unchanged` on a
+  byte-identical rewrite across every lifecycle artifact remains a separate
+  enhancement.
+- **D-012 — code-segment path sanitization.** The artifact directory is derived
+  from the work-item code, which is still only lower-cased and dot-split rather
+  than run through `kebab_slug`. This release only adds fixed filenames inside an
+  already-used directory, so it widens no path surface; the latent seam carried
+  from v0.31.2 stays recorded, not fixed here.
+
+## What We Learned
+
+The same lesson arrived three times in one release. A surface that re-derives what
+a writer did, a document that carries a copy of cursor state, and a detector that
+hardcodes the renderer's text are all the same shape: a second copy of a fact that
+already has an owner, free to drift. Each was fixed not by smarter
+synchronization but by removing the duplication — the writer returns its own
+result, the document stops carrying status, the sections live in one table. Where
+two artifacts genuinely must agree, a test that reads the source of truth turned
+out cheaper than vigilance. The review also earned its keep: it inverted the
+release's central decision, replacing a status patcher that would have added a
+parser with a deletion that removed the problem entirely.
+
+## Next Horizon
+
+The Delivery Story plan lifecycle is now trustworthy end to end: it materializes
+truthfully, scaffolds completely, preserves authored work, and flags
+incompleteness. Visible from here are the follow-ups this release consciously
+deferred — an optional validating or blocking mode for plan completeness, the
+content-diff refinement that would let every artifact report `unchanged`, and the
+D-012 code-segment sanitization the next time artifact-path derivation is
+touched.

package/docs/releases/v0.31.4.md

@@ -0,0 +1,117 @@
+---
+digest: >
+  v0.31.4 is a maintenance patch that stops Ariad's Builder from materializing
+  a phantom, parallel story-package tree when expanding a Delivery Story.
+  `_artifact_directory` derived roadmap folder slugs from the item code plus
+  title, but real roadmaps use hand-authored CV/DS slugs
+  (`cv3-build-de-producao`) that no title derivation can reproduce — so pulling
+  and expanding CV3.DS22 wrote a boilerplate `cv3-manage-100-funcional/cv3-ds22/`
+  tree instead of expanding the real node at
+  `cv3-build-de-producao/cv3-ds22-manage-100-funcional/`. The fix makes Expand
+  resolve the existing on-disk folder first — scanning `docs/project/roadmap`
+  for the `index.md` whose `# CODE — Title` heading matches the item code, the
+  same scan-and-skip-legacy path the pull inspector already uses — and only
+  falls back to title derivation for genuinely new items. A regression test
+  pins the nested case, and the fix was validated against the live kia-desktop
+  roadmap.
+---
+
+# v0.31.4 — Roadmap-Aligned Story Expansion
+
+**Date:** 2026-07-22
+
+## Highlights
+
+- Fixes Expand materializing a *parallel* story-package tree at a
+  title-derived path instead of expanding the real Delivery Story: for CV3.DS22
+  the runtime wrote `docs/project/roadmap/cv3-manage-100-funcional/cv3-ds22/`
+  with a boilerplate US1 while the real node lived at
+  `docs/project/roadmap/cv3-build-de-producao/cv3-ds22-manage-100-funcional/`.
+- Root cause: `_artifact_directory` derived folder slugs from code plus title,
+  but hand-authored roadmaps use CV/DS slugs (`cv3-build-de-producao`) that no
+  title derivation can reproduce.
+- Expand now resolves the existing folder by heading code via a new
+  `_resolve_existing_item_directory` — scanning `docs/project/roadmap` for the
+  `index.md` whose `# CODE — Title` heading matches the item code (the same
+  scan plus legacy-path skip the pull inspector uses) — and only falls back to
+  title derivation for genuinely new items not yet on disk.
+- Aligns Expand with pull inspection, which already resolved true on-disk
+  paths; the writer and the inspector had silently diverged.
+- Ships test-first: a nested-folder regression (child lands under the real
+  `cv3-build-de-producao/cv3-ds22-*` dir, no stray `cv3-manage-100-funcional`
+  tree) fails before and passes after. Validated against the live kia-desktop
+  roadmap (CV3, CV3.DS18, CV3.DS22, CV3.DS18.TS2 all resolve to their true
+  folders).
+
+## Where We Started
+
+A Builder session pulling a Delivery Story and expanding it produced two
+roadmap trees where there should have been one. Pulling CV3.DS22 ("Manage 100%
+funcional") and expanding it wrote a fresh `cv3-manage-100-funcional/cv3-ds22/`
+folder containing a boilerplate US1, while the real, hand-authored Delivery
+Story sat untouched at `cv3-build-de-producao/cv3-ds22-manage-100-funcional/`.
+The runtime had quietly forked the roadmap: the authored node and a synthetic
+sibling now coexisted, and the expansion landed in the wrong one.
+
+The cause was a divergence between two code paths that should agree. Pull
+inspection already resolves the true on-disk location by scanning `index.md`
+headings, so it found the real folder. Expand did not — `_artifact_directory`
+rebuilt a path from the item code plus a title-derived slug. Real roadmaps use
+hand-chosen CV/DS slugs (`cv3-build-de-producao`) that no title derivation can
+reproduce, so the derived path never matched the authored one, and Expand
+created a parallel tree instead.
+
+## What Changed
+
+`_artifact_directory` now resolves the existing folder before deriving
+anything. A new `_resolve_existing_item_directory` scans `docs/project/roadmap`
+for the `index.md` whose `# CODE — Title` heading matches the item's code
+(case-insensitive), reusing the same traversal and legacy-path skip the pull
+inspector already relies on. When it finds the authored folder, Expand
+materializes children there. Only for a genuinely new item — one not yet on
+disk — does it fall back to the previous code-plus-title-slug derivation. That
+preserves the ability to scaffold new nodes while keeping existing ones aligned
+with the hand-authored tree.
+
+The change is small and surgical: 36 lines in `builder/lifecycle.py`, reusing
+`HEADING_RE` and `is_legacy_path` from `roadmap_grammar` rather than
+introducing a second heading parser. It shipped test-first. A new regression
+builds the real nested structure
+(`cv3-build-de-producao/cv3-ds22-manage-100-funcional/`), expands the Delivery
+Story, and asserts the child lands under the real directory by its real code,
+that no stray `cv3-manage-100-funcional` tree appears, and that every
+materialized path stays under the resolved directory. The test fails before the
+fix and passes after; the full builder unit suite is green and ruff is clean.
+The fix was also validated against the live kia-desktop roadmap, where CV3,
+CV3.DS18, CV3.DS22, and CV3.DS18.TS2 all resolve to their true folders.
+
+## Conscious Exclusions
+
+- **Heading resolution, not tree cleanup.** The fix resolves the *existing*
+  folder by heading code; it does not retroactively rename or migrate a
+  parallel tree that a prior buggy expand already wrote. Any phantom
+  `cv3-manage-100-funcional/` folder from before the fix must still be removed
+  by hand.
+- **No change to new-item derivation.** Genuinely new items still derive their
+  folder from code plus title slug. Title derivation still cannot reproduce a
+  hand-authored slug for a node that does not yet exist on disk — by design,
+  since there is nothing on disk to resolve against.
+
+## What We Learned
+
+Two code paths that answer the same question — "where does this roadmap item
+live?" — must share one resolver, or they drift. Pull inspection had the correct
+answer (scan headings) while Expand carried a plausible-but-wrong shortcut
+(derive from title). The bug was not in either derivation in isolation; it was
+in letting a writer and an inspector disagree about identity. Reusing the
+inspector's scan for the writer closed the gap by construction rather than by
+teaching the derivation to guess better.
+
+## Next Horizon
+
+The remaining title-derivation path is now confined to genuinely new items. The
+visible follow-up, the next time this area is touched, is whether new-item
+creation should let authors pin a folder slug explicitly rather than derive
+one — the same authored-slug reality that caused this bug appears whenever a new
+node's human slug matters. Cleaning up any phantom trees written by the old
+behavior is a separate, manual housekeeping task.

package/docs/releases/v0.31.5.md

@@ -0,0 +1,155 @@
+---
+digest: >
+  v0.31.4 fixed Ariad Expand materializing a phantom, title-derived roadmap
+  folder instead of the real, hand-authored one — but only for Expand, and
+  only for the case where a package already exists. v0.31.5 closes the class:
+  one shared resolver (`story_paths.py`) now backs both Expand and the CLI's
+  Plan/checkpoint lookups, silent ambiguity and silent fabrication both become
+  a rendered `EXPAND_BLOCKED` refusal, a new CI check makes "one code, one
+  package" a build-time guarantee instead of a runtime hope, and a related,
+  pre-existing path-sanitization gap (D-012) closes as a direct consequence.
+  v0.31.4's same-day, independently-discovered fix is superseded during this
+  release, its regression test retained as additional coverage.
+---
+
+# v0.31.5 — One Code, One Package
+
+**Date:** 2026-07-23
+
+## Highlights
+
+- Supersedes v0.31.4's `_resolve_existing_item_directory` with one shared
+  resolver, `memory.builder.story_paths.resolve_story_directory` — heading-based,
+  unconditional, used by both Expand (`lifecycle.py`) and the CLI's Plan/checkpoint
+  path lookup (`cli/build.py`), which had its own separate, equally fragile
+  title-derivation fallback that v0.31.4 never touched.
+- Fail-loud instead of silent, in both directions v0.31.4 left open: two
+  packages claiming the same code now raise `StoryPackageAmbiguityError`
+  instead of silently resolving to whichever sorts first; a resolved package
+  whose candidate table can't be parsed now renders `<<<ARIAD:EXPAND_BLOCKED>>>`
+  instead of fabricating a generic story over real, unparseable content.
+- New CI guard — `find_duplicate_roadmap_headings` / `check_roadmap_duplicate_headings`,
+  wired into the existing `scripts/check_doc_links.py` and `docs.yml` (no new
+  workflow) — fails the build on two `docs/project/roadmap/**/index.md` files
+  sharing a heading code, closing the class statically, not just at runtime.
+- **D-012 closed**: the candidate-table *code* cell (Navigator- or
+  LLM-authored, unlike the title) is now sanitized the same way the title
+  already was, via a new `_sanitize_code_segment`. An unsanitized `/` or `..`
+  can no longer create unintended nested directories when Expand materializes
+  a child.
+- Canonical candidate-table grammar (`| Code | Story | Type | Outcome | Status |`)
+  documented in the DS index template and the mm-build skill's new authoring
+  contract, so hand-authored packages are Expand-compatible by construction.
+- Discovered independently on `kia-desktop` (v0.31.4, `b83b8a8`) and on
+  `mirror-ts-core`/CV22.DS7 (this release), the same day, before either
+  session knew about the other. Reconciled by rebase: v0.31.4's fix is
+  retired, its regression test (`test_expand_resolves_existing_nested_roadmap_folder`)
+  kept as additional coverage — verified to pass against this release's
+  implementation before the rebase was attempted.
+
+## Where We Started
+
+Two Ariad sessions hit the identical root cause on the same day, on two
+different projects, without knowing about each other. On `kia-desktop`,
+pulling and expanding `CV3.DS22` wrote a phantom `cv3-manage-100-funcional/cv3-ds22/`
+tree instead of expanding the real, hand-authored
+`cv3-build-de-producao/cv3-ds22-manage-100-funcional/`. That session shipped a
+narrow, same-day fix as v0.31.4: resolve the existing folder by heading code
+before falling back to title derivation.
+
+Meanwhile, a handoff from the `mirror-ts-core` journey described the second
+occurrence of a defect first seen as CR048 (`DS6.TS5`, hand-relocated): Expand
+diverging from an authored `CV22.DS7` package because the delivery cursor only
+ever carries a story's *leaf* title, and the old derivation assumed a full
+ancestor-title chain. Investigating that handoff surfaced the same class v0.31.4
+had just patched — but v0.31.4's fix lived entirely inside `lifecycle.py`,
+leaving the CLI's own separate path-resolution implementation untouched, never
+detecting ambiguity, and never addressing the second defect this class
+carries: silent fabrication over content that resolves but doesn't parse.
+
+## What Changed
+
+The fix is a DRY consolidation, not a patch on a patch. New
+`src/memory/builder/story_paths.py` gives every path-resolution call site one
+resolver: `resolve_story_directory` is unconditional and heading-based, tried
+first everywhere, and raises `StoryPackageAmbiguityError` the moment two
+packages claim the same code — the actual fix for the divergence class.
+Creating a genuinely new package (nothing exists yet, so nothing can diverge)
+degrades gracefully through three tiers — an existing parent package, the root
+roadmap snapshot's own CV title, or a bare code segment — and never uses
+title-chain arithmetic across code levels, the second, quieter defect in the
+original derivation.
+
+Fail-loud is reserved for real ambiguity. When Expand resolves an authored
+package whose `## Candidate Stories` table doesn't parse, or when two packages
+share a code, it now renders a first-class `<<<ARIAD:EXPAND_BLOCKED>>>`
+surface and writes nothing, rather than silently fabricating a generic story
+or silently picking a match. A new CI check makes the "one code, one package"
+invariant a build-time guarantee: `find_duplicate_roadmap_headings` scans the
+whole roadmap tree once, and `check_roadmap_duplicate_headings` wires it into
+the existing documentation-link CI job, so this class fails a pull request
+instead of surfacing in production months later.
+
+Pre-flight verification against this project's own 259-package roadmap found
+and fixed two more pre-existing bugs the new invariant depends on: a live
+duplicate heading (`CV20.DS4.US2`, a dropped story whose heading was never
+retitled away from its replacement's code) and a `HEADING_RE` gap that
+silently dropped lowercase sub-story codes like `CV21.E2.S1b`. And touching
+`_story_folder_name` / `_artifact_directory` / `_canonical_package_path` — the
+exact functions [D-012](../project/debt.md#d-012--roadmap-folder-derivation-does-not-sanitize-the-candidate-table-code-cell-for-path-separators)
+named as its revisit trigger — surfaced a real, if low-severity, gap: the
+candidate-table code cell was never sanitized the way the title already was.
+It is now, via `_sanitize_code_segment`, closing the debt in the same release
+rather than carrying it forward again.
+
+Reconciling with v0.31.4 required a rebase, not a merge: this release's
+implementation is a strict superset, verified empirically by running v0.31.4's
+own regression test against it before touching any history. The conflict was
+concentrated exactly where expected — `lifecycle.py`'s `_artifact_directory`
+region — and resolved by retiring v0.31.4's `_resolve_existing_item_directory`
+entirely while keeping its test as permanent, independent coverage of the
+`kia-desktop` scenario.
+
+## Conscious Exclusions
+
+- **No retroactive tree cleanup.** Any phantom folder a prior buggy Expand
+  already wrote — on `kia-desktop`, on `mirror-ts-core`'s CV22.DS7 — is not
+  cleaned up by this release. Both v0.31.4 and this release fix resolution
+  going forward; relocating already-diverged trees remains separate, manual
+  housekeeping, consistent with how the first occurrence of this class
+  (CR048 / `DS6.TS5`) was hand-fixed rather than migrated.
+- **`mirror-ts-core` port-branch work stays out of scope.** Deleting the
+  divergent CV22.DS7 tree and fixing its authored candidate table's grammar
+  happen on that branch, separately.
+- **Exact-code matching, not case-insensitive.** v0.31.4's resolver compared
+  codes case-insensitively (`.upper()`); this release's shared resolver
+  compares exactly. Every real code in this project's roadmap is
+  conventionally uppercase, and case-insensitive matching risks its own
+  ambiguity (two literally different headings resolving as one) more than it
+  protects against a real, observed failure mode.
+
+## What We Learned
+
+v0.31.4's own release note already named the lesson: two code paths answering
+"where does this roadmap item live?" must share one resolver, or they drift.
+This release shows that lesson needed to be pushed one level further. Knowing
+the lesson didn't prevent its own near-recurrence the same day, because the
+first fix was narrow enough to leave a second, unconsolidated implementation
+untouched (the CLI's own path lookup) and to leave the defect's quieter half
+unaddressed (silent fabrication over unparseable content, silent ambiguity).
+Closing a symptom is not the same as closing a class. The class closes when
+there is exactly one resolver everywhere it is needed, when every way that
+resolver can fail is either handled or refused loudly, and when a CI check
+makes the invariant impossible to violate silently — not when the one reported
+reproduction stops happening.
+
+## Next Horizon
+
+The roadmap-resolution class is now closed on every path that writes to it
+inside Mirror Mind's own runtime — CLI, Expand, and CI. Any project already
+using Ariad Builder Mode inherits the runtime fix on upgrade automatically.
+Whether the CI guard itself (`check_roadmap_duplicate_headings`) should become
+something consumer projects can wire into their *own* CI, rather than living
+only in Mirror Mind's repository, is now a visible, undecided question —
+`kia-desktop` had no equivalent guard and would not have caught its own
+CV3.DS22 divergence before it shipped.

package/docs/releases/v0.31.6.md

@@ -0,0 +1,132 @@
+---
+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.