Run 4: Production Cutover

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	Run 3 GO/NO-GO decision is GO	grep -q "Decision: GO" run-3-validation/go-no-go.md	Match found
2	Workflows validated on demo	Run 3 exit criteria all passed	All passed
3	Alpha002 IAM role exists	aws iam get-role --role-name Alpha002-API-GitHubActionFrontEnd --query "Role.RoleName"	Alpha002-API-GitHubActionFrontEnd
4	Existing Amplify App IDs verified	See verification commands below	App IDs match documented values
5	amplifyExports.cfn.yaml exists in infrastructure repo	test -f infrastructure/src/main/cfn/amplifyExports.cfn.yaml	File exists
6	Stakeholders notified of cutover	Manual confirmation	denisa, jmpicnic, danmerb, davequinta aware

Verify existing Amplify App IDs (must match before proceeding):

# dev (Alpha002, us-east-1)
aws amplify get-app --app-id d38w5m1ngjza76 --region us-east-1 \
  --query "app.name" --output text
# Expected: dev-arda-frontend-app

# stage (Alpha002, us-east-1)
aws amplify get-app --app-id d1kbrvra79y8sc --region us-east-1 \
  --query "app.name" --output text
# Expected: stage-arda-frontend-app

# prod (Alpha001, us-east-2)
aws amplify get-app --app-id duhexavnwh88g --region us-east-2 \
  --query "app.name" --output text
# Expected: arda-frontend-app

Artifact Specifications

Artifact	Path	Format	Description
Rollback plan	run-4-cutover/rollback-plan.md	Markdown	Per-partition rollback procedures
Post-cutover instructions	run-4-cutover/post-cutover-instructions.md	Markdown	Deferred cleanup procedures
Frontend development guide	/documentation/src/content/docs/process/craft/implementation/frontend-development.md	Markdown	Developer-facing guide
Lightweight export stacks	AWS CloudFormation (us-east-1)	Stacks	Alpha002-dev-AmplifyExports, Alpha002-stage-AmplifyExports, Alpha001-prod-AmplifyExports

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
4.1	Write rollback-plan.md	Agent	—	Pending	Document exists with per-partition rollback commands
4.2	Deploy lightweight export stacks for dev, stage, prod	Operator	—	Pending	CloudFormation exports available for all three partitions in us-east-1
4.3	Create and merge PR2 (demo → main): workflows with full matrix + CI status check in redeploy	Operator	—	Pending	PR2 merged; workflows exist on main; deploy.yaml has full matrix; redeploy.yaml includes CI status check (commit status API verification before deployment)
4.4	Migrate dev partition	Operator	4.1, 4.2, 4.3	Pending	Auto-build disabled; deployment via deploy.yaml succeeds; site functional
4.5	Migrate stage partition	Operator	4.4 verified	Pending	Auto-build disabled; deployment succeeds (with reviewer approval); site functional
4.6	Migrate prod partition	Operator	4.5 verified	Pending	Auto-build disabled; deployment succeeds (with reviewer approval); site functional
4.7	Create and merge PR3: deploy.yaml trigger switch — add workflow_run on CI success	Agent + Operator	4.6 verified	Pending	PR3 merged; deploy.yaml on main fires on CI success
4.8	Enable PR preview on dev app	Operator	4.4	Pending	PR preview builds; preview URL posted on PR; sign-in works
4.9	Update Amplify build spec with unit tests	Agent	4.8	Pending	npm run test runs before npm run build in build spec
4.10	Rollback dry-run	Operator	4.4	Pending	redeploy.yaml deploys previous SHA to dev successfully
4.11	Write frontend development guide	Agent	4.7, 4.8	Pending	Guide exists at expected path; covers all required topics
4.12	Write post-cutover-instructions.md	Agent	4.6	Pending	Document exists with deferred procedures
4.13	Pipeline stability verification: merge a trivial PR (e.g., README change) to main and verify the full automated pipeline	Agent + Operator	4.7	Pending	PR merged → CI passes → workflow_run triggers deploy.yaml → all 4 partitions deploy successfully → sites verified

Task Details

Task 4.1: Write rollback-plan.md

Who: Agent

File: run-4-cutover/rollback-plan.md

Content must include:

Per-partition rollback — re-enable auto-build:

Partition	Command
dev	aws amplify update-branch --app-id d38w5m1ngjza76 --branch-name dev --enable-auto-build --region us-east-1
stage	aws amplify update-branch --app-id d1kbrvra79y8sc --branch-name stage --enable-auto-build --region us-east-1
prod	aws amplify update-branch --app-id duhexavnwh88g --branch-name main --enable-auto-build --region us-east-2

Per-partition rollback — trigger manual build from original branch:

Partition	Command
dev	aws amplify start-job --app-id d38w5m1ngjza76 --branch-name dev --job-type RELEASE --region us-east-1
stage	aws amplify start-job --app-id d1kbrvra79y8sc --branch-name stage --job-type RELEASE --region us-east-1
prod	aws amplify start-job --app-id duhexavnwh88g --branch-name main --job-type RELEASE --region us-east-2

Redeploy via redeploy.yaml:

• Go to GitHub Actions → “Redeploy Frontend” → select partition and known-good SHA

Contact list: denisa, jmpicnic, danmerb, davequinta

Task 4.2: Deploy Lightweight Export Stacks

Who: Operator

All stacks deployed in us-east-1 regardless of Amplify app region. Use the AWS CLI with the correct account credentials.

Alpha002 — dev (account 139852620346):

aws cloudformation deploy \
  --region us-east-1 \
  --stack-name "Alpha002-dev-AmplifyExports" \
  --template-file "src/main/cfn/amplifyExports.cfn.yaml" \
  --parameter-overrides \
    "Infrastructure=Alpha002" "Partition=dev" \
    "AmplifyAppId=d38w5m1ngjza76" "AmplifyBranchName=dev"

Alpha002 — stage (account 139852620346):

aws cloudformation deploy \
  --region us-east-1 \
  --stack-name "Alpha002-stage-AmplifyExports" \
  --template-file "src/main/cfn/amplifyExports.cfn.yaml" \
  --parameter-overrides \
    "Infrastructure=Alpha002" "Partition=stage" \
    "AmplifyAppId=d1kbrvra79y8sc" "AmplifyBranchName=stage"

Alpha001 — prod (account 009765408297):

aws cloudformation deploy \
  --region us-east-1 \
  --stack-name "Alpha001-prod-AmplifyExports" \
  --template-file "src/main/cfn/amplifyExports.cfn.yaml" \
  --parameter-overrides \
    "Infrastructure=Alpha001" "Partition=prod" \
    "AmplifyAppId=duhexavnwh88g" "AmplifyBranchName=main"

Verification (all in us-east-1):

# dev
aws cloudformation list-exports --region us-east-1 --output text \
  --query "Exports[?Name=='Alpha002-dev-I-AmplifyAppId'].Value"
# Expected: d38w5m1ngjza76

# stage
aws cloudformation list-exports --region us-east-1 --output text \
  --query "Exports[?Name=='Alpha002-stage-I-AmplifyAppId'].Value"
# Expected: d1kbrvra79y8sc

# prod
aws cloudformation list-exports --region us-east-1 --output text \
  --query "Exports[?Name=='Alpha001-prod-I-AmplifyAppId'].Value"
# Expected: duhexavnwh88g

Task 4.3: Create and Merge PR2 (demo → main)

Who: Operator

PR2 brings the validated workflows from the demo branch to main.

The PR must include a CHANGELOG.md update in the arda-frontend-app repository.

1. Create a PR from demo to main in arda-frontend-app containing the three workflow files.
2. Before merging, update deploy.yaml on the PR branch to include the full matrix:

strategy:
  matrix:
    include:
      - partition: dev
      - partition: stage
      - partition: demo
      - partition: prod
        amplify_region: us-east-2
  max-parallel: 1
  fail-fast: true

3. Also implement the CI status check in redeploy.yaml (the TODO from Run 2 task 2.3).
4. Merge the PR. The validate-pr-source.yml check may need to be addressed — the PR comes from demo, not from stage. Options:
   • Temporarily relax validate-pr-source.yml for this specific PR
   • Use an admin merge bypass
   • The workflow may already allow PRs from any branch to main if demo is not a protected branch target

Task 4.4: Migrate dev Partition

Who: Operator

1. Disable auto-build:

   aws amplify update-branch --app-id d38w5m1ngjza76 --branch-name dev \
     --no-enable-auto-build --region us-east-1

2. Verify auto-build disabled:

   aws amplify get-branch --app-id d38w5m1ngjza76 --branch-name dev \
     --region us-east-1 --query "branch.enableAutoBuild"
   # Expected: false

3. Trigger deploy.yaml via workflow_dispatch on main. The matrix now includes dev. Monitor the dev partition deployment.

4. Verify the site: Visit dev.alpha002.app.arda.cards — page loads, no errors.

5. Do not proceed to stage until dev is verified.

Task 4.5: Migrate stage Partition

Who: Operator

1. Disable auto-build:

   aws amplify update-branch --app-id d1kbrvra79y8sc --branch-name stage \
     --no-enable-auto-build --region us-east-1

2. Verify auto-build disabled:

   aws amplify get-branch --app-id d1kbrvra79y8sc --branch-name stage \
     --region us-east-1 --query "branch.enableAutoBuild"
   # Expected: false

3. Trigger deploy.yaml via workflow_dispatch on main. The stage partition requires reviewer approval — one of denisa, jmpicnic, danmerb, davequinta must approve.

4. Verify the site: Visit stage.alpha002.app.arda.cards — page loads, no errors.

5. Do not proceed to prod until stage is verified.

Task 4.6: Migrate prod Partition

Who: Operator

This is the highest-risk step. Ensure the rollback plan is reviewed before proceeding.

1. Disable auto-build:

   aws amplify update-branch --app-id duhexavnwh88g --branch-name main \
     --no-enable-auto-build --region us-east-2

2. Verify auto-build disabled:

   aws amplify get-branch --app-id duhexavnwh88g --branch-name main \
     --region us-east-2 --query "branch.enableAutoBuild"
   # Expected: false

3. Trigger deploy.yaml via workflow_dispatch on main. The prod partition:

   • Uses amplify_region: us-east-2 (from the matrix override)
   • Requires reviewer approval

4. Verify the site: Visit live.app.arda.cards — page loads, authentication works, API calls succeed. The deployed version should match the commit SHA from main.

5. If deployment fails: Execute the rollback plan (Task 4.1) — re-enable auto-build on prod:

   aws amplify update-branch --app-id duhexavnwh88g --branch-name main \
     --enable-auto-build --region us-east-2

Task 4.7: Create and Merge PR3 (Trigger Switch)

Who: Agent + Operator

PR3 enables automatic deployment on CI success. This is a separate PR from PR2 because the trigger switch should only happen after all partitions are verified with manual workflow_dispatch triggers.

Create a feature branch off main (e.g., jmpicnic/frontend-pipeline/deploy-trigger-switch). The PR must include a CHANGELOG.md update in the arda-frontend-app repository.

Modify deploy.yaml to add workflow_run as the primary trigger, retaining workflow_dispatch as fallback:

on:
  workflow_run:
    workflows: ["CI"]  # Must match the exact name of ci.yaml
    types: [completed]
    branches: [main]
  workflow_dispatch:
    # Manual fallback trigger

Add a condition to the job to only run on CI success (for the workflow_run trigger):

jobs:
  deploy:
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')

Also in this PR — fix redeploy.yaml CI verification: The verify-ci job in redeploy.yaml checks ALL check runs on the commit, including non-CI runs (deploy workflows, coverage, validate-pr-source). This causes false negatives — the redeploy is blocked by pre-existing non-CI failures. Fix by filtering to only CI-relevant check run names:

# Filter to CI check names only
TOTAL=$(gh api "repos/${{ github.repository }}/commits/${SHA}/check-runs?per_page=100" \
  --jq '[.check_runs[] | select(.name | test("^(lint|build|test|validate-release)"))] | length')

Apply the same filter to the pending and failing counts.

Verification: Merge a test PR to main. Confirm ci.yaml runs, then deploy.yaml triggers automatically.

Task 4.8: Enable PR Preview on Dev App

Who: Operator

aws amplify update-branch --app-id d38w5m1ngjza76 --branch-name dev \
  --enable-pull-request-preview --region us-east-1

Verification:

1. Open a test PR against main in arda-frontend-app
2. Wait for Amplify to build the PR branch (triggered via GitHub webhook, independent of GHA)
3. Check the PR comments for the preview URL (e.g., pr-{N}.d38w5m1ngjza76.amplifyapp.com)
4. Visit the preview URL — page loads
5. Sign in with test credentials — sign-in works (direct password auth, no callback URL needed)
6. Push a new commit to the PR branch — verify it redeploys to the same URL
7. Close/merge the PR — verify the preview is deleted

Task 4.9: Update Amplify Build Spec

Who: Agent

Update the Amplify build spec to run unit tests before the build. This applies to both PR preview builds and official StartJob deployments.

The build spec is inline on the dev app (not in a repo file). Update via Amplify Console or AWS CLI. Alternatively, add an amplify.yml file to the repository root.

The key change — add npm run test before npm run build in the build commands:

build:
  commands:
    - npm run test
    - npm run build

Task 4.10: Rollback Dry-Run

Who: Operator

1. Identify the previous production SHA (before the cutover deployment):

   gh api repos/Arda-cards/arda-frontend-app/commits?sha=main&per_page=3 \
     --jq '.[1].sha'

2. Trigger redeploy.yaml with partition dev and the previous SHA.

3. Verify the deployment succeeds and the dev site reflects the older version.

4. Redeploy the latest SHA to restore dev to current state.

Task 4.11: Write Frontend Development Guide

Who: Agent

File: documentation/src/content/docs/process/craft/implementation/frontend-development.md

Content must cover:

1. Development workflow: Open a PR against main → Amplify PR preview deploys automatically → verify at preview URL → push updates → merge when ready
2. PR preview details: How to find the preview URL (Amplify comment on the PR), what backend it talks to (dev partition — same API Gateway, Cognito pools, database), quality gate (unit tests in Amplify build spec), automatic cleanup on PR close/merge
3. Production deployment pipeline: What happens after merge to main — CI runs, then sequential deployment to dev → stage → demo → prod with authorization gates on stage and prod
4. Manual redeploy / rollback: How to use redeploy.yaml to deploy a specific SHA to a single partition. Re-enable auto-build as emergency fallback.
5. Local development: Existing npm run dev workflow, environment variable setup, .env.local configuration
6. Environment map:

Partition	URL	Account	Purpose
dev	dev.alpha002.app.arda.cards	Alpha002	Development testing, PR preview backend
stage	stage.alpha002.app.arda.cards	Alpha002	Pre-production staging
demo	demo.alpha001.app.arda.cards	Alpha001	Demo environment
prod	live.app.arda.cards	Alpha001	Production

Task 4.12: Write post-cutover-instructions.md

Who: Agent

File: run-4-cutover/post-cutover-instructions.md

Content must include:

1. Production verification procedure: Step-by-step instructions for verifying live.app.arda.cards — sign-in, page navigation, key workflows. Coordinate with business stakeholders.

2. validate-pr-source.yml relaxation: Three options:

   • (a) Remove the workflow entirely
   • (b) Two-step: first allow PRs from any branch to main, then remove
   • (c) Invert: block PRs from dev/stage to main (prevent accidental use of old model)

3. Branch deletion: Delete dev, stage, and demo branches from arda-frontend-app:

   git push origin --delete dev
   git push origin --delete stage
   git push origin --delete demo

   Only after confirming the new pipeline is stable.

4. Demo cleanup (if demo is not permanent):

   aws cloudformation delete-stack --stack-name "Alpha001-demo-AmplifyBranch" --region us-east-1
   aws cloudformation wait stack-delete-complete --stack-name "Alpha001-demo-AmplifyBranch" --region us-east-1
   aws cloudformation delete-stack --stack-name "Alpha001-demo-Amplify" --region us-east-1

   Branch stack must be deleted first (depends on app stack exports).

5. IAM role OIDC scope cleanup (PR4): Remove refs/heads/demo from the frontend role’s OIDC trust conditions in gh-oidc-provider.ts. Create PR4 in infrastructure repo (branch: jmpicnic/frontend-pipeline/oidc-cleanup) with a CHANGELOG.md update, merge, and deploy via amm.sh to both accounts.

Task 4.13: Pipeline Stability Verification

Who: Agent + Operator

This is the final verification that the entire automated pipeline works end-to-end from a real PR merge. It exercises the workflow_run trigger added in PR3 and confirms all four partitions deploy successfully without manual intervention.

Steps:

1. Create a feature branch with a trivial change (e.g., add a comment to README.md)
2. Open a PR against main
3. Wait for CI to pass
4. Merge the PR
5. Verify ci.yaml runs and succeeds on main
6. Verify deploy.yaml triggers automatically via workflow_run
7. Monitor the sequential deployment: dev (auto) → stage (approve) → demo (auto) → prod (approve)
8. Verify all four sites are functional after deployment

Pipeline is stable when: This verification passes — a real PR merge triggers automated CI → deploy to all partitions with correct approval gates. At that point, post-cutover cleanup items (branch deletion, validate-pr-source.yml relaxation, OIDC scope cleanup) can proceed.

Internal Dependency Graph

4.1 (rollback plan) ──────────────────────────────────────┐
4.2 (export stacks) ──────────────────────────────────────┤
4.3 (PR2: demo → main) ──────────────────────────────────┤
                                                           │
                     4.4 (migrate dev) ◄───────────────────┘
                           │
                     4.5 (migrate stage) ◄── 4.4 verified
                           │
                     4.6 (migrate prod) ◄── 4.5 verified
                           │
              ┌────────────┼────────────┐
              │            │            │
        4.7 (PR3:      4.12 (post)   4.10 (rollback dry-run, can start after 4.4)
         trigger)
              │
        4.13 (stability verification) ◄── 4.7
              │
        4.11 (dev guide) ◄── 4.13 + 4.8

4.8 (PR preview) ◄── 4.4
4.9 (build spec) ◄── 4.8

Tasks 4.1, 4.2, 4.3 can be done in parallel. Task 4.3 (PR2) must be merged before partition migration. Task 4.8 can start after 4.4. Task 4.10 can start after 4.4. The partition migrations (4.4 → 4.5 → 4.6) are strictly sequential. Task 4.7 (PR3) is a separate PR created after all partitions are verified.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	rollback-plan.md exists	test -f run-4-cutover/rollback-plan.md	File exists
2	Export stacks deployed (dev)	aws cloudformation list-exports --region us-east-1 --output text --query "Exports[?Name=='Alpha002-dev-I-AmplifyAppId'].Value"	d38w5m1ngjza76
3	Export stacks deployed (stage)	aws cloudformation list-exports --region us-east-1 --output text --query "Exports[?Name=='Alpha002-stage-I-AmplifyAppId'].Value"	d1kbrvra79y8sc
4	Export stacks deployed (prod)	aws cloudformation list-exports --region us-east-1 --output text --query "Exports[?Name=='Alpha001-prod-I-AmplifyAppId'].Value"	duhexavnwh88g
5	Auto-build disabled (dev)	aws amplify get-branch --app-id d38w5m1ngjza76 --branch-name dev --region us-east-1 --query "branch.enableAutoBuild"	false
6	Auto-build disabled (stage)	aws amplify get-branch --app-id d1kbrvra79y8sc --branch-name stage --region us-east-1 --query "branch.enableAutoBuild"	false
7	Auto-build disabled (prod)	aws amplify get-branch --app-id duhexavnwh88g --branch-name main --region us-east-2 --query "branch.enableAutoBuild"	false
8	Full sequential deployment succeeded	Check deploy.yaml run history on main	Run with all 4 partitions succeeded
9	Dev site functional	curl -s -o /dev/null -w "%{http_code}" https://dev.alpha002.app.arda.cards	200
10	Stage site functional	curl -s -o /dev/null -w "%{http_code}" https://stage.alpha002.app.arda.cards	200
11	Prod site functional	curl -s -o /dev/null -w "%{http_code}" https://live.app.arda.cards	200
12	PR preview works	Open test PR; preview URL posted	Preview URL accessible
13	Rollback dry-run succeeded	redeploy.yaml ran with previous SHA on dev	Workflow succeeded
14	deploy.yaml triggers on CI success	Merge a PR to main; check if deploy.yaml fires	workflow_run trigger in run metadata
15	Pipeline stability verified	Trivial PR merged → CI → deploy → all 4 partitions succeed automatically	All sites functional after automated deploy
16	Frontend dev guide exists	test -f documentation/src/content/docs/process/craft/implementation/frontend-development.md	File exists
17	Post-cutover instructions exist	test -f run-4-cutover/post-cutover-instructions.md	File exists

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path/Location
Workflow files (on demo branch)	Run 2	arda-frontend-app/.github/workflows/
GO/NO-GO decision	Run 3	run-3-validation/go-no-go.md
amplifyExports.cfn.yaml	Run 1	infrastructure/src/main/cfn/amplifyExports.cfn.yaml
amm.sh with export stack support	Run 1	infrastructure/amm.sh
IAM roles (both accounts)	Run 1	AWS IAM

Artifacts Produced (for subsequent runs)

Artifact	Consumer	Path/Location
Migrated Amplify apps (all 4 partitions)	Ongoing operations	AWS Amplify
Frontend development guide	Developers	documentation/src/content/docs/process/craft/implementation/frontend-development.md
post-cutover-instructions.md	Post-project cleanup	run-4-cutover/post-cutover-instructions.md
rollback-plan.md	Emergency reference	run-4-cutover/rollback-plan.md