Skip to main content

Critical-Path Definition & Gate

What is a critical path?​

A critical path is a code flow where breakage immediately harms customers or costs the company real money:

  • Live Stripe checkout (customer pays, nothing provisions)
  • Inbound voice call (phone rings, agent doesn't answer)
  • User login (pastors locked out of their admin)
  • Live chatbot response (visitor asks, nothing answers)

Critical paths are declared in knowledge/tests/registry.yaml with critical_path: true. Each declaration lists:

  • code_files — the directories + files whose modification puts the path at risk
  • playwright_spec — the name of the live-flow E2E test that must pass
  • override_label — the PR label that explicitly overrides the gate
  • last_break (if applicable) — the date the path most recently broke in production

What the gate does​

On every PR to a repo with the critical-path-gate workflow installed, the gate:

  1. Reads knowledge/tests/registry.yaml from the ChurchWiseAI/knowledge repo
  2. Filters to entries with critical_path: true for this repo
  3. Compares the PR's changed files against each entry's code_files list
  4. If the PR touches any critical-path file, requires one of:
    • A CI artifact named <spec_name>-playwright-run.zip showing a green run
    • The PR label critical-path-override + a comment explaining why
  5. Blocks merge if neither is present

Why this exists (the 2026-04-14 incident)​

On April 14, 2026, an agent shipped a Stripe harness refactor that passed build, passed type checks, and merged cleanly. The webhook started returning HTTP 200 on silent provisioning failures — Stripe thought everything was fine, customers paid real money, nothing got provisioned. The founder lost a live payment and spent the evening diagnosing instead of onboarding customers.

Agent feedback memory already said "NEVER claim done without Playwright-verified interaction on the deployed URL." It had no enforcement mechanism. This gate is the enforcement mechanism. Agents can no longer ship critical-path code and say "done" — the PR literally cannot merge without either verified evidence or a logged override.

How to add a new critical path​

  1. Edit knowledge/tests/registry.yaml
  2. Add an entry with critical_path: true, list the code_files, name the playwright_spec
  3. Ensure the Playwright spec exists and runs against the deployed URL
  4. Wire the spec to upload its output as an artifact named <spec_name>-playwright-run.zip in the CI workflow that runs it
  5. Merge the registry change. From then on, every PR touching those files is gated.

How to override (for genuinely non-customer-facing changes)​

If you're editing a critical-path file in a way that cannot touch the customer flow (e.g., updating a code comment, renaming an unused variable):

  1. Add label critical-path-override to the PR
  2. Add a comment explaining why the change is safe without a live-flow run
  3. Gate allows merge

Overrides are logged and auditable. The expected use is rare — the default path should always be "attach a verified Playwright run."

Current critical paths (MVP)​

As of 2026-04-14, one path is gated:

  • stripe-live-checkout — live Stripe checkout + webhook provisioning in churchwiseai-web

Paths declared but not yet gated (waiting for their Playwright specs to exist and go green at least once):

  • voice-live-call
  • user-login-cwa

When their specs exist and pass, flip critical_path: true in the registry and they're live.