The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.
Junk classes, retention bar, marks
One table for three jobs: writing a test (programming), cleaning a branch (remove-ai-slops), and auditing a suite. A test that matches a class below is junk unless the retention bar keeps it. The gate reviewer applies the same table; a test that would be deleted in review is a test not to write.
Marks (one per test declaration; one per row when table rows differ)
| Mark | Meaning | What the ledger line names |
|---|---|---|
R retain |
guards a contract | the contract and the regression it catches |
F fix |
real contract, weak assertion (a negative that passes when only one of several items is missing; toBeTruthy on a value that is always an object; a lower bound over independently removable items) |
the repaired assertion |
C consolidate |
the assertion moves into a keeper (a table row in a sibling, a stronger boundary suite); the declaration disappears | the keeper |
D delete |
no contract, or another test owns it | the owner test that still fails on the regression, or why no contract exists; plus a proof receipt |
Junk classes (candidates for D or C)
| Class | What it looks like | Proof that it is junk |
|---|---|---|
| Cannot fail | no assertion; expect(x).toBe(x); expected value computed by the code under test; assert result is not None and nothing else; an override fixture equal to its fallback; assertion inside a callback that never runs |
a mutation of the owner the test survives |
| Change certificate | pins the diff, not a behavior: a constant, a string, a rename, a call, the shape of the edit the PR made | revert the change: the test fails for the diff, not for a regression; the run is the proof |
| Mock echo | the mock returns the value the test then asserts; the behavior lives in the mock | mutate the owner: test stays green |
| Implementation mirror | asserts call order, call count, private helper args, bracket-notation access to private members, internal state shape that a behavior-preserving refactor would break | a keeper at the real boundary catches the behavioral mutation |
| Prose pin | asserts wording, headings, section order, snapshots, phrase counts, or length of SKILL.md, prompts, AGENTS.md, docs, rule text |
no runtime behavior to mutate; cite the repo's prose-test rule |
| Copied inventory | a hard-coded list of exports, files, tools, keys that mirrors the source and fails only when someone edits both | a generator or freshness check or a real consumer already owns it |
| Source grep | reads a source file and greps for a string or import | an identifier-only refactor turns it red for no reason; a behavior mutation it misses |
| Duplicate contract | the same input/output asserted at two or more layers with no distinct transport or lifecycle risk; an adapter package's copy of a Core package's test | the mutation is caught by both: keep the stronger boundary |
| Layer replay | a shared helper re-tested through every wrapper that calls it | one helper owner test plus one wiring test per real wrapper |
| Seam keeper | exists to keep a test-only export, flag, getter, or reset hook alive | knip or grep shows no production caller; delete test and seam together |
| Fabricated postcondition | the fixture supplies the receipt, ordering, or stored state the owner should produce; asserts a store nothing writes | mutate the writer: test stays green |
| Capability restatement | asserts a flag or capability is true instead of the delivery it promises |
a delivery test owns it, or none exists (then F, not D) |
| Input transcript | asserts the argv, flags, URL, or request the code handed to a child, not the state the child resolved | mutate the child's handling of that input: test stays green; the witness drives the real component and asserts resolved state |
| Misnamed | the name promises a behavior its inputs never exercise | read the assertions; mark by what it actually checks |
| Near-duplicate cases | N tests differing only in input literals | C into one table (it.each / test.each, or a loop over a typed array where the package's test typings lack .each); typecheck after; every old assertion stays a row |
Retention bar (these stay R even when they match a class above)
Keep a test that independently guards a public API, SDK, RPC or app-server protocol, config schema or default, migration, storage format, security boundary, platform behavior, prompt-byte or shipped-copy equality between real artifacts, generated or cross-language contract, package or install payload, release, or architecture invariant (meta-audits, tracked-artifact audits). Say which one in the test. Also keep:
- Node-compat suites: anything that runs shipped code under real Node is a platform contract even when a Bun run covers the same assertions.
- Issue regressions: a test naming an issue number stays until another test is shown to fail on that exact regression.
- Machine-consumed text: parsed fields, sentinel tokens, tool names, schema keys, a routing-bearing fragment of a parsed frontmatter
description. - Baseline-red tests: a test that fails on the unchanged base is a product bug to fix at its owner, never a deletion.
Outside that list, a source-inspection test survives only as the cheapest independent guard of a user-facing key, byte, or path that an identifier-only refactor leaves green. Static or slow is never a reason to delete.
Proof rule for D and C
Break the production owner (flip a condition, drop a branch, return a constant, skip a write) and run the candidate and its named keeper on the unmodified test tree:
| Candidate | Keeper | Verdict |
|---|---|---|
| green | red | candidate cannot catch this: D proven |
| red | red | candidate redundant for this behavior: D or C proven |
| red | green | candidate is the ONLY proof: R, or C it into the keeper and re-run |
| green | green | the mutation missed the behavior: confirm the edit landed, then pick another mutation |
Restore the owner byte for byte; never commit a mutation. A prose pin needs no mutation: the receipt is the assertion line plus the repo rule. Coverage diffs prove lines still execute, not that anything still asserts on them; pair a coverage diff with at least one mutation per theme.