rcf-lite 0.12.0 → 0.13.0

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6104.json

@@ -0,0 +1,37 @@
+{
+  "usId": "ci-pipeline-US-6104",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The suite runs per-AC strict coverage and fails the pipeline on any gap",
+  "asA": "reviewer accountable for the RCF chain on merge",
+  "iWant": "the pipeline to have already run `rcf audit coverage --strict` and refused on any AC without a resolving TC",
+  "soThat": "a merge that ships an AC unbound to a TC is impossible",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6104-1",
+      "description": "The suite invokes `rcf audit coverage --strict` as a required gate after `rcf define validate`. The gate's exit code, captured stdout, and captured stderr are written to a per-gate report at the configured stable path.",
+      "given": "the pipeline has run against the head commit",
+      "when": "the reviewer opens the per-gate report file at `<reportDir>/coverage-strict.json`",
+      "then": "the file exists, its `gate` field is `coverage-strict`, its `command` field names the `rcf audit coverage --strict` invocation, its `exitCode` field records the underlying process exit code, and its `stdout` and `stderr` fields carry the captured streams",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6104-2",
+      "description": "A non-zero exit from `rcf audit coverage --strict` (exit 4 on gaps, per mechanism) marks the aggregate verdict as failed and the aggregate exit code as non-zero. The suite never substitutes shallow-any coverage for strict coverage.",
+      "given": "an invocation of the suite against a tree with a deliberately uncovered AC",
+      "when": "the suite completes",
+      "then": "the aggregate report's `verdict` field is `failed`, its `gates[]` entry for `coverage-strict` records `outcome: failed` with the underlying exit code preserved, and no gate report on disk records a shallow-any invocation for coverage",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner",
+    "TAC-702-ci-pipeline-gate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6105.json

@@ -0,0 +1,36 @@
+{
+  "usId": "ci-pipeline-US-6105",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every gate leaves a machine-readable JSON report at a stable path",
+  "asA": "downstream reader of the pipeline (a reviewer, a dashboard, an audit tool)",
+  "iWant": "each gate the suite runs to write a JSON report file at a stable relative path with a stable schema",
+  "soThat": "I can pick up the gate's outcome without re-running it or scraping the CI provider's log surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6105-1",
+      "description": "Every gate the suite runs writes a JSON report file at `<reportDir>/<gate>.json` whether the gate passed or failed. The report carries a fixed set of fields: `gate`, `command`, `toolVersion`, `startedAt`, `endedAt`, `durationMs`, `exitCode`, `outcome`, `stdout`, `stderr`.",
+      "given": "the suite has run against any tree",
+      "when": "the reviewer inspects the configured report directory after the run",
+      "then": "for every gate named in the aggregate report's `gates[]` array, a file at `<reportDir>/<gate>.json` exists whose top-level keys are exactly the fixed set above, and the value types match the stable schema (`startedAt` and `endedAt` are ISO-8601 strings, `durationMs` is an integer, `exitCode` is an integer, `outcome` is one of `passed` or `failed`)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6105-2",
+      "description": "The `toolVersion` field records the underlying CLI's version string (the value `rcf --version` prints) at the time the gate ran. A tool-version mismatch across two pipeline runs of the same commit is visible in the report without re-running the gate.",
+      "given": "two invocations of the suite against the same commit under two different installed versions of the `rcf` CLI",
+      "when": "the reviewer diffs the two runs' per-gate reports",
+      "then": "the `toolVersion` field in the affected per-gate reports differs between the two runs, and the value on each side matches what the invoked `rcf --version` prints on that host",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-702-ci-pipeline-gate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6106.json

@@ -0,0 +1,36 @@
+{
+  "usId": "ci-pipeline-US-6106",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The suite emits an aggregate pipeline report at a stable path",
+  "asA": "downstream reader who needs the single-record verdict of a pipeline run",
+  "iWant": "an aggregate report at a stable path summarising every gate's outcome and pointing at the per-gate reports",
+  "soThat": "the pipeline's answer is one JSON file whose shape I can rely on across blueprint minor versions",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6106-1",
+      "description": "The suite writes an aggregate report at `<reportDir>/pipeline.json` on every run. The aggregate carries `verdict`, `trigger`, `startedAt`, `endedAt`, `durationMs`, `runner.entryPoint`, and `gates[]` (each entry naming `gate`, `outcome`, `durationMs`, and `reportPath`).",
+      "given": "the suite has run against any tree",
+      "when": "the reviewer opens `<reportDir>/pipeline.json`",
+      "then": "the file exists, its top-level keys are exactly the fixed set above, `verdict` is one of `passed` or `failed`, `gates[]` is a non-empty array in fixed configured order, and every `reportPath` value resolves to an existing per-gate report file at that relative path",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6106-2",
+      "description": "The aggregate verdict is `passed` if and only if every gates[] entry's `outcome` is `passed` and no entry's outcome is `missing`.",
+      "given": "any suite run whose gates[] array contains at least one entry with outcome `failed` or `missing`",
+      "when": "the reviewer reads the aggregate report",
+      "then": "the aggregate report's `verdict` field is `failed`, and the aggregate does not record `passed` while any per-gate entry recorded a non-`passed` outcome",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-703-ci-pipeline-aggregate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6107.json

@@ -0,0 +1,37 @@
+{
+  "usId": "ci-pipeline-US-6107",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A gate failure surfaces the failing gate and its report path in the operator-visible output",
+  "asA": "reviewer whose first look at a red CI job is the runner-log tail",
+  "iWant": "the tail of the failing pipeline job to name the failing gate and point me at the report file",
+  "soThat": "I find the detail I need without clicking through the provider's UI",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6107-1",
+      "description": "On any gate failure, the Node entry point writes an operator-readable failure summary to its own stderr naming the failing gate, its exit code, and the relative path to the per-gate report file.",
+      "given": "an invocation of the suite whose `validate` (or any) gate fails",
+      "when": "the reviewer reads the runner-log tail (the Node process's own stderr)",
+      "then": "the tail contains a single-line summary matching the shape `[ci-pipeline] gate '<gate>' failed (exit <n>); report: <reportDir>/<gate>.json`, and the reference report file exists at the named path",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6107-2",
+      "description": "The suite continues past a failing gate to run the remaining required gates and record their outcomes. Multiple gate failures produce multiple entries in the aggregate report's `gates[]` array, each carrying its own outcome and report path.",
+      "given": "a suite invocation against a tree that fails both `validate` and `coverage-strict`",
+      "when": "the suite completes",
+      "then": "the aggregate report's `gates[]` array contains both `validate` and `coverage-strict` entries, each with `outcome: failed`, and each with a `reportPath` value pointing to an existing per-gate report file",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner",
+    "TAC-703-ci-pipeline-aggregate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6108.json

@@ -0,0 +1,37 @@
+{
+  "usId": "ci-pipeline-US-6108",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A missing gate report is never treated as an implicit pass",
+  "asA": "reviewer trusting the aggregate report as the sole ledger of what actually ran",
+  "iWant": "the aggregate verdict to be `failed` on any missing required gate report",
+  "soThat": "a runner crash, an unhandled exception, or a write failure cannot be indistinguishable from success",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6108-1",
+      "description": "The aggregate report records the fixed configured set of required gates as its `gates[]` array in configured order. A required gate whose per-gate report file was not written during the run is recorded in the array with `outcome: missing` and a `reason` field naming the failure mode.",
+      "given": "a suite invocation in which the `coverage-strict` gate's Node child process was killed before its report could be written (or the report directory was not writable, or the child exited with an uncaught exception)",
+      "when": "the aggregate report is written at the end of the run",
+      "then": "the aggregate report's `gates[]` array contains a `coverage-strict` entry with `outcome: missing`, its `reason` field carries a non-empty string, and the aggregate `verdict` is `failed`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6108-2",
+      "description": "The Node entry point's process exit code is non-zero when any required gate's outcome is `missing`, even if no gate outcome is `failed`.",
+      "given": "a suite invocation whose required-gate set has one gate outcome `missing` and every other outcome `passed`",
+      "when": "the Node entry point completes",
+      "then": "the process exit code is non-zero, and the aggregate report's `verdict` is `failed`",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner",
+    "TAC-703-ci-pipeline-aggregate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6109.json

@@ -0,0 +1,36 @@
+{
+  "usId": "ci-pipeline-US-6109",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The blueprint provides one illustrative GitHub Actions example; alternate providers wire the same entry point",
+  "asA": "operator setting up CI on an rcf-lite project for the first time",
+  "iWant": "one worked example that shows the entire trigger, setup, invoke, and artefact-upload shape",
+  "soThat": "I have a copy-paste starting point regardless of which provider I use",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6109-1",
+      "description": "The applied blueprint's source path (recorded on `manifest.blueprints[ci-pipeline].source`) contains an illustrative GitHub Actions workflow at `assets/ci-provider-examples/github-actions.yml`. The workflow defines the required triggers (push to the default branch and pull_request into it), sets up Node and the package manager, installs dependencies, invokes the Node entry point as a single command line, and uploads the report directory as a workflow artefact.",
+      "given": "an rcf-lite project that has applied this blueprint",
+      "when": "the operator opens the blueprint's source path and reads `assets/ci-provider-examples/github-actions.yml`",
+      "then": "the workflow file exists at that path, its `on:` block names `push` on the default branch and `pull_request`, its steps include a Node setup and a package-manager setup, one step invokes the gate entry point as a single `node <path>` line (or a package-manager script that resolves to the same), and a final step uploads the configured report directory as a workflow artefact",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6109-2",
+      "description": "The applied blueprint's guide names GitLab CI, CircleCI, Buildkite, and Jenkins as equally supported providers, states the mapping (job trigger, Node setup, single-line entry-point invocation, artefact upload), and states that the blueprint does not ship provider-specific configuration for those runners.",
+      "given": "an rcf-lite project that has applied this blueprint",
+      "when": "the operator opens `guide/ci-pipeline.md` from the blueprint's source path",
+      "then": "the guide's `when to reach for it` or an adjacent section names GitLab CI, CircleCI, Buildkite, and Jenkins by name, describes the four mapping points, and states that no provider-specific configuration file for those runners is shipped by the blueprint at v1.0.0",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6110.json

@@ -0,0 +1,36 @@
+{
+  "usId": "ci-pipeline-US-6110",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The gate suite entry point runs the same code path locally as in CI",
+  "asA": "developer reproducing a CI failure on my own machine",
+  "iWant": "the exact command the CI job ran to run the same way on my checkout",
+  "soThat": "I reproduce the failure without guessing which flag or wrapper produced it",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6110-1",
+      "description": "The CI provider's job step invokes the Node entry point with the same command a developer runs locally: the same file path, the same required arguments, the same environment variables the entry point reads (report directory path, tool-version pin). No CI-only wrapper script sits between the runner and the Node entry point.",
+      "given": "an rcf-lite project with this blueprint applied and a CI job wired per the illustrative example",
+      "when": "a developer runs the same command line the CI job's invocation step records against their local checkout at the same commit",
+      "then": "the aggregate report the local run writes at the configured report directory carries the same `runner.entryPoint`, the same `gates[]` ordering, and the same per-gate outcomes as the CI run's aggregate report for that commit, given the same rcf CLI version installed locally",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6110-2",
+      "description": "The gate entry point reads no CI-provider-specific environment variable to alter its behaviour. Every configuration input the entry point honours is documented and available to a developer running locally.",
+      "given": "the applied blueprint's source path and the project's realised gate entry point",
+      "when": "the reviewer greps the entry point's source and its dependency modules for reads against known CI-provider environment variables (`GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `BUILDKITE`, `JENKINS_URL`)",
+      "then": "no read of any of those variables gates the entry point's control flow or its gate set; if any such variable is read it is only for reporting into the aggregate report's `runner.environment` metadata field",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/docs/topics.md

@@ -0,0 +1,49 @@
+# ci-pipeline blueprint coordination vocabulary
+
+This file is the ci-pipeline half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | ci-pipeline contribution | Origin | Composition note |
+|---|---|---|---|
+| `ciGates` | ADR-701-ci-pipeline-ci-gates | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The fixed ordered required-gate set the pipeline runs. Any composing blueprint that ships its own required-gate opinion (an adherence-pack blueprint, a browser-verify blueprint, an observability probe blueprint) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the extended set and states the reasoning |
+| `strictCoverageGate` | ADR-702-ci-pipeline-strict-coverage-gate | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, and hello-panel | The coverage-mode posture for the required gate (per-AC strict, not shallow-any). A composing blueprint that holds an opinion on coverage-mode policy (a shallow-any-for-early-projects blueprint, a coverage-with-grace-window blueprint) conflicts here by design. Expected resolution: one project-level ADR fixing the coverage posture |
+
+The ci-pipeline blueprint claims two global topics. Every other contribution is scope-local (ADR-703 on node-only runner shape and ADR-704 on report shape do not contribute global topics; a composing blueprint that holds an opinion on runner language or report shape authors its own project-level ADR if it wants to override).
+
+Note on the delineation from the application-api-rest blueprint's `logging` topic and the persistence-data-sqlite blueprint's store event log: `logging` (owned by application-api-rest ADR-304) governs the wire-log shape of the HTTP tier; persistence ADR-603 governs the store-event log shape. This blueprint's report shape (ADR-704) governs the pipeline-run report shape, which is a build-time artefact, not a runtime log. The three surfaces may share a shipper but do not share a topic. A blueprint that contributes a unified telemetry discipline across build-time and runtime surfaces would author its own scope:global ADR and expect to conflict with all three, not just here.
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, and persistence vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`ciChecks`, `pipelineGates`, `strictCoverage`, `coverageStrict` are all wrong when `ciGates` and `strictCoverageGate` already exist).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 6101-6110 sit at the LOW end of the 6101-6899 band on purpose. A project-side story that mechanically derives from `ci-pipeline-REQ-011` into the number `6111` would collide against ci-pipeline-US-6111 in this package; the band leaves headroom at the HIGH end (US 6181-6899) so a project's own stories anchored to ci-pipeline REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `ciGates` exactly as spelled here when your blueprint holds an opinion on the required-gate set the pipeline runs; contribute your own scope:global ADR on that string and let composition surface the pairing. An observability-essentials blueprint that ships health-probe or status-page gates as required will conflict here by design.
+- Reuse `strictCoverageGate` exactly as spelled here when your blueprint holds an opinion on the coverage-mode policy (strict per-AC versus shallow-any versus grace-window); a blueprint that ships a different posture conflicts here.
+- This blueprint's decision states the two required gates at v1.0.0 (`validate` and `coverage-strict` in that order) and the Node-only entry-point shape. Compose compatible adherence packs, browser-verify shipping, or observability probes, or expect the operator to supersede with one project-level ADR per topic.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `healthProbes`, `statusPageContract`, and `readinessSemantics` (an observability-essentials blueprint's natural globals), `adherencePack` (an adherence-shipping blueprint's natural global), and `mutationSampling` (a mutation-testing blueprint's natural global). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.

package/blueprints/ci-pipeline/guide/ci-pipeline.md

@@ -0,0 +1,79 @@
+# Ci-pipeline blueprint guide
+
+## What it is
+
+A default CI floor for rcf-lite projects. The blueprint contributes the WHAT of a pipeline pattern: which gates run, in which order, what constitutes a passed run, what report files land on disk after every run, and how a failing run surfaces the failing gate in the operator's own log tail. The pipeline is a single Node entry-point script the CI job invokes with one line, and the gate set at v1.0.0 is exactly two required gates: `rcf define validate` followed by `rcf audit coverage --strict`.
+
+Concretely, the blueprint ships ten requirements, ten user stories (twenty acceptance criteria), three architecture components, and four architecture decision records. Two ADRs are `scope: global` on the topics `ciGates` (the fixed required-gate set) and `strictCoverageGate` (the per-AC strict coverage posture); the other two are scope-local (the Node-only runner shape and the JSON report shape) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a matrix of provider-specific configuration files. One illustrative GitHub Actions workflow ships under `assets/ci-provider-examples/github-actions.yml` as a copy-paste starting point. Alternate providers (GitLab CI, CircleCI, Buildkite, Jenkins) wire the same Node entry point per the four-point mapping named below; the blueprint does not carry a per-provider configuration file for those runners at v1.0.0.
+
+Not a source-code contribution. The blueprint contributes the gate-runner contract, the per-gate report writer contract, the aggregate report writer contract, and the discipline that binds them. The project realises the Node entry point against those contracts in its own build cycle; the blueprint does not ship the entry-point source.
+
+Not a linter, formatter, or unit-test gate. The v1.0.0 required-gate set is two gates that speak to the RCF chain and its coverage. A project that wants to add a linter or a unit-test gate authors a project-level ADR superseding ADR-701 and lists the extended gate set; the runner set is a decision area, not a runtime knob.
+
+Not a merge-queue integration. A project that wants a merge queue reads the aggregate report from the queue tool of its choice; the blueprint owns the aggregate report shape and stability, not the queue tool wiring.
+
+Not a coverage-trend dashboard. A project that wants one reads the aggregate reports over time and layers the dashboard on top; the blueprint owns the per-run reports, not the trend view.
+
+Not a branch-protection or merge-policy configuration. AC-6101-2 states the property the project owes on the platform's own configuration surface (branch protection, required checks, or the equivalent), but the blueprint does not ship that configuration file.
+
+## When to reach for it
+
+Reach for the ci-pipeline blueprint when:
+
+- The project is an rcf-lite deployment with an RCF chain and a default branch merged into through pull requests.
+- The project's CI provider can run Node 24 or later on its runner (every mainstream provider can: GitHub Actions, GitLab CI, CircleCI, Buildkite, Jenkins).
+- The project wants the RCF chain and its per-AC strict coverage 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 the same command line to reproduce a CI failure on a developer's machine.
+
+## When it does not fit
+
+Do not reach for the ci-pipeline blueprint when:
+
+- The project does not use RCF (no `rcf/` tree, no `rcf define validate` invocation makes sense). A project without an RCF chain does not need this blueprint; its pipeline is a different shape entirely.
+- The project runs on a CI provider whose runners cannot execute Node 24 or later (a legacy internal Jenkins pool locked to Node 12, an embedded hardware CI). Upgrade the runner or supersede ADR-703 with a project-level ADR selecting a different runner shape.
+- The project's default branch model is trunk-based with no pull requests. The `push to default branch` half of the trigger still applies, but the pull-request half of AC-6101-1 does not; a project on trunk-based development authors a project-level ADR narrowing the trigger set.
+- The project wants a coverage-mode grace window on newly introduced ACs. Supersede ADR-702 with a project-level ADR stating the grace window and the reasoning.
+- The project wants the pipeline to include gates that are not shipped by any rcf-lite blueprint (a linter, a mutation-testing gate, a stack-specific unit-test runner). Supersede ADR-701 with a project-level ADR listing the extended set; the runner then invokes the added gates alongside the two required ones.
+
+## What a good outcome looks like
+
+A project applies the ci-pipeline blueprint on a fresh tree, realises the three TACs in project-authored FBSes, wires a CI job per the illustrative GitHub Actions workflow (or per the four-point mapping for its own provider), configures its branch protection to require the pipeline job as a merge-blocking check, and lands on a deployed pipeline where:
+
+- Every push to the default branch and every pull request into it fires the CI job automatically; the job's aggregate report at `.rcf/reports/ci/pipeline.json` records the trigger event, the timing, and the ordered gate outcomes.
+- A pull request whose head commit fails `rcf define validate` sees `validate` outcome as `failed` in the aggregate, sees the specific schema or reference issue in the per-gate report, and cannot be merged through the platform's standard merge path.
+- A pull request whose head commit passes `rcf define validate` but leaves an AC without a resolving TC sees `coverage-strict` outcome as `failed`, sees the specific `covered-unresolved` AC in the per-gate report, and cannot be merged.
+- A pull request whose head commit passes both gates sees `verdict: passed` in the aggregate, sees green on the platform's required-check surface, and can be merged.
+- A runner crash mid-suite (a killed Node child, a report write failure) produces an aggregate with `outcome: missing` for the affected gate and `verdict: failed`; the crash is not silently indistinguishable from a pass.
+- 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.
+- A downstream reader (a coverage-trend dashboard the project may add later) picks up successive aggregate reports over time without any scraping or provider-API integration.
+
+## Wiring alternate CI providers (four-point mapping)
+
+Every mainstream CI provider ships the same four ingredients under a different runner language. The blueprint's Node entry point is the fourth ingredient; the other three are provider-specific. The illustrative GitHub Actions workflow shows all four; alternate providers translate the first three and keep the fourth unchanged:
+
+1. Job trigger. GitHub Actions uses `on: push` and `on: pull_request` YAML; GitLab CI uses `rules:` with `if:` predicates on `$CI_COMMIT_BRANCH` and `$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`; CircleCI uses `workflows:` with `filters:` on branches; Buildkite uses pipeline conditions on the branch name; Jenkins declarative pipelines use `when { branch }` blocks.
+2. Node setup. GitHub Actions uses `actions/setup-node@vX`; GitLab CI images typically pre-install Node or use a Docker image; CircleCI uses `cimg/node` orbs; Buildkite installs Node in the queue's setup hook; Jenkins agents install Node through a tool config.
+3. Package-manager setup and install. Whichever manager the project uses (pnpm, npm, yarn, bun); the same `install --frozen-lockfile` (or equivalent) pattern applies everywhere.
+4. Node entry-point invocation and artefact upload. `node <path>` (or a package-manager script that resolves to the same); every provider ships an artefact-upload primitive that reads the configured report directory.
+
+The blueprint does not ship provider-specific configuration files for GitLab CI, CircleCI, Buildkite, or Jenkins at v1.0.0. A project on one of those providers hand-authors the trigger, setup, install, and artefact-upload steps in that provider's runner language and invokes the Node entry point unchanged.
+
+## Operator decisions that remain open after apply
+
+- Report directory path (default `.rcf/reports/ci/`; a project that wants a different location changes the configuration input to the runner). Blueprint owns the schema and the file names; project owns the path.
+- Gate set beyond the two required ones. Blueprint owns the required set (`validate` then `coverage-strict`); project supersedes ADR-701 with a project-level ADR to add gates.
+- Coverage-mode posture. Blueprint owns strict per-AC as the required posture; project supersedes ADR-702 with a project-level ADR if a different posture (shallow-any, grace-window) is thoughtfully accepted.
+- CI provider choice. Blueprint owns the Node entry-point shape and one illustrative provider example; project picks the provider and wires the trigger, setup, install, and artefact-upload steps.
+- Branch protection and merge-policy configuration on the default branch. Blueprint states the property (AC-6101-2); project configures the platform surface.
+- Artefact upload retention and destination. Blueprint owns the report directory and its stable paths; project owns how long the CI provider keeps the artefact and where a downstream reader picks it up.
+- Merge-queue integration, if any. Blueprint owns the aggregate report as the single-record verdict; project wires the merge-queue tool to read it.
+- Coverage-trend dashboard or audit-log integration, if any. Blueprint owns the aggregate schema stability; project owns the reader.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every push and every pull request into the default branch runs both gates every time; on a small tree that is seconds, on a large tree with a deep chain it can be tens of seconds of pipeline wall time per run. The strict-coverage posture makes every new AC a two-file edit (author the AC and author the TC that resolves it); a project that skips the TC hits the strict-coverage gate on the pull request rather than at merge time. Adding a gate is a project-level ADR and a code change to the entry-point runner, not a knob-flip in a config file, which is the intended shape but does cost the ADR. The illustrative GitHub Actions workflow is a starting point; a project on another provider owes the translation of the first three of the four mapping points. 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 pipeline that does not block merges. The report directory grows one per-gate file per gate per run; a project that runs the pipeline against a very short-lived branch may accumulate reports until the CI provider's artefact retention rolls them off. The atomic-write posture for report files costs one extra file-system syscall per report; the 256KB truncation cap on stdout and stderr costs the tail of a very verbose gate on runaway output.

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.