code-foundry 1.17.0 → 1.19.0

package/.github/workflows/qualified-foundry-publish.yml

@@ -0,0 +1,144 @@
+name: Qualified Foundry Publication
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Published immutable release tag at the caller commit.
+        required: true
+        type: string
+      asset:
+        description: Exact pre-attached Code Foundry npm tarball name.
+        required: true
+        type: string
+      environment:
+        description: Protected GitHub environment for npm publication.
+        required: false
+        default: npm
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: false
+
+permissions:
+  attestations: read
+  contents: read
+
+jobs:
+  qualify:
+    name: Qualify Node ${{ matrix.node }}
+    if: vars.CI_BILLING_PAUSED != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ['20', '22', '24']
+    steps:
+      - name: Checkout trusted qualification runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install pinned Actionlint
+        run: go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
+      - name: Download and cryptographically verify the release archive
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+          RELEASE_ASSET: ${{ inputs.asset }}
+        run: |
+          set -euo pipefail
+          node src/commands/qualified-publication.mjs download \
+            "$GITHUB_REPOSITORY" "$RELEASE_TAG" "$GITHUB_SHA" "$RELEASE_ASSET" \
+            "$RUNNER_TEMP/candidate" > "$RUNNER_TEMP/download.json"
+      - name: Qualify those exact bytes
+        env:
+          RELEASE_ASSET: ${{ inputs.asset }}
+        run: |
+          set -euo pipefail
+          node src/lib/consumer-qualification.mjs \
+            "$RUNNER_TEMP/candidate/$RELEASE_ASSET" "$GITHUB_SHA" \
+            "$RUNNER_TEMP/report.json" "$(go env GOPATH)/bin/actionlint"
+      - name: Retain this attempt's qualification report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: qualified-${{ github.run_attempt }}-node-${{ matrix.node }}
+          path: ${{ runner.temp }}/report.json
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish qualified archive
+    needs: qualify
+    if: vars.CI_BILLING_PAUSED != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment: ${{ inputs.environment }}
+    concurrency:
+      group: qualified-foundry-npm-${{ github.repository }}-${{ inputs.tag }}
+      cancel-in-progress: false
+    permissions:
+      actions: read
+      attestations: read
+      contents: read
+      id-token: write
+    env:
+      HAS_NPM_TOKEN: ${{ secrets.NPM_TOKEN != '' }}
+      RELEASE_TAG: ${{ inputs.tag }}
+      RELEASE_ASSET: ${{ inputs.asset }}
+    steps:
+      - name: Checkout trusted publication runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup Node for trusted publishing
+        if: env.HAS_NPM_TOKEN != 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '24'
+      - name: Setup Node for token publishing
+        if: env.HAS_NPM_TOKEN == 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '24'
+          registry-url: https://registry.npmjs.org
+      - name: Retrieve only this run attempt's evidence
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          for node in 20 22 24; do
+            gh run download "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" \
+              --name "qualified-$GITHUB_RUN_ATTEMPT-node-$node" \
+              --dir "$RUNNER_TEMP/reports/$node"
+          done
+          node src/commands/qualified-publication.mjs download \
+            "$GITHUB_REPOSITORY" "$RELEASE_TAG" "$GITHUB_SHA" "$RELEASE_ASSET" \
+            "$RUNNER_TEMP/candidate" > "$RUNNER_TEMP/download.json"
+      - name: Reverify and publish the tested tarball without lifecycle hooks
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          node src/commands/qualified-publication.mjs publish \
+            "$GITHUB_REPOSITORY" "$RELEASE_TAG" "$GITHUB_SHA" "$RELEASE_ASSET" \
+            "$RUNNER_TEMP/candidate" \
+            "$RUNNER_TEMP/reports/20/report.json" \
+            "$RUNNER_TEMP/reports/22/report.json" \
+            "$RUNNER_TEMP/reports/24/report.json" > "$RUNNER_TEMP/publication.json"
+      - name: Retain publication identity
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: qualified-publication-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/publication.json
+          if-no-files-found: warn
+          retention-days: 14

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **releases:** stage qualified assets and publish verified identical archives ([#547](https://github.com/0xPlayerOne/code-foundry/issues/547)) ([dffcb83](https://github.com/0xPlayerOne/code-foundry/commit/dffcb834c8ee8c5c2bcba606350276e6a7de58d0))
+
 ## [1.17.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.16.0...v1.17.0) (2026-09-09)
 
 

package/docs/PERFORMANCE.md

@@ -15,21 +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                     | 240 kB | Bound registry transfer and install cost             |
-| Unpacked artifact                   | 900 kB | Bound installed footprint                            |
+| Packed artifact                     | 250 kB | Bound registry transfer and install cost             |
+| Unpacked artifact                   | 930 kB | Bound installed footprint                            |
 | Packed files                        |    110 | 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 merged candidate includes the release-integrity verifier, fleet eligibility,
+consumer qualification harness, product-quality profiles, and qualified
+publication workflow. It measured 243,466 packed bytes, 930,389 unpacked bytes,
+and 109 files on Node 24.18.0; the 250 kB, 945 kB, and 110-file limits retain a
+small margin while continuing to bound package growth.
 
 ## v1.6.1 baseline
 
@@ -63,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/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/qualified-publication.md

@@ -0,0 +1,111 @@
+# Qualified Publication
+
+Publish only the same immutable Code Foundry archive that passed consumer qualification.
+
+**Dependencies:** Consumer qualification (#544) and release integrity (#537).
+**Activation:** Opt-in replacement publisher; no existing publisher is silently changed.
+
+The reusable `qualified-foundry-publish.yml` downloads an explicitly named npm
+archive from an already-published immutable release, verifies the release and
+asset attestations against the caller's exact commit, qualifies that same archive
+on Node 20/22/24, and only then admits a protected npm publication job. The final
+job downloads only reports from its own workflow run **and run attempt**, rechecks
+all required fixtures and archive/source identities, repeats cryptographic asset
+verification, validates the package name/version, and publishes the tarball with
+lifecycle scripts disabled. It never publishes a directory or rebuilds the package.
+
+The publishing job uses a GitHub environment, serializes publication for a tag,
+and has no dependency installation/build step. Qualification has no npm credential.
+Normal npm trusted publishing is preferred; an explicit optional token supports
+existing consumers. Configure the trusted publisher for the **actual caller and
+reusable-workflow relationship** before enabling this route. Existing version
+publication is not overwritten: retrying an already-published version fails rather
+than treating a registry conflict or network error as proof of identity.
+
+## Release producer contract
+
+Build and test a package once, attach its tarball to a **draft** release, then
+publish that release with immutability enabled. The archive must contain the
+Code Foundry CLI/templates; this is intentionally not a generic package harness.
+The candidate's `package.json` name must be `code-foundry` and its version must
+match the explicit tag. All qualification modules must exist in the caller commit.
+A recent GitHub CLI with `release verify` and `release verify-asset` is required;
+missing support or authentication errors fail closed.
+
+This workflow blocks npm publication, not a GitHub Release that was already
+published. It does **not** add assets after an immutable release is published.
+The `stage` command implements the draft-asset producer: it verifies qualification,
+checks immutability without changing settings, resolves the existing tag to the
+qualified commit, uploads the archive and digest-bound qualification receipt,
+rechecks uploaded digests, then publishes and verifies the release. It requires
+an existing draft and existing tag; it never creates/moves tags or overwrites
+conflicting assets. Settings permission failures block writes. Matching existing
+assets can resume staging; conflicting assets require manual reconciliation.
+The pre-release gate in #544 supplies the required matrix reports.
+The legacy Release Please workflow creates releases without
+this archive staging step. Wire the new `stage` command into a draft-producing
+caller instead of pointing the old direct-release caller at the new publisher:
+
+```sh
+node src/commands/qualified-publication.mjs stage \
+  "$GITHUB_REPOSITORY" "$TAG" "$SOURCE_SHA" "$ASSET" "$CANDIDATE_DIRECTORY" \
+  "$REPORT_NODE_20" "$REPORT_NODE_22" "$REPORT_NODE_24"
+```
+
+The stage command needs a credential with immutable-setting read, release
+write, and attestation-read access; a normal Actions token may lack the
+administration-read permission.
+No elevated credential is installed or requested automatically. The producer must
+also prevent concurrent tag mutation (for example with protected release-tag
+rules and a single tag-scoped producer); GitHub does not offer an atomic
+"publish this draft only if the tag still resolves to SHA" operation. The final
+verification blocks npm if that invariant is violated, but cannot undo an
+already-published immutable release.
+
+Disable the old npm path before
+activating the replacement to prevent racing publishers. None of those production
+settings or existing release workflows are changed in this PR.
+
+Example caller job after its release producer (illustrative job IDs):
+
+```yaml
+permissions:
+  actions: read
+  attestations: read
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    needs: release-producer
+    uses: ./.github/workflows/qualified-foundry-publish.yml
+    with:
+      tag: ${{ needs.release-producer.outputs.tag }}
+      asset: ${{ needs.release-producer.outputs.npm-asset }}
+      environment: npm
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Only main-branch `push` and `workflow_dispatch` callers are admitted. Pull-request
+events (including fork PRs), release-event shortcuts, and billing-paused runs
+cannot publish through this workflow. The event guard does not itself verify
+branch protection or prohibit a fork's independent main-branch workflow; configure
+branch/environment protections and registry publisher identity separately.
+The tag must resolve to `github.sha`, not a caller-selected old commit. To retry
+an older release after main moves, use a separately reviewed recovery procedure;
+do not weaken the identity gate ad hoc.
+
+## Local policy tests and trust
+
+`node --test test/qualified-publication.test.mjs` uses CLI/verifier fixtures to
+exercise missing matrix members, skipped checks, absent Actionlint, changed
+archives, invalid asset names, wrong package identity, and prevention of npm
+execution before verification. These tests do not establish live GitHub signing,
+OIDC permissions, registry publication, or runner tool availability.
+
+Qualification reports are not standalone signatures: they are trusted only after
+selection from this workflow's successful jobs in the same run attempt. Supplying
+arbitrary local JSON to the library is not a security boundary. The reusable
+workflow and its caller must be reviewed/trusted and protected; repository-owned
+code executes with the permissions of its job. No credentials or production
+resources were configured by adding this feature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "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) {