code-foundry 1.20.2 → 1.25.3

package/docs/merge-queues.md

@@ -2,25 +2,25 @@
 
 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`.
+**Activation:** Set `merge_queue: true` in the consumer's
+`.github/code-foundry.yml`, then run `sync`.
+**Required check:** The canonical `Validation / Gate` aggregate check.
 
 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.
+explicitly enabled. Queue validation does not turn draft pushes into CI, mark
+pull requests ready, enqueue pull requests, or change release behavior. Queue
+events receive the full audit even when staging pull requests normally use fast
+validation. Release Please branch detection is not reused for a merge group
+containing several pull requests; the combined tree is audited as submitted.
 
 ```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
+Normal `npx 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.
@@ -60,8 +60,7 @@ Setting `merge_queue: false` or removing the key removes only a caller bearing t
 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.
+updating, or deleting the caller.
 
 Disable the repository's queue rule before removing its required queue workflow.
 Otherwise queued PRs will correctly wait for checks that no longer run.
@@ -74,16 +73,17 @@ 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.
+Enabling this workflow does not change repository rules, branch protection,
+secrets, merge settings, or the queue itself.
 
 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.
+preservation. They do not establish a live merge-group run or full sync
+integration. Before enabling the queue rule, run the complete sync/fleet tests,
+locked formatter, linter, type check, package budgets, and Actionlint against
+rendered callers and their pinned/local reusable workflow contracts. Exercise two
+queued pull requests 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/docs/product-quality.md

@@ -20,16 +20,15 @@ Commit a version-1 JSON manifest and use the installed, pinned Foundry runtime:
 
 Wire these scripts into the consumer's existing validation entrypoints. The
 Foundry runtime discovers only `performance:check`/`perf:check` and
-`test:e2e`/`e2e`; if those names do not already exist, they can run
-`bun run quality:build` and `bun run quality:browser`. If they do exist, preserve their current
-commands and compose the quality command after them rather than replacing the
-existing performance or E2E checks. The standalone entrypoint deliberately avoids
-changing the public CLI dispatch being introduced in the separate agent-validation
-PR. Install the reviewed Foundry version in the consumer's existing dependency
-manager and lockfile, not an unpinned network invocation. Add `.code-foundry/` to
-Git/package ignores and retain selected evidence through the consumer workflow's
-artifact uploader. Reports and browser traces may contain application data; review
-retention and never upload authenticated traces publicly without sanitization.
+`test:e2e`/`e2e`. If those names do not already exist, they can run
+`bun run quality:build` and `bun run quality:browser`. If they do exist, preserve
+their current commands and compose the quality command after them rather than
+replacing the existing performance or E2E checks. Install the reviewed Foundry
+version in the consumer's existing dependency manager and lockfile, not through
+an unpinned network invocation. Add `.code-foundry/` to Git/package ignores and
+retain selected evidence through the consumer workflow's artifact uploader.
+Reports and browser traces may contain application data; review retention and
+never upload authenticated traces publicly without sanitization.
 
 ```json
 {

package/docs/qualified-publication.md

@@ -1,72 +1,77 @@
-# 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):
+# Qualified publication
+
+Code Foundry publishes only the same immutable archive that passed consumer
+qualification. This path is used by Code Foundry's own release caller; generated
+consumer release callers keep the ordinary `release.yml` behavior.
+
+## Publication contract
+
+The self-release pipeline is intentionally staged:
+
+1. `consumer-qualification.yml` packs the candidate once and qualifies it across
+   Node 20, 22, and 24.
+2. Release Please creates a draft release for the qualified source.
+3. The staging job attaches the exact archive and a digest-bound qualification
+   receipt, publishes the immutable GitHub Release, and verifies its identity.
+4. `qualified-foundry-publish.yml` downloads that archive and the reports from
+   its own workflow run and attempt, requalifies all three Node versions, and
+   publishes the tarball.
+
+The reusable publisher downloads an explicitly named npm archive from the
+already-published immutable release, verifies the release and asset attestations
+against the caller's exact commit, and only then admits the npm publication job.
+The final job downloads only reports from its own workflow run and 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 serializes publication for a tag and has no dependency
+installation/build step. Qualification has no npm credential. This self-only
+publisher has no environment approval gate; publication is automatic after its
+completed gates. npm trusted publishing is preferred; an explicit optional token
+supports environments that cannot use it. 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.
+
+The publisher never rebuilds the package, publishes a directory, or treats an
+already-published version conflict as proof of success. The workflow uses npm
+trusted publishing when no `NPM_TOKEN` is supplied; the optional token is a
+fallback for environments that cannot use trusted publishing.
+
+Qualification and publication are gated on `main` push or an explicitly
+requested `workflow_dispatch`. The shared billing pause blocks normal runs. A
+manual release-only dispatch can pass `billing-pause-bypass: true` through the
+publisher, but it does not bypass environment approvals, branch protection, or
+identity checks.
+
+## Release producer requirements
+
+The producer must:
+
+- pack the candidate with lifecycle scripts disabled;
+- create or reuse a draft release for the exact package version;
+- attach the package archive before the release is published;
+- keep the tag at the qualified source commit;
+- enable and verify GitHub release immutability before publication; and
+- serialize release-tag mutation so two producers cannot race.
+
+The candidate package must be named `code-foundry`, and its version must match
+the explicit release tag. A recent GitHub CLI with `release verify` and
+`release verify-asset` support is required. Missing support, ambiguous release
+identity, unavailable permissions, changed assets, or conflicting assets fail
+closed.
+
+The generic reusable `release.yml` supports `defer-publication: true` for this
+producer pattern. That mode suppresses its legacy npm, reconciliation, and
+post-release jobs while exposing the release outputs needed by the self caller.
+Consumer callers do not inherit the self-only qualification and staging jobs.
+
+## Reusable publisher interface
+
+The caller supplies the tag and exact pre-attached archive name:
 
 ```yaml
 permissions:
@@ -74,6 +79,7 @@ permissions:
   attestations: read
   contents: read
   id-token: write
+
 jobs:
   publish:
     needs: release-producer
@@ -81,31 +87,98 @@ jobs:
     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.
+For the self repository, `release_self-ci.yml` supplies the release output and
+uses the protected `npm` environment. Configure trusted publishing for the
+actual caller/reusable-workflow relationship, not only for a similarly named
+workflow. Protect both the `release` and `npm` environments with the intended
+branch restrictions and approvals.
+
+## Identity and retry rules
+
+Every qualification report is bound to the source SHA, archive digest, Node
+version, and workflow attempt. The staging and publish jobs verify:
+
+- the tag resolves to the current `github.sha`;
+- the archive name and package identity are expected;
+- all required Node reports belong to the same run attempt;
+- the downloaded bytes match the qualified digest; and
+- the release and assets have not been replaced.
+
+On a failed or cancelled qualification, use **Re-run all jobs**. A failed-job-only
+rerun cannot safely reuse an earlier pack or combine reports from different
+attempts. Missing or expired artifacts require a fresh run.
+
+If Release Please reports that no new release was created, the recovery path may
+reuse an exact draft release only when its tag, version, source SHA, and draft
+state still match the qualified candidate. An already-published release is never
+restaged or overwritten. Inspect the retained staging and publication identity
+receipts when recovery is needed.
+
+## Publication prerequisites
+
+Enable immutable releases and verify the setting with the actual
+`CODE_FOUNDRY_TOKEN` (or workflow credential), then set
+`REQUIRE_IMMUTABLE_RELEASES=true`. Missing permissions, a disabled or unknown
+setting, or a CLI without release verification support fail before Release Please
+writes. Protect release tags against concurrent moves. The staging token needs
+administration-read, contents-write, and verification access; it is never exposed
+to qualification jobs. Preflight and staging reuse the producer's validated
+credential selection, falling back to the workflow token only when the configured
+token is rejected. Configure npm trusted-publisher identity for the actual
+caller/reusable-workflow relationship, or explicitly retain the optional npm
+token in the final publisher.
+
+## Trust boundaries
+
+Qualification reports are evidence selected from successful jobs in the same
+workflow attempt; they are not standalone signatures or authorization outside
+the protected workflow. The workflow executes repository-owned code with the
+permissions of its job. Keep credentials out of qualification jobs and review
+release/environment protections separately. A YAML environment reference does
+not prove that approval protections exist.
+
+Run the full locked-toolchain suite, Actionlint contracts, and a disposable-repo
+release/signing/registry rehearsal before production approval. The producer
+serializes the full release workflow and never cancels an active publish. The
+self caller auto-publishes after its gates without bypassing branch or review
+requirements for source changes.
+
+The staging command requires release-write, attestation-verification, and
+immutable-setting read access. No elevated credential is installed automatically.
+If the configured automation token is rejected, the producer's documented
+fallback is used only where the workflow permits it; missing permissions fail
+closed.
+
+Use **Re-run all jobs** for qualification failures; attempts cannot reuse earlier
+reports. If Release Please returns `release_created: false`, the recovery job
+looks up only the package version's draft release through the authenticated,
+paginated release list, resolves its tag, and resumes only when that tag still
+points to the newly qualified source. Staging uses the same list because GitHub's
+get-by-tag endpoint does not return draft releases. Missing or already published
+releases are a safe no-op; malformed, inaccessible, or source-mismatched drafts
+fail closed. Inspect the retained identity receipts. Once a release is
+published, do not attempt to re-stage or overwrite it: rerun the verified
+publisher from the same source-bound workflow after confirming npm has not already
+accepted that version. Never weaken the SHA guard, move an immutable tag, or treat
+npm's version-conflict response as success.
+
+## Validation
+
+Run the focused local suites before changing this path:
+
+```sh
+node --test test/consumer-qualification.test.mjs
+node --test test/consumer-qualification-workflow.test.mjs
+node --test test/qualification-handoff.test.mjs
+node --test test/qualified-publication.test.mjs
+node --test test/release-cutover.test.mjs
+```
+
+These tests use fixtures and do not establish live GitHub signing, OIDC
+permissions, registry publication, environment approvals, or runner tool
+availability. Exercise those controls in a disposable repository before changing
+production release settings.

package/docs/release-integrity.md

@@ -1,9 +1,10 @@
 # Release integrity and build provenance
 
-Code Foundry now provides a read-only immutable-setting preflight, cryptographic
+Code Foundry 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.
+separate guarantees: a checksum identifies bytes, an attestation identifies
+their origin, and GitHub's immutable-release setting prevents replacement after
+publication.
 
 ## Enable immutable releases explicitly
 
@@ -16,9 +17,9 @@ 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.
+replace assets after an immutable release is published. If a repository adds
+release assets, its release workflow must stage them before the release is
+published; the verifier does not repair an already-published release.
 
 A release workflow can run this preflight before publication:
 

package/docs/required-capabilities.md

@@ -1,12 +1,13 @@
 # Required capabilities and task evidence
 
 Declared requirements fail closed when discovery cannot find an executable task.
-Existing optional task discovery remains available. Configure scalar values in
+Optional task discovery remains available. Configure scalar values in
 `.github/code-foundry.yml`:
 
 ```yaml
-required_capabilities: type_check,unit,e2e,performance,coverage
+required_capabilities: type_check,unit,e2e,eval,performance,coverage
 performance: true
+eval: true
 coverage_enforcement: required
 coverage_minimum: 80
 coverage_metrics: lines,branches
@@ -14,16 +15,17 @@ coverage_report: coverage/coverage-summary.json
 ```
 
 Supported task capabilities are `format`, `lint`, `type_check`, `build`, `unit`,
-`integration`, `e2e`, `smoke`, and `performance`. `coverage` additionally requires
+`integration`, `e2e`, `smoke`, `eval`, and `performance`. `coverage` additionally requires
 unit tests. Unknown names, contradictory requirements, and invalid thresholds
-are errors. `performance: true` now means required, not merely enabled when a
-script happens to exist. Use `performance: auto` to retain optional discovery.
+are errors. `performance: true` and `eval: true` mean required, not merely
+enabled when a script happens to exist. Use `performance: auto` or
+`eval: auto` to retain optional discovery.
 
 The public `src/runtime.mjs` entrypoint delegates ecosystem execution to the
-unchanged private `src/runtime-core.mjs`. Keep both files and `src/lib` when
-vendoring the runtime. Published packages and the reusable workflows' existing
-cone-mode sparse checkout include both files. Do not call the private executor
-from consumer CI: it intentionally does not enforce the public policy contract.
+private `src/runtime-core.mjs`. Keep both files and `src/lib` when vendoring the
+runtime. Published packages and reusable workflows must include those paths. Do
+not call the private executor from consumer CI: it does not enforce the public
+policy contract.
 
 ## Coverage migration
 
@@ -84,10 +86,17 @@ script-derived reasons. Do not put credentials in command arguments. Artifact
 access follows repository/Actions visibility; receipt retention does not provide
 a sandbox or independently validate repository-authored evidence.
 
-`node src/runtime.mjs ci plan` prints a JSON discovery plan without executing
-checks. Discovery validates every required task before reusable workflows select
-jobs. A fast/unit-only tier is still a subset: discovery proves that E2E exists,
-not that E2E ran. Require the existing audit validation gate before merging.
+Use the public CLI for a repository-facing discovery plan:
+
+```sh
+npx code-foundry plan --tier audit --json
+```
+
+The lower-level `node src/runtime.mjs ci plan` form remains useful to reusable
+workflows and runtime tests. Both forms discover tasks without executing checks.
+Discovery validates every required task before workflows select jobs. A
+fast/unit-only tier is still a subset: discovery proves that E2E exists, not that
+E2E ran. Require the audit validation gate before merging.
 
 Native task detection rejects known no-ops such as a JavaScript project with no
 build script or a Python project with no supported type-check command. Add a
@@ -98,5 +107,5 @@ an installed package manager or discovered project proves task execution.
 
 `node --test test/task-policy.test.mjs` exercises policy parsing, discovery,
 coverage parsing/thresholds/freshness/path safety, exit propagation, and reports
-with a deterministic executor fixture. The unchanged ecosystem executor remains
-covered by `test/runtime.test.mjs` in the full suite.
+with a deterministic executor fixture. The ecosystem executor is covered by
+`test/runtime.test.mjs` in the full suite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.20.2",
+  "version": "1.25.3",
   "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/commands/cloudflare-delivery.mjs

@@ -300,8 +300,13 @@ export async function deliveryCommand(command, env = process.env) {
     else if (command === 'rollback') await rollback(env, state)
     else if (command === 'record-start') {
       const production = env.FOUNDRY_PHASE === 'production'
+      // pull_request workflows build the merge ref, while GitHub associates
+      // PR deployments with the head commit. The reusable workflow supplies
+      // that head SHA; direct pushes fall back to the checked-out source SHA.
+      const deploymentRef = env.GITHUB_DEPLOYMENT_REF || state.sourceSha
+      if (!/^[0-9a-f]{40}$/i.test(deploymentRef)) throw new Error('Invalid GitHub deployment ref')
       const deployment = await github(env, 'deployments', {
-        ref: state.sourceSha,
+        ref: deploymentRef,
         environment: required(env, 'DEPLOYMENT_ENVIRONMENT'),
         auto_merge: false,
         required_contexts: [],