@drawbridge/drawbridge-agents 0.1.78 → 0.1.80

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

@@ -22,52 +22,61 @@ The ten lines below are the release, as Darren confirmed them on 2026-10-22. The
 
 ## Line 1: start
 
-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" and stay there. `gh auth status` must pass; if it does not, stop and tell the person `brew install gh && gh auth login`. Other developers start releases from their own machines, so this is never assumed.
+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.
 
 ## Line 2: the one list
 
 For every subtask, find or write the story (`drawbridge-feature` step 1). Then ONE numbered list to the person who started the release, each item three plain sentences (`conventions/rules.md` rule 7), holding:
 
 - every unknown from every story;
-- **who on the development team takes the pull requests** (a GitHub username). Asked now so nobody needs to be present between lines 3 and 5. Never guess a reviewer;
-- **a package publish, if any subtask names `@drawbridge/components` or `@drawbridge/drawbridge-utils`**, in these words: this release publishes a package; the package is built, reviewed and merged to the package's `main` first; the person publishes it when asked (the skill cannot), the publish needs the one-time password until the automation token (queue task 1218041740718540) exists; the apps' pull requests cannot merge until their pin bumps resolve.
+- **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;
+- **a package publish, if any subtask names `@drawbridge/components` or `@drawbridge/drawbridge-utils`**, in these words: this release publishes a package; the package is built first and gets its own pull request to the package's `main`; once that merges the person publishes from `main` (`npm run build`, the one-time password, until the automation token, queue task 1218041740718540, exists); the skill then bumps the pin in every consumer and no app pull request opens before the registry has the version. Line 4 step 2 is the exact sequence.
 
-Wait for the yes. Nothing below runs before it.
+Wait for the yes. Nothing below runs before it. A release that publishes a package stops once more, at the publish (line 4 step 2); everything else between lines 3 and 5 runs without anyone present.
 
 ## Line 3: Building
 
-1. Move the task to Building (`POST /sections/1219601033297172/addTask { task }`).
-2. `release/<id>` in every repo a subtask touches, off `develop` (components and utils off `main`; docs off `main`), each in a worktree under `/Users/darrenshea/Projects/.worktrees/<repo>-release-<id>` so no main checkout changes branch.
+1. **One release at a time.** List the project's tasks (`GET /projects/1219601041167594/tasks?opt_fields=name,memberships.section.name`). If any other release sits in Building, Review, QA or Approved, stop and say which one; only one release is being built or tested at a time (Darren, 2026-10-22). Then move this task to Building (`POST /sections/1219601033297172/addTask { task }`).
+2. `release/<id>` in every repo a subtask touches, off `develop` (components and utils off `main`), each in a worktree under `/Users/darrenshea/Projects/.worktrees/<repo>-release-<id>` so no main checkout changes branch. **drawbridge-docs is the exception**: its `release/<id>` branch is made in the main docs checkout (docs is `main`-only and single-writer), because `npx drawbridge-agents-check-stories` reads nothing from a worktree path (Asana 1218852240225835). "Repo a subtask touches" includes docs, components and utils, not only the six apps.
 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 the task link into `drawbridge-api/release.json`, commit on the api's `develop` directly ("release <id>: band"), push. Dev shows the yellow band above the account once the api redeploys. This is the only develop commit before the pull requests merge.
-5. If the release task has no subtask named "Marketing: What's new", create one.
+4. If `drawbridge-api/release.json` does not already carry this task's link, write it, commit on the api's `develop` directly ("release <id>: band"), push; dev shows the yellow band above the account once the api redeploys. This is the only develop commit before the pull requests merge. When the link is already there, say so and move on.
+5. 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. **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
 
 All work on the release branches against the **Local** database. Develop and its schema are never touched while a release is being built, and one release at a time is promoted to develop.
 
-1. **Local up.** `npm run migrate -- refresh` in the api (copies dev into Local; `--dry` first), then `npm run local` in every app the release touches: dashboard 3000, share 3001, website 3002, api 4000, sync 4001, webhooks 4002. The scripts force the ports; nothing sets them.
-2. **Package first.** A package subtask is built, reviewed and merged to the package's `main` before any app subtask that depends on it; when it is merged, ask the person to publish, then bump the pin on the apps' release branches.
+1. **Local up.** `npm run migrate -- refresh` in the api (copies dev into Local; `--dry` first), then `npm run local` in every app the release touches: dashboard 3000, share 3001, website 3002, api 4000, sync 4001, webhooks 4002; the components app (`npm run app` in drawbridge-components) is 3003. The scripts force the ports; nothing sets them.
+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 publish is the earliest thing the person is asked for, and it never pauses the build (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 `release/<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. Put the link on the release task.
+   3. Ask the person for the publish, as one numbered item with the exact words: merge that pull request, then from the package checkout on `main`: `git pull && npm run build` (tsup, tests, `npm publish` with the one-time password), then confirm with `npm view <package> version`.
+   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 (checked between subtasks, never by stopping): 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 `release/<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.
 3. **Per subtask**, on the release branch: read the story and the reference page, one graph query, failing test first where a suite exists, the change, `npm test` in that repo. One commit per subtask, its message starting with the subtask id.
-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. 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.
+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, take a snapshot) 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 from `drawbridge-tests/fixtures/e2e-org.md`, present on Local because Local is a copy of dev). 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").
+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.
 7. **Review.** `superpowers:code-reviewer` against the stories, then `ponytail-review`, on each repo's diff.
 8. Push the release branches.
 
 ## Line 5: Review
 
+Only when every repo's release branch is finished: every subtask committed, `npm test` green in each repo, every QA report at `fails : 0`, both review passes done, the branches pushed. A pull request is the request to review, so it exists only once there is something to review.
+
 1. One pull request per repo: `gh pr create --base develop --head release/<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. Fill the Branches table in `releases/<id>.md` with the PR links; commit.
-3. Put the PR links on the release task as ONE numbered list (`drawbridge-asana-comment`), assign the task to the developer, move it to Review (`POST /sections/1219762451512990/addTask`).
+3. 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`), assign the task to the developer, move it to Review (`POST /sections/1219762451512990/addTask`).
 4. Stop. Report the PR links.
 
 ## Lines 6 to 8: the developer and the QA person
 
 The skill does none of this. For the record, so the skill can answer "what is the next step":
 
-- Line 6, the developer: reviews the diff, runs the branch locally, approves and merges. Dev deploys itself. If there is a migration: `npm run migrate -- <id> --dry --env dev` from the api checkout on `develop`, read the printed result, then without `--dry`. Then moves the task to QA and assigns the QA person in Asana.
+- Line 6, the developer: reviews the diff, runs the branch locally, approves and merges. Dev deploys itself. If there is a migration: `npm run migrate -- <id> --dry --env dev` from the api checkout on `develop`, read the printed result, then without `--dry`. The developer may have an agent run those two dev commands on their explicit instruction in their own session (Darren, 2026-10-22); the skill never runs them on its own, and no agent ever runs the production one. Then moves the task to QA and assigns the QA person in Asana.
 - Line 7, the QA person: tests on dev. The band already names the release.
 - Line 8, the QA person: moves the task to Approved.
 
@@ -77,23 +86,23 @@ The skill does none of this. For the record, so the skill can answer "what is th
 
 1. Confirm the task sits in Approved; refuse otherwise.
 2. Hand over the preparation: the window (avoid 00:00 and 02:00 UTC, sync's scheduled jobs) and the Atlas snapshot. Wait.
-3. Per app, in this order unless the release doc says otherwise (dashboard, api, sync, share, webhooks, website): hand over the fast-forward of `main` to the exact tested `develop` commit (`git push origin <sha>:refs/heads/main`), then the Deploy click in DigitalOcean (prod apps deploy from `main` with deploy-on-push off). Verify by reading: the deployment ACTIVE, `/health` reporting the commit. Note the commit in the release doc's Promote section.
-4. Migration, after the api is ACTIVE and before sync: from the developer's api checkout on `main` at the promoted commit, with the api's two-line `.env.production` beside `migrate.js`: `npm run migrate -- <id> --env prod --dry --sha <promoted api commit>`, read the result, then without `--dry`. (The deployed api container can run it too, through `doctl apps console`.) Then `git rm drawbridge-api/scripts/migration-<id>.js`, committed on develop, and `main` fast-forwarded once more.
+3. Per app, in this order unless the release doc says otherwise (dashboard, api, sync, share, webhooks, website): hand over the fast-forward of `main` to the exact tested `develop` commit (`git push origin <sha>:refs/heads/main`), then the Deploy click in DigitalOcean (prod apps deploy from `main` with deploy-on-push off). Verify by reading: the deployment ACTIVE through the DigitalOcean MCP server registered in Claude Code (`apps-get-deployment-status`; the release doctor checks it is there, and no machine needs doctl), `/health` reporting the commit. Note the commit in the release doc's Promote section.
+4. Migration, after the api is ACTIVE and before sync: from the developer's api checkout on `main` at the promoted commit, with the api's two-line `.env.production` beside `migrate.js`: `npm run migrate -- <id> --env prod --dry --sha <promoted api commit>`, read the result, then without `--dry`. (The deployed api container can run it too, from the api component's Console in the DigitalOcean dashboard.) Then `git rm drawbridge-api/scripts/migration-<id>.js`, committed on develop, and `main` fast-forwarded once more.
 5. Hand over the verification list from the release doc's Promote section; the developer reports what they saw; the skill fills it in.
 
 ## Line 10: Released
 
-1. **What's new.** Write the marketing breakdown into the "Marketing: What's new" subtask, in the customer's words, one item per subtask a merchant would notice (`drawbridge-asana-comment` for the shape, `humanizer` for the words).
+1. **What's new.** Create the "Marketing: What's new" subtask on the release task now (`POST /tasks/<id>/subtasks`), with the marketing breakdown as its description, in the customer's words, one item per subtask a merchant would notice (`drawbridge-asana-comment` for the shape, `humanizer` for the words), and complete it in the same step (`PUT /tasks/<subtask> { completed : true }`). It exists only finished; a release never carries an open marketing subtask.
 2. Complete every subtask (Application → Complete). Move the release task to Released (`POST /sections/1219601137919036/addTask`).
 3. Remove the worktrees; refresh the knowledge graph (`drawbridge-ship-feature` step 5). Report the promoted commits.
 
 ## What the skill never does
 
-- Push `main`, deploy production, run anything against the production or dev database, publish a package, merge a pull request, assign the QA person or move the task to QA, Approved. Those are a developer's or a tester's lines.
-- Name a reviewer, a tester, a window or a release scope that nobody told it. Each is one numbered question in line 2.
+- 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.
+- 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.
 - 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.
 
 ## Section ids
 
-Planned `1219601041167595`, Building `1219601033297172`, Review `1219762451512990`, QA `1219601033155111`, Approved `1219601033299066`, Released `1219601137919036`; project `1219601041167594`, workspace `15457086713130`.
+Releases project `1219601041167594` (workspace `15457086713130`): Planned `1219601041167595`, Building `1219601033297172`, Review `1219762451512990`, QA `1219601033155111`, Approved `1219601033299066`, Released `1219601137919036`. Application project `1207845659550631`, where the subtasks live: Queue `1207845659550632` (not scheduled), In progress `1211315620607633` (in a release), Complete `1213887707425532`.

package/bin/bump.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Bump one @drawbridge package to an exact version in EVERY consumer in the family,
+// lockfile included, one commit per repo on its current branch, pushed.
+//
+//   npx drawbridge-agents-bump @drawbridge/components 0.1.6
+//   npx drawbridge-agents-bump @drawbridge/drawbridge-agents 0.1.80 --no-push
+//   npx drawbridge-agents-bump @drawbridge/drawbridge-utils 0.0.222 --only drawbridge-api,drawbridge-sync
+//   … --dry                     list the consumers and stop
+//
+// Pins are version-exact family-wide (conventions/drawbridge-packages.md), so a
+// publish is not finished until every consumer names it: the release skill runs
+// this the moment the registry has the version (Darren, 2026-10-22: "Once a
+// package is published, all consumer pins should also be updated"). A consumer's
+// own place for the package (dependencies, devDependencies, peerDependencies) is
+// kept. Bumping the agents package also mirrors its template into .claude.
+const { execFileSync } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+const FLAGS = { dependencies: '--save', devDependencies: '--save-dev', peerDependencies: '--save-peer' }
+
+// Which repos pin `name`, and under which field. `manifests` is { repoName: packageJson }.
+const consumersOf = (manifests, name) => Object.entries(manifests)
+  .map(([ repo, pkg ]) => {
+    const field = Object.keys(FLAGS).find((key) => pkg && pkg[key] && pkg[key][name])
+    return field ? { repo, field, current: pkg[field][name] } : null
+  })
+  .filter(Boolean)
+  .sort((a, b) => a.repo.localeCompare(b.repo))
+
+const saveFlag = (field) => FLAGS[field]
+
+// A pin lands on an integration branch or the release's own branch, never on a
+// stray feature branch someone left checked out (growth-b sat on ship-main).
+const takesBump = (branch) => branch === 'develop' || branch === 'main' || branch.startsWith('release/')
+
+const readManifests = (projectsDir) => Object.fromEntries(
+  fs.readdirSync(projectsDir)
+    .filter((entry) => entry.startsWith('drawbridge-') && fs.existsSync(path.join(projectsDir, entry, 'package.json')) && fs.existsSync(path.join(projectsDir, entry, '.git')))
+    .map((entry) => {
+      try { return [ entry, JSON.parse(fs.readFileSync(path.join(projectsDir, entry, 'package.json'), 'utf8')) ] } catch (error) { return [ entry, null ] }
+    })
+)
+
+const run = (cwd, cmd, args) => execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: [ 'ignore', 'pipe', 'pipe' ] }).trim()
+
+const main = () => {
+  const argv = process.argv.slice(2)
+  const [ name, version ] = argv
+  const dry = argv.includes('--dry')
+  const push = !argv.includes('--no-push')
+  const onlyIndex = argv.indexOf('--only')
+  const only = onlyIndex === -1 ? null : new Set(argv[onlyIndex + 1].split(','))
+
+  if (!name || !version || !/^\d+\.\d+\.\d+/.test(version)) {
+    console.error('usage: drawbridge-agents-bump <@drawbridge/package> <exact version> [--dry] [--no-push] [--only repo,repo]')
+    process.exit(1)
+  }
+
+  const projectsDir = path.resolve(process.cwd(), '..')
+  const consumers = consumersOf(readManifests(projectsDir), name).filter((c) => !only || only.has(c.repo))
+
+  if (!consumers.length) {
+    console.error('no consumer of ' + name + ' under ' + projectsDir)
+    process.exit(1)
+  }
+
+  for (const { repo, field, current } of consumers) {
+    const dir = path.join(projectsDir, repo)
+    const branch = run(dir, 'git', [ 'branch', '--show-current' ])
+    if (current === version) { console.log(repo + ': already ' + version + ' (' + field + ', ' + branch + ')'); continue }
+    if (!takesBump(branch)) { console.log(repo + ': skipped, on ' + (branch || 'a detached head') + ' (check out develop, main or release/<id> first)'); continue }
+    if (dry) { console.log(repo + ': ' + current + ' -> ' + version + ' (' + field + ', ' + branch + ')'); continue }
+    run(dir, 'npm', [ 'install', '--save-exact', saveFlag(field), name + '@' + version, '--no-audit', '--no-fund', '--loglevel=error' ])
+    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')
+    }
+    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'); continue }
+    run(dir, 'git', [ 'commit', '-q', '-m', name.replace('@drawbridge/', '') + ' ' + version ])
+    if (push) run(dir, 'git', [ 'push', '-q', 'origin', branch ])
+    console.log(repo + ': ' + current + ' -> ' + version + ' on ' + branch + (push ? ', pushed' : ''))
+  }
+}
+
+module.exports = { consumersOf, readManifests, saveFlag, takesBump }
+
+if (require.main === module) main()

package/bin/release-doctor.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Everything a release needs on this machine, checked in one go before line 1 of
+// the release skill, printed as ONE numbered list of what is missing with the fix
+// for each. Exit 1 when anything required is missing, so a developer on a new
+// machine fails in ten seconds, not an hour in.
+//
+//   npx drawbridge-agents-release-doctor
+//
+// Required: git, gh signed in, op on the beta channel (--environment), the api's
+// .env.local and .env.development naming a 1Password Environment, the Local and
+// dev clusters resolving, the npm registry reachable, the DigitalOcean MCP server
+// registered in Claude Code. Warned, not required: graphify (the read-before-write
+// gate skips it when absent).
+const { execFileSync } = require('child_process')
+const dns = require('dns')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+process.env.PATH = [ path.join(os.homedir(), '.local', 'bin'), '/opt/homebrew/bin', '/usr/local/bin', process.env.PATH || '' ].join(path.delimiter)
+
+const sh = (cmd, args) => { try { return execFileSync(cmd, args, { encoding: 'utf8', stdio: [ 'ignore', 'pipe', 'pipe' ] }) } catch (error) { return null } }
+
+// A two-line env file: OP_SERVICE_ACCOUNT_TOKEN and OP_ENVIRONMENT_ID, both with a value.
+const envFileOk = (text) => {
+  const keys = {}
+  for (const line of String(text || '').split('\n')) {
+    const match = line.match(/^\s*([A-Z_]+)\s*=\s*['"]?([^'"\s]*)['"]?\s*$/)
+    if (match) keys[match[1]] = match[2]
+  }
+  return Boolean(keys.OP_SERVICE_ACCOUNT_TOKEN && keys.OP_ENVIRONMENT_ID)
+}
+
+// Deployments are read through the DigitalOcean MCP server registered in Claude Code
+// at user scope (~/.claude.json, `mcpServers.digitalocean`), the way Darren's machine
+// has it; every developer's machine is set up to match (Darren, 2026-10-22). doctl is
+// not used anywhere in the flow.
+const readClaudeConfig = () => { try { return JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8')) } catch (error) { return null } }
+const hasDigitalOcean = (config) => Boolean(config && config.mcpServers && config.mcpServers.digitalocean && config.mcpServers.digitalocean.url)
+
+// The printed list: one numbered line per failure, each with its fix; nothing when all pass.
+const report = (results) => {
+  const failed = results.filter((r) => !r.ok)
+  if (!failed.length) return 'release doctor: everything present (' + results.length + ' checks).'
+  return 'release doctor: ' + failed.length + ' of ' + results.length + ' missing.\n' + failed.map((r, i) => (i + 1) + '. ' + r.name + (r.required ? '' : ' (optional)') + ': ' + r.fix).join('\n')
+}
+
+const checks = (projectsDir) => {
+  const api = path.join(projectsDir, 'drawbridge-api')
+  const read = (file) => { try { return fs.readFileSync(path.join(api, file), 'utf8') } catch (error) { return null } }
+  return [
+    { name: 'git', required: true, ok: Boolean(sh('git', [ '--version' ])), fix: 'install Xcode command line tools' },
+    { name: 'gh signed in', required: true, ok: Boolean(sh('gh', [ 'auth', 'status' ])), fix: 'brew install gh && gh auth login' },
+    { name: 'op with --environment (beta channel)', required: true, ok: /--environment/.test(sh('op', [ 'run', '--help' ]) || ''), fix: 'install the 1Password CLI beta: see drawbridge-growth/scripts/op.sh for the curl line' },
+    { name: 'drawbridge-api/.env.local', required: true, ok: envFileOk(read('.env.local')), fix: 'two lines, OP_SERVICE_ACCOUNT_TOKEN and OP_ENVIRONMENT_ID, naming the Local Environment' },
+    { name: 'drawbridge-api/.env.development', required: true, ok: envFileOk(read('.env.development')), fix: 'two lines naming the Development Environment' },
+    { name: 'drawbridge-api/scripts/op.sh', required: true, ok: fs.existsSync(path.join(api, 'scripts', 'op.sh')), fix: 'pull develop in drawbridge-api' },
+    { name: 'npm registry', required: true, ok: Boolean(sh('npm', [ 'view', '@drawbridge/drawbridge-agents', 'version' ])), fix: 'check the network or npm login' },
+    { name: 'DigitalOcean MCP server in Claude Code', required: true, ok: hasDigitalOcean(readClaudeConfig()), fix: 'claude mcp add --scope user --transport http digitalocean https://apps.mcp.digitalocean.com/mcp --header "Authorization: Bearer <your DigitalOcean API token>" (the skill reads deployments through it; no doctl)' },
+    { name: 'graphify', required: false, ok: Boolean(sh('graphify', [ '--version' ])), fix: 'npm run sync installs it; or DRAWBRIDGE_SKIP_GRAPHIFY=1' }
+  ]
+}
+
+const resolves = (host) => dns.promises.resolveSrv('_mongodb._tcp.' + host).then(() => true, () => false)
+
+const main = async () => {
+  const projectsDir = path.resolve(process.cwd(), '..')
+  const results = checks(projectsDir)
+  results.push({ name: 'Local cluster resolves', required: true, ok: await resolves('cluster0.sbftndf.mongodb.net'), fix: 'the Local Atlas cluster is paused or gone; resume it in Atlas' })
+  results.push({ name: 'dev cluster resolves', required: true, ok: await resolves('cluster0.1iourxk.mongodb.net'), fix: 'check the network' })
+  console.log(report(results))
+  process.exit(results.some((r) => r.required && !r.ok) ? 1 : 0)
+}
+
+module.exports = { checks, envFileOk, hasDigitalOcean, report }
+
+if (require.main === module) main()

package/conventions/cross-repo-contracts.md

@@ -20,12 +20,14 @@ skill) so it stops living only in tribal memory.
   (fails closed). Deploy order matters: ship app-web **before** api, or the api blocks every
   signin that arrives without a token. See `drawbridge-docs/user-stories/03-auth`.
 - `BASIC_AUTH_USERNAME` + `BASIC_AUTH_PASSWORD` is the shared basic-auth staging-gate pair read
-  by **drawbridge-website** (`middleware.js`) and **drawbridge-app-web** (`proxy.js`) — same
-  names in both so one credential pair gates both dev deployments. The gate arms only when
-  **both** are set (fails open: a missing/misnamed var silently leaves the deployment public —
-  unset both in prod, set both in dev). Exempt: app-web `/api/health` (platform health checks)
-  and website Builder preview traffic. Not related to OAuth/session auth, which runs after the
-  gate unchanged.
+  by **drawbridge-website** (`proxy.js`), **drawbridge-app-web** (`proxy.js`) and, since
+  2026-10-22, **drawbridge-components** (`server.js`, the components app at
+  components.trydrawbridge.com, where the pair is set directly on the DO app rather than
+  through a 1Password Environment) — same names everywhere so one credential pair gates
+  all three. The gate arms only when **both** are set (fails open: a missing/misnamed var
+  silently leaves the deployment public — unset both in prod, set both in dev). Exempt:
+  app-web `/api/health`, components `/health` (platform health checks) and website Builder
+  preview traffic. Not related to OAuth/session auth, which runs after the gate unchanged.
 
 ## Sync owns reactive side effects
 

package/conventions/migrations.md

@@ -1,6 +1,6 @@
 # Migrations live in the api
 
-Every one-off migration and backfill goes in `drawbridge-api/scripts.js`.
+Every one-off migration and backfill is one file in `drawbridge-api/scripts/`, `migration-<release asana id>.js`, run through `drawbridge-api/migrate.js` and nothing else.
 
 **The only exception is media processing** — work that needs ffmpeg or sharp to
 open an image or a video. Those dependencies exist in `drawbridge-sync` and
@@ -46,23 +46,31 @@ quietly that dev served stale code the whole time.
   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>`.
+  `npm run migrate -- <release asana id> --dry --env dev`, then
+  `--organization <org id> --env dev`, then `--env dev`. There is no `--release`
+  flag: the migration id IS the release id.
   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 <release asana id> --env prod --dry --sha <promoted commit>`, then the
-  same without `--dry`. 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.
+- **Production is run by a developer, by hand, from their api checkout** on
+  `main` at the promoted commit with a clean tree, with the api's two-line
+  `.env.production` beside `migrate.js` (Darren, 2026-10-22: "the api is the
+  only place that needs this, and locally it's there"):
+  `npm run migrate -- <release asana id> --env prod --dry --sha <promoted commit>`,
+  then the same without `--dry`. The runner refuses production off `main`, at
+  the wrong commit, or with `scripts/`, `lib/` or `migrate.js` modified. The
+  deployed api container can run it too (the api component's Console in the
+  DigitalOcean dashboard, then the `op run --environment "$OP_ENVIRONMENT_ID" --
+  node migrate.js …` form; nobody installs doctl for this; the image carries `migrate.js` and `scripts/`, there is no
+  git, so `--sha` is proven against `APP_COMMIT_HASH`). An agent never runs it:
+  it hands the developer the command and verifies by reading afterwards. The
+  dev run is different: a developer may ask an agent in their own session to run
+  the two `--env dev` commands and show the result, since the guard admits only
+  the dev cluster whoever types it (Darren, 2026-10-22). Never unasked, and
+  never production.
 - **The runner records nothing but its counts file**, and nothing else records
   a run either: a developer runs the migration on dev after the pull request
   merges and reads the printed result, and runs it on production from their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -16,7 +16,9 @@
     "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-streams": "scripts/check-streams.js"
+    "drawbridge-agents-check-streams": "scripts/check-streams.js",
+    "drawbridge-agents-bump": "bin/bump.js",
+    "drawbridge-agents-release-doctor": "bin/release-doctor.js"
   },
   "files": [
     "claude",