@drawbridge/drawbridge-agents 0.1.93 → 0.1.94

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

@@ -43,7 +43,7 @@ Wait for both answers. Never guess either name. The developer still assigns the
 - nothing about who reviews or tests: both were answered at line 1;
 - **a package publish, if any subtask names `@drawbridge/components` or `@drawbridge/drawbridge-utils`**, as a statement, not a question: this release publishes a package; the developer named above publishes it. The package is built first and gets its own pull request to the package's `main`; the end list (line 5) hands the developer the merge and the tag to push; the skill then bumps the pin in every consumer, and the app pull requests open after that, once the publish is done. Line 4 step 2 is the exact sequence.
 
-**Publishing is settled; never ask about it.** The developer publishes every package by merging its version bump to `main` and pushing the tag `v<version>` (`git checkout main && git pull && git tag v<version> && git push origin v<version>`); GitHub Actions (`.github/workflows/publish.yml`, since Butterscotch 2026-10-23, task 1218041740718540) builds, runs the tests and publishes through npm trusted publishing, so no npm token exists anywhere and the registry shows the publisher as "GitHub Actions" (proven with stripe 0.1.56). The workflow refuses a tag that differs from `package.json` or is not on `main`. The hand path, `git pull && npm run build` on `main` with the developer's one-time password, still works as a fallback. Agents hold no npm token and never will. So the skill never asks who publishes, whether to publish, whether it may publish, or how: it writes the one command into the end list as an instruction to the developer and waits for `npm view` to show the version (Darren, 2026-10-22: "I get a lot of questions in the release about npm publishing etc, lets make sure that it's clear that the developers do the publishing so that these go away").
+**Publishing is settled; never ask about it.** The developer publishes every package by merging its version bump to `main`: GitHub Actions (`.github/workflows/publish.yml`, on merge for every package since Cherry, 2026-10-27) builds, runs the tests, publishes through npm trusted publishing when the version is new to npm, and tags the commit `v<version>`, so no npm token exists anywhere and the registry shows the publisher as "GitHub Actions" (proven with stripe 0.1.56). A merge that keeps the version publishes nothing. The hand path, `git pull && npm run build` on `main` with the developer's one-time password, still works as a fallback. Agents hold no npm token and never will. So the skill never asks who publishes, whether to publish, whether it may publish, or how: it writes the one command into the end list as an instruction to the developer and waits for `npm view` to show the version (Darren, 2026-10-22: "I get a lot of questions in the release about npm publishing etc, lets make sure that it's clear that the developers do the publishing so that these go away").
 
 Wait for the yes. Nothing below runs before it. From the yes to the end list, the run is unattended: the next section says what that means.
 
@@ -76,7 +76,7 @@ All work on the release branches against the **Local** database. Develop and its
 2. **Package first, and the publish never blocks.** Every subtask that touches `@drawbridge/drawbridge-utils` or `@drawbridge/components` is built before any app subtask, so the package is finished and its pull request ready when the end list goes out, and the build never pauses for it (Darren, 2026-10-22: "I had to wait a while for the publishing code to be written"; "the publish step includes merging each npm package to main, and bumping the pin(s)"). The whole package step, per package, utils before components (components peer-depends on utils):
    1. Build the package subtasks on `feature/<id>` in that package, tests first, `npm test` and `npm run test:app` (components) green, the two review passes.
    2. Bump the package's own version in its `package.json` (patch), commit, push, and open its pull request to the package's `main` (`gh pr create --base main …`), assigned to the developer from line 2. Nothing is posted to Asana yet; the link goes into the end list.
-   3. Write the publish instruction into the Parked section, addressed to the developer from line 1, as one numbered item with the exact words: merge that pull request, then from the package checkout: `git checkout main && git pull && git tag v<version> && git push origin v<version>`; the Publish workflow does the rest, and `npm view <package> version` shows it within a few minutes (by hand if the workflow fails: `npm run build` on `main`). It is an instruction, not a question, and it goes out at line 5, never now. No question about publishing is ever put to anyone (line 2).
+   3. Write the publish instruction into the Parked section, addressed to the developer from line 1, as one numbered item with the exact words: merge that pull request to `main`; the Publish workflow does the rest, and `npm view <package> version` shows it within a few minutes (by hand if the workflow fails: `npm run build` on `main`). It is an instruction, not a question, and it goes out at line 5, never now. No question about publishing is ever put to anyone (line 2).
    4. **Keep going** on the app subtasks. For one that needs the new package code, `npm link` the local package checkout into the app worktree so it is written and tested against it now.
    5. When `npm view <package> version` shows the new version (after the person has published from the end list): bump the pin to that exact version in **every consumer in the family**, not only the release's (Darren, 2026-10-22: "Once a package is published, all consumer pins should also be updated"; pins are version-exact family-wide, `conventions/drawbridge-packages.md`). One command does it: `npx drawbridge-agents-bump <package> <version>` (from any family checkout; `--dry` lists the consumers first) finds every consumer, keeps each one's field, installs the exact version so the lockfile names it, commits "<package> <version>" and pushes each repo's current branch. Before running it, the release's own consumers must have their `feature/<id>` branch checked out (the worktrees), so they take the bump there, while every other consumer takes a pin-only commit on its integration branch. Unlink first where a worktree was linked; run the tests after. A sibling package bumped this way is itself published by the same steps before the apps that depend on it.
    6. No app pull request opens while a pin still names a version the registry does not have.

package/.root-template/nvmrc

@@ -1 +1 @@
-v22.23.1
+v22.23.4

package/README.md

@@ -31,7 +31,7 @@ claude/
   mcp.json                  → .mcp.json    project-level MCP servers (Sentry, Asana)
   editorconfig              → .editorconfig family-wide editor defaults (tabs, lf, utf-8)
   npmrc                     → .npmrc        save-exact=true (exact-pin convention)
-  nvmrc                     → .nvmrc        family-standard node version (v22.23.1)
+  nvmrc                     → .nvmrc        family-standard node version (v22.23.4)
 
 bin/
   sync-claude.js            ← drawbridge-agents-sync — mirrors templates + graphify preflight

package/conventions/cross-repo-contracts.md

@@ -37,7 +37,11 @@ skill) so it stops living only in tribal memory.
   `status:'pending'` + the `business` details, sync's `queue/identity.js` verify job is the
   ONLY writer of `'verified'` (after Twilio Toll-Free Verification approval, via the utils
   twilio transport — it also renders and uploads the opt-in evidence at submission), and
-  sync's `queue/notification.js` sends from `'verified'` rows only. An api route (or script)
+  sync's `queue/notification.js` sends lead-facing SMS ONLY from the organization's own
+  `'verified'` row, on the platform's Twilio keys: no merchant Twilio connection is consulted,
+  and no row cancels the send (`no-sms-number`), never falling back to the platform number.
+  api's draw route requires the same verified row before a winner text (since Cherry, release
+  1219789739362144). An api route (or script)
   minting `'verified'` ships a number Twilio blocks outright — it looks live and delivers
   nothing. (Collection renamed `networking` → `identity` 2026-09-03, pre-data; the plan
   feature key stays `organization:networking` because custom-plan documents can store
@@ -90,13 +94,17 @@ skill) so it stops living only in tribal memory.
   (`lib/buffer.js 'twilio.message.inbound'`). The ONLY reader on any send path is sync
   `lib/suppression.js canSend()` — a new lead-facing send path must call it, or opted-out
   recipients get contacted (TCPA/CAN-SPAM exposure). Lead-facing = the notification carries
-  `lead`/`workflow`/`connection`; those sends also REQUIRE an org connection (no system-sender
-  fallback), while system mail (OTC codes, member invites, security notices) keeps the system
+  `lead`/`workflow`/`connection`; lead-facing SMS also REQUIRES the organization's own verified
+  number (no system-number fallback), while system mail (OTC codes, member invites, security notices) keeps the system
   sender and is never suppressed. **System mail is identified by `audience`, not by whether an
   organization is present** — `queue/identity.js` sends member mail WITH an org, and
   `stream/transaction.js` sends AI-balance notices with none. Inbound STOP flows webhooks
-  (`POST /connection/:id/twilio`, signature-verified against the URL built from
-  `APP_CLIENT_WEBHOOKS_URI`) → `buffer` doc → sync drain → platform-global suppression row;
+  (`POST /connection/drawbridge/sms`, signature-verified against the URL built from
+  `APP_CLIENT_WEBHOOKS_URI`) → `buffer` doc → sync drain (utils drawbridge `inbound.process`,
+  given `read`) → a suppression row scoped to the organization whose number received it (from
+  the `To` number's `identity` row; only the platform's own number writes `organization : null`).
+  **STOP is per organization since Cherry**, like an email unsubscribe; rows written before it
+  carry `organization : null` and still block everyone;
   api registers the number's SmsUrl at twilio connect (`lib/twilio.js`) and `scripts.js
   registerTwilioWebhooks` backfills — a deployed webhooks route with unregistered numbers hears
   nothing, silently. **Since Butterscotch (release 1219790090574059; sync 762fdd7, Darren
@@ -125,10 +133,10 @@ skill) so it stops living only in tribal memory.
   same tag; break the round-trip and consent lookups stop matching. api mirrors ONLY the
   lead-facing branch (`identityDefaults.from`). Detail: drawbridge-docs `reference/providers.md`.
 - **Adding an email/SMS vendor is a two-repo change** (api ↔ sync). A connection is deliverable
-  only if sync implements a sender for its slug — `lib/email.js` (`{ mailchimp, sendgrid }`) and
-  `lib/sms.js` (`{ twilio }`), which `queue/notification.js` reads **directly** as its guard and
-  org-scoped lookup; never re-list the slugs as literals, or the guard drifts from the senders
-  that exist. Adding a vendor to drawbridge-api `lib/connections.js` with `group : 'email'`/`'sms'`
+  only if sync implements a sender for its slug — `smsSenders` in `queue/notification.js`, which
+  since Cherry guards only a legacy notification pinned to a connection (lead-facing SMS sends
+  from the org's verified number; email from the platform or the org's verified domain); never
+  re-list the slugs as literals, or the guard drifts from the senders that exist. Adding a vendor to drawbridge-api `lib/connections.js` with `group : 'email'`/`'sms'`
   makes it selectable throughout api and app-web, but with no sync sender every send is
   cancelled, not delivered — merchant sees a workflow that ran and no message. The miss is
   detectable, not silent: `notification.reason = 'connection-slug-mismatch'` plus an
@@ -170,7 +178,19 @@ skill) so it stops living only in tribal memory.
   and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
   `render` content-hashes the rendered output — drop `render` from either side and a rendering
   fix never ships: reuse serves the first-ever render forever (the onemethod
-  black-on-black-logo-twice bug).
+  black-on-black-logo-twice bug). Since Cherry a captured video's origin IS its storage address,
+  `scrape/<id>/videos/<digest>-original`, owned by that scrape (sync `scrape.mediaKey`; images
+  under `scrape/<id>/images/`): moving one means rewriting `data.gallery.video.origin`, the
+  cached `data.files` entry and every file's `meta.origin` to the same string in one step, or the
+  next generation re-trims and duplicates the clip (api migration 1219789739362144 `scrape`).
+- **A workflow's campaigns are read only through utils `workflowCampaigns( workflow )`** (utils ↔
+  sync ↔ api ↔ components, since Cherry). `trigger.filters.campaigns` is a list of ids, empty =
+  every campaign; the helper falls back to a legacy `campaign` string. sync (`firesForCampaign`,
+  `pauseWorkflowsForCampaign`), the utils digest/notify steps and the api's save and read all go
+  through it. **Sync deploys BEFORE the api**: the new api writes `campaigns` and drops `campaign`
+  on every save, and an old sync reads only `campaign`, so it fires every narrowed workflow for
+  every campaign. The migration converting `campaign` → `campaigns` runs after both are live.
+  Saving refuses another organization's campaign id.
 
 ## Billing / metering
 
@@ -329,6 +349,15 @@ skill) so it stops living only in tribal memory.
 - The api's `POST /oauth/google/callback` returns `redirectTo` in its 400 body when it read the state
   row before failing, so app-web can keep the resume target across `/auth?error=oauth`. A
   `oauth.state.invalid` failure cannot — that row is what carried the target.
+- **Sign-out ends a token family** (utils ↔ api ↔ app-web, since Cherry). Every token of one
+  sign-in shares `token.family` (utils `saveToken`, api `issueTokenPair`/`silentRefresh`); sign-out
+  calls utils `revokeFamily` and clears the api's session cache for each access hash. app-web's
+  `lib/signout.js` sends the refresh token in the body: Bearer while the session cookie lives, the
+  dashboard's Basic client credentials once it has lapsed. The api schema declaring `family` and
+  `pair` must have **booted** before the api runs utils ≥0.0.223 (only the api writes tokens, so
+  sync may run it first), and the api deploys before app-web. NEVER
+  pass a missing family to `revokeFamily` (it refuses; a query on a missing family would revoke
+  every older token). A rotated refresh token expires 60 s after rotation, so the TTL deletes it.
 - Google sign-in NEVER auto-links (`profile/disconnect-google` must stick): the callback signs in
   only on an exact google account row; an email-only match is refused with `code: google.not.linked`
   in the error body, which app-web's `/api/auth/google` maps to `/auth?error=google-not-linked`
@@ -521,6 +550,13 @@ renaming one orphans what is already enqueued and starts a parallel stream nobod
 with no error. `bullmq-identity.test.js` in sync spells out the routing table so moving a
 step between queues requires editing it deliberately.
 
+**A hook asks for a retry by throwing `retry : true` (utils ↔ sync, since Cherry).** Sync's
+step runner (`lib/step-runner.js`) re-runs the same step after 5, 10 and 15 seconds with a new job
+id, writing no step row and no issue until the retries are spent; utils' Send SMS hook throws it
+when the entry's submission is not written yet (the api's thin ingest writes the lead first). A
+utils that throws it ahead of a sync without the runner change turns every retry into a failed
+step with an issue: sync deploys first.
+
 **`grant_refused` is minted in utils, keyed on in sync (utils ↔ sync).** Only the two
 dead-grant paths in drawbridge-utils — a refused refresh (`connections/oauth.js`) and an
 unrenewable expiry (`connections/token.js`) — set `error.code = 'grant_refused'`; a network

package/conventions/drawbridge-packages.md

@@ -9,24 +9,20 @@ on GitHub and `@drawbridge/shopify` deprecated on npm (2026-09-13, "use
 
 ## Publishing
 
-**A publish is a tag push (since 2026-10-23).** Merge the version bump to `main`, then from
-the package checkout `git checkout main && git pull && git tag v<version> && git push origin
-v<version>`. Every package's `.github/workflows/publish.yml` runs on `v*` tags: it refuses a
-tag that differs from `package.json` or is not on `main`, runs `npm ci`, `npx tsup` and
-`node --test`, then `npm publish --ignore-scripts` through npm trusted publishing (OIDC,
-`id-token: write`, npm 11). No npm token is stored anywhere; the registry records the
-publisher as "GitHub Actions" (first proven with stripe 0.1.56, run 39975659406). The
-trusted publisher for each package is configured on npmjs.com by Darren. A developer pushes
-the tag; an agent never does.
-
-**drawbridge-agents publishes on merge (since 2026-10-23).** Merging a version bump to its
-`main` publishes it and tags `v<version>`; a merge that keeps the version publishes nothing.
-The session that merged then waits for `npm view @drawbridge/drawbridge-agents version` to
-show it and runs `npx drawbridge-agents-bump @drawbridge/drawbridge-agents <version>`, leaving
-out growth and any repo checked out on another release's branch (docs often is: bump docs on
-`main` in a worktree). No GitHub key is involved (Darren, 2026-10-23: merging to main should
-"publish agents and trigger the pin bump"). Merging is publishing, so whoever merges to agents
-`main` decides. The other packages still publish on the tag push above.
+**A publish is a merge to `main` (every package since Cherry, 2026-10-27; agents since
+2026-10-23).** Each package's `.github/workflows/publish.yml` runs on every push to `main`: when
+the `package.json` version is already on npm it publishes nothing; when it is new it runs
+`npm ci`, the package's build (`npx tsup`, plus `node scripts/esm-extensions.js` for components,
+`npx tsup ./index.js` for mongodb and redis) and `node --test`, then `npm publish
+--ignore-scripts` through npm trusted publishing (OIDC, `id-token: write`, npm 11) and tags the
+commit `v<version>` itself. No npm token is stored anywhere; the registry records the publisher
+as "GitHub Actions" (first proven with stripe 0.1.56, run 39975659406). The trusted publisher
+for each package is configured on npmjs.com by Darren. Merging is publishing, so whoever merges
+a version bump to a package's `main` decides it ships (Darren, 2026-10-27: "all npm connected
+packages should publish the same way"). The session that merged waits for `npm view <package>
+version` to show it and runs `npx drawbridge-agents-bump <package> <version>`, leaving out growth
+and any repo checked out on another release's branch (docs often is: bump docs on `main` in a
+worktree).
 
 The hand path below still works as a fallback when the workflow fails.
 

package/package.json

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