rcf-lite 0.21.0 → 0.23.0

package/blueprints/deploy-cloudflare-workers/blueprint.json

@@ -1,48 +1,246 @@
 {
   "slug": "deploy-cloudflare-workers",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "category": "deploy",
   "contributions": [
-    { "id": "deploy-cloudflare-workers-REQ-001", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-001.json" },
-    { "id": "deploy-cloudflare-workers-REQ-002", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-002.json" },
-    { "id": "deploy-cloudflare-workers-REQ-003", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-003.json" },
-    { "id": "deploy-cloudflare-workers-REQ-004", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-004.json" },
-    { "id": "deploy-cloudflare-workers-REQ-005", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-005.json" },
-    { "id": "deploy-cloudflare-workers-REQ-006", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-006.json" },
-    { "id": "deploy-cloudflare-workers-REQ-007", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-007.json" },
-    { "id": "deploy-cloudflare-workers-REQ-008", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-008.json" },
-    { "id": "deploy-cloudflare-workers-REQ-009", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-009.json" },
-    { "id": "deploy-cloudflare-workers-REQ-010", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-010.json" },
-    { "id": "deploy-cloudflare-workers-REQ-011", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-011.json" },
-    { "id": "deploy-cloudflare-workers-REQ-012", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-012.json" },
-    { "id": "deploy-cloudflare-workers-US-12101", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12101.json" },
-    { "id": "deploy-cloudflare-workers-US-12102", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12102.json" },
-    { "id": "deploy-cloudflare-workers-US-12103", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12103.json" },
-    { "id": "deploy-cloudflare-workers-US-12104", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12104.json" },
-    { "id": "deploy-cloudflare-workers-US-12105", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12105.json" },
-    { "id": "deploy-cloudflare-workers-US-12106", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12106.json" },
-    { "id": "deploy-cloudflare-workers-US-12107", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12107.json" },
-    { "id": "deploy-cloudflare-workers-US-12108", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12108.json" },
-    { "id": "deploy-cloudflare-workers-US-12109", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12109.json" },
-    { "id": "deploy-cloudflare-workers-US-12110", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12110.json" },
-    { "id": "deploy-cloudflare-workers-US-12111", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12111.json" },
-    { "id": "deploy-cloudflare-workers-US-12112", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12112.json" },
-    { "id": "TAC-1301-deploy-cloudflare-workers-deploy-adapter", "kind": "tac", "path": "tacs/tac-1301-deploy-cloudflare-workers-deploy-adapter.json" },
-    { "id": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest", "kind": "tac", "path": "tacs/tac-1302-deploy-cloudflare-workers-wrangler-manifest.json" },
-    { "id": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver", "kind": "tac", "path": "tacs/tac-1303-deploy-cloudflare-workers-preview-url-resolver.json" },
-    { "id": "TAC-1304-deploy-cloudflare-workers-promote-gate", "kind": "tac", "path": "tacs/tac-1304-deploy-cloudflare-workers-promote-gate.json" },
-    { "id": "TAC-1305-deploy-cloudflare-workers-served-surface-verifier", "kind": "tac", "path": "tacs/tac-1305-deploy-cloudflare-workers-served-surface-verifier.json" },
-    { "id": "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows", "kind": "tac", "path": "tacs/tac-1306-deploy-cloudflare-workers-deploy-ci-workflows.json" },
+    {
+      "id": "deploy-cloudflare-workers-REQ-001",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-001.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-002",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-002.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-003",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-003.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-004",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-004.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-005",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-005.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-006",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-006.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-007",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-007.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-008",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-008.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-009",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-009.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-010",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-010.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-011",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-011.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-012",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-012.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12101",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12101.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12102",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12102.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12103",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12103.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12104",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12104.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12105",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12105.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12106",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12106.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12107",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12107.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12108",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12108.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12109",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12109.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12110",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12110.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12111",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12111.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12112",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12112.json"
+    },
+    {
+      "id": "TAC-1301-deploy-cloudflare-workers-deploy-adapter",
+      "kind": "tac",
+      "path": "tacs/tac-1301-deploy-cloudflare-workers-deploy-adapter.json"
+    },
+    {
+      "id": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+      "kind": "tac",
+      "path": "tacs/tac-1302-deploy-cloudflare-workers-wrangler-manifest.json"
+    },
+    {
+      "id": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+      "kind": "tac",
+      "path": "tacs/tac-1303-deploy-cloudflare-workers-preview-url-resolver.json"
+    },
+    {
+      "id": "TAC-1304-deploy-cloudflare-workers-promote-gate",
+      "kind": "tac",
+      "path": "tacs/tac-1304-deploy-cloudflare-workers-promote-gate.json"
+    },
+    {
+      "id": "TAC-1305-deploy-cloudflare-workers-served-surface-verifier",
+      "kind": "tac",
+      "path": "tacs/tac-1305-deploy-cloudflare-workers-served-surface-verifier.json"
+    },
+    {
+      "id": "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows",
+      "kind": "tac",
+      "path": "tacs/tac-1306-deploy-cloudflare-workers-deploy-ci-workflows.json"
+    },
     {
       "id": "ADR-1301-deploy-cloudflare-workers-deployment-target",
       "kind": "adr",
       "path": "adrs/adr-1301-deploy-cloudflare-workers-deployment-target.json",
       "scope": "global",
-      "topic": "deploymentTarget"
+      "topic": "deploymentTarget",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-1302-deploy-cloudflare-workers-default-vendor",
+      "kind": "adr",
+      "path": "adrs/adr-1302-deploy-cloudflare-workers-default-vendor.json",
+      "standardsTraceClause": "generic enterprise practice"
     },
-    { "id": "ADR-1302-deploy-cloudflare-workers-default-vendor", "kind": "adr", "path": "adrs/adr-1302-deploy-cloudflare-workers-default-vendor.json" },
-    { "id": "ADR-1303-deploy-cloudflare-workers-preview-vs-production", "kind": "adr", "path": "adrs/adr-1303-deploy-cloudflare-workers-preview-vs-production.json" },
-    { "id": "ADR-1304-deploy-cloudflare-workers-rollback-is-promote", "kind": "adr", "path": "adrs/adr-1304-deploy-cloudflare-workers-rollback-is-promote.json" },
-    { "id": "ADR-1305-deploy-cloudflare-workers-dev-mode-drift", "kind": "adr", "path": "adrs/adr-1305-deploy-cloudflare-workers-dev-mode-drift.json" }
+    {
+      "id": "ADR-1303-deploy-cloudflare-workers-preview-vs-production",
+      "kind": "adr",
+      "path": "adrs/adr-1303-deploy-cloudflare-workers-preview-vs-production.json",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-1304-deploy-cloudflare-workers-rollback-is-promote",
+      "kind": "adr",
+      "path": "adrs/adr-1304-deploy-cloudflare-workers-rollback-is-promote.json",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-1305-deploy-cloudflare-workers-dev-mode-drift",
+      "kind": "adr",
+      "path": "adrs/adr-1305-deploy-cloudflare-workers-dev-mode-drift.json",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-013",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-013.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-REQ-014",
+      "kind": "req",
+      "path": "requirements/deploy-cloudflare-workers-req-014.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12113",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12113.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12114",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12114.json"
+    },
+    {
+      "id": "deploy-cloudflare-workers-US-12115",
+      "kind": "us",
+      "path": "user-stories/deploy-cloudflare-workers-us-12115.json"
+    },
+    {
+      "id": "ADR-1306-deploy-cloudflare-workers-spa-shape",
+      "kind": "adr",
+      "path": "adrs/adr-1306-deploy-cloudflare-workers-spa-shape.json",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Cloudflare Pages landing-page recommendation (2026-09-06)"
+    }
+  ],
+  "elicits": [
+    {
+      "id": "assets-directory",
+      "prompt": "Assets directory: the path (relative to the Worker source root) whose files Cloudflare serves at the edge as static assets under the Workers-with-static-assets shape. An empty answer keeps the bare-Worker shape (no [assets] block on the generated wrangler.toml). A non-empty answer emits [assets] directory = the answered path.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "run-worker-first",
+      "prompt": "Run Worker first: whether the Worker fetch handler runs BEFORE static asset lookup for every request. True emits run_worker_first = true under the [assets] block (right for a SPA whose Worker owns arbitrary routing or whose auth middleware must gate every path). False (default) omits the field and lets Cloudflare's runtime serve a matching static asset before the Worker runs. Only meaningful when assets-directory is non-empty; the loader-side when-elicitedNonEmpty predicate is a mechanism follow-up.",
+      "kind": "boolean",
+      "default": false
+    }
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every promote and every served-surface verify writes a structured deploy log record and a probe verdict; a logging companion supplies the record factory the deploy adapter and the verifier both call."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A promote refusal (bad version id, verifier fail, mixed-shape wrangler manifest) constructs an internal error record; an error-handling companion supplies the record factory and the boundary at which the deploy adapter's refusals surface to the operator."
+    }
   ]
 }

package/blueprints/deploy-cloudflare-workers/contributions/adrs/adr-1306-deploy-cloudflare-workers-spa-shape.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1306-deploy-cloudflare-workers-spa-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.2.0",
+  "status": "accepted",
+  "title": "Workers-with-static-assets is the ratified SPA-on-Workers deploy shape; Pages is a documented alternative held for legacy projects only",
+  "context": "Cloudflare ships two shapes for browsing static assets in front of a Workers-tier deploy target: Cloudflare Pages (a workflow-shaped product with its own build pipeline and its own preview URL model) and Workers-with-static-assets (a wrangler.toml [assets] block declaring a directory the Cloudflare runtime serves at the edge). Cloudflare's own Pages landing page states, verbatim (fetched 2026-09-06): 'Workers supports most Pages use cases and offers a broader feature set. It is Cloudflare's primary platform for building applications. Start new projects with Workers.' The prior v1.1.0 blueprint blessed neither shape as the default; v1.1.0 taught the wrangler [assets] block in an asset sample but left the shape choice implicit. The T-0 round bumps the blueprint to v1.2.0 to close the gap: a rcf-lite project choosing SPA-on-Workers gets a single, ratified wrangler shape rather than a hand-rolled convention, and the ratified shape follows Cloudflare's own recommendation for new projects.",
+  "decision": "The blueprint blesses Workers-with-static-assets as the ratified SPA-on-Workers deploy shape (recommendedDefault true for new SPA projects). A project answering the elicited assets-directory parameter with a non-empty path emits an [assets] block on wrangler.toml whose directory value carries the elicited path; a project answering with an empty path keeps the bare-Worker shape (no [assets] block). The elicited run-worker-first (boolean, default false) surfaces the SPA fallback discipline: truthy answers emit run_worker_first = true under the [assets] block; falsy or unanswered answers omit the field, letting Cloudflare's runtime run asset lookup before the Worker fetch handler. The blueprint does not mint a Cloudflare Pages blueprint; a future deploy-cloudflare-pages-legacy sibling mints on demand only if a project cannot make the jump. Every existing v1.1.0 contribution carries through unchanged.",
+  "consequences": "One ratified shape lands on the shelf for greenfield SPA-on-Workers projects; the shape's standards trace is the Cloudflare Pages landing-page recommendation (2026-09-06 snapshot). The two new elicits become part of the operator surface at blueprint add: assets-directory names the static-assets root, run-worker-first names the SPA fallback discipline. A project generating both an [assets] block and a Pages-only pages_build_output_dir field is a mixed-shape drift the T-0 probe (assets-manifest-scan.mjs) refuses. A project on the legacy Pages shape stays on v1.1.0 semantics until it migrates; the guide's new Workers-with-static-assets section links Cloudflare's migrate-from-Pages walkthrough for projects that choose to jump. Future round-6 blueprints (T-1 KV, T-2 cron, T-3 DO, T-4 Access, T-5 Turnstile, T-6 rate-limiting) all compose on this shape via the shared cf-platform sample-app fixture.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a Cloudflare Pages blueprint alongside deploy-cloudflare-workers",
+      "summary": "Mint a fresh deploy-cloudflare-pages blueprint that owns the Pages workflow surface (build pipeline, preview URLs, deploy hooks) and lets the operator pick shapes at apply.",
+      "reasonNotChosen": "Cloudflare's Pages landing page tells new projects to start with Workers. A Pages blueprint would ship a shape Cloudflare tells greenfield projects not to start. The maintenance load of a second deploy blueprint (its own ADRs, its own vendor URL trace, its own promote workflow) buys a shape Cloudflare itself recommends against; the round-6 spec (ruling 1) rejects the sibling and folds Workers-with-static-assets into this blueprint's minor bump instead."
+    },
+    {
+      "name": "Leave the shape choice implicit as the v1.1.0 blueprint does",
+      "summary": "Keep the wrangler-shape asset sample as an example only; do not mint an ADR blessing Workers-with-static-assets and do not elicit the assets-directory or run-worker-first parameters.",
+      "reasonNotChosen": "The v1.1.0 sample teaches the shape but does not commit to it; a project applying the blueprint has to reach for the sample and decide alone. Naming the ratified default as an ADR with a standards trace makes the shape decision legible in the applied project, and eliciting the two knobs surfaces the ratified shape's parameters where the operator can see them at apply."
+    },
+    {
+      "name": "Bless Workers-with-static-assets only through the guide, without an ADR contribution",
+      "summary": "Add the guide section but do not mint an ADR; keep the shape as prose guidance rather than an architected decision.",
+      "reasonNotChosen": "The standards-derived-discipline discipline (blueprint-authoring.md section 8a) requires an ADR with standardsTraceClause for any decision that traces to a vendor standard. Blessing the shape only in the guide leaves no traceable decision record and no place for a superseding project-level ADR to hang off. The blueprint's own trace mechanism is exactly this shape."
+    }
+  ],
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/probes/assets-manifest-scan.mjs

@@ -0,0 +1,207 @@
+// Source-tree scan probe for the deploy-cloudflare-workers v1.2.0
+// Workers-with-static-assets shape (T-0 of the Cloudflare round 6
+// spec, section 5.0). accountBound false: this probe reads the
+// applied fixture wrangler.toml and asserts three properties:
+//
+//   1. When the elicited assets-directory answer is non-empty, the
+//      [assets] table's directory field equals the elicited answer
+//      (assetsBlockEmitted, canonical AC-12113-1).
+//   2. When the elicited run-worker-first answer is truthy, the
+//      [assets] table carries run_worker_first equal to true; when
+//      falsy or unanswered, run_worker_first is absent
+//      (spaFallbackShape facet of AC-12113-1).
+//   3. The manifest never carries a Pages-only pages_build_output_dir
+//      field alongside [assets]; the two shapes are mutually
+//      exclusive per Cloudflare's static-assets doc.
+//
+// Verdict envelope per spec section 3.2: { verdict, detail,
+// anchorAcId, aggregateVerdict } where anchorAcId is
+// AC-12113-1 (the assetsBlockEmitted anchor). aggregateVerdict is
+// pass when every result is pass, warn when any is warn (unused
+// here), fail when any is fail. Cleans up any temporary files it
+// wrote on exit.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+
+export const anchorAcId = 'AC-12113-1';
+export const accountBound = false;
+
+// Minimal wrangler.toml reader. Handles the small subset of TOML the
+// blueprint's manifest declares (top-level scalars, one [assets]
+// table, and boolean/string literals). Reaches for no runtime dep;
+// keeps the probe accountBound-false and dependency-free.
+export function parseWranglerToml(text) {
+  const lines = text.split(/\r?\n/);
+  const root = {};
+  let currentTable = root;
+  let currentTableName = '';
+  for (const raw of lines) {
+    const line = raw.replace(/^\s+/, '').replace(/\s+$/, '');
+    if (line === '' || line.startsWith('#')) continue;
+    const tableMatch = line.match(/^\[([A-Za-z0-9_.\-]+)\]$/);
+    if (tableMatch) {
+      currentTableName = tableMatch[1];
+      root[currentTableName] = root[currentTableName] || {};
+      currentTable = root[currentTableName];
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z0-9_\-]+)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    let value = kv[2].trim();
+    // Strip trailing comments (a naive #-then-space split; sufficient
+    // for the wrangler shapes this blueprint generates).
+    const hashAt = value.indexOf(' #');
+    if (hashAt !== -1) value = value.slice(0, hashAt).trim();
+    if (value === 'true') {
+      currentTable[key] = true;
+    } else if (value === 'false') {
+      currentTable[key] = false;
+    } else if (/^-?\d+$/.test(value)) {
+      currentTable[key] = Number(value);
+    } else if (value.startsWith('"') && value.endsWith('"')) {
+      currentTable[key] = value.slice(1, -1);
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      currentTable[key] = value.slice(1, -1);
+    } else {
+      currentTable[key] = value;
+    }
+  }
+  return root;
+}
+
+// Drive the scan against the fixture. `opts.fixtureRoot` names the
+// directory the wrangler.toml lives in; `opts.elicited` names the
+// answers the fixture baked in (assets-directory string, run-worker-
+// first boolean). Optionally `opts.simulate` is one of
+// 'mixed-shape' or 'empty-assets': the caller rewrites wrangler.toml
+// in a scratch copy for the simulate branches so the base fixture
+// stays honest.
+export async function scan(opts) {
+  const fixtureRoot = opts.fixtureRoot;
+  const elicited = opts.elicited || {};
+  const manifestPath = opts.manifestPath || join(fixtureRoot, 'wrangler.toml');
+  const text = await readFile(manifestPath, 'utf8');
+  const parsed = parseWranglerToml(text);
+  const results = [];
+  const detail = {
+    manifestPath,
+    parsed,
+    elicited: {
+      assetsDirectory: elicited['assets-directory'] || '',
+      runWorkerFirst: elicited['run-worker-first'] === true,
+    },
+  };
+
+  const assets = parsed.assets || null;
+  const answered = detail.elicited.assetsDirectory !== '';
+  if (answered) {
+    if (!assets) {
+      results.push({
+        verdict: 'fail',
+        detail: 'assets table absent: elicited assets-directory is "' + detail.elicited.assetsDirectory + '" but wrangler.toml carries no [assets] block',
+        anchorAcId,
+      });
+    } else if (assets.directory !== detail.elicited.assetsDirectory) {
+      results.push({
+        verdict: 'fail',
+        detail: 'assets.directory mismatch: wrangler.toml carries directory=' + JSON.stringify(assets.directory) + ' but elicited answer is ' + JSON.stringify(detail.elicited.assetsDirectory),
+        anchorAcId,
+      });
+    } else {
+      results.push({
+        verdict: 'pass',
+        detail: 'assets.directory equals elicited assets-directory answer ' + JSON.stringify(assets.directory),
+        anchorAcId,
+      });
+    }
+    const runWorkerFirstOnManifest = assets && Object.prototype.hasOwnProperty.call(assets, 'run_worker_first');
+    if (detail.elicited.runWorkerFirst) {
+      if (!runWorkerFirstOnManifest || assets.run_worker_first !== true) {
+        results.push({
+          verdict: 'fail',
+          detail: 'run_worker_first mismatch: elicited answer is true but manifest carries ' + (runWorkerFirstOnManifest ? String(assets.run_worker_first) : 'no run_worker_first key'),
+          anchorAcId,
+        });
+      } else {
+        results.push({
+          verdict: 'pass',
+          detail: 'assets.run_worker_first equals true, matching the elicited run-worker-first answer',
+          anchorAcId,
+        });
+      }
+    } else {
+      if (runWorkerFirstOnManifest && assets.run_worker_first !== false) {
+        results.push({
+          verdict: 'fail',
+          detail: 'run_worker_first mismatch: elicited answer is falsy but manifest carries run_worker_first=' + JSON.stringify(assets.run_worker_first),
+          anchorAcId,
+        });
+      } else {
+        results.push({
+          verdict: 'pass',
+          detail: 'assets.run_worker_first is absent (or false), matching the falsy elicited run-worker-first answer',
+          anchorAcId,
+        });
+      }
+    }
+  } else {
+    if (assets) {
+      results.push({
+        verdict: 'fail',
+        detail: 'assets table present without an elicited assets-directory answer: bare-Worker shape expected, wrangler.toml carries [assets] block',
+        anchorAcId,
+      });
+    } else {
+      results.push({
+        verdict: 'pass',
+        detail: 'no [assets] block on wrangler.toml, matching the bare-Worker shape (assets-directory elicit unanswered)',
+        anchorAcId,
+      });
+    }
+  }
+
+  const pagesFieldAtRoot = Object.prototype.hasOwnProperty.call(parsed, 'pages_build_output_dir');
+  const pagesFieldUnderAssets = assets && Object.prototype.hasOwnProperty.call(assets, 'pages_build_output_dir');
+  if (pagesFieldAtRoot || pagesFieldUnderAssets) {
+    results.push({
+      verdict: 'fail',
+      detail: 'mixed-shape drift: wrangler.toml carries pages_build_output_dir (' + (pagesFieldAtRoot ? 'top-level' : 'inside [assets]') + ') alongside the Workers-with-static-assets shape; the two are mutually exclusive per Cloudflare static-assets doc',
+      anchorAcId,
+    });
+  } else {
+    results.push({
+      verdict: 'pass',
+      detail: 'no pages_build_output_dir field on wrangler.toml (Workers-with-static-assets shape is exclusive of the Pages shape)',
+      anchorAcId,
+    });
+  }
+
+  const aggregateVerdict = results.some((r) => r.verdict === 'fail')
+    ? 'fail'
+    : results.some((r) => r.verdict === 'warn')
+      ? 'warn'
+      : 'pass';
+
+  return { verdict: aggregateVerdict, aggregateVerdict, anchorAcId, results, detail };
+}
+
+// Convenience for the run-shim: write a report file next to a
+// project-relative .rcf/reports/ path. Creates the directory if it
+// does not exist; the shim removes any scratch file it wrote to
+// simulate the mixed-shape or empty-assets branch before exit.
+export async function writeReport(reportPath, report) {
+  await mkdir(dirname(reportPath), { recursive: true });
+  await writeFile(reportPath, JSON.stringify(report, null, 2) + '\n', 'utf8');
+}
+
+export async function removeIfExists(path) {
+  try {
+    await rm(path, { force: true });
+  } catch (_err) {
+    // Nothing to clean.
+  }
+}
+
+export default { scan, writeReport, removeIfExists, parseWranglerToml, anchorAcId, accountBound };

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-013.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-013",
+  "prdId": "PRD-001",
+  "title": "Workers-with-static-assets shape: an [assets] directory declared under wrangler blesses static assets served by the Worker",
+  "description": "The blueprint blesses the Workers-with-static-assets deploy shape as the ratified SPA-on-Workers shape (per ADR-1306, quoting the Cloudflare Pages landing-page recommendation verbatim). A project answering the elicited `assets-directory` parameter with a non-empty path emits an `[assets]` block on `wrangler.toml` whose `directory` value carries the elicited path (for example `directory = \"./dist\"`). Cloudflare's Workers runtime serves files from that directory at the edge before the Worker fetch handler runs (unless `run_worker_first` is set truthy per REQ-014). A project answering with an empty path keeps the bare-Worker shape (no `[assets]` block, no static-asset lookup). The wrangler manifest MUST NOT carry any Pages-only field (`pages_build_output_dir`) alongside `[assets]`; the two shapes are mutually exclusive per Cloudflare's static-assets doc.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Cloudflare's own Pages landing page tells new projects to start with Workers; the Workers-with-static-assets shape is the primary SPA-on-Workers deploy shape. Blessing it here means a rcf-lite project choosing SPA-on-Workers gets a single, ratified wrangler shape rather than a hand-rolled convention. The mutual exclusion of `[assets]` and `pages_build_output_dir` keeps a project from silently drifting into a mixed-shape wrangler that Cloudflare's runtime refuses at deploy time.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:13-static-assets"
+  ],
+  "version": "1.2.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-014.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-014",
+  "prdId": "PRD-001",
+  "title": "SPA fallback discipline: run_worker_first flips the assets pipeline off the fetch handler's critical path",
+  "description": "The blueprint elicits `run-worker-first` (boolean, default false) alongside the `[assets] directory` shape from REQ-013. When the operator answers truthy, the generated wrangler manifest emits `run_worker_first = true` under the `[assets]` block: Cloudflare's runtime runs the Worker's fetch handler BEFORE looking up a static asset for the requested path. That is the shape a SPA-on-Workers project uses when the Worker owns arbitrary routing or when the Worker's auth middleware must gate every path a static file could shadow. When the operator answers falsy or leaves the elicit unanswered, `run_worker_first` is absent from the manifest and Cloudflare's runtime looks up a static asset first, falling back to the Worker only when no asset matches. The Worker code and the guide teach both shapes; the elicit surface is one boolean, the wrangler shape is one line.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "should",
+  "rationale": "The default (asset lookup first, Worker on miss) is right for a static-content-heavy project. The truthy branch is what keeps auth middleware from being silently bypassed by an unauthenticated request for a file the assets pipeline serves from the edge cache. Naming the discipline as its own REQ makes the shape trade legible; anchoring the elicit to a wrangler line keeps the choice observable in the applied project.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:13-static-assets"
+  ],
+  "version": "1.2.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

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

@@ -0,0 +1,36 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12113",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-013",
+  "version": "1.2.0",
+  "status": "approved",
+  "title": "SPA-on-Workers deploy shape: [assets] block emitted with the elicited directory and the run_worker_first hint",
+  "asA": "operator deploying a SPA on Cloudflare Workers",
+  "iWant": "the generated wrangler.toml to carry an [assets] block whose directory matches my elicited answer and whose run_worker_first field carries my elicited SPA fallback choice",
+  "soThat": "my SPA-on-Workers project ships with a single, ratified wrangler shape and my static assets and my auth-gated routes both behave the way Cloudflare's runtime documents them",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12113-1",
+      "description": "Given the operator answers assets-directory with a non-empty path P at blueprint add, when the wrangler manifest generator emits wrangler.toml, then the manifest contains exactly one [assets] block whose directory field equals P (with the leading `./` preserved when the operator answered `./P`) and the manifest carries no pages_build_output_dir field. When the operator answers assets-directory with an empty string or leaves the elicit unanswered, the manifest carries no [assets] block and no pages_build_output_dir field. Anchored to TAC-1302-deploy-cloudflare-workers-wrangler-manifest; probed by assets-manifest-scan.mjs (source-tree scan against the applied fixture wrangler.toml) with anchorAcId AC-12113-1.",
+      "given": "an applied fixture whose operator answered assets-directory = ./dist at blueprint add",
+      "when": "the probe module assets-manifest-scan.mjs parses the fixture wrangler.toml",
+      "then": "the parsed structure contains an assets table whose directory string equals ./dist and no top-level pages_build_output_dir key; the probe returns verdict pass",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12113-2",
+      "description": "Given the operator answers run-worker-first with true alongside a non-empty assets-directory, when the manifest is generated, then the [assets] block carries run_worker_first = true. Given the operator answers run-worker-first with false or leaves it unanswered, when the manifest is generated, then the [assets] block does NOT carry a run_worker_first key (Cloudflare's runtime treats the absent field as the default asset-lookup-first shape). Anchored to TAC-1302; probed by assets-manifest-scan.mjs with anchorAcId AC-12113-1 (the same module surfaces both facets of the shape).",
+      "given": "an applied fixture whose operator answered assets-directory = ./dist and run-worker-first = true",
+      "when": "the probe module parses the fixture wrangler.toml",
+      "then": "the parsed [assets] table carries run_worker_first equal to true; when the fixture is switched with SIMULATE_EMPTY_ASSETS=true the run_worker_first field is absent (the whole [assets] block is absent) and the probe still returns verdict pass because the bare-Worker shape is legal",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

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

@@ -0,0 +1,27 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12114",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-013",
+  "version": "1.2.0",
+  "status": "approved",
+  "title": "assets-directory elicitation: the operator picks the static-assets root at blueprint add",
+  "asA": "operator applying deploy-cloudflare-workers on a fresh project",
+  "iWant": "the blueprint to prompt me for the static-assets directory at blueprint add and remember my answer on my project's sidecar so re-apply picks it back up",
+  "soThat": "my wrangler.toml reflects my project's build output shape without me having to hand-edit the [assets] block",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12114-1",
+      "description": "The blueprint.json elicits[] block declares an entry with id assets-directory, kind string, default empty. The blueprint loader accepts the entry (validateElicits shape gate on src/blueprint/loader.js). The CLI accepts --answer assets-directory=<path> at blueprint add; the applied sidecar records the answered value on appliedElicitations.assets-directory. When the operator does not pass --answer assets-directory, the effective value is the empty-string default and the wrangler generator emits no [assets] block.",
+      "given": "a fresh rcf init scratch project after rcf define blueprint add ./blueprints/deploy-cloudflare-workers --answer assets-directory=./public --answer run-worker-first=false",
+      "when": "the applied sidecar records the operator's answers and a wrangler.toml is generated",
+      "then": "appliedElicitations.assets-directory equals ./public; the generated wrangler.toml carries [assets] directory = \"./public\" and no run_worker_first field; the manifest carries no pages_build_output_dir field",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}