Release Readiness Loop
This page is a retained loop design. Its named release template and prompt are
not currently tracked under .agents/tasks; restore and review them before
attempting a release loop.
Overview
The release readiness loop validates that the project is ready to ship. It runs build, type-check, and the full test suite; checks version bump, changelog, and release hygiene; auto-fixes the blockers it can (version, changelog, lock file); and produces an explicit recommendation.
Template: prd-release.template.json
Prompt: PROMPT_release.md
Stories: 6 (R00-R05)
Slash command: /release-loop-bootstrap [version]
Story Breakdown
| ID | Title | Depends On | Output |
|---|---|---|---|
| R00 | Preflight: lock release scope and target | -- | .ralph/release-scope.md |
| R01 | Build and type-check validation | R00 | .ralph/release-checks.md (Build section) |
| R02 | Test suite validation | R01 | .ralph/release-checks.md (Tests section) |
| R03 | Version, changelog, and hygiene checks | R00 | .ralph/release-checks.md (Hygiene section) |
| R04 | Fix release blockers | R01, R02, R03 | .ralph/release-blockers.md |
| R05 | Final validation and release summary | R04 | .ralph/release-summary.md |
R01, R02, and R03 are all independent of each other after R00. R04 waits for all three.
Flow
Hygiene Checks (R03)
R03 runs six independent checks and records each as PASS / FAIL / SKIP:
| Check | What It Verifies |
|---|---|
VERSION_BUMP | Current version is higher than the last git tag |
CHANGELOG_UPDATED | CHANGELOG.md has an entry for the target version |
NO_TODO_IN_DELTA | No TODO/FIXME/HACK/XXX in files changed since last tag |
UNCOMMITTED_CHANGES | No uncommitted changes to non-.ralph/ files |
LOCK_FILE_SYNC | Lock file committed alongside any package.json changes |
ENV_CONSISTENCY | .env.example contains all keys in the required env config |
What the Loop Auto-Fixes
| Blocker | Auto-Fix Applied |
|---|---|
| Version not bumped | Bumps package.json to target version |
| No changelog entry | Generates entry from git log in Keep-a-Changelog format |
| Lock file out of sync | Runs npm install to regenerate |
All other failures (build errors, test failures, type errors) are documented in .ralph/release-blockers.md for human action -- the loop never changes application logic or test assertions to force a pass.
Release Recommendation
R05 produces an explicit recommendation in .ralph/release-summary.md:
| Status | Meaning |
|---|---|
READY_TO_RELEASE | All must-fix blockers resolved |
BLOCKED | Must-fix blockers remain (listed with exact description) |
RELEASE_WITH_KNOWN_ISSUES | Only nice-to-have items remain |
Quality Gates
- Read
.ralph/intake/current-guidelines.jsonat the start of every story - Do not implement new features or change application logic
- Never fix test failures by modifying test assertions to match wrong behavior
- Every check must be recorded as PASS, FAIL, or SKIP (never left without a status)
- Document all findings before attempting any fix
Artifacts
| File | Written By | Purpose |
|---|---|---|
.ralph/release-scope.md | R00 | Target version, release branch, delta since last tag |
.ralph/release-checks.md | R01, R02, R03 | All check results with PASS/FAIL/SKIP status |
.ralph/release-blockers.md | R04 | Remaining blockers with human action required |
.ralph/release-summary.md | R05 | Final recommendation and metrics |
Run Command
# Bootstrap (from within repo with Ralph as submodule):
/release-loop-bootstrap v1.2.3
# Then run Ralph:
PROMPT_BUILD=.agents/ralph/PROMPT_release.md \
PRD_PATH=.agents/tasks/prd-active.json \
bash .agents/ralph/loop.sh