@drawbridge/drawbridge-agents 0.1.71 → 0.1.74

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/.claude-template/skills/drawbridge-feature/SKILL.md

@@ -30,6 +30,17 @@ check refuses a touched story that fails it. The QA agent in step 5 checks exact
 reads the mailbox for `@inbox`, and fails an untagged scenario that names nothing visible. Get
 Darren's yes on the story before step 2.
 
+**List every way the change is undone, before the questions.** Name each state the change
+writes (a row, a status, a vendor record, a counter) and each way a person or the system
+reverses it: resubscribe, START, disconnect, unpublish, a row deleted, a segment left. For
+each one, write down what else has to follow the reversal, such as connected apps or
+counters, and give it a scenario. If nothing can reverse it, tag the scenario `@one-way`.
+This list goes at the top of the numbered list Darren reads. `check-stories` refuses a When
+whose undo has no scenario in the domain folder. `check-streams` refuses a sync stream that
+handles a write and says nothing about a delete. Darren, 2026-09-24: the opt-out fix carried
+an unsubscribe to Mailchimp and never asked what a Resubscribe does, so people who opted
+back in stayed unsubscribed.
+
 **Ask for the access QA will need, in the same numbered list.** Walk the scenarios you just
 wrote and name what the QA agent must reach to check them: a screen on dev (nothing to ask),
 an inbox (`@inbox`: the connected Gmail mailbox with a `+<task id>` tag, or a shared box such

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)
@@ -593,8 +600,8 @@ api's identity/organization routes); the merged keys keep the old names. Reading
 - **No Shopify webhook reaches the embedded app.** Every `[[webhooks.subscriptions]]` in
   drawbridge-shopify-app's `shopify.app.*.toml` — `app/uninstalled` included — is delivered to
   drawbridge-webhooks (`route/shopify.js`, topic-agnostic → `buffer` doc), which drawbridge-sync
-  consumes (`lib/buffer.js` `shopify.app/uninstalled` → delete connections, hard-delete the `shop`
-  record). So `app/routes/webhooks.app.uninstalled.tsx` is unreachable and **nothing in the
+  consumes (`lib/buffer.js` `shopify.app/uninstalled` → delete connections, hard-delete the store's
+  `install` record). So `app/routes/webhooks.app.uninstalled.tsx` is unreachable and **nothing in the
   embedded app may hold per-shop state that needs invalidating on uninstall** — no memo, no cache,
   no "already done" set. Violated once: `ensureChannel` cached "this shop is bound to our channel
   spec" in a process-local Set cleared only by that dead route, so uninstall → reinstall skipped
@@ -616,7 +623,8 @@ api's identity/organization routes); the merged keys keep the old names. Reading
   `extend.organization({ connections : true })` (org GET + org menu opt in via
   `hasOrganizationAccess`); app-web's `hasConnection` helper (`lib/helpers.js`) and api's
   `lib/tasks.js connectionErrors` read it. Two invariants: the lookup's `$project`
-  (id/slug/status/title/shop/errors) is a **security boundary** — the org response spreads to the
+  (id/slug/status/install/source/errors; `group` and `title` are added after from the manifest
+  registry, not the row) is a **security boundary** — the org response spreads to the
   browser, so adding a credential field ships connection tokens to every dashboard user; and api
   deploys before app-web — the gate treats a missing field as "no connection" and silently hides
   connection-gated UI (e.g. the campaign Shop product columns row).

package/conventions/testing.md

@@ -17,6 +17,14 @@ Full strategy, conventions, and per-repo coverage map live in
   export is a silent-undefined production throw — this has happened); every
   fixed production incident gets a same-day regression test naming the
   incident.
+- **A test per state, not per ticket.** A handler that branches on a status
+  field or on a row's presence gets a case per value it can meet: each status,
+  the row absent, and the other side's timing (a cascade that runs before the
+  worker, a job that runs after the delete). Darren, 2026-09-24, after a fix
+  tested only the ticket's case and left the pending-submission case wrong.
+- **A changed handler ships with a changed test.** The end-of-turn check
+  refuses a turn that changed `stream/`, `queue/`, `route/` or `lib/` source
+  with no `test/*.test.js` changed alongside it in that repo.
 - **Next.js apps get pure-logic tests only** — no jsdom/component testing; UI
   correctness is the smoke pack's job. Extract a pure seam into `lib/` rather
   than importing a react/next module into a test.

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/hooks/drift-check.js

@@ -49,6 +49,18 @@ const changedFiles = (cwd) => {
   }
 }
 
+// A CHANGED HANDLER SHIPS WITH A CHANGED TEST. The four directories are the
+// ones a unit test can pin (conventions/testing.md); a Next.js page has none by
+// convention. Darren, 2026-09-24: "every surface has required tests."
+const TESTED_DIRS = /\/(stream|queue|route|lib)\/[^/]+\.(js|mjs|cjs|ts)$/
+const TEST_FILE = /\/test\/.+\.test\.(js|mjs|cjs|ts)$/
+
+const untestedSource = (changed) => {
+  const files = changed.map((file) => file.split(path.sep).join('/'))
+  if (files.some((file) => TEST_FILE.test(file))) return []
+  return files.filter((file) => TESTED_DIRS.test(file) && !file.split('/').some((part) => part === '.claude' || part === 'node_modules'))
+}
+
 const run = () => {
   const input = readStdin()
 
@@ -98,6 +110,25 @@ const run = () => {
     }
   }
 
+  // 1c. The reverse direction (blocking) — a sync stream changed this turn that
+  //     reacts to a write must say what a delete of that row does. The opt-out
+  //     resync handled the insert and never the Resubscribe that deletes it.
+  const checkStreams = path.join(resolvePackageRoot(cwd), 'scripts', 'check-streams.js')
+  if (fs.existsSync(checkStreams)) {
+    try {
+      execFileSync('node', [ checkStreams, ...changedSource ], { cwd, encoding: 'utf8', stdio: 'pipe' })
+    } catch (error) {
+      const detail = ((error.stdout || '') + (error.stderr || '')).trim()
+      block(`A sync stream changed this turn reacts to a write and never says what happens when that row is deleted.\n${ detail }\nAdd the delete handler (and the story scenario for the undo), or a // ONE-WAY: comment saying why a delete needs nothing, before finishing.`)
+    }
+  }
+
+  // 1d. A changed handler ships with a changed test (blocking). See untestedSource.
+  const untested = untestedSource(changed)
+  if (untested.length) {
+    block(`Source changed with no test changed alongside it:\n${ untested.map((file) => '  ' + path.relative(cwd, file)).join('\n') }\nAdd or extend a test/*.test.js in this repo, one case per state the change can meet (each status value, the row absent, the other side's timing), before finishing.`)
+  }
+
   const skipGraph = process.env.DRAWBRIDGE_SKIP_GRAPHIFY === '1'
 
   // 2. Graph freshness (non-blocking nudge) — a full re-extract is expensive, so alert rather
@@ -145,9 +176,13 @@ const run = () => {
   process.exit(0)
 }
 
-try {
-  run()
-} catch (error) {
-  // Never fail a user's turn because of a hook bug.
-  process.exit(0)
+module.exports = { untestedSource }
+
+if (require.main === module) {
+  try {
+    run()
+  } catch (error) {
+    // Never fail a user's turn because of a hook bug.
+    process.exit(0)
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.71",
+  "version": "0.1.74",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -15,7 +15,8 @@
     "drawbridge-agents-sync": "bin/sync-claude.js",
     "drawbridge-agents-graph": "bin/graph.js",
     "drawbridge-agents-check-docs": "scripts/check-doc-links.js",
-    "drawbridge-agents-check-stories": "scripts/check-stories.js"
+    "drawbridge-agents-check-stories": "scripts/check-stories.js",
+    "drawbridge-agents-check-streams": "scripts/check-streams.js"
   },
   "files": [
     "claude",

package/scripts/check-stories.js

@@ -21,6 +21,23 @@ const path = require('path')
 const TAGS = new Set([ '@inbox', '@sms', '@offscreen' ])
 const VISIBLE = /\*\*[^*]+\*\*|"[^"]+"|“[^”]+”/
 
+// EVERY ACTION THAT CAN BE UNDONE HAS ITS UNDO IN THE STORY. A scenario whose
+// When does one side of a pair below needs a scenario in the same domain folder
+// whose When does the other side, or the tag @one-way on the line above it (the
+// action genuinely cannot be undone). Darren, 2026-09-24: the opt-out story
+// said connected apps learn about an unsubscribe and never asked what a
+// Resubscribe does, so Mailchimp kept people unsubscribed after they opted
+// back in. Matched on When lines only, whole words, both directions.
+const UNDO = [
+  [ /\bunsubscrib/i, /\bresubscrib/i, 'unsubscribe', 'resubscribe' ],
+  [ /\bconnect(s|ed|ing)?\b/i, /\bdisconnect/i, 'connect', 'disconnect' ],
+  [ /\bSTOP\b/, /\bSTART\b/, 'STOP', 'START' ],
+  [ /\bpublish(es|ed|ing)?\b/i, /\bunpublish/i, 'publish', 'unpublish' ],
+  [ /\bpaus(e|es|ed|ing)\b/i, /\bresum(e|es|ed|ing)\b/i, 'pause', 'resume' ],
+  [ /\benabl(e|es|ed|ing)\b/i, /\bdisabl(e|es|ed|ing)\b/i, 'enable', 'disable' ],
+  [ /\barchiv(e|es|ed|ing)\b/i, /\b(unarchiv|restor)/i, 'archive', 'restore' ]
+]
+
 const findFamilyRoot = () => {
   let dir = process.env.INIT_CWD || process.cwd()
   for (let i = 0; i < 8; i++) {
@@ -41,8 +58,10 @@ const walk = (dir, out = []) => {
   return out
 }
 
-// Returns [{ line, name, reason }] for one story file.
-const checkStory = (text) => {
+// Returns [{ line, name, reason }] for one story file. `siblings` are the other
+// story texts in the same domain folder: an undo written up in a sibling story
+// (connect here, disconnect in the lifecycle story) counts.
+const checkStory = (text, siblings = []) => {
   const problems = []
   const lines = text.split('\n')
   let scenario = null
@@ -55,7 +74,9 @@ const checkStory = (text) => {
     scenario = null
   }
 
+  const scenarios = []
   let pendingTag = false
+  let pendingOneWay = false
   lines.forEach((raw, index) => {
     const line = raw.trim()
     if (line.startsWith('```')) {
@@ -64,23 +85,41 @@ const checkStory = (text) => {
       if (!inFence) flush()
       return
     }
-    if (/^#/.test(line)) { flush(); pendingTag = false; return }
+    if (/^#/.test(line)) { flush(); pendingTag = false; pendingOneWay = false; return }
     if (/^@\w/.test(line)) {
-      pendingTag = line.split(/\s+/).some((tag) => TAGS.has(tag))
+      const tags = line.split(/\s+/)
+      pendingTag = tags.some((tag) => TAGS.has(tag))
+      pendingOneWay = tags.includes('@one-way')
       return
     }
     if (/^Scenario( Outline)?:/.test(line)) {
       flush()
-      scenario = { line: index + 1, name: line, hasThen: false, visible: false, tagged: pendingTag }
+      scenario = { line: index + 1, name: line, hasThen: false, visible: false, tagged: pendingTag, oneWay: pendingOneWay, when: '' }
+      scenarios.push(scenario)
       pendingTag = false
+      pendingOneWay = false
       return
     }
     if (!scenario) return
+    if (/^When\b/.test(line)) scenario.when += ' ' + line
     if (/^Then\b/.test(line)) scenario.hasThen = true
     if (/^(Then|And|But)\b/.test(line) && VISIBLE.test(line)) scenario.visible = true
   })
   flush()
-  return problems
+
+  const elsewhere = siblings.join('\n').split('\n').filter((line) => /^\s*When\b/.test(line)).join('\n')
+  for (const each of scenarios) {
+    if (each.oneWay) continue
+    for (const [ left, right, leftName, rightName ] of UNDO) {
+      for (const [ does, undoes, undoName ] of [ [ left, right, rightName ], [ right, left, leftName ] ]) {
+        if (!does.test(each.when)) continue
+        if (scenarios.some((other) => undoes.test(other.when)) || undoes.test(elsewhere)) continue
+        problems.push({ line: each.line, name: each.name, reason: `can be undone (${ undoName }) and no scenario's When does that; add the scenario, including what else must follow the undo, or tag this one @one-way` })
+      }
+    }
+  }
+
+  return problems.sort((a, b) => a.line - b.line)
 }
 
 const main = () => {
@@ -97,7 +136,9 @@ const main = () => {
   let count = 0
   for (const file of files) {
     if (!fs.existsSync(file)) continue
-    for (const problem of checkStory(fs.readFileSync(file, 'utf8'))) {
+    const folder = path.dirname(file)
+    const siblings = fs.readdirSync(folder).filter((name) => name.endsWith('.md') && path.join(folder, name) !== file).map((name) => fs.readFileSync(path.join(folder, name), 'utf8'))
+    for (const problem of checkStory(fs.readFileSync(file, 'utf8'), siblings)) {
       count += 1
       console.error(`  ${ path.relative(familyRoot, file) }:${ problem.line }  ${ problem.name }  — ${ problem.reason }`)
     }

package/scripts/check-streams.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// A sync stream that reacts to a row being written must say what happens when
+// that row is deleted: a `delete` handler, or a comment starting `ONE-WAY:`
+// that says why a delete needs nothing. Darren, 2026-09-24: stream/suppression.js
+// carried an opt-out to Mailchimp on insert and had no delete, so a person who
+// pressed Resubscribe (which deletes the row) stayed unsubscribed there.
+//
+// Usage: node scripts/check-streams.js <file ...>   Only drawbridge-sync
+// stream/*.js files are checked; stream/index.js is the router, not a handler.
+// Exits 1 naming each file that fails.
+const fs = require('fs')
+
+const STREAM = /\/drawbridge-sync[^/]*\/stream\/(?!index\.js$)[^/]+\.js$/
+
+// Returns a reason string, or null when the file passes.
+const checkStream = (text) => {
+  const writes = /^\s*(insert|update)\s*:/m.test(text)
+  if (!writes) return null
+  if (/^\s*delete\s*:/m.test(text)) return null
+  if (/\/\/\s*ONE-WAY:/.test(text)) return null
+  return 'handles a write but not a delete; add a `delete` handler, or a `// ONE-WAY:` comment saying why a deleted row needs nothing'
+}
+
+const main = () => {
+  const files = process.argv.slice(2).filter((file) => STREAM.test(file.split('\\').join('/')) && fs.existsSync(file))
+  let count = 0
+  for (const file of files) {
+    const reason = checkStream(fs.readFileSync(file, 'utf8'))
+    if (reason) {
+      count += 1
+      console.error(`  ${ file }  — ${ reason }`)
+    }
+  }
+  if (count) {
+    console.error(`drawbridge-agents-check-streams: ${ count } stream(s) never say what a delete does`)
+    process.exit(1)
+  }
+  console.log(`drawbridge-agents-check-streams: every stream says what a delete does (${ files.length } file(s))`)
+}
+
+module.exports = { STREAM, checkStream }
+
+if (require.main === module) main()