Instruction file imported from Columbia-Cloudworks-LLC/EquipQR (.cursor/rules/pr-ci-gate-before-open.mdc). Copyright stays with the author.

PR CI Gate (mandatory before open and handoff)

This file is a publish gate (branching.mdc). It does not apply to local-iterate work.

Local lint/tests/build are necessary but not sufficient for feature-branch PRs. CI runs a clean npm ci on Linux runners; that path must pass before gh pr create and before the agent marks the PR workflow complete.

Hard rules

1. Never run gh pr create until CI-parity install succeeds locally:

   .\dev\npm-ci-safe.bat

   That script stops the stack, then runs npm ci --prefer-offline --no-audit. Do not run bare npm ci while Vite or the stack is up on Windows (dev-stack-lifecycle.mdc). If this fails, fix lockfile / .npmrc / dependency peers before push or PR open. If still blocked locally after a lock release, ensure CI passes on push (Linux clean install). Do not rely on npm install --legacy-peer-deps alone when npm ci would fail — if you needed --legacy-peer-deps, ensure .npmrc sets legacy-peer-deps=true and re-run .\dev\npm-ci-safe.bat.

2. After git push to the PR branch, wait for required checks before handoff:

   gh pr checks <number> --watch

   Or poll until all required jobs pass:

   gh pr checks <number>

   Do not report the PR as complete, walk away, or publish final summary while Lint, Test shards, Security Scan, or Build jobs are failing or pending.

3. If checks fail after push: fix on the same branch, push again, re-watch until green. Post a brief PR comment only after the fix push if the maintainer needs context.

4. Handoff must cite CI status: include gh pr checks output or a link to the green workflow run. "Local tests passed" is not an acceptable substitute for red CI.

Release metadata (dual modes)

CI runs different release-metadata jobs by PR base (ci.yml):

Local checks:

# Feature PR into preview
$env:RELEASE_METADATA_MODE = 'preview'
$env:RELEASE_METADATA_BASE_SHA = (git merge-base HEAD origin/preview)
npm run verify:release-metadata
Remove-Item Env:RELEASE_METADATA_MODE, Env:RELEASE_METADATA_BASE_SHA -ErrorAction SilentlyContinue

# Release PR into main
$env:RELEASE_METADATA_MODE = 'main'
$env:RELEASE_METADATA_BASE_SHA = (git merge-base HEAD origin/main)
npm run verify:release-metadata
Remove-Item Env:RELEASE_METADATA_MODE, Env:RELEASE_METADATA_BASE_SHA -ErrorAction SilentlyContinue

Workflow-only paths (.cursor/**, docs/**, AGENTS.md, etc.) remain exempt, same as changelog-stop.

Minimum CI-parity gate (feature PRs)

Run in order after dependency changes or before first PR open:

1. Fallow (both scans) per fallow-before-commit.mdc
2. npm ci --prefer-offline --no-audit — must exit 0 (matches .github/workflows/ci.yml)
3. npm run lint, npm run type-check, npm run test:ci, npm run build, npm run verify:spa-routing
4. Local E2E per local-verify-before-preview-push.mdc
5. PR visual evidence per pr-visual-evidence.mdc when UI changed
6. Push → gh pr checks --watch until required jobs pass and Supabase is green or skipped, then merge per pr-merge-ready-workflow.mdc. Do not wait for Qodo.

Relationship to other rules

• pr-merge-ready-workflow.mdc: full open-through-merge-ready standard; this rule covers install parity + CI green within that flow.
• local-verify-before-preview-push.mdc: adds E2E and product verification before push/open.
• branching.mdc: linked-worktree PR flow is not complete until merge-ready criteria pass — not merely "open PR and let CI run." Day-to-day base is preview; promote via preview → main.
• Direct push to main / preview: blocked by branch protection; merge via PR after local verify. Feature branches use this rule in full.

Stop conditions

• Stop before gh pr create if npm ci fails locally.
• Stop handoff if required checks are red — fix or report blocker; do not leave a failing PR for the maintainer to discover.
• Stop if fixes require secrets/OAuth the agent cannot run in CI (report explicitly).