@pilotspace/add 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.5.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

@@ -121,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/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.
@@ -4113,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.
 
@@ -4425,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)")