release: Add Homebrew tap publication module (TG4GZ4)

.agentplane/tasks/202605011626-TG4GZ4/README.md

@@ -0,0 +1,129 @@
+---
+id: "202605011626-TG4GZ4"
+title: "Add Homebrew tap publication module"
+status: "DOING"
+priority: "high"
+owner: "CODER"
+revision: 5
+origin:
+  system: "manual"
+depends_on:
+  - "202605011626-HXH0R5"
+tags:
+  - "code"
+  - "release"
+verify:
+  - "bun run release:distribution:check"
+  - "bun run workflows:command-check"
+plan_approval:
+  state: "approved"
+  updated_at: "2026-05-01T16:29:08.550Z"
+  updated_by: "ORCHESTRATOR"
+  note: null
+verification:
+  state: "ok"
+  updated_at: "2026-05-01T17:13:07.600Z"
+  updated_by: "CODER"
+  note: "Homebrew tap module verified: release:homebrew:check passed; release:distribution:check passed; workflows:command-check passed; docs:scripts:check passed; publish workflow contract test passed; lint:core passed; targeted Prettier check passed."
+commit: null
+comments:
+  -
+    author: "CODER"
+    body: "Start: add Homebrew tap publication rendering and credentials-gated release workflow evidence from release-distribution.json."
+events:
+  -
+    type: "status"
+    at: "2026-05-01T17:10:15.206Z"
+    author: "CODER"
+    from: "TODO"
+    to: "DOING"
+    note: "Start: add Homebrew tap publication rendering and credentials-gated release workflow evidence from release-distribution.json."
+  -
+    type: "verify"
+    at: "2026-05-01T17:13:07.600Z"
+    author: "CODER"
+    state: "ok"
+    note: "Homebrew tap module verified: release:homebrew:check passed; release:distribution:check passed; workflows:command-check passed; docs:scripts:check passed; publish workflow contract test passed; lint:core passed; targeted Prettier check passed."
+doc_version: 3
+doc_updated_at: "2026-05-01T17:13:07.603Z"
+doc_updated_by: "CODER"
+description: "Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels."
+sections:
+  Summary: |-
+    Add Homebrew tap publication module
+
+    Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+  Scope: |-
+    - In scope: Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+    - Out of scope: unrelated refactors not required for "Add Homebrew tap publication module".
+  Plan: "Plan: add a Homebrew tap publication module that renders Formula/agentplane.rb from release-distribution.json, supports dry-run/check mode, and can open or update a tap PR when credentials are configured. Verification: distribution check and workflow command check."
+  Verify Steps: |-
+    1. Run `bun run release:distribution:check`. Expected: it succeeds and confirms the requested outcome for this task.
+    2. Run `bun run workflows:command-check`. Expected: it succeeds and confirms the requested outcome for this task.
+    3. Review the changed artifact or behavior for the `code` task. Expected: the requested outcome is visible and matches the approved scope.
+    4. Compare the final result against the task summary and touched scope. Expected: remaining follow-up is either resolved or explicit in ## Findings.
+  Verification: |-
+    <!-- BEGIN VERIFICATION RESULTS -->
+    ### 2026-05-01T17:13:07.600Z — VERIFY — ok
+
+    By: CODER
+
+    Note: Homebrew tap module verified: release:homebrew:check passed; release:distribution:check passed; workflows:command-check passed; docs:scripts:check passed; publish workflow contract test passed; lint:core passed; targeted Prettier check passed.
+
+    VerifyStepsRef: doc_version=3, doc_updated_at=2026-05-01T17:10:15.206Z, excerpt_hash=sha256:fef2300e08f7c4b9ce2fe68d00d1060c458c74174c417e3488a171d9279a6a1d
+
+    <!-- END VERIFICATION RESULTS -->
+  Rollback Plan: |-
+    - Revert task-related commit(s).
+    - Re-run required checks to confirm rollback safety.
+  Findings: |-
+    - Observation: Added scripts/render-homebrew-formula.mjs, release:homebrew:check, Homebrew formula rendering in publish.yml, and homebrew-module workflow artifact upload. The module records skipped_missing_credentials until HOMEBREW_TAP_TOKEN is configured.
+      Impact: The next release can produce a Homebrew formula and channel evidence from release-distribution.json, even before tap credentials are installed.
+      Resolution: Commit the Homebrew renderer, workflow wiring, scripts README update, and workflow contract test update.
+id_source: "generated"
+---
+## Summary
+
+Add Homebrew tap publication module
+
+Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+
+## Scope
+
+- In scope: Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+- Out of scope: unrelated refactors not required for "Add Homebrew tap publication module".
+
+## Plan
+
+Plan: add a Homebrew tap publication module that renders Formula/agentplane.rb from release-distribution.json, supports dry-run/check mode, and can open or update a tap PR when credentials are configured. Verification: distribution check and workflow command check.
+
+## Verify Steps
+
+1. Run `bun run release:distribution:check`. Expected: it succeeds and confirms the requested outcome for this task.
+2. Run `bun run workflows:command-check`. Expected: it succeeds and confirms the requested outcome for this task.
+3. Review the changed artifact or behavior for the `code` task. Expected: the requested outcome is visible and matches the approved scope.
+4. Compare the final result against the task summary and touched scope. Expected: remaining follow-up is either resolved or explicit in ## Findings.
+
+## Verification
+
+<!-- BEGIN VERIFICATION RESULTS -->
+### 2026-05-01T17:13:07.600Z — VERIFY — ok
+
+By: CODER
+
+Note: Homebrew tap module verified: release:homebrew:check passed; release:distribution:check passed; workflows:command-check passed; docs:scripts:check passed; publish workflow contract test passed; lint:core passed; targeted Prettier check passed.
+
+VerifyStepsRef: doc_version=3, doc_updated_at=2026-05-01T17:10:15.206Z, excerpt_hash=sha256:fef2300e08f7c4b9ce2fe68d00d1060c458c74174c417e3488a171d9279a6a1d
+
+<!-- END VERIFICATION RESULTS -->
+
+## Rollback Plan
+
+- Revert task-related commit(s).
+- Re-run required checks to confirm rollback safety.
+
+## Findings
+
+- Observation: Added scripts/render-homebrew-formula.mjs, release:homebrew:check, Homebrew formula rendering in publish.yml, and homebrew-module workflow artifact upload. The module records skipped_missing_credentials until HOMEBREW_TAP_TOKEN is configured.
+  Impact: The next release can produce a Homebrew formula and channel evidence from release-distribution.json, even before tap credentials are installed.
+  Resolution: Commit the Homebrew renderer, workflow wiring, scripts README update, and workflow contract test update.

.agentplane/tasks/202605011626-TG4GZ4/pr/diffstat.txt

@@ -0,0 +1,6 @@
+ .github/workflows/publish.yml                      |  14 ++
+ package.json                                       |   1 +
+ .../release/publish-workflow-contract.test.ts      |   4 +
+ scripts/README.md                                  |   1 +
+ scripts/render-homebrew-formula.mjs                | 154 +++++++++++++++++++++
+ 5 files changed, 174 insertions(+)

.agentplane/tasks/202605011626-TG4GZ4/pr/github-body.md

@@ -0,0 +1,38 @@
+## Summary
+
+Add Homebrew tap publication module
+
+Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+
+## Scope
+
+- In scope: Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+- Out of scope: unrelated refactors not required for "Add Homebrew tap publication module".
+
+## Verification
+
+- State: ok
+- Note: Homebrew tap module verified: release:homebrew:check passed; release:distribution:check passed; workflows:command-check passed; docs:scripts:check passed; publish workflow contract test passed; lint:core passed; targeted Prettier check passed.
+- 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-01T17:13:16.665Z
+- Branch: task/202605011626-TG4GZ4/homebrew-tap-publication
+- Head: 91fb43545abd
+
+```text
+ .github/workflows/publish.yml                      |  14 ++
+ package.json                                       |   1 +
+ .../release/publish-workflow-contract.test.ts      |   4 +
+ scripts/README.md                                  |   1 +
+ scripts/render-homebrew-formula.mjs                | 154 +++++++++++++++++++++
+ 5 files changed, 174 insertions(+)
+```
+
+</details>

.agentplane/tasks/202605011626-TG4GZ4/pr/github-title.txt

@@ -0,0 +1 @@
+release: Add Homebrew tap publication module (TG4GZ4)

.agentplane/tasks/202605011626-TG4GZ4/pr/meta.json

@@ -0,0 +1,14 @@
+{
+  "base": "main",
+  "branch": "task/202605011626-TG4GZ4/homebrew-tap-publication",
+  "created_at": "2026-05-01T17:10:15.251Z",
+  "head_sha": "91fb43545abd7d8acf5e679a295f466e58100759",
+  "last_verified_at": "2026-05-01T17:13:07.600Z",
+  "last_verified_sha": "bb38e9d2423c928eca92501a362e64748608a3ee",
+  "schema_version": 1,
+  "task_id": "202605011626-TG4GZ4",
+  "updated_at": "2026-05-01T17:13:16.665Z",
+  "verify": {
+    "status": "pass"
+  }
+}

.agentplane/tasks/202605011626-TG4GZ4/pr/review.md

@@ -0,0 +1,63 @@
+# PR Review
+
+Created: 2026-05-01T17:10:15.251Z
+Branch: task/202605011626-TG4GZ4/homebrew-tap-publication
+
+## Summary
+
+Add Homebrew tap publication module
+
+Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+
+## Scope
+
+- In scope: Add a release module that can update an AgentPlane Homebrew tap formula from the published npm tarball, checksum, and release manifest without blocking unrelated channels.
+- Out of scope: unrelated refactors not required for "Add Homebrew tap publication module".
+
+## Verification
+
+### Plan
+
+1. Run `bun run release:distribution:check`. Expected: it succeeds and confirms the requested outcome for this task.
+2. Run `bun run workflows:command-check`. Expected: it succeeds and confirms the requested outcome for this task.
+3. Review the changed artifact or behavior for the `code` task. Expected: the requested outcome is visible and matches the approved scope.
+4. Compare the final result against the task summary and touched scope. Expected: remaining follow-up is either resolved or explicit in ## Findings.
+
+### Current Status
+
+- State: ok
+- Note: Homebrew tap module verified: release:homebrew:check passed; release:distribution:check passed; workflows:command-check passed; docs:scripts:check passed; publish workflow contract test passed; lint:core passed; targeted Prettier check passed.
+
+## 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-01T17:13:16.665Z
+- Branch: task/202605011626-TG4GZ4/homebrew-tap-publication
+- Head: 91fb43545abd
+
+```text
+ .github/workflows/publish.yml                      |  14 ++
+ package.json                                       |   1 +
+ .../release/publish-workflow-contract.test.ts      |   4 +
+ scripts/README.md                                  |   1 +
+ scripts/render-homebrew-formula.mjs                | 154 +++++++++++++++++++++
+ 5 files changed, 174 insertions(+)
+```
+
+</details>
+<!-- END AUTO SUMMARY -->

.github/workflows/publish.yml

@@ -278,6 +278,13 @@ jobs:
             --tag "${{ needs.detect.outputs.tag }}" \
             --sha "${{ needs.detect.outputs.sha }}" \
             --repo "${{ github.repository }}"
+      - name: Render Homebrew tap formula
+        shell: bash
+        run: |
+          set -euo pipefail
+          node scripts/render-homebrew-formula.mjs \
+            --manifest .agentplane/.release/publish/distribution/release-distribution.json \
+            --out .agentplane/.release/publish/homebrew
       - name: Write npm auth config
         shell: bash
         run: |
@@ -347,6 +354,13 @@ jobs:
           name: release-distribution
           path: .agentplane/.release/publish/distribution/
           if-no-files-found: warn
+      - name: Upload homebrew-module artifact
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: homebrew-module
+          path: .agentplane/.release/publish/homebrew/
+          if-no-files-found: warn
       - name: Write publish-result manifest
         if: always()
         shell: bash

package.json

@@ -51,6 +51,7 @@
     "release:smoke:published": "node scripts/check-published-packages.mjs",
     "release:distribution:generate": "node scripts/generate-release-distribution.mjs",
     "release:distribution:check": "node scripts/generate-release-distribution.mjs --check",
+    "release:homebrew:check": "node scripts/render-homebrew-formula.mjs --check",
     "ci:release-extras": "bun run artifacts:check && bun run task-state:check && bun run build && bun run package:tarball:check && bun run package:install-smoke && bun run docs:cli:check && bun run docs:recipes:check && GIT_AUTHOR_NAME=agentplane-ci GIT_AUTHOR_EMAIL=agentplane-ci@example.com GIT_COMMITTER_NAME=agentplane-ci@example.com GIT_COMMITTER_EMAIL=agentplane-ci@example.com node scripts/run-vitest-suite.mjs release-ci-base && bun run coverage:workflow-suite && bun run coverage:significant-suite && GIT_AUTHOR_NAME=agentplane-ci GIT_AUTHOR_EMAIL=agentplane-ci@example.com GIT_COMMITTER_NAME=agentplane-ci@example.com GIT_COMMITTER_EMAIL=agentplane-ci@example.com bun run test:release:critical",
     "release:ci-check": "bun run ci:contract && bun run ci:release-extras",
     "release:prepublish:fast": "bun run release:check",

packages/agentplane/src/commands/release/publish-workflow-contract.test.ts

@@ -32,6 +32,8 @@ describe("publish workflow contract", () => {
     expect(workflow).toContain("path: .agentplane/.release/publish/publish-result.json");
     expect(workflow).toContain("Generate release distribution assets");
     expect(workflow).toContain("node scripts/generate-release-distribution.mjs");
+    expect(workflow).toContain("Render Homebrew tap formula");
+    expect(workflow).toContain("node scripts/render-homebrew-formula.mjs");
     expect(workflow).toContain(
       ".agentplane/.release/publish/distribution/release-distribution.json",
     );
@@ -40,6 +42,8 @@ describe("publish workflow contract", () => {
     expect(workflow).toContain(".agentplane/.release/publish/distribution/SHA256SUMS");
     expect(workflow).toContain("name: Upload release-distribution artifact");
     expect(workflow).toContain("name: release-distribution");
+    expect(workflow).toContain("name: homebrew-module");
+    expect(workflow).toContain("path: .agentplane/.release/publish/homebrew/");
     expect(workflow).toContain(
       "--distribution-manifest .agentplane/.release/publish/distribution/release-distribution.json",
     );

scripts/README.md

@@ -33,6 +33,7 @@ Grouping policy: `ci`, `release`, `docs`, `test`, `coverage`, `arch`, `bench`, `
 | `release:distribution:check`    | `node scripts/generate-release-distribution.mjs --check`                                                                                                          | Run release workflow: distribution check.    |
 | `release:distribution:generate` | `node scripts/generate-release-distribution.mjs`                                                                                                                  | Run release workflow: distribution generate. |
 | `release:e2e:local`             | `node scripts/run-local-release-e2e.mjs`                                                                                                                          | Run release workflow: e2e local.             |
+| `release:homebrew:check`        | `node scripts/render-homebrew-formula.mjs --check`                                                                                                                | Run release workflow: homebrew check.        |
 | `release:parity`                | `node scripts/check-release-parity.mjs`                                                                                                                           | Run release workflow: parity.                |
 | `release:prepublish`            | `bun run release:prepublish:fast && bun run release:prepublish:heavy`                                                                                             | Run release workflow: prepublish.            |
 | `release:prepublish:fast`       | `bun run release:check`                                                                                                                                           | Run release workflow: prepublish fast.       |