@pilotspace/add 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [1.6.0] — 2026-06-16
+
+The releasing release: shipping a versioned cut is now a first-class **5th ADD
+scope level**, not an ad-hoc ritual. The AI gathers the inventory and drafts
+evidence-backed notes, the engine records the cut behind a security-hard-stop
+readiness floor, and the human owns the tag and publish. All additive; no
+breaking changes (SemVer MINOR).
+
+### Added
+- **The RELEASE scope level (`release.md`)** — the on-demand guide for the 7-step
+  flow `cue → gather → draft notes → readiness floor → human confirms → cut → watch`,
+  orthogonal to stage: bundle one or more closed milestones into a versioned,
+  watched cut. Cross-referenced from `SKILL.md`.
+- **`add.py release-report`** — a read-only gather of the five record-sets (closed
+  milestones · their consolidated deltas · riding `RISK-ACCEPTED` waivers · open
+  security `HARD-STOP` · scenarios → monitors), with `--json`, plus the
+  `→ releasable: N milestone(s)` status cue.
+- **`add.py release <version>`** — a guarded, record-only cut: it prepends the
+  `CHANGELOG.md` block, appends an append-only `RELEASES.md` ledger row
+  (newest-first), and attributes the bundled milestones — behind a four-code
+  readiness floor (`release_security_open` · `release_tests_red` ·
+  `release_no_closed_milestone` · `release_undisclosed_waiver`). The security stop
+  is **un-forceable**: `--force` can override the other three, never that one.
+- **`RELEASES.md`** — the append-only release ledger (date · version · milestones ·
+  waivers · evidence); membership is the attribution source, so the cue never has
+  to read a compacted milestone file.
+- **Book chapter 16 (`16-releasing.md`)** + five glossary entries (Release · Release
+  scope level · Readiness floor · RELEASES.md ledger · Hotfix release) + the
+  `test_release_docs_accord` guard that keeps the book in accord with `release.md`.
+
+### Notes
+- **The engine records; the human ships.** `add.py release` writes the changelog +
+  ledger + attribution; it never bumps a version source, tags, publishes, or
+  deploys. The outward act stays human-owned and tool-agnostic — exactly the
+  human-gated `git tag` that cut this very release.
+
+## [1.5.0] — 2026-06-16
+
+The UDD design-loop release: defining the design *before* the code is now a
+guided, evidence-backed loop inside the method. A new `design.md` drives the UDD
+beats to a confirmed screen, a wireframe + HTML-mock recipe renders a real screen
+the human approves before build, and the engine measures that the confirmation
+was actually captured. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **UDD design-definition loop (`design.md`)** — turns the foundation's UDD
+  concern into a runnable loop: a low-fi structural wireframe → a self-contained
+  HTML mock (resolve semantic tokens → one kit class per component → compose the
+  prototype tree → populate with mock data) → a captured screen the human
+  confirms *before* any build. Wired into `0-setup` and `1-specify`.
+- **Wireframe + HTML-mock recipe (`udd-wireframe.md`) + sample templates** — a
+  zero-dependency, any-stack floor for rendering a prototype tree into a real
+  screen, with a worked sample set (`tokens.sample.css`, `kit.sample.css`,
+  `welcome.sample.html`, `settings.sample.html` reusing the kit,
+  `wireframe.sample.txt`). One semantic-token flip re-themes every screen by
+  construction. An optional `@json-render/image` (Satori → PNG/SVG, no browser)
+  fast path is noted for JS-ecosystem projects.
+- **Capture-evidence convention + `missing_capture` WARN** — design captures live
+  at `.add/design/captures/<name>.<ext>`; `add.py check` emits a never-red
+  `missing_capture` warning for any prototype lacking a capture (silent when
+  absent, so non-UI projects stay clean). The engine *measures* capture presence;
+  it never renders.
+
 ## [1.4.0] — 2026-06-15
 
 The guided-onboarding release: starting and running an ADD project is now guided

package/docs/14-foundation.md

@@ -47,6 +47,17 @@ the method already names, made explicit as three concerns.
   test that behaviour; the foundation keeps the design intent that makes a screen
   worth building.
 
+When a milestone has screens, UDD is not only a static `DESIGN.md` — it runs a
+**design-definition loop** that turns the domain into a screen the human has *seen
+and confirmed before build*. Its four beats are `review-domain → research-components
+→ wireframe → render-capture-confirm`: read the domain into screens and regions,
+research and reuse components before inventing them, wireframe the structure low-fi,
+then render a real screen and **capture** it. That capture is the **design-confirm**
+evidence — a real image the person approves *before* implementation, so the build
+matches the layout instead of discovering it. The book keeps the *why*; the
+operational recipe (the wireframe format, the token-bound mock, the capture engines)
+lives in the `add` skill's `design.md` and `udd-wireframe.md`.
+
 These three foundation competencies, together with the **TDD ⇄ ADD** engine of
 [Part II](./02-the-flow.md), are ADD's five. The first four feed context to the
 fifth, where the AI executes on it:

package/docs/16-releasing.md

@@ -0,0 +1,182 @@
+# 16 · Releasing
+
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+
+---
+
+The flow chapters ([03](./03-step-1-specify.md)–[08](./08-step-6-verify.md)) take one feature from
+spec to verified. The loop chapter ([09](./09-the-loop.md)) keeps a milestone going until its goal
+is met. The stages chapter ([10](./10-setup-and-stages.md)) graduates the project's rigor. None of
+them *ship*. This chapter names the act every project eventually performs and that the method, until
+now, never formalized: bundling closed milestones into a versioned, user-facing release whose notes
+are evidence-backed, whose risk is disclosed, and whose behaviour is then watched.
+
+Releasing is the **fifth scope level** — after the task, the milestone, the foundation/setup level,
+and stage graduation. Like every scope level it runs the same shape: **gather → propose → the human
+confirms → the engine records and enforces a floor.** And like graduation, it ends with an outward
+act the human owns. The operational recipe lives in the `release.md` skill guide; this chapter is the
+*why* behind it.
+
+## 16.1 · Why release is its own scope level
+
+A number bump is not a release. A release is the moment one or more **closed milestones** become a
+versioned cut that real users can run. Three distinctions make it its own scope level:
+
+- **Milestone ≠ release.** A milestone is *feature-complete and consolidated* — its goal is met and
+  its lessons are gathered into the foundation (see [14 · The foundation](./14-foundation.md) and the
+  `fold.md` retrospective consolidation). A release is *shipped and watched*. The first is an internal
+  state; the second faces outward.
+- **Graduation ≠ release.** Stage graduation moves the project's *rigor* (mvp → production); a release
+  ships a *version*. The two axes are orthogonal: you cut a prototype preview, an mvp beta, and a
+  production GA, each at its own stage. You release at every stage, not only at the end.
+- **A release bundles; it does not equal.** One version may attribute several milestones — "we shipped
+  after a couple of milestones closed" is the normal case, not the exception. Forcing one release per
+  milestone is the anti-pattern; the decoupling is the whole point.
+
+So release sits beside the other scope levels rather than inside any of them. The granularity ladder
+is now complete: intake → milestone → task, with stage graduation and release as the two cross-cutting
+levels that change *rigor* and ship *versions* respectively (see the **Scope level** entry in
+[Appendix C](./appendix-c-glossary.md)).
+
+## 16.2 · The cue and the inventory — gather, never judge
+
+The trigger is a status line. When at least one milestone is `done`, archived, and not yet attributed
+to any release, `add.py status` prints:
+
+```
+  → releasable: N milestone(s) closed since last release
+```
+
+That line is a **tally**, never a verdict. It counts archived-but-unreleased milestones; it is silent
+for a project that has never released or has already shipped everything (grandfathered — zero change).
+It says *there is something to consider*, not *you are ready*.
+
+To gather the cut's evidence, run `add.py release-report`. It clusters five labeled record-sets: the
+closed milestones since the last release · their **consolidated deltas** (the "what changed" record) ·
+the open `RISK-ACCEPTED` waivers riding into the release · any open security `HARD-STOP` (a blocker) ·
+the §2 scenarios to take live as monitors. The report **gathers; it does not judge** — there is no
+readiness score to read off, because a tally that pretended to be a verdict would invite reading the
+number instead of the evidence.
+
+The reuse claim, stated plainly: **the consolidated deltas are the changelog source.** You do not write
+release notes from memory. The foundation already recorded what changed when each milestone was
+consolidated (`fold.md`); the release surfaces it. This is why release runs *after* consolidation, not
+before. The lifecycle order is one line:
+`milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
+
+## 16.3 · Drafting the notes and the version — the proposal
+
+From those record-sets you draft a [Keep a Changelog](https://keepachangelog.com/) entry: group the
+changes under Added / Changed / Fixed and name the headline capabilities concretely, in the user's
+language, not the commit's. Each bundled milestone's goal anchors one or more entries.
+
+Then propose the version. Semver is a decision the evidence informs but does not make for you: a
+breaking change is a MAJOR, a new capability a MINOR, a fix-only cut a PATCH. You propose the bump; the
+**human confirms it** — the version is a judgement, not a default the tool fills in.
+
+Both the notes and the version are *shown before they are asked about*. Present the drafted entry, the
+proposed version, and the waivers shipping in this cut via the report template — opening with the ARC
+(goal · done · plan) — and let the human approve once. The question is a summary to decide on; the
+artifact itself is rendered first, never pre-stamped.
+
+## 16.4 · The floor — what the engine enforces
+
+`add.py release <version>` is **guarded**. Before it records anything it enforces a readiness floor,
+refusing with a non-zero exit and leaving every file byte-unchanged on any of four conditions:
+
+- `release_security_open` — an open security `HARD-STOP` exists. This is the non-negotiable one: a
+  security finding is never shipped. Resolve it first, as a change request back to Specify.
+- `release_tests_red` — the suite is not green. A release ships on evidence, not on a plausible diff.
+- `release_no_closed_milestone` — nothing new since the last release. The cut would be a no-op; do not
+  bump a version to mark time.
+- `release_undisclosed_waiver` — a `RISK-ACCEPTED` waiver rides into the release but is missing from the
+  notes. Disclosure *is* the floor: a shipped risk the user cannot read about is a hidden risk.
+
+The security stop is **un-forceable.** `--force` exists for grandfathered and brownfield first-cuts —
+the same authority valve as `stage --force` ([10 · Setup and stages](./10-setup-and-stages.md)) — and
+it can override the other three rejects, but it can never override `release_security_open`. This mirrors
+the verify gate exactly ([08 · Verify](./08-step-6-verify.md)) and the governance ceiling that no
+autonomy level may lift ([11 · Governance](./11-governance.md)): a security `HARD-STOP` is the one
+outcome the method refuses to auto-pass, at verify and again at the cut.
+
+## 16.5 · The cut versus the ship — the engine records, the human ships
+
+Only after the human confirms do you run the cut. And here is the line that keeps releasing honest:
+**the engine records; the human ships.**
+
+`add.py release <version>` **records** the marker. It prepends the entry to `CHANGELOG.md`, stamps one
+append-only row (newest-first, like the §Key Decisions log) into `RELEASES.md` — date · version ·
+milestones · waivers shipped · evidence — and attributes the bundled milestones to this version, so the
+cue stops firing for them. The ledger is the attribution source: a milestone is "released" because a
+`RELEASES.md` row says so, never because a file was edited to claim it.
+
+What the engine does **not** do is act outward. It **never tags, publishes, or deploys.** The outward
+act — `git tag`, `npm publish`, the deploy pipeline — is the human's, tool-agnostic, exactly as the
+method tool "never renders" in design and "never spawns" a subagent. Design-for-failure — timeouts,
+retries, rollback, a tested revert path — belongs in the pipeline the human owns, not in a method tool
+that has no business holding deploy credentials. The tag is the human-gated trigger; the record is the
+engine's receipt that the floor was met.
+
+> **A caveat worth one paragraph.** `add.py release` writes `CHANGELOG.md` at the **project root**. That
+> is the right default for most repositories. But a repo with a different changelog convention — for
+> instance a **nested-package** layout whose root `CHANGELOG.md` is a deliberate pointer to a package's
+> own changelog — will get release blocks *prepended above* its existing content rather than replacing
+> it (the writer preserves what is there; it does not clobber). Reconcile per repo: either let the root
+> file carry the canonical log, or point the human's publish step at the package changelog the team
+> treats as the source of truth.
+
+## 16.6 · Watch and the hotfix path — re-entering observe
+
+A release is not the finish line; it is where the most reliable information finally appears. The §2
+scenarios that were pass/fail cases at build time become **live monitors** for the released version, and
+error-budget burn feeds the next loop. Live-registry and deploy confirmation are post-cut *evidence*,
+gathered after the tag — not unit tests pretending to be one.
+
+The unhappy path is first-class. A regression found in the wild re-enters at Specify as a **change
+request**, which narrows to a **hotfix release** — the same seven-step flow, scoped to the fix, cut as a
+PATCH. Releasing does not have a separate emergency mode; it has the ordinary flow at a tighter scope.
+
+Depth follows the stage, as everywhere in the method:
+
+- **prototype / poc** — a one-line preview note and a tag; no deploy ceremony. The point is feedback.
+- **mvp** — full notes, a tag, a guarded publish; watch the headline scenarios.
+- **production** — every step at full rigor: notes, tag, a deploy behind a rollback-tested pipeline,
+  live scenario monitors, and error-budget watch. The hotfix path is a routine capability here, not a
+  fire drill.
+
+## 16.7 · The flow, in one arc
+
+One arc, seven steps:
+
+**cue → gather → draft notes → readiness floor → human confirms → cut → watch**
+
+1. **cue** — `add.py status` prints `→ releasable: N` when an archived milestone is unreleased.
+2. **gather** — `add.py release-report` clusters the five record-sets (gather, never judge).
+3. **draft notes** — a Keep-a-Changelog entry drawn from the consolidated deltas; propose the version.
+4. **readiness floor** — the four guarded rejects; the security stop is un-forceable.
+5. **human confirms** — the notes, version, and waivers are shown, then approved once.
+6. **cut** — `add.py release <version>` records the CHANGELOG block + the `RELEASES.md` row + attribution.
+7. **watch** — the scenarios become monitors; a wild regression becomes a PATCH hotfix release.
+
+The recipe for each step — flags, the report's `--json` shape, the exact ledger row — lives in the
+`release.md` skill guide. This chapter is the reasoning; the guide is the procedure.
+
+## 16.8 · Worked example — this method's own 1.5.0
+
+The repository already runs this by hand, which is the best evidence the flow is real. The
+`udd-design-loop` milestone closed (4/4) and consolidated into `foundation-version 33`. From those
+deltas the human drafted the `## [1.5.0]` changelog entry, bumped the three version sources in
+lockstep, and a forward-pinned `test_release_1_5_0.py` asserted in-repo readiness: the versions agree,
+the changelog lineage survives, the feature anchors are named, and the engine is untouched by the
+release. The cut itself — the `git tag` that triggers the npm and PyPI publish — stayed human-gated,
+and the live-registry confirmation was gathered *after* the tag as verify evidence, never as a unit
+test.
+
+That ritual is what this chapter formalizes. `release-report` gathers the inventory, the floor enforces
+the security stop and the disclosures, `add.py release` records the cut, and the human still owns the
+tag. The method releases itself the way it asks every project to release: gather the evidence, disclose
+the risk, record the marker, and let a person make the outward call.
+
+---
+
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)

package/docs/README.md

@@ -54,6 +54,9 @@ For every feature, before AI writes any code, you write four short artifacts in
 **Lineage**
 - [15 · Foundations & Lineage](./15-foundations-and-lineage.md)
 
+**Releasing**
+- [16 · Releasing](./16-releasing.md)
+
 **Part IV — Reference**
 - [Appendix A · Templates](./appendix-a-templates.md)
 - [Appendix B · Prompt library](./appendix-b-prompts.md)

package/docs/appendix-c-glossary.md

@@ -72,10 +72,20 @@
 
 **Baseline approval** (formerly "the lock-down") — the single human gate ending autonomous setup: an explicit yes that freezes the foundation, first scope, and first contract together; runs as `add.py lock --by <name>`.
 
-**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level. (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
+**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level · release level (≥1 closed milestone → a versioned, watched cut; see **Release scope level**). (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
 
 **Autonomy level** (formerly "autonomy dial") — the explicit per-task setting (`autonomy: manual | conservative | auto`, an ordered ladder manual < conservative < auto) choosing who resolves Verify: `auto` auto-PASSes on complete evidence, `conservative` keeps a human at the gate, `manual` is the strict floor (the human owns the gate; nothing auto-resolves). A high-risk scope refuses an unguarded `auto` — it must be lowered to `manual` or `conservative`. New tasks seed a visible, overridable `autonomy: auto`; a live task with no level warns (`implicit_autonomy`), a token outside the set is rejected (`unknown_autonomy_level`).
 
+**Release** — a versioned, user-facing cut that bundles one or more closed milestones into something real users can run; its notes are evidence-backed, its risk is disclosed, and its behaviour is then watched. Recorded with `add.py release <version>`, which writes the changelog block and the ledger row but never tags, publishes, or deploys — the outward act stays human-owned. See [16 · Releasing](./16-releasing.md).
+
+**Release scope level** — the fifth scope level: releasing as its own granularity, orthogonal to the stage. A release bundles ≥1 closed milestone (never forced one-per-milestone) and may be cut at any stage — prototype preview, mvp beta, production GA. Distinct from milestone-close (feature-complete + consolidated) and from stage graduation (which changes rigor, not version). See **Scope level** and [16 · Releasing](./16-releasing.md).
+
+**Readiness floor** — the engine-enforced pre-cut gate `add.py release` applies before it records anything: a green suite, zero open security `HARD-STOP`, a closed-and-unreleased milestone to bundle, and every riding `RISK-ACCEPTED` waiver disclosed in the notes. Its four rejects are `release_security_open` (un-forceable) · `release_tests_red` · `release_no_closed_milestone` · `release_undisclosed_waiver`; `--force` may override every reject except the security stop.
+
+**RELEASES.md ledger** — the append-only, newest-first trail of release rows at the project root (date · version · milestones · waivers shipped · evidence). Like the §Key Decisions log it is never rewritten; a superseded or yanked version is recorded as a new row. The ledger is the attribution source — a milestone is "released" because a row says so — which is why the `→ releasable` cue never has to read a milestone file.
+
+**Hotfix release** — a narrowed PATCH cut that re-enters at Specify as a change request when a regression is found in a released version. It runs the same seven-step release flow scoped to the fix; releasing has no separate emergency mode, only the ordinary flow at a tighter scope.
+
 **Auto-ready goal** — a milestone goal whose every exit criterion **cites a verifier** (`(verify: <test|command|metric>)`), so the engine can self-verify the result against the goal without human judgment. It is the prerequisite by which **autonomy is earned by goal-clarity**: the **autonomy level** governs *who* resolves Verify, but a clarified, machine-checkable goal is what makes a self-verifying run meaningful. `add.py check` raises a `goal_not_auto_ready` **WARN** (never red) for the active milestone until it has an auto-ready goal (≥1 exit criterion and every one cited), and `status` surfaces it (`goal-ready: auto-ready ✓` / cited-of-total); a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this warning's. The lint forces a citation *slot* per criterion — it raises the floor but **cannot prove the citation is real** (a human can write `(verify: it works)`): citation-theater is the accepted irreducible floor, and the freeze gate and autonomy behavior are unchanged by it.
 
 **Automated quality gate** (formerly "evidence auto-gate") — the Verify resolver under `autonomy: auto`: a run may auto-PASS on complete evidence, recorded as *auto-resolved*; a security finding always escalates (`HARD-STOP`).
@@ -108,6 +118,14 @@
 
 **Newest-first append-only** — every append-only foundation sequence prepends the newest record at the top; the rolled-up settled line anchors at the bottom (the oldest end), so compaction collapses upward.
 
+**Wireframe** — the Stage-A low-fidelity, *structural* map of one screen: its regions and the component **slots** inside them, derived from `prototypes/<name>.json` *before* any color, type, or spacing — it answers "what goes where", not "what it looks like". Beat 3 of the UDD **design-definition loop**; the low-fi half of the two-stage fidelity that ends in a confirmed capture. See the `add` skill's `udd-wireframe.md` (Stage A).
+
+**Design mock** — the Stage-B high-fidelity, **self-contained** HTML render of a screen: the `catalog.json` components as a reusable token-bound kit, bound to `tokens.json` and populated with mock data, openable offline and screenshot-able. The human-facing *visible* evidence the human confirms (the frozen `prototypes/<name>.json` tree is its machine-checkable twin). Beat 4's hi-fi artifact; the recipe lives in the `add` skill's `udd-wireframe.md` (Stage B).
+
+**Capture** — the real rendered image (PNG/SVG) of a design mock: the **design-confirm evidence** artifact. Captures live at `.add/design/captures/<name>.<ext>` (one per prototype) and are attached or mentioned in the feature's `TASK.md`; `@json-render/image` (Satori → PNG/SVG, no browser) is the named default capture engine, otherwise the self-contained mock is screenshot headless. The engine never renders — it only MEASURES presence: `add.py check` raises a never-red `missing_capture` WARN for a prototype with no capture.
+
+**Design-confirm** — the human touchpoint closing the UDD **design-definition loop** (`review-domain → research-components → wireframe → render-capture-confirm`, beat 4 of the `add` skill's `design.md`): approving the captured screen image **before build**, show-before-ask, so the implementation matches the layout the human has already seen instead of discovering it.
+
 ---
 
 ## Optional mapping to formal phase names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -106,6 +106,11 @@ template, the tier pick — read `advisor.md`; and at any decision point self-sc
 (0–1 across six dimensions, refine if any < 0.9) with `confidence.md`. Both are advisory: the
 engine never spawns, and the self-score is never a gate.
 
+When a **UI feature** reaches specify, run the **design-definition loop** in `design.md` (UDD):
+review the domain → research and reuse components → wireframe → render a real captured screen the
+human confirms **before** build — so the build matches the expected layout. Tool-agnostic; the
+engine never renders.
+
 When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not
 yet met, `milestone-done` holds the milestone open — read `loop.md` for the dynamic loop that turns
 open deltas + extras into the next tasks, proposed by you and confirmed by the human, until the goal is met.
@@ -116,6 +121,13 @@ orchestration: gather `graduation-report` analytics → co-specify interview →
 milestone → human confirm → then (and only then) `stage production`. The flip is guarded
 (`stage_no_roadmap`) and is the FINAL step — never a bare label change.
 
+When one or more milestones have closed since the last release, `add.py status` prints
+**`→ releasable: N milestone(s) closed since last release`** — read `release.md` for the 5th scope
+level: gather `release-report` → draft notes from the consolidated deltas → meet the readiness floor
+(security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
+(CHANGELOG + `RELEASES.md` ledger + milestone attribution) → watch. The engine records; the human runs
+the tag / publish / deploy. A release bundles ≥1 milestone and is orthogonal to stage.
+
 ## Non-negotiable rules (from the method)
 
 <constraints>

package/skill/add/design.md

@@ -0,0 +1,92 @@
+# Design — the design-definition loop (UDD)
+
+When a **UI feature** reaches specify, design it before you build it. This loop takes the
+feature from the **domain** to a screen the human has **seen and confirmed** — a real captured
+image — *before* any implementation, so the build matches the expected layout instead of
+discovering it. It is loaded on demand (like `advisor.md` / `confidence.md`); the engine never
+runs it for you.
+
+Design before code is the UDD half of the method. The token + component foundation a UI project
+draws from already exists — `tokens.json` (the compact-DTCG dialect, `udd-tokens.md`),
+`catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop is how you *fill* that
+foundation for a feature and earn the human's sign-off on the look before build.
+
+## The loop — four beats
+
+```
+review-domain  →  research-components  →  wireframe  →  render-capture-confirm
+```
+
+Run the beats in order. Each feeds the next; the last ends at a human design-confirm.
+
+### 1 · review-domain
+Start from the **domain**, not from a blank canvas. Read the domain model — entities, flows, the
+ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature
+needs and the **regions** each screen holds. Map each domain entity to a *presentational*
+component (it shows state; it does not own a domain decision). The screen list + per-screen
+regions are this beat's output, and they are grounded in the domain you just read.
+
+### 2 · research-components (reuse before you invent)
+Check `catalog.json` **first** and **reuse** the components already there — that is what keeps
+screens consistent. Research a reference UI (a websearch over pattern galleries / component
+libraries for this kind of screen) only to fill a **genuine gap**, and propose a **new** catalog
+component for that gap with a **cited** reference. Reuse before invention; a new component is the
+exception, named and justified, not the default.
+
+### 3 · wireframe
+Draw a **low-fi**, **structural** layout for each screen — regions and component slots, no
+styling, no color. This is the cheapest possible artifact that shows the *expected layout*, so
+the human can correct the structure before a pixel is styled. Confirm the wireframe, then move on.
+
+### 4 · render-capture-confirm
+Render the screen as a **self-contained HTML mock** — the project's component library via CDN,
+bound to `tokens.json` (resolved to CSS variables), composed from the **reusable per-component
+kit** (one token-bound partial per catalog component), populated with realistic **mock** data.
+**Capture** a real image of it (a headless screenshot) and present that image to the human for
+**design-confirm** — show-before-ask, **before build**. On confirm, record the layout back to
+`prototypes/<name>.json` + `catalog.json`, save the captured image to
+`.add/design/captures/<name>.<ext>`, and **attach or mention it in the feature's `TASK.md`**
+(alongside the §6 evidence) — so the screen the human approved is traceable from the task that
+builds it. The HTML mock is the *visible evidence*; the json-render tree is the
+*machine-checkable* record of the same screen.
+
+## Tool-agnostic capture
+
+How you render and capture is **your** choice, not the engine's: a headless browser
+(Playwright / Puppeteer), an `html2image`-style renderer, a browser-automation skill, a design
+tool, or a hosted screenshot service — whatever the agent has. The recommended default is the
+self-contained HTML mock above, captured headless, because it needs no app build yet still wears
+the project's real tokens and component vocabulary. For a project that renders json-render, the
+recommended default is **`@json-render/image`** (Satori → PNG/SVG, no browser) — a deterministic
+`Spec` → image. The captured image is a **design-confirm evidence** artifact the human approves;
+it is never an engine output, and the engine never renders. This keeps the loop tool-agnostic and
+the method renderer-free.
+
+Captures live at **`.add/design/captures/<name>.<ext>`** (one per prototype) and are
+attached/mentioned in the feature's `TASK.md`. `add.py check` raises a never-red
+`missing_capture` WARN for any prototype under `.add/design/prototypes/` that still lacks a
+capture — a nudge to render + confirm it, never a blocker.
+
+The loop **binds** the existing UDD contracts **read-only**: `tokens.json`, `catalog.json`, and
+`prototypes/<name>.json` are read and composed, never reshaped — the `prototypes/<name>.json`
+data contract stays **unchanged** (a change to it is a change request, not a design step). And
+**identity** values — brand color, palette, typeface — stay **human-owned**: surface them for the
+human to decide, never auto-pick a brand value (`udd-tokens.md`).
+
+## The hard rules
+
+<constraints>
+- **Domain first.** A screen is derived from the domain (beat 1), never sketched blind.
+- **Reuse before invent.** Beat 2 checks the catalog first; a new component is a justified,
+  cited exception — never the reflex.
+- **Confirm before build.** The captured image is approved by the human *before* implementation;
+  a design-confirm placed at or after build defeats the loop.
+- **The engine never renders.** Capture is a recommended, tool-agnostic recipe run by the
+  agent's own tools; the image is evidence, not an engine artifact.
+- **Bind, don't break.** The loop reads `tokens.json` / `catalog.json` / `prototypes/<name>.json`
+  read-only; the data contract is unchanged, and identity values stay human-owned.
+</constraints>
+
+> Used at specify for a UI feature: `phases/0-setup.md` scaffolds `DESIGN.md`, and
+> `phases/1-specify.md` points here when the feature has a screen — run the four beats, then
+> carry the confirmed layout into the contract.

package/skill/add/phases/0-setup.md

@@ -74,7 +74,8 @@ gate: auto-complete NEVER skips the human baseline approval — the `lock` (§4)
 1. **Fill the living documentation** (it outlives all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
    milestone · UI/UX · Key Decisions, one screen), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`,
    `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (the design source of truth: identity ·
-   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI).
+   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI;
+   the design-definition loop that fills it — domain → components → wireframe → a captured screen confirmed before build — is `design.md`).
    Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
 2. **Propose, then size it.** You just read the codebase (brownfield) or interviewed (greenfield) — so
    don't silently draft. First float a **kickoff suggestion** for the first milestone the human reacts to:

package/skill/add/phases/1-specify.md

@@ -18,7 +18,9 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 **Identity is direction, not default (UDD).** For UI/design work, identity values — the brand
 color, the core palette, the typeface — are human-owned. Surface them for discussion during
 Diverge; never assume a brand value. The UDD token dialect checks a token's *shape*; its *value*
-is the user's call (`udd-tokens.md`).
+is the user's call (`udd-tokens.md`). For a UI feature with a screen, run the design-definition
+loop in `design.md` — domain → research and reuse components → wireframe → a real captured screen
+the human confirms before build — and carry the confirmed layout into the contract.
 
 ## Produce (in TASK.md §1)
 

package/skill/add/release.md

@@ -0,0 +1,114 @@
+# Release — cut a versioned ship, never an unwatched flip
+
+A project does not "release" because someone bumped a number. It releases when one or more
+**closed milestones** are bundled into a versioned, user-facing cut whose notes are evidence-backed,
+whose risk is disclosed, and whose behaviour is then watched. This guide is the **5th scope level** —
+after setup (`phases/0-setup.md`), intake (`intake.md` / `scope.md`), the milestone loop (`loop.md`),
+and stage graduation (`graduate.md`). It is a different verb from each of them:
+
+- a **milestone** is *feature-complete and consolidated*; a **release** is *shipped + watched*.
+- **graduation** changes the project's *rigor* (mvp→production); a **release** ships a *version*.
+  The axes are orthogonal — you cut releases at every stage (prototype preview · mvp beta · prod GA).
+
+So a release is its own scope level: it bundles **≥1** closed milestone, and it may bundle several.
+You (the AI) **gather and propose**; the **human confirms and judges**; the engine records the cut
+and enforces a floor — it **never tags, publishes, or deploys** (the same stance as "the engine never
+renders" in `design.md` and "never spawns" in `advisor.md`). The outward act is the human's.
+
+## The cue (what starts this)
+
+When ≥1 milestone is `done` AND archived AND not yet attributed to a release, `add.py status` prints:
+
+```
+  → releasable: N milestone(s) closed since last release
+```
+
+That line is the trigger. It is a **tally** over unreleased-but-archived milestones — never a
+readiness judgment. It is silent until the first such milestone exists (a project that has never
+released, or has released everything, sees nothing here — grandfathered, zero change).
+
+## The flow
+
+One arc, seven steps: **cue → gather → draft notes → readiness floor → human confirms → cut → watch.**
+
+1. **Gather the release inventory** — run `add.py release-report` (add `--json` to branch on it). It
+   clusters the cut's evidence into labeled record-sets: the closed milestones since the last release ·
+   their **consolidated deltas** (the "what changed" record) · open RISK-ACCEPTED waivers riding into
+   the release · any open **security HARD-STOP** (a blocker) · the §2 scenarios to take live as monitors.
+   It **gathers, never judges** — there is no readiness verdict to read; the records are what you reason from.
+2. **Draft the release notes** — write a [Keep a Changelog](https://keepachangelog.com/) entry **from the
+   consolidated deltas + each milestone's goal** (reuse — those consolidated deltas ARE the changelog source;
+   you are not inventing the story, you are surfacing what the foundation already recorded). Group Added / Changed /
+   Fixed; name the headline capabilities concretely. Propose the **semver bump** — breaking→MAJOR,
+   feature→MINOR, fix-only→PATCH — and let the human confirm it (the version is a decision, not a default).
+3. **Meet the readiness floor** — before the cut the engine enforces a floor (see below): the suite is
+   green, **zero** open security HARD-STOP, and every RISK-ACCEPTED waiver shipping in this release is
+   signed AND disclosed in the notes. A security finding is a HARD-STOP here exactly as in verify —
+   never auto-passed, never shipped silent.
+4. **Human confirms the cut** — present via `report-template.md`, opening with the ARC (goal · done · plan):
+   the version you are shipping, the milestones + evidence that earn it, and the rollout + watch plan that
+   follows. Show the drafted notes, the version, and the waivers being shipped. The human approves once
+   (the decision point) — never pre-stamped; you surface a summary to decide on, not the artifact itself.
+5. **Cut — record the marker** — only now run `add.py release <version> --notes <file>`. The engine
+   **records**: it prepends the CHANGELOG entry, stamps one append-only row (newest-first) in
+   `RELEASES.md` (date · version · milestones · waivers shipped · evidence), and attributes the bundled
+   milestones to this version (so the cue stops firing for them).
+6. **Ship — the human's outward act** — the engine has recorded the cut; the **human runs the tag /
+   publish / deploy** (`git tag`, `npm publish`, the deploy pipeline — tool-agnostic, whatever this project
+   ships through). The tag is the human-gated trigger, exactly the dogfooded recipe today. The engine never
+   performs it: design-for-failure lives in the pipeline the human owns, not in the method tool.
+7. **Watch — re-enter observe at the release scope level** — the §2 scenarios become live monitors for the
+   *released* version; live-registry / deploy confirmation is post-cut **evidence**, not a unit test. A
+   regression found in the wild re-enters at Specify as a **change request** → a narrowed **PATCH hotfix
+   release** (this same flow, scoped to the fix). Release is not the finish line — it is where the most
+   reliable information appears (`phases/7-observe.md`).
+
+## The floor (what the engine enforces)
+
+`add.py release <version>` is **guarded** — it refuses (non-zero exit, state byte-unchanged) on:
+
+<reject_codes>
+- `release_security_open` — an open security HARD-STOP exists. The non-negotiable; a security finding is
+  never shipped. Resolve it (a change request back to Specify) before the cut. `--force` does NOT override this.
+- `release_tests_red` — the suite is not green. Evidence, not a plausible diff, is what a release ships on.
+- `release_no_closed_milestone` — nothing new since the last release. The cut is a no-op; do **not** bump.
+- `release_undisclosed_waiver` — a RISK-ACCEPTED waiver rides into the release but is absent from the notes.
+  Disclosure is the floor: a shipped risk the user can't read about is a hidden risk. Add it to the notes.
+</reject_codes>
+
+`--force` preserves human authority for grandfathered / edge cases (e.g. a first release of a brownfield
+adopt), mirroring `stage --force` — but it never overrides `release_security_open`. Use it deliberately,
+not as the normal path.
+
+## Invariants (never break these)
+
+- **The engine records; the human ships.** `add.py release` writes the CHANGELOG + ledger + attribution;
+  it never tags, publishes, or deploys. The outward act stays human-owned and tool-agnostic.
+- **Security is a HARD-STOP at the cut**, not just at verify. No `--force`, no waiver, no exception.
+- **Notes draw from consolidated deltas** — release after `fold.md` has run, so the changelog surfaces
+  consolidated learnings, not raw open lessons. The lifecycle order is one line:
+  `milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
+- **The ledger is append-only (newest-first)** — like §Key Decisions, a release row is never rewritten;
+  a superseded or yanked version is recorded with a new row, never edited away.
+- **A release bundles, it does not equal.** One version may attribute several milestones; never force a
+  release per milestone.
+
+## Depth and reuse
+
+The shape is constant; the depth follows the stage (read it from `add.py status`):
+
+- **prototype / poc** — a one-line preview note + a tag; no deploy ceremony. The point is feedback, not GA.
+- **mvp** — full notes + tag + a guarded publish; watch the headline scenarios.
+- **production** — every step at full rigor: notes + tag + deploy behind a rollback-tested pipeline +
+  live scenario monitors + error-budget watch. The hotfix path (step 7) is first-class here.
+
+## Worked example (this method's own 1.5.0)
+
+The repo already runs this by hand. The `udd-design-loop` milestone closed (4/4) and consolidated into
+`foundation-version 33`; the human then drafted the `## [1.5.0]` CHANGELOG entry from those deltas,
+bumped the three version sources in lockstep, and the forward-pinned `test_release_1_5_0.py` asserted
+in-repo readiness (versions agree · changelog lineage survives · feature anchors named · engine
+untouched). The cut itself — the `git tag` that triggers the npm/PyPI publish — stayed human-gated, and
+the live-registry confirmation was gathered *after* the tag as verify evidence, never a unit test. This
+guide makes that ritual first-class: `release-report` gathers it, the floor enforces it, `add.py release`
+records it, and the human still owns the tag.

package/tooling/add.py

@@ -36,6 +36,14 @@ STAGES = ("prototype", "poc", "mvp", "production")
 # v22 stage-graduation: the read-only cue `status` shows when the MVP is covered.
 # Worded as the ACTION (never a file) so it stands before graduate.md exists.
 GRADUATION_CUE = "MVP covered → propose graduation"
+# release-altitude: the read-only cue `status` shows when ≥1 closed milestone is
+# unreleased. The 5th scope level (release.md). `{n}` is filled at print time; the
+# wording matches SKILL.md's "Beyond the bundle" cross-ref byte-for-byte.
+RELEASABLE_CUE = "releasable: {n} milestone(s) closed since last release"
+# the append-only release ledger lives at the PROJECT ROOT (the dir containing .add/),
+# a sibling of CHANGELOG.md — NOT inside .add/. The ledger IS the attribution source:
+# a milestone is "released" iff its slug appears on a `milestones:` row.
+RELEASES_FILE = "RELEASES.md"
 PHASES = ("ground", "specify", "scenarios", "contract", "tests", "build", "verify", "observe", "done")
 GATES = ("none", "PASS", "RISK-ACCEPTED", "HARD-STOP")
 # heal-then-escalate (verify-integrity): the bounded self-heal loop cap. A CONFIRMED cheat
@@ -1055,6 +1063,14 @@ def cmd_status(args: argparse.Namespace) -> None:
         print(f"archived: {n} milestone{'s' if n != 1 else ''} "
               f"({m_tasks} task{'s' if m_tasks != 1 else ''})")
 
+    # release cue (release-altitude): project-global + read-only. Fires when ≥1 CLOSED
+    # milestone (live-done OR archived) is not yet attributed to a RELEASES.md row — so it
+    # stands even with no live milestones. Additive: a line solely when releasable; the
+    # ledger read is fail-open (a vanished ledger never silences the cue). See release.md.
+    _rel = _releasable(root, state)
+    if _rel:
+        print(f"  → {RELEASABLE_CUE.format(n=len(_rel))}")
+
     print(f"active  : {active or '(none)'}")
     # surface the active task's autonomy level (task explicit-autonomy-dial) so the human
     # reads the throttle every session; "unset" when no explicit `autonomy:` line is present.
@@ -1606,6 +1622,27 @@ def _udd_named_set_checks(root: Path) -> list[tuple[bool, str, str]]:
     return out
 
 
+_CAPTURE_EXTS = ("png", "svg", "jpg", "jpeg", "webp")
+
+
+def _missing_captures(root: Path) -> list[str]:
+    """Prototype names under `.add/design/prototypes/` lacking a design-confirm capture.
+
+    A prototype `<name>.json` is CAPTURED iff a file `.add/design/captures/<name>.<ext>`
+    exists (ext in _CAPTURE_EXTS). Returns the uncaptured names in document (sorted) order.
+    PURE · TOTAL (missing dirs -> []) · READ-ONLY (never writes, never renders): the engine
+    MEASURES capture presence; producing the image is the agent's tool-agnostic choice
+    (design.md beat 4; default `@json-render/image`). [] == every prototype captured / none exist.
+    """
+    proto_dir = root / "design" / "prototypes"
+    cap_dir = root / "design" / "captures"
+    if not proto_dir.is_dir():
+        return []
+    names = sorted(p.stem for p in proto_dir.glob("*.json") if p.is_file())
+    return [n for n in names
+            if not any((cap_dir / f"{n}.{ext}").is_file() for ext in _CAPTURE_EXTS)]
+
+
 def cmd_check(args: argparse.Namespace) -> None:
     """Read-only integrity check of the .add project. Exit 1 if anything fails."""
     as_json = getattr(args, "json", False)
@@ -1772,6 +1809,16 @@ def cmd_check(args: argparse.Namespace) -> None:
     # Silent when absent; read-only; fail-closed on malformed JSON.
     checks.extend(_udd_named_set_checks(root))
 
+    # capture-evidence: a never-red WARN naming each prototype with no design-confirm capture
+    # at .add/design/captures/<name>.<ext>. Measure-never-block — rides `warnings`, NEVER
+    # `checks` (so never feeds `failed`); silent-when-absent (no prototypes -> []). The engine
+    # MEASURES capture presence; producing the image is the agent's tool-agnostic choice.
+    for _pname in _missing_captures(root):
+        warnings.append(("missing_capture",
+                         f"prototype '{_pname}' has no design-confirm capture at "
+                         f".add/design/captures/{_pname}.<png|svg|…> — render + confirm it "
+                         "before build (design.md beat 4)"))
+
     passed = sum(1 for ok, _, _ in checks if ok)
     failed = len(checks) - passed
     if as_json:
@@ -4082,6 +4129,296 @@ def cmd_graduation_report(args: argparse.Namespace) -> None:
     print("\n".join(L))
 
 
+def _releases_path(root: Path) -> Path:
+    """The append-only release ledger — at the PROJECT ROOT (root IS the .add dir, so its
+    parent), a sibling of CHANGELOG.md. NOT inside .add/."""
+    return root.parent / RELEASES_FILE
+
+
+def _released_milestones(root: Path) -> set[str]:
+    """Slugs already attributed to a release — the union of every `milestones:` row in
+    RELEASES.md. Fail-OPEN: a missing/unreadable/malformed ledger yields the empty set, so
+    every closed milestone reads as still-releasable (a vanished ledger never hides work).
+    READ-ONLY."""
+    try:
+        text = _releases_path(root).read_text(encoding="utf-8")
+    except OSError:
+        return set()                         # no ledger (or a dir at the path) -> nothing released yet
+    out: set[str] = set()
+    for line in text.splitlines():
+        st = line.strip()
+        if st.lower().startswith("milestones:"):
+            for tok in re.split(r"[,\s]+", st.split(":", 1)[1]):
+                tok = tok.strip()
+                if tok and tok.lower() != "none":
+                    out.add(tok)
+    return out
+
+
+def _closed_milestones(state: dict) -> list[dict]:
+    """Every CLOSED milestone (its milestone-done gate passed): LIVE done milestones
+    (status == 'done', still in state) + ARCHIVED milestones (all were PASS-done before
+    archive — see _archived_task_slugs). Each: {slug, title, tier}."""
+    out: list[dict] = []
+    for slug, m in (state.get("milestones") or {}).items():
+        if m.get("status") == "done":
+            out.append({"slug": slug, "title": m.get("title", slug), "tier": "live"})
+    for rec in state.get("archived") or []:
+        if rec.get("slug"):
+            out.append({"slug": rec["slug"], "title": rec.get("title", rec["slug"]),
+                        "tier": "archived"})
+    return out
+
+
+def _releasable(root: Path, state: dict) -> list[dict]:
+    """Closed milestones NOT yet attributed to any RELEASES.md row — the cut's candidate
+    bundle. Drives BOTH the `→ releasable: N` status cue and release-report. READ-ONLY."""
+    released = _released_milestones(root)
+    return [m for m in _closed_milestones(state) if m["slug"] not in released]
+
+
+def _key_decisions_for(root: Path, slug: str) -> list[str]:
+    """Best-effort §Key-Decisions rows from PROJECT.md that NAME this milestone slug — the
+    consolidated decisions the changelog can cite. Fail-open: a missing section / unreadable
+    foundation / no slug match -> [] (a gather never raises). READ-ONLY."""
+    try:
+        text = (root / "PROJECT.md").read_text(encoding="utf-8")
+    except OSError:
+        return []
+    m = re.search(r"^#{1,6}[^\n]*key decision[^\n]*$(.*?)(?=^#{1,6}\s|\Z)", text, re.S | re.M | re.I)
+    if not m:
+        return []
+    return [st.lstrip("-* ").strip() for st in (ln.strip() for ln in m.group(1).splitlines())
+            if st.startswith(("-", "*")) and slug in st]
+
+
+def release_data(root: Path, state: dict) -> dict:
+    """The single source of FACTS for a release cut — PURE, NO writes (mirrors graduation_data).
+    Both the `release-report` text dashboard and `--json` render from this one dict, so the human
+    view and the machine view can never disagree.
+
+    GATHER, never JUDGE: every value is a RECORD the human verifies by looking; there is no
+    readiness/score/ranking field by construction. Five record-sets feed the release.md flow:
+      releasable — closed-but-unreleased milestones (the bundle candidate; the cue's count)
+      changed    — per releasable milestone: RETRO path + carried-delta count + §Key-Decisions rows
+      waivers    — open RISK-ACCEPTED riding into the cut (soonest expiry first)
+      blockers   — open HARD-STOP gate records (the security stop the floor will refuse on)
+      monitors   — declared §7 Watch lines to carry into the post-cut watch step
+    A source is read fail-closed (skip on error); the ledger is read fail-OPEN (see _releasable)."""
+    tasks = state.get("tasks") or {}
+    releasable = _releasable(root, state)
+
+    # changed — the consolidated learning trail per releasable milestone (the changelog source)
+    changed = []
+    for m in releasable:
+        slug = m["slug"]
+        retro = None
+        for sub in ("milestones", "archive"):
+            cand = root / sub / slug / "RETRO.md"
+            if cand.is_file():               # a directory at the path is not a ledger (fail-closed)
+                retro = str(cand.relative_to(root))
+                break
+        changed.append({"milestone": slug, "key_decisions": _key_decisions_for(root, slug),
+                        "retro": retro,
+                        "carried_deltas": _retro_carried(root / retro) if retro else 0})
+
+    # waivers — open RISK-ACCEPTED riding into the cut, soonest expiry first (mirrors graduation_data)
+    waivers = []
+    for slug, t in tasks.items():
+        if t.get("gate") == "RISK-ACCEPTED" and t.get("waiver"):
+            w = t["waiver"]
+            waivers.append({"slug": slug, "owner": w.get("owner", "?"),
+                            "ticket": w.get("ticket", "?"), "expires": w.get("expires", "?")})
+
+    def _exp_key(wv):
+        try:
+            return (0, date.fromisoformat(wv["expires"]).isoformat())
+        except (ValueError, TypeError):
+            return (1, "")                   # unparseable/missing -> after every real date
+    waivers.sort(key=_exp_key)
+
+    # blockers — open HARD-STOP gate records (the un-forceable security stop the floor enforces)
+    blockers = [{"slug": s, "gate": t.get("gate")} for s, t in tasks.items()
+                if t.get("gate") == "HARD-STOP"]
+
+    # monitors — declared §7 Watch lines (filled, not the `<…>` template) for the watch step
+    monitors = []
+    for slug in tasks:
+        try:
+            text = (root / "tasks" / slug / "TASK.md").read_text(encoding="utf-8")
+        except OSError:
+            continue                         # unreadable TASK.md -> skip this task's monitor record
+        for line in text.splitlines():
+            st = line.strip()
+            if st.startswith("Watch") and "<" not in st and st != "Watch":
+                monitors.append({"slug": slug, "watch": st})
+                break
+
+    return {
+        "releasable": releasable,
+        "changed": changed,
+        "waivers": waivers,
+        "blockers": blockers,
+        "monitors": monitors,
+        "summary": {
+            "releasable": len(releasable), "changed": len(changed), "waivers": len(waivers),
+            "blockers": len(blockers), "monitors": len(monitors),
+        },
+    }
+
+
+def cmd_release_report(args: argparse.Namespace) -> None:
+    """Read-only: GATHER the release inventory into five labeled record-sets for the release.md
+    flow. text (default) or --json (the frozen JSON facts interface). Exit 0 ALWAYS — a gather,
+    not a gate; the ONLY non-zero exit is no_project. Judges nothing. NO writes."""
+    root = find_root()
+    if root is None:                 # frozen contract: fail-closed with a no_project signal
+        _die("no_project: no .add/ project found. Run `add.py init` first.")
+    state = load_state(root)
+    d = release_data(root, state)
+
+    if getattr(args, "json", False):
+        print(json.dumps(d, ensure_ascii=False, indent=2))
+        return
+
+    s = d["summary"]
+    L = ["RELEASE REPORT — release inventory (gather, not judge)", ""]
+    L.append(f"Releasable ({s['releasable']}) — closed milestones not yet in {RELEASES_FILE}:")
+    for m in d["releasable"]:
+        L.append(f"  - {m['slug']} [{m['tier']}]: {m['title']}")
+    L.append("")
+    L.append(f"Changed ({s['changed']}) — the consolidated learning trail per milestone:")
+    for c in d["changed"]:
+        L.append(f"  - {c['milestone']}: {c['retro'] or '(no RETRO record)'} "
+                 f"({c['carried_deltas']} carried · {len(c['key_decisions'])} key decision(s))")
+    L.append("")
+    L.append(f"Waivers ({s['waivers']}) — open RISK-ACCEPTED riding into the cut, soonest expiry first:")
+    for w in d["waivers"]:
+        L.append(f"  - {w['slug']}: {w['owner']} · {w['ticket']} · expires {w['expires']}")
+    L.append("")
+    L.append(f"Blockers ({s['blockers']}) — open HARD-STOP (the un-forceable security stop):")
+    for b in d["blockers"]:
+        L.append(f"  - {b['slug']}: {b['gate']}")
+    L.append("")
+    L.append(f"Monitors ({s['monitors']}) — declared §7 Watch lines to carry into the watch step:")
+    for mo in d["monitors"]:
+        L.append(f"  - {mo['slug']}: {mo['watch']}")
+    print("\n".join(L))
+
+
+def _build_in_flight(state: dict) -> bool:
+    """release_tests_red proxy (PURE): is any ACTIVE task mid-build without a recorded green gate
+    — phase ∈ {build, verify} AND gate == 'none'? The tool-agnostic engine never runs the suite,
+    so an entered-but-ungated build is the recorded-evidence stand-in for 'the suite is red'."""
+    return any(t.get("phase") in ("build", "verify") and t.get("gate") == "none"
+               for t in (state.get("tasks") or {}).values())
+
+
+def _prepend_block(existing: str, header: str, block: str) -> str:
+    """Newest-first prepend: insert `block` directly under the top H1 `header`, creating the
+    header when `existing` is empty / headerless. Existing content is preserved VERBATIM
+    (append-only). `block` is expected to end in a blank-line separator."""
+    if not existing.strip():
+        return f"{header}\n\n{block}"
+    if existing.lstrip().startswith(header):
+        after = existing.split(header, 1)[1].lstrip("\n")
+        return f"{header}\n\n{block}{after}"
+    return f"{block}{existing}"               # no recognized header -> block goes on top, verbatim tail
+
+
+def _render_changelog_block(version: str, day: str, bundle: list[dict],
+                            changed_by_slug: dict) -> str:
+    """A CHANGELOG block: `## <version> — <date>` + one bullet per bundled milestone (title +
+    carried-delta / key-decision counts from release_data['changed'])."""
+    lines = [f"## {version} — {day}", ""]
+    if bundle:
+        for m in bundle:
+            c = changed_by_slug.get(m["slug"], {})
+            lines.append(f"- {m['title']} — {c.get('carried_deltas', 0)} carried · "
+                         f"{len(c.get('key_decisions', []))} key decision(s)")
+    else:
+        lines.append("- (no milestone bundled)")
+    return "\n".join(lines) + "\n\n"
+
+
+def _render_releases_row(version: str, day: str, bundle: list[dict],
+                         waiver_slugs: list[str], evidence: str | None) -> str:
+    """One append-only RELEASES.md row — the attribution source (`milestones:` membership)."""
+    ms = ", ".join(m["slug"] for m in bundle) if bundle else "none"
+    wv = ", ".join(waiver_slugs) if waiver_slugs else "none"
+    return (f"## {version} — {day}\n"
+            f"milestones: {ms}\n"
+            f"waivers: {wv}\n"
+            f"evidence: {evidence or 'recorded by add.py release'}\n\n")
+
+
+def cmd_release(args: argparse.Namespace) -> None:
+    """GUARDED, record-only: cut a version. Enforce the 4-code readiness floor, then RECORD by
+    prepending CHANGELOG.md + an append-only RELEASES.md row (whose `milestones:` line attributes
+    the bundle). The engine RECORDS; it NEVER tags / publishes / deploys / bumps a version source /
+    writes state.json. Validate-before-write: a reject leaves both files + state.json byte-unchanged.
+    A failed second write rolls back the first (release_write_failed)."""
+    root = find_root()
+    if root is None:                 # frozen contract: fail-closed with a no_project signal
+        _die("no_project: no .add/ project found. Run `add.py init` first.")
+    state = load_state(root)
+    d = release_data(root, state)
+    forced = getattr(args, "force", False)
+    disclosed = getattr(args, "with_waivers", False)
+
+    # ── FLOOR — all checks BEFORE any write (validate-before-write) ──────────────────────────
+    if d["blockers"]:                # the UN-FORCEABLE reject — security is never shipped
+        _die("release_security_open: an open HARD-STOP blocks the cut — a security finding is "
+             "never shipped. Resolve it (a change request back to Specify) before releasing. "
+             "--force does NOT override this.")
+    if not forced and _build_in_flight(state):
+        _die("release_tests_red: a build is in flight without a recorded green gate — finish and "
+             "gate it first, or pass --force to override.")
+    bundle = _releasable(root, state)
+    if not forced and not bundle:
+        _die("release_no_closed_milestone: nothing closed-and-unreleased to bundle — the cut "
+             "would be a no-op. Close a milestone first, or pass --force to override.")
+    if not forced and d["waivers"] and not disclosed:
+        _die("release_undisclosed_waiver: a RISK-ACCEPTED waiver rides into this release — pass "
+             "--with-waivers to disclose it in the notes, or --force to override.")
+
+    # ── RECORD — build both contents in memory, then write CHANGELOG, then RELEASES (commit) ──
+    day = date.today().isoformat()
+    changed_by_slug = {c["milestone"]: c for c in d["changed"]}
+    waiver_slugs = [w["slug"] for w in d["waivers"]] if disclosed else []
+    changelog_path = root.parent / "CHANGELOG.md"
+    releases_path = _releases_path(root)
+    cl_before = changelog_path.read_text(encoding="utf-8") if changelog_path.exists() else None
+    rel_before = releases_path.read_text(encoding="utf-8") if releases_path.exists() else ""
+    new_cl = _prepend_block(cl_before or "", "# Changelog",
+                            _render_changelog_block(args.version, day, bundle, changed_by_slug))
+    new_rel = _prepend_block(rel_before, "# Releases",
+                             _render_releases_row(args.version, day, bundle, waiver_slugs,
+                                                  getattr(args, "evidence", None)))
+    _atomic_write(changelog_path, new_cl)
+    try:
+        _atomic_write(releases_path, new_rel)         # the attribution commit point
+    except OSError as e:
+        if cl_before is not None:                     # ROLLBACK (design-for-failure)
+            _atomic_write(changelog_path, cl_before)
+        else:
+            try:
+                changelog_path.unlink()
+            except OSError:
+                pass
+        _die(f"release_write_failed: the ledger write failed ({e}); CHANGELOG was rolled back — "
+             "nothing was recorded. Retry the release.")
+
+    # NO save_state — attribution lives in RELEASES.md (the cue re-reads it), never state.json
+    ms = ", ".join(m["slug"] for m in bundle) if bundle else "none"
+    print(f"released {args.version} — recorded {len(bundle)} milestone(s): {ms}")
+    print("  CHANGELOG.md + RELEASES.md updated (project root). The engine records; "
+          "you run the tag / publish / deploy.")
+    if forced:
+        print("  (--force: forceable floor rejects were bypassed — release_security_open is never bypassable)")
+    print(_next_footer(root, state))
+
+
 def cmd_deltas(args: argparse.Namespace) -> None:
     """Read-only: report all open lessons learned grouped by competency.
 
@@ -4394,6 +4731,26 @@ def build_parser() -> argparse.ArgumentParser:
     pgr.add_argument("--plain", action="store_true", help="ASCII/pipe-safe text (output is plain by default)")
     pgr.set_defaults(func=cmd_graduation_report)
 
+    prr = sub.add_parser("release-report",
+                         help="read-only: gather the release inventory (releasable milestones · "
+                              "changed/RETROs · waivers · HARD-STOP blockers · monitors) for a "
+                              "release cut — gathers, never judges")
+    prr.add_argument("--json", action="store_true", help="emit the frozen JSON facts interface")
+    prr.add_argument("--plain", action="store_true", help="ASCII/pipe-safe text (output is plain by default)")
+    prr.set_defaults(func=cmd_release_report)
+
+    prl = sub.add_parser("release",
+                         help="guarded, record-only: cut a version — enforce the readiness floor, "
+                              "then prepend CHANGELOG.md + an append-only RELEASES.md row (the "
+                              "engine records; you tag/publish). Security HARD-STOP is un-forceable")
+    prl.add_argument("version", help="the version string to cut (free-form: semver / calver / any)")
+    prl.add_argument("--force", action="store_true",
+                     help="override the forceable floor rejects (NEVER release_security_open)")
+    prl.add_argument("--with-waivers", action="store_true", dest="with_waivers",
+                     help="disclose riding RISK-ACCEPTED waivers (records them on the ledger row)")
+    prl.add_argument("--evidence", default=None, help="the RELEASES.md row's evidence line")
+    prl.set_defaults(func=cmd_release)
+
     pau = sub.add_parser("audit",
                          help="read-only: verify recorded human decision points left well-formed records "
                               "(exit 1 on findings — the CI enforcement gate)")

package/tooling/templates/kit.sample.css

@@ -0,0 +1,53 @@
+/* kit.sample.css — one class per catalog.sample.json component (the reusable kit).
+   Every visual value resolves a var(--…) from tokens.sample.css — no literals here, so
+   a token flip in tokens.sample.css restyles every screen that composes from this kit.
+   Screens use these classes and style nothing inline. */
+
+/* Screen — the root viewport container */
+.screen {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  min-height: 100vh;
+  gap: var(--semantic-space-inset-md);
+  padding: var(--semantic-space-inset-md);
+  background: var(--semantic-color-surface);
+  font-family: var(--primitive-font-family-sans);
+}
+
+/* Card — a surface that groups related content */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--semantic-space-inset-sm);
+  width: 100%;
+  max-width: 360px;
+  padding: var(--semantic-space-inset-md);
+  background: var(--semantic-color-surface);
+  border-radius: var(--semantic-space-inset-sm);
+}
+
+/* Text — a run of styled text */
+.text {
+  margin: 0;
+  line-height: 1.5;
+  color: var(--semantic-color-text);
+  font-family: var(--primitive-font-family-sans);
+}
+.text--bold { font-weight: var(--primitive-font-weight-bold); }
+.text--regular { font-weight: var(--primitive-font-weight-regular); }
+
+/* Button — a primary call-to-action */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--semantic-space-inset-sm) var(--semantic-space-inset-md);
+  border: 0;
+  border-radius: var(--semantic-space-inset-sm);
+  background: var(--semantic-color-accent);
+  color: var(--semantic-color-surface);
+  font-family: var(--primitive-font-family-sans);
+  font-weight: var(--primitive-font-weight-bold);
+  cursor: pointer;
+}

package/tooling/templates/settings.sample.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<!-- settings.sample.html — a SECOND screen that proves REUSE. It composes from the SAME
+     kit classes (screen/card/text/button) and links the SAME tokens.sample.css +
+     kit.sample.css as welcome. It redefines nothing — no per-screen stylesheet, no inline
+     styles — so a single semantic-token flip in tokens.sample.css re-renders BOTH screens
+     identically. This is consistency by construction. -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Settings — design mock</title>
+  <link rel="stylesheet" href="tokens.sample.css">
+  <link rel="stylesheet" href="kit.sample.css">
+</head>
+<body>
+  <!-- reuses the welcome kit: Screen > Card > {Text, Text, Button} -->
+  <main class="screen">
+    <section class="card">
+      <h1 class="text text--bold">Settings</h1>
+      <p class="text text--regular">Manage your workspace preferences.</p>
+      <button class="button" type="button">Save changes</button>
+    </section>
+  </main>
+</body>
+</html>

package/tooling/templates/tokens.sample.css

@@ -0,0 +1,23 @@
+/* tokens.sample.css — tokens.sample.json resolved to CSS custom properties.
+   The SINGLE source of token values. Literals live ONLY here; the kit and the
+   screens reference var(--semantic-*). Flip one --semantic-* line below and EVERY
+   screen that links this file re-renders the same way. */
+:root {
+  /* primitive — raw values (the only literals in the whole sample) */
+  --primitive-color-blue-500: #3B82F6;
+  --primitive-color-slate-900: #0F172A;
+  --primitive-color-white: #FFFFFF;
+  --primitive-space-2: 8px;
+  --primitive-space-4: 16px;
+  --primitive-font-family-sans: "Inter", system-ui, sans-serif;
+  --primitive-font-weight-regular: 400;
+  --primitive-font-weight-bold: 700;
+
+  /* semantic — alias the primitives; THIS is the layer screens bind to.
+     Repoint one of these to re-theme every screen at once. */
+  --semantic-color-accent: var(--primitive-color-blue-500);
+  --semantic-color-text: var(--primitive-color-slate-900);
+  --semantic-color-surface: var(--primitive-color-white);
+  --semantic-space-inset-sm: var(--primitive-space-2);
+  --semantic-space-inset-md: var(--primitive-space-4);
+}

package/tooling/templates/udd-wireframe.md

@@ -0,0 +1,118 @@
+# UDD wireframe + HTML mock — make the layout visible before build
+
+`udd-tokens.md` says what a UI is *made of*; `udd-catalog.md` says what it is *built
+from*. Both are abstract JSON. This doc closes the last gap design.md names: turn a
+prototype tree into a **real, captured screen the human confirms BEFORE build** — so
+the build matches the expected layout instead of discovering it.
+
+Two stages, low-fi → hi-fi:
+
+- **Stage A — wireframe**: a fast, low-fi *structural* map. No styling.
+- **Stage B — HTML mock**: a self-contained screen the human (or a headless tool)
+  actually renders and screenshots. The image is the design-confirm evidence.
+
+The engine never renders. This is a recommendation + a worked sample, tool-agnostic
+(consistent with `udd-catalog.md`'s render recipe). A worked pair ships beside it —
+`welcome.sample.html` + `settings.sample.html` — that you can open in any browser.
+
+## Stage A — wireframe (low-fi, structural)
+
+A **wireframe** is a low-fidelity, *structural* map of one screen — regions and the
+component **slots** inside them — derived directly from the prototype tree, **before**
+any color, type scale, or spacing is decided. It answers "what goes where", not "what
+it looks like".
+
+Derive it mechanically from `prototypes/<name>.json`: each container element is a
+region, each leaf element is a slot, the tree's nesting is the layout nesting. Keep it
+in plain text or boxes — the point is speed and a shared structural picture, not paint.
+
+Worked example: `wireframe.sample.txt` is the Stage-A map of the welcome screen
+(`Screen > Card > {Text, Text, Button}`), with each slot mapped 1:1 to its prototype
+element. No colors, no pixel values — those arrive in Stage B.
+
+## Stage B — HTML mock (hi-fi, self-contained, screenshot-able)
+
+The mock is a real screen built from the design foundation in **four moves**:
+
+1. **Resolve `tokens.json`'s `semantic` layer → CSS custom properties.** Each
+   `{semantic.dotted.path}` alias becomes a `--semantic-dotted-path` variable in a
+   `:root` block. This file is the single source of token values — see
+   `tokens.sample.css`.
+2. **One kit class per `catalog.json` component.** Each component (Screen, Card, Text,
+   Button, …) gets exactly one CSS class whose every visual value is a `var(--…)` from
+   step 1 — never a literal. This is the reusable **kit** — see `kit.sample.css`.
+3. **Compose the prototype tree into HTML using the kit classes.** Walk
+   `prototypes/<name>.json`: each element becomes an HTML node carrying its
+   component's kit class; nesting follows `children`. Style nothing inline.
+4. **Populate with mock data.** Fill the `Text`/`Button` content from the prototype's
+   props (or representative stand-ins). The result is a **self-contained** screen —
+   *no network*: it links only local sibling files — that opens offline and a
+   **headless** tool can **screenshot** directly (Playwright, `html2image`,
+   an agent browser, or a SaaS renderer — pick one; the engine never renders).
+
+`welcome.sample.html` is the worked Stage-B mock of `prototype.sample.json`.
+
+## Fast path — render via json-render (for JS-ecosystem projects)
+
+Your `prototypes/<name>.json` is already a **json-render `Spec`** — the exact schema
+`udd-catalog.md` pins. If your project renders json-render (React, Vue, Svelte, Solid,
+React Native, …) you can skip the hand-authored kit and render the prototype through
+your *real* catalog, so the mock **is** the product and cannot drift from it:
+
+- **Render** — feed `prototype.json` into your `defineCatalog(…)` (see `udd-catalog.md`'s
+  "Render recipe"), or use a pre-built catalog such as `@json-render/shadcn` (36
+  shadcn/ui components) — no hand-written components for those stacks.
+- **Capture** — `@json-render/image` renders a `Spec` straight to **PNG / SVG** (Satori,
+  no browser), a deterministic captured image with no headless-screenshot step. That
+  image is the same design-confirm evidence (see "Capture is evidence").
+
+Trade-off — this is the *fast path*, not the floor. json-render needs the JS/npm
+toolchain + a renderer package, so it does NOT cover a native (SwiftUI / Flutter / …)
+project, and it has **no wireframe mode** (Stage A stays a separate, renderer-agnostic
+structural artifact). When there is no toolchain, or the stack is not JS, the
+self-contained HTML + CSS mock above is the universal default.
+
+## Reuse & consistency (by construction)
+
+Screens compose **only** from the shared kit + token vars — never hand-styled per
+screen. Because every screen links the *same* `tokens.sample.css` + `kit.sample.css`,
+a single **semantic-token flip** (one line in `tokens.sample.css`) re-renders **every**
+screen the same way. Reuse before invent: pull an existing kit class first; add a new
+one only for a genuine new `catalog.json` component.
+
+`settings.sample.html` is a SECOND screen that **reuses** the welcome kit classes
+(screen/card/text/button) without redefining them — proving the consistency: flip
+`--semantic-color-surface` once and both screens change together.
+
+## Capture is evidence
+
+The screenshot of a Stage-B mock is **design-confirm evidence** — the human-facing
+proof of beat 4 in `design.md`. Captures live at **`.add/design/captures/<name>.<ext>`**
+(one per prototype) and are **attached or mentioned in the feature's `TASK.md`**
+(alongside the §6 evidence), so the screen the human approved stays traceable from the
+task that builds it. The recommended default capture engine for a json-render project is
+**`@json-render/image`** (Satori → PNG/SVG, no browser); otherwise capture the
+self-contained HTML mock headless. The engine never produces this image — it only
+MEASURES presence (`add.py check` raises a never-red `missing_capture` WARN for a
+prototype with no capture); the capture recipe is a recommendation, not an engine feature.
+
+## Binds (read-only)
+
+This recipe **consumes** the UDD contracts and never reshapes them:
+
+- `tokens.json` — the semantic layer is the source of the CSS variables (unchanged).
+- `catalog.json` — its component set is the source of the kit classes (unchanged).
+- `prototypes/<name>.json` — the json-render tree is the structure both stages walk
+  (unchanged; the frozen data contract is read-only — a change there is a separate
+  change-request).
+
+The mock (`*.sample.html`) is the human-facing *visible* view; the frozen
+`prototypes/<name>.json` tree is the *machine-checkable* record. They are two views of
+one screen.
+
+## Ships byte-identical
+
+`udd-wireframe.md` and its five sample files ship **byte-identical** in both template
+trees (canonical `tooling/templates/` and the `_bundled` mirror) — enforced by
+`test_bundle_parity`. A file present in one tree but missing from the other is a
+`parity_break`.

package/tooling/templates/welcome.sample.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<!-- welcome.sample.html — Stage-B HTML mock of prototype.sample.json (the welcome screen).
+     Self-contained (no network): links only the local shared stylesheets. Composes ONLY
+     from the kit classes in kit.sample.css and styles nothing inline. A headless tool
+     screenshots this file directly; that image is the design-confirm evidence
+     (see udd-wireframe.md, "Capture is evidence"). -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Welcome — design mock</title>
+  <link rel="stylesheet" href="tokens.sample.css">
+  <link rel="stylesheet" href="kit.sample.css">
+</head>
+<body>
+  <!-- prototype tree: Screen > welcome-card(Card) > {title(Text), subtitle(Text), cta(Button)} -->
+  <main class="screen">
+    <section class="card">
+      <h1 class="text text--bold">Welcome to ADD</h1>
+      <p class="text text--regular">Spec-and-tests-first, render-ready.</p>
+      <button class="button" type="button">Get started</button>
+    </section>
+  </main>
+</body>
+</html>

package/tooling/templates/wireframe.sample.txt

@@ -0,0 +1,27 @@
+WIREFRAME — welcome screen (Stage A · low-fi · pre-styling)
+derived from: prototypes/welcome.json  (Screen > Card > Text, Text, Button)
+
++--------------------------------------------------+
+|  SCREEN   [region: full viewport]                |
+|                                                  |
+|     +--------------------------------------+     |
+|     |  CARD   [region: centered group]     |     |
+|     |                                      |     |
+|     |   [ Text slot ]    title  (bold)     |     |
+|     |   [ Text slot ]    subtitle          |     |
+|     |   [ Button slot ]  primary CTA       |     |
+|     |                                      |     |
+|     +--------------------------------------+     |
+|                                                  |
++--------------------------------------------------+
+
+slots map one-to-one to prototype elements:
+  SCREEN  ->  Screen   (root)
+  CARD    ->  Card     (welcome-card)
+  Text    ->  Text     (title, subtitle)
+  Button  ->  Button   (cta)
+
+notes:
+  - structure only — no color, no type scale, no spacing values yet
+  - styling arrives in Stage B (kit.sample.css bound to tokens.sample.css)
+  - confirm the STRUCTURE here is right before investing in the hi-fi mock