code-foundry 1.14.0 → 1.16.0

package/.github/actions/attest-artifact/action.yml

@@ -0,0 +1,56 @@
+name: Attest verified build artifacts
+description: Generate checksums and signed provenance for explicitly selected build outputs.
+inputs:
+  artifacts:
+    description: 'JSON array of nonempty regular artifact files relative to the workspace.'
+    required: true
+outputs:
+  manifest-path:
+    description: Path to the generated SHA-256 JSON manifest.
+    value: ${{ steps.manifest.outputs.manifest-path }}
+  bundle-path:
+    description: Path to the signed provenance bundle.
+    value: ${{ steps.attest.outputs.bundle-path }}
+  attestation-url:
+    description: URL of the published attestation.
+    value: ${{ steps.attest.outputs.attestation-url }}
+runs:
+  using: composite
+  steps:
+    - name: Select and hash build outputs
+      id: manifest
+      shell: bash
+      env:
+        ARTIFACTS: ${{ inputs.artifacts }}
+      run: |
+        set -euo pipefail
+        [[ "$GITHUB_EVENT_NAME" != pull_request && "$GITHUB_EVENT_NAME" != pull_request_target ]]
+        node --input-type=module <<'NODE'
+        import { appendFileSync, mkdtempSync, writeFileSync } from 'node:fs'
+        import { join, resolve } from 'node:path'
+        import { pathToFileURL } from 'node:url'
+        const helper = pathToFileURL(resolve(process.env.GITHUB_ACTION_PATH, '../../../src/commands/release-integrity.mjs'))
+        const { assetManifest } = await import(helper.href)
+        const files = JSON.parse(process.env.ARTIFACTS)
+        if (!Array.isArray(files) || files.some(file => typeof file !== 'string')) throw new Error('artifacts must be a JSON string array')
+        const manifest = assetManifest(process.env.GITHUB_WORKSPACE, files)
+        const directory = mkdtempSync(join(process.env.RUNNER_TEMP, 'foundry-attestation-'))
+        const manifestPath = join(directory, 'manifest.json')
+        const sumsPath = join(directory, 'SHA256SUMS')
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+        writeFileSync(sumsPath, manifest.checksums)
+        appendFileSync(process.env.GITHUB_OUTPUT, `manifest-path=${manifestPath}\nchecksums-path=${sumsPath}\n`)
+        NODE
+    - name: Sign build provenance
+      id: attest
+      uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3
+      with:
+        subject-checksums: ${{ steps.manifest.outputs.checksums-path }}
+    - name: Verify artifacts were not changed during signing
+      shell: bash
+      env:
+        CHECKSUMS_PATH: ${{ steps.manifest.outputs.checksums-path }}
+      run: |
+        set -euo pipefail
+        cd "$GITHUB_WORKSPACE"
+        sha256sum --check "$CHECKSUMS_PATH"

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

@@ -0,0 +1,95 @@
+name: Consumer Qualification
+
+on:
+  workflow_call:
+    inputs:
+      billing-pause-bypass:
+        description: Allow an explicitly dispatched release to qualify while shared CI remains paused.
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  actions: read
+  contents: read
+
+jobs:
+  pack:
+    name: Pack candidate once
+    if: vars.CI_BILLING_PAUSED != 'true' || inputs['billing-pause-bypass'] == true
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    outputs:
+      filename: ${{ steps.pack.outputs.filename }}
+    steps:
+      - name: Checkout candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Setup packaging Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '24'
+      - name: Pack the distributable once
+        id: pack
+        run: |
+          set -euo pipefail
+          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"
+      - name: Retain the shared candidate
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: qualification-candidate-${{ github.run_id }}
+          path: ${{ runner.temp }}/candidate/*
+          if-no-files-found: error
+          overwrite: true
+          retention-days: 14
+
+  qualify:
+    name: Node ${{ matrix.node }}
+    needs: pack
+    if: vars.CI_BILLING_PAUSED != 'true' || inputs['billing-pause-bypass'] == true
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ['20', '22', '24']
+    steps:
+      - name: Checkout qualification runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Retrieve the shared archive from this attempt
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh run download "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" \
+            --name "qualification-candidate-$GITHUB_RUN_ID" \
+            --dir "$RUNNER_TEMP/candidate"
+      - 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"
+      - 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
+          retention-days: 14

package/.github/workflows/consumer-qualification_self-ci.yml

@@ -0,0 +1,19 @@
+name: Qualification
+
+on:
+  pull_request:
+    branches: [main]
+    types: [ready_for_review]
+
+permissions:
+  actions: read
+  contents: read
+
+concurrency:
+  group: qualification-${{ github.event_name }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  consumers:
+    if: vars.CI_BILLING_PAUSED != 'true' && github.event.pull_request.draft == false
+    uses: ./.github/workflows/consumer-qualification.yml

package/.github/workflows/release-integrity.yml

@@ -0,0 +1,63 @@
+name: Code Foundry Release Integrity
+on:
+  workflow_call:
+    inputs:
+      runtime-ref:
+        description: Exact Code Foundry tag or SHA containing the verifier.
+        required: true
+        type: string
+      tag:
+        description: Exact published release tag in the caller repository.
+        required: true
+        type: string
+      expected-sha:
+        description: Optional full expected source commit SHA.
+        required: false
+        type: string
+        default: ''
+    outputs:
+      source-sha:
+        description: Verified immutable tag commit.
+        value: ${{ jobs.verify.outputs.source-sha }}
+permissions:
+  contents: read
+  attestations: read
+jobs:
+  verify:
+    if: vars.CI_BILLING_PAUSED != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      source-sha: ${{ steps.verify.outputs.source-sha }}
+    steps:
+      - name: Validate runtime pin
+        env:
+          RUNTIME_REF: ${{ inputs.runtime-ref }}
+        run: '[[ "$RUNTIME_REF" =~ ^(v[0-9]+\.[0-9]+\.[0-9]+|[0-9a-fA-F]{40})$ ]]'
+      - name: Checkout verifier, not release-owned executable code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          repository: 0xPlayerOne/code-foundry
+          ref: ${{ inputs.runtime-ref }}
+          persist-credentials: false
+          sparse-checkout: src/commands
+      - name: Verify immutable release and signed attestation
+        id: verify
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+          EXPECTED_SHA: ${{ inputs.expected-sha }}
+        run: |
+          set -euo pipefail
+          args=(release --repo "$GITHUB_REPOSITORY" --tag "$RELEASE_TAG")
+          if [ -n "$EXPECTED_SHA" ]; then args+=(--expected-sha "$EXPECTED_SHA"); fi
+          node src/commands/release-integrity.mjs "${args[@]}" > "$RUNNER_TEMP/release-integrity.json"
+          node -e 'const fs = require("node:fs"); const r = JSON.parse(fs.readFileSync(process.env.RUNNER_TEMP + "/release-integrity.json")); fs.appendFileSync(process.env.GITHUB_OUTPUT, "source-sha=" + r.sourceSha + "\n")'
+      - name: Preserve verification evidence
+        if: always() && steps.verify.outcome != 'skipped'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: release-integrity-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/release-integrity.json
+          if-no-files-found: error
+          retention-days: 30

package/.github/workflows/release-integrity_self-ci.yml

@@ -0,0 +1,22 @@
+name: Verify Code Foundry Release Integrity
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Published immutable release tag to verify.
+        required: true
+        type: string
+permissions:
+  contents: read
+  attestations: read
+jobs:
+  verify:
+    # Enable only after an administrator enables immutable releases. This is a
+    # post-publication verifier, not a substitute for the GitHub repository setting.
+    if: vars.CI_BILLING_PAUSED != 'true' && (vars.REQUIRE_IMMUTABLE_RELEASES == 'true' || github.event_name == 'workflow_dispatch')
+    uses: ./.github/workflows/release-integrity.yml
+    with:
+      runtime-ref: ${{ github.sha }}
+      tag: ${{ github.event.release.tag_name || inputs.tag }}

package/.github/workflows/release_self-ci.yml

@@ -19,8 +19,18 @@ permissions:
   id-token: write
 
 jobs:
+  qualification:
+    name: Qualify consumers
+    if: vars.CI_BILLING_PAUSED != 'true' || (github.event_name == 'workflow_dispatch' && inputs['release-while-paused'] == true)
+    uses: ./.github/workflows/consumer-qualification.yml
+    with:
+      billing-pause-bypass: ${{ github.event_name == 'workflow_dispatch' && inputs['release-while-paused'] == true }}
+    permissions:
+      actions: read
+      contents: read
   release:
     name: Release
+    needs: qualification
     if: vars.CI_BILLING_PAUSED != 'true' || (github.event_name == 'workflow_dispatch' && inputs['release-while-paused'] == true)
     uses: ./.github/workflows/release.yml
     with:

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.16.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.15.0...v1.16.0) (2026-09-09)
+
+
+### Features
+
+* **qualification:** gate releases on installed consumer compatibility ([#544](https://github.com/0xPlayerOne/code-foundry/issues/544)) ([33c759b](https://github.com/0xPlayerOne/code-foundry/commit/33c759be8c78c633f55a58dc6144986758676336))
+
+## [1.15.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.14.0...v1.15.0) (2026-09-09)
+
+
+### Features
+
+* **releases:** verify immutable releases and attest selected build artifacts ([#537](https://github.com/0xPlayerOne/code-foundry/issues/537)) ([099aa57](https://github.com/0xPlayerOne/code-foundry/commit/099aa577227ab067a9a554e4cfc286aa2f5eb38e))
+
 ## [1.14.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.13.0...v1.14.0) (2026-09-09)
 
 

package/README.md

@@ -127,7 +127,8 @@ first. Either way, Release Please creates a GitHub release after the version
 PR is merged. npm publication is opt-in through `npm_publish: true` and
 supports npm trusted publishing or an `NPM_TOKEN` fallback.
 
-Read [Release management](docs/RELEASES.md) and
+Read [Release management](docs/RELEASES.md),
+[Release integrity and build provenance](docs/release-integrity.md), and
 [Publishing packages](docs/PUBLISHING.md) before enabling automated
 publishing. They are intentionally written with placeholders so they can be
 copied into other repositories.

package/docs/PERFORMANCE.md

@@ -15,14 +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                     | 210 kB | Bound registry transfer and install cost             |
-| Unpacked artifact                   | 820 kB | Bound installed footprint                            |
-| Packed files                        |     92 | Detect accidental release contents                   |
+| Packed artifact                     | 225 kB | Bound registry transfer and install cost             |
+| Unpacked artifact                   | 860 kB | Bound installed footprint                            |
+| Packed files                        |    100 | 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.
+
 ## v1.6.1 baseline
 
 Measurements were taken on 2026-09-08 with Node 24.18.0. Process startup used

package/docs/README.md

@@ -10,6 +10,7 @@ its own names, environments, and deployment details.
 - [Configuration reference](CONFIGURATION.md)
 - [Workflow and CI conventions](WORKFLOWS.md)
 - [Release management](RELEASES.md)
+- [Release integrity and build provenance](release-integrity.md)
 - [Publishing packages](PUBLISHING.md)
 - [Caching and remote caching](CACHING.md)
 - [Performance budgets and baselines](PERFORMANCE.md)

package/docs/consumer-qualification.md

@@ -0,0 +1,48 @@
+# Consumer Qualification
+
+Release-candidate compatibility checks against the distributable package.
+
+**Status:** Opt-in reusable workflow; required by Code Foundry's own release caller.
+**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,
+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.
+
+The matrix covers npm, pnpm, Yarn, Bun, direct and staging-release topologies,
+authored documentation and workflows, an existing mise selection, and nested
+Rust/Python manifests. It checks detected package managers, byte preservation,
+and two successive no-change synchronizations. Lockfiles are detection fixtures:
+this suite does not claim to install or execute every ecosystem toolchain.
+Repository unit/policy suites and real consumer canaries remain required.
+
+Actionlint checks copies of generated callers against the candidate's local
+reusable workflows. Only exact candidate repository/ref calls are localized;
+production callers and custom workflows are never edited by this step. Shellcheck
+and Pyflakes are disabled here because this gate tests Actions contracts; existing
+shell/security validation remains independent. Actionlint is pinned to v1.7.12.
+
+```sh
+npm pack --ignore-scripts --pack-destination /tmp/candidate
+node src/lib/consumer-qualification.mjs \
+  /tmp/candidate/code-foundry-VERSION.tgz \
+  "$(git rev-parse HEAD)" /tmp/qualification.json /absolute/path/to/actionlint
+```
+
+The JSON report binds the result to the source SHA, archive SHA-256, Node version,
+and completed fixtures. Failed runs retain `complete: false`. Running without
+Actionlint is a local structural probe only (`actionlint: false`), not release
+qualification. Downstream eligibility must require both `complete` and
+`actionlint`, the expected source/digest, and successful reports for every matrix
+member. Reports are evidence, not signatures or a substitute for release identity
+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
+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.

package/docs/release-integrity.md

@@ -0,0 +1,140 @@
+# Release integrity and build provenance
+
+Code Foundry now provides a read-only immutable-setting preflight, cryptographic
+release/asset verification, and an optional build-provenance action. These are
+separate guarantees: a checksum identifies bytes, an attestation identifies their
+origin, and GitHub's immutable-release setting prevents replacement after publish.
+
+## Enable immutable releases explicitly
+
+An administrator must enable **Settings → General → Releases → Enable release
+immutability**. This applies only to future releases. Existing mutable releases
+are not retroactively frozen, and this implementation does not change the setting.
+After enabling it, set the repository variable `REQUIRE_IMMUTABLE_RELEASES=true`
+to activate Code Foundry's post-publication verification caller. Manual dispatch
+can verify an explicitly selected tag without the variable. Billing pause is
+honored by both workflows. A skipped workflow is not verification evidence.
+
+Publish all assets to a draft release **before** publishing it. Do not attach or
+replace assets after an immutable release is published. The existing Release
+Please/npm workflow is not rewritten by this change; repositories adding release
+assets must review their attachment ordering before enabling immutability.
+
+A release workflow can run this preflight before publication:
+
+```sh
+npx code-foundry release-integrity settings --repo owner/repository
+```
+
+The setting endpoint needs an authenticated identity with repository
+Administration **read** permission. Do not grant Administration write for this
+check. The ordinary Actions token may be unable to read it. Inaccessible,
+unsupported, malformed, or disabled settings fail as unverified; a 404 is not
+silently interpreted as proof that a setting is absent. No setting writes exist
+in the verifier.
+
+## Verify published releases and local assets
+
+```sh
+npx code-foundry release-integrity release \
+  --repo owner/repository --tag v1.2.3 \
+  --expected-sha FULL_40_CHARACTER_COMMIT_SHA \
+  --asset dist/package.tgz
+```
+
+`--expected-sha` and repeatable `--asset` are optional. Verification requires the
+exact published tag to be immutable, invokes `gh release verify` for signed
+release-attestation validation, resolves lightweight/annotated tags to a commit,
+and optionally checks that commit against the expected source. Each local asset
+is checked with `gh release verify-asset`, and hashed before/after verification to
+reject replacement during the check. GitHub-generated source archives are not
+supported release assets for this command; verify uploaded binaries/packages.
+The GitHub CLI must support these subcommands; an older CLI fails rather than
+falling back to a metadata-only claim. The verifier targets github.com explicitly.
+
+JSON is emitted on stdout with a nonzero exit status on failure. No credential or
+raw failed API response is included in the report. Selected assets must be
+nonempty regular files inside the repository, without symlink components.
+
+`sync` installs an opt-in release-event caller in
+`.github/workflows/release-integrity.yml`; set `REQUIRE_IMMUTABLE_RELEASES=true`
+to enable it. To call the reusable workflow directly, pin both references to the
+same reviewed tag or commit:
+
+```yaml
+permissions:
+  contents: read
+  attestations: read
+jobs:
+  verify-release:
+    uses: 0xPlayerOne/code-foundry/.github/workflows/release-integrity.yml@REVIEWED_REF
+    with:
+      runtime-ref: REVIEWED_REF
+      tag: v1.2.3
+      expected-sha: FULL_40_CHARACTER_COMMIT_SHA
+```
+
+`runtime-ref`, `tag`, and optional `expected-sha` are the workflow inputs. The job
+checks out only the selected verifier, not executable code from the release under
+test, needs `contents: read` and `attestations: read`, preserves evidence, and
+exposes the verified `source-sha`. Downstream publication or consumer steps should
+explicitly `needs` this job when verification is their gate. Code Foundry's own
+release-event caller verifies **after publication**; it cannot prevent a release
+that has already been published. Actual immutability comes from the repository
+setting.
+
+## Optional build provenance
+
+In the same trusted job that builds the artifacts, grant `contents: read`,
+`id-token: write`, and `attestations: write`, then call:
+
+```yaml
+- name: Attest built package
+  # Replace REVIEWED_SHA with the reviewed Code Foundry commit.
+  uses: 0xPlayerOne/code-foundry/.github/actions/attest-artifact@REVIEWED_SHA
+  id: provenance
+  with:
+    artifacts: '["dist/package.tgz"]'
+```
+
+The action hashes only the explicitly selected files, generates a checksum
+manifest, signs those digests with the commit-pinned official GitHub provenance
+action, and checks the files have not changed during signing. Its outputs provide
+the manifest, signed bundle, and attestation URL. Persist the manifest and bundle
+alongside build evidence; attach release assets before publishing an immutable
+release. The action refuses PR event contexts. Repository-owned build scripts
+must still be trusted: signing attacker-controlled downloaded bytes does not
+prove that this job built them. Do not place attestation into an unrelated job
+that merely downloads and re-labels artifacts from another build.
+
+Artifact attestations require GitHub support for the repository/account. Never
+silently skip a required attestation because the account lacks that capability.
+Consumers should use `gh attestation verify` with the expected source repository
+and trusted signer workflow as appropriate; digest equality alone is insufficient.
+This action covers local file artifacts, not registry image publishing. npm
+trusted publishing remains available through the existing release workflow; this
+change does not replace or require an npm token.
+
+Generate a local unsigned manifest without GitHub/network access with:
+
+```sh
+npx code-foundry release-integrity manifest --asset dist/package.tgz
+```
+
+That command makes no provenance or authenticity claim.
+
+## Validation and references
+
+Run `node --test test/release-integrity.test.mjs`. Tests cover exact command
+contracts, signature-verifier invocation, tag identity, asset replacement/path
+safety, settings uncertainty, sync-installed caller wiring, and pinned/read-only
+workflow structure using CLI fixtures. Real signing and release verification
+require a supported authenticated GitHub environment and must be exercised there
+before rollout.
+
+- https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases
+- https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/verify-release-integrity
+- https://cli.github.com/manual/gh_release_verify
+- https://cli.github.com/manual/gh_release_verify-asset
+- https://docs.github.com/en/rest/repos/repos#get-immutable-releases-settings
+- https://docs.github.com/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.14.0",
+  "version": "1.16.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, releaseSubcommand?: string, fleetSubcommand?: string, ciSubcommand?: 'pause'|'resume'|'status' }} Options */
+/** @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 {{ command: string, options: Options }} ParsedArgs */
 
 const usage = `code-foundry — initialize and maintain agent-ready repositories
@@ -21,6 +21,9 @@ Usage:
   npx code-foundry ci pause|resume|status [--target PATH]
   npx code-foundry release reconcile [--github] [--base BRANCH] [--head BRANCH]
   npx code-foundry release hook --tag TAG --workflow WORKFLOW
+  npx code-foundry release-integrity settings --repo OWNER/REPO
+  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]
 
@@ -38,6 +41,9 @@ Options:
   --tag TAG       Published release tag for a post-release hook
   --workflow FILE  Workflow to dispatch for a post-release hook
   --mode MODE     auto, workflow-dispatch, release-event, or disabled
+  --repo OWNER/REPO  GitHub repository for release-integrity commands
+  --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)
   --create-pr     Create isolated upgrade branches and pull requests
   --version TAG   Runtime tag to report in fleet upgrade branches
@@ -71,6 +77,10 @@ function parseArgs(argv) {
     workflow: '',
     mode: 'auto',
     version: `v${readPackageVersion(packageRoot)}`,
+    repository: '',
+    expectedSha: '',
+    assets: [],
+    rootProvided: false,
   }
 
   if (command === 'release') {
@@ -80,6 +90,13 @@ function parseArgs(argv) {
         `unknown release command: ${subcommand ?? '(missing)'}; use release reconcile, release hook, release validate-prs, or release recovery-plan`
       )
     options.releaseSubcommand = subcommand
+  } else if (command === 'release-integrity') {
+    const subcommand = argv.shift() ?? ''
+    if (!['settings', 'release', 'manifest'].includes(subcommand))
+      fail(
+        `unknown release-integrity command: ${subcommand || '(missing)'}; use release-integrity settings, release, or manifest`
+      )
+    options.integritySubcommand = /** @type {'settings'|'release'|'manifest'} */ (subcommand)
   } else if (command === 'fleet') {
     const subcommand = argv.shift() ?? ''
     if (subcommand !== 'status' && subcommand !== 'upgrade')
@@ -110,12 +127,26 @@ function parseArgs(argv) {
     else if (arg === '--base') options.base = argv.shift() ?? fail('--base requires a branch')
     else if (arg === '--head') options.head = argv.shift() ?? fail('--head requires a branch')
     else if (arg === '--tag') options.tag = argv.shift() ?? fail('--tag requires a tag')
-    else if (arg === '--workflow')
+    else if (arg === '--repo') {
+      if (command !== 'release-integrity')
+        fail('--repo is only supported by release-integrity commands')
+      options.repository = argv.shift() ?? fail('--repo requires OWNER/REPO')
+    } else if (arg === '--expected-sha') {
+      if (command !== 'release-integrity')
+        fail('--expected-sha is only supported by release-integrity commands')
+      options.expectedSha = argv.shift() ?? fail('--expected-sha requires a commit SHA')
+    } else if (arg === '--asset') {
+      if (command !== 'release-integrity')
+        fail('--asset is only supported by release-integrity commands')
+      options.assets.push(argv.shift() ?? fail('--asset requires a path'))
+    } else if (arg === '--workflow')
       options.workflow = argv.shift() ?? fail('--workflow requires a workflow')
     else if (arg === '--mode')
       options.mode = argv.shift() ?? fail('--mode requires a delivery mode')
-    else if (arg === '--root') options.root = argv.shift() ?? fail('--root requires a path')
-    else if (arg === '--create-pr') options.createPr = true
+    else if (arg === '--root') {
+      options.root = argv.shift() ?? fail('--root requires a path')
+      options.rootProvided = true
+    } 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')
       options.exclude.push(argv.shift() ?? fail('--exclude requires a name'))
@@ -177,6 +208,32 @@ async function main() {
     } catch (error) {
       fail(error instanceof Error ? error.message : String(error))
     }
+  } else if (command === 'release-integrity') {
+    try {
+      const { integrityCommand } = await import('./commands/release-integrity.mjs')
+      const integrityArgs = /** @type {string[]} */ ([options.integritySubcommand])
+      if (options.repository) integrityArgs.push('--repo', options.repository)
+      if (options.tag) integrityArgs.push('--tag', options.tag)
+      if (options.expectedSha) integrityArgs.push('--expected-sha', options.expectedSha)
+      if (options.rootProvided || options.integritySubcommand !== 'settings')
+        integrityArgs.push('--root', options.root)
+      for (const asset of options.assets) integrityArgs.push('--asset', asset)
+      console.log(JSON.stringify(integrityCommand(integrityArgs), null, 2))
+    } catch (error) {
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            kind: 'code-foundry-release-integrity',
+            status: 'failed',
+            reason: error instanceof Error ? error.message : String(error),
+          },
+          null,
+          2
+        )
+      )
+      process.exitCode = 1
+    }
   } else if (command === 'fleet') {
     try {
       const { discoverRepositories, upgradeFleet } = await import('./commands/fleet.mjs')

package/src/commands/release-integrity.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { createHash } from 'node:crypto'
+import { lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+
+/** @typedef {(argv: string[]) => {status: number|null, stdout: string}} Runner */
+
+/** @type {Runner} */
+export function runGh(argv) {
+  const result = spawnSync('gh', argv, {
+    encoding: 'utf8',
+    timeout: 120000,
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_HOST: 'github.com' },
+  })
+  if (result.error) throw new Error(`GitHub CLI unavailable: ${result.error.name}`)
+  return { status: result.status, stdout: result.stdout ?? '' }
+}
+
+/** @param {string} repository */
+function validateRepository(repository) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/.test(repository) ||
+    repository.split('/').some((part) => ['.', '..'].includes(part))
+  )
+    throw new Error('repository must be an owner/name on github.com')
+}
+
+/** @param {string} tag */
+function validateTag(tag) {
+  const hasInvalidCharacter = tag
+    ? [...tag].some((character) => {
+        const codePoint = character.codePointAt(0)
+        return (
+          (codePoint !== undefined && (codePoint <= 0x20 || codePoint === 0x7f)) ||
+          '~^:?*[\\'.includes(character)
+        )
+      })
+    : false
+  if (
+    !tag ||
+    tag.startsWith('-') ||
+    hasInvalidCharacter ||
+    tag.includes('..') ||
+    tag.includes('@{')
+  )
+    throw new Error('Invalid release tag')
+}
+
+/** @param {Runner} run @param {string[]} argv */
+function json(run, argv) {
+  const result = run(argv)
+  if (result.status !== 0)
+    throw new Error(
+      `GitHub verification command failed (${result.status ?? 'signal'}); state is unverified`
+    )
+  try {
+    return JSON.parse(result.stdout)
+  } catch {
+    throw new Error('GitHub verification returned invalid JSON; state is unverified')
+  }
+}
+
+/** @param {Runner} run @param {string} endpoint */
+function api(run, endpoint) {
+  return json(run, ['api', '--hostname', 'github.com', endpoint])
+}
+
+/** Read only. A permissions failure is unknown, never evidence of disabled settings.
+ * @param {string} repository @param {Runner} [run]
+ */
+export function verifyImmutableSetting(repository, run = runGh) {
+  validateRepository(repository)
+  const result = api(run, `repos/${repository}/immutable-releases`)
+  if (result?.enabled !== true) throw new Error('Release immutability is not confirmed enabled')
+  return {
+    schemaVersion: 1,
+    kind: 'code-foundry-release-integrity',
+    status: 'passed',
+    repository,
+    check: 'immutable-setting',
+    enforcedByOwner: result.enforced_by_owner === true,
+  }
+}
+
+/** @param {string} root @param {string} file */
+export function assetDigest(root, file) {
+  if (!file || isAbsolute(file)) throw new Error('Asset paths must be repository-relative')
+  const base = realpathSync(root)
+  const path = resolve(base, file)
+  const rel = relative(base, path)
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`))
+    throw new Error('Asset path escapes repository')
+  let current = base
+  for (const part of rel.split(sep)) {
+    current = resolve(current, part)
+    if (lstatSync(current).isSymbolicLink()) throw new Error('Release assets must not be symlinks')
+  }
+  if (!lstatSync(path).isFile()) throw new Error('Release asset must be a regular file')
+  const content = readFileSync(path)
+  if (!content.length) throw new Error('Release asset is empty')
+  return {
+    file: rel.split(sep).join('/'),
+    name: basename(path),
+    bytes: content.length,
+    digest: `sha256:${createHash('sha256').update(content).digest('hex')}`,
+    path,
+  }
+}
+
+/** @param {string} root @param {string[]} files */
+export function assetManifest(root, files) {
+  if (!files.length) throw new Error('At least one artifact is required')
+  const assets = files.map((file) => assetDigest(root, file))
+  if (new Set(assets.map((asset) => asset.file)).size !== assets.length)
+    throw new Error('Duplicate artifact')
+  if (assets.some((asset) => /[\r\n\\]/.test(asset.file)))
+    throw new Error('Unsupported checksum filename')
+  return {
+    schemaVersion: 1,
+    kind: 'code-foundry-asset-manifest',
+    assets: assets.map(({ path: _path, ...asset }) => asset),
+    checksums: assets.map((asset) => `${asset.digest.slice(7)}  ${asset.file}\n`).join(''),
+  }
+}
+
+/** @param {Runner} run @param {string} repository @param {string} tag */
+function tagCommit(run, repository, tag) {
+  let object = api(run, `repos/${repository}/git/ref/tags/${encodeURIComponent(tag)}`).object
+  for (let depth = 0; object?.type === 'tag' && depth < 8; depth += 1) {
+    if (!/^[0-9a-f]{40}$/i.test(object.sha ?? '')) throw new Error('Malformed annotated tag')
+    object = api(run, `repos/${repository}/git/tags/${object.sha}`).object
+  }
+  if (object?.type !== 'commit' || !/^[0-9a-f]{40}$/i.test(object.sha ?? ''))
+    throw new Error('Release tag does not resolve to a commit')
+  return object.sha
+}
+
+/** GitHub CLI performs signature/attestation verification, not merely a metadata check.
+ * @param {{repository: string, tag: string, root?: string, assets?: string[], expectedSha?: string}} options
+ * @param {Runner} [run]
+ */
+export function verifyRelease(options, run = runGh) {
+  const { repository, tag } = options
+  validateRepository(repository)
+  validateTag(tag)
+  if (options.expectedSha && !/^[0-9a-f]{40}$/i.test(options.expectedSha))
+    throw new Error('expected-sha must be a full commit SHA')
+  const release = api(run, `repos/${repository}/releases/tags/${encodeURIComponent(tag)}`)
+  if (release?.immutable !== true || release.draft !== false || release.tag_name !== tag)
+    throw new Error('Expected a published immutable release with the exact requested tag')
+  json(run, ['release', 'verify', tag, '--repo', repository, '--format', 'json'])
+  const sourceSha = tagCommit(run, repository, tag)
+  if (options.expectedSha && options.expectedSha.toLowerCase() !== sourceSha.toLowerCase())
+    throw new Error('Release tag does not match the expected source SHA')
+  const assets = []
+  for (const file of options.assets ?? []) {
+    const asset = assetDigest(options.root ?? process.cwd(), file)
+    json(run, [
+      'release',
+      'verify-asset',
+      tag,
+      asset.path,
+      '--repo',
+      repository,
+      '--format',
+      'json',
+    ])
+    // Rehash after signature verification so a replaced local file is not reported verified.
+    if (assetDigest(options.root ?? process.cwd(), file).digest !== asset.digest)
+      throw new Error('Local release asset changed during verification')
+    assets.push({ file: asset.file, bytes: asset.bytes, digest: asset.digest, status: 'verified' })
+  }
+  return {
+    schemaVersion: 1,
+    kind: 'code-foundry-release-integrity',
+    status: 'passed',
+    check: 'release-attestation',
+    repository,
+    tag,
+    sourceSha,
+    immutable: true,
+    assets,
+  }
+}
+
+/** @param {string[]} argv @param {Runner} [run] */
+export function integrityCommand(argv, run = runGh) {
+  const [command, ...args] = argv
+  /** @type {Record<string, string>} */
+  const values = {}
+  const assets = []
+  while (args.length) {
+    const key = args.shift()
+    if (!key || !['--repo', '--tag', '--root', '--asset', '--expected-sha'].includes(key))
+      throw new Error(`Unknown argument: ${key}`)
+    const value = args.shift()
+    if (!value || value.startsWith('--')) throw new Error(`Missing value for ${key}`)
+    if (key === '--asset') assets.push(value)
+    else {
+      if (Object.hasOwn(values, key)) throw new Error(`Duplicate ${key}`)
+      values[key] = value
+    }
+  }
+  const allowed =
+    command === 'settings'
+      ? ['--repo']
+      : command === 'manifest'
+        ? ['--root']
+        : ['--repo', '--tag', '--root', '--expected-sha']
+  if (
+    Object.keys(values).some((key) => !allowed.includes(key)) ||
+    (command === 'settings' && assets.length)
+  )
+    throw new Error('An argument is not supported by this integrity command')
+  if (command === 'settings') return verifyImmutableSetting(values['--repo'] ?? '', run)
+  if (command === 'manifest') return assetManifest(values['--root'] ?? process.cwd(), assets)
+  if (command === 'release')
+    return verifyRelease(
+      {
+        repository: values['--repo'] ?? '',
+        tag: values['--tag'] ?? '',
+        root: values['--root'],
+        expectedSha: values['--expected-sha'],
+        assets,
+      },
+      run
+    )
+  throw new Error('Use release-integrity settings, release, or manifest')
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    console.log(JSON.stringify(integrityCommand(process.argv.slice(2)), null, 2))
+  } catch (error) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          kind: 'code-foundry-release-integrity',
+          status: 'failed',
+          reason: error instanceof Error ? error.message : String(error),
+        },
+        null,
+        2
+      )
+    )
+    process.exitCode = 1
+  }
+}

package/src/commands/sync.mjs

@@ -48,6 +48,7 @@ const standardFiles = [
   '.github/workflows/draft-pr.yml',
   '.github/workflows/release-pr.yml',
   '.github/workflows/release.yml',
+  '.github/workflows/release-integrity.yml',
   '.github/workflows/opencode-security.yml',
 ]
 
@@ -241,7 +242,15 @@ export function syncRepository(options) {
     }
     if (file.endsWith('.yml') && file.startsWith('.github/workflows/')) {
       content = Buffer.from(
-        renderWorkflow(content.toString('utf8'), config, runtimeRepository, runtimeRef, rustCodeql)
+        renderWorkflow(
+          content.toString('utf8'),
+          config,
+          runtimeRepository,
+          runtimeRef,
+          rustCodeql,
+          file,
+          target === source
+        )
       )
     }
     if (file === '.github/dependabot.yml') {
@@ -492,6 +501,7 @@ function shouldInclude(file, languages, features, config) {
   // without a configuration change. The detect job keeps the scan off unless
   // the configuration or the variable enables it and the API key exists.
   if (file === '.github/workflows/opencode-security.yml') return true
+  if (file === '.github/workflows/release-integrity.yml') return true
   const workflow = file.match(/^\.github\/workflows\/([^/]+)\.yml$/)?.[1]
   if (workflow === 'draft-control' || workflow === 'draft-enforcement') {
     return (
@@ -535,8 +545,10 @@ function sourcePath(source, file) {
  * @param {string} repository
  * @param {string} ref
  * @param {{ shards: string, threads: string, maxParallel: string }} rustCodeql
+ * @param {string} file
+ * @param {boolean} selfRepository
  */
-function renderWorkflow(content, config, repository, ref, rustCodeql) {
+function renderWorkflow(content, config, repository, ref, rustCodeql, file, selfRepository) {
   const localPrefix = 'uses: ./.github/workflows/'
   const remotePrefix = `uses: ${repository}/.github/workflows/`
   let rendered = content.replaceAll(localPrefix, remotePrefix)
@@ -576,7 +588,15 @@ function renderWorkflow(content, config, repository, ref, rustCodeql) {
     'release-pr': config.pr_runner ?? config.runner,
     release: config.release_runner ?? config.runner,
   }
-  const workflow = content.match(/\.github\/workflows\/([^/]+)\.yml/)?.[1]
+  const workflow = file.match(/^\.github\/workflows\/([^/]+)\.yml$/)?.[1]
+  // Consumer release callers are generic package release workflows. The
+  // installed-consumer qualification harness is specific to Code Foundry's
+  // own package and must remain in the self workflow rather than being
+  // rendered into every consumer's release caller.
+  if (workflow === 'release' && !selfRepository) {
+    rendered = removeWorkflowBlock(rendered, 'qualification')
+    rendered = removeWorkflowNeed(rendered, 'release', 'qualification')
+  }
   // The staging-release topology validates and scans pull requests against
   // both main and the integration branch; direct repositories only ever
   // target main, so their callers trigger on main alone.
@@ -667,6 +687,26 @@ function removeWorkflowBlock(content, blockId) {
   return lines.join('\n')
 }
 
+/**
+ * Remove a single root-job dependency while preserving the rest of the job.
+ * @param {string} content
+ * @param {string} jobId
+ * @param {string} dependency
+ * @returns {string}
+ */
+function removeWorkflowNeed(content, jobId, dependency) {
+  const lines = content.split('\n')
+  const start = lines.findIndex((line) => line === `  ${jobId}:`)
+  if (start === -1) return content
+  let end = start + 1
+  while (end < lines.length && !/^  [A-Za-z0-9_-]+:\s*$/.test(lines[end])) end += 1
+  const need = lines.findIndex(
+    (line, index) => index > start && index < end && line === `    needs: ${dependency}`
+  )
+  if (need >= 0) lines.splice(need, 1)
+  return lines.join('\n')
+}
+
 /**
  * Dependabot updates land on the repository's integration branch. Direct
  * repositories have no staging branch, so every update targets main. Cargo,

package/src/lib/consumer-qualification.mjs

@@ -0,0 +1,273 @@
+// @ts-check
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import {
+  cpSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** @param {string} file */
+export function digest(file) {
+  if (!lstatSync(file).isFile()) throw new Error(`Expected a regular file: ${file}`)
+  return createHash('sha256').update(readFileSync(file)).digest('hex')
+}
+
+/** Snapshot consumer-owned bytes, never Git metadata or dependency directories.
+ * @param {string} root @param {string} [prefix]
+ * @returns {Record<string, string>}
+ */
+export function snapshot(root, prefix = '') {
+  /** @type {Record<string, string>} */
+  const result = {}
+  for (const entry of readdirSync(join(root, prefix), { withFileTypes: true })) {
+    if (['.git', 'node_modules'].includes(entry.name)) continue
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name
+    if (entry.isSymbolicLink()) throw new Error(`Unexpected fixture symlink: ${name}`)
+    if (entry.isDirectory()) Object.assign(result, snapshot(root, name))
+    else if (entry.isFile()) result[name] = digest(join(root, name))
+  }
+  return result
+}
+
+/** @param {string} command @param {string[]} args @param {string} cwd */
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120_000,
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, CI: 'true', npm_config_update_notifier: 'false' },
+  })
+  if (result.error || result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(' ')} failed (${result.status ?? result.error?.message})\n${result.stderr}\n${result.stdout}`
+    )
+  }
+  return result.stdout
+}
+
+export const FIXTURES = [
+  { name: 'npm-direct', manager: 'npm', lock: 'package-lock.json', topology: 'direct' },
+  { name: 'pnpm-direct', manager: 'pnpm', lock: 'pnpm-lock.yaml', topology: 'direct' },
+  { name: 'yarn-staging', manager: 'yarn', lock: 'yarn.lock', topology: 'staging-release' },
+  { name: 'bun-mise', manager: 'bun', lock: 'bun.lock', topology: 'direct' },
+  { name: 'nested-rust', manager: '', lock: '', topology: 'direct' },
+  { name: 'nested-python', manager: '', lock: '', topology: 'direct' },
+]
+
+/** @param {string} root @param {(typeof FIXTURES)[number]} fixture */
+export function seedFixture(root, fixture) {
+  mkdirSync(join(root, '.github/workflows'), { recursive: true })
+  const authored = '# Consumer-owned instructions\n\nPreserve this paragraph exactly.\n'
+  writeFileSync(join(root, 'AGENTS.md'), authored)
+  writeFileSync(
+    join(root, '.github/workflows/custom.yml'),
+    'name: Custom\non: workflow_dispatch\njobs:\n  check:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo preserved\n'
+  )
+  writeFileSync(join(root, 'LICENSE'), 'Consumer-owned license\n')
+  if (fixture.manager) {
+    writeFileSync(
+      join(root, 'package.json'),
+      JSON.stringify(
+        {
+          name: `qualification-${fixture.name}`,
+          version: '0.0.0',
+          private: true,
+          scripts: { 'test:unit': 'node -e "process.exit(0)"' },
+        },
+        null,
+        2
+      ) + '\n'
+    )
+    const locks = {
+      npm: '{"name":"fixture","lockfileVersion":3,"packages":{}}\n',
+      pnpm: "lockfileVersion: '9.0'\nimporters: {}\n",
+      yarn: '# yarn lockfile v1\n',
+      bun: '{"lockfileVersion":1,"workspaces":{},"packages":{}}\n',
+    }
+    writeFileSync(
+      join(root, fixture.lock),
+      locks[/** @type {keyof typeof locks} */ (fixture.manager)]
+    )
+  } else if (fixture.name === 'nested-rust') {
+    mkdirSync(join(root, 'native/core/src'), { recursive: true })
+    writeFileSync(
+      join(root, 'native/core/Cargo.toml'),
+      '[package]\nname = "fixture"\nversion = "0.1.0"\nedition = "2021"\n'
+    )
+    writeFileSync(join(root, 'native/core/src/lib.rs'), 'pub fn value() -> u8 { 1 }\n')
+  } else {
+    mkdirSync(join(root, 'services/api'), { recursive: true })
+    writeFileSync(
+      join(root, 'services/api/pyproject.toml'),
+      '[project]\nname = "fixture"\nversion = "0.1.0"\n'
+    )
+    writeFileSync(join(root, 'services/api/app.py'), 'VALUE = 1\n')
+  }
+  if (fixture.name === 'bun-mise') writeFileSync(join(root, '.mise.toml'), '[tools]\nnode = "22"\n')
+  // Explicit topology only; init must still detect languages and lockfiles.
+  writeFileSync(
+    join(root, '.github/code-foundry.yml'),
+    `git_workflow: ${fixture.topology}\nmerge_strategy: ${fixture.topology === 'direct' ? 'squash' : 'rebase'}\nrelease_merge_strategy: ${fixture.topology === 'direct' ? 'squash' : 'rebase'}\n`
+  )
+}
+
+/** @param {string} value */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Localize only this candidate's remote workflow calls for Actionlint's local
+ * caller/callee contract checks. Production files are never rewritten.
+ * @param {string} text @param {string} repository @param {string} ref
+ */
+export function localizeCalls(text, repository, ref) {
+  const pattern = new RegExp(
+    `(uses:\\s*)${escapeRegExp(repository)}/\\.github/workflows/([A-Za-z0-9_.-]+)@${escapeRegExp(ref)}(?=\\s|$)`,
+    'g'
+  )
+  return text.replace(pattern, '$1./.github/workflows/$2')
+}
+
+/** @param {string} consumer @param {string} candidate @param {string} destination @param {string} actionlint @param {string} version */
+function lintContracts(consumer, candidate, destination, actionlint, version) {
+  mkdirSync(join(destination, '.github/workflows'), { recursive: true })
+  run('git', ['init', '-q'], destination)
+  cpSync(join(candidate, '.github'), join(destination, '.github'), { recursive: true })
+  // Event callers in the candidate are not reusable-workflow dependencies.
+  for (const name of readdirSync(join(destination, '.github/workflows'))) {
+    if (name.includes('_self-ci')) rmSync(join(destination, '.github/workflows', name))
+  }
+  const paths = []
+  for (const name of readdirSync(join(consumer, '.github/workflows'))) {
+    if (!/\.ya?ml$/.test(name)) continue
+    const target = join(destination, '.github/workflows', `consumer-${name}`)
+    const text = readFileSync(join(consumer, '.github/workflows', name), 'utf8')
+    writeFileSync(target, localizeCalls(text, '0xPlayerOne/code-foundry', `v${version}`))
+    paths.push(target)
+  }
+  // Check all candidate callees as well as rendered callers, without executing them.
+  const workflows = readdirSync(join(destination, '.github/workflows')).filter((name) =>
+    /\.ya?ml$/.test(name)
+  )
+  run(
+    actionlint,
+    [
+      '-shellcheck=',
+      '-pyflakes=',
+      ...workflows.map((name) => join(destination, '.github/workflows', name)),
+    ],
+    destination
+  )
+  return paths.length
+}
+
+/** @param {{ packageFile: string, sourceSha: string, reportPath: string, actionlint?: string }} options */
+export function qualifyCandidate(options) {
+  if (!/^[a-f0-9]{40}$/.test(options.sourceSha))
+    throw new Error('An exact 40-character source SHA is required')
+  const packageFile = resolve(options.packageFile)
+  const before = digest(packageFile)
+  const temporary = mkdtempSync(join(tmpdir(), 'code-foundry-qualification-'))
+  const report = {
+    schema_version: 1,
+    source_sha: options.sourceSha,
+    artifact_sha256: before,
+    node: process.version,
+    complete: false,
+    actionlint: Boolean(options.actionlint),
+    /** @type {Array<{ name: string, status: string }>} */ fixtures: [],
+  }
+  try {
+    const host = join(temporary, 'host')
+    mkdirSync(host)
+    writeFileSync(join(host, 'package.json'), '{"private":true}\n')
+    run(
+      'npm',
+      [
+        'install',
+        '--offline',
+        '--ignore-scripts',
+        '--no-audit',
+        '--no-fund',
+        '--package-lock=false',
+        packageFile,
+      ],
+      host
+    )
+    const candidate = join(host, 'node_modules/code-foundry')
+    const manifest = JSON.parse(readFileSync(join(candidate, 'package.json'), 'utf8'))
+    assert.equal(manifest.name, 'code-foundry')
+    assert.equal(manifest.bin?.['code-foundry'], 'src/cli.mjs')
+    const cli = join(candidate, 'src/cli.mjs')
+    assert.match(run(process.execPath, [cli, '--help'], host), /code-foundry/)
+    for (const fixture of FIXTURES) {
+      const root = join(temporary, fixture.name)
+      seedFixture(root, fixture)
+      run('git', ['init', '-q'], root)
+      const original = snapshot(root)
+      run(process.execPath, [cli, 'init', '--target', root], root)
+      assert.ok(
+        readFileSync(join(root, 'AGENTS.md'), 'utf8').startsWith(
+          '# Consumer-owned instructions\n\nPreserve this paragraph exactly.\n'
+        )
+      )
+      const initialized = snapshot(root)
+      for (const [name, hash] of Object.entries(original)) {
+        if (name === 'AGENTS.md' || name === '.github/code-foundry.yml') continue
+        assert.equal(initialized[name], hash, `${fixture.name}: authored ${name} was changed`)
+      }
+      if (fixture.manager)
+        assert.match(
+          readFileSync(join(root, '.github/code-foundry.yml'), 'utf8'),
+          new RegExp(`^package_manager: ${fixture.manager}$`, 'm')
+        )
+      for (let pass = 0; pass < 2; pass++) {
+        run(process.execPath, [cli, 'sync', '--target', root], root)
+        assert.deepEqual(snapshot(root), initialized, `${fixture.name}: sync is not idempotent`)
+      }
+      if (options.actionlint)
+        lintContracts(
+          root,
+          candidate,
+          join(temporary, `lint-${fixture.name}`),
+          options.actionlint,
+          manifest.version
+        )
+      report.fixtures.push({ name: fixture.name, status: 'passed' })
+    }
+    assert.equal(digest(packageFile), before, 'Candidate archive changed during qualification')
+    report.complete = true
+    return report
+  } finally {
+    mkdirSync(dirname(resolve(options.reportPath)), { recursive: true })
+    writeFileSync(options.reportPath, JSON.stringify(report, null, 2) + '\n')
+    rmSync(temporary, { recursive: true, force: true })
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [packageFile, sourceSha, reportPath, actionlint, ...extra] = process.argv.slice(2)
+    if (!packageFile || !sourceSha || !reportPath || extra.length)
+      throw new Error(
+        'Usage: node consumer-qualification.mjs PACKAGE.tgz SOURCE_SHA REPORT.json [ACTIONLINT]'
+      )
+    console.log(
+      JSON.stringify(qualifyCandidate({ packageFile, sourceSha, reportPath, actionlint }))
+    )
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}