code-foundry 1.10.1 → 1.12.0

package/.github/workflows/test.yml

@@ -78,6 +78,7 @@ jobs:
           sparse-checkout: |
             .github/actions
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: |
@@ -143,6 +144,7 @@ jobs:
           sparse-checkout: |
             .github/actions
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: |
@@ -208,6 +210,7 @@ jobs:
           sparse-checkout: |
             .github/actions
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: |
@@ -257,6 +260,7 @@ jobs:
           sparse-checkout: |
             .github/actions
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: |
@@ -318,6 +322,7 @@ jobs:
           sparse-checkout: |
             .github/actions
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: |

package/.github/workflows/validation-no-codeql.yml

@@ -143,6 +143,7 @@ jobs:
           path: .github/.code-foundry
           sparse-checkout: |
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: mv .github/.code-foundry "$RUNNER_TEMP/code-foundry"

package/.github/workflows/validation.yml

@@ -155,6 +155,7 @@ jobs:
           path: .github/.code-foundry
           sparse-checkout: |
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: mv .github/.code-foundry "$RUNNER_TEMP/code-foundry"

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

@@ -45,6 +45,7 @@ jobs:
           path: .github/.code-foundry
           sparse-checkout: |
             src/lib
+            src/runtime-core.mjs
             src/runtime.mjs
       - name: Install runtime
         run: mv .github/.code-foundry "$RUNNER_TEMP/code-foundry"

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.12.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.11.0...v1.12.0) (2026-09-09)
+
+
+### Features
+
+* **cloudflare:** verify candidates before protected version promotion ([#535](https://github.com/0xPlayerOne/code-foundry/issues/535)) ([5dd9afa](https://github.com/0xPlayerOne/code-foundry/commit/5dd9afa8418718823844875b0aedce926b887184))
+
+## [1.11.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.10.1...v1.11.0) (2026-09-09)
+
+
+### Features
+
+* **validation:** enforce required capabilities, coverage, and task evidence ([#534](https://github.com/0xPlayerOne/code-foundry/issues/534)) ([2e341d9](https://github.com/0xPlayerOne/code-foundry/commit/2e341d94381599f1d78ec1394d42883157b30ea6))
+
 ## [1.10.1](https://github.com/0xPlayerOne/code-foundry/compare/v1.10.0...v1.10.1) (2026-09-09)
 
 

package/docs/CONFIGURATION.md

@@ -36,10 +36,15 @@ repository manifests and source
 | `package_manager`          | `bun`, `pnpm`, `yarn`, `npm`, `none`                                             | JavaScript setup                                                                                                    |
 | `toolchain`                | `auto`, `native`, `mise`                                                         | Environment setup policy; defaults to `auto`                                                                        |
 | `staging_validation_mode`  | `fast`, `audit`                                                                  | Staging-release-only validation tier; omitted from direct repositories                                              |
-| `performance`              | `auto`, `true`, `false`                                                          | Run a deterministic performance task when a supported entrypoint exists; defaults to `auto`                         |
+| `performance`              | `auto`, `true`, `false`                                                          | `auto` discovers an optional task; `true` requires a supported performance entrypoint; `false` disables discovery   |
 | `performance_command`      | JSON argv array or array of argv arrays                                          | One or more ordered commands for non-package harnesses; package scripts take precedence                             |
 | `performance_profile`      | empty, `node-package`                                                            | Optional shared package import, memory, archive, and dependency budget harness                                      |
 | `performance_budget_file`  | repository path                                                                  | Budget policy for the shared package harness; defaults to `performance-package-budgets.json`                        |
+| `required_capabilities`    | comma-separated task names                                                       | Fail closed when a required task or `coverage` evidence is unavailable; defaults to none                            |
+| `coverage_enforcement`     | `auto`, `required`, `off`                                                        | Shared coverage report policy; `auto` accepts explicit skips, `required` rejects missing reports, `off` skips it    |
+| `coverage_minimum`         | percentage from `0` to `100`                                                     | Minimum measured coverage; defaults to `80`                                                                         |
+| `coverage_metrics`         | `lines`, `functions`, `branches`, `statements`                                   | Metrics checked by the shared coverage gate; defaults to `lines`                                                    |
+| `coverage_report`          | comma-separated repository paths                                                 | Istanbul summary or LCOV evidence files; defaults to standard coverage paths                                        |
 | `features`                 | `all` or a list                                                                  | Standard workflow callers                                                                                           |
 | `codeql`                   | `auto`, `true`, `false`                                                          | CodeQL policy; public repositories default to enabled, non-public repositories default to disabled                  |
 | `codeql_rust_shards`       | JSON array of paths                                                              | Rust scan scopes; `["all"]` keeps the safe single full scan                                                         |
@@ -174,15 +179,23 @@ shards. Do not split a single crate by arbitrary non-Rust directories: use
 ## Cloudflare Workers deployments
 
 Repositories that deploy to Cloudflare Workers can opt into GitHub-native
-deployments (Preview/Production environments with deployment statuses, like
-Vercel's integration) by adding a small caller for the runtime's reusable
-`cloudflare-deploy.yml` workflow. The workflow runs `wrangler versions upload`
-for pull-request previews and `wrangler deploy` for production, records a
-GitHub deployment plus status with the workers.dev URL, and respects
-`CI_BILLING_PAUSED`. It requires the `CLOUDFLARE_API_TOKEN` and
-`CLOUDFLARE_ACCOUNT_ID` secrets in the consumer repository. Bun consumers may
-also pass `build-script`, `install-working-directory`, and `bun-version`; the
-runtime installs the frozen lockfile and builds the Worker before invoking
+verified delivery (fixed `Preview`/`Production` environments, candidate
+verification, and version-identity promotion) by adding a caller for the
+runtime's reusable `cloudflare-delivery.yml` workflow. Use the same immutable
+40-character Code Foundry commit SHA for both the reusable workflow ref and
+`runtime-ref`; configure required reviewers and branch restrictions on the
+`Production` environment. The workflow requires the
+`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets in the consumer
+repository. See [Verified Cloudflare delivery](./cloudflare-delivery.md) for
+binding policy, canary, rollback, and evidence requirements.
+
+The legacy `cloudflare-deploy.yml` workflow remains available for direct
+(unverified) deployments. It runs `wrangler versions upload` for previews and
+`wrangler deploy` for production, records a GitHub deployment plus status, and
+respects `CI_BILLING_PAUSED`. Its legacy-compatible Wrangler default is `latest`;
+callers should prefer `local` or provide an exact `wrangler-version` for
+reproducibility. Bun consumers may pass `build-script`, `install-working-directory`, and `bun-version`;
+the runtime installs the frozen lockfile and builds the Worker before invoking
 Wrangler. Bun-backed callers invoke Wrangler through `bunx` so OpenNext's
 production delegation resolves the workspace-local `opennextjs-cloudflare`
 binary; callers without `build-script` retain the npm/npx path.

package/docs/README.md

@@ -13,6 +13,7 @@ its own names, environments, and deployment details.
 - [Publishing packages](PUBLISHING.md)
 - [Caching and remote caching](CACHING.md)
 - [Performance budgets and baselines](PERFORMANCE.md)
+- [Required capabilities and task evidence](required-capabilities.md)
 
 ## Repository-specific documentation
 

package/docs/cloudflare-delivery.md

@@ -0,0 +1,188 @@
+# Verified Cloudflare delivery
+
+The opt-in `cloudflare-delivery.yml` workflow builds and uploads a candidate,
+validates its actual version bindings, runs an HTTP smoke probe and the required
+repository-owned verification command, then promotes **that version ID** after
+GitHub environment approval. Production promotion uses the Cloudflare deployment
+API and never rebuilds the application. The existing `cloudflare-deploy.yml`
+remains available for direct deployments and initial provisioning.
+
+## Adoption
+
+Call the new reusable workflow using an immutable, reviewed 40-character Code
+Foundry commit SHA and pass the same `runtime-ref`. Required inputs are
+`worker-name`, `artifact-path`, and `verify-command`.
+
+```yaml
+jobs:
+  delivery:
+    # Replace REVIEWED_SHA with the same reviewed 40-character SHA in both places.
+    uses: 0xPlayerOne/code-foundry/.github/workflows/cloudflare-delivery.yml@REVIEWED_SHA
+    permissions:
+      contents: read
+      deployments: write
+    with:
+      runtime-ref: REVIEWED_SHA
+      mode: production
+      worker-name: company-site
+      artifact-path: dist
+      verify-command: '["bun", "run", "test:deployed"]'
+      production-url: https://example.com
+      smoke-path: /health
+      canary-percentage: 10
+      canary-verify-command: '["bun", "run", "test:canary"]'
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+`artifact-path` is relative to `working-directory`; `install-working-directory`
+selects the lockfile root. The selected output tree is hashed before and after
+upload; changes during upload fail. Include all built code/assets in that tree
+and disable duplicate custom build steps. This digest identifies the declared
+local build tree, not a Cloudflare-signed digest of every uploaded configuration
+field. The Worker version ID is the authoritative identity for promotion.
+
+Wrangler defaults to the installed, lockfile-resolved version. Explicit overrides
+must be exact versions, never `latest`, floating majors, or semver ranges. Pin a
+Wrangler version supporting `WRANGLER_OUTPUT_FILE_PATH` and version-1
+`version-upload` records. Missing preview URLs and output-schema mismatches fail.
+Bun remains the installation path, consistent with the existing deploy workflow.
+
+The repository verification command receives `BASE_URL` and
+`FOUNDRY_DEPLOYMENT_PHASE` (`candidate`, `canary`, or `production`). It must check
+critical journeys, redirects, assets, and application-specific behavior. The
+built-in smoke probe requires a successful 2xx response and does not follow
+redirects. Deploy credentials are not supplied to verification steps and are
+removed from the verification child environment as defense in depth. Install any
+browser binaries required by your verification command explicitly.
+
+When `canary-percentage` is below 100, `canary-verify-command` is required and
+must prove that the live request served the candidate rather than the baseline.
+It receives `FOUNDRY_EXPECTED_VERSION_ID`, `FOUNDRY_DEPLOYMENT_ID`, and
+`FOUNDRY_CANARY_PERCENTAGE`; use a version-aware response/header or an equivalent
+application check. A command that only observes a successful production URL is
+not sufficient.
+
+## Approvals, ordering, and evidence
+
+Create and protect the fixed `Preview` and `Production` GitHub environments
+before adoption. The workflow references them at the **job** level; naming an
+environment does not itself configure reviewers or branch restrictions. Configure
+required reviewers and branch restrictions on `Production` separately. Production
+execution requires the current default-branch commit and
+rechecks freshness after approval and before final promotion. Fork PRs and
+`pull_request_target` execution are excluded.
+
+Per-repository/Worker/mode concurrency never cancels a running promotion. GitHub
+concurrency is not a FIFO queue; stale-source rejection is still necessary.
+Other deployment systems and dashboard edits are outside this lock. The helper
+also checks that its deployment has not been replaced before a subsequent
+promotion or rollback, but the Cloudflare API check/write is not an atomic CAS.
+Migrate one application to one deployment owner; do not leave competing legacy
+and new production workflows active.
+
+Outputs include preview URL, exact version ID, source SHA, declared build-tree
+SHA-256 digest, Cloudflare deployment ID, and GitHub application deployment ID.
+Explicit application deployment records receive in-progress and success/failure
+statuses, in addition to GitHub's environment-job records. Sanitized candidate and
+production JSON evidence is uploaded even on failure. Binding values, API bodies,
+and credentials are not copied into those reports. Forced runner termination may
+prevent final status steps; the GitHub job still reflects cancellation/failure.
+
+## Stateful resources and isolation
+
+Without a policy file, non-resource bindings (for example strings, secrets, and
+static assets) are allowed; resource/service bindings fail closed. The uploaded
+version's actual bindings are inspected through the Cloudflare API. Durable
+Object bindings or exports are rejected: use a repository-specific migration and
+preview workflow instead of pretending version preview supports that topology.
+
+A reviewed read-only policy can allow smoke testing a candidate that shares
+production resources:
+
+```json
+{
+  "schemaVersion": 1,
+  "readOnlyBindings": [{ "name": "DB", "type": "d1" }],
+  "rollbackSafe": false
+}
+```
+
+Pass its relative path as `binding-policy-file`. This declaration is **not a
+sandbox**: the repository owner must ensure its test routes cannot mutate shared
+data. A version preview does not automatically create isolated KV, R2, D1, or
+service resources, and a GET route can still have side effects.
+
+For separately provisioned preview Workers, `isolatedBindings` entries can compare
+the actual binding's resource identifiers with expected preview identifiers and
+assert that they differ from declared production identifiers:
+
+```json
+{
+  "schemaVersion": 1,
+  "isolatedBindings": [
+    {
+      "name": "DB",
+      "type": "d1",
+      "expected": { "id": "preview-database-id" },
+      "production": { "id": "production-database-id" }
+    }
+  ]
+}
+```
+
+Use the field names returned for that binding type by the Version API. Resource
+provisioning and the correctness of production-identifier declarations remain
+repository-owned. Isolated preview bindings are rejected in production mode to
+prevent accidentally promoting staging resources. A version from a different
+Worker cannot be promoted across Workers; production mode uploads and tests its
+own candidate on the production Worker with reviewed read-only tests.
+
+## Canary and rollback policy
+
+A percentage below 100 first routes that share to the candidate, verifies it,
+and then promotes the same version to 100 and verifies again. A canary requires
+one prior baseline serving 100% and the explicit `canary-verify-command` above.
+A single load-balanced HTTP request may hit the old version; the command must
+observe the expected version ID. Set `canary-percentage: 100` when that
+version-aware observability is not configured.
+
+Automatic rollback is off. Enabling `auto-rollback` also requires an explicit
+`rollbackSafe: true` policy and both current and prior versions to be free of
+stateful bindings/DO exports. The policy must additionally account for external
+side effects that binding inspection cannot detect. Rollback restores the exact
+previous traffic split only when this run's deployment is still current. Failure
+remains a failed deployment even after rollback. Resource data, migrations,
+external API side effects, routes, and non-versioned settings are never rewound.
+The evidence file records prior versions for manual recovery when automation is
+unsafe or unavailable. Recovery itself must be verified operationally.
+
+This workflow targets already-provisioned Workers with version previews enabled.
+Manage initial Worker/route/trigger setup and non-versioned settings separately;
+the deployment API intentionally changes version routing only.
+
+## Legacy workflow hardening
+
+`cloudflare-deploy.yml` now uses real job environments, non-cancelling concurrency,
+structured Wrangler output, exact/local Wrangler selection, reusable outputs, and
+in-progress/failure deployment records. Its legacy-compatible default remains
+`latest`; callers should prefer `local` or an exact version for reproducibility. A
+production URL can be supplied with `deployment-url` when API output contains only
+route patterns. It is still a **direct, unverified deployment**; adopt
+`cloudflare-delivery.yml` for candidate verification and guarded promotion.
+
+## References and testing
+
+The implementation follows Cloudflare's structured Wrangler output and version
+routing APIs:
+
+- https://developers.cloudflare.com/workers/wrangler/system-environment-variables/
+- https://developers.cloudflare.com/workers/versions-and-deployments/
+- https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/versions/methods/get/
+- https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/deployments/methods/create/
+
+Run `node --test test/cloudflare-delivery.test.mjs`. Tests use deterministic API
+responses and never deploy a Worker. Before production rollout, run the new
+workflow against a disposable Worker and protected test environments, including
+smoke failure and rollback scenarios.

package/docs/required-capabilities.md

@@ -0,0 +1,82 @@
+# 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
+`.github/code-foundry.yml`:
+
+```yaml
+required_capabilities: type_check,unit,e2e,performance,coverage
+performance: true
+coverage_enforcement: required
+coverage_minimum: 80
+coverage_metrics: lines,branches
+coverage_report: coverage/coverage-summary.json
+```
+
+Supported task capabilities are `format`, `lint`, `type_check`, `build`, `unit`,
+`integration`, `e2e`, `smoke`, 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.
+
+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.
+
+## Coverage migration
+
+`coverage_enforcement` accepts:
+
+- `auto` (default): missing reports are explicitly reported as skipped; present
+  reports must be fresh, valid, and meet the threshold.
+- `required`: missing reports also fail, as does required capability `coverage`.
+- `off`: skip the shared report gate. This does not disable a test runner's own
+  coverage threshold, and cannot be combined with required coverage.
+
+The default report candidates are `coverage/coverage-summary.json` (Istanbul
+summary) and `coverage/lcov.info`. `coverage_report` accepts a comma-separated
+list of repository-relative files. When multiple reports exist, every report
+must meet the selected metrics. Percentages are recomputed from measured counts,
+not trusted from reported `pct` fields. Empty reports, unmeasured selected
+metrics, stale files, traversal, and escaping symlinks fail. LCOV supports lines,
+functions, and branches; use JSON summaries for statement coverage.
+
+Configure the repository-owned unit-test command to generate the report on each
+run before enabling required mode. The runtime does not inject coverage tooling,
+install a new runner, delete old reports, or lower thresholds. Auto mode preserves
+repos that declare a threshold but have not yet configured report generation;
+a passing unit task with `coverage.status: skipped` is **not** coverage evidence.
+
+## Results and validation tiers
+
+Each executed CI task writes `.code-foundry/results/<task>.json`, including its
+status (`passed`, `failed`, or `skipped`), discovery reason, delegated command and
+exit status, source SHA when available, timestamps, and evidence paths. Coverage
+has its own nested status. Discovery also records optional skips. Task reports
+appear in the GitHub job summary when `GITHUB_STEP_SUMMARY` is available.
+
+The recorded command is the delegated executor invocation, not a transcript of
+all nested package scripts. No environment variables or captured command output
+are copied into the report. Repository scripts remain responsible for sanitizing
+their own logs. Upload `.code-foundry/results/*.json` with `if: always()` and
+`include-hidden-files: true` to retain downloadable reports; only upload this
+specific directory, not arbitrary hidden files or the entire checkout.
+
+`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.
+
+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
+repository-owned script for unsupported layouts or toolchains. Do not infer that
+an installed package manager or discovered project proves task execution.
+
+## Verification
+
+`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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.10.1",
+  "version": "1.12.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": {