@drawbridge/drawbridge-agents 0.1.74 → 0.1.76

package/.claude-template/skills/drawbridge-asana-comment/SKILL.md

@@ -23,8 +23,9 @@ bulleted section beside it. In order:
 1. What changed, in plain past tense. Numbered.
 2. What they need before the first step: a permission to grant, a setting to switch on, a
    record that has to exist. One item each.
-3. What to do and what to expect. One step per item, each one something they can actually do
-   or check. Every step starts with the click path from where they already are (Admin,
+3. What to do and what to expect. One step per item, one action per step (rules.md rule 9),
+   each one something they can actually do or check. "Open the campaign and click Draw" is
+   two steps. Every step starts with the click path from where they already are (Admin,
    Connections, then the store; Shopify admin, Apps, then Drawbridge). "Open the app" is not a
    path.
 4. Anything that would otherwise look wrong to them. Numbered too.

package/conventions/git-branching.md

@@ -7,7 +7,7 @@ Branches use the **full gitflow prefixes, always spelled out**. Never use abbrev
 | `feature/<name>` | New features / changes (branched from `develop`) |
 | `bugfix/<name>` | Non-urgent bug fixes |
 | `hotfix/<name>` | Urgent production fixes (branched from `main`) |
-| `release/<version>` | Release preparation |
+| `release/<asana id>` | A release (since 2026-10-21): the Releases project task id, the same id as `drawbridge-api/scripts/migration-<id>.js` and `drawbridge-docs/releases/<id>.md`; one branch per app the release touches, off `develop`, built against the Local database, merged by a developer through a pull request |
 | `chore/<name>` | Maintenance — dependency bumps, config, cleanup |
 | `support/<name>` | Long-lived support branches |
 

package/conventions/migrations.md

@@ -29,11 +29,50 @@ quietly that dev served stale code the whole time.
 
 ## How
 
-- Add the function to `drawbridge-api/scripts.js`, alongside the others.
-- Add a commented invocation to the numbered run-list at the bottom. Nothing runs
-  until somebody uncomments a line and deploys.
-- Take `dryRun` and report what it would do. The first run of a migration is a
-  read.
+- One release has at most one migration file,
+  `drawbridge-api/scripts/migration-<release asana id>.js`, named for the
+  RELEASE task (the same id as the `release/<id>` branches and
+  `drawbridge-docs/releases/<id>.md`), holding every data step the release
+  needs and exporting
+  `({ controller }) => async ({ dryRun, organization, ...args }) => counts`.
+  Nothing at boot requires `scripts/`; `test/migrations-folder.test.js` refuses
+  any other file there. **The folder only ever holds what production has not
+  run**: once the production run is recorded, `git rm` the file (the promote
+  step will do this), so two releases in flight are two files and no spent code
+  lingers. (Until 2026-10-21 these were functions in one
+  `scripts.js` that boot required and that kept its fifteen spent functions for
+  a month; Darren, 2026-10-21: "avoids old code kicking around".)
+- Take `{ dryRun, organization }` and report what it would do as the object you
+  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>`.
+  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 <asana id> --env prod --dry --sha <promoted commit>`, then the same
+  without `--dry` and with `--release <slug>`. 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.
+- A real fleet run records itself when drawbridge-docs sits beside the api:
+  `drawbridge-docs/releases/<slug>.json` gets
+  `migrations.<asana id>.<development|production> = true`, and the release
+  document `releases/<slug>.md` gets a row in its Migrations table. That is how
+  "has it run on prod?" is answered. In the container there is no docs checkout:
+  the runner prints exactly which flag and row to write, and you commit them
+  from a laptop from the counts file. After a production run the promote step
+  deletes `scripts/migration-<asana id>.js`, so the folder only ever holds what
+  has not run.
 - Add it to the release document in `drawbridge-docs/releases/` for the launch it
   belongs to, with the ordering constraint stated: what has to be deployed before
   it can run, and what breaks if it runs early.

package/conventions/rules.md

@@ -36,3 +36,7 @@
 8. Never make it up. A statement of fact in anything you write to a person is backed by something you read in this session: a file you opened whole, a doc in `drawbridge-docs`, the knowledge graph, a vendor's documentation you fetched, a value you measured. If none of those backs it, it is not a fact yet: say "I do not know" or put it to Darren as a numbered question. Never write a step in the past tense for something you have not done ("Updated the step in the task" when nothing was edited). Never describe a thing as absent because you have not found it yet; rule 6 says how to search first.
 
    Why: a confident sentence with nothing behind it reads exactly like a verified one, and the reader builds on it. It has sent a tester hunting for a badge that did not exist, described a repo as missing code that was in another package, and promised an edit that had not happened. Every one of those was cheaper to ask about than to correct afterwards.
+
+9. Write in the spirit of ASD-STE100. One idea per sentence, with an active verb, in about 20 words. A procedural step is one action: "Open the campaign. Click Draw." never "Open the campaign and click Draw". A condition or warning comes before the step it applies to, never after. One word has one meaning for the whole reply: do not swap in synonyms for variety, and write "must" for a requirement and "we recommend" for advice, never "should". The STE dictionary is not in force; use the words the team uses (rule 7).
+
+   Why: STE exists so that a reader who skims under pressure cannot misread a step. That is Jaime reading a retest list and Darren reading a question. Darren, 2026-10-21, asked for the spirit of STE and not the letter.

package/package.json

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

package/scripts/check-stories.js

@@ -35,7 +35,7 @@ const UNDO = [
   [ /\bpublish(es|ed|ing)?\b/i, /\bunpublish/i, 'publish', 'unpublish' ],
   [ /\bpaus(e|es|ed|ing)\b/i, /\bresum(e|es|ed|ing)\b/i, 'pause', 'resume' ],
   [ /\benabl(e|es|ed|ing)\b/i, /\bdisabl(e|es|ed|ing)\b/i, 'enable', 'disable' ],
-  [ /\barchiv(e|es|ed|ing)\b/i, /\b(unarchiv|restor)/i, 'archive', 'restore' ]
+  [ /\barchiv(e|es|ed|ing)\b|\bwrit(e|es|ing)\s+(it\s+)?off\b/i, /\b(unarchiv|restor)/i, 'archive or write off', 'restore' ]
 ]
 
 const findFamilyRoot = () => {