Nuke Release
Review's sibling, pointed at the shipping surface instead of a diff (map: references/family-map.md). What breaks a release is rarely deep code — it is the README's install command that no longer works, the version that says 3.2 in one manifest and 3.4 in another, the count in the docs that drifted from the artifact, the debug flag left on. Every one of those is mechanically checkable, so the protocol checks them mechanically and reports SHIP or DON'T SHIP with blockers. Never edits anything.
Arguments
[mode] — light (default) | full | plan (preflight, print, STOP).
[scope] — a subpath (one package of a monorepo) | default: the whole repo.
--ask — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md). --spec — always write the mini fix-spec.
Modes
Tier vocabulary and platform mechanics: references/model-tiers.md.
|
light (default) |
full |
| Checkers (4 charters below) |
worker |
worker |
| Truth charter depth |
install/quickstart/usage claims — the paths a new user walks |
every testable doc claim, nuke-docs style |
| Packaging charter depth |
artifact contents listed and judged |
+ clean-environment install simulated (fresh temp dir, the exact documented commands) |
| Batched skeptic |
session |
top |
| Wave ceiling |
one checker wave + one skeptic pass |
same — release checks converge or they don't; no loops |
Mandates
- Read-only everywhere. Writes only under
.nuke/ and the temp dirs a clean-install simulation uses. No git add / git commit / git stash; no version bumps, no fixes — a release check that edits the release invalidates itself.
- Execute or trace, never eyeball — a claim is verified the nuke-docs way: run it,
test -f it, grep it; destructive/publishing commands (deploy, publish, tag) are traced, never executed.
- Every blocker carries evidence — the failing command output, the mismatched pair of quoted lines, the missing path — verbatim.
- The verdict is binary.
SHIP or DON'T SHIP — <n> blockers; "mostly ready" is not a verdict. Non-blocking findings are listed separately and never soften the verdict line.
Artifacts
run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-release-<slug>/ — fresh per run; on collision append -2, -3, ….
| File |
Role |
plan.md |
Shipping surface inventory, charters, wave, tiers |
checks.md |
Every check with verdict + evidence |
release.md |
Verdict-first report |
fix-spec.md |
Only with --spec or >5 blockers |
Pipeline
Phase 0 preflight (plan → apply) → Phase 1 checker wave (4 × worker, parallel) → Phase 2 skeptic (1, batched) → Phase 3 verdict (STOP)
Phase 0 — Preflight
Read references/preflight.md and follow its plan-then-apply gate. Release specifics: resolve the shipping surface — what a user actually receives and reads: the published artifact's file set (package manifest / plugin manifest / build output), the user-facing docs (README, install/quickstart guides), the declared install paths, the version-bearing files. Resolve the gates table per references/stack-adapters.md. Print the plan block and apply it (gate only with --ask).
Phase 1 — Checker wave (worker, parallel)
Four charters, each returning candidate findings in the family schema (severity + file:line + quoted evidence + trace + proposed fix + refutation attempt), tagged blocker or note:
- Truth — every claim on the new-user path verified by execution or trace (Mandate 2): install commands, quickstart steps, usage examples, requirement statements. Depth per mode.
- Consistency — versions agree across every version-bearing file; counts, names, and lists in docs match the artifact (enumerate both sides, diff them); internal links and cross-references resolve; changelog (if present) mentions the version being shipped.
- Build — the build runs clean from the current checkout AND leaves generated artifacts in sync (build, then
git status --porcelain on generated paths — drift means the commit ships stale artifacts); the declared gates pass; CI config runs the same steps the docs claim.
- Packaging & trust — the artifact contains what the docs promise and nothing embarrassing: missing entries in the manifest's file list, dev leftovers (debug flags, local absolute paths, TODO/FIXME on user-facing surfaces), secrets (grep per the security checklist's vocabulary), license present and matching the docs' claim.
blocker = a new user hits it or trust is damaged (broken install, lying quickstart, version mismatch, secret, missing license). note = worth fixing, survivable (stale badge, tone nit).
Phase 2 — Skeptic (batched)
One batched skeptic (a release wave never exceeds the ≤20-candidate batch rule in references/skeptic-protocol.md) verdicts every candidate separately — re-runs the failing command, re-reads both sides of a mismatch — and may reclassify blocker ↔ note with a written reason. Uncertain after full research → note, never blocker: a release gate must not cry wolf.
Phase 3 — Verdict (STOP)
release.md, first line: SHIP — 0 blockers · <n> notes or DON'T SHIP — <n> blockers. Then blockers (each: evidence + the one-line fix), notes, checks passed count, run stats. --spec or >5 blockers → mini fix-spec per references/fix-spec-template.md (single phase, mechanical Accepts), with the handoff line to nuke-exec. Append the calibration line to .nuke/calibration.log (format in references/preflight.md). STOP — never start fixing.
1---2name: nuke-release3description: Use when a repo, package, or plugin is about to be shipped to users — "nuke release", "is this ready to publish", "release check", "can I ship this" — verifying the things users hit first: docs that tell the truth, install paths that work, versions that agree, a build that passes from a clean checkout, nothing embarrassing in the artifact. Verdict-first, read-only.4---56# Nuke Release78Review's sibling, pointed at the shipping surface instead of a diff (map: references/family-map.md). What breaks a release is rarely deep code — it is the README's install command that no longer works, the version that says 3.2 in one manifest and 3.4 in another, the count in the docs that drifted from the artifact, the debug flag left on. Every one of those is mechanically checkable, so the protocol checks them mechanically and reports **SHIP** or **DON'T SHIP** with blockers. Never edits anything.910## Arguments1112`[mode]` — `light` (default) | `full` | `plan` (preflight, print, STOP).13`[scope]` — a subpath (one package of a monorepo) | default: the whole repo.14`--ask` — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md). `--spec` — always write the mini fix-spec.1516## Modes1718Tier vocabulary and platform mechanics: references/model-tiers.md.1920| | **light** (default) | **full** |21|---|---|---|22| Checkers (4 charters below) | worker | worker |23| Truth charter depth | install/quickstart/usage claims — the paths a new user walks | every testable doc claim, nuke-docs style |24| Packaging charter depth | artifact contents listed and judged | + clean-environment install simulated (fresh temp dir, the exact documented commands) |25| Batched skeptic | session | top |26| Wave ceiling | one checker wave + one skeptic pass | same — release checks converge or they don't; no loops |2728## Mandates29301. **Read-only everywhere.** Writes only under `.nuke/` and the temp dirs a clean-install simulation uses. No `git add` / `git commit` / `git stash`; no version bumps, no fixes — a release check that edits the release invalidates itself.312. **Execute or trace, never eyeball** — a claim is verified the nuke-docs way: run it, `test -f` it, grep it; destructive/publishing commands (deploy, publish, tag) are traced, never executed.323. **Every blocker carries evidence** — the failing command output, the mismatched pair of quoted lines, the missing path — verbatim.334. **The verdict is binary.** `SHIP` or `DON'T SHIP — <n> blockers`; "mostly ready" is not a verdict. Non-blocking findings are listed separately and never soften the verdict line.3435## Artifacts3637`run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-release-<slug>/` — fresh per run; on collision append `-2`, `-3`, ….3839| File | Role |40|---|---|41| `plan.md` | Shipping surface inventory, charters, wave, tiers |42| `checks.md` | Every check with verdict + evidence |43| `release.md` | Verdict-first report |44| `fix-spec.md` | Only with `--spec` or >5 blockers |4546## Pipeline4748```49Phase 0 preflight (plan → apply) → Phase 1 checker wave (4 × worker, parallel) → Phase 2 skeptic (1, batched) → Phase 3 verdict (STOP)50```5152## Phase 0 — Preflight5354Read references/preflight.md and follow its plan-then-apply gate. Release specifics: resolve the **shipping surface** — what a user actually receives and reads: the published artifact's file set (package manifest / plugin manifest / build output), the user-facing docs (README, install/quickstart guides), the declared install paths, the version-bearing files. Resolve the gates table per references/stack-adapters.md. Print the plan block and apply it (gate only with `--ask`).5556## Phase 1 — Checker wave (worker, parallel)5758Four charters, each returning candidate findings in the family schema (severity + file:line + quoted evidence + trace + proposed fix + refutation attempt), tagged `blocker` or `note`:59601. **Truth** — every claim on the new-user path verified by execution or trace (Mandate 2): install commands, quickstart steps, usage examples, requirement statements. Depth per mode.612. **Consistency** — versions agree across every version-bearing file; counts, names, and lists in docs match the artifact (enumerate both sides, diff them); internal links and cross-references resolve; changelog (if present) mentions the version being shipped.623. **Build** — the build runs clean from the current checkout AND leaves generated artifacts in sync (build, then `git status --porcelain` on generated paths — drift means the commit ships stale artifacts); the declared gates pass; CI config runs the same steps the docs claim.634. **Packaging & trust** — the artifact contains what the docs promise and nothing embarrassing: missing entries in the manifest's file list, dev leftovers (debug flags, local absolute paths, TODO/FIXME on user-facing surfaces), secrets (grep per the security checklist's vocabulary), license present and matching the docs' claim.6465`blocker` = a new user hits it or trust is damaged (broken install, lying quickstart, version mismatch, secret, missing license). `note` = worth fixing, survivable (stale badge, tone nit).6667## Phase 2 — Skeptic (batched)6869One batched skeptic (a release wave never exceeds the ≤20-candidate batch rule in references/skeptic-protocol.md) verdicts every candidate separately — re-runs the failing command, re-reads both sides of a mismatch — and may reclassify blocker ↔ note with a written reason. Uncertain after full research → note, never blocker: a release gate must not cry wolf.7071## Phase 3 — Verdict (STOP)7273`release.md`, first line: **`SHIP — 0 blockers · <n> notes`** or **`DON'T SHIP — <n> blockers`**. Then blockers (each: evidence + the one-line fix), notes, checks passed count, run stats. `--spec` or >5 blockers → mini fix-spec per references/fix-spec-template.md (single phase, mechanical Accepts), with the handoff line to **nuke-exec**. Append the calibration line to `.nuke/calibration.log` (format in references/preflight.md). STOP — never start fixing.
b4r7x