@drawbridge/drawbridge-agents 0.1.70 → 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/.claude-template/skills/drawbridge-asana-comment/SKILL.md

@@ -64,6 +64,10 @@ Write for the person reading it, not for the repo.
   the interface labels them. Not your paraphrase, not the variable name. If the button says
   Send, write Send.
 - **Quote user-facing copy exactly**, so they can match it against what is on screen.
+  Double quotes mean "one of our labels", and the comment tool refuses the post if a
+  double-quoted label was not seen by a walk in the last day (`npm run walk` in
+  drawbridge-tests) and exists nowhere in the family's source. A third-party label, a mail
+  client's button, a Shopify admin page, goes in 'single quotes' and is not checked.
 - Use their words for their bug. If they called it a prize notification, it is a prize
   notification, not a lead-facing transactional send.
 

package/.claude-template/skills/drawbridge-feature/SKILL.md

@@ -83,4 +83,4 @@ posted. The handoff comment is refused by the QA gate while this session changed
 | Reading the story and graph before coding | `hooks/consult-docs-gate.js` on the first source edit |
 | Updating the story when anchored code changed | `hooks/drift-check.js` at turn end |
 | QA on dev | `hooks/qa-gate.js` on the Asana comment |
-| Walking before naming a button | `drawbridge-asana-ship-handoff`, every quoted label from the walk output |
+| Walking before naming a button | `hooks/qa-gate.js` on every Asana comment: a "double-quoted" label must appear in a walk record from the last day or in family source |

package/README.md

@@ -45,7 +45,7 @@ hooks/
   drift-check.js            ← Stop hook (wired via .claude-template/settings.json)
   consult-docs-record.js    ← PostToolUse hook: remembers a docs page read / graph query per session
   consult-docs-gate.js      ← PreToolUse hook: refuses the first source edit until both happened
-  qa-gate.js                ← PreToolUse hook on the Asana comment tool: a session that changed code needs a clean QA report
+  qa-gate.js                ← PreToolUse hook on the Asana comment tool: every "quoted label" must have been walked or exist in source; a session that changed code needs a clean QA report
   guard-superpowers-docs.js ← PreToolUse hook: plans/specs go to drawbridge-docs
 ```
 

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/hooks/qa-gate.js

@@ -41,11 +41,10 @@ const readJson = (file) => {
   }
 }
 
-const findReport = (cwd, task) => {
+const findFamilyRoot = (cwd) => {
   let dir = cwd
   for (let depth = 0; depth < 4; depth += 1) {
-    const candidate = path.join(dir, 'drawbridge-tests', 'results', 'qa', task + '.json')
-    if (fs.existsSync(candidate)) return candidate
+    if (fs.existsSync(path.join(dir, 'drawbridge-tests'))) return dir
     const parent = path.dirname(dir)
     if (parent === dir) break
     dir = parent
@@ -53,19 +52,97 @@ const findReport = (cwd, task) => {
   return null
 }
 
+const findReport = (cwd, task) => {
+  const root = findFamilyRoot(cwd)
+  if (!root) return null
+  const candidate = path.join(root, 'drawbridge-tests', 'results', 'qa', task + '.json')
+  return fs.existsSync(candidate) ? candidate : null
+}
+
+// --- Quoted labels must have been seen -------------------------------------
+//
+// A "double-quoted" string in a comment is a label on OUR screens and is checked:
+// it must appear in a walk record from the last day (drawbridge-tests/results/walk/
+// *.json, written by npm run walk) or, failing that, in the family's source. A
+// 'single-quoted' string is a third-party label (Outlook's buttons, a Shopify
+// admin page) or spoken words, and is not checked. Darren, 2026-09-23: no more
+// "buttons or functions that don't exist".
+
+const SOURCE_REPOS = [ 'drawbridge-app-web', 'drawbridge-components', 'drawbridge-share', 'drawbridge-api', 'drawbridge-utils', 'drawbridge-shopify-app', 'drawbridge-website', 'drawbridge-emails' ]
+
+const quotedLabels = (text) => {
+  const found = new Set()
+  const re = /"([^"\n]{1,120})"|“([^”\n]{1,120})”/g
+  let match
+  while ((match = re.exec(text)) !== null) found.add((match[1] || match[2]).trim())
+  return Array.from(found).filter(Boolean)
+}
+
+const walkedLabels = (root) => {
+  const dir = path.join(root, 'drawbridge-tests', 'results', 'walk')
+  const seen = []
+  if (!fs.existsSync(dir)) return seen
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue
+    const file = path.join(dir, name)
+    try {
+      if (Date.now() - fs.statSync(file).mtimeMs > MAX_AGE_MS) continue
+      const record = JSON.parse(fs.readFileSync(file, 'utf8'))
+      for (const key of [ 'buttons', 'headings', 'inputs', 'links', 'tableHeaders', 'title' ]) {
+        const value = record[key]
+        if (Array.isArray(value)) seen.push(...value.map(String))
+        else if (typeof value === 'string') seen.push(value)
+      }
+    } catch (error) {
+      // an unreadable record proves nothing
+    }
+  }
+  return seen
+}
+
+const inSource = (root, label) => {
+  const { spawnSync } = require('child_process')
+  const dirs = SOURCE_REPOS.map((name) => path.join(root, name)).filter((dir) => fs.existsSync(dir))
+  if (!dirs.length) return false
+  const result = spawnSync('grep', [
+    '-rFq', '--include=*.js', '--include=*.jsx', '--include=*.ts', '--include=*.tsx', '--include=*.json', '--include=*.hbs', '--include=*.md',
+    '--exclude-dir=node_modules', '--exclude-dir=.next', '--exclude-dir=dist', '--exclude-dir=.git', '--exclude-dir=.claude',
+    '--', label, ...dirs
+  ], { encoding: 'utf8' })
+  return result.status === 0
+}
+
+const unseenLabels = (cwd, text) => {
+  const root = findFamilyRoot(cwd)
+  if (!root) return []
+  const labels = quotedLabels(text)
+  if (!labels.length) return []
+  const walked = walkedLabels(root).map((value) => value.toLowerCase())
+  return labels.filter((label) => {
+    const needle = label.toLowerCase()
+    if (walked.some((value) => value.includes(needle))) return false
+    return !inSource(root, label)
+  })
+}
+
 const run = () => {
   const input = readStdin()
 
   if (input.tool_name !== 'mcp__claude_ai_Asana__add_comment') process.exit(0)
   if (!input.session_id) process.exit(0)
 
+  const cwd = input.cwd || process.cwd()
+  const toolInput = input.tool_input || {}
+
+  // Every comment, code changed or not: a quoted label has to exist.
+  const unseen = unseenLabels(cwd, String(toolInput.html_text || toolInput.text || ''))
+  if (unseen.length) deny('A label in this comment was never seen: ' + unseen.map((label) => '"' + label + '"').join(', ') + '. Walk the page (npm run walk in drawbridge-tests) and quote the label as it prints, or use \'single quotes\' for a third-party label such as a mail client\'s button.')
+
   const seen = readJson(markerPath(input.session_id)) || {}
   if (!seen.edited) process.exit(0)
 
-  const task = String((input.tool_input || {}).task_id || '')
+  const task = String(toolInput.task_id || '')
   if (!task) process.exit(0)
-
-  const cwd = input.cwd || process.cwd()
   const file = findReport(cwd, task)
   const how = 'Dispatch the drawbridge-qa agent with the story file(s), task ' + task + ' and the dev organization id; it writes drawbridge-tests/results/qa/' + task + '.json. Fix every fail and run it again before commenting.'
 

package/package.json

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