implementation-tdd · diff
v1.0.0 to v1.0.0
1 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: implementation-tdd
version: 1.0.0
description: Strict one-ticket TDD for implementation work — lock the Verification-command before editing, drive red-green at the highest meaningful seam production traffic actually uses, and prove the provider failure modes (duplicate and out-of-order delivery, replay, partial failure, forged payloads, wrong-tenant access) rather than assuming them. Use when implementing a Coding ticket, and whenever the change touches an external provider, a queue, a signed webhook, a billing or provisioning lifecycle, persistence, or auth.
recommended: false
---
# implementation-tdd
One ticket. Gate first. Real seams. The tests that matter are the ones that fail
for the reason production would.
Plain logic bugs are the easy half. Anything crossing a network fails in ways a
unit test of your own code never surfaces: the same event arrives twice, out of
order, forged, or three days late. Both halves run through the same loop below.
## Step 1 — Lock the gate BEFORE editing
Take the ticket's `Verification-command` verbatim. Then:
1. **Run it before any change.** You need to know whether it was already green,
already red, or doesn't run at all.
2. If it doesn't run (missing harness, wrong path, no such script) — that's a
**ticket defect**. Fix the command with the user's agreement *before*
treating it as the done-definition, and note the correction on the ticket.
3. If the ticket has no command, derive one and get it agreed. Do not invent a
private definition of done.
Once locked, the gate does not move to accommodate your implementation. If the
gate is wrong, you change it deliberately and say so — you never quietly relax it.
## Step 2 — Red at the highest meaningful seam
Write the failing test at the **outermost seam that still fails fast and
specifically**:
- Prefer a real domain, service, or API boundary over a unit test of a private helper.
- The test must exercise the seam **production traffic actually uses**. A test
against a path the app never takes proves nothing — this is the single most
common false-green in this pipeline.
- Watch the test fail. A test that passes before you write the code tests nothing.
- Assert on **anchored tokens**, not substrings. `not.toContain("9.99")` breaks
against `"119.99"`.
Cover the corners the ticket's invariants imply, not just the happy path:
malformed, empty, oversized, concurrent, hostile input; dependency down, slow, or
rate-limited; wrong-tenant and unauthorized access.
## Step 3 — Green with the smallest correct change
- Smallest change that makes the test pass honestly.
- **No opportunistic rewrites** tangled into the ticket.
- Preserve the codebase's domain vocabulary and module boundaries — if the ticket
forces you to violate one, that's a bounce-worthy finding, not a thing to
quietly do.
- Scope is **one ticket**. Discoveries outside it become follow-up tickets, not
extra diff.
## Step 4 — Seams for anything crossing a network or costing money
- Put the provider behind a **seam the production path uses too** — inject the
client. Monkeypatching the module under test creates a green suite over a
broken app.
- Tests use a **fake with a contract test** against the provider's documented
behavior, not an ad-hoc mock that returns whatever makes the test pass. Mocking
the thing you are testing produces a tautology.
- **Live provider calls cost money and are separately authorized.** Default test
runs must never hit a paid API. If a contract test needs live access, gate it
behind an explicit environment flag and say so on the ticket.
- Record the provider's real error shapes (rate limit, auth failure, 5xx) and
test your handling of each: retried, surfaced, or degraded — the ticket's
invariants say which.
Idempotency, retry, timeout, and signature verification are **invariants to
test**, not implementation details to assume.
## Step 5 — The four provider hazard classes
Write a red test for whichever of these the ticket touches. They are failure
modes, not features, so nothing else in the suite will catch them.
### Queues and delivery semantics
- **At-least-once is the default.** Assume duplicates. Test that processing the
same message twice produces one effect.
- **Order is not guaranteed.** Test out-of-order arrival explicitly — an
`updated` event landing before its `created`.
- **Partial failure.** What happens when step 2 of 3 throws? Test that you don't
leave a half-applied state.
- **Poison messages.** A permanently-failing message must not block the queue
forever. Test the dead-letter path.
### Signed webhooks
- **Verify the signature before parsing the body.** Test that an invalid
signature is rejected *and* that nothing was written.
- **Test a forged payload with a valid-looking shape.** Signature checks
accidentally skipped in one branch are common.
- **Timestamp and replay window.** Test that an old-but-correctly-signed payload
is rejected.
- **Raw body handling.** Frameworks that re-serialize JSON break HMAC
verification. Test against the raw bytes.
- **Never log the signing secret** or a full payload carrying PII.
### Idempotent lifecycle
- Every state-changing operation needs an **idempotency key** and a test that
replaying it is a no-op.
- Test the **full lifecycle path** — created, updated, canceled, refunded —
including terminal-state transitions that must be rejected.
- Test that a **retry after a timeout**, where the provider succeeded but you
never saw the response, doesn't double-charge or double-provision. Money and
provisioning are the classic cases: a duplicate is not a cosmetic bug.
### Owned artifacts
- Assert ownership and tenancy on every read *and* write. Test **wrong-tenant
access explicitly** — this is the invariant most often assumed and least often
tested.
- Test lifecycle: orphaned artifacts, cleanup, and what happens when the
provider's copy disappears.
- Signed URLs: test expiry and scope.
## Step 6 — Refactor under green
Only with the gate green. Behavior unchanged. Re-run after.
## Step 7 — Native checks and the final gate
In this order:
```
typecheck → lint → build (if applicable) → the locked gate → proportional broader suite
```
The gate must be re-run **after the final edit**. A gate run three edits ago is
not evidence. Paste the output verbatim.
Sweep for junk before finishing: duplicate `file 2.ts` artifacts, stray console
logs, commented-out code, a `.only` left on a test.
## Step 8 — Evidence
```
Implemented <owner>/<repo>#<issue-number>.
Paths: <list>
Gate: `<cmd>`
Output:
<verbatim>
Native checks: typecheck ✅ lint ✅ build ✅
Broader: `<cmd>` → pass
Commit: <sha>
Invariants: <held / unproven>
```
## Invariants a provider ticket must pin
State these concretely on the ticket before implementing, because each one is a
test you owe:
- Timeout and retry policy — counts, backoff, ceiling
- What the user sees when the provider is down, slow, or rate-limited
- The idempotency guarantee and its key
- Signature verification requirement
- Tenancy boundary
- Whether any test path may spend money
"Handles errors gracefully" is not an invariant. `On 429, retry 3× with
exponential backoff to 8s, then surface a retryable error to the caller` is.
## Verification checklist
```
- [ ] Gate locked and run before the first edit, re-run after the last
- [ ] Every new behavior had a failing test first
- [ ] The test drives the seam production traffic uses
- [ ] Duplicate delivery test (exactly-once effect)
- [ ] Out-of-order delivery test
- [ ] Partial-failure test — no half-applied state
- [ ] Invalid signature rejected AND no side effect written
- [ ] Replay and timestamp window enforced
- [ ] Idempotent retry proven for every money or provisioning operation
- [ ] Wrong-tenant access denied
- [ ] Provider-down and rate-limited behavior match the stated invariant
- [ ] No test hits a paid API without explicit authorization
- [ ] typecheck, lint, build clean
```
## Non-negotiables
- One ticket per run.
- Gate locked before the first edit, re-run after the last.
- Red before green, or a stated justified exception.
- Test the production seam, not a parallel fake path.
- Never claim a command passed without running it.
- Unrelated dirty files are sacred — stage only ticket-owned paths.
- Nothing written outside the repository under work.
## Related
- `invariant-evidence-review` · `codebase-audit` · `shared-worktree-safety` · `controlled-ticket-delivery`
+ `audit` · `subagent-delegation` · `delivery-constraints`