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