---
digest: >
  v0.29.2 is the Ariad Builder flow refinement release. It sharpens the
  Refinement and Delivery surfaces introduced in the previous Builder releases,
  replacing metadata-heavy cards with compact Navigator-facing orientation,
  stable RS/CR display codes, deterministic lifecycle ribbons, and clearer
  handoffs through validation, debt review, Done, and project position. It also
  separates raw roadmap inspection from narrative project orientation while
  preserving artifact traceability and release/push boundaries.
---

# v0.29.2 — Ariad Builder Flow Refinement

**Date:** 2026-07-02

## Highlights

- Adds stable human-readable Refinement Story and Change Request display codes such as `RS001` and `CR021`, backed by a database migration while preserving internal ids for storage and diagnostics.
- Simplifies Refinement Work and Delivery Work surfaces so lifecycle ribbons appear only on real flow events and cards prioritize Navigator orientation over form-like metadata.
- Adds `PROJECT_POSITION` as the narrative orientation surface for Builder activation and Done completion while preserving `ROADMAP_SNAPSHOT` as the raw roadmap inspection surface.
- Centralizes artifact reporting through `ARTIFACTS_MATERIALIZED`, keeping lifecycle cards readable while retaining created/updated/existing file traceability.
- Folds Delivery Coherence into Done verification, clarifies validation-to-debt-review and no-action-debt-to-Done handoffs, and requires confirmation before final Done closure.
- Adds development/test environment visibility to the status line so local dogfooding sessions are easier to distinguish from production use.

## Where We Started

`v0.29.0` made Ariad Refinement Work real inside Builder Mode. Dogfooding immediately exposed a second-order problem: the system could move through the right states, but many cards still felt like internal records rather than conversational orientation surfaces. Opaque ids leaked into Navigator-facing views, lists mixed active work with closed work, lifecycle ribbons appeared on surfaces that were only inspections, and Delivery closure still treated Coherence as a separate stage instead of a Done responsibility.

At the same time, Builder activation and Done completion needed a better sense of position. Showing a raw roadmap table was useful when explicitly inspecting the roadmap, but it was too blunt as the final word after a story closed. The Navigator needed a compact answer to: where are we now, what just moved, and what looks next?

## What Changed

Refinement Work now speaks in stable display codes. Refinement Stories and Change Requests receive persisted `RS###` and `CR###` codes, with migrations that backfill existing Workbench rows and unique indexes per journey. The runtime still keeps opaque internal ids for storage and CLI/debug cases, but Navigator-facing surfaces use the readable codes.

The Refinement cards were tightened around flow semantics. Overview, capture, query, and orientation surfaces no longer pretend to be lifecycle events. Real transitions still show ribbons, but static inspection surfaces stay quiet. Done items render after active/actionable work, and status marks use consistent colored square grammar.

Delivery Work received the same dogfooding pressure. Plan approval now explicitly begins implementation, plan and validation cards are more compact, artifact paths moved out of lifecycle cards into `ARTIFACTS_MATERIALIZED`, and flow-unit selection became a scope confirmation rather than duplicated state output. Validation acceptance can hand off to Debt Review, no-action Debt Review can hand off to Done confirmation, and Done now performs the coherence responsibility internally.

The roadmap/orientation split is now explicit. `ROADMAP_SNAPSHOT` remains the raw inspection surface for commands that ask to see the roadmap. `PROJECT_POSITION` is the narrative orientation surface used at Builder activation and at the end of Done. Done completion can now say what just moved and still leave the Navigator oriented toward the next pull.

A small runtime orientation improvement also entered this release: the status line now shows `development` or `test` when the runtime environment is not production. That change is intentionally included because this release was driven by local dogfooding and needs clearer environment awareness.

## Conscious Exclusions

- This release does not publish new Delivery Story functionality beyond the Builder/Ariad flow refinements described here.
- Refinement Work is not yet fully governed by Ariad method DSL data; CV20.DS11 records that as the next governance story.
- Refinement phase outputs are not yet materialized as durable project artifacts; CV20.DS12 records that artifact trail as future work.
- The global project-wide `mypy src` debt is not resolved here. Focused mypy on the touched Builder/runtime modules is clean, and the global diagnostics were confirmed to be preexisting.
- Push, tag creation, stable promotion, and GitHub Release publication remain explicit release operations, not Builder Done side effects.

## What We Learned

Dogfooding surfaces is different from proving state machines. The underlying lifecycle can be correct while the Navigator still feels lost. A good Builder surface should not expose every field the runtime knows; it should preserve the current decision, the boundary, and the next possible move.

The work also clarified the distinction between inspection and orientation. A roadmap table is valuable when the user asks for the roadmap. At an activation or Done boundary, the better surface is narrative position: the current focus, the movement that just happened, and the available path.

## Next Horizon

The next Builder horizon is governance and durability. CV20.DS11 should move Refinement lifecycle semantics into inspectable Ariad method data, and CV20.DS12 should give Refinement Work a durable artifact trail comparable to Delivery Story packages. Release and push policy also remain visible as a separate governance layer: Builder can close work, but public publication stays an explicit human-authorized operation.
