Quality-First TDD

Priority: P0 (CRITICAL)

A passing test is insufficient; the test must prove an owned behavior and a distinct plausible fault.

Choose the mode

• New behavior: strict RED -> GREEN -> REFACTOR. Do not write production code before the expected RED. If implementation preceded tests, report original RED as NOT RUN; never manufacture fake RED by deleting guards or falsifying logs.
• Legacy or bug fix: characterize only when needed, then reproduce the intended change as a failing regression (RED). Frozen old-revision proof against a pre-repair snapshot is valid regression evidence when explicitly labeled as frozen_snapshot_red. Preserve unrelated existing code; do not delete it merely because it predates the test.

Before writing a test

Compare against the existing suite before adding or removing cases. Ensure the scenario is not already covered upstream or in nearby layers. Preserve justified cross-layer tests when layers catch distinct regression risks.

Create one Test Intent Record per behavior/risk (see references/quality-contract.md for schema):

• id: unique stable intent identifier
• requirements: traceable requirement IDs (at least one)
• owner: accountable owner
• contract: observable contract, application-owned result or outward side effect
• fault: distinct plausible fault this test catches (risk-sensitive, not blanket mutation quota)
• layer: smallest honest layer (unit, integration, contract, e2e)
• cases: minimal distinct equivalence classes; use a parameterized test for equivalent inputs
• command: exact focused single-run command
• oracle: independent oracle ref (path + sha256), basis (approved_requirement, external_specification, independently_reviewed_example), owner, and rationale; never copied solely from implementation
• boundaries: explicit real vs mocked boundaries with justification