@drawbridge/drawbridge-agents 0.1.72 → 0.1.76

package/.claude-template/skills/drawbridge-asana-comment/SKILL.md

@@ -23,8 +23,9 @@ bulleted section beside it. In order:
 1. What changed, in plain past tense. Numbered.
 2. What they need before the first step: a permission to grant, a setting to switch on, a
    record that has to exist. One item each.
-3. What to do and what to expect. One step per item, each one something they can actually do
-   or check. Every step starts with the click path from where they already are (Admin,
+3. What to do and what to expect. One step per item, one action per step (rules.md rule 9),
+   each one something they can actually do or check. "Open the campaign and click Draw" is
+   two steps. Every step starts with the click path from where they already are (Admin,
    Connections, then the store; Shopify admin, Apps, then Drawbridge). "Open the app" is not a
    path.
 4. Anything that would otherwise look wrong to them. Numbered too.

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

@@ -600,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
@@ -623,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/git-branching.md

@@ -7,7 +7,7 @@ Branches use the **full gitflow prefixes, always spelled out**. Never use abbrev
 | `feature/<name>` | New features / changes (branched from `develop`) |
 | `bugfix/<name>` | Non-urgent bug fixes |
 | `hotfix/<name>` | Urgent production fixes (branched from `main`) |
-| `release/<version>` | Release preparation |
+| `release/<asana id>` | A release (since 2026-10-21): the Releases project task id, the same id as `drawbridge-api/scripts/migration-<id>.js` and `drawbridge-docs/releases/<id>.md`; one branch per app the release touches, off `develop`, built against the Local database, merged by a developer through a pull request |
 | `chore/<name>` | Maintenance — dependency bumps, config, cleanup |
 | `support/<name>` | Long-lived support branches |
 

package/conventions/migrations.md

@@ -29,11 +29,50 @@ quietly that dev served stale code the whole time.
 
 ## How
 
-- Add the function to `drawbridge-api/scripts.js`, alongside the others.
-- Add a commented invocation to the numbered run-list at the bottom. Nothing runs
-  until somebody uncomments a line and deploys.
-- Take `dryRun` and report what it would do. The first run of a migration is a
-  read.
+- One release has at most one migration file,
+  `drawbridge-api/scripts/migration-<release asana id>.js`, named for the
+  RELEASE task (the same id as the `release/<id>` branches and
+  `drawbridge-docs/releases/<id>.md`), holding every data step the release
+  needs and exporting
+  `({ controller }) => async ({ dryRun, organization, ...args }) => counts`.
+  Nothing at boot requires `scripts/`; `test/migrations-folder.test.js` refuses
+  any other file there. **The folder only ever holds what production has not
+  run**: once the production run is recorded, `git rm` the file (the promote
+  step will do this), so two releases in flight are two files and no spent code
+  lingers. (Until 2026-10-21 these were functions in one
+  `scripts.js` that boot required and that kept its fifteen spent functions for
+  a month; Darren, 2026-10-21: "avoids old code kicking around".)
+- Take `{ dryRun, organization }` and report what it would do as the object you
+  return (`{ found, updated }` or whatever the counts are). The first run of a
+  migration is a read.
+- Run it only through the runner. On a laptop, from the api checkout:
+  `npm run migrate -- <asana id> --dry --env dev`, then
+  `--organization <id> --env dev --release <slug>`, then `--env dev --release <slug>`.
+  No env file holds a value: the runner re-runs itself through `scripts/op.sh`
+  with the file `--env` names (`.env.local` / `.env.development`, two lines naming
+  a 1Password Environment), so the Environment is injected the way the servers
+  get it. It refuses the wrong cluster, hands a dry run a controller that throws
+  on any write, and writes the result to `runs/<env>-<fn>-<time>.json` (read the
+  file, never the console: `op run` conceals anything that looks like a secret).
+- **Production runs inside the deployed api container**, never from a laptop,
+  so no laptop ever holds a production file: `doctl apps console <prod api app
+  id> drawbridge-api`, then `op run --environment "$OP_ENVIRONMENT_ID" -- node
+  migrate.js <asana id> --env prod --dry --sha <promoted commit>`, then the same
+  without `--dry` and with `--release <slug>`. The image carries `migrate.js`
+  and `scripts/`. There is no git there, so the runner proves `--sha`
+  against `APP_COMMIT_HASH` (the deployed commit, injected by the app spec); in
+  a checkout it still refuses production off `main`, at the wrong commit, or with
+  `scripts/`, `lib/` or `migrate.js` modified. `cat` the counts file from the
+  console shell afterwards, outside `op run`, to read it unconcealed.
+- A real fleet run records itself when drawbridge-docs sits beside the api:
+  `drawbridge-docs/releases/<slug>.json` gets
+  `migrations.<asana id>.<development|production> = true`, and the release
+  document `releases/<slug>.md` gets a row in its Migrations table. That is how
+  "has it run on prod?" is answered. In the container there is no docs checkout:
+  the runner prints exactly which flag and row to write, and you commit them
+  from a laptop from the counts file. After a production run the promote step
+  deletes `scripts/migration-<asana id>.js`, so the folder only ever holds what
+  has not run.
 - Add it to the release document in `drawbridge-docs/releases/` for the launch it
   belongs to, with the ordering constraint stated: what has to be deployed before
   it can run, and what breaks if it runs early.

package/conventions/rules.md

@@ -36,3 +36,7 @@
 8. Never make it up. A statement of fact in anything you write to a person is backed by something you read in this session: a file you opened whole, a doc in `drawbridge-docs`, the knowledge graph, a vendor's documentation you fetched, a value you measured. If none of those backs it, it is not a fact yet: say "I do not know" or put it to Darren as a numbered question. Never write a step in the past tense for something you have not done ("Updated the step in the task" when nothing was edited). Never describe a thing as absent because you have not found it yet; rule 6 says how to search first.
 
    Why: a confident sentence with nothing behind it reads exactly like a verified one, and the reader builds on it. It has sent a tester hunting for a badge that did not exist, described a repo as missing code that was in another package, and promised an edit that had not happened. Every one of those was cheaper to ask about than to correct afterwards.
+
+9. Write in the spirit of ASD-STE100. One idea per sentence, with an active verb, in about 20 words. A procedural step is one action: "Open the campaign. Click Draw." never "Open the campaign and click Draw". A condition or warning comes before the step it applies to, never after. One word has one meaning for the whole reply: do not swap in synonyms for variety, and write "must" for a requirement and "we recommend" for advice, never "should". The STE dictionary is not in force; use the words the team uses (rule 7).
+
+   Why: STE exists so that a reader who skims under pressure cannot misread a step. That is Jaime reading a retest list and Darren reading a question. Darren, 2026-10-21, asked for the spirit of STE and not the letter.

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/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.72",
+  "version": "0.1.76",
   "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|\bwrit(e|es|ing)\s+(it\s+)?off\b/i, /\b(unarchiv|restor)/i, 'archive or write off', '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()