@drawbridge/drawbridge-agents 0.1.95 → 0.1.96

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

@@ -65,7 +65,7 @@ A run does not stop while there is code left to write. Whatever the hour, the ag
 3. Copy `drawbridge-docs/templates/release.md` to `releases/<id>.md`, fill Scope and Branches (reviewer from line 2), commit on the docs branch. The markdown is the one record; there is no json.
 4. Write this task's link into `drawbridge-api/release.json` and commit it on the api's `feature/<id>` branch ("release <id>: band"), never on `develop`: with several releases building at once, a band written to develop at open would name a release that is not on dev. The band reaches develop with the merge, and dev shows it above the account once the api redeploys, which is exactly when that release is the one on dev. A release that touches no api code still gets an api `feature/<id>` branch carrying this one commit and its own pull request at line 5. Nothing is committed to develop before the pull requests merge. The previous release's cut empties `release.json` on develop (line 8), so when this pull request merges after that, GitHub shows a conflict on `release.json` (changed on both sides): keep the branch's file.
 5. **Every subtask links its story.** Append to each subtask's description, under its own text, one line per story: "Story: <story id>, <GitHub link>", the link being the story file in the docs repo on GitHub, `https://github.com/trydrawbridge/drawbridge-docs/blob/main/user-stories/<domain folder>/<file>.md` (`PUT /tasks/<subtask> { notes }`; the original description stays above, untouched). Never paste the story into the task: the file in drawbridge-docs is the one copy, and the link is read on GitHub (Darren, 2026-10-22: "link to the GitHub repo for each story in the subtask so it can be read in GitHub in the docs repo"; "Don't rewrite them in the task, just link to them"). The stories were pushed to docs `main` in step 2, so every link resolves the moment it is added; check each with `gh api repos/trydrawbridge/drawbridge-docs/contents/user-stories/<folder>/<file>.md` before writing it. The QA person cross-references the story against the feature before the final test.
-6. Move every subtask from Application → Queue to Application → In progress (`POST /sections/1211315620607633/addTask { task }`). In the Application project, Queue means not scheduled and In progress means in a release (Darren, 2026-10-22); Complete comes at line 10. The release task itself lives in the Releases project only, never in Application or the Backlog, because a release draws its subtasks from both (Darren, 2026-10-22: "releases will include application tasks and backlog items, so their own board makes more sense"). A Backlog subtask keeps its Backlog membership; only Application subtasks get the Queue → In progress move.
+6. Move every subtask from Application → Queue to Application → In progress (`POST /sections/1211315620607633/addTask { task }`). In the Application project, Queue means not scheduled and In progress means in a release (Darren, 2026-10-22); Complete comes at line 10. A code subtask carries no assignee while it is in a release: the release task is what gets assigned (the developer at line 5, the QA person at line 6), so clear an assignee left on a subtask from before the release (`PUT /tasks/<subtask> { assignee : null }`; Darren, 2026-10-28, on a subtask still assigned to him from September). A setup subtask the release needs a person for (switch a vendor on, buy and verify an SMS number) is the exception: it is assigned to the developer with a due date that leaves its lead time before the release's QA (a toll-free number takes about three business days to verify, so its due date is the Monday before the release's date, not the release's date). The release task itself lives in the Releases project only, never in Application or the Backlog, because a release draws its subtasks from both (Darren, 2026-10-22: "releases will include application tasks and backlog items, so their own board makes more sense"). A Backlog subtask keeps its Backlog membership; only Application subtasks get the Queue → In progress move.
 7. **No pull request yet.** No "Marketing: What's new" subtask yet either: it is created, written and completed in one go at line 10, so developers and QA never see an open marketing item among the subtasks they are building and testing (Darren, 2026-10-22: "we should not have the marketing task in a release until it's completed, as it's confusing for the developers and qa people"). Nothing is opened, drafted or assigned at this point; the developer hears nothing until line 5, when the branch is finished. A pull request opened early reads to the developer as "review this now" and there is nothing to review (Darren, 2026-10-22, after the first run).
 
 ## Line 4: build, on Local
@@ -84,7 +84,8 @@ All work on the release branches against the **Local** database. Develop and its
 4. **Migration.** If any subtask moves data, ONE file, `drawbridge-api/scripts/migration-<id>.js`, exporting `({ controller }) => async ({ dryRun, organization, ...args }) => counts`, holding every data step. It uses the controller only; a dry run refuses controller writes but cannot refuse a native `collection.drop()` or `dropIndex()`, so a step that drops anything branches on `dryRun` itself and reports what it would drop. Anything a person must do around the run (export a collection and read it back before a drop) is written into the release doc's Migrations section as the developer's steps, not into the file. Prove it on Local: `npm run migrate -- <id> --dry --env local`, then `--env local`. The runner prints the counts and writes `runs/<env>-<id>-<time>.json`; nothing copies them anywhere.
 5. **Walk every touched app on Local**: `npm run walk -- --local <path or url>` from drawbridge-tests (dashboard at `localhost:3000`; sync must be running for anything live). Record what was seen; a label quoted later comes from this walk.
 6. **QA agent on Local.** Dispatch `drawbridge-qa` with `target : local`, once per subtask that has a story (story paths, the SUBTASK id, the organization id: `APP_TEST_ORG_ID` in `drawbridge-tests/.env`, the e2e organization `fixtures/e2e-org.md` describes, present on Local because Local is a copy of dev). A subtask spanning many stories gets one report listing them all. Fix every fail on the release branch, redispatch, until every `drawbridge-tests/results/qa/<subtask id>.json` reads `fails : 0`. The fixes are commits in the same pull request; that is why the agent runs here and not on dev (Darren: "all agent work is done locally so the work and fixes get committed as part of the PR").
-   **Inbound webhooks are the exception.** Every Local Environment points `APP_CLIENT_WEBHOOKS_URI` at `http://localhost:4002`, which Shopify, Stripe and Twilio cannot reach, so a change to how a webhook is received or handled is marked in the Scope table as "webhooks: tested on dev" and the QA person checks it on dev in line 7.
+   **Inbound webhooks are walked against dev, by the agent.** Every Local Environment points `APP_CLIENT_WEBHOOKS_URI` at `http://localhost:4002`, which Shopify, Stripe and Twilio cannot reach, so the agent connects to dev for that one step instead of handing it on (Darren, 2026-10-28: "if you need to test a third party integration you might have to connect to the dev environment, but we must always do this"). The vendor is already pointed at dev's webhooks service (every number and store registers dev's URL), so the agent triggers the event there — a STOP text to dev's number, a test order on the dev store, a Stripe test event — and reads what dev wrote (the `buffer` row, the suppression row, the screen). A change to how the event is HANDLED downstream (sync, api) is then walked on Local by copying that dev `buffer` row into Local's `buffer` collection, where Local's sync drains it through the new code. A change to how it is RECEIVED (drawbridge-webhooks itself) cannot run anywhere but dev until it is deployed there, so the agent walks it on dev right after the developer's merge deploys (line 6), before the task moves to QA, and the developer hears from the agent before the tester does. Either way the walk is recorded in the QA table like any other; "webhooks: tested on dev" by the QA person is no longer a row.
+   **Nothing else is the exception.** A blocked scenario is a step nobody has run, and a developer never receives one (Darren, 2026-10-28: "I don't want testing with our developers happening on tasks that you haven't validated locally"). Local reaches more than it looks: it shares dev's Twilio, SendGrid, Spaces, Gemini and BrightData keys, so a text can be sent from a number bought on Local, a real bounce can be made by sending a winner email to an address that does not exist, the SendGrid API key on the sendgrid provider row lists and clears that bounce (`GET`/`DELETE /v3/suppression/bounces`; no dashboard login is needed), and a campaign can be generated from a site with a page video. Each of those is a paid run or a vendor action, so it is parked, asked for in the end list with what it unblocks, and walked on Local once granted, before the task moves to Review (Darren, 2026-10-28, granted all three for Cherry). A Twilio number bought on Local lives in the shared account: once sync marks its row `verified`, a developer copies that one identity row into dev's test organization and dev's sync marks it Active on its next sweep, so dev needs no second purchase and no second three-day verification. A second member of the e2e organization (for the read-only scenarios) needs no vendor: invite one on Local and accept from the connected mailbox. **A fail inside a path the release changed is a bug to find, never a note on the list**: Cherry's winner emails did not arrive on Local and the list told the tester to "check the winner email on dev" instead.
 7. **Review.** `superpowers:code-reviewer` against the stories, then `ponytail-review`, on each repo's diff.
 8. Push the release branches.
 
@@ -96,7 +97,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 approved and cut to its release/ branch." 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), 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 step per check (what the tester does, then what they must see), fifteen steps at most (`drawbridge-asana-comment`; Darren, 2026-10-28, on a 52-step list: "It's insane to expect someone to go through this list"). 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 step per check (what the tester does, then what they must see), fifteen steps at most (`drawbridge-asana-comment`; Darren, 2026-10-28, on a 52-step list: "It's insane to expect someone to go through this list"). **Only the paths the subtask changed.** A story's other scenarios (the Klaviyo sync behind an SMS change, the Shopify reconnect behind a campaign picker, the Google accounts behind a logging change) are not walked again for this release (Darren, 2026-10-28: "we don't need unchanged paths"); that is how a list lands under fifteen without folding steps. **Build and log steps are the developer's.** A Dockerfile, a lockfile, a DigitalOcean build log or deployment status, a Sentry issue, an api log line: these go on the developer's list only, never on the QA list (Darren, 2026-10-28: "all build and log steps should be developer only not QA"). **Every step on both lists was run on Local in line 4**, by the agent, with the access the end list obtained; a step that was not run is not written (line 4 step 6). 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 description is rewritten whole at this point**: the original text, the Story lines, the two lists, nothing else. Build notes, "still to do" lines and parked items live in the release document, and one left in a description reads as unfinished work to the developer (Cherry's sample products subtask carried a "Still to do in Cherry" block after all three items were done). 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.
 
@@ -147,6 +148,8 @@ The cut stages the approved release for production and frees develop for the nex
 - 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.
+- Hand a developer or a tester a step the agent did not run on Local. A blocked scenario is parked and asked for, never written into a test list with a note (line 4 step 6).
+- Put a build, lockfile, deployment, log or Sentry step on the QA list. Those are the developer's (line 5 step 3).
 
 ## Section ids
 

package/bin/bump.js

@@ -88,7 +88,7 @@ const bumpOne = ({ projectsDir, repo, field, current, name, version, dry, push }
   const files = [ 'package.json', 'package-lock.json' ]
   if (name === '@drawbridge/drawbridge-agents') {
     try { run(dir, 'npx', [ 'drawbridge-agents-sync' ]) } catch (error) { /* the mirror is best-effort; the pin still lands */ }
-    files.push('.claude')
+    files.push('.claude', '.nvmrc')
   }
   run(dir, 'git', [ 'add', '-A', ...files.filter((f) => fs.existsSync(path.join(dir, f))) ])
   if (!run(dir, 'git', [ 'status', '--porcelain', '--', ...files ])) { console.log(repo + ': nothing to commit'); return }

package/conventions/walk-the-app.md

@@ -122,6 +122,22 @@ Claude can walk it as you. Vendor reference: https://code.claude.com/docs/en/chr
 This path is not available to a headless or SDK session, which is why the Playwright walk
 above is the one every handoff relies on.
 
+## A vendor step Local cannot reach is walked against dev, not parked
+
+Every update built on Local is walked before it is reported, with no exception for the
+step a vendor has to take part in (Darren, 2026-10-28: "make sure you have walked all
+updates when working locally. If you need to test a third party integration you might
+have to connect to the dev environment, but we must always do this"). Local shares dev's
+vendor keys, so most vendor steps run from Local directly: a text from a number bought on
+Local, a winner email to an address that does not exist for a real bounce, a campaign
+generated from a live site. The step Local cannot run is the one the vendor delivers
+inbound (a Twilio STOP, a Shopify order, a Stripe event), because every Local Environment
+points the webhooks URL at `localhost`. For that step the agent connects to dev: trigger
+the event against dev's number, store or account, read what dev wrote, and replay the
+captured `buffer` row into Local so the local sync handles it through the new code. The
+walk is recorded like any other. "Tested on dev by QA" or "blocked" is never the record
+for a step the agent could have reached on dev.
+
 ## What is enforced
 
 - The `drawbridge-asana-ship-handoff` skill requires the walk before a handoff comment.

package/package.json

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