@drawbridge/drawbridge-agents 0.1.88 → 0.1.90

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

@@ -9,7 +9,7 @@ One Asana release task is the unit. Its id names everything: the `feature/<id>`
 
 The ten lines below are the release, as Darren confirmed them on 2026-10-22. The skill owns lines 1 to 5 and 10 and runs them without anyone present once line 2 has its yes. A developer owns 6 and 9. A QA person owns 7 and 8. The skill never does a developer's or a tester's line for them.
 
-1. A person gives the skill the release task link. The skill checks `gh auth status`.
+1. A person gives the skill the release task link. The skill runs the doctor, then asks two things before reading anything: who reviews and who tests.
 2. The skill reads the task and subtasks, writes the stories, sends ONE numbered list and waits for the yes. The yes starts an unattended run.
 3. Task → Building: branches, the release document, the band.
 4. The skill builds on the release branches against the Local database, with the QA agent run locally. Nobody is asked anything; whatever needs a person is parked.
@@ -24,6 +24,15 @@ The ten lines below are the release, as Darren confirmed them on 2026-10-22. The
 
 Read the release task and every subtask through `drawbridge-tests/lib/asana.js` (`api( 'GET', '/tasks/<id>?opt_fields=name,notes,memberships.section.name' )`, then `/tasks/<id>/subtasks`). Subtasks live in "DrawBridge - Application" (or the Backlog) and stay there. A release is named with one ice cream, in alphabetical order across releases, nothing else: "Almond", "Butterscotch", "Cherry", "Dulce", "Espresso" exist (Darren, 2026-10-22: no numbers, no weeks, no dates; the alphabet carries the order). The date is the task's due field. If asked to create one, take the next letter after the latest in the Releases project. Run `npx drawbridge-agents-release-doctor` from the api checkout first: it checks git, `gh auth status`, `op` on the beta channel, the api's two env files, `scripts/op.sh`, the npm registry and both clusters, and prints one numbered list of what is missing with the fix for each. Stop on any required miss and hand that list to the person. Other developers start releases from their own machines, so nothing is assumed.
 
+**Then, before the stories, ONE numbered list of two questions**, so the people are known before any work starts and nobody waits for the review to finish (Darren, 2026-10-23: "the first questions asked right away is who is the development reviewer and who is the qa specialist"; "Then any task questions can come after the initial review"):
+
+1. Who on the development team reviews this release: their GitHub username (for the pull requests) and their Asana name (for the task).
+2. Who tests it: the QA person's Asana name.
+
+No organization is asked for, and no test list names one. Nobody can guess which organization a developer or a tester will use, and a link to an organization they cannot open loses the whole session (Jaime, 2026-10-23: a link went to one of Darren's organizations). Each test list instead says what the organization must have (Darren, 2026-10-23: "Open an organization with the following features...").
+
+Wait for both answers. Never guess either name. The developer still assigns the QA person at line 6; the name asked here is who that will be.
+
 ## Line 2: the one list
 
 **The graph first, grep last.** `git -C ../drawbridge-docs pull` brings the committed knowledge graph (`drawbridge-docs/knowledge/graphs/global.json`, rebuilt at the end of every release); it already knows the family, so a release does not rediscover it by searching sixteen repos from scratch (Darren, 2026-10-22: "make sure we are leveraging the knowledge graphs and not always searching each time we start from develop. That is the point of having that feature"). For every subtask, before any grep: `graphify query "<the subtask in words>"`, then `graphify explain <symbol>` and `graphify affected <symbol>` for the handlers, fields or components it names, all with `--graph ../drawbridge-docs/knowledge/graphs/global.json`. The answers give the repos and files the subtask touches and the cross-repo contracts in play; that list is the Scope table at line 3. Grep only inside a file the graph named, to read it, never across repos to find it.
@@ -31,7 +40,7 @@ Read the release task and every subtask through `drawbridge-tests/lib/asana.js`
 **Every subtask has a story; no exceptions.** For every subtask, find the existing story or write one (`drawbridge-feature` step 1), from what the graph showed: a bug fix gets the story whose scenario it restores, a new behaviour gets a new story, an internal change gets the story of the behaviour it must keep working. A subtask that ends line 2 with no story is a stop condition, not a gap to fill later: the QA person tests from the story, so a subtask without one has nothing to test against (Darren, 2026-10-22: "all subtasks in a release create or link to an existing story, so there is context about what needs to be tested"). Then ONE numbered list to the person who started the release, each item three plain sentences (`conventions/rules.md` rule 7) plus a fourth, the recommendation, holding:
 
 - every unknown from every story, **each with the fix you recommend**: "I recommend <the option>, because <the reason>." The recommendation comes from having read the code the subtask touches (the files the graph named, opened whole) and from what apps like Drawbridge commonly do for the same thing, and it picks the best experience for the person using the product. That goes for every aspect of the platform, not only screens: a feature, a price or plan rule, a design, a message, a default, a limit. A question without a recommendation reads as a question nobody has thought about (Darren, 2026-10-22: "recommend the fix as well. This way I know you've reviewed the code and considered the best approach. We should always be looking at what is the best user experience as well as what is common for apps like ours"). When the recommendation needs a fact you do not have, say which, and still name the option you would take;
-- **who on the development team takes the pull requests**: their GitHub username (for the pull requests) and their Asana name (for the task). Asked now so nobody needs to be present between lines 3 and 5. Never guess a reviewer;
+- 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 publish command; 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, from the package checkout on `main`, with `git pull && npm run build` (tsup, the tests, `npm publish`, their one-time password). Agents hold no npm token and never will (an agent's `npm publish` answers 401); the automation token (queue task 1218041740718540, in Butterscotch) will move the publish into CI, and until then it is the developer's hand. 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").
@@ -87,7 +96,7 @@ Only when every subtask that can be built has been built: each committed, `npm t
 
 1. One pull request per repo: `gh pr create --base develop --head feature/<id> --title "Release <id>: <task name>" --assignee <developer> --reviewer <developer> --body <the Scope table, the per-subtask commits, the QA reports' paths, and the migration's dev command if there is one>`. Components and utils target `main`.
 2. Every pull request body ends with the lane rule in one line: "Review any time, on the feature branch locally. Merge only when develop is free: one release on develop at a time, so this merges once the release before it is Released." Fill the Branches table in `releases/<id>.md` with the PR links; commit.
-3. **How to test, on every subtask, for both readers.** Append to each subtask's description, under its Story lines, two headings (Darren, 2026-10-22: "steps for a developer to test via code, or locally, and a QA person's steps"). First, "Test locally (developer)": one numbered list with the branch to check out, the exact commands (`npm test` in the repo, the test file that proves the change, `npm run migrate -- <id> --dry --env local` when there is a migration, `npm run walk -- --local <path>` for a screen), the localhost URL and the result each command must print or show. Then, "Test on dev (QA)": one numbered list with the dev app to open first by URL (dashboard `https://dev.dashboard.trydrawbridge.com/...`, a share page `https://<slug>.dev.drwbrdg.com/...`, the website `https://dev.trydrawbridge.com/...`, the components app `https://components.trydrawbridge.com/...`), then one action per step, then what the tester must see. Every label in it is quoted from the Local walk and the QA reports of line 4, never from memory (`conventions/walk-the-app.md`), with dev URLs in place of localhost. A migration subtask says what the tester checks after the developer's dev run. The words go through `humanizer`. Both lists are written here, after the build, because only then are the commands and labels known (Darren, 2026-10-22: "include steps on how to test in the respective development apps"). The pull request body and the release doc's QA table point at the subtasks for these steps rather than repeating them.
+3. **How to test, on every subtask, for both readers.** Append to each subtask's description, under its Story lines, two headings (Darren, 2026-10-22: "steps for a developer to test via code, or locally, and a QA person's steps"). First, "Test locally (developer)": one numbered list with the branch to check out, the exact commands (`npm test` in the repo, the test file that proves the change, `npm run migrate -- <id> --dry --env local` when there is a migration, `npm run walk -- --local <path>` for a screen), and for a screen: "Open an organization with the following features: <what this subtask needs, e.g. a connected Shopify store, a giveaway with a published prize>" on `http://localhost:3000`, then the path inside it by screen name, and the result each command must print or show. Never a fixed organization id. Then, "Test on dev (QA)": one numbered list with the dev app to open first (dashboard `https://dev.dashboard.trydrawbridge.com/organizations`, then "Open an organization with the following features: <what this subtask needs>" and the screens by name from there, never a fixed organization id, a share page `https://<slug>.dev.drwbrdg.com/...`, the website `https://dev.trydrawbridge.com/...`, the components app `https://components.trydrawbridge.com/...`), then one action per step, then what the tester must see. Every label in it is quoted from the Local walk and the QA reports of line 4, never from memory (`conventions/walk-the-app.md`), with dev URLs in place of localhost. A migration subtask says what the tester checks after the developer's dev run. The words go through `humanizer`. Both lists are written here, after the build, because only then are the commands and labels known (Darren, 2026-10-22: "include steps on how to test in the respective development apps"). The pull request body and the release doc's QA table point at the subtasks for these steps rather than repeating them.
 4. Attach every QA report's screenshots to the release task (`node lib/asana-attach.js <release id> <png>` from drawbridge-tests, one per scenario, named `<subtask id>-<scenario>.png`), because the reports under `results/qa/` are gitignored and exist only on the machine that ran them. Then put the PR links on the release task as ONE numbered list (`drawbridge-asana-comment`): this is the first Asana comment of the release, and the package pull request's link rides in it too. Assign the task to the developer and move it to Review (`POST /sections/1219762451512990/addTask`) only once every pull request is open, parked items included.
 5. Stop. Report the PR links.
 
@@ -119,7 +128,8 @@ The skill does none of this. For the record, so the skill can answer "what is th
 
 - Push `main`, deploy production, write to the production database, publish a package, merge a pull request, assign the QA person or move the task to QA or Approved. Those are a developer's or a tester's lines. On dev the skill writes nothing of its own either (the refresh only READS dev to copy it into Local); the dev migration runs on a developer's explicit instruction, by the developer or by an agent they ask.
 - Ask anything about npm publishing: who, whether, how, or for permission. The developer publishes, always; the skill hands them the one command in the end list and waits for the registry.
-- Name a reviewer or a release scope that nobody told it; both are asked in line 2. The tester is the developer's choice at line 6 and the window is the developer's at line 9; the skill asks for neither.
+- Name a reviewer, a tester or a release scope that nobody told it; the people are asked at line 1, the scope at line 2. The window is the developer's at line 9; the skill asks for it never.
+- Name an organization in a test list. A developer or a tester opens one that has the features the list names; nobody can guess which they will use.
 - Write a release document, branch or migration under any name but the Asana id.
 - Build or run the QA agent against dev or develop before the pull requests merge. Local only.
 

package/conventions/cross-repo-contracts.md

@@ -68,8 +68,15 @@ skill) so it stops living only in tribal memory.
   Connections/Workflows warning dots reflect statuses `reconcileWorkflowStatus` writes — every
   handler must emit **after** the reconcile (regression: sync test/connection-emit-order.test.js).
   Emitting first hands the client a stale menu nothing re-emits to correct (the stuck-dot bug).
-  Workflow doc changes have **no** socket event, so app-web workflow status mutations
-  (pause/resume/delete) invalidate the menu client-side themselves.
+  **Since Butterscotch (release 1219790090574059; sync `stream/workflow.js`, components
+  `template-socket.js`)** a workflow doc change DOES have a socket event: sync emits
+  `organization.workflows` through `lib/emit.js` on every status change, on an `issue` write or
+  clear, and on delete, and the shared socket template refetches the open workflow, the list,
+  the organization (Next steps) and the menu dot on it. Every status writer passes through that
+  stream handler, so a new writer must not emit on its own, and app-web's own invalidation after
+  pause/resume/delete is belt and braces, not the mechanism. Before Butterscotch there was no
+  event and app-web invalidated the menu client-side itself; a branch cut before it merges still
+  behaves that way.
 - Notification dedupe has two distinct mechanisms — pick by intent. `notification.coalesce`
   is **last-write-wins supersede** (stream/notification.js deletes the prior doc sharing the
   key); `notification.key` is **first-write-wins idempotency** — a partial unique index in
@@ -92,7 +99,15 @@ skill) so it stops living only in tribal memory.
   `APP_CLIENT_WEBHOOKS_URI`) → `buffer` doc → sync drain → platform-global suppression row;
   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.
+  nothing, silently. **Since Butterscotch (release 1219790090574059; sync 762fdd7, Darren
+  2026-10-23: an opt-out is the person's choice, not one address's) `canSend` gates the
+  PERSON, not only the address**: it reads the recipient's contact in the organization (found by
+  `canonical.emails`/`canonical.phones` or by `leads`) and blocks when any canonical or raw
+  address on that contact is suppressed for the channel. `lead` is optional, so every caller
+  that knows the lead passes it, or a returning person under a new mailbox passes until their
+  contact is rebuilt with the new address. The api's draw opt-out check
+  (`route/organization-campaign-draw.js` `optedOutLeads`) applies the same rule and must stay
+  in step with it; before Butterscotch both matched the lead's own canonical address only.
 - **`audience` picks the FROM-address; `intent` picks the unsubscribe plumbing — and NOTHING
   passes the suppression gate** (utils ↔ sync ↔ api). Every suppression source blocks every
   lead-facing send, the winner claim included: api's draw route refuses up front ("Disqualify
@@ -412,7 +427,16 @@ skill) so it stops living only in tribal memory.
   `priority` for fetchpriority=high when it's the LCP element), `defer` gates only the player —
   never the placeholder, so deferring can't blank the box — and the native poster attribute is
   kept so unmounting the placeholder at player-ready isn't frame-timing-critical. `onError` fires
-  exactly once, only after the hls→mp4 retry is exhausted. drawbridge-share's gallery carousel
+  exactly once. **Since Butterscotch (release 1219790090574059; components `video.js` and
+  `shared/lib/video.js` `videoErrorAction`)** when it fires is decided in one place: a non-fatal
+  hls.js error and an `AbortError` (a `play()` cut short by `pause()` or a source swap) are
+  ignored; a `NotAllowedError` (the browser refused to start playback, e.g. iOS Low Power Mode)
+  fails at once with NO mp4 retry, because the file is fine and the mp4 would be refused too; only
+  a FATAL hls.js error takes the one hls→mp4 retry, and `onError` fires when that is exhausted.
+  hls.js is bundled into the package and handed to react-player (`provideHls`, `window.Hls` set
+  before the player loads), so nothing is fetched from jsdelivr and an ad blocker cannot break
+  playback silently. Before Butterscotch, every player error took the retry and `onError` fired
+  only after it. drawbridge-share's gallery carousel
   depends on BOTH callbacks: it advances slides off `onDuration` OR `onError` registering a
   duration — remove or re-fire either and a broken video stalls the whole carousel (share
   `template-subdomain-gallery.js`, components `video.js`).

package/conventions/walk-the-app.md

@@ -88,8 +88,15 @@ 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
+`removeEntrant` deletes the draws that picked the lead and then the lead, and lifts any denial a
+walk made on the entrant, which outlives the lead by design (drawbridge-api `schema/denial.js`
+keys moderation on the person's canonical identifiers, not the lead id, so no product cascade
+removes it; since drawbridge-tests b081ac1, Asana 1219802418571685); sync's cascade does the
+rest and each counter nets back to zero. **Every `walk+<tag>@…` address is ONE person** to
+moderation and to consent, because `toCanonicalEmail` in utils `lib/email.js` strips the plus
+tag before either looks a person up: a denial or an unsubscribe made on `walk+a@` also covers
+`walk+b@`. Concurrent or later walks that must not share a moderation or consent state use
+different base mailboxes, not different tags. 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.

package/package.json

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