AI Wrote the Code. Now Prove It.

AI can produce a clean diff, a green test suite, and a confident summary. That is not proof.
A feature is done when the evidence shows it meets the requirement that started the work. This part is a tutorial for building the test package (test-package.md) that proves Tablewait's waitlist auto-promote.
Step 1: Generate the test package from a template
Give the agent the generative prompt and the template — test-package.md is the shape to fill. Start with the AC list and name the proof each one needs. A row with no check is an assumption; a check with no row may be noise.
If you wrote some tests first, as the note on test-first describes, this part still applies. The test package maps each acceptance criterion to the tests that exist, in whatever order you wrote them.
Draft test-package.md for this feature.
Use test-package.md as the exact template: a testing plan, an AC to
evidence mapping, unit, integration and e2e test lists, edge cases,
representative snippets, CI gate commands, and an "open uncertainty"
section.
Read first:
- the approved requirements.md (AC1..AC8 are the contract)
- the implemented code and existing tests
Map every AC to a concrete test. Where you cannot prove an AC yet, list it
under open uncertainty rather than claiming coverage.The draft opens with a short testing plan, then the AC to evidence mapping:
# Test Package — Waitlist Auto-Promote
## Testing plan
Every acceptance criterion `AC1..AC8` maps to at least one executable test. Unit tests cover
selection and hold-repository invariants; integration tests cover the service transactions,
idempotency, and the expiry sweep; e2e tests cover the host→party flow and the flag-OFF path.
A criterion is only "met" when its test is green on CI.
## AC → evidence mapping
| AC | Test type | File | Owner |
| --- | --- | --- | --- |
| AC1 | integration | `promotionService.spec.ts` | implementation-agent |
| AC2 | integration | `holdActions.spec.ts` | implementation-agent |
| AC3 | integration | `holdExpirySweep.spec.ts` | implementation-agent |
| AC4 | integration | `holdActions.spec.ts` | implementation-agent |
| AC5 | integration | `concurrency.spec.ts` | test-agent |
| AC6 | unit | `selectNextParty.spec.ts` | implementation-agent |
| AC7 | e2e | `autoPromote.e2e.spec.ts` | test-agent |
| AC8 | integration | `promotionService.spec.ts` | implementation-agent |This table is the contract between the requirement and the proof.
Step 2: Make the acceptance criteria executable
Turn the product decision into a test that fails if the behaviour is wrong.
// promotionService.spec.ts — AC1 + AC8 (idempotent, exactly one active hold)
test('AC1/AC8: marking available creates exactly one active hold, retries are idempotent', async () => {
const table = await makeTable({ capacity: 4, status: 'available' });
await makeParty({ restaurantId: table.restaurantId, size: 2, status: 'waiting' });
const key = { tableId: table.id, freedAt: SERVER_NOW };
const first = await promoteNextParty(table.id, { actor: 'host', idempotencyKey: key });
const retry = await promoteNextParty(table.id, { actor: 'host', idempotencyKey: key });
expect(first.status).toBe('active');
expect(retry.id).toBe(first.id); // AC8: no second hold
const active = await holdRepo.countActiveForTable(table.id);
expect(active).toBe(1); // AC1 + AC5 invariant
});This is not a generic test. It carries two product decisions into the codebase: exactly one active hold, and a retry that creates no second one. It fails if an agent adds a convenient but incorrect shortcut.
Step 3: Prove the concurrency guarantee
AC5 is the one that matters most and is easiest to get wrong. Test it directly.
// concurrency.spec.ts — AC5 (simultaneous frees never create two active holds for one table)
test('AC5: two simultaneous frees of one table create exactly one active hold', async () => {
const table = await makeTable({ capacity: 4, status: 'available' });
await makeParty({ restaurantId: table.restaurantId, size: 2, status: 'waiting' });
// Two hosts free the same table at the same instant.
await Promise.all([
promoteNextParty(table.id, { actor: 'host', idempotencyKey: { tableId: table.id, freedAt: SERVER_NOW } }),
promoteNextParty(table.id, { actor: 'host', idempotencyKey: { tableId: table.id, freedAt: SERVER_NOW_PLUS_1S } }),
]);
expect(await holdRepo.countActiveForTable(table.id)).toBe(1); // AC5: unique partial index + row lock
});If the unique partial index and row locking from the design are missing, this test is where it shows up — not in production.
Step 4: Cover the edge cases
List the cases that break naive implementations, and test each:
- Hold expiry exactly at the boundary (
expiresAt == now()). - Party declines after expiry — expiry wins, decline is a no-op.
- Empty waitlist — table stays available, no hold, no error.
- A party on two restaurants' lists is only eligible on the relevant restaurant.
- Concurrent accept + expire on the same hold — exactly one outcome.
- Table capacity smaller than party size — skip to next fitting party.
The "expiry wins" case is the easiest to get wrong, so it gets a test of its own:
// holdExpirySweep.spec.ts — AC3 (expiry rolls to next) + "expiry wins" edge case
test('AC3: unanswered hold expires and rolls to next eligible party', async () => {
const { hold, nextParty } = await seedHoldAboutToExpire();
await advanceServerClock('5m');
await runHoldExpirySweep();
expect(await holdRepo.get(hold.id)).toMatchObject({ status: 'expired' });
const rolled = await holdRepo.activeForTable(hold.tableId);
expect(rolled.waitlistEntryId).toBe(nextParty.id); // rolled to next
// expiry wins: a late decline is a no-op
await expect(declineHold(hold.id, { actor: 'party' })).resolves.toMatchObject({ noop: true });
});Step 5: Drive the visible flow in a real browser
When the requirement includes something a user sees, run a real browser. AC7 — flag off means nothing changes — needs this.
// autoPromote.e2e.spec.ts — AC7 (flag OFF = unchanged manual flow), Playwright
test('AC7: with flag OFF, no hold is created and manual flow is unchanged', async ({ page }) => {
await setFeatureFlag('waitlist_auto_promote', false);
await loginAsHost(page);
await page.getByRole('row', { name: 'Table 7' }).getByRole('button', { name: 'Mark available' }).click();
await expect(page.getByTestId('active-hold-banner')).toHaveCount(0); // no auto-promote
await expect(page.getByTestId('manual-notify-next')).toBeVisible(); // manual path intact
});Collect the screenshot, the route, and the viewport so the browser agent's report is inspectable.
Step 6: Ask a review agent for evidence, not reassurance
Review this pull request against requirements.md.
Do not change files.
Return:
1. Each acceptance criterion with its evidence (name the test or source line).
2. Missing or weak evidence — which AC is not proven and why.
3. Scope changes not requested by the requirements.
4. Risk — mark each as block, follow-up, or no action.
Do not treat an agent summary as evidence. Read the diff and test output.The useful answer is not "looks good." It is "AC4 has no decline-after-expiry test."
Step 7: Let CI enforce the repeatable gates
# .github/workflows/verify.yml
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20, cache: npm }
- run: npm ci
- run: npm run typecheck
- run: npm run test:unit
- run: npm run test:integration
- run: npm run test:e2e
- run: npm run buildThe three test commands are the CI gate commands from the test package:
npm run test:unit
npm run test:integration
npm run test:e2eAll three must pass before wp6-acceptance-tests is marked done and before release. The pipeline above also typechecks and builds. CI runs the same commands for every pull request. It still needs the right ones. A green pipeline that never exercises the expiry sweep proves the wrong thing.
Step 8: Record the uncertainty
Some evidence will be incomplete. Say so. Record each gap, and decide whether it blocks release, needs monitoring, or is a follow-up. The Tablewait test package records two:
- Boundary test (
expiresAt == now()) depends on whether the sweep uses<=or<; design says<=(expire at the boundary) — confirm once wp4 lands. - The accept-vs-expire concurrency test is currently flaky in wp3 until DB
now()is pinned in the harness; not a product defect but it blocks a clean green.
What the finished test package looks like
Put together, the reviewed test package has nine sections, in this order:
# Test Package — Waitlist Auto-Promote
## Testing plan
## AC → evidence mapping
## Unit tests
## Integration tests
## E2E tests
## Edge cases
## Representative snippets
## CI gate commands
## Open uncertaintyThe package you just built
test-package.md — the AC→evidence map, the test lists, the edge cases, and the CI gate — now joins the pack. The next part turns this evidence into a release.
Download this stage's package (.zip) — the test package artifact and the pack README. The complete pack is linked from the series guide and the final part.


