docs/release: Record release distribution contract (D4P2MF)

.agentplane/tasks/202605011625-D4P2MF/README.md

@@ -0,0 +1,126 @@
+---
+id: "202605011625-D4P2MF"
+title: "Record release distribution contract"
+status: "DOING"
+priority: "high"
+owner: "DOCS"
+revision: 5
+origin:
+  system: "manual"
+depends_on: []
+tags:
+  - "docs"
+  - "release"
+verify:
+  - "agentplane doctor"
+  - "node .agentplane/policy/check-routing.mjs"
+plan_approval:
+  state: "approved"
+  updated_at: "2026-05-01T16:28:08.565Z"
+  updated_by: "ORCHESTRATOR"
+  note: null
+verification:
+  state: "ok"
+  updated_at: "2026-05-01T16:40:54.828Z"
+  updated_by: "DOCS"
+  note: "Docs contract verified: node .agentplane/policy/check-routing.mjs passed; agentplane doctor passed with zero errors and zero warnings."
+commit: null
+comments:
+  -
+    author: "DOCS"
+    body: "Start: document the release distribution contract and acceptance gates before downstream release automation changes."
+events:
+  -
+    type: "status"
+    at: "2026-05-01T16:38:50.138Z"
+    author: "DOCS"
+    from: "TODO"
+    to: "DOING"
+    note: "Start: document the release distribution contract and acceptance gates before downstream release automation changes."
+  -
+    type: "verify"
+    at: "2026-05-01T16:40:54.828Z"
+    author: "DOCS"
+    state: "ok"
+    note: "Docs contract verified: node .agentplane/policy/check-routing.mjs passed; agentplane doctor passed with zero errors and zero warnings."
+doc_version: 3
+doc_updated_at: "2026-05-01T16:40:54.842Z"
+doc_updated_by: "DOCS"
+description: "Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm."
+sections:
+  Summary: |-
+    Record release distribution contract
+
+    Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+  Scope: |-
+    - In scope: Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+    - Out of scope: unrelated refactors not required for "Record release distribution contract".
+  Plan: "Plan: define a multi-channel release distribution contract for npm, GitHub Release assets, Homebrew tap, Scoop bucket, GHCR image, and setup-agentplane. Classify channels as blocking or follow-up, list required secrets, evidence artifacts, recovery behavior, and next-release acceptance criteria. Verification: policy routing and doctor."
+  Verify Steps: |-
+    1. Review the requested outcome for "Record release distribution contract". Expected: the visible result matches ## Summary and stays inside approved scope.
+    2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched behavior.
+    3. Compare the final result against ## Scope and record any residual follow-up in ## Findings. Expected: open edges are explicit rather than implicit.
+  Verification: |-
+    <!-- BEGIN VERIFICATION RESULTS -->
+    ### 2026-05-01T16:40:54.828Z — VERIFY — ok
+
+    By: DOCS
+
+    Note: Docs contract verified: node .agentplane/policy/check-routing.mjs passed; agentplane doctor passed with zero errors and zero warnings.
+
+    VerifyStepsRef: doc_version=3, doc_updated_at=2026-05-01T16:38:50.138Z, excerpt_hash=sha256:8803f7065a9c72155f5858bc81b6a88e3b18e8722995b84a1e05a9be612812c1
+
+    <!-- END VERIFICATION RESULTS -->
+  Rollback Plan: |-
+    - Revert task-related commit(s).
+    - Re-run required checks to confirm rollback safety.
+  Findings: |-
+    - Observation: Release distribution contract now defines manifest, installer assets, blocking channels, credentials-gated skips, module evidence files, and recovery behavior.
+      Impact: Downstream release automation can derive package manager, GHCR, and setup-action publication from one documented source instead of hidden workflow shell state.
+      Resolution: Proceed to implement release distribution asset and manifest generation against this contract.
+id_source: "generated"
+---
+## Summary
+
+Record release distribution contract
+
+Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+
+## Scope
+
+- In scope: Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+- Out of scope: unrelated refactors not required for "Record release distribution contract".
+
+## Plan
+
+Plan: define a multi-channel release distribution contract for npm, GitHub Release assets, Homebrew tap, Scoop bucket, GHCR image, and setup-agentplane. Classify channels as blocking or follow-up, list required secrets, evidence artifacts, recovery behavior, and next-release acceptance criteria. Verification: policy routing and doctor.
+
+## Verify Steps
+
+1. Review the requested outcome for "Record release distribution contract". Expected: the visible result matches ## Summary and stays inside approved scope.
+2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched behavior.
+3. Compare the final result against ## Scope and record any residual follow-up in ## Findings. Expected: open edges are explicit rather than implicit.
+
+## Verification
+
+<!-- BEGIN VERIFICATION RESULTS -->
+### 2026-05-01T16:40:54.828Z — VERIFY — ok
+
+By: DOCS
+
+Note: Docs contract verified: node .agentplane/policy/check-routing.mjs passed; agentplane doctor passed with zero errors and zero warnings.
+
+VerifyStepsRef: doc_version=3, doc_updated_at=2026-05-01T16:38:50.138Z, excerpt_hash=sha256:8803f7065a9c72155f5858bc81b6a88e3b18e8722995b84a1e05a9be612812c1
+
+<!-- END VERIFICATION RESULTS -->
+
+## Rollback Plan
+
+- Revert task-related commit(s).
+- Re-run required checks to confirm rollback safety.
+
+## Findings
+
+- Observation: Release distribution contract now defines manifest, installer assets, blocking channels, credentials-gated skips, module evidence files, and recovery behavior.
+  Impact: Downstream release automation can derive package manager, GHCR, and setup-action publication from one documented source instead of hidden workflow shell state.
+  Resolution: Proceed to implement release distribution asset and manifest generation against this contract.

.agentplane/tasks/202605011625-D4P2MF/pr/diffstat.txt

@@ -0,0 +1,2 @@
+ docs/developer/release-and-publishing.mdx | 75 +++++++++++++++++++++++++++++++
+ 1 file changed, 75 insertions(+)

.agentplane/tasks/202605011625-D4P2MF/pr/github-body.md

@@ -0,0 +1,34 @@
+## Summary
+
+Record release distribution contract
+
+Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+
+## Scope
+
+- In scope: Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+- Out of scope: unrelated refactors not required for "Record release distribution contract".
+
+## Verification
+
+- State: ok
+- Note: Docs contract verified: node .agentplane/policy/check-routing.mjs passed; agentplane doctor passed with zero errors and zero warnings.
+- Full verification checklist lives in local review.md.
+
+## Handoff Notes
+
+- No handoff notes recorded yet. Use `agentplane pr note ...` to append one.
+
+<details>
+<summary>Raw evidence</summary>
+
+- Updated: 2026-05-01T16:41:31.459Z
+- Branch: task/202605011625-D4P2MF/release-distribution-contract
+- Head: c687d8ba4016
+
+```text
+ docs/developer/release-and-publishing.mdx | 75 +++++++++++++++++++++++++++++++
+ 1 file changed, 75 insertions(+)
+```
+
+</details>

.agentplane/tasks/202605011625-D4P2MF/pr/github-title.txt

@@ -0,0 +1 @@
+docs/release: Record release distribution contract (D4P2MF)

.agentplane/tasks/202605011625-D4P2MF/pr/meta.json

@@ -0,0 +1,14 @@
+{
+  "base": "main",
+  "branch": "task/202605011625-D4P2MF/release-distribution-contract",
+  "created_at": "2026-05-01T16:38:50.202Z",
+  "head_sha": "c687d8ba4016b4f638986ad794a7ac71aa3c6894",
+  "last_verified_at": "2026-05-01T16:40:54.828Z",
+  "last_verified_sha": "3d56cc31a62e08bda955e9e58321ace2c9817182",
+  "schema_version": 1,
+  "task_id": "202605011625-D4P2MF",
+  "updated_at": "2026-05-01T16:41:31.459Z",
+  "verify": {
+    "status": "pass"
+  }
+}

.agentplane/tasks/202605011625-D4P2MF/pr/review.md

@@ -0,0 +1,58 @@
+# PR Review
+
+Created: 2026-05-01T16:38:50.202Z
+Branch: task/202605011625-D4P2MF/release-distribution-contract
+
+## Summary
+
+Record release distribution contract
+
+Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+
+## Scope
+
+- In scope: Define the multi-channel release contract, blocking gates, non-blocking follow-ups, required secrets, and verification evidence for publishing beyond npm.
+- Out of scope: unrelated refactors not required for "Record release distribution contract".
+
+## Verification
+
+### Plan
+
+1. Review the requested outcome for "Record release distribution contract". Expected: the visible result matches ## Summary and stays inside approved scope.
+2. Run the most relevant validation step for this task. Expected: it succeeds without unexpected regressions in touched behavior.
+3. Compare the final result against ## Scope and record any residual follow-up in ## Findings. Expected: open edges are explicit rather than implicit.
+
+### Current Status
+
+- State: ok
+- Note: Docs contract verified: node .agentplane/policy/check-routing.mjs passed; agentplane doctor passed with zero errors and zero warnings.
+
+## Risks
+
+- Risk level: not recorded
+- Breaking change: no
+
+### Rollback
+
+- Revert task-related commit(s).
+- Re-run required checks to confirm rollback safety.
+
+## Handoff Notes
+
+- No handoff notes recorded yet. Use `agentplane pr note ...` to append one.
+
+<!-- BEGIN AUTO SUMMARY -->
+<details>
+<summary>Raw evidence</summary>
+
+- Updated: 2026-05-01T16:41:31.459Z
+- Branch: task/202605011625-D4P2MF/release-distribution-contract
+- Head: c687d8ba4016
+
+```text
+ docs/developer/release-and-publishing.mdx | 75 +++++++++++++++++++++++++++++++
+ 1 file changed, 75 insertions(+)
+```
+
+</details>
+<!-- END AUTO SUMMARY -->

docs/developer/release-and-publishing.mdx

@@ -125,6 +125,65 @@ GitHub workflow `Publish to npm`:
 
 `Pre-publish Checks` workflow remains available as a manual matrix gate (`workflow_dispatch`) for explicit validation runs.
 
+## Distribution contract
+
+The release commit is the source of truth. Every downstream distribution channel must derive its
+version, tag, source URL, checksum, and human-readable status from the same release distribution
+manifest rather than recalculating those values independently.
+
+Required release distribution artifacts:
+
+- `release-distribution.json`: machine-readable summary of the release version, tag, source SHA,
+  npm tarball URLs, npm package status, GitHub Release asset names, external channel status, and
+  recovery hints.
+- `SHA256SUMS`: checksums for generated GitHub Release assets and installer payloads.
+- `install.sh`: POSIX installer entrypoint for users who want a shell install path.
+- `install.ps1`: PowerShell installer entrypoint for Windows users. The script must install a
+  versioned release payload and verify checksums before executing or linking installed files.
+- `agentplane-upgrade.tar.gz`: upgrade bundle consumed by `agentplane upgrade`.
+
+The install scripts are convenience entrypoints, not update sources of truth. Package managers and
+scripts must install an exact release version and must not implement self-update behavior that
+bypasses the hosted release pipeline.
+
+Blocking release channels:
+
+- npm packages: `@agentplaneorg/core`, `@agentplaneorg/recipes`, and `agentplane`
+- GitHub Release tag/body/assets
+- GitHub Release checksum manifest
+- GHCR image for the exact version and commit
+- AgentPlane-owned Homebrew tap update when tap credentials are configured
+- AgentPlane-owned Scoop bucket update when bucket credentials are configured
+- `setup-agentplane` release/update when action repository credentials are configured
+
+Credentials-gated channels must be explicit in the manifest. If a credential is absent, the channel
+must record `skipped_missing_credentials` with the expected secret name and a recovery command. It
+must not fail an otherwise valid npm/GitHub release unless that channel was explicitly marked
+required for the run.
+
+External moderated registries such as `homebrew/core`, winget, Chocolatey, AUR, and nixpkgs are
+follow-up publication targets. They should be opened as PR jobs or manual recovery tasks after the
+release is already published, because their review queues are outside the AgentPlane release SLA.
+
+## Distribution modules
+
+Keep publication modules independent and evidence-backed:
+
+- npm module: publishes packages, runs published-package smoke checks, and records package outcomes.
+- GitHub assets module: creates release assets, checksum manifest, and upload evidence.
+- GHCR module: builds the exact-version image, tags `vX.Y.Z`, commit SHA, and `latest`, then runs a
+  container CLI smoke check.
+- Homebrew tap module: renders `Formula/agentplane.rb` from `release-distribution.json`, verifies
+  the formula in dry-run/check mode, then opens or updates a tap PR when credentials exist.
+- Scoop bucket module: renders `bucket/agentplane.json` from `release-distribution.json`, verifies
+  checksum and URL fields in check mode, then opens or updates a bucket PR when credentials exist.
+- setup action module: updates the `setup-agentplane` release path so CI users can resolve an exact
+  AgentPlane version from the manifest.
+
+Each module must emit a compact JSON evidence file under `.agentplane/.release/publish/`. The final
+`publish-result.json` should reference those module files instead of flattening every channel into
+one shell step.
+
 GitHub workflow `Core CI` also supports `workflow_dispatch` recovery:
 
 - prefer `sha=<release commit>` to validate the exact historical release candidate
@@ -191,6 +250,17 @@ The publish workflow now also writes `publish-result.json` as a separate artifac
 diagnostics can distinguish a completed release from a partially failed publish run without relying
 only on workflow status inference.
 
+For distribution recovery, use the manifest first:
+
+- if npm succeeded but a package-manager channel was skipped, rerun only that channel with the same
+  `release-distribution.json`
+- if GitHub Release assets are missing, regenerate and upload assets for the same tag before running
+  package-manager modules
+- if GHCR publish failed after npm succeeded, rerun the GHCR module against the exact release SHA
+- if a tap or bucket PR already exists, update that PR rather than creating a duplicate
+- if credentials were missing, add the secret and rerun the credentials-gated module; do not bump the
+  release version
+
 ## Local release E2E harness
 
 For a local end-to-end validation of the exact release SHA against the real GitHub `release-ready`
@@ -226,3 +296,8 @@ versions, or release notes for you.
 - verify npm versions for all published packages
 - verify GitHub release body matches `docs/releases/vX.Y.Z.md`
 - verify upgrade bundle artifacts exist in release assets
+- verify `release-distribution.json` matches the published tag and release SHA
+- verify `SHA256SUMS` covers all install and upgrade assets
+- verify GHCR image tags resolve and `agentplane --version` works in the container
+- verify Homebrew tap, Scoop bucket, and setup-action outcomes are either published or explicitly
+  recorded as `skipped_missing_credentials` with recovery instructions