git:20260909.c3d036e to git:20260915.de490fa

50 added, 36 removed. Audit A to A.

---

name: cut-release

- description: Prepare and publish an explicitly requested Foundry plugin-edition release using its actual platform branch, version owner and catalog. Includes coordinated README and verification gates; never an automatic release trigger.

+ description: Prepare and publish an explicitly requested Foundry plugin or edition release using its actual release branch, version owner and catalogs. Includes coordinated README and verification gates; never an automatic release trigger.

---

- # Release a Foundry plugin edition

+ # Release a Foundry plugin or edition

Use this workflow only for an explicit release request. Establish the plugin,

edition and intended version from that request and the current repository state.

- If the edition is ambiguous, resolve it before writing metadata. Running in a

- particular assistant does not by itself choose the edition being released.

+ A package plugin, whose catalogs pin one main commit for both hosts, has no

+ edition to choose. Otherwise, if the edition is ambiguous, resolve it before

+ writing metadata. Running in a particular assistant does not by itself choose

+ the edition being released.

## Sources of truth

| --- | --- | --- | --- |

Both catalog entries identify the plugin repository, platform ref and full

validated commit SHA. Claude's version and source.sha move together. A Codex

release updates its native version and then pins that exact integrated commit;

do not introduce a Claude-style version field into the Codex catalog.

+ A package such as Foreman (ADR 0011) releases one main commit. Bump the same

+ version in both manifests, then pin that commit with `ref: "main"` in both

+ catalogs. Its Claude catalog entry carries no version, so only `source.sha`

+ moves in Foundry.

Hush/Codex is not installable until its package and validation exist. Do not

create a release or add it to the catalog merely because the branch exists.

## Prepare a reviewable release

1. Locate Foundry and the intended plugin checkout. Check its branch, HEAD,

working tree and published refs. Confirm its physical working directory with

`git rev-parse --show-toplevel`; worktree-list output alone can identify a

submodule's gitdir instead. Preserve other working copies and unrelated edits.

2. Work on an appropriate non-main branch. On Windows, an existing Codex ref can

- prevent a codex/ prefix; use a non-conflicting maintenance branch. A plugin's

- main branch is its selector, never the implementation release destination.

+ prevent a codex/ prefix; use a non-conflicting maintenance branch. For a

+ plugin with editions, main is its selector, never the implementation release

+ destination; a package integrates into main.

3. Establish the exact release surface and inspect the changes since the last

- published pin for this edition. A dirty checkout is not authorization to

- include everything in it. Prepare the requested files and checks before

- requesting any genuinely missing publication approval.

- 4. Write a short user-facing CHANGELOG entry and update the edition's version

+ published pin for this edition or package. A dirty checkout is not

+ authorization to include everything in it. Prepare the requested files and

+ checks before requesting any genuinely missing publication approval.

+ 4. Write a short user-facing CHANGELOG entry and update the release's version

owner. Use the user's version when supplied; otherwise choose or clarify the

bump according to the actual compatibility change. Keep unrelated metadata.

- 5. Use coordinate-readmes and check the actual candidate pair. The CLI supports

- `--pair <Claude-README> <Codex-README>` and

+ 5. For a plugin with editions, use coordinate-readmes and check the actual

+ candidate pair. The CLI supports `--pair <Claude-README> <Codex-README>` and

`--git-pair <plugin-repo> <Claude-candidate-ref> <Codex-candidate-ref>`.

Shared changes need both candidates; model-specific measurements must retain

- their own evidence. Missing benchmarks stay explicitly unmeasured.

+ their own evidence. A package's single README needs its navigation check and

+ a review of each host's evidence. Missing benchmarks stay explicitly unmeasured.

6. Run the relevant plugin, packaging, documentation and maintenance checks.

- Read the edition's compatibility/validation guide. Do not run a Claude hook

- canary against a Codex package, invent hook events, or treat unit tests as

- installed activation. Paid benchmarks and installations need their own scope.

+ Read the compatibility/validation guide for each host in the release. Do not

+ run a Claude hook canary against a Codex package, invent hook events, or treat

+ unit tests as installed activation. Paid benchmarks and installations need

+ their own scope.

- ## Integrate and publish the selected edition

+ ## Integrate and publish the release

Commit only the reviewed release surface. Use the repository's actual PR and

- branch-protection process to integrate into Claude or Codex. Push the explicit

- reviewed branch/ref to its intended destination; never substitute `origin main`

- for the current edition. Preserve any separate acceptance or merge requirement

- from the user. Do not bypass a failing check to force a release through.

+ branch-protection process to integrate into Claude or Codex, or into main for a

+ package. Push the explicit reviewed branch/ref to its intended destination; never

+ substitute `origin main` for an edition branch. Preserve any separate acceptance

+ or merge requirement from the user. Do not bypass a failing check to force a

+ release through.

- Once the edition commit is integrated and remotely reachable, record its full

+ Once the release commit is integrated and remotely reachable, record its full

SHA in the correct Foundry catalog. Verify the remote branch contains that SHA.

- For Claude, update the catalog version in that same root change. For Codex,

- verify the pinned manifest contains the new effective version. A gitlink update

- alone does not publish a package update.

+ For a Claude edition, update the catalog version in that same root change. For a

+ Codex edition, verify the pinned manifest contains the new effective version. For

+ a package, move `source.sha` in both catalogs to the same main commit and verify

+ that both manifests there carry the new version. A gitlink update alone does not

+ publish a package update.

Run `node scripts/git-hooks/check-platform-marketplaces.js` from Foundry and

the relevant documentation/integration checks. Integrate the reviewed root

- catalog change through its normal PR process. Publish destination branches

- before selector pages that link to them. Do not fold unrelated local work into

- either repository's release commit.

+ catalog change through its normal PR process. For a plugin with editions,

+ publish destination branches before selector pages that link to them. Do not

+ fold unrelated local work into either repository's release commit.

## Report the outcome

- Report the plugin and edition, version, integrated plugin SHA, root catalog SHA,

- actual push/check results and any remaining activation or publication boundary.

- If a remote operation fails, inspect the result and report its concrete state;

- do not silently broaden the push or retry with force. Do not claim publication

- from a local commit, valid manifest or passing unit suite alone.

+ Report the plugin and its edition or package, version, integrated plugin SHA,

+ root catalog SHA, actual push/check results and any remaining activation or

+ publication boundary. If a remote operation fails, inspect the result and report

+ its concrete state; do not silently broaden the push or retry with force. Do not

+ claim publication from a local commit, valid manifest or passing unit suite alone.