feat: add release candidate bundles

Author: solomonneas

CHANGELOG.md

@@ -77,6 +77,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `brigade work review init/plan/run/runs/show/import-findings/findings/finding-show/closeout` for explicit local multi-harness code review producers, receipts, normalized findings, imported finding resolution, local closeout records, and `code-review` work inbox imports without automatic fixes or remote mutation.
 - `brigade work verify plan/run/runs/show` and `brigade work closeout <session-id-or-latest>` for local verification receipts and work closeout records that collect task acceptance, test command results, scanner sweep status, code review closeout state, handoff draft status, and session evidence without CI or remote mutation.
 - `brigade release plan/doctor/run/runs/show` for local release-readiness receipts that collect work closeout, verification, review closeout, scanner sweep, security, handoff, content-guard, docs, changelog, roadmap, and git-state evidence without pushing, tagging, or mutating remotes.
+- `brigade release candidate plan/build/list/show/archive` for local release candidate bundles with readiness evidence, release notes drafts, manual-only publish plans, changed file lists, blockers, warnings, and content-guard summaries without pushing, tagging, or creating releases.
 - `brigade work backup init/status/doctor/import-issues` for read-only local backup health summaries and `backup-health` inbox imports.
 - Backup health checks for stale snapshots, failed or stale checks, failed or stale prunes, missing summaries, overdue restore rehearsals, and unsafe private summary fields.
 - `brigade tools init/list/show/search/describe/contracts/call plan/call queue/call list/call show/call approve/call reject/call hold/call run/runtime/policy/plan/apply/doctor/import-issues`, plus `brigade tools run list/show/latest/replay` and `brigade tools checkpoint list/show/approve/reject/resume`, for portable tool, slash command, skill, superpower, script, and MCP catalog discovery plus explicit projection writes, read-only call planning, local call approval review, explicit approved script and local MCP execution, run history inspection, replay review, checkpointed resume, runtime supervision, and host-local execution policy.

README.md

@@ -160,6 +160,11 @@ brigade release doctor
 brigade release run
 brigade release runs
 brigade release show <run-id>
+brigade release candidate plan
+brigade release candidate build
+brigade release candidate list
+brigade release candidate show <candidate-id>
+brigade release candidate archive <candidate-id>
 brigade handoff doctor
 brigade handoff lint
 brigade handoff list
@@ -542,10 +547,14 @@ Release readiness commands:
 - `brigade release doctor` runs local publish checks such as content-guard when available and reports blockers.
 - `brigade release run` writes a release-readiness receipt under `.brigade/release/runs/`.
 - `brigade release runs` and `brigade release show <run-id>` inspect local release receipts.
+- `brigade release candidate plan` previews a local release candidate bundle.
+- `brigade release candidate build` writes a local bundle under `.brigade/release/candidates/`.
+- `brigade release candidate list`, `show`, and `archive` inspect or archive local candidate bundles.
 
 Release readiness is a local publish gate. It reviews latest work closeout, verification, code review closeout, scanner sweep state, security health, handoff draft health, content-guard results, git state, and docs/changelog/roadmap touch warnings. It never pushes, tags, creates releases, comments remotely, or mutates remotes.
 
 See [`docs/release-readiness.md`](docs/release-readiness.md) for the receipt contract and local-only boundary.
+See [`docs/release-candidates.md`](docs/release-candidates.md) for the candidate bundle files and manual-only publish plan.
 
 ### Memory And Bootstrap Health
 

ROADMAP.md

@@ -44,6 +44,7 @@ Goal: make Brigade a safe target for local automations that discover useful work
 - Close out imported review findings against downstream work. Status: implemented with `brigade work review findings`, `finding-show`, `closeout`, source-fingerprint re-review detection, task review evidence, and daily-loop warnings for unclosed review runs.
 - Close out completed work against local verification evidence. Status: implemented with `brigade work verify plan/run/runs/show` and `brigade work closeout`, collecting task acceptance, test command receipts, scanner sweep state, code review closeout state, handoff draft status, and session evidence without CI or remote mutation.
 - Check local release readiness before publish operations. Status: implemented with `brigade release plan`, `doctor`, `run`, `runs`, and `show`, collecting work closeout, verification, review, scanner, security, handoff, content-guard, docs, changelog, roadmap, and git-state evidence without pushing, tagging, or mutating remotes.
+- Build local release candidate packets before manual publish steps. Status: implemented with `brigade release candidate plan/build/list/show/archive`, local candidate bundles, evidence JSON, release notes drafts, manual-only publish plans, candidate health warnings, and no remote mutation.
 
 ## Later Phase: Chat Surface Scanners
 

docs/release-candidates.md

@@ -0,0 +1,42 @@
+# Release Candidates
+
+`brigade release candidate` turns local release readiness evidence into a reviewable candidate packet. It is designed for the step after `brigade release run` and before any manual publish action.
+
+## Commands
+
+```bash
+brigade release candidate plan
+brigade release candidate build
+brigade release candidate list
+brigade release candidate show <candidate-id>
+brigade release candidate archive <candidate-id>
+```
+
+`plan` previews the candidate evidence without writing files.
+
+`build` writes a bundle under:
+
+```text
+.brigade/release/candidates/
+```
+
+`list` and `show` inspect bundles. `archive` moves a reviewed candidate into the local archive so it no longer appears as the latest candidate.
+
+## Bundle Files
+
+Each candidate contains:
+
+- `RELEASE_CANDIDATE.md`, a human-readable summary of readiness, blockers, warnings, and changed files.
+- `RELEASE_NOTES_DRAFT.md`, an editable draft inferred from `CHANGELOG.md`, commit subjects since the base ref, and touched docs. Uncertain sections are marked `review-needed`.
+- `PUBLISH_PLAN.md`, a manual checklist for verification, closeout, release doctor, content guard, tag, push, and release creation. Remote-mutating commands are marked manual-only and are not run.
+- `EVIDENCE.json`, stable wrapper-friendly evidence for the release readiness receipt, work closeout, verification receipt, code review closeout, scanner sweep state, security state, handoff state, git state, changed files, docs touch status, content-guard summaries, blockers, warnings, and suggested next commands.
+
+## Candidate Health
+
+`brigade release doctor` warns when the latest candidate is stale, references missing receipts, was built from blocked readiness, or no longer matches the current git HEAD.
+
+These are warnings because candidate bundles are review artifacts. They do not replace release readiness checks, verification, code review closeout, or content guard.
+
+## Boundary
+
+Release candidate commands are local and explicit. Brigade does not push, tag, create GitHub releases, mutate pull requests, edit changelogs outside the candidate bundle, upload artifacts, approve content-guard findings, start daemons, install schedulers, or store secrets.

docs/release-readiness.md

@@ -10,6 +10,11 @@ brigade release doctor
 brigade release run
 brigade release runs
 brigade release show <run-id>
+brigade release candidate plan
+brigade release candidate build
+brigade release candidate list
+brigade release candidate show <candidate-id>
+brigade release candidate archive <candidate-id>
 ```
 
 `plan` gathers local evidence and reports readiness without running publish checks or writing a receipt.
@@ -24,6 +29,8 @@ brigade release show <run-id>
 
 `runs` and `show` inspect those receipts.
 
+`release candidate` commands turn readiness receipts into local candidate bundles under `.brigade/release/candidates/`. They do not push, tag, create releases, or mutate remotes. See [`release-candidates.md`](release-candidates.md).
+
 ## Evidence
 
 Release readiness includes:
@@ -43,7 +50,7 @@ Release readiness includes:
 
 Blockers include missing or blocked work closeout, missing or failed verification, unclosed review runs, unresolved code-review findings, unresolved scanner sweep issues, open security issues, stale or invalid handoff draft state, content-guard failures, and dirty tracked files.
 
-Warnings include missing content-guard and docs/changelog/roadmap touch expectations. Warnings do not make the receipt blocked by themselves.
+Warnings include missing content-guard, docs/changelog/roadmap touch expectations, stale release candidate bundles, missing candidate receipt references, changed git HEAD since candidate build, and candidates built from blocked readiness. Warnings do not make the receipt blocked by themselves.
 
 ## Boundary
 

src/brigade/cli.py

@@ -132,6 +132,29 @@ def _build_parser() -> argparse.ArgumentParser:
     p_release_show.add_argument("run_id", help="Run id, unique prefix, or latest.")
     p_release_show.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
     p_release_show.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_release_candidate = release_sub.add_parser("candidate", help="Build and inspect local release candidate bundles.")
+    release_candidate_sub = p_release_candidate.add_subparsers(dest="release_candidate_command", metavar="<candidate-command>")
+    release_candidate_sub.required = True
+    p_release_candidate_plan = release_candidate_sub.add_parser("plan", help="Plan a release candidate bundle without writing it.")
+    p_release_candidate_plan.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
+    p_release_candidate_plan.add_argument("--base-ref", default="origin/main", help="Base ref for changed files and release notes.")
+    p_release_candidate_plan.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_release_candidate_build = release_candidate_sub.add_parser("build", help="Build a local release candidate bundle.")
+    p_release_candidate_build.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
+    p_release_candidate_build.add_argument("--base-ref", default="origin/main", help="Base ref for changed files and release notes.")
+    p_release_candidate_build.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_release_candidate_list = release_candidate_sub.add_parser("list", help="List local release candidate bundles.")
+    p_release_candidate_list.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
+    p_release_candidate_list.add_argument("--limit", type=int, default=20, help="Maximum candidates to list.")
+    p_release_candidate_list.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_release_candidate_show = release_candidate_sub.add_parser("show", help="Show one local release candidate bundle.")
+    p_release_candidate_show.add_argument("candidate_id", help="Candidate id, unique prefix, or latest.")
+    p_release_candidate_show.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
+    p_release_candidate_show.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_release_candidate_archive = release_candidate_sub.add_parser("archive", help="Archive one local release candidate bundle.")
+    p_release_candidate_archive.add_argument("candidate_id", help="Candidate id, unique prefix, or latest.")
+    p_release_candidate_archive.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to update.")
+    p_release_candidate_archive.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
 
     # handoff
     p_handoff = sub.add_parser("handoff", help="Inspect memory handoff inbox health.")
@@ -1185,6 +1208,19 @@ def main(argv=None) -> int:
             return release_cmd.runs(target=args.target, limit=args.limit, json_output=args.json)
         if args.release_command == "show":
             return release_cmd.show(target=args.target, run_id=args.run_id, json_output=args.json)
+        if args.release_command == "candidate":
+            if args.release_candidate_command == "plan":
+                return release_cmd.candidate_plan(target=args.target, base_ref=args.base_ref, json_output=args.json)
+            if args.release_candidate_command == "build":
+                return release_cmd.candidate_build(target=args.target, base_ref=args.base_ref, json_output=args.json)
+            if args.release_candidate_command == "list":
+                return release_cmd.candidate_list(target=args.target, limit=args.limit, json_output=args.json)
+            if args.release_candidate_command == "show":
+                return release_cmd.candidate_show(target=args.target, candidate_id=args.candidate_id, json_output=args.json)
+            if args.release_candidate_command == "archive":
+                return release_cmd.candidate_archive(target=args.target, candidate_id=args.candidate_id, json_output=args.json)
+            parser.error(f"unknown release candidate command: {args.release_candidate_command}")
+            return 2
         parser.error(f"unknown release command: {args.release_command}")
         return 2
     if cmd == "handoff":