Skip to content

Test-First Evidence

Test-first development (TDD) establishes a behavioral claim before implementation, then shows that the implementation satisfies that same claim. codeArbiter’s verification workflow selects the approach appropriate to the change: regression-first repair for confirmed defects, preferably test-first feature checks, or passing characterization baselines before refactoring.

The important observation is the contrast. The test should distinguish the incorrect behavior from the required behavior. A test that only repeats an implementation detail, asserts on its own mock, or fails because its module cannot load has not yet established that contrast.

On the full feature lane, the specification and plan exist first. executing-plans passes a scope to subagent-driven-development, which chooses direct implementation or useful delegation. Verification runs inside the task using its selected approach. The implementation is checked against actual criteria, with independent or specialist review where risk or policy requires it.

The small feature lane enters TDD after its confirmed inline criteria. A confirmed fix has a regression-first entry. Refactoring has a behavior-preservation contract and must not be treated as permission to change old assertions. Those paths are not all identical to this full-feature workflow. Build a feature follows the current caller and delivery sequence.

An obligation is a verifiable claim with an ID, a source and a state. A specification criterion is one source; contract invariants and applicable security controls can add others. “Test the export” is too vague. “Preserve the input order in the output rows” is a claim a test can challenge.

Record the obligations and verification approach before changing code. Preserve agreed criteria and ask only about consequential unresolved requirements. Genuinely missing facts remain explicit; do not fill them with an invented command or expected result. Changes to the intended outcome go to their actual decision owner.

A plan references the specification’s stable criterion IDs. It does not create another independent criterion list. The artifact model explains why that ownership matters.

For a confirmed fix, reuse or add a named regression and observe it fail for the defect before repair. Test-first feature work similarly observes the intended missing behavior. Existing implementation can instead use current criterion-focused checks and meaningful negative controls. For refactors, passing characterization tests establish the baseline before restructuring. Unrelated baseline failures remain separately identified; never damage correct code to obtain RED.

For example, the saved-search fixture requires non-empty input to produce CSV text. Its baseline returns None. The recorded red output reports two failing assertions for that missing output and one passing empty-input test. This is not a demonstrated quoting-only defect: the baseline does not yet produce non-empty CSV at all.

A missing import would establish only that the test environment is incomplete. A test that never executes the target would establish even less. Diagnose those problems before describing the result as the behavioral red phase.

Implement the scoped change and run its proving checks and affected existing tests. For a regression-first fix, preserve assertions between RED and GREEN. A material fixture or setup change requires renewed target RED against the broken source. Refactors preserve the baseline’s behavioral assertions, including any characterization tests added before restructuring.

In the same fixture, the completed serializer passes all three tests with the same test-file digest. The result is useful, bounded local evidence. It does not prove a codeArbiter host session ran, a human approved the example, or another application is correct.

A green run against a weakened assertion would not establish the intended correction. “We changed the expected output to match the implementation” is a changed requirement, not a successful proof of the original one.

Review the map from claims to passing evidence. A test file can exist and still miss the seam that matters. A MISSING obligation stays outstanding until an appropriate check demonstrates it. Repair the affected work and rerun its checks; do not force every verification approach through a fictional failing-test sequence.

For security-relevant or contract-critical logic, the TDD contract dispatches coverage-auditor to challenge whether tests exercise the claimed behavior. This is a conditional role, not a universal extra author or a substitute for the later scope review.

A useful objection names the consequence: an untested export failure could deliver malformed records to a caller. A bare percentage or a generic “needs tests” comment does not identify that risk as clearly.

Phases 5 and 6: coverage and quality tools

Section titled “Phases 5 and 6: coverage and quality tools”

Coverage measures exercised lines and branches under the declared tooling and maturity rules. It does not decide that an assertion is meaningful. Both required measures must satisfy the applicable contract; a high line percentage cannot hide a failing branch measure.

Where the surface has no coverage tooling, the documented no-tooling treatment requires a citation to that actual project configuration. “The command was not found” is not equivalent to “this surface has no coverage command.” For platform-forked behavior, state what environment and any required union were measured rather than treating one host’s result as universal.

Finally, run the project-declared lint and applicable type checks. Their success is a separate quality observation. They do not replace the obligation proof or grant approval for unrelated work.

Compare the implementation with the specification and the actual output of applicable checks. Review the combined relevant change at the scope its risks warrant. Reuse observed results only while their checked source and inputs remain applicable; refresh affected evidence after changes.

Typed DONE records implementation progress, not passing tests or independent review. Return checks, limits and remaining work to the caller, which continues authorized work unless an explicitly requested pause, real decision or applicable host boundary intervenes. Ordinary progress needs no artifact acceptance receipt. Commit and PR preparation still require their own permissions and current checks; merge requires exact-head hosted CI and explicit authority.

Use Investigate and fix to work from a symptom into a regression, and Review and ship for the final handoff. The exact six-phase contract remains in tdd.

Pick one current criterion and select its proving approach. For a fix, show the target failure and unchanged assertion passing after correction. For a refactor, compare the passing baseline and resulting behavior. Name the scope, limits, review and delivery evidence still needed. That answer is more useful than an unqualified “the suite is green.”