Superspec TDD (Mechanical Enforcement)

Superspec TDD (Mechanical Enforcement)

Iron Law

NO PRODUCTION CODE BEFORE A VERIFIED FAILING TEST.

Task Tags

• [TDD][RED]
• [TDD][VERIFY_RED]
• [TDD][GREEN]
• [TDD][VERIFY_GREEN]
• [TDD][REFACTOR]
• [NON-TDD][DO]
• [NON-TDD][VERIFY]

Allowed [NON-TDD] Scope (ONLY)

• docs-only
• config-only (no behavior change)
• generated outputs
• formatting/​renaming only

Core Principle

If you didn't watch the test fail, you don't know if it tests the right thing.

Gates (non-negotiable)

• A task line with [TDD][GREEN] MUST NOT be executed unless its corresponding [TDD][VERIFY_RED] task for the same Scenario is completed.
• A [NON-TDD][DO] task MUST NOT be executed unless there is a corresponding [NON-TDD][VERIFY] task line.

VERIFY_RED Decision Table (zero-decision)

A [TDD][VERIFY_RED] task MUST result in exactly one of these outcomes:

• PASS: STOP. The test is not proving missing behavior. Fix the test/​spec/​Test Obligation. Do not write production code.
• ERROR (test runner/​config/​typo): STOP. Fix the error and re-run until it FAILs for the expected reason.
• FAIL: Continue only if output contains the required Expected (RED) substring.

VERIFY_GREEN Decision Table (zero-decision)

A [TDD][VERIFY_GREEN] task MUST result in exactly one of these outcomes:

• PASS: Continue.
• FAIL: Fix production code (not the test).
• Other tests failing: STOP and fix until all relevant tests are green.

REFACTOR Rule

• [TDD][REFACTOR] is allowed only after [TDD][VERIFY_GREEN].
• After refactor, re-run the same Verify Command and confirm it still passes.

[NON-TDD] Verification Rule

• A [NON-TDD][VERIFY] step MUST be mechanical (command output / file existence / openspec validate --all --json), not a manual check.
• If you cannot express verification as a command or deterministic check, this is not [NON-TDD].

When Stuck (zero-decision)

• Don't know how to test: the contract is unclear. Update specs/​**/​spec.md Test Obligation and/​or design.md Test Commands.
• Test setup is huge: simplify the contract or split the Scenario.
• Must mock everything: code is too coupled. Stop and revise design boundaries.

Strict Prohibitions

• NEVER test mock behavior.
• NEVER add test-only methods to production code.
• NEVER mock without understanding dependency side effects.

Reference: references/​testing-anti-patterns.md