code-foundry 1.18.0 → 1.20.1

package/.github/workflows/consumer-qualification.yml

@@ -8,6 +8,19 @@ on:
         required: false
         type: boolean
         default: false
+    outputs:
+      filename:
+        description: Exact qualified npm archive name.
+        value: ${{ jobs.pack.outputs.filename }}
+      source-sha:
+        description: Commit whose archive passed the complete qualification matrix.
+        value: ${{ jobs.gate.outputs.source-sha }}
+      sha256:
+        description: SHA-256 of the qualified archive, without an algorithm prefix.
+        value: ${{ jobs.gate.outputs.sha256 }}
+      candidate-artifact:
+        description: Candidate artifact scoped to this workflow run and attempt.
+        value: ${{ jobs.gate.outputs.candidate-artifact }}
 
 permissions:
   actions: read
@@ -21,6 +34,9 @@ jobs:
     timeout-minutes: 10
     outputs:
       filename: ${{ steps.pack.outputs.filename }}
+      source-sha: ${{ steps.pack.outputs.source-sha }}
+      sha256: ${{ steps.pack.outputs.sha256 }}
+      run-attempt: ${{ steps.pack.outputs.run-attempt }}
     steps:
       - name: Checkout candidate
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -37,14 +53,18 @@ jobs:
           mkdir -p "$RUNNER_TEMP/candidate"
           npm pack --ignore-scripts --json --pack-destination "$RUNNER_TEMP/candidate" > "$RUNNER_TEMP/candidate/pack.json"
           PACKAGE=$(node -e 'const p=require(process.argv[1]); if(p.length!==1 || !/^[A-Za-z0-9._-]+\.tgz$/.test(p[0].filename)) process.exit(1); console.log(p[0].filename)' "$RUNNER_TEMP/candidate/pack.json")
-          echo "filename=$PACKAGE" >> "$GITHUB_OUTPUT"
+          {
+            echo "filename=$PACKAGE"
+            echo "source-sha=$(git rev-parse HEAD)"
+            echo "sha256=$(sha256sum "$RUNNER_TEMP/candidate/$PACKAGE" | cut -d' ' -f1)"
+            echo "run-attempt=$GITHUB_RUN_ATTEMPT"
+          } >> "$GITHUB_OUTPUT"
       - name: Retain the shared candidate
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
-          name: qualification-candidate-${{ github.run_id }}
+          name: qualification-candidate-${{ github.run_id }}-${{ github.run_attempt }}
           path: ${{ runner.temp }}/candidate/*
           if-no-files-found: error
-          overwrite: true
           retention-days: 14
 
   qualify:
@@ -57,6 +77,11 @@ jobs:
       fail-fast: false
       matrix:
         node: ['20', '22', '24']
+    env:
+      PACKAGE: ${{ needs.pack.outputs.filename }}
+      SOURCE_SHA: ${{ needs.pack.outputs.source-sha }}
+      CANDIDATE_SHA256: ${{ needs.pack.outputs.sha256 }}
+      PACK_ATTEMPT: ${{ needs.pack.outputs.run-attempt }}
     steps:
       - name: Checkout qualification runtime
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -70,26 +95,103 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          set -euo pipefail
+          test "$PACK_ATTEMPT" = "$GITHUB_RUN_ATTEMPT" || { echo 'Rerun all jobs: qualification cannot mix run attempts.' >&2; exit 1; }
+          test "$(git rev-parse HEAD)" = "$SOURCE_SHA"
           gh run download "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" \
-            --name "qualification-candidate-$GITHUB_RUN_ID" \
+            --name "qualification-candidate-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" \
             --dir "$RUNNER_TEMP/candidate"
+          test "$(sha256sum "$RUNNER_TEMP/candidate/$PACKAGE" | cut -d' ' -f1)" = "$CANDIDATE_SHA256"
       - name: Install pinned workflow validator
         run: go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
       - name: Qualify the exact shared distributable
-        env:
-          PACKAGE: ${{ needs.pack.outputs.filename }}
         run: |
           set -euo pipefail
           node src/lib/consumer-qualification.mjs \
-            "$RUNNER_TEMP/candidate/$PACKAGE" \
-            "$(git rev-parse HEAD)" \
-            "$RUNNER_TEMP/report.json" \
-            "$(go env GOPATH)/bin/actionlint"
+            "$RUNNER_TEMP/candidate/$PACKAGE" "$SOURCE_SHA" \
+            "$RUNNER_TEMP/report.json" "$(go env GOPATH)/bin/actionlint"
       - name: Retain qualification evidence
         if: always()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: consumer-qualification-${{ github.run_attempt }}-node-${{ matrix.node }}
           path: ${{ runner.temp }}/report.json
-          if-no-files-found: warn
+          if-no-files-found: error
+          retention-days: 14
+
+  gate:
+    name: Gate
+    needs: [pack, qualify]
+    if: >-
+      always() && !cancelled() &&
+      (vars.CI_BILLING_PAUSED != 'true' || inputs['billing-pause-bypass'] == true)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    outputs:
+      source-sha: ${{ steps.verify.outputs.source-sha }}
+      sha256: ${{ steps.verify.outputs.sha256 }}
+      candidate-artifact: ${{ steps.verify.outputs.candidate-artifact }}
+    env:
+      PACKAGE: ${{ needs.pack.outputs.filename }}
+      SOURCE_SHA: ${{ needs.pack.outputs.source-sha }}
+      CANDIDATE_SHA256: ${{ needs.pack.outputs.sha256 }}
+      PACK_ATTEMPT: ${{ needs.pack.outputs.run-attempt }}
+      PACK_RESULT: ${{ needs.pack.result }}
+      QUALIFY_RESULT: ${{ needs.qualify.result }}
+    steps:
+      - name: Require the complete successful matrix
+        run: |
+          set -euo pipefail
+          test "$PACK_RESULT" = success
+          test "$QUALIFY_RESULT" = success
+          test "$PACK_ATTEMPT" = "$GITHUB_RUN_ATTEMPT" || { echo 'Rerun all jobs: qualification cannot mix run attempts.' >&2; exit 1; }
+      - name: Checkout qualification policy
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '24'
+      - name: Retrieve this attempt's candidate and reports
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          test "$(git rev-parse HEAD)" = "$SOURCE_SHA"
+          gh run download "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" \
+            --name "qualification-candidate-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" \
+            --dir "$RUNNER_TEMP/candidate"
+          for node in 20 22 24; do
+            gh run download "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" \
+              --name "consumer-qualification-$GITHUB_RUN_ATTEMPT-node-$node" \
+              --dir "$RUNNER_TEMP/reports/$node"
+          done
+      - name: Verify source, archive and every fixture before handing off
+        id: verify
+        run: |
+          node --input-type=module <<'NODE'
+          import assert from 'node:assert/strict'
+          import { appendFileSync, readFileSync, writeFileSync } from 'node:fs'
+          import { join } from 'node:path'
+          import { qualifyArchive } from './src/commands/qualified-publication.mjs'
+          const env = process.env
+          const version = JSON.parse(readFileSync('package.json', 'utf8')).version
+          const candidate = {
+            repository: env.GITHUB_REPOSITORY, tag: `v${version}`,
+            sourceSha: env.SOURCE_SHA, asset: env.PACKAGE,
+            directory: join(env.RUNNER_TEMP, 'candidate'),
+          }
+          const result = qualifyArchive(candidate, ['20', '22', '24'].map(node => join(env.RUNNER_TEMP, 'reports', node, 'report.json')))
+          assert.equal(result.digest, `sha256:${env.CANDIDATE_SHA256}`)
+          const artifact = `qualification-candidate-${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT}`
+          writeFileSync(join(env.RUNNER_TEMP, 'qualification.json'), JSON.stringify({ ...result, run_id: env.GITHUB_RUN_ID, run_attempt: env.GITHUB_RUN_ATTEMPT }, null, 2) + '\n')
+          appendFileSync(env.GITHUB_OUTPUT, `source-sha=${result.sourceSha}\nsha256=${env.CANDIDATE_SHA256}\ncandidate-artifact=${artifact}\n`)
+          NODE
+      - name: Retain the qualified handoff
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: qualification-handoff-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/qualification.json
+          if-no-files-found: error
           retention-days: 14

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.20.1](https://github.com/0xPlayerOne/code-foundry/compare/v1.20.0...v1.20.1) (2026-09-09)
+
+
+### Bug Fixes
+
+* **qualification:** isolate attempts and verify release handoff ([#556](https://github.com/0xPlayerOne/code-foundry/issues/556)) ([5fe7f42](https://github.com/0xPlayerOne/code-foundry/commit/5fe7f4203b8018fd3eb88bd68e2286c6feb3d3dc))
+
+## [1.20.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.19.0...v1.20.0) (2026-09-09)
+
+
+### Features
+
+* **ci:** add opt-in merge-group audit validation ([#549](https://github.com/0xPlayerOne/code-foundry/issues/549)) ([ae418a7](https://github.com/0xPlayerOne/code-foundry/commit/ae418a779ada2927bd391cc6cf54db16e342d921))
+
+## [1.19.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.18.0...v1.19.0) (2026-09-09)
+
+
+### Features
+
+* **fleet:** gate upgrades on verified release qualification ([#548](https://github.com/0xPlayerOne/code-foundry/issues/548)) ([3247cc6](https://github.com/0xPlayerOne/code-foundry/commit/3247cc6f2295c65c42bb43e4ec8f87a08f3dd02d))
+
 ## [1.18.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.17.0...v1.18.0) (2026-09-09)
 
 

package/docs/PERFORMANCE.md

@@ -15,25 +15,19 @@ belong to the run that produced them, not the source tree.
 | Format, lint, type-check, and build |   15 s | Bound the local CI feedback loop                     |
 | Runtime dependencies                |      0 | Keep the installed CLI dependency-free               |
 | Development dependencies            |      4 | Prevent unreviewed toolchain growth                  |
-| Packed artifact                     | 250 kB | Bound registry transfer and install cost             |
-| Unpacked artifact                   | 930 kB | Bound installed footprint                            |
-| Packed files                        |    110 | Detect accidental release contents                   |
+| Packed artifact                     | 255 kB | Bound registry transfer and install cost             |
+| Unpacked artifact                   | 965 kB | Bound installed footprint                            |
+| Packed files                        |    115 | Detect accidental release contents                   |
 
 The performance workflow disables build-cache reads and writes for this task.
 That makes timing comparisons independent of a warm protected-branch cache and
 prevents benchmark code from populating shared cache entries.
 
-The consumer qualification workflow adds the installed-package harness and
-workflow contract to the distributable. The merged candidate measured 221,495
-packed bytes, 853,573 unpacked bytes, and 100 files on Node 24.18.0; the updated
-budgets leave a small margin while continuing to bound package growth. The
-product-quality profiles and consumer qualification workflow measured 232,650
-packed bytes, 890,418 unpacked bytes, and 103 files on Node 24.18.0, so the
-limits remain intentionally bounded while covering both opt-in feature sets.
-The qualified-publication workflow adds the release staging and publication
-contract to the distributable. This candidate measured 238,816 packed bytes,
-915,957 unpacked bytes, and 106 files on Node 24.18.0; the 250 kB and 930 kB
-limits retain a measured margin while covering the required release path.
+The merged candidate includes the release-integrity verifier, fleet eligibility,
+consumer qualification harness, product-quality profiles, qualified publication
+workflow, and opt-in merge-queue verifier. It measured 248,464 packed bytes,
+947,310 unpacked bytes, and 111 files on Node 24.18.0; the 255 kB, 965 kB, and
+115-file limits retain a small margin while continuing to bound package growth.
 
 ## v1.6.1 baseline
 
@@ -67,4 +61,6 @@ pull request, run the complete validation gate, and merge only when the new
 result artifact is available. A Release Please PR then carries the change into
 the next version. Never raise a budget solely to clear CI; include before/after
 measurements and the expected effect on local feedback, hosted runner time,
-package transfer, or installed footprint.
+package transfer, or installed footprint. The current budget covers the measured
+combined release-integrity, fleet, consumer-qualification, and product-quality
+package footprint described above.

package/docs/consumer-qualification.md

@@ -6,7 +6,7 @@ Release-candidate compatibility checks against the distributable package.
 **Scope:** Package installation, CLI initialization/synchronization, generated workflow contracts.
 
 `consumer-qualification.yml` packs the checked-out candidate once, shares that archive across all supported
-Node majors using an artifact scoped to the same workflow run (including failed-job reruns), installs it offline with lifecycle scripts disabled,
+Node majors using an artifact scoped to the same workflow run **and attempt**, installs it offline with lifecycle scripts disabled,
 and executes its public CLI from the installed package. The harness does not
 import the source checkout's initializer as a substitute for package testing.
 
@@ -39,10 +39,26 @@ member. Reports are evidence, not signatures or a substitute for release identit
 verification.
 
 The self release caller cannot start Release Please or npm publication until all
-qualification jobs succeed. An explicit `release-while-paused` dispatch is passed
+qualification jobs and the aggregate `Gate` succeed. An explicit `release-while-paused` dispatch is passed
 through to the reusable workflow; ordinary calls remain blocked by the billing pause.
 Consumer-generated release callers do not inherit this Code Foundry-specific
 qualification job. This does not yet guarantee that its legacy publishing job uses
 this same archive; the verified-publication workflow handles that separate
 requirement. No branch protections, repository settings, credentials, or consumer
 runtimes are changed by this feature.
+
+## Verified handoff and reruns
+
+The reusable workflow exports `filename`, `source-sha`, `sha256`, and
+`candidate-artifact`. Only the gate exports the verified source, digest, and
+artifact identity. It requires a successful pack and complete Node matrix,
+retrieves every report from the current attempt, and checks all fixture results
+against the same source and archive through the publication eligibility policy.
+Its retained `qualification-handoff-RUN_ID-ATTEMPT` receipt records that identity.
+A green matrix without valid matching reports cannot authorize a release.
+
+Artifacts are never overwritten. On a failed or cancelled qualification, use
+**Re-run all jobs**, not a failed-job-only rerun: a later attempt cannot reuse
+an earlier pack or silently combine old and new reports. Missing/expired artifacts
+fail closed; start a fresh complete run. This stricter retry policy also applies
+when qualification is nested in a release workflow. No release settings change.

package/docs/fleet-release-eligibility.md

@@ -0,0 +1,80 @@
+# Fleet Release Eligibility
+
+Require a verified, qualified runtime before any fleet upgrade mutates repositories.
+
+**Dependency:** Installed release-integrity verifier (#537).
+**Activation:** Consumer-owned `.code-foundry-release-policy.json` at the fleet root.
+
+The public `upgradeFleet` entrypoint now applies an optional release eligibility
+guard before delegating to the unchanged legacy/manifest rollout implementation.
+The implementation was moved verbatim to `fleet-core.mjs`; discovery exports and
+existing callers retain their interface. No policy file means existing behavior.
+A malformed or symlinked policy is an error, not an opt-out. Dry runs use the same
+guard, and `--force` cannot bypass source identity or qualification.
+
+```json
+{
+  "schema_version": 1,
+  "repository": "owner/code-foundry",
+  "workflow": ".github/workflows/release_self-ci.yml",
+  "branch": "main",
+  "required_jobs": [
+    "Qualify consumers / Node 20",
+    "Qualify consumers / Node 22",
+    "Qualify consumers / Node 24"
+  ]
+}
+```
+
+This is a shape example, not a completed fleet policy. Populate canonical repository
+identity, actual workflow path, and exact job names from the qualified release
+caller's Actions API results. Include the publication job when successful registry
+publication is required before adoption. Require every relevant job: a workflow's
+aggregate success alone can conceal skipped jobs. The qualification gate in #544
+and verified publisher in #547 provide the producer side of this policy.
+
+Keep the policy alongside the **consumer workspace's** fleet inventory. Do not put
+private repository names, local layouts, or deployment credentials into this
+reusable baseline. Commit policy changes for review; the guard does not secretly
+change branch protection, environments, rollout cohorts, or required capabilities.
+
+## What is verified
+
+The proposed runtime must be a clean Git source checkout. Its exact HEAD must
+match the cryptographically verified immutable release tag. An installed npm
+package without Git metadata cannot substitute for a verifiable source checkout;
+use the existing `--source` option with the checked-out release. The verifier comes
+from the trusted running Foundry installation, not the unverified candidate.
+
+The guard resolves the configured workflow's identity, retrieves every page of
+runs for the exact source, and selects the latest matching protected-branch push
+or manual run. It rejects pending/failed/cancelled runs, fork provenance, disabled
+workflows, missing/ambiguous/skipped jobs, and incomplete pagination. An older
+success does not override a newer failed run. Job evidence comes from the precise
+run attempt; that attempt is rechecked before proceeding. Source HEAD, cleanliness,
+and the policy's bytes are rechecked before the upgrade callback executes.
+
+Successful eligibility emits JSON to stderr with source SHA, policy digest,
+workflow/run/attempt identifiers, and required job names. It does not write an
+approval into the source or silently make PRs ready. Existing resumable rollouts,
+canary validation, draft creation, and provenance markers stay in the original
+fleet engine. The guard is policy enforcement in the supported public entrypoint,
+not a sandbox against someone intentionally importing private implementation files
+or using Git directly. Normal credentials still determine what remote mutations
+are possible after eligibility passes.
+
+## Activation and validation
+
+First release and validate the qualification/verification producer and confirm
+real workflow/job identities. Then opt a consumer workspace into this policy and
+exercise `fleet upgrade --dry-run --root <fleet-root> --source <clean-release-checkout>`.
+When `--source` is omitted, the installed package is used and an enabled policy
+will reject it unless that installation is itself a clean Git checkout. Older mutable
+releases or unavailable permissions should fail; do not weaken the policy just to
+make an old release eligible. No real fleet inventory is fabricated by this PR.
+
+The focused suite verifies guard ordering and failure propagation with GitHub/CLI
+fixtures. Live authenticated verification, exact production job naming, and the
+full existing fleet-engine suite must pass before activation. The original fleet
+engine's Git blob is retained byte-for-byte; the source move still needs full
+repository import/type-check/packaging validation in CI.

package/docs/fleet-rollouts.md

@@ -55,11 +55,12 @@ Adopt those requirements in consumer repositories before requiring them here.
 
 ```sh
 code-foundry fleet status --root /path/to/fleet
-code-foundry fleet upgrade --root /path/to/fleet --dry-run
-code-foundry fleet upgrade --root /path/to/fleet --create-pr
+code-foundry fleet upgrade --root /path/to/fleet --source /path/to/release-checkout --dry-run
+code-foundry fleet upgrade --root /path/to/fleet --source /path/to/release-checkout --create-pr
 ```
 
-Run from the intended released Code Foundry installation/checkout. The existing
+Use `--source` to provide the clean Code Foundry release checkout used for the
+upgrade; when omitted, the installed Code Foundry package is used. The existing
 source-version guard still rejects mismatched `--version` requests. Manifest mode
 requires `--create-pr` or `--dry-run` and never syncs original checkouts in place.
 `--force` does not bypass dirty-tree safety in manifest mode. Dry-run reports

package/docs/merge-queues.md

@@ -0,0 +1,89 @@
+# Merge Queue Validation
+
+Opt-in validation of the combined commit produced by GitHub's merge queue.
+
+**Activation:** `merge_queue: true` in the consumer's `.github/code-foundry.yml`, followed by normal sync.
+**Required check:** Existing canonical `Validation / Gate`.
+
+The synchronizer adds `.github/workflows/validation-merge-queue.yml` only when
+explicitly enabled. The ordinary PR readiness workflow is unchanged: this feature
+does not turn draft pushes into CI, mark PRs ready, enqueue PRs, or change release
+behavior. Queue events receive the full audit even when staging PRs normally use
+fast validation. Release Please branch detection is deliberately not reused for
+a merge group containing several PRs; the group's combined tree is audited, not
+treated as a generated version-only diff.
+
+```yaml
+merge_queue: true
+```
+
+Normal `code-foundry sync` updates the generated queue caller alongside the other
+runtime pins. Explicit fleet runtime overrides are honored. The installed runtime
+must contain this feature, and queues require an exact commit or released version
+pin rather than a moving branch. Direct topology enables main; staging-release
+enables main and staging. Existing runner choices, Rust CodeQL sharding, and an
+explicit `codeql: false` policy select the same appropriate validation orchestrator
+as ordinary PRs. No CodeQL policy or runtime default is relaxed.
+
+## Event identity and checks
+
+The generated caller accepts only `merge_group` / `checks_requested`. A pinned,
+trusted verifier checks the payload's repository, allowed base branch, queue ref,
+base SHA, and head SHA against the actual workflow context before validation can
+start. The existing reusable orchestrator then checks out the merge-group commit
+through its normal GitHub context and runs CI, tests (including non-unit lanes),
+security, and the configured CodeQL policy with `mode: audit`.
+
+The caller job is named `Validation`, so the existing orchestrator still emits
+`Validation / Gate`. That gate's audit truth table requires successful results;
+skipped or failed required jobs cannot satisfy it. A failed identity job prevents
+validation from starting and cannot manufacture a successful aggregate check.
+The standard PR classifier remains PR/scheduled/manual-specific; merge groups
+have their own strict classifier rather than weakening its event whitelist.
+
+Concurrency is scoped to the actual queue ref and has a different prefix from PR,
+release, and scheduled workflows. New groups do not cancel unrelated groups or
+PR readiness runs. Replaced attempts for the same queue ref can supersede each
+other. The billing-pause switch is preserved; paused validation does not produce
+a success that authorizes a merge.
+
+The caller forwards no secrets and grants no deployment or OIDC publication
+permission. Its permission union matches the existing audit chain (including
+CodeQL security-event uploads). Applications requiring secret-backed tests must
+provide safe queue-compatible fixtures or a separately reviewed explicit caller;
+this feature does not introduce `secrets: inherit`. Native test commands remain
+repository-owned code, not a sandbox.
+
+## Preservation and disabling
+
+Setting `merge_queue: false` or removing the key removes only a caller bearing the
+exact Foundry management marker. A custom file at that path is preserved when
+disabled; enabling over it fails before synchronization writes, even with force.
+Symlinked workflow paths are rejected. Dry runs report changes without creating,
+updating, or deleting the caller. The original synchronizer is retained verbatim
+in `sync-core.mjs`; its public exports are preserved through the thin wrapper.
+
+Disable the repository's queue rule before removing its required queue workflow.
+Otherwise queued PRs will correctly wait for checks that no longer run.
+
+## Repository activation remains separate
+
+A repository administrator must verify GitHub plan/repository eligibility,
+review queue merge-method compatibility with the chosen branch topology, and
+configure required checks. Register the aggregate check, not PR-only mode or
+readiness checks that have no merge-group equivalent. An existing rule requiring
+individual checks needs those exact contexts reviewed as well. Do not enable the
+queue rule before the workflow is merged and a disposable queue exercise passes.
+No repository rule, branch protection, secret, merge setting, or queue is changed
+by this PR.
+
+Focused tests cover event identity and rejection, generated audit wiring,
+configured CodeQL policy, pin evolution, idempotence, dry runs, and ownership
+preservation. They do not establish a live merge-group run or full sync integration.
+Before readiness, run the existing complete sync/fleet tests, locked formatter,
+linter, TypeScript and package budgets, and Actionlint against rendered callers
+and their pinned/local reusable workflow contracts. Exercise two queued PRs and
+one deliberately failing check in an eligible disposable repository.
+
+References: [GitHub merge-queue CI configuration](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue),
+[merge-group event](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.18.0",
+  "version": "1.20.1",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "homepage": "https://github.com/0xPlayerOne/code-foundry#readme",
   "bugs": {

package/src/cli.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url'
 
 const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
 
-/** @typedef {{ target: string, root: string, dryRun: boolean, force: boolean, github: boolean, createPr: boolean, exclude: string[], base: string, head: string, tag: string, workflow: string, mode: string, version: string, repository: string, expectedSha: string, assets: string[], rootProvided: boolean, releaseSubcommand?: string, fleetSubcommand?: string, integritySubcommand?: 'settings'|'release'|'manifest', ciSubcommand?: 'pause'|'resume'|'status' }} Options */
+/** @typedef {{ target: string, root: string, source: string, dryRun: boolean, force: boolean, github: boolean, createPr: boolean, exclude: string[], base: string, head: string, tag: string, workflow: string, mode: string, version: string, versionExplicit: boolean, repository: string, expectedSha: string, assets: string[], rootProvided: boolean, releaseSubcommand?: string, fleetSubcommand?: string, integritySubcommand?: 'settings'|'release'|'manifest', ciSubcommand?: 'pause'|'resume'|'status' }} Options */
 /** @typedef {{ command: string, options: Options }} ParsedArgs */
 
 const usage = `code-foundry — initialize and maintain agent-ready repositories
@@ -25,7 +25,7 @@ Usage:
   npx code-foundry release-integrity release --repo OWNER/REPO --tag TAG
   npx code-foundry release-integrity manifest --asset PATH [--root PATH]
   npx code-foundry fleet status [--root PATH]
-  npx code-foundry fleet upgrade [--root PATH] [--dry-run] [--create-pr]
+  npx code-foundry fleet upgrade [--root PATH] [--source PATH] [--dry-run] [--create-pr]
 
 The repository configuration lives in .github/code-foundry.yml.
 init detects the repository, creates that file, and renders the baseline.
@@ -45,6 +45,7 @@ Options:
   --expected-sha SHA  Expected source commit for release-integrity verification
   --asset PATH    Selected release-integrity artifact (repeatable)
   --root PATH     Fleet root containing repositories (default: current directory)
+  --source PATH   Clean Code Foundry release checkout used for fleet upgrades
   --create-pr     Create isolated upgrade branches and pull requests
   --version TAG   Runtime tag to report in fleet upgrade branches
   --exclude NAME  Skip a repository path or owner/name in fleet operations
@@ -66,6 +67,7 @@ function parseArgs(argv) {
   const options = {
     target: process.cwd(),
     root: process.cwd(),
+    source: packageRoot,
     dryRun: false,
     force: false,
     github: false,
@@ -77,6 +79,7 @@ function parseArgs(argv) {
     workflow: '',
     mode: 'auto',
     version: `v${readPackageVersion(packageRoot)}`,
+    versionExplicit: false,
     repository: '',
     expectedSha: '',
     assets: [],
@@ -146,9 +149,17 @@ function parseArgs(argv) {
     else if (arg === '--root') {
       options.root = argv.shift() ?? fail('--root requires a path')
       options.rootProvided = true
+    } else if (arg === '--source') {
+      if (command !== 'fleet' || options.fleetSubcommand !== 'upgrade')
+        fail('--source is only supported by fleet upgrade')
+      const value = argv.shift()
+      if (!value || value.startsWith('-')) fail('--source requires a path')
+      options.source = value
     } else if (arg === '--create-pr') options.createPr = true
-    else if (arg === '--version') options.version = argv.shift() ?? fail('--version requires a tag')
-    else if (arg === '--exclude')
+    else if (arg === '--version') {
+      options.version = argv.shift() ?? fail('--version requires a tag')
+      options.versionExplicit = true
+    } else if (arg === '--exclude')
       options.exclude.push(argv.shift() ?? fail('--exclude requires a name'))
     else fail(`unknown option: ${arg}; run --help for the supported options`)
   }
@@ -241,11 +252,13 @@ async function main() {
       if (options.fleetSubcommand === 'status')
         console.log(JSON.stringify(discoverRepositories(root), null, 2))
       else
-        upgradeFleet(root, packageRoot, {
+        upgradeFleet(root, resolve(options.source), {
           createPr: options.createPr,
           dryRun: options.dryRun,
           force: options.force,
-          version: options.version,
+          version: options.versionExplicit
+            ? options.version
+            : `v${readPackageVersion(resolve(options.source))}`,
           exclude: options.exclude,
         })
     } catch (error) {