Skip to content
GOVERN Internal

QA Gates

GOVERN enforces two constitutional quality gates before any release. These are not suggestions — a failed gate is a blocked deploy. This page defines what each gate requires and how to measure compliance.

Gate II — V(Q) >= 85%

Gate II is the convergence quality gate. It scores the release across multiple dimensions and requires a combined score of 85% or higher.

The V(Q) formula

V(Q) = (TypecheckScore × 0.20) +
       (UnitTestScore × 0.20) +
       (IntegrationTestScore × 0.20) +
       (E2ETestScore × 0.15) +
       (VisualRegressionScore × 0.15) +
       (APISpotCheckScore × 0.10)


Threshold: V(Q) >= 0.85 → PROCEED
           V(Q) < 0.85  → BLOCKED

Dimension scoring

DimensionWeightPass conditionScore
TypeScript typecheck20%Zero errors (pnpm typecheck)1.0 if zero, 0.0 otherwise
Unit tests20%All suites pass(passing / total)
Integration tests20%All suites pass(passing / total)
E2E tests15%Critical paths pass(passing critical paths / total)
Visual regression15%No unreviewed diffs1.0 if none, 0.0 if any
API spot-checks10%All spot-checks pass(passing checks / total)

Running the V(Q) score

expressiveCode.terminalWindowFallbackTitle
# Full V(Q) score calculation
pnpm run qa:score


# Output:
# TypeScript: PASS (0 errors) → 1.00
# Unit tests: PASS (248/248) → 1.00
# Integration: PASS (42/42) → 1.00
# E2E: PASS (8/8) → 1.00
# Visual: PASS (0 diffs) → 1.00
# API checks: PASS (12/12) → 1.00
#
# V(Q) Score: 1.00 ✓ (threshold: 0.85)
# Gate II: OPEN

What makes Gate II fail

  • Any TypeScript error (even in non-critical files)
  • Any unit test failure
  • Any integration test failure
  • Any unreviewed visual diff
  • Any API spot-check returning unexpected status codes

A partial failure (e.g., 3 of 248 unit tests failing) will lower the score below 85% and block the gate. There is no “close enough” — fix the failures.

Gate IV — 5-Point Polish Check

Gate IV applies to every UI surface before it ships. It verifies that GOVERN’s user-facing components meet the Living Visualization doctrine.

The 5 checkpoints

Checkpoint 1: Scene moves at idle

The UI must have ambient animation running at idle state. A completely static UI fails this check.

Verification:

expressiveCode.terminalWindowFallbackTitle
# Playwright check
await page.waitForTimeout(3000);
const animationsRunning = await page.evaluate(() => {
  const elements = document.querySelectorAll('[data-animated="true"]');
  return elements.length > 0;
});
expect(animationsRunning).toBe(true);

Checkpoint 2: Orb is the interface, not a textarea

The primary interaction surface must be the civilization orb, not a traditional input field. No large textarea should be the dominant visual element.

Verification:

expressiveCode.terminalWindowFallbackTitle
# Check orb is present and dominant
const orb = await page.locator('[data-testid="civilization-orb"]');
await expect(orb).toBeVisible();


# Check no textarea is the primary element
const textareas = await page.locator('textarea').count();
# If textareas exist, they should be secondary (below the fold or in a panel)

Checkpoint 3: Page matches reference benchmark

The page must visually match the reference at https://archetypal-app.pages.dev/ in terms of energy, color palette, and interface density.

Verification: Visual comparison screenshot. Reviewed by an engineer against the benchmark.

Checkpoint 4: Energy layers L1/L2/L3 visible

All three energy layers (base field, mid field, surface field) must be present and visible.

Verification:

expressiveCode.terminalWindowFallbackTitle
await expect(page.locator('[data-layer="energy-l1"]')).toBeVisible();
await expect(page.locator('[data-layer="energy-l2"]')).toBeVisible();
await expect(page.locator('[data-layer="energy-l3"]')).toBeVisible();

Checkpoint 5: Text is ambient, not dominant

Text content must be secondary to the visualization. Dense text walls, modal-heavy UIs, or form-first layouts fail this check.

Verification: Visual review. The primary visual impression should be energy and motion, with text appearing on focus or hover, not filling the viewport.

Running the Gate IV check

expressiveCode.terminalWindowFallbackTitle
# Automated checks (3 of 5 can be automated)
pnpm run qa:polish


# This runs Playwright checks for:
# - Checkpoint 1 (ambient animation)
# - Checkpoint 3 (energy layers)


# Checkpoints 2, 4, 5 require human review
# The Testing Dashboard shows a review form:
# [ ] Orb is the dominant interaction element
# [ ] Visual matches reference benchmark
# [ ] Text is secondary to the visualization

TypeScript Zero-Error Requirement

Every GOVERN package must pass typecheck with zero errors before release.

expressiveCode.terminalWindowFallbackTitle
# Run across all packages
pnpm typecheck


# Expected output for a clean build:
# packages/core: 0 errors
# packages/api-gateway: 0 errors
# packages/dashboard: 0 errors
# packages/govern-dashboard: 0 errors
# packages/govern-app: 0 errors
# Total: 0 errors ✓


# If errors are found:
# packages/api-gateway: 3 errors
#   src/routes/monitoring.ts(42,5): error TS2345: ...
# Total: 3 errors ✗ — GATE BLOCKED

TypeScript strict mode

All GOVERN packages run TypeScript in strict mode:

tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

These settings catch errors that non-strict TypeScript would miss. Do not disable them to silence errors — fix the errors.

Test Pass Requirements

expressiveCode.terminalWindowFallbackTitle
# Unit tests — must return 0 failures
pnpm test
# Test Files  12 passed (12)
# Tests       248 passed (248)


# Integration tests — must return 0 failures
pnpm test:integration
# Test Files  6 passed (6)
# Tests       42 passed (42)

Non-negotiable test rules (from ENGINEERING_LAW_CODE.md)

  1. Every bug fix requires a regression test that would have caught the bug
  2. Every new API endpoint requires at least one test
  3. pnpm test must pass before any commit or deploy
  4. pnpm typecheck must pass. Zero TypeScript errors is the bar
  5. Evidence of passing must appear in the work report

Gate Status Dashboard

The Testing Dashboard shows gate status in real-time:

GOVERN Release Gate Status — v0.12.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Gate II (V(Q))
  Typecheck        ✓  1.00  (0 errors)
  Unit Tests       ✓  1.00  (248/248)
  Integration      ✓  1.00  (42/42)
  E2E              ✓  1.00  (8/8)
  Visual           ✓  1.00  (0 diffs)
  API Spot-checks  ✓  1.00  (12/12)
  ─────────────────────────────────
  V(Q) Score:      1.00  ✓ GATE OPEN


Gate IV (Polish)
  [ ✓ ] Scene moves at idle
  [ ✓ ] Orb is the interface
  [ ✓ ] Matches reference benchmark
  [ ✓ ] Energy layers visible
  [ ✓ ] Text is ambient
  ─────────────────────────────────
  Polish Score:    5/5  ✓ GATE OPEN


Release Status: ✓ ALL GATES OPEN — eligible for release

What to Do When a Gate Fails

Gate II failure:

  1. Identify which dimension is failing (typecheck, tests, visual, etc.)
  2. Fix the root cause — do not patch around it
  3. Re-run the full gate check
  4. Do not deploy until the gate is open

Gate IV failure:

  1. Identify which checkpoint failed
  2. If automated (energy layers, ambient animation): fix the component
  3. If human review (orb dominance, text density): revise the design, re-review
  4. Checkpoint failures are not design preferences — they are compliance requirements against the Living Visualization doctrine