building

Building (Code Generation + TDD)

Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.

Reference Files

Read only what's needed:

• references/testing-patterns.md — test structure, isolation, naming; load when writing the first test of a cycle or a test feels awkward to structure
• references/test-data-and-mocks.md — mock discipline, test data factories; load when a test needs fixtures/factories or you are about to mock anything
• references/integration-and-live-proof.md — integration test guidance, live verification; load when the slice crosses a service/DB/API boundary or the plan names live proof

Test Process Discipline

• Always use run mode: CI=true npm test, npx vitest run (NOT npx vitest), CI=true npx jest — watch mode never exits, so the agent hangs waiting for a prompt that never returns
• Timeout guard: timeout 60s npx vitest run if uncertain about CI=true
• After TDD cycle: pgrep -f "vitest|jest" || echo "Clean". Kill if found — orphaned watchers hold ports and re-run stale code, producing false greens in later cycles.
• IDE vs CLI truth: If CLI tests pass with exit 0, trust CLI over IDE/LSP errors (stale cache)

RED → GREEN → REFACTOR

RED — Failing Test First

Write one failing test for the current slice. Run it. RED = a behavioral failure ("X is not a function", "expected 3, received undefined") — never a bare exit code.

False-RED guard (CRITICAL): Exit 1 from an import/syntax/collection ERROR is a broken harness, not a RED — fix the harness and re-run. Record the observed failure reason verbatim.

GREEN — Minimal Code

Write the minimum code to pass the test. No extra features, no abstractions for hypothetical futures. No unrelated test breakage. If existing tests break, fix the code not the tests.

REFACTOR — Clean Up

Improve code quality while keeping tests green. If tests fail during refactor, revert — a red test proves it wasn't a refactor, and debugging forward mixes two changes. Re-run after every refactor step.