@drawbridge/drawbridge-agents 0.1.40 → 0.1.47

package/conventions/cross-repo-contracts.md

@@ -31,6 +31,15 @@ skill) so it stops living only in tribal memory.
 
 - All socket emits from sync go through `drawbridge-sync/lib/emit.js` — never call
   `io.to().emit()` directly from a worker.
+- An `sms` identity row is **never created `verified`**: api's purchase route writes
+  `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)
+  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
+  granted keys — that string is data, never rename it without a migration.)
 - Cascade cleanup of dependent rows belongs in a sync change-stream listener, not inline in the
   API route that triggered the delete (see `cascade-cleanup.md`).
 - A collection with no `queue/<collection>.js` handler is watched but its events are **silently
@@ -134,9 +143,33 @@ skill) so it stops living only in tribal memory.
   would have zeroed every invoice once the products were archived.
 - **The v2 pricing-plan layer (`bpp_*`, billing cadences) is never touched by script.** Canceling a
   billing cadence is terminal and unrecoverable. Dashboard, by hand, only.
+- **The Shopify meter handle is a config contract no code validates** (shopify ↔ Partner
+  Dashboard ↔ sync/utils). `SHOPIFY_USAGE_ORDERS_EVENT_HANDLE` in `@drawbridge/shopify`
+  (`drawbridge-orders`) must exactly match — case-sensitive, handle not display name — a usage
+  meter on the App Pricing plan version each merchant has APPROVED (meters are never
+  retroactive). A mismatch, a missing meter, or a merchant on a pre-meter plan still 202s every
+  event, logs it as a plain app event, and bills nothing; no error surfaces anywhere in code
+  (the 19/99 write-off). Any change to the handle constant, the Partner Dashboard pricing
+  config, or a plan version requires verifying a fresh order classifies as a billing event in
+  Dev Dashboard → Logs (type "App billing event"). The trace key both sides share is
+  `billed.transaction` = the event's `reference` = `drawbridge-orders.<orderId>`. Detail:
+  drawbridge-docs `reference/shopify-app.md` (Billing).
 - **A subscription must open with the plan item.** It used to open with the metered actions price
   and attach the plan afterwards with `always_invoice`. With no metered item, Stripe rejects an
   itemless subscription, so the plan goes in at creation — changing the first invoice's shape.
+- **Ending a subscription is written twice, from ONE implementation** (stripe ↔ api ↔ sync).
+  `subscription.markTerminal` in **drawbridge-stripe** (`lib/subscription.js`, takes the caller's
+  db controller + session like `reconcile`) clears the org's `subscription` pointer, demotes to
+  `unsubscribed` under `status : { $nin : [ 'suspended', 'unsubscribed' ] }`, `$pull`s the org's
+  `type : 'method'` errors and flips the sub doc to `canceled`. Both callers run it: sync's
+  `markSubscriptionTerminal` (`lib/buffer.js`, on `customer.subscription.deleted` and terminal
+  `subscription.updated`) and drawbridge-api's admin cancel
+  (`route/organization-subscription.js` `handlers.delete.cancel`), which mirrors it inline so the
+  page isn't stale for a webhook it just caused. **The mirror runs FIRST and consumes the status
+  guard**, so the webhook's pass then matches nothing — anything one caller does outside
+  `markTerminal` therefore never happens on the admin path. Never re-inline these writes: the
+  hand-copied version drifted, and a stale card decline outlived its subscription and permanently
+  blocked the org from resubscribing (Asana 1217947409527192).
 - **Invoice line descriptions must keep the word "actions":** `isActionsLine` matches `/actions/i`
   to count billed quantity for the billed-vs-ledger reconcile. A copy edit that drops it silently
   breaks the audit. Detail: drawbridge-docs `reference/billing.md`.
@@ -371,6 +404,21 @@ 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.
 
+**`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
+failure never does. Sync's step-runner errors the connection on that code during a
+`lifecycle.health` step (the shell mints the token, so the hook can't). Minting the code
+anywhere transient flips healthy connections to error on a blip; renaming it in either repo
+means dead grants retry into Sentry forever (the Shopify 08-16 incident, ecosystem-wide).
+
+**The SMS inbound URL is one string two repos must agree on (api ↔ sync ↔ webhooks).**
+`APP_CLIENT_WEBHOOKS_URI + '/connection/drawbridge/sms'` is written to each purchased
+number by api (`route/organization-networking.js`) and re-asserted by sync's daily identity
+sweep (`queue/identity.js`), which re-points any number whose Twilio config drifts. Change
+the path in one place and the sweep "repairs" every number to the wrong URL — inbound SMS
+(STOP included) goes dark with all rows reading healthy.
+
 ## Import surfaces
 
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`

package/conventions/superpowers-docs.md

@@ -8,7 +8,12 @@ drawbridge-docs/superpowers/plans/YYYY-MM-DD-<slug>.md
 drawbridge-docs/superpowers/specs/YYYY-MM-DD-<slug>.md
 ```
 
-This is the **only** allowed home for these working docs. Rules:
+**THE ONE EXCEPTION IS drawbridge-growth** (Darren, repeatedly, most recently 2026-09-01:
+"Don't add growth docs to docs"): growth is its own system — its plans and specs live in
+`drawbridge-growth/docs/superpowers/{plans,specs}/` and must **never** be written to
+drawbridge-docs. The guard hook exempts any `drawbridge-growth*` path for this reason.
+
+For every other repo, this is the **only** allowed home for these working docs. Rules:
 
 - Do **not** create or keep superpowers plans/specs (or `docs/superpowers/`, `docs/plans/`)
   inside any other repo. When you finalize a plan or spec, write it under

package/hooks/guard-superpowers-docs.js

@@ -47,6 +47,11 @@ const run = () => {
   // drawbridge-docs is the canonical home — anything there is fine.
   if (resolved.split('/').includes('drawbridge-docs')) process.exit(0)
 
+  // GROWTH IS THE EXCEPTION (Darren, repeatedly, most recently 2026-09-01):
+  // growth is its own system and its docs stay in drawbridge-growth — never
+  // in drawbridge-docs. Any growth checkout or worktree passes.
+  if (/\/drawbridge-growth[^/]*\//.test(resolved + '/')) process.exit(0)
+
   const hit = FORBIDDEN.find((seg) => resolved.includes('/' + seg + '/') || resolved.endsWith('/' + seg))
   if (!hit) process.exit(0)
 

package/package.json

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