[ClaudiaFang]

Summary

Refactor Cloudflare Workers v2 CI/CD in place to reduce orchestration duplication while retaining one shared delivery engine, one normal-pipeline D1 Migration job, per-target Smoke/Recovery, deferred verification, and the existing public workflow inputs/outputs.

Current reviewed HEAD: 8ad4d40 (includes the P1 stale-migration fix). Latest PR CI: run 41595263650 — passed. This PR has not been merged; main, the floating @v2 tag, and consumer repositories have not been changed by this PR.

Current DAG

Consumer workflow
  └─ _cf-worker-v2.yml (public)
       ├─ CI → _cf-worker-ci.yml
       │    ├─ Lint ─────────────┐
       │    ├─ Typecheck ────────┤
       │    ├─ Unit ─────────────┤
       │    ├─ Integration ──────┤ parallel
       │    ├─ Build Validation ─┤
       │    └─ E2E (matrix) ─────┘
       │                 ↓
       │           Validation Gate
       ├─ Delivery Plan (enabled targets + one physical D1)
       ├─ Database Migration (ONE job; validate all targets before mutation)
       ├─ Delivery × enabled kind → _cf-worker-delivery.yml
       │    ├─ Production ───────┐
       │    ├─ Native Branch ────┤ Deploy → Smoke → conditional Rollback
       │    ├─ Native Dev ───────┤ (one shared implementation, isolated results)
       │    └─ Persistent Dev ───┘
       └─ Release (main + verified Production only)

Other event paths (not part of the delivery DAG):
  same-repo PR / branch delete → _cf-worker-lifecycle.yml
  approved manual Persistent Dev → _cf-worker-persistent-dev.yml
  pipeline_phase=verify → Plan (restored handoff) → Smoke → optional Rollback

The four Delivery job definitions are conditional; disabled targets do not execute. The normal pipeline has no separate Preflight job/matrix. stage: preflight remains as read-only validation inside the single Migration job.

Key changes

• Reusable CI: Move six independent checks and their fail-closed Validation Gate into _cf-worker-ci.yml. Same-repo PR does not rerun CI already covered by branch push; fork PRs run credential-free validation.
• One physical-D1 migration per invocation: The Plan deduplicates shared D1 bindings and rejects two distinct physical D1s before mutation. The Migration job audits enabled target builds and effective Wrangler/D1 bindings first; d1_migrations: false skips Migration without blocking Delivery.
• One delivery implementation: Four thin target calls reuse _cf-worker-delivery.yml and actions/cf-deploy for Build/Audit/Publish → Smoke → guarded Rollback. Deployment outputs, environment approvals, concurrency and rollback decisions remain target-specific.
• Event handlers extracted: Preview PR comment/branch deletion and the protected manual Persistent Dev route now live in dedicated small internal workflows. Manual Persistent Dev retains its existing engine and legacy-command options.
• Self-repository references: Nested workflows/actions use $/..., binding tooling to the called workflow's exact repository commit and removing the redundant .cf-tools checkouts. tools_ref remains accepted but is deprecated, optional and ignored.
• Public interface: All 60 input names and 20 output names remain available. The opaque phase_state handoff omits a redundant internal d1 map; pass it through unchanged. Check-context names do change due to CI extraction.

Security / P1 resolution (fixed at HEAD 8ad4d40)

The previous resolveMigrationUsed() accepted a Migration result with stale=true without proving that any D1 migration ran. In a potential branch A → B → A force-push race, a later fresh-SHA check would not prove migration completion.

Fixed: the publish-stage Migration Gate now rejects stale (true or "true"), absent/malformed result, failed/skipped Migration, missing or incorrect owner, non-applied result, or mismatched physical D1. The Gate runs before publish-stage build or mutation. d1_migrations=false and deferred pipeline_phase=verify remain supported. Regression coverage includes A → B → A, no unauthorized Publish/Smoke/Rollback/Release.

Additional protections retained: Production/non-production D1 isolation; effective Wrangler config validation; protected Production Environment; stale-SHA guards; Smoke full|basic|skip; target-specific recovery; Release only after verified Production; no automatic schema rollback.

Scope and metrics

Metric	Before this extraction	Current
Public _cf-worker-v2.yml	1,081 lines	769 lines
_cf-worker-delivery.yml	320 lines	282 lines
Total five pipeline workflows	1,401 lines	1,516 lines (+8%)
Separate Preflight jobs	0	0
Normal-pipeline Migration jobs	1	1
Shared tooling repository checkouts (representative feature push)	up to 11	0
Delivery implementations	1	1

The benefit is separation of responsibilities and less duplicated setup, not lower total YAML line count. Available real-runner comparison (n=1 per scenario) shows no established runtime improvement.

Verification evidence

• Latest reviewed HEAD 8ad4d40: PR CI run 41595263650 — passed. Fast profile, Chain profile (mocked Cloudflare/GitHub), ShellCheck and Actionlint all passed; includes the stale-migration regression tests.
• Earlier implementation SHA 3bda5fb (before P1 fix): PR CI run 41589279882 — passed; cross-repository disposable scratch-caller evidence confirms $/ resolution, parallel CI and Validation Gate, D1 gating and skip cases, distinct-D1 rejection, deferred verification, manual Persistent Dev and lifecycle. Examples: parallel CI, CI failure blocks delivery, migration disabled, two D1s rejected, legacy manual Dev, PR lifecycle. Several scratch runs intentionally conclude failure because Cloudflare credentials were withheld; their intended gates and observed steps are recorded in the docs.
• Post-P1-fix cross-repo scratch run pinned to 8ad4d40: done, see Final merge-readiness verification below.
• Still not demonstrated: live non-production D1 migration / publish / smoke / recovery (BLOCKED, no approved credentials); protected Environment approval; consumer Required Check migrations (unreadable, administrator action); GHES or runners older than 2.336.0.

Final merge-readiness verification (implementation 8ad4d40, 2026-11-03)

Implementation is unchanged since 8ad4d40; a docs-only commit recording the details below (fd6ab85, touching docs/cf-worker-v2-refactor.md, docs/cf-worker-v2-unified-delivery.md and the OpenSpec tasks.md only) is the PR branch tip; the implementation SHA stays 8ad4d40. Nothing was merged; @v2, consumers, branch protection and Cloudflare were not changed.

1. Regression at 8ad4d40. PR CI 41595263650 passed. Local re-run on the exact SHA: test.sh fast and test.sh full PASSED (561 contract + 420 chain checks), ShellCheck 0.11.0 (+ composite-action scripts) clean, actionlint 1.7.12 clean. All nine required assertions have named passing tests (stale true/"true" blocked; missing/malformed fail closed; valid applied Migration with matching owner + physical D1 succeeds; d1_migrations=false does not block; A → B → A rejected before the build; failed Migration never starts publishing; verify never migrates; Smoke/Rollback target-isolated; Release only after verified Production).

2. Real-runner stale gate. cf-v2-scratch-caller run 41598319442 runs the real cli.mjs migration-gate entrypoint from 8ad4d40 on the org linux runner and ubuntu-latest with a validated descriptor and synthetic handoffs: stale (true and "true"), empty, malformed, none, owner mismatch, D1 mismatch and failed-Migration inputs all exit 1; valid and d1_migrations=false controls exit 0; PATH shims show no wrangler/gh/curl/pnpm/npx call (no publish-side action). (The first dispatch, 41598162595, failed on a bug in my test script — bash -e — not in the implementation.) The full A → B → A race is not reproducible on Actions without a live account; its evidence stays the chain regression.

3. Scratch caller pinned to 8ad4d40 (all referenced_workflows and nested $/ actions resolved to the same SHA; org runners 2.338.0; no Cloudflare credentials, so failure conclusions below are the designed fail-closed result and each was checked against its step message):

Scenario	Run	Result
Parallel CI	41598183911	7 check jobs success → Gate/Plan success → Migration skipped → Deploy preview credentials not provided (expected)
Validation failure	41598188577	Lint fails, others still run, Gate fails; Plan/Migration/Deliveries/Release skipped
Single D1 Migration	41598193186, 41598197646	exactly one Database Migration; failed closed on credentials; Deliveries skipped
Migration disabled	41598201733	Migration skipped; both Deliveries started
Distinct D1s	41598206295	Plan fails naming both D1s, nothing was changed
Deferred verification	41598211512, 41598215678	Migration skipped in both calls; Smoke from the original handoff
Same-repo PR / Branch Delete	41598279417 / 41598501202	lifecycle only (no duplicate CI); ledger retired, Preview kept
Manual Persistent Dev	41598224024, 41598228322	legacy contract success; engine contract failed closed on credentials

4. Consumer compatibility (default branches read 2026-11-03; no other consumer of _cf-worker-v2.yml exists; the real planner was run on every call × push/dispatch/PR/delete):

Repository / App	Runner	Required Checks	D1	Deployment	Action
blog	yes	UNVERIFIED — ADMIN ACCESS REQUIRED	yes (prod 45031ada…; branch feb45b04…)	yes	fix secrets:; update checks
heaven-monorepo / heaven-id	yes	UNVERIFIED	yes (prod 193440aa…; dev ca755ecb…)	yes	update checks
heaven-monorepo / heaven-checkin	yes	UNVERIFIED	yes (prod 41fa4337…; dev 8e3f8323…)	yes	update checks
heaven-monorepo / test-client	yes	UNVERIFIED	yes (no D1)	yes	update checks
innovation-apps / diet-manager	yes	UNVERIFIED	yes (prod e12e2d9e…; preview b9421085…)	yes	update checks
innovation-apps / notification-hub	yes	UNVERIFIED	yes (prod 311ab3c8…; dev 9a69f8e9…)	yes	update checks
anas-mcp	yes	yes — verified: public, no protection, no rulesets	yes (no D1)	yes	none
heaven-www	yes	UNVERIFIED	yes (no D1)	yes	fix secrets:; update checks

• Runner: all online org runners report 2.338.0 (nine of ten listed on 2026-11-03; heavenweb-runner-10 absent) (≥ 2.336.0, confirmed by API; scratch jobs ran on heavenweb-runner-3). Node/pnpm/Playwright setup is unchanged from main. Hosted ubuntu-latest also accepted $/ but lacks pnpm.
• Required Checks: branch protection/rulesets of the four private repos return 403 Upgrade to GitHub Pro although the token has admin rights (org plan free) — plan limit, not proof that none exist. An administrator must confirm none of these is required, or move it: <job> / Lint|Typecheck|Unit Tests|Integration Tests|Build Validation|E2E[ (variant)] → <job> / CI / …; add <job> / CI / Validation Gate; <job> / Migration → <job> / Database Migration; <job> / Deploy|Smoke Tests|Revert on Verify Failure|Shared Dev* → <job> / Delivery (<kind>) / …. <job> is Pipeline (blog, innovation-apps, heaven-www), Heaven ID / Heaven Checkin / Heaven ID Test Client, or cf (anas-mcp).
• D1: no call plans two distinct physical D1s in any modeled event. Not modeled: the post-build effective-config audit (live only).
• Environments: no consumer Environment has required reviewers, wait timers or branch policies, so the Production approval described above is not enforced by any consumer today; approval behaviour was not exercised.
• Deferred verification: no consumer uses pipeline_phase/phase_state/upstream_gate.

5. Live non-production evidence — BLOCKED. The only Cloudflare credentials reachable are the Production org secrets; the scratch repository has none and no disposable, approved account/D1/protected Environment exists. Prerequisites: a scratch Cloudflare account or disposable-scope token, a throw-away D1 with migrations, scratch repo secrets, and a protected Environment with a reviewer (paid plan or public repository). No live evidence is claimed.

Rollout blocker found (not caused by this PR; must be fixed before @v2 moves): blog cicd.yml, blog preview-gc.yml and heaven-www cicd.yml pass CLOUDFLARE_PREVIEW_API_TOKEN / CLOUDFLARE_PREVIEW_ACCOUNT_ID, which neither the current @v2 (def3679) nor 8ad4d40 declares (commit 5def01d on main). GitHub rejects such a caller before any job starts — reproduced as startup_failure in 41599151750 (8ad4d40) and 41600536212 (fd6ab85); the run page reads Invalid secret, CLOUDFLARE_PREVIEW_API_TOKEN is not defined in the referenced workflow. (same for CLOUDFLARE_PREVIEW_ACCOUNT_ID); heaven-www CI/CD (41017574023) and blog Preview GC nightly runs show matching startup_failures (cause inferred, not read from a log). Remedy: drop those two lines from the three callers, or declare them as optional secrets. Fix PRs (open, not merged): blog#461, heaven-www#56; replicas of the fixed callers start against both the v2 tag and this PR (fail closed only on missing scratch credentials). Preconditions, procedure and rollback for the tag move: docs/cf-worker-v2-rollout.md.

Verdict: no merge blocker found in the implementation. Remaining items are @v2-rollout requirements: the secrets fix, administrator Required-Check confirmation/update, and live non-production evidence.

Detailed evidence: architecture/refactor guide · unified delivery + P1 fix · OpenSpec.

Compatibility and rollout requirements

1. Check-context rename: Required Checks may change from <caller-job> / Lint to <caller-job> / CI / Lint (likewise for other checks). Audit every consumer's branch protection/rulesets before moving @v2; missing admin/ruleset visibility is unverified, not proof that no rule exists.
2. Runner floor: $/ requires GitHub Actions runner >= 2.336.0. The tested org linux runner is newer; check all consumers' runner choices. $/ is not verified for GHES.
3. D1 compatibility: One invocation may migrate at most one distinct physical D1. Existing expected consumer configurations appear compatible, but all supported branch/dispatch variants and live bindings must be confirmed before tag promotion. Repository-scoped concurrency does not lock a D1 shared across repositories.
4. No live claim: Contract and stub tests are not evidence of a successful remote Cloudflare migration, publish, Smoke or Rollback. Use approved disposable non-production resources for a staged end-to-end exercise, then roll out pinned to an immutable SHA.

Review / rollout checklist

• Single Migration + reusable Delivery architecture implemented; no Preflight jobs or Migration matrix
• P1 stale-migration authorization fixed with unit, contract and A → B → A chain regressions
• Fast, Chain, ShellCheck and Actionlint passed on reviewed HEAD 8ad4d40
• Earlier cross-repository scratch caller exercised reusable-workflow structure without Cloudflare credentials
• Repeat the critical scratch-caller checks using final 8ad4d40 (including stale Migration fail-closed on a real runner)
• Audit consumer Required Check names, runner versions and distinct-D1 configurations (Required Checks on 4 private repos remain UNVERIFIED — administrator must confirm)
• Final human review and approval for merge
• Merge to main and record the immutable merged SHA only after approval
• Validate live non-production deployment/smoke/recovery with authorized resources before moving @v2 (BLOCKED: none available)
• Merge the consumer fixes (blog#461, heaven-www#56) that remove undeclared CLOUDFLARE_PREVIEW_* secrets before moving @v2 (PRs open; merging runs the real Production pipelines)
• Promote @v2 / migrate consumers in a separately approved rollout

Do not merge, move @v2, or change consumers as part of this PR-description update.