# Verify Rules (VRF-*) + Integration Rules (INT-*)

## VRF-001: TDD Red Phase
**Severity:** MUST
**Description:** Before writing implementation, write a test that asserts expected behavior. The test MUST fail on first run.
**Valid:** `pytest apps/backend/tests/unit/test_auth.py -k test_login` → FAILED.
**Invalid:** Test passes on first run.

## VRF-002: TDD Green Phase
**Severity:** MUST
**Description:** Write the minimum code needed to make the test pass. No premature abstraction.
**Valid:** Only the code path required by the test is implemented.
**Invalid:** Adding database, caching, or logging before the test requires it.

## VRF-003: TDD Refactor Phase
**Severity:** MUST
**Description:** After tests pass, refactor to improve code quality while keeping ALL tests green.
**Valid:** `pytest --cov --cov-fail-under=80` → all pass.
**Invalid:** Behavior change during refactoring.

## VRF-004: BDD Scenario Pass Gate
**Severity:** MUST
**Description:** ALL BDD scenarios MUST pass at every required layer before marking complete.
**Valid:** `pytest-bdd apps/{component}/features/ --verbose` → all pass.
**Invalid:** Any failing BDD scenario.

## VRF-005: Quality Gate Backpressure
**Severity:** MUST
**Description:** On every unit completion, ALL gates must pass: coverage ≥80%, BDD 100%, 0 vulns, no TODO.
**Valid:** `pytest --cov --cov-fail-under=80 && bandit -r src/ -q && ! grep -rn "TODO" src/`
**Invalid:** Any single gate fails.

## VRF-006: Test Layer Correctness
**Severity:** MUST
**Description:** Each BDD scenario MUST be tested at the layer the plan specified. Cross-stack ≠ unit.
**Valid:** Cross-stack scenarios in `tests/cross-stack/` against STACK_URL.
**Invalid:** Cross-stack scenario implemented as mocked unit test.

## INT-001: Contract as Source of Truth
**Severity:** MUST
**Description:** All cross-component APIs and events MUST be defined in `contracts/` (OpenAPI/AsyncAPI/GraphQL) and tagged with `INT-FR-*`.
**Valid:** `contracts/api/auth.yaml` defines POST /auth/login; components use generated types.
**Invalid:** Duplicate hand-written types across components with no contract file.

## INT-002: Backward-Compatibility by Default
**Severity:** MUST
**Description:** Contract changes MUST be backward-compatible. Breaking = field removed, type changed, status code changed, required field added. BLOCKED until human approves MAJOR bump + CHANGELOG entry.
**Valid:** Adding a new optional field (MINOR).
**Invalid:** Removing a field without human approval.

## INT-003: Generated Shared Types
**Severity:** MUST
**Description:** `packages/shared/` generated from `contracts/`. Component code MUST import from shared.
**Valid:** `git diff --exit-code packages/shared/` → clean after generation.
**Invalid:** Hand-edited files under `packages/shared/`.

## INT-004: Contract Tests at INT FR Level
**Severity:** MUST
**Description:** Every `INT-FR-*` MUST have contract tests in `tests/contract/` verifying schema.
**Valid:** Provider-agnostic contract tests using generated shared types.
**Invalid:** Contract tests calling real production backend.

## INT-005: Cross-Stack Feature Coverage
**Severity:** MUST
**Description:** Every `INT-FR-*` MUST have ≥3 scenarios in `features/cross-stack/` implemented in `tests/cross-stack/`.
**Valid:** Cross-stack scenarios running against unified STACK_URL.
**Invalid:** INT-FR without cross-stack feature file.

## INT-006: Contract Diff Artifact
**Severity:** MUST
**Description:** Every contract change MUST produce `openspec/changes/{id}/contract-diff.md`.
**Valid:** Generated by `tools/contract_diff.py` with added/removed/changed fields.
**Invalid:** Contract change merged without contract-diff.md.
