---
digest: >
  v0.31.2 is a maintenance patch that stops the Ariad Builder runtime from
  crashing on long document content. `build pull-item` on a Delivery Story
  raised OSError [Errno 63] (File name too long) whenever a candidate story
  title was paragraph-length, because the kebab slug used for the roadmap
  folder had no length cap. The fix consolidates four drifted `_slugify`
  copies into one accent-stripping, length-capped `memory.utils.kebab_slug`,
  which also closes the identical latent crash in the Explorer handoff writer
  and makes the roadmap package writer and locator derive the same path by
  construction. A five-persona review of the plan corrected the original
  handoff's "single choke point" assumption and left code-cell sanitization
  and the transcript-export slug sibling as recorded debt.
---

# v0.31.2 — Filesystem-Safe Slug Consolidation

**Date:** 2026-07-22

## Highlights

- Fixes an `OSError [Errno 63] (File name too long)` crash in `build
  pull-item` when a Delivery Story's candidate-story title is
  paragraph-length: the roadmap folder slug now hard-caps at 80 characters,
  well under the 255-byte filesystem `NAME_MAX`.
- Consolidates four drifted kebab `_slugify` copies (`builder/lifecycle`,
  `cli/build`, `services/explorer_handoff`, `services/journey`) into a single
  `memory.utils.kebab_slug` — accent-stripping, kebab-case, length-capped.
- Closes the *same* latent `mkdir` crash in the Explorer→Builder handoff
  writer, which used `exist_ok=False` and would have failed harder on a long
  handoff title.
- Makes the roadmap package *writer* (`lifecycle`) and *locator* (`build`)
  derive the same folder path by construction, removing a silent divergence
  that capping only one copy would have introduced.
- Empty-slug guard: an all-punctuation title now yields the bare code folder
  (`ds-35-ts-1`) instead of a trailing-hyphen name (`ds-35-ts-1-`).
- Records two conscious exclusions as debt: D-012 (the candidate-table *code*
  cell is still not sanitized for path separators) and D-013 (the
  `transcript_export` capped-kebab sibling stays separate).

## Where We Started

A separate Builder session pulling Delivery Story DS-37 hit a hard runtime
crash. `build pull-item` ran `pull → prepare → expand`, and `expand` died
inside `mkdir` with `OSError [Errno 63] (File name too long)`. The Delivery
Story's candidate-stories table used full paragraphs as the "Story" cell, and
the kebab slug that becomes the child package's directory name had no length
cap — a ~650-character component against a 255-byte filesystem limit. The
runtime must never crash on document content, so this was a robustness bug,
not an authoring problem to be worked around by shortening a title.

## What Changed

The reported fix was a five-line length cap in one function. The review found
that would have been wrong in a subtle way. There were four separate
kebab-style `_slugify` implementations, and two of them —
`builder/lifecycle.py` (which *writes* the roadmap package) and
`cli/build.py` (which *locates* it) — derive the same folder path. Capping
only the crashing one would have made the writer and the locator disagree.
Meanwhile `services/journey.py` already carried the correct capped,
accent-stripping version, and `services/explorer_handoff.py` held a third
uncapped copy feeding a stricter `mkdir(exist_ok=False)`.

So the fix became a consolidation. The correct algorithm was promoted to a
single `memory.utils.kebab_slug` — strip accents, collapse to kebab-case,
hard-cap at 80 characters — and all four callers now route through it. That
one change fixes the DS-37 crash, closes the identical latent crash in the
Explorer handoff writer, keeps the writer and locator consistent by
construction, and adds accent-stripping to the two callers that lacked it. An
all-punctuation title now produces the bare code folder rather than a
trailing-hyphen name, matching the sibling path-derivation code that already
handled the empty case.

The plan was reviewed through five professional lenses — quality-assurance,
database-architect, security-engineer, devops-engineer, and ai-engineer —
before implementation. That review corrected the original handoff's premise
(the "single choke point" was actually four choke points), confirmed the
back-compat guarantee, and surfaced the two gaps now carried as debt.
Back-compat was verified against the live repository: the longest existing
roadmap slug is ~63 characters, under the 80 cap, and no existing folder ends
in a hyphen, so no package path on disk changes. The change shipped test-first
with unit coverage for `kebab_slug`, the empty-slug guard, both
paragraph-title crash regressions, and a single-source consolidation guard.

## Conscious Exclusions

- **D-012 — code-cell sanitization.** `kebab_slug` hardened the folder
  *title*, but the work-item *code* segment is still only lower-cased and
  dot-replaced, so a crafted code cell with path separators remains a latent
  traversal vector. Low severity today — candidate tables are Navigator-
  authored and local — so it is recorded, not fixed here.
- **D-013 — the fifth slugger.** `cli/transcript_export.slugify` is a
  capped-kebab sibling with different semantics (public name, cap 50,
  word-boundary truncation, `"conversation"` fallback) and stays separate;
  `docs_lint.slugify` is a deliberately different GitHub-anchor slugger and is
  not debt.
- **No behavior change to journey slugs.** `kebab_slug` reproduces
  `journey.py`'s prior output exactly, so journey creation and validation are
  untouched.

## What We Learned

A handoff that framed the fix as a five-line, single-site cap was accurate
about the crash and wrong about the blast radius. Reading the actual call
graph before writing the cap turned a local patch into a consolidation that
closed a second, unreported crash site and prevented a silent writer/locator
divergence. The cheap correctness came from treating the handoff's "root
cause" as a hypothesis to verify, not a conclusion to implement.

## Next Horizon

The two recorded debt items — code-segment sanitization (D-012) and the
transcript-export slug sibling (D-013) — are the visible follow-ups the next
time a change touches roadmap folder derivation or transcript export. The
consolidation leaves a single, obvious place to make those improvements.
