rcf-lite 0.12.0 → 0.14.0

package/blueprints/delivery-ci-workflows/guide/delivery-ci-workflows.md

@@ -0,0 +1,136 @@
+# delivery-ci-workflows blueprint guide
+
+## What it is
+
+The default CI floor for rcf-lite projects, expressed as a workflow SET the operator declares once and the workflow-materialiser produces from that declaration. The blueprint contributes the WHAT of the workflow set: which workflows exist per branch model, which required check set every check-set workflow runs, what the release workflow does per release mode, what the scheduled-audit workflow does when enabled, and what report files land on disk after every run. Each workflow is a single Node entry point the CI job invokes with one line; the elicitation surface is the four required plus two optional fields of `workflowShape` in `.rcf/config/delivery-ci-workflows.json` on the project tree.
+
+Concretely, the blueprint ships 23 requirements, 23 user stories (roughly 50 acceptance criteria), 6 architecture components, and 10 architecture decision records. Three ADRs are `scope: global` on the topics `ciGates` (the required check set every commit-triggered workflow runs), `strictCoverageGate` (the per-AC strict coverage posture), and `releaseArtefacts` (the four-mode release workflow shape); the other seven ADRs are scope-local.
+
+## What it is not
+
+Not a matrix of provider-specific configuration files. v2.0.0 ships one illustrative GitHub Actions workflow file per workflow the matrix materialises under `assets/ci-provider-examples/github-actions/` (`pull-request-checks.yml`, `default-branch-checks.yml`, `release.yml`, `scheduled-audit.yml`) as copy-paste starting points. Alternate providers (GitLab CI, CircleCI, Buildkite, Jenkins) wire the same Node entry points per the four-point mapping named below applied to each workflow; the blueprint does not carry per-provider configuration files for those runners at v2.0.0.
+
+Not a source-code contribution. The blueprint contributes the workflow-materialiser contract, the gate-runner contract, the release-workflow contract, the scheduled-audit contract, the per-gate report writer contract, the aggregate report writer contract, and the discipline that binds them. The project realises the Node entry points against those contracts in its own build cycle; the blueprint does not ship the entry-point source.
+
+Not a choice of linter, formatter, typechecker, test runner, or security scanner. The elicited check catalogue names the check kinds; the project picks the tools that satisfy the runner-contract interfaces. A code-formatting style guide, a security-scan severity threshold, and the linter rule set are all project decisions the blueprint does not opine on.
+
+Not a release-mechanism. The release workflow reacts to a tag or a `workflow_dispatch`; the project creates the tag through its own release mechanism (a `standard-version` invocation, a manual git tag, a release-please bot). The blueprint does not ship a tag-creation workflow, a changelog generator, or a version-bump tool.
+
+Not a merge-queue integration or a coverage-trend dashboard. A project that wants either reads the aggregate reports from the queue tool or the dashboard of its choice; the blueprint owns the aggregate report shapes and stability, not the reader wiring.
+
+Not a branch-protection or merge-policy configuration. AC-6101-2, AC-6114-3, AC-6115-1, and AC-6115-2 state the property the project owes on the platform's own configuration surface per branch model; the blueprint does not ship the configuration file.
+
+## When to reach for it
+
+Reach for the `delivery-ci-workflows` blueprint when:
+
+- The project is an rcf-lite deployment with an RCF chain and a default or trunk branch.
+- The project's CI provider can run Node 24 or later on its runner (every mainstream provider can).
+- The project wants the required check set (RCF chain plus enabled elicited checks) to be a merge-blocking property, not an author-time habit.
+- The project wants a stable per-run report artefact any downstream reader (dashboard, audit tool, merge queue) can pick up without scraping the CI provider's log surface.
+- The project wants a release workflow that scales with what the project has already declared (from `none` for internal packages up to `deployHandoff:<slug>` for paired services).
+
+## When it does not fit
+
+Do not reach for the `delivery-ci-workflows` blueprint when:
+
+- The project does not use RCF (no `rcf/` tree, no `rcf define validate` invocation makes sense).
+- The project runs on a CI provider whose runners cannot execute Node 24 or later.
+- The project wants a coverage-mode grace window on newly introduced ACs (supersede ADR-702 with a project-level ADR stating the grace window).
+- The project wants required checks that are not in the catalogue and not naturally cross-blueprint (a mutation-testing gate, an accessibility scan). Supersede ADR-701 with a project-level ADR listing the extended catalogue and register the check under `custom:<name>`.
+
+## What a good outcome looks like
+
+A project applies the `delivery-ci-workflows` blueprint on a fresh tree, populates `.rcf/config/delivery-ci-workflows.json` with its `workflowShape` (four required fields plus any optional ones), realises the six TACs in project-authored FBSes, and lands on a deployed workflow set where:
+
+- Every commit-triggered event fires the appropriate workflow (per branch model). The workflow's aggregate report at `.rcf/reports/ci/pipeline.json` records the trigger, the timing, and the ordered gate outcomes including the `checkKind` per gate.
+- A pull request whose head commit fails any required check sees the failed check in the aggregate, sees the specific issue in the per-gate report, and cannot be merged through the platform's standard merge path.
+- A pull request whose head commit passes every required check sees `verdict: passed` in the aggregate, sees green on the platform's required-check surface, and can be merged.
+- A release trigger fires the release workflow per `releaseMode`: `none` means no workflow at all; `tagOnly` creates a release entity; `tagPlusArtefact` also publishes an artefact; `deployHandoff:<slug>` also invokes the named deploy blueprint's promote workflow with the `versionId` input.
+- When `scheduledAudit: true`, the scheduled-audit workflow fires on a cron cadence and writes to `.rcf/reports/ci/scheduled-audit.json`, distinct from commit-triggered `pipeline.json`.
+- A developer reproducing a CI failure on their machine runs the same one-line invocation the CI job's step recorded and sees the same per-gate outcomes at the same report paths.
+
+## The workflowShape declaration (four dimensions plus two optional)
+
+The project ships `.rcf/config/delivery-ci-workflows.json` at the project root. The declaration has three required fields, one optional field with defined default semantics, and two optional dimensions.
+
+```json
+{
+  "workflowShape": {
+    "branchModel": "feature",
+    "checkSet": {
+      "linter": true,
+      "formatter": true,
+      "typecheck": true,
+      "unitTest": true,
+      "securityScan": true
+    },
+    "releaseMode": "tagPlusArtefact",
+    "providerHint": "githubActions",
+    "scheduledAudit": false
+  }
+}
+```
+
+- `branchModel` (required): `feature` or `trunk`.
+- `checkSet` (required): object of booleans keyed by elicited-check name.
+- `providerHint` (required): `githubActions`, `gitlabCi`, `circleCi`, `buildkite`, or `jenkins`.
+- `releaseMode` (OPTIONAL, Q6-B ratification): `none`, `tagOnly`, `tagPlusArtefact`, or `deployHandoff:<slug>`. An absent field is treated the same as `none` (no release workflow ships). Not having a release path yet is a common scenario when starting a project; the ratification chose ergonomics over an explicit `none`.
+- `scheduledAudit` (optional): boolean; default `false`.
+- `trunkPullRequests` (optional; qualifies `branchModel: trunk`): `never` or `sometimes`; default `never`.
+
+### Profile aliases
+
+Named profile aliases (`smallLibrary`, `smallService`, `internalPackage`, `trunkLibrary`) compose the four-field form. The materialiser expands the alias to the four-field form at boot; every AC binds to the four-field form. Adding an alias is a minor bump; renaming or removing an alias is a minor bump.
+
+## The check catalogue
+
+Two tiers:
+
+- **Mandatory tier** (preserved from v1): `validate` (running `rcf define validate`) then `coverage-strict` (running `rcf audit coverage --strict`), in that order.
+- **Elicited tier** (v2 additions): `linter`, `formatter`, `typecheck`, `unitTest`, `securityScan`. Default: every catalogued check on. Per-check auto-detection may adjust the default (typecheck defaults on when the project tree contains a `tsconfig.json` or equivalent tool marker).
+
+Each elicited check ships an AC contract stating what its runner must produce: a non-zero exit code on any blocking finding, a per-gate report at the check's stable path, and a `checkKind` field naming the check kind. The blueprint does NOT ship the linter, formatter, typechecker, test runner, or scanner; the project picks the tools.
+
+Custom checks (`custom:<name>`) supersede this ADR at the project level and register alongside the catalogued checks in the aggregate.
+
+## The four release modes
+
+`releaseMode` scales what the release workflow does:
+
+- `none` (or absent, per Q6-B ratification): no release workflow ships.
+- `tagOnly`: on a release trigger, creates a release entity on the provider's release surface (a GitHub Release, a GitLab release).
+- `tagPlusArtefact`: on a release trigger, creates the release entity and runs the project-realised artefact-publish step, uploading the artefact to the release entity.
+- `deployHandoff:<slug>`: on a release trigger, runs the tagPlusArtefact flow and then dispatches the named deploy blueprint's `promote` workflow via `workflow_dispatch` with the just-published version identifier as the `versionId` input.
+
+The release workflow does NOT invoke the required check set: that already ran on the `default-branch-checks` workflow at the commit the release points at.
+
+The `deployHandoff:<slug>` mode has a manifest boot-check: the materialiser refuses when the named deploy blueprint is absent from `manifest.blueprints[]`.
+
+## Wiring alternate CI providers (four-point mapping applied per workflow)
+
+Every mainstream CI provider ships the same four ingredients under a different runner language. The blueprint's Node entry points are the fourth ingredient (one per workflow); the other three are provider-specific. The illustrative GitHub Actions workflow files show all four applied per workflow; alternate providers translate the first three and keep the fourth unchanged per workflow:
+
+1. Job trigger. The trigger set per workflow (pull_request into the target branch for `pull-request-checks`; push to the target branch for `default-branch-checks`; release event or workflow_dispatch for `release`; cron schedule for `scheduled-audit`).
+2. Node setup.
+3. Package-manager setup and install.
+4. Node entry-point invocation and artefact upload per workflow.
+
+See `assets/ci-provider-examples/notes.md` for the per-provider translation.
+
+## Operator decisions that remain open after apply
+
+- The workflow shape declaration (`.rcf/config/delivery-ci-workflows.json` populated).
+- Report directory path (default `.rcf/reports/ci/`).
+- Tool choices for elicited checks (linter, formatter, typechecker, unit-test runner, security scanner).
+- Security-scan severity threshold.
+- Coverage-mode posture (supersede ADR-702 with a project-level ADR if a different posture is wanted).
+- CI provider choice and the trigger/setup/install steps per workflow.
+- Branch-protection or push-protection configuration on the default or trunk branch per branch model.
+- Artefact-upload retention and destination.
+- Merge-queue integration and coverage-trend dashboard wiring.
+- Release-mechanism (how tags get created).
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every commit-triggered event runs the required check set every time; the elicited tier lengthens wall time in proportion to the number of enabled checks. The strict-coverage posture makes every new AC a two-file edit (author the AC and author the TC that resolves it). Adding a check kind outside the catalogue is a project-level ADR plus a runner realisation, not a knob-flip. The illustrative GHA assets are a starting point; a project on another provider owes the translation of the first three of the four mapping points per workflow (extending v1's per-workflow cost to a per-workflow-set cost). Branch-protection configuration is not shipped by the blueprint; a project that forgets to configure it satisfies every AC on the doc set and still ships a workflow set that does not block merges. The report directory grows one per-gate file per gate per run plus one aggregate per workflow per run; a project that runs many workflows against short-lived branches accumulates reports until the CI provider's artefact retention rolls them off.

package/blueprints/deploy-cloudflare-workers/README.md

@@ -0,0 +1,63 @@
+# Deploy Cloudflare Workers blueprint (v1.1.0)
+
+The ninth content blueprint on the rcf-build-lite blueprint mechanism, and the first in the `deploy` category. Scope: an artefact-upload + explicit-promote deployment model with three distinct addressable URLs (per-version-id, stable preview alias, production), a single Deploy Adapter as the sole vendor caller, a repo-root wrangler manifest as the sole declaration of deploy shape, a rollback-is-promote posture, a served-surface verifier on every promote, a dev-mode-inadmissible-for-deployed-coverage posture, and build-provenance baked into every uploaded version. Targeted at small greenfield rcf-lite projects; larger deployments supersede the default vendor (ADR-1302) with a project-level ADR and swap the adapter's vendor binding.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/deploy-cloudflare-workers
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `deploy` category; `rcf define blueprint remove deploy-cloudflare-workers` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `deploy`, and the 35 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 12 REQs, 12 USs (36 ACs), 6 TACs, 5 ADRs, all schema-valid and namespaced (`deploy-cloudflare-workers-REQ-001` prefix family; `ADR-1301-deploy-cloudflare-workers-deployment-target` suffix family) |
+| Wrangler manifest sample | `assets/wrangler-samples/wrangler-toml-shape.md` | The exact shape of a `wrangler.toml` for a Worker with static assets, KV, D1, and secret bindings, worked as one committable example |
+| Preview alias example | `assets/wrangler-samples/preview-alias-shape.md` | The URL patterns for the three URL kinds (per-version-id, stable alias, production) with placeholder account/worker names |
+| Build-and-upload workflow | `assets/ci-workflows/build-and-upload.yml.md` | The GitHub Actions form of the build-and-upload workflow with token binding, alias input, and structured output |
+| Promote workflow | `assets/ci-workflows/promote.yml.md` | The GitHub Actions form of the promote workflow with `workflow_dispatch`, optional `versionId` input, and post-promote verifier invocation |
+| Served-surface probe pattern | `assets/verification/served-surface-probes.md` | The probe-config shape, retry bounds, and expect-shape pattern for the health probe and one project smoke probe |
+| Guide | `guide/deploy-cloudflare-workers.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signals for future deploy blueprints |
+| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (nine shipped blueprints including this one) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the deploy shape, the adapter contract, the manifest shape, the three URL kinds, the promote-is-explicit posture, the rollback-is-promote posture, the served-surface verify shape, the dev-mode drift posture, the build-provenance surface); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: a vendor CLI implementation (the default vendor is named in ADR-1302 as Cloudflare's `wrangler`, the shape of the vendor binding is fixed by TAC-1301, the actual binding code is a project-authored implementation shelling to the CLI); a project's authorisation model for who is allowed to promote (promote authorisation sits at the CI platform's own permission model on the `workflow_dispatch` primitive); a promote-approval workflow (a project that wants an approver review on every promote layers a manual-approval step above the `workflow_dispatch` trigger); a canary or gradual-rollout controller (the vendor's own primitives support gradual promote where the operator wants it; the blueprint mandates the served-surface verifier on the eventual full promote); an image or artefact registry (the vendor's own upload-and-version primitive is the artefact store); a project's audit-log storage engine (the blueprint fixes the deploy-log record shape, not where the records land); a status page (the observability-essentials blueprint owns `statusPageContract`; the deploy log feeds into it); the secrets pipeline itself (the security-secrets-management blueprint owns `secretsSource`; this blueprint consumes it for the vendor API token and any application secret bindings the Worker reads).
+
+## The one global decision
+
+ADR-1301-deploy-cloudflare-workers-deployment-target ships `scope: global` on topic `deploymentTarget`. This is the project's single source of truth for how bits reach a running target: an artefact-upload + explicit-promote model with three distinct addressable URLs. A composing blueprint that wants a different deployment shape (a container-image-per-commit + rolling-deploy blueprint, a merge-to-production-coupled blueprint, a serverless-function-per-endpoint blueprint) conflicts here by design and expects a project-level ADR resolution. Vendor DEFAULT (ADR-1302) is deliberately scope-local: the contract is global; the default that ships behind it is not.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from vendor-choice (which is not global), and the AC id band allocation (deploy-cloudflare-workers owns 12101-12899, ADR/TAC suffix block 13xx).
+
+## Quality bar
+
+Repo-root wrangler manifest as the sole declaration of Worker name, entry, compatibility settings, and every binding; one Deploy Adapter as the sole caller of the vendor CLI on the boundary; every merge to main uploads a Worker version reachable at both a permanent per-version-id URL and a stable preview alias URL; the uploaded version never serves production traffic; production only changes when the `promote` workflow runs on an explicit operator trigger; the promote workflow accepts one input `versionId` (empty defaults to newest-of-main); rollback IS a promote of a prior version id, on the same workflow, with the same audit shape; every promote runs the Served-surface Verifier against the production URL with bounded retries; a promote whose verifier fails is not marked successful; every uploaded version carries build provenance (commit sha, build timestamp, CI run URL) readable at a fixed health-probe path; the health probe's `versionSha` field is the served-surface verifier's confirmation that the promoted version is the version being served; no secret value ever lives in the wrangler manifest, in a committed environment file, in a CI variable readable outside the promote job, or in any CI log line; a probe against a dev-mode local URL is refused as coverage for a `deployed`-scope AC; the manifest loader refuses a wrangler config whose production route resolves to the same host as the preview alias URL. Every bar is carried by ACs in the doc set, not by this README.
+
+## What v1.1.0 adds
+
+v1.1.0 is an additive-non-global minor bump. No global topics change; no contribution is removed; the compose invocation is unchanged. The bump cures seven content findings that the round-2 dogfood acceptance build surfaced when a stranger followed the v1.0.0 teaching against wrangler 4.x reality (three HIGH, three MEDIUM, one LOW). Every fixed teaching is execution-verified against the shipped vendor CLI, with one depth-stop caveat: the bootstrap flow taught in `assets/wrangler-samples/bootstrap-vs-steady-state.md` (F-006) is composed from vendor CLI refusals reproduced against a real Worker (the three refusal-message excerpts in the asset are byte-verified against the shipped CLI's output) and each individual vendor primitive it composes is verified in isolation, but the composed `wrangler deploy --secrets-file <tmp>` bootstrap sequence itself is not end-to-end executed as a single verified run in this ship. A project applying the blueprint exercises the composed sequence the first time it bootstraps a Worker.
+
+- **Bootstrap-vs-steady-state (HIGH).** A new asset `assets/wrangler-samples/bootstrap-vs-steady-state.md` teaches the one-time first-deploy flow (`wrangler deploy --secrets-file <tmp>`) that creates the Worker AND sets every referenced secret in one atomic act, and the steady-state ship path (`wrangler versions upload` on every merge, `wrangler versions deploy <versionId>` on operator-triggered promote) that assumes bootstrap has already run. The bootstrap prerequisite is called out on both CI workflow asset reader-notes.
+- **Assets-binding auth-gate discipline (HIGH, security-class).** `assets/wrangler-samples/wrangler-toml-shape.md` now teaches `[assets] run_worker_first` as the default posture whenever the Worker gates access to any path a static file under `directory` could shadow, with the bypass mechanism explained (the assets pipeline serves files at their file-path from the edge cache BEFORE the fetch handler runs, silently bypassing any auth middleware for the collision path). US-12101 adds AC-12101-4, a runtime-observable acceptance criterion that a deployed unauthenticated request to a gated route returns the auth middleware's response, not the file body.
+- **Newest-of-alias resolution (HIGH).** `wrangler versions view <alias>` is not a real verb in wrangler 4.x (the CLI accepts a version UUID as its positional argument only). `assets/wrangler-samples/preview-alias-shape.md` and TAC-1301's vendor binding now teach the working path: `wrangler versions list --json` filtered on `annotations['workers/alias']`, picking the item with the greatest `metadata.created_on`.
+- **Compose boundary with `observability-probe-endpoints` (MEDIUM).** `assets/verification/served-surface-probes.md` gains a dedicated section documenting the deploy blueprint's `/healthz` provenance surface as distinct from any profile-owned probe path the probe-endpoints blueprint contributes; TAC-1305's trade-offs note the boundary. The sibling blueprint's guide carries one boundary sentence pointing back.
+- **Two identifiers, one probe body (MEDIUM).** `assets/verification/served-surface-probes.md`, TAC-1301, TAC-1304, TAC-1305, US-12110's AC-12110-2, and US-12112's AC-12112-3 now distinguish `promotedVersionId` (the vendor-assigned version UUID, the string `wrangler versions deploy` takes) from `versionSha` (the git commit sha of the source tree the version was built from, baked into the bundle by `build-and-upload` and served on `/healthz`). The verifier reconciles the served body's `versionSha` against the promote record's `versionSha` field; both identifiers are now required on the promote record and both flow through the promote workflow's summary.
+- **`[secrets]` block removed (MEDIUM).** The v1.0.0 `[secrets] required = [...]` block in `wrangler-toml-shape.md` was not a wrangler-parsed key. It is removed. The asset now teaches that wrangler 4.x treats every `env.<NAME>` reference from Worker code as an implicit binding declaration and enforces its presence at deploy time; project-intent documentation of the required secret set belongs in a README section or a project-owned `SECRETS.md` outside `wrangler.toml`. Reasoning: leaving decorative TOML in vendor-official position taught readers a false enforcement contract; moving intent-documentation to a non-mistakable location cures the invention.
+- **workers.dev subdomain discovery (MEDIUM/LOW).** `assets/wrangler-samples/preview-alias-shape.md` gains a `Discovering the workers.dev subdomain` section teaching the CF REST endpoint `GET /accounts/<accountId>/workers/subdomain` (verified: no wrangler CLI verb returns the subdomain, `whoami` prints account id and email only). `wrangler-toml-shape.md` documents the workers.dev-only production branch alongside the custom-domain branch. TAC-1301 gains a `resolveSubdomain()` verb (env-var pin first, REST fallback, cached for the process's lifetime); TAC-1303's `workerIdentity` interface reads the subdomain through the new verb rather than from an ambiguous boot input.
+
+An upgrade from v1.0.0 is compose-invocation identical (`rcf define blueprint add <path-to>/blueprints/deploy-cloudflare-workers` unchanged); a project on v1.0.0 that re-applies picks up the corrected teaching, the one new AC, and the new asset without changing contribution ids or bands.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed application (source-tree import-graph scans for the adapter boundary, structured-record accumulation for the deploy-log shape, HTTP probes against the three URL kinds for the served-surface properties, byte-equality checks against resolved secret values for the leakage properties, workflow-file parsing for the trigger-set invariants, coverage-gate walk for the dev-mode-inadmissible invariant). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational surface a project must own on its own is the vendor binding implementation (the default `wrangler`-shelling binding, or a superseding vendor's binding); that responsibility is stated as a TAC interface, not as a smuggled runtime probe. The one AC whose runtime observability depends on operator choice is AC-12112-2 (the `/healthz` path is a common default but the project picks the actual path); the runtime observability there is the project-declared probe path resolving with the expected shape, which the served-surface verifier's own success signal confirms.

package/blueprints/deploy-cloudflare-workers/assets/ci-workflows/build-and-upload.yml.md

@@ -0,0 +1,109 @@
+# build-and-upload workflow (GitHub Actions form)
+
+Reference shape for the `build-and-upload` workflow. Every value with `<...>` is a placeholder the project fills. The workflow triggers on `push` to `main`, injects build provenance, invokes the Deploy Adapter's `uploadVersion` verb, and writes the uploaded version id plus the two preview URLs to the run summary and to a structured output the `promote` workflow reads.
+
+```yaml
+# .github/workflows/build-and-upload.yml
+name: build-and-upload
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: build-and-upload
+  cancel-in-progress: false
+
+jobs:
+  build-and-upload:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      versionId: ${{ steps.upload.outputs.versionId }}
+      versionIdUrl: ${{ steps.upload.outputs.versionIdUrl }}
+      previewAliasUrl: ${{ steps.upload.outputs.previewAliasUrl }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - uses: pnpm/action-setup@v4
+
+      - name: Install pinned dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build with provenance
+        env:
+          BUILD_VERSION_SHA: ${{ github.sha }}
+          BUILD_BUILT_AT: ${{ github.event.head_commit.timestamp }}
+          BUILD_CI_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: pnpm build
+
+      - name: Upload version
+        id: upload
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: node scripts/deploy/upload-version.mjs --preview-alias main
+
+      - name: Write run summary
+        run: |
+          {
+            echo "## Uploaded version"
+            echo ""
+            echo "- versionId: \`${{ steps.upload.outputs.versionId }}\`"
+            echo "- versionIdUrl: ${{ steps.upload.outputs.versionIdUrl }}"
+            echo "- previewAliasUrl: ${{ steps.upload.outputs.previewAliasUrl }}"
+          } >> "$GITHUB_STEP_SUMMARY"
+```
+
+## The Node.js orchestration script
+
+`scripts/deploy/upload-version.mjs` is the project-authored script the workflow invokes. Its body:
+
+```javascript
+#!/usr/bin/env node
+// Invoked by the build-and-upload workflow. Wraps the Deploy Adapter's
+// uploadVersion verb, parses --preview-alias, and writes structured outputs
+// the workflow references via ${{ steps.upload.outputs.<name> }}.
+
+import { appendFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { createDeployAdapter } from '../../src/deploy/adapter.mjs';
+
+const { values } = parseArgs({
+  options: { 'preview-alias': { type: 'string' } }
+});
+if (!values['preview-alias']) {
+  console.error('DEPLOY_PREVIEW_ALIAS_REQUIRED: --preview-alias is required');
+  process.exit(2);
+}
+
+const adapter = createDeployAdapter();
+const { versionId, versionIdUrl, previewAliasUrl } =
+  await adapter.uploadVersion({ previewAlias: values['preview-alias'] });
+
+const out = process.env.GITHUB_OUTPUT;
+if (!out) {
+  console.error('GITHUB_OUTPUT unset; running outside GitHub Actions?');
+  process.exit(2);
+}
+appendFileSync(out, `versionId=${versionId}\n`);
+appendFileSync(out, `versionIdUrl=${versionIdUrl}\n`);
+appendFileSync(out, `previewAliasUrl=${previewAliasUrl}\n`);
+```
+
+## Reader notes
+
+- Triggers ONLY on `push` to `main`. No `pull_request`, no `schedule`. AC-12107-1 refuses any other trigger; AC-12104-1 refuses any workflow that both pushes-to-main AND promotes.
+- The Worker being uploaded must exist on the vendor before `wrangler versions upload` succeeds. The first-time-per-Worker bootstrap is a one-time operator act, not part of this workflow; see `assets/wrangler-samples/bootstrap-vs-steady-state.md`. This workflow assumes bootstrap has already run.
+- The three provenance env vars (`BUILD_VERSION_SHA`, `BUILD_BUILT_AT`, `BUILD_CI_RUN_URL`) are baked into the built bundle by the project's build step. AC-12112-1 requires them readable from within the Worker at request time; the health probe exposes them. `BUILD_VERSION_SHA` is the git commit sha (`github.sha`); it is NOT the vendor-assigned version UUID that `wrangler versions upload` returns. The two identifiers name two different things (see `assets/verification/served-surface-probes.md` for the boundary the verifier reconciles).
+- `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` are GHA repository secrets. The token is scoped to the Worker's account with the minimum verbs the adapter uses. AC-12107-3 requires neither byte-sequence appear in any log line; wrangler and the redactor in the Deploy Adapter both mask them by default.
+- `concurrency` on the workflow name prevents overlapping uploads racing the preview alias. `cancel-in-progress: false` because cancelling an upload mid-flight leaves the alias in an ambiguous state on some vendors.
+- The workflow's `outputs` block surfaces `versionId`, `versionIdUrl`, and `previewAliasUrl` for the `promote` workflow's `resolveNewestOfMain` path. AC-12107-2 requires this structured output.

package/blueprints/deploy-cloudflare-workers/assets/ci-workflows/promote.yml.md

@@ -0,0 +1,120 @@
+# promote workflow (GitHub Actions form)
+
+Reference shape for the `promote` workflow. Every value with `<...>` is a placeholder the project fills. The workflow triggers only on `workflow_dispatch`, accepts an optional `versionId` input, invokes the Promote Gate, and honours the Served-surface Verifier's pass or fail.
+
+```yaml
+# .github/workflows/promote.yml
+name: promote
+
+on:
+  workflow_dispatch:
+    inputs:
+      versionId:
+        description: "Version id to promote. Leave blank for newest-of-main."
+        required: false
+        type: string
+
+concurrency:
+  group: promote
+  cancel-in-progress: false
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - uses: pnpm/action-setup@v4
+
+      - name: Install pinned dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Promote and verify
+        id: promote
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PROMOTED_BY: ${{ github.actor }}
+        run: node scripts/deploy/promote.mjs --version-id "${{ inputs.versionId }}"
+
+      - name: Write run summary
+        if: always()
+        run: |
+          {
+            echo "## Promote outcome"
+            echo ""
+            echo "- promotedVersionId: \`${{ steps.promote.outputs.promotedVersionId }}\`"
+            echo "- versionSha:        \`${{ steps.promote.outputs.versionSha }}\`"
+            echo "- previousVersionId: \`${{ steps.promote.outputs.previousVersionId }}\`"
+            echo "- promotedBy:        \`${{ github.actor }}\`"
+            echo "- outcome:           \`${{ steps.promote.outcome }}\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+```
+
+## The Node.js orchestration script
+
+`scripts/deploy/promote.mjs` is the project-authored script the workflow invokes. Its body:
+
+```javascript
+#!/usr/bin/env node
+// Invoked by the promote workflow. Wraps the Promote Gate (TAC-1304).
+// Resolves the newest-of-main when --version-id is blank; refuses an unknown
+// version id before any vendor call; invokes the Served-surface Verifier
+// after promoteVersion returns success; writes structured outputs.
+
+import { appendFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { createDeployAdapter } from '../../src/deploy/adapter.mjs';
+import { createServedSurfaceVerifier } from '../../src/deploy/verifier.mjs';
+import { createPromoteGate } from '../../src/deploy/promote-gate.mjs';
+
+const { values } = parseArgs({
+  options: { 'version-id': { type: 'string', default: '' } }
+});
+
+const adapter = createDeployAdapter();
+const verifier = createServedSurfaceVerifier({ adapter });
+const gate = createPromoteGate({ adapter, verifier });
+
+try {
+  const record = await gate.promote({
+    versionId: values['version-id'] || null,
+    promotedBy: process.env.PROMOTED_BY || 'unknown'
+  });
+  const out = process.env.GITHUB_OUTPUT;
+  if (out) {
+    // promotedVersionId is the vendor-assigned version UUID (the string
+    // `wrangler versions deploy` takes). versionSha is the git commit sha
+    // of the source tree the promoted version was built from; the verifier
+    // substitutes this into the health probe's `expectShape.versionSha`
+    // slot to reconcile served against promoted. Both identifiers are
+    // required on the promote record; they are never equal.
+    appendFileSync(out, `promotedVersionId=${record.promotedVersionId}\n`);
+    appendFileSync(out, `versionSha=${record.versionSha}\n`);
+    appendFileSync(out, `previousVersionId=${record.previousVersionId}\n`);
+  }
+  process.exit(0);
+} catch (err) {
+  console.error(`${err.code || 'PROMOTE_FAILED'}: ${err.message}`);
+  process.exit(1);
+}
+```
+
+## Reader notes
+
+- The Worker being promoted must have been bootstrapped once with `wrangler deploy --secrets-file <path>` before the first `wrangler versions upload` from `build-and-upload` can succeed; see `assets/wrangler-samples/bootstrap-vs-steady-state.md`. Steady-state ship (this workflow's world) assumes bootstrap has already run.
+- The promote record carries two identifiers: `promotedVersionId` (vendor-assigned UUID, the value `wrangler versions deploy` took) and `versionSha` (git commit sha the promoted version was built from). The verifier reconciles the served health-probe body's `versionSha` against the promote record's `versionSha`, NOT against `promotedVersionId`; see `assets/verification/served-surface-probes.md` for the boundary.
+- Triggers ONLY on `workflow_dispatch`. No `push`, no `pull_request`, no `schedule`. AC-12104-2 refuses any other trigger; AC-12104-1 refuses any workflow that pushes-to-main AND promotes.
+- The `versionId` input is optional (`required: false`). Blank defaults to newest-of-main, resolved by the Promote Gate through the Deploy Adapter. AC-12108-1 requires exactly one optional input; AC-12108-2 requires the blank case to resolve through `resolveNewestOfMain`.
+- The Promote Gate refuses a `versionId` absent from `listVersions()` BEFORE any vendor promote call. AC-12108-3 requires the refusal to exit non-zero with `DEPLOY_VERSION_NOT_FOUND` and to leave no promote record.
+- The Served-surface Verifier runs after `promoteVersion` returns success. A verifier failure exits non-zero with `PROMOTE_VERIFY_FAILED` and refuses to mark the release successful. AC-12110-3 requires this.
+- `PROMOTED_BY: ${{ github.actor }}` binds the operator principal from the trigger context into the deploy-log record. AC-12104-3 requires the record.
+- To rollback: invoke this workflow with the prior version id supplied as the `versionId` input. AC-12109-1 requires no separate rollback path. AC-12109-3 requires rollback promotes to run the same verifier.
+- Additional approver-gating (a two-person integrity policy on every promote) layers above `workflow_dispatch` through the platform's manual-approval primitive; the blueprint's ADR set does not fix that policy.

package/blueprints/deploy-cloudflare-workers/assets/verification/served-surface-probes.md

@@ -0,0 +1,90 @@
+# Served-surface probe pattern
+
+Reference shape for the Served-surface Verifier's probe declaration. Every value with `<...>` is a placeholder the project fills.
+
+## Two identifiers, one probe body
+
+The verifier reconciles a promoted version against what production is serving. The reconciliation compares two named identifiers the vendor and the project both know:
+
+| Identifier | What it is | Where it lives | Written by |
+|---|---|---|---|
+| `promotedVersionId` | The vendor-assigned version UUID (`06839e70-1f7c-414f-99a9-babf3969efca`), the string `wrangler versions deploy` takes as its positional argument | The promote record's `promotedVersionId` field, emitted by the Promote Gate on every promote | The vendor CLI's response to `wrangler versions deploy`, captured by the Deploy Adapter's `promoteVersion` return value |
+| `versionSha` | The git commit sha of the source tree the version was built from (the 40-character hex the `github.sha` context carries), baked into the built bundle by `build-and-upload` | The bundle as a build-time constant AND the Worker's health-probe response body | The `build-and-upload` workflow, which sets `BUILD_VERSION_SHA=${{ github.sha }}` before the build step |
+
+The two identifiers name two different things on two different systems. They are NEVER equal by construction: `promotedVersionId` is a UUID assigned by the vendor at upload time; `versionSha` is a git sha assigned by the source-control system at commit time. Any teaching that "substitutes the promoted id into the probe body" and expects a match is wrong on the wire.
+
+The verifier's reconciliation is: the Promote Gate captures BOTH identifiers on every promote (the vendor returns `promotedVersionId`; the project pairs it with the `versionSha` of the source-tree the version was built from, carried on the promote record's `versionSha` field). At verify time, the verifier substitutes the promote record's `versionSha` into the probe's `expectShape.versionSha` slot and refuses the probe when the served body's `versionSha` does not match.
+
+## The probe declaration
+
+```javascript
+// src/deploy/verify-config.mjs
+// Consumed by the Served-surface Verifier (TAC-1305). The health probe is
+// mandatory; add project smoke probes for surfaces where a served-surface
+// check adds signal a health probe does not.
+
+export const probes = [
+  {
+    path: '/healthz',
+    method: 'GET',
+    successStatus: [200],
+    expectShape: {
+      // <PROMOTED_VERSION_SHA> is substituted at verify time from the
+      // promote record's `versionSha` field (the git sha), NOT from the
+      // promote record's `promotedVersionId` (the vendor UUID). The two
+      // are different identifiers on two different systems.
+      versionSha: '<PROMOTED_VERSION_SHA>'
+    }
+  },
+  {
+    // A project smoke probe: a read that exercises one binding and one
+    // Worker code path a health probe does not. Keep it stateless, idempotent,
+    // and observable in one round trip.
+    path: '/api/status',
+    method: 'GET',
+    successStatus: [200],
+    expectShape: {
+      ok: true
+    }
+  }
+];
+
+export const retryBounds = {
+  // At most six attempts per probe over at most sixty seconds; per-request
+  // timeout at most five seconds. AC-12110-1 refuses a bound looser than these.
+  maxAttemptsPerProbe: 6,
+  windowMs: 60_000,
+  perRequestTimeoutMs: 5_000
+};
+```
+
+## The verifier's runtime shape
+
+The Served-surface Verifier consumes the config through the `probeConfig` interface (TAC-1305). Per probe:
+
+1. Compose the request against the target URL (from `probeUrl('production', null)` for a promote verify, from `probeUrl('alias', <alias>)` for a preview-only verify).
+2. Send the request; on transport error or on a status outside `successStatus`, sleep with an exponential-shaped backoff bounded by `windowMs / maxAttemptsPerProbe`.
+3. On a status in `successStatus`, parse the response body as JSON and check every key in `expectShape` matches the value in the response. `<PROMOTED_VERSION_SHA>` in `expectShape` is substituted at verify time with the promote record's `versionSha` field (the git commit sha the promoted version was built from).
+4. Pass on the first attempt whose status AND body-shape match.
+5. Fail the verify when any probe exhausts `maxAttemptsPerProbe` or when the cumulative elapsed time exceeds `windowMs`, whichever comes first. Emit `{ probePath, status, elapsedMs, outcome: 'failed', versionShaSeen }` on the result sink.
+
+## Compose boundary with observability-probe-endpoints
+
+The `/healthz` probe declared above is a DEPLOY-blueprint surface. Its body carries build provenance (`versionSha`, `builtAt`, `ciRunUrl`) because the verifier's reconciliation requires it (AC-12112-3). That body shape is NOT a supervisor-integration probe response; it is the deploy blueprint's own provenance readback.
+
+The `observability-probe-endpoints` blueprint contributes an operator-supervised probe interface derived from a target integration profile (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`). Every profile mandates a minimal response contract: `loadBalancer` requires an empty body; `kubernetes` requires exactly `{"status": "pass"|"fail"}`; the profile validator refuses any override that would add a field beyond the enumerated set. That contract's audience is the external supervisor whose conventions drive the wire shape; adding build-provenance fields to it would leak reconnaissance value to unintended readers and would fail the profile validator.
+
+When both blueprints compose, the project runs TWO probe surfaces with distinct paths and distinct contracts:
+
+- One `/health` (or the profile-declared path) owned by `observability-probe-endpoints`, whose body is minimal per its profile.
+- One `/healthz` (or the deploy-blueprint's chosen path, distinct from the profile's) owned by `deploy-cloudflare-workers`, whose body carries `{ versionSha, builtAt, ciRunUrl }` for the verifier.
+
+The two surfaces coexist on purpose; the deploy verifier never hits the profile-owned path and the external supervisor never hits the deploy-owned path. A project unsure which path is which picks distinct strings at apply time (`/health` for the profile, `/healthz` for the deploy verifier; or `/health` for the profile and `/build-info` for the deploy verifier) and documents both on the project's ADR set. Collapsing the two onto one path is not supported; the deploy verifier's provenance body would fail the profile validator, and stripping provenance from the body would break the verifier's reconciliation.
+
+## Reader notes
+
+- A dev-mode local URL (`http://localhost:<port>`, `http://127.0.0.1:<port>`) is refused by the verifier with `DEPLOY_DEV_MODE_INADMISSIBLE`. AC-12111-1 makes this a hard refusal at the verifier layer; AC-12111-2 accepts the vendor's preview and production URL patterns.
+- The health probe's response body carries `{ versionSha, builtAt, ciRunUrl }`. The Worker reads these at request time from the build-time constants injected by `build-and-upload`. AC-12112-2 requires the shape; AC-12112-3 makes the `versionSha` field the verifier's evidence that the promoted version is the version being served.
+- A probe path that returns 200 with the WRONG `versionSha` fails the probe. A stale response served by a routing layer that has not converged yet fails the probe; the retry window buys the propagation-lag window; a full exhaustion fails the release.
+- The project may add authenticated smoke probes; each carries an operator-chosen auth binding (a signed request header, a probe-only token) that lives in the secrets contract, not in this file. The verifier does not carry an `Authorization` header that would bypass a production auth layer; a probe surface that requires auth is exposed on a project-declared unauthenticated path (a signed-header contract for probes only, with a rotation cadence tied to the deploy-log).
+- The `/healthz` path (or whichever path the project picks) MUST be listed in `[assets] run_worker_first` when the Worker declares an `[assets]` binding whose directory contains any file that could shadow the path. Without the listing, the assets pipeline may serve a stale (or absent) response before the fetch handler runs, and the verifier reads a shape that is not the Worker's answer; see `wrangler-toml-shape.md` for the discipline.

package/blueprints/deploy-cloudflare-workers/assets/wrangler-samples/bootstrap-vs-steady-state.md

@@ -0,0 +1,87 @@
+# First-deploy bootstrap versus steady-state upload
+
+The blueprint's ship path (`wrangler versions upload` on every merge, `wrangler versions deploy <versionId>` on operator-triggered promote) works only against a Worker that already exists on the vendor. A fresh Worker has to be bootstrapped once with a different verb. This asset documents both flows.
+
+## Why the distinction exists
+
+The vendor refuses `wrangler versions upload` against a Worker that has not been deployed at least once:
+
+```
+You cannot upload a new version of a Worker that does not yet exist.
+Please run the 'deploy' command first.
+```
+
+The vendor also refuses `wrangler secret put <NAME>` against a Worker that does not yet exist:
+
+```
+This Worker does not exist yet, so secrets cannot be set in advance
+with 'wrangler secret put'.
+```
+
+And the vendor refuses `wrangler deploy` when the Worker code references secret bindings that have not been set:
+
+```
+The following required secrets have not been set: <NAME>, <NAME>, ...
+```
+
+The three refusals compose into one bootstrap constraint: the FIRST deploy has to (a) create the Worker, (b) set every referenced secret in the same act. Only `wrangler deploy --secrets-file <path>` satisfies both.
+
+## The bootstrap flow (once per Worker)
+
+Run this once, from an operator machine with the vendor credentials in the environment. The secrets file is a temp file in a directory the repo ignores; it must not touch the working tree and must not survive the run.
+
+```bash
+# 1. Compose a temp secrets file. Sourced from the project's secrets
+#    contract (see the security-secrets-management blueprint or the
+#    equivalent project-authored pipeline). NO plaintext in the shell
+#    history; use a here-doc into a temp path outside the repo.
+TMP_SECRETS="$(mktemp -t bootstrap-secrets.XXXXXX.json)"
+trap 'rm -f "$TMP_SECRETS"' EXIT
+
+# 2. Write the JSON object of secret NAME -> VALUE the Worker needs.
+#    The value strings are resolved from the secrets contract; this
+#    example shows the shape, not the values.
+cat > "$TMP_SECRETS" <<'JSON'
+{
+  "<SECRET_NAME_1>": "<value-from-secrets-contract>",
+  "<SECRET_NAME_2>": "<value-from-secrets-contract>"
+}
+JSON
+
+# 3. First deploy: creates the Worker on the vendor AND sets every
+#    secret in one atomic act.
+wrangler deploy --secrets-file "$TMP_SECRETS"
+
+# 4. The trap removes the temp file. Verify it's gone.
+[ ! -f "$TMP_SECRETS" ] || { echo "bootstrap-secrets leaked" >&2; exit 1; }
+```
+
+After the bootstrap deploy returns success, the Worker exists on the vendor, every referenced secret is set, and the steady-state ship path becomes available.
+
+## The steady-state flow (every merge and every operator-triggered promote)
+
+Once the Worker exists, the blueprint's ship path is the only one used:
+
+```bash
+# On every merge to main (build-and-upload workflow, see
+# `ci-workflows/build-and-upload.yml.md`):
+wrangler versions upload --preview-alias main
+
+# On operator-triggered promote (promote workflow, see
+# `ci-workflows/promote.yml.md`):
+wrangler versions deploy <versionId>
+
+# When a secret's value has to rotate, steady-state is `wrangler secret
+# put <NAME>` invoked from a CI step whose environment has the new value
+# from the secrets contract. No temp file, because the Worker already
+# exists.
+wrangler secret put <NAME>
+```
+
+## Reader notes
+
+- The bootstrap flow is a one-time operator act. The blueprint's Deploy Adapter (TAC-1301) does NOT wrap it; the adapter's verbs are the steady-state surface. A project that automates bootstrap wraps this shell flow in a project-local script under `scripts/deploy/` and gates it behind an explicit operator invocation.
+- The temp secrets file is the only shape wrangler 4.x accepts for pre-existence secret provisioning. Any alternative (`wrangler secret put` before `wrangler deploy`, an interactive prompt, environment-variable smuggling into `wrangler.toml`) either fails or leaks the value.
+- The `--secrets-file` path must be outside the repo working tree, deleted on shell exit, and never emitted to stdout. The bootstrap shell above uses `mktemp` and a `trap` to enforce this.
+- After bootstrap, the CI workflows never invoke `wrangler deploy`. Every version reaches the vendor via `wrangler versions upload` (which does NOT change the served version) and every production change rides `wrangler versions deploy <versionId>` from the promote workflow. Preserving this discipline is what keeps the promote-is-explicit invariant load-bearing.
+- A project that superseded the default vendor (per ADR-1302) with a different target (Fly.io, Vercel, a hyperscaler's FaaS, a self-hosted target) authors an equivalent bootstrap flow against that vendor's own create-and-provision primitives; the WHEN (once per environment, before steady-state) stays; the WHAT (which CLI verb, which primitive) is vendor-specific.