@drawbridge/drawbridge-agents 0.1.71 → 0.1.72

package/.claude-template/agents/drawbridge-qa.md

@@ -36,6 +36,26 @@ session scratch directory that reuses the saved session
 (`drawbridge-tests/e2e/.auth/user.json`, `lib/basic-auth.js`), performs the steps, and
 screenshots after each. `drawbridge-tests/e2e/walk.js` is the pattern to copy.
 
+## How to seed an entrant (a scenario that needs a lead, an entry or a winner)
+
+Never insert a lead by hand. A hand-written lead carries subtotals the product never
+counted, and removing it afterwards drives the campaign's Entries and Submissions below zero
+(Asana 1218811920761541). Seed the way the product does, through
+`drawbridge-tests/lib/seed.js`:
+
+```js
+const { removeEntrant, seedEntrant } = require( './lib/seed' );
+
+const seeded = await seedEntrant({ campaign : '<campaign id>', email : 'qa+<task id>@…', entries : 1 });
+// … walk the scenario; seeded.lead, seeded.entry, seeded.submission are the ids …
+await removeEntrant( seeded );
+```
+
+It writes a zero-count lead plus one pending submission and waits for the sync worker to
+process it, exactly as a share-page submission does; removing it nets every counter back to
+zero. If a scenario needs something the helper cannot seed, the scenario is `blocked` with
+that as the reason, never seeded by hand.
+
 ## How to check an inbox (`@inbox` scenarios)
 
 The connected Gmail account is the QA mailbox. Trigger the email with a recipient of the form

package/conventions/cross-repo-contracts.md

@@ -242,6 +242,13 @@ skill) so it stops living only in tribal memory.
   breaks the audit. Detail: drawbridge-docs `reference/billing.md`.
 - Every `$inc` on a `totals.*` counter needs a matching entry in `drawbridge-sync/lib/totals.js`
   `SOURCES` — that map is the only drift backstop.
+- **A count never reads below zero.** Every decrement of a `totals.*` counter goes through
+  `drawbridge-sync/lib/totals.js` `adjustTotals` / `flooredTotals`, a pipeline update that clamps
+  each field at zero in the same write. A bare `$inc` with a negative delta, or a `{ $gt : 0 }`
+  query guard that skips the whole write, is the shape that drove a campaign to Entries -5
+  (Asana 1218811920761541). Test data is seeded through `drawbridge-tests/lib/seed.js` so the
+  worker does the counting; a lead inserted by hand with subtotals was never counted and its
+  delete decrements what was never added.
 - The `invoice` collection's **unique partial index on `stripeInvoiceId`** (drawbridge-api
   `schema/invoice.js`) and sync's `upsertInvoice` E11000 catch (`lib/buffer.js`) are one contract:
   sync upserts the same invoice from three concurrent webhooks (finalized/payment_succeeded/voided)

package/conventions/walk-the-app.md

@@ -66,6 +66,26 @@ write the comment from what is on it. Quote labels from the printed list, never
 The full smoke pack (`npm test`) and the dashboard functional run (`npm run dashboard`)
 use the same session; see `drawbridge-tests/readme.md`.
 
+### Seeding an entrant for a walk
+
+A walk that needs a lead, an entry or a winner seeds it through
+`drawbridge-tests/lib/seed.js`, never with a hand-written `insertOne`:
+
+```js
+const { removeEntrant, seedEntrant } = require( './lib/seed' );
+
+const seeded = await seedEntrant({ campaign : '<campaign id>', email : 'walk+<date>@…', entries : 1 });
+await removeEntrant( seeded );   // when the walk is done
+```
+
+`seedEntrant` writes what the api's thin ingest writes — a zero-count lead and one submission
+flagged pending — and waits for the sync worker to materialize the entries and every counter.
+`removeEntrant` deletes the draws that picked the lead and then the lead; sync's cascade does
+the rest and each counter nets back to zero. A lead inserted with its subtotals filled in was
+never counted on its campaign, so deleting it decremented Entries and Submissions below zero
+(Asana 1218811920761541, 2026-09-23). Counters now floor at zero in sync, but the seed still
+has to go through the worker or the counts on the walked screen are wrong.
+
 ## 2. Claude in Chrome (optional, interactive sessions only)
 
 Claude Code can drive the developer's own Chrome through the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.71",
+  "version": "0.1.72",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {