AI Wrote the Code. Now Prove It.

An abstract verification pipeline with three completed gates

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 build

The three test commands are the CI gate commands from the test package:

npm run test:unit
npm run test:integration
npm run test:e2e

All 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 uncertainty

The 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.