---
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.
