fix(ci): restore marketing Pages deployments

[simple-agent-manager]

Summary

• Restore Cloudflare Pages publishing by making apps/www directly own the catalog-pinned Wrangler 4.118.0 executable and invoking it through that workspace in both marketing workflows.
• Make Pages provisioning fail closed: list projects, validate the JSON response, skip only an exact project-name match, and preserve real list/create/auth/network failures.
• Add a deterministic workflow contract that rejects npx wrangler, missing dependency ownership, or weakened provisioning behavior.

Validation

• pnpm lint — 13/13 tasks passed; 8 pre-existing warnings and zero errors
• pnpm typecheck — 19/19 tasks passed
• pnpm test — 21/21 tasks passed
• pnpm build — 9/9 tasks passed
• Additional validation: offline frozen install; Wrangler 4.118.0 resolution; focused workflow contract 9/9; quality suite 32 files/297 tests; pnpm check:fast; git diff --check
• Candidate-selection I/O-budget check — N/A: no sweep, cron, alarm, query, or candidate-selection logic changes

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — N/A for the SAM application runtime: this PR changes marketing CI configuration, not application runtime code. The relevant branch-specific Cloudflare Pages deployment passed in run 31488280296.
• Live app verified via Playwright — N/A: no application or UI runtime behavior changed.
• Existing workflows confirmed working — N/A: no dashboard, project, settings, navigation, or client-state behavior changed; repository-wide lint, typecheck, test, and build gates passed.
• New feature/fix verified on staging — the exact formerly failing workflow command resolved the pinned Wrangler 4.118.0, uploaded the marketing build, and returned HTTP 200 from both the immutable and branch-preview Pages URLs.
• Infrastructure verification completed — no VM/cloud-init/DNS/TLS/scripts/deploy path changed, so VM provisioning is N/A. The Pages deployment boundary passed live; the fail-closed Pages list/create branches were exercised locally for existing, missing/create, malformed JSON, list failure, and create failure.
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes.

Staging Verification Evidence

The Deploy Marketing Site workflow ran against branch commit 47774d3deb5a4f12789211c263ccdca812a29d53. Wrangler 4.118.0 uploaded successfully, and https://fbc054e7.sam-www.pages.dev/ plus https://sam-looks-merged-couple-prs.sam-www.pages.dev/ both returned HTTP 200. The current head differs only by task evidence and the merge of unrelated main experiment files; the workflow, package, lockfile, and regression-test changes are identical.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified — N/A: no UI changes
• Accessibility checks completed — N/A: no UI changes
• Shared UI components used or exception documented — N/A: no UI changes
• Playwright visual audit run locally — N/A: no UI changes

End-to-End Verification (Required for multi-component changes)

• Data flow traced from workflow install to final Cloudflare Pages outcome with code-path citations
• Capability test exercises the complete happy path across the package-manager, GitHub Actions, Wrangler, and Cloudflare Pages boundaries
• Existing CLI assumptions verified against the pinned Wrangler 4.118.0 source/help and Cloudflare's official command reference
• The only remaining full-E2E gap is the production alias after merge; it is documented below and will be monitored before declaring the task complete

Data Flow Trace

1. apps/www/package.json declares wrangler: catalog:; pnpm-lock.yaml resolves the workspace dependency to 4.118.0 during the frozen install.
2. deploy-www.yml installs the lockfile, builds apps/www, then runs the marketing workspace's binary against its dist directory at line 71.
3. Wrangler authenticates with the unchanged CF_API_TOKEN and CF_ACCOUNT_ID, uploads to the unchanged Pages project, and returns the immutable/branch deployment URLs.
4. provision-www.yml uses that same binary to list projects, validates an array response, skips an exact Project Name match, or creates the missing project while allowing failures to terminate the job.
5. deployment-workflow-hardening.test.ts freezes the dependency owner, pinned invocations, fail-closed checks, and ban on npx wrangler across both workflows.

Untested Gaps

The production custom-domain alias cannot represent the merged revision before merge. After merge, the exact merge SHA's Deploy Marketing Site run will be monitored and https://www.simple-agent-manager.org/ checked before completion is reported.

Post-Mortem (Required for bug fix PRs)

What broke

Every affected main marketing deployment since PR #1784 built successfully and then failed with sh: 1: wrangler: not found, leaving the public site available but stale.

Root cause

The workflow relied on npx registry fallback instead of declaring and invoking a repository-owned executable. PR #1784 changed the dependency graph so npm detected a transitive Wrangler that pnpm did not link at the repository root, exposing the hidden executable-resolution assumption.

Class of bug

Package-manager executable-resolution ambiguity in a post-merge deployment workflow.

Why it wasn't caught

PR validation did not enforce the same pinned-Wrangler contract across the separate marketing workflows. The marketing deployment itself runs after merge and was not a required pull-request check.

Process fix included in this PR

scripts/quality/deployment-workflow-hardening.test.ts now requires direct marketing-workspace dependency ownership, exact pinned deployment/provisioning invocations, strict failure semantics, and rejects npx wrangler anywhere in either workflow. The two .github/workflows/ files now encode the repository-owned invocation directly.

Post-mortem file

tasks/active/2026-08-11-fix-marketing-pages-wrangler-resolution.md

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A: every reviewer completed.

Reviewer	Status	Outcome
task-completion-validator	PASS	No implementation gap; production delivery is the scheduled post-merge gate.
cloudflare-specialist	ADDRESSED	Verified pinned CLI/schema, working directory, five provision/error paths, and live Pages deployment; no remaining finding.
test-engineer	ADDRESSED	Whole-workflow npx guard added; focused 9/9 and quality 297/297 pass with no merge-blocking gap.
constitution-validator	ADDRESSED	Principle XIII fail-open finding fixed with strict, shape-validated, exact-match provisioning.
doc-sync-validator	PASS	No public inputs, permissions, secrets, architecture, or documentation contract changed.

Exceptions (If any)

• Scope: Production custom-domain verification is post-merge by definition.
• Rationale: The production Pages deployment workflow triggers from main; branch verification used a real isolated Pages preview.
• Expiration: Immediately after merge, when the exact merged SHA is verified on Pages.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

Official documentation consulted before coding: Cloudflare Wrangler Pages commands, covering pages deploy, pages project list --json, and pages project create --production-branch.

Codebase Impact Analysis

apps/www/package.json and pnpm-lock.yaml establish executable ownership; .github/workflows/deploy-www.yml and .github/workflows/provision-www.yml use it; scripts/quality/deployment-workflow-hardening.test.ts and scripts/quality/direct-dependency-evidence.json freeze the contract; the active task records the incident and evidence.

Documentation & Specs

N/A: the fix changes internal executable resolution and failure handling without changing public commands, configuration inputs, environment variables, permissions, secrets, or product behavior. The incident/post-mortem is recorded in the active task file.

Constitution & Risk Check

Checked Principles II, III, XI, XII, XIII, XIV, XVII, XVIII, XXIII, and XXV. Primary risks were hidden executable resolution, registry fallback, false-success provisioning, accidental project-name matches, and documentation drift. Direct catalog ownership, frozen-install proof, strict shell/error propagation, response-shape validation, exact matching, contract tests, live preview deployment, and specialist review mitigate them without expanding permissions or secret handling.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/looks-merged-couple-prs-sgpvq2 (c940199) with main (e5aea69)}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud