rcf-lite 0.12.0 → 0.13.0

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1305-deploy-cloudflare-workers-served-surface-verifier.json

@@ -0,0 +1,51 @@
+{
+  "tacId": "TAC-1305-deploy-cloudflare-workers-served-surface-verifier",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Served-surface Verifier",
+  "purpose": "The post-promote probe layer. Hits the SERVED surface (production URL by default; the preview alias URL when the promote gate is running a preview-only verify) with a fixed set of probe paths, retries within a bounded window, and returns a structured pass or fail the promote gate honours. Never targets a dev-mode local URL; refuses to accept a probe URL matching the dev-mode pattern.",
+  "responsibilities": [
+    "Hit every declared probe path against the target URL after `promoteVersion` returns success; each probe retries up to six times over up to sixty seconds with per-request timeouts of at most five seconds (AC-12110-1).",
+    "Pass a probe when the response status is in the project-declared success set AND the response body carries the expected shape. For the mandatory health probe, `expectShape.versionSha` is substituted at verify time with the promote record's `versionSha` field (the git commit sha the promoted version was built from), NOT with the promote record's `promotedVersionId` (the vendor-assigned version UUID); the two identifiers name different things and are never equal (AC-12110-2, AC-12112-3).",
+    "Fail the verify when any probe exhausts its retries without passing; emit the failing probe path, the last response status seen, and the elapsed time; return `PROMOTE_VERIFY_FAILED` (AC-12110-3).",
+    "Refuse a target URL matching the dev-mode local pattern (`http://localhost:*`, `http://127.0.0.1:*`, or the vendor's local emulator loopback host); return `DEPLOY_DEV_MODE_INADMISSIBLE` (AC-12111-1).",
+    "Accept a target URL matching the vendor's preview or production URL patterns (per-version-id URL, alias URL, custom-domain URL, workers.dev production host) (AC-12111-2).",
+    "Emit structured probe records the deploy log can persist: `{ probePath, status, elapsedMs, outcome, versionShaSeen }` per probe attempt."
+  ],
+  "internalStructure": "One async probe-runner per probe path, each retrying against the same target URL. The runner is a small state machine: attempt, on-fail sleep, retry until budget exhausted, resolve pass or fail. A property test enforces the retry-count and window bounds at build time. The probe-path set and the success-status set are project-declared configuration.",
+  "interfaces": [
+    {
+      "name": "probeConfig",
+      "kind": "read-api",
+      "description": "Project-supplied probe declaration: an array of `{ path, method?: 'GET'|'HEAD', successStatus: number[], expectShape?: object }`. At least one probe must be declared; the health probe is the mandatory one."
+    },
+    {
+      "name": "urlTarget",
+      "kind": "read-api",
+      "description": "The URL the verifier hits. Sourced from the Preview URL Resolver's `probeUrl('production', null)` for a promote verify, or `probeUrl('alias', <alias>)` for a preview-only verify."
+    },
+    {
+      "name": "httpClient",
+      "kind": "read-api",
+      "description": "The HTTP client the verifier drives (Node.js `fetch` in the default form; project-supplied for a project running under a different runtime)."
+    },
+    {
+      "name": "resultSink",
+      "kind": "callback",
+      "description": "Structured-record sink invoked with each probe attempt's outcome `{ probePath, status, elapsedMs, outcome, versionShaSeen }`."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Preview URL Resolver",
+      "kind": "tac",
+      "tacId": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+      "description": "Source of the URL the verifier hits; the resolver's `probeUrl` verb keeps URL assembly out of the verifier."
+    }
+  ],
+  "tradeoffs": "The retry bounds are opinionated (six attempts over sixty seconds). A project whose vendor propagates faster shrinks the window; a project whose vendor propagates slower buys a bigger budget by superseding the AC's numeric bound with a project-level ADR. The trade is the default catches propagation lag without turning a stuck workflow into a silent one; the numeric floor is the shape a project changes deliberately, not by drift. The verifier's probe path is a DEPLOY-blueprint surface whose response body carries build provenance; it is distinct from any external-supervisor probe surface a composing observability-probe-endpoints application declares. The two coexist on distinct paths with distinct contracts; see `assets/verification/served-surface-probes.md` for the boundary. A project composing both blueprints picks separate paths (`/health` for the profile, `/healthz` for the verifier, or equivalents) and refuses to collapse them.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1306-deploy-cloudflare-workers-deploy-ci-workflows.json

@@ -0,0 +1,64 @@
+{
+  "tacId": "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Deploy CI Workflows",
+  "purpose": "The two CI workflow files that operationalise the upload-and-promote model. `build-and-upload` runs on every merge to main and produces an uploaded version at the preview alias URL. `promote` runs only on explicit operator trigger and routes production to a named version id (or the newest-of-main) through the Promote Gate. Both workflows are the project's sole vendor-authenticated ship paths.",
+  "responsibilities": [
+    "Ship a `build-and-upload` workflow file whose trigger set is `push` scoped to the main branch (and any linear-history proxy), with no `pull_request` or `schedule` trigger (AC-12107-1, AC-12104-1).",
+    "The `build-and-upload` workflow checks out the tree at the merged commit, installs pinned dependencies, runs the project build, invokes `deployAdapter.uploadVersion({ previewAlias })`, and writes `versionId`, `versionIdUrl`, `previewAliasUrl` to the workflow's structured output and to the run summary (AC-12103-1, AC-12107-2).",
+    "The `build-and-upload` workflow injects the commit sha, an ISO 8601 build timestamp, and the CI run URL into the built bundle before `uploadVersion` runs; the values become the version's provenance surface (AC-12112-1).",
+    "Ship a `promote` workflow file whose trigger set is exclusively the platform's explicit-manual-trigger primitive (`workflow_dispatch` on GitHub Actions), declaring exactly one input `versionId` typed as an optional string (AC-12104-2, AC-12108-1).",
+    "The `promote` workflow calls the Promote Gate with the input `versionId`; on gate-side success, the workflow's summary carries `promotedVersionId`, `previousVersionId`, `promotedBy`, `promotedAt` (AC-12104-3, AC-12108-2, AC-12108-3).",
+    "Both workflows authenticate to the vendor using named CI secrets (`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` for the default vendor); the secrets are populated only into the vendor CLI's environment; no log line prints either byte sequence (AC-12107-3, AC-12106-2).",
+    "The CI gate that guards both workflows scans the change for wrangler-manifest issues (undeclared bindings, inline secrets, collapsed URLs) before the deploy verbs run; a lint failure refuses the workflow with a stable-coded error (AC-12101-2, AC-12101-3, AC-12105-2, AC-12106-3)."
+  ],
+  "internalStructure": "Two YAML workflow files (GitHub Actions form shipped as an asset under `assets/ci-workflows/`) plus a Node.js orchestration script per workflow that both files invoke. The scripts are the durable form; the YAML files are thin shims that platform-adapt the trigger set and input handling. A project on another CI platform authors platform-native trigger stanzas and calls the same orchestration scripts.",
+  "interfaces": [
+    {
+      "name": "workflowRuntime",
+      "kind": "read-api",
+      "description": "The CI platform's runtime (event context, actor login, workflow inputs, run URL, summary sink, structured-output sink). Consumed by the orchestration scripts."
+    },
+    {
+      "name": "promoteGate",
+      "kind": "read-write-api",
+      "description": "The Promote Gate (TAC-1304) callable; the `promote` workflow invokes it with the resolved `versionId` and the `promotedBy` principal from the workflow runtime."
+    },
+    {
+      "name": "buildStep",
+      "kind": "read-api",
+      "description": "Project-authored build step invoked by `build-and-upload` before `uploadVersion` runs; must produce the artefact the wrangler manifest's `main` points at."
+    },
+    {
+      "name": "secretBinding",
+      "kind": "read-api",
+      "description": "Named CI secrets the workflows read: `CLOUDFLARE_API_TOKEN` (or the operator-chosen vendor token name) and `CLOUDFLARE_ACCOUNT_ID` (or the operator-chosen account-id name); values populate the vendor CLI's environment via the platform's secret-injection primitive."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Deploy Adapter",
+      "kind": "tac",
+      "tacId": "TAC-1301-deploy-cloudflare-workers-deploy-adapter",
+      "description": "The workflows' only path to the vendor: `uploadVersion` from `build-and-upload`, and `promoteVersion` via the Promote Gate from `promote`."
+    },
+    {
+      "name": "Promote Gate",
+      "kind": "tac",
+      "tacId": "TAC-1304-deploy-cloudflare-workers-promote-gate",
+      "description": "The `promote` workflow delegates its full body to the gate; the workflow's role is trigger-set enforcement and input-declaration plumbing."
+    },
+    {
+      "name": "Wrangler Manifest",
+      "kind": "tac",
+      "tacId": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+      "description": "The CI gate's pre-flight lint reads the manifest and enforces the shape rules before either workflow's deploy verbs run."
+    }
+  ],
+  "tradeoffs": "The GitHub Actions form is shipped as a first-class asset because it is the CI platform the estate the blueprint targets uses today. A project on GitLab CI, Buildkite, CircleCI, or a self-hosted runner adapts the trigger stanzas and the input primitive; the orchestration scripts stay identical. The trade is a project on a non-GHA platform has to author the platform-native wrapper themselves; the payoff is the durable behaviour is in Node.js, not YAML.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12101.json

@@ -0,0 +1,54 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12101",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The repo-root wrangler manifest is the sole declaration of the Worker's deploy shape",
+  "asA": "operator reading a fresh repo",
+  "iWant": "one file at the repo root that declares the Worker name, entry, compatibility settings, and every binding",
+  "soThat": "the deploy shape is legible without reading CI scripts or a vendor dashboard",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12101-1",
+      "description": "A `wrangler.toml` (or `wrangler.jsonc`) exists at the repo root, parses as valid config, and its top-level object carries `name`, `main`, `compatibility_date`, and every non-secret binding block the Worker's runtime code references (KV namespaces, D1 databases, R2 buckets, Durable Object namespaces, static-assets binding, and non-secret environment variables); secret bindings are implicit through env-accessor references in the Worker source and are NOT declared in the manifest (wrangler 4.x has no `[secrets]` block, no `secrets.required[]` list, and no empty-value binding entry for secrets).",
+      "given": "a fresh clone of a repo that has applied the blueprint and realised the manifest",
+      "when": "a manifest loader parses the file",
+      "then": "the loader returns a config object whose `name` is a non-empty string, `main` resolves to an existing entry file, `compatibility_date` matches `\\d{4}-\\d{2}-\\d{2}`, and every non-secret binding name referenced from the Worker's source appears as a declaration key in the config; the config carries no `[secrets]` block",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12101-2",
+      "description": "A CI gate scans the Worker's source tree for references to bindings (env accessors keyed by binding name) and refuses the build when a referenced binding name has no matching declaration in `wrangler.toml`.",
+      "given": "a change adds `env.NEW_KV.get(...)` to the Worker source and does not add `NEW_KV` to `wrangler.toml`",
+      "when": "the CI gate runs on the change",
+      "then": "the run fails with a stable-coded `WRANGLER_BINDING_UNDECLARED` error naming the offending source path and the missing binding name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12101-3",
+      "description": "The manifest never carries a secret VALUE; a source-tree scan across every file that could contribute a bound value at deploy time (the wrangler config, any `.env`-shaped file the deploy step reads, any CI environment block committed to the repo) finds no match for any value the secrets contract resolves.",
+      "given": "the secrets contract resolves a set of secret values `V` for the current environment",
+      "when": "a redaction-scanner runs against `wrangler.toml`, any committed environment file, and the CI workflows",
+      "then": "no file in the scanned set contains any byte sequence in `V`",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12101-4",
+      "description": "When the manifest declares an `[assets]` block AND the Worker's fetch handler installs an auth gate on any route whose path could be shadowed by a file under the assets `directory`, the manifest MUST declare `[assets] run_worker_first` naming every gated route (glob-matched); a deployed request to any listed path is answered by the fetch handler before the assets pipeline runs. Without the listing, the assets pipeline serves the shadowing file directly and the auth gate is silently bypassed at the edge.",
+      "given": "a Worker whose fetch handler installs an auth middleware on `/notes` and a `./public/notes.html` file present at build time; the deployed Worker is reachable at production URL P",
+      "when": "an unauthenticated HTTP GET hits `P/notes`",
+      "then": "the response is the auth middleware's unauthenticated response (a redirect to sign-in, a 401, or the middleware's declared shape); the response is NOT the byte content of `./public/notes.html`; a manifest that omits `/notes` from `[assets] run_worker_first` fails the deployed observation because the assets pipeline answered before the fetch handler ran",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12102.json

@@ -0,0 +1,45 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12102",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One deploy adapter is the sole caller of the deploy CLI",
+  "asA": "engineer reading the project",
+  "iWant": "a single named module every path imports to talk to the deploy vendor",
+  "soThat": "changing vendors is a one-module change and duplicate CLI call paths cannot drift",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12102-1",
+      "description": "The project exposes one Deploy Adapter module whose public surface is `uploadVersion`, `promoteVersion`, `listVersions`, `resolveNewestOfMain`, and `describeVersion`; the module is the only source file that spawns the vendor CLI binary or imports the vendor's deploy SDK.",
+      "given": "a project that has applied the blueprint and realised TAC-1301",
+      "when": "the source tree is scanned for spawns of `wrangler` (or the vendor's CLI binary name) and for imports of the vendor's deploy SDK identifier",
+      "then": "the only source file that matches either scan is the Deploy Adapter module; no other module names an alternative deploy call path",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12102-2",
+      "description": "The adapter's `uploadVersion({ previewAlias })` verb returns `{ versionId, versionIdUrl, previewAliasUrl }` on success and refuses to complete when the alias argument is empty.",
+      "given": "a Deploy Adapter instance backed by the default vendor",
+      "when": "a caller invokes `deployAdapter.uploadVersion({ previewAlias: 'main' })`",
+      "then": "the call resolves with a `versionId` string matching the vendor's version-id format, a `versionIdUrl` naming the per-version URL, and a `previewAliasUrl` whose host segment carries the alias `main`; a call with `previewAlias: ''` throws a `DEPLOY_PREVIEW_ALIAS_REQUIRED` error",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12102-3",
+      "description": "The adapter's `promoteVersion({ versionId })` verb refuses when `versionId` is not present in `listVersions()`.",
+      "given": "an adapter whose `listVersions()` returns a set that does not include the id `bogus-v1`",
+      "when": "a caller invokes `deployAdapter.promoteVersion({ versionId: 'bogus-v1' })`",
+      "then": "the call throws a `DEPLOY_VERSION_NOT_FOUND` error naming `bogus-v1` and no vendor promote call is issued",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12103.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12103",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every merge to main produces an uploaded version at a stable preview alias URL",
+  "asA": "reviewer of a merged change",
+  "iWant": "a stable preview URL that always resolves to the newest-of-main uploaded version",
+  "soThat": "I can look at the change on a live surface without waiting for a production promote",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12103-1",
+      "description": "A successful `build-and-upload` CI run on a merge to main leaves the preview alias URL resolving to the version id the run just uploaded, and the version-id URL resolving to the same version permanently.",
+      "given": "a merge to main triggers `build-and-upload` and it exits zero with recorded `versionId` V and `previewAliasUrl` A and `versionIdUrl` U",
+      "when": "an HTTP request hits A and then a second HTTP request hits U within five minutes of the run completing",
+      "then": "both responses carry the `versionSha` field of V's build provenance in the health-probe body, and the two responses agree on that field",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12103-2",
+      "description": "A subsequent merge that produces a new upload W leaves the preview alias URL resolving to W while the version-id URL for the previous version V still resolves to V.",
+      "given": "an upload V behind preview alias A followed by a fresh merge that produces upload W",
+      "when": "requests hit A and the version-id URLs for V and W after W's run completes",
+      "then": "the response at A carries W's `versionSha`; the response at V's version-id URL still carries V's `versionSha`; the two are distinct",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12103-3",
+      "description": "The uploaded version does not serve production traffic; the production URL continues to serve the version that was serving before the upload.",
+      "given": "production is serving version P and a merge lands producing upload W",
+      "when": "the `build-and-upload` run completes and no promote has run",
+      "then": "the production URL's health probe carries P's `versionSha`, not W's",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12104.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12104",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Production only changes via an explicit promote step",
+  "asA": "operator responsible for what production serves",
+  "iWant": "no code path that changes production as a side effect of a merge",
+  "soThat": "every ship is a deliberate act with a named principal on the record",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12104-1",
+      "description": "The project's CI workflow set contains no workflow that both triggers on `push` to main AND calls the Deploy Adapter's `promoteVersion` verb (or the vendor's coupled deploy verb `wrangler deploy`).",
+      "given": "the CI workflow set of a project that has applied the blueprint",
+      "when": "a lint scan walks every workflow file and inspects the trigger set of each and the deploy verb it invokes",
+      "then": "no workflow file both matches trigger `push` on branch `main` (or a linear-history proxy) AND invokes a promote verb; the scan reports zero offenders",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12104-2",
+      "description": "The `promote` workflow triggers only on explicit manual operator action, not on any push, pull-request, or schedule.",
+      "given": "the `promote` workflow file",
+      "when": "the trigger stanza is parsed",
+      "then": "the only trigger present is the platform's explicit-manual-trigger primitive (`workflow_dispatch` on GitHub Actions or the equivalent) and no `push`, `pull_request`, or `schedule` trigger appears",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12104-3",
+      "description": "Every successful promote leaves a structured record naming the version id promoted, the operator principal, the previously-serving version id, and the timestamp.",
+      "given": "a successful invocation of the `promote` workflow",
+      "when": "the deploy log store is inspected after the run",
+      "then": "a new record exists whose fields include `promotedVersionId`, `promotedBy`, `previousVersionId`, and `promotedAt`; every field is populated and no field carries a secret value",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1304-deploy-cloudflare-workers-promote-gate",
+    "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12105.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12105",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Preview and production surfaces live at distinct URLs both discoverable from the manifest",
+  "asA": "operator investigating a change or an incident",
+  "iWant": "one command to print the preview URLs and the production URL for the Worker",
+  "soThat": "the dashboard is not a step on any triage path",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12105-1",
+      "description": "The Deploy Adapter's `deploy status` (or equivalent named verb on the adapter surface) returns a structured object naming the current production URL, the preview alias URL, and the currently-serving version id.",
+      "given": "an operator on a machine authenticated to the deploy vendor",
+      "when": "the operator invokes the adapter's `deploy status` verb",
+      "then": "the response is a structured object whose fields include `productionUrl`, `previewAliasUrl`, and `currentlyServingVersionId`; every field is populated",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12105-2",
+      "description": "The preview alias URL and the production URL are never equal; a manifest whose production route resolves to the same host as the preview alias URL is refused by the adapter with a stable-coded error.",
+      "given": "a `wrangler.toml` whose production route stanza names the same host as the preview alias URL",
+      "when": "the adapter loads the manifest",
+      "then": "the load throws a `DEPLOY_URL_COLLAPSED` error naming both URLs; no deploy verb accepts the manifest",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12105-3",
+      "description": "A request to the production URL and a request to the preview alias URL immediately after an upload but before a promote resolve to different version ids in their health-probe responses.",
+      "given": "production serving version P and an uploaded-not-promoted version W behind preview alias A",
+      "when": "a health probe hits the production URL and a second health probe hits A",
+      "then": "the production response body carries `versionSha` of P and the preview response body carries `versionSha` of W; the two values are not equal",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12106.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12106",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Secret bindings resolve through the secrets contract; no secret value ever lives in the manifest",
+  "asA": "reviewer of a change that touches deploy config",
+  "iWant": "certainty that a PR touching wrangler config cannot leak a secret",
+  "soThat": "review moves as fast as the config change and nothing else",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12106-1",
+      "description": "Every secret binding the Worker consumes at runtime is referenced implicitly via the runtime's env accessor (in the default JS/TS Worker, `env.<NAME>`) in the Worker source; wrangler 4.x has no `[secrets]` block, no `secrets.required[]` list, and no empty-value binding entry for secrets, and the vendor treats each such env-accessor reference as an implicit secret binding declaration and refuses `wrangler deploy` when the referenced secret has not been set on the target. Each such name is populated on the deploy target through the vendor's own secret-set flow, sourced from the project's secrets contract.",
+      "given": "a project that has applied both this blueprint and the `security-secrets-management` blueprint (or an equivalent project-authored secrets contract)",
+      "when": "the Worker source is scanned for env-accessor references that resolve to secret bindings (per the manifest loader's binding-kind classification) and each such name is cross-checked against the secrets contract's declared names",
+      "then": "every implicitly-referenced secret name maps to a name declared in the secrets contract; every name has a resolvable value in the active deploy environment; the manifest carries no `[secrets]` block, no `secrets.required[]` list, and no binding declaration with an inline secret value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12106-2",
+      "description": "The CI workflows redact any log line that would emit a resolved secret value.",
+      "given": "a CI run whose steps read a resolved secret value into a shell step that would echo it",
+      "when": "the run's captured logs are inspected byte-for-byte after completion",
+      "then": "no log line contains any byte sequence in the resolved-values set; every substitution shows a fixed placeholder in the emitted line",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12106-3",
+      "description": "A committed file whose bytes match any resolved secret value is refused by the CI gate.",
+      "given": "a change that adds a file whose contents include a byte sequence equal to any resolved secret value",
+      "when": "the CI gate scans the change",
+      "then": "the run fails with a stable-coded `DEPLOY_SECRET_LEAKED_IN_FILE` error naming the offending path and the logical name of the matching secret",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12107.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12107",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The build-and-upload workflow runs on every merge to main and records the version id",
+  "asA": "reviewer following a merged change",
+  "iWant": "the CI run for the merge to surface the uploaded version id and both preview URLs",
+  "soThat": "I can reach the preview surface and reference the version id without hunting",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12107-1",
+      "description": "The `build-and-upload` workflow triggers on `push` to the `main` branch (and on the project's chosen linear-history proxy for merges), and does not trigger on `pull_request` or any other event.",
+      "given": "the `build-and-upload` workflow file",
+      "when": "the trigger stanza is parsed",
+      "then": "the trigger set contains `push` scoped to the `main` branch (or the equivalent linear-history proxy); it contains no `pull_request` or `schedule` trigger",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12107-2",
+      "description": "A successful run writes the uploaded version id, the version-id URL, and the preview alias URL to a structured output the `promote` workflow's `resolveNewestOfMain` path can read.",
+      "given": "a successful `build-and-upload` run on a merge to main",
+      "when": "the run's outputs are inspected after completion",
+      "then": "a structured output object exists whose fields include `versionId`, `versionIdUrl`, and `previewAliasUrl`; every field is populated with a non-empty string; the `previewAliasUrl` host segment carries the operator-chosen alias string",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12107-3",
+      "description": "The workflow authenticates to the vendor through named CI secrets (a vendor API token and a vendor account id) scoped to the Worker's account; neither secret ever appears in any log line.",
+      "given": "a `build-and-upload` run that reads the vendor API token and account id from named CI secrets",
+      "when": "the run's captured logs are inspected byte-for-byte",
+      "then": "no log line contains the API token bytes; no log line contains the account id bytes; both are populated only into the vendor CLI's environment and redacted from any emitted line",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows",
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12108.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12108",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The promote workflow is manually triggered and accepts an optional versionId input",
+  "asA": "operator shipping a change to production",
+  "iWant": "one promote workflow that ships the newest-of-main by default and accepts an explicit version id",
+  "soThat": "the common ship, a hotfix, and a rollback all travel the same path",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12108-1",
+      "description": "The `promote` workflow declares one input field `versionId` typed as an optional string.",
+      "given": "the `promote` workflow file",
+      "when": "the input stanza is parsed",
+      "then": "one input `versionId` exists and is not marked required; the workflow declares no other input fields",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12108-2",
+      "description": "A promote invocation with an empty `versionId` input resolves the newest-of-main by querying the Deploy Adapter's `resolveNewestOfMain` verb and then promotes THAT version.",
+      "given": "the preview alias `main` currently resolves to version W",
+      "when": "the `promote` workflow runs with `versionId=''`",
+      "then": "the workflow invokes `resolveNewestOfMain` returning W, calls `promoteVersion({ versionId: W })`, and the recorded promote record names W as `promotedVersionId`",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12108-3",
+      "description": "A promote invocation whose input `versionId` is not present in `listVersions()` fails before calling `promoteVersion` and records nothing to the deploy log.",
+      "given": "an id `not-a-version` absent from `listVersions()`",
+      "when": "the `promote` workflow runs with `versionId='not-a-version'`",
+      "then": "the run fails with the `DEPLOY_VERSION_NOT_FOUND` code from the adapter, no vendor promote call is issued, and no promote record is appended to the deploy log",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1304-deploy-cloudflare-workers-promote-gate",
+    "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12109.json

@@ -0,0 +1,47 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12109",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Rollback is a promote of a prior version id",
+  "asA": "operator responding to a bad release",
+  "iWant": "the same promote workflow to take a prior version id and route production to it",
+  "soThat": "rollback carries the same audit shape and post-promote verification as every other ship",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12109-1",
+      "description": "The Deploy Adapter's `listVersions` verb returns the recent version history with the currently-serving version id marked; the `promote` workflow's `versionId` input accepts any id present in this list.",
+      "given": "an operator on a machine authenticated to the deploy vendor",
+      "when": "the operator invokes `deployAdapter.listVersions()` and picks a prior id P then triggers the `promote` workflow with `versionId=P`",
+      "then": "`listVersions` returns a list containing P with the currently-serving flag on the correct entry; the `promote` run succeeds; the deploy-log record names P as `promotedVersionId` and the prior currently-serving id as `previousVersionId`",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12109-2",
+      "description": "The project's source tree contains no separately-authored `rollback` verb that bypasses the `promote` workflow, the deploy-log record, or the post-promote verifier.",
+      "given": "the project source tree",
+      "when": "a scan searches for verbs named `rollback` (or synonyms `revert`, `undoPromote`) that spawn the vendor CLI or issue a vendor deploy call outside the Deploy Adapter",
+      "then": "no such verb exists; every rollback path routes through the `promote` workflow and the Deploy Adapter",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12109-3",
+      "description": "A rollback promote runs the served-surface verifier against the production URL and fails the run if any probe path fails, exactly like a forward promote.",
+      "given": "a promote of a prior version id P that intentionally fails a probe (a probe path P is missing from the older bundle)",
+      "when": "the `promote` workflow completes",
+      "then": "the workflow exits non-zero with `PROMOTE_VERIFY_FAILED`; the failing probe path and the response status are recorded; the deploy-log record does not mark the release successful",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter",
+    "TAC-1304-deploy-cloudflare-workers-promote-gate",
+    "TAC-1305-deploy-cloudflare-workers-served-surface-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12110.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12110",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every promote runs bounded served-surface probes and fails on breach",
+  "asA": "operator answering to a released change",
+  "iWant": "the promote workflow to fail loudly and record diagnostics when the promoted version does not serve correctly",
+  "soThat": "a bad promote never quietly stays in place while the pipeline reports green",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12110-1",
+      "description": "The Served-surface Verifier hits the fixed probe path set against the PRODUCTION URL immediately after `promoteVersion` returns success; every probe is retried up to six times over up to sixty seconds with per-request timeouts of at most five seconds.",
+      "given": "a promote of version W and a project-declared probe set including path `/healthz`",
+      "when": "the verifier runs",
+      "then": "at least one HTTP request to the production URL's `/healthz` completes within the sixty-second window; the request carries no `Authorization` header that would bypass a production auth layer; the retry count for any single probe does not exceed six",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12110-2",
+      "description": "A probe passes when the response status is in the project-declared success set AND the response body carries the expected shape. For the mandatory health probe, `expectShape.versionSha` is substituted at verify time with the promote record's `versionSha` field (the git commit sha the promoted version was built from); the substitution value is NOT the promote record's `promotedVersionId` (the vendor-assigned version UUID), which names a different identifier and will never match the health-probe body.",
+      "given": "a successful promote of W with promote record `{ promotedVersionId: 'v-uuid-W', versionSha: 'sha-W' }` and a `/healthz` probe declared as `{ status: [200], expectShape: { versionSha: '<PROMOTED_VERSION_SHA>' } }`",
+      "when": "the verifier receives the response",
+      "then": "the verifier substitutes `sha-W` into the `expectShape.versionSha` slot before requesting; the probe passes exactly when the status is 200 AND the JSON body's `versionSha` matches `sha-W`; a 200 response whose `versionSha` names a different sha fails the probe",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12110-3",
+      "description": "If any probe path exhausts its retries without passing, the workflow exits non-zero with the stable code `PROMOTE_VERIFY_FAILED` and records the failing probe path, the last response status seen, and the elapsed time to the deploy log.",
+      "given": "a promote of a version whose `/healthz` never returns 200 within the window",
+      "when": "the verifier completes",
+      "then": "the workflow exits non-zero; the exit records include the stable code `PROMOTE_VERIFY_FAILED`; the deploy log entry names the failing probe path, the last status observed, and the elapsed time; the release is not marked successful",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1305-deploy-cloudflare-workers-served-surface-verifier",
+    "TAC-1304-deploy-cloudflare-workers-promote-gate"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}