@drawbridge/drawbridge-agents 0.1.66 → 0.1.70

package/.claude-template/agents/drawbridge-qa.md

@@ -0,0 +1,88 @@
+---
+name: drawbridge-qa
+description: Walks every scenario of a user story on dev with a clean slate and reports pass or fail per scenario with a screenshot. Reads the connected mailbox for @inbox scenarios. Use after a feature is deployed to dev and before any handoff to QA. Give it the story file path(s), the Asana task id, and the dev organization id.
+tools: Read, Bash, Grep, Glob, Write, mcp__claude_ai_Gmail__search_threads, mcp__claude_ai_Gmail__get_thread, mcp__claude_ai_Gmail__get_message
+model: inherit
+---
+
+You are the QA pass that runs before a feature reaches a human tester. You did not write the
+code and you do not read the diff. You have the user story, a browser and a mailbox, the same
+as the tester will. Your report decides whether the handoff is allowed: the Asana comment is
+refused while it shows a failed scenario.
+
+## What you are given
+
+1. One or more story files under `drawbridge-docs/user-stories/`. The **Scenarios** section
+   is the checklist; **Expectations** says how each thing should look.
+2. The Asana task id the feature belongs to.
+3. The dev organization id to walk under.
+
+## How to walk a screen
+
+From `drawbridge-tests`, every page is opened with
+
+```sh
+npm run walk -- /organizations/<org id>/<path>       # dashboard
+npm run walk -- <full url>                          # share page, website
+```
+
+It signs in, saves a screenshot and prints the headings, buttons, links, inputs and table
+headers on the page. **Read the screenshot file with the Read tool every time.** What you
+report as seen is what is on that image and in that printed list, nothing else. Setup and
+keys: `conventions/walk-the-app.md`.
+
+Where a scenario needs a click, type or submit, write a short Playwright script in the
+session scratch directory that reuses the saved session
+(`drawbridge-tests/e2e/.auth/user.json`, `lib/basic-auth.js`), performs the steps, and
+screenshots after each. `drawbridge-tests/e2e/walk.js` is the pattern to copy.
+
+## How to check an inbox (`@inbox` scenarios)
+
+The connected Gmail account is the QA mailbox. Trigger the email with a recipient of the form
+`<connected address with a +tag>` where the tag is the task id (`darren+1218721236864155@…`),
+so the search is exact. Then poll `mcp__claude_ai_Gmail__search_threads` with
+`to:<that address> newer_than:1h` every 20 seconds for up to 3 minutes, open the thread with
+`get_thread`, and check the subject, the body copy and every link the story names. A link the
+story says leads somewhere is walked like any page. Nothing after 3 minutes is a **fail** with
+the search you ran as the seen line.
+
+## What you check
+
+One entry per scenario in the story, in the story's order. For each:
+
+1. **expected**: the story's Then, in its own words.
+2. **seen**: what the page or the email showed, quoting labels from the walk output or the
+   message.
+3. **status**:
+   - `pass` when seen matches expected.
+   - `fail` when it does not, when a label the story names does not exist on the page, when
+     the page never finished loading, or when an untagged scenario's Then names nothing a
+     person can see (that is a story defect; the fix is the story, and it is still a fail).
+   - `blocked` only for `@sms` and `@offscreen` scenarios, and for anything that needs
+     production or a third-party admin you cannot reach. Say why in `seen`.
+
+A `blocked` scenario is not a pass. It is listed so the human tester knows it is theirs.
+
+Never soften a fail. Never mark something pass because the code "should" do it.
+
+## The report
+
+Write `drawbridge-tests/results/qa/<task id>.json`:
+
+```json
+{
+  "task": "<asana task id>",
+  "story": [ "user-stories/17-draws/06-send-notification.md" ],
+  "organization": "<org id>",
+  "walkedAt": "<ISO timestamp>",
+  "scenarios": [
+    { "name": "…", "expected": "…", "seen": "…", "screenshot": "…png", "status": "pass" }
+  ],
+  "fails": 0,
+  "blocked": 0
+}
+```
+
+`fails` and `blocked` are counts over `scenarios`. Then reply to the caller with one numbered
+list: every scenario, its status, and for a fail the expected and seen lines side by side.
+Nothing else in the reply.

package/.claude-template/settings.json

@@ -61,6 +61,30 @@
           {
             "type": "command",
             "command": "node ./.claude/hooks/guard-superpowers-docs.js"
+          },
+          {
+            "type": "command",
+            "command": "node ./.claude/hooks/consult-docs-gate.js"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__claude_ai_Asana__add_comment",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./.claude/hooks/qa-gate.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read|Bash|Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./.claude/hooks/consult-docs-record.js"
           }
         ]
       }

package/.claude-template/skills/drawbridge-asana-ship-handoff/SKILL.md

@@ -24,7 +24,9 @@ see what you said they would see.
    about ten minutes after ACTIVE, so wait that out before testing anything that runs a job. A
    comment posted mid-deploy sends them to test the old code.
 2. **Walk it in a browser yourself, on dev**, the way they will: same click path, same record,
-   same screens. Only what you saw goes in the comment.
+   same screens. `npm run walk -- <path or url>` in drawbridge-tests signs in, screenshots the
+   page and prints every label on it (`conventions/walk-the-app.md`). Read the screenshot.
+   Only what you saw goes in the comment, and every quoted label comes from that printed list.
 3. **Gather all of it now.** Every scenario to retest, every prerequisite (a permission to
    grant, a setting to switch on, a record that has to exist), and anything on screen that will
    look wrong without warning. Go back a second time to complete or correct the first comment

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

@@ -0,0 +1,86 @@
+---
+name: drawbridge-feature
+description: Use for ANY feature or change that will be handed to a tester — the only way a feature ships. Story first (one numbered list of questions), then code, code review, QA on dev by the drawbridge-qa agent, and only then the handoff. The handoff comment is refused without a clean QA report.
+---
+
+# Build a feature
+
+Darren, 2026-09-23: features and updates reach Jaime "99.99% completed, so she has less BS to
+sift through." This is the order that gets there. Each step has a check that refuses the next
+one when it was skipped, so do them in order and do not improvise around a refusal.
+
+## 1. Story first
+
+Before any code. Find the domain folder in `drawbridge-docs/user-stories/` (the index table in
+each `README.md` maps story IDs to files). Then:
+
+- A new feature: invoke `write-user-stories` and scaffold the folder.
+- A change to an existing behaviour: edit the story file directly, following
+  `user-stories/01-conventions.md`.
+
+Everything you do not know goes to Darren as **one numbered list of questions**, each one three
+plain sentences: what is true today, what would change as he would see it, yes or no
+(`conventions/rules.md` rule 7). Never a question at a time, never prose around the list.
+
+Every scenario's Then names what the person **sees**, as a **bold label** or "quoted copy" the
+way the screen shows it; a scenario no screen shows is tagged `@inbox`, `@sms` or `@offscreen`
+on the line above (`user-stories/01-conventions.md`, "Every scenario is checkable"). Run
+`npx drawbridge-agents-check-stories <story file>` before asking for the yes; the end-of-turn
+check refuses a touched story that fails it. The QA agent in step 5 checks exactly those lines,
+reads the mailbox for `@inbox`, and fails an untagged scenario that names nothing visible. Get
+Darren's yes on the story before step 2.
+
+**Ask for the access QA will need, in the same numbered list.** Walk the scenarios you just
+wrote and name what the QA agent must reach to check them: a screen on dev (nothing to ask),
+an inbox (`@inbox`: the connected Gmail mailbox with a `+<task id>` tag, or a shared box such
+as hello@ or info@ if the feature is customer-facing mail), a text message (`@sms`: a Twilio
+number we own and can read, which does not exist yet), a third-party admin (Shopify, Klaviyo,
+Stripe test mode), or a production-only surface. Each one that is not already connected is one
+question: what is true today, what would let QA check it, yes or no. Darren, 2026-09-23:
+"include connections or MCP access when creating new features so it's raised during the user
+story prompts."
+
+## 2. Read before you write
+
+Open the story you just wrote and the reference page it touches, and run one graph query for
+the code you will change. The read-before-write hook refuses the first source edit until both
+happened (`conventions/docs-linkage.md`).
+
+## 3. Code
+
+In a worktree (`using-git-worktrees`), on a `feature/<name>` branch off `develop`. Where the
+repo has a test suite, write the failing test first (`test-driven-development`). Keep to the
+ladder: reuse before writing, one line before fifty.
+
+## 4. Code review
+
+Two passes before merge, both on the diff:
+
+1. The `superpowers:code-reviewer` agent, against the story and the plan. Fix what it finds
+   or say in one line why not.
+2. `ponytail-review` for anything that should not exist.
+
+## 5. Deploy to dev and QA it
+
+Merge to `develop` (that is the dev deploy) and wait until every touched app reports ACTIVE;
+sync keeps the old build for about ten minutes after that. Then dispatch the **`drawbridge-qa`**
+agent with the story file path(s), the Asana task id and the dev organization id. It walks
+every scenario with a clean slate and writes `drawbridge-tests/results/qa/<task id>.json`.
+
+Read its numbered list. Fix every `fail`, redeploy, dispatch it again. Repeat until `fails` is
+0. A `blocked` scenario stays in the report and goes into the handoff as the tester's line.
+
+## 6. Ship
+
+Invoke `drawbridge-ship-feature`: docs reconciled, anchors checked, graph refreshed, handoff
+posted. The handoff comment is refused by the QA gate while this session changed code and
+`results/qa/<task id>.json` is missing, older than a day, or shows a fail.
+
+## What each check refuses
+
+| Skipped | Refused by |
+| --- | --- |
+| Reading the story and graph before coding | `hooks/consult-docs-gate.js` on the first source edit |
+| Updating the story when anchored code changed | `hooks/drift-check.js` at turn end |
+| QA on dev | `hooks/qa-gate.js` on the Asana comment |
+| Walking before naming a button | `drawbridge-asana-ship-handoff`, every quoted label from the walk output |

package/.claude-template/skills/drawbridge-ship-feature/SKILL.md

@@ -37,9 +37,14 @@ knowledge graph, and the Asana handoff so nothing drifts at ship time.
    knowledge graph (<feature>)" && git push origin main`. If it reports "graphify runtime not
    found", the `uv`/`graphify` binaries are in `~/.local/bin` — `export PATH="$HOME/.local/bin:$PATH"`
    and retry (do NOT run `graphify install`; it rewrites `CLAUDE.md`).
-6. **Hand off the task.** Invoke `drawbridge-asana-ship-handoff` with the Asana task to reassign
-   to the last commenter, post the change summary + retest steps, and set the due date.
-7. **Clear the worktree.** If the feature was built in a git worktree (a sibling directory or a
+6. **Confirm the QA report is clean.** `drawbridge-tests/results/qa/<task id>.json`, written by
+   the `drawbridge-qa` agent (`drawbridge-feature` step 5), must exist, be from today, and show
+   `fails: 0`. If it is missing or stale, dispatch the agent now; if it shows a fail, fix and
+   redeploy first. The handoff comment in the next step is refused otherwise (`hooks/qa-gate.js`).
+7. **Hand off the task.** Invoke `drawbridge-asana-ship-handoff` with the Asana task to reassign
+   to the last commenter, post the change summary + retest steps, and set the due date. Any
+   `blocked` scenario in the QA report becomes a numbered line the tester runs themselves.
+8. **Clear the worktree.** If the feature was built in a git worktree (a sibling directory or a
    `.worktrees/` folder), remove it now that the branch is merged: from the main checkout,
    `git worktree remove <path>` then `git worktree prune`. If the removal complains about
    uncommitted changes, inspect them first — add `--force` only once you've confirmed the dirt

package/README.md

@@ -43,6 +43,10 @@ scripts/
 
 hooks/
   drift-check.js            ← Stop hook (wired via .claude-template/settings.json)
+  consult-docs-record.js    ← PostToolUse hook: remembers a docs page read / graph query per session
+  consult-docs-gate.js      ← PreToolUse hook: refuses the first source edit until both happened
+  qa-gate.js                ← PreToolUse hook on the Asana comment tool: a session that changed code needs a clean QA report
+  guard-superpowers-docs.js ← PreToolUse hook: plans/specs go to drawbridge-docs
 ```
 
 ## Consuming from a drawbridge-* repo
@@ -105,8 +109,13 @@ identical copy via the sync mirror (see "Delivery model").
   against `drawbridge-docs`.
 - **Drift-check Stop hook.** `hooks/drift-check.js` runs at each task-turn end, wired via the
   drift-check `Stop` hook in the mirrored `.claude/settings.json`. It **blocks** on an unresolved
-  doc anchor, and **nudges** (non-blocking) when the graph looks stale or docs may need updating.
-  It skips plan-mode and turns with no source changes.
+  doc anchor and on `@story`-anchored code changed without a drawbridge-docs change (once per
+  turn; the second attempt passes so the agent must answer), and **nudges** (non-blocking) when
+  the graph looks stale. It skips plan-mode and turns with no source changes.
+- **Read-before-write hooks.** `hooks/consult-docs-record.js` (PostToolUse on Read/Bash) remembers
+  that a drawbridge-docs page was read and a graph query ran in this session;
+  `hooks/consult-docs-gate.js` (PreToolUse on Write/Edit) refuses the first source edit until
+  both happened. See `conventions/docs-linkage.md`, "Enforced, not just asked".
 - **Shared skills.** Mirrored into every repo's `.claude/skills/` (from `.claude-template/skills/`):
   `drawbridge-ship-feature` (verify → docs → graph → handoff), `drawbridge-asana-ship-handoff`,
   `drawbridge-explore-ecosystem`, `drawbridge-record-contract`.

package/claude/CLAUDE.md

@@ -21,4 +21,6 @@
 @../conventions/git-branching.md
 @../conventions/graphify.md
 @../conventions/testing.md
+@../conventions/walk-the-app.md
+@../conventions/feature-pipeline.md
 @../conventions/workflow-step-naming.md

package/conventions/docs-linkage.md

@@ -5,6 +5,19 @@
 developer lookups live in `reference/<file>.md` keyed by stable filename + heading anchor.
 Story IDs never change; only the `NN-`/`01-` file-name numbers shift, so never cite those.
 
+## Enforced, not just asked
+
+Two hooks in the shared `.claude/settings.json` hold this line (since 0.1.67, 2026-09-23):
+
+- **Read before you write.** The first edit to a source file in a session is refused until a
+  markdown page under `drawbridge-docs` has been read and a graph query has been run in that
+  session (`hooks/consult-docs-record.js` remembers, `hooks/consult-docs-gate.js` refuses).
+  Docs, `.claude/`, non-source files and growth are not gated; the graph half is skipped when
+  graphify is not installed or `DRAWBRIDGE_SKIP_GRAPHIFY=1`.
+- **Docs move with the code.** Ending a turn after changing `@story`-anchored code without
+  touching drawbridge-docs is refused once (`hooks/drift-check.js`): update the story, or say
+  which story was read and why it still matches, then end the turn again.
+
 ## Before you change a documented behaviour
 
 1. Find the matching story by its **ID** (the story-index table in each

package/conventions/feature-pipeline.md

@@ -0,0 +1,18 @@
+# How a feature ships
+
+Every feature or change that a tester will see goes through the `drawbridge-feature` skill, in
+this order, and no other way:
+
+1. Story first, in `drawbridge-docs/user-stories/`, with every scenario saying what the person
+   sees. Unknowns go to Darren as one numbered list of questions.
+2. Read the story and the reference page, and query the graph, before the first edit.
+3. Code, in a worktree, tests first where a suite exists.
+4. Code review on the diff: the reviewer agent and `ponytail-review`.
+5. Deploy to dev and dispatch the `drawbridge-qa` agent. It walks every scenario with a clean
+   slate and writes `drawbridge-tests/results/qa/<task id>.json`. Fix until `fails` is 0.
+6. `drawbridge-ship-feature`: docs, anchors, graph, handoff.
+
+Each skipped step is refused by a hook, not by a reminder: the first source edit
+(`consult-docs-gate.js`), the turn end (`drift-check.js`), and the Asana comment
+(`qa-gate.js`, which only fires in a session that changed source code). Darren, 2026-09-23:
+the point is that what reaches Jaime is "99.99% completed."

package/conventions/graphify.md

@@ -17,6 +17,9 @@ graphify explain "closeDraw" --graph ../drawbridge-docs/knowledge/graphs/global.
 graphify affected "closeDraw" --graph ../drawbridge-docs/knowledge/graphs/global.json
 ```
 
+This is enforced: the first source edit of a session is refused until a graph query has run
+(see `docs-linkage.md`, "Enforced, not just asked").
+
 `git pull` in drawbridge-docs gets you the current shared graph. It spans all sibling repos
 (code, via local AST); a semantic build additionally pulls in doc prose and richer INFERRED
 edges — see "Refreshing it".

package/conventions/rules.md

@@ -23,6 +23,14 @@
 
    Why: three drafts on 2026-09-23 went out as bullets with paragraphs around them, then a partly numbered list with prose before and after. Each one had to be sent back. An ask that cannot be answered by number costs a round trip every time.
 
+   Each question is three plain sentences, in this order, and nothing else:
+
+   1. What is true today. ("Today, nothing stops me from editing code before I have read the docs page.")
+   2. What I would change, described as what the reader would see happen. ("I can add a check that refuses my first code edit until I have opened the docs page.")
+   3. The ask. ("Do you want that? Yes or no.")
+
+   Use the words the team uses. Never a name I made up for the thing ("record hook", "gate hook", "marker", "nudge", "semantic pass") and never a term that lives only in our code or docs. If a sentence needs a word nobody on the team says out loud, rewrite the sentence. Test: could Jaime answer it without opening a repo? Darren, 2026-09-23: "the entire team hates the way you ask questions, they are always convoluted and use words that no one says." The same list of four questions had to be sent twice that day; the second version, in this shape, was answered in one line.
+
    This rule wins over two things that load into every session and say otherwise. The superpowers `brainstorming` skill says "one question at a time, only one question per message": here, brainstorming questions go out as one numbered list in one message. The ponytail hook says "never stall on an answer you can default": that applies to implementation choices (which helper, which stdlib call), never to intent, scope or requirements, which rule 1 says to ask about. Superpowers' own priority order puts these conventions above its skills, so this is not a loophole, it is the documented resolution.
 
 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.

package/conventions/walk-the-app.md

@@ -0,0 +1,94 @@
+# Walk the app before you describe it
+
+Every button, screen, label or flow named in a comment, a handoff or a reply was seen in a
+browser in that session. Not inferred from the code, not remembered from last week. A tester
+sent to a button that does not exist costs a full retest; this page is what makes the walk
+possible from any developer's session.
+
+Two ways to drive a browser. The first works from every session, headless, with no extra
+setup beyond the `.env`; the second is optional and only works in an interactive session.
+
+## 1. Playwright in drawbridge-tests (always available)
+
+Verified 2026-09-23: sign-in 2.5 s, screenshot and labels of a dev page in one command.
+
+### One-time setup, per machine
+
+```sh
+cd drawbridge-tests
+nvm use                                  # Node 22 — the family node; v12 breaks on node: imports
+npm run sync
+npx playwright install chromium webkit
+```
+
+Create `drawbridge-tests/.env` (gitignored; wrap values in single quotes). The keys the walk
+needs, and where each value comes from:
+
+| Key | Value | Where it comes from |
+| --- | --- | --- |
+| `APP_CLIENT_DASHBOARD_URI` | `https://dev.dashboard.trydrawbridge.com` | dev dashboard |
+| `APP_CLIENT_FORM_URI` | dev share base | dev share app |
+| `APP_CLIENT_WEBSITE_URI` | `https://dev.trydrawbridge.com` | dev website |
+| `APP_TEST_ORG_ID` | the e2e organization id | `fixtures/e2e-org.md` |
+| `USER_AUTH_EMAIL` | the account that OWNS the e2e organization | `fixtures/e2e-org.md`; a different address fails with "Invalid or expired code" |
+| `USER_AUTH_OTC` | the fixed testing code the setup seeds and confirms with | `fixtures/e2e-org.md`; any value works, it is hashed at seed time |
+| `BASIC_AUTH_USERNAME`, `BASIC_AUTH_PASSWORD` | the dev staging gate pair | the dev app spec, or 1Password (same pair gates dashboard and website) |
+| `ENCRYPT_OTC_SECRET` | the DEPLOYED dev value, exactly | 1Password vault "Drawbridge - Environments", item "1. Environment Variables - Development", API section, via `op environment read` |
+| `MONGODB_DATABASE_URI` | the dev database | same 1Password item |
+
+`ENCRYPT_OTC_SECRET` must be the value the deployed dev API is running with. When it drifts,
+sign-in fails with "Invalid or expired code" and nothing else in the error says why; re-copy
+it from 1Password. `op whoami` reports "not signed in" even when the desktop-app integration
+works, so probe with `op vault list`.
+
+### How the sign-in override works (so you can fix it when it breaks)
+
+The dashboard's sign-in is reCAPTCHA-gated and reCAPTCHA scores an automated browser as a
+bot, on purpose, with no test bypass. So the test does not use the sign-in form. It writes a
+pending sign-in code straight into the dev database, hashed with `ENCRYPT_OTC_SECRET` the way
+the API hashes it, then confirms that code through the dashboard's own confirm route, which
+is not reCAPTCHA-gated. The session cookie is saved to `e2e/.auth/user.json` and reused by
+every later walk until it expires (`e2e/auth.setup.js`, `lib/otc.js`).
+
+### Walking a page
+
+```sh
+npm run walk -- /organizations/<org id>/suppressions          # a dashboard path
+npm run walk -- https://<slug>.dev.drwbrdg.com/<campaign>      # any full URL (share, website)
+npm run walk -- /organizations/<org id>/campaigns --out shot.png
+```
+
+It signs in if the saved session is missing or stale, opens the page, saves a screenshot
+(default `results/walk/<timestamp>.png`) and prints the headings, buttons, links and table
+headers a person would see. **Read the screenshot** (the Read tool renders images), then
+write the comment from what is on it. Quote labels from the printed list, never from memory.
+
+The full smoke pack (`npm test`) and the dashboard functional run (`npm run dashboard`)
+use the same session; see `drawbridge-tests/readme.md`.
+
+## 2. Claude in Chrome (optional, interactive sessions only)
+
+Claude Code can drive the developer's own Chrome through the
+[Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn).
+It shares the browser's login state, so once you are signed in to the dev dashboard in Chrome,
+Claude can walk it as you. Vendor reference: https://code.claude.com/docs/en/chrome (read
+2026-09-23). What it needs:
+
+- Google Chrome or Microsoft Edge (other Chromium browsers work; not WSL).
+- The extension, version 1.0.36 or later.
+- Claude Code signed in with `/login` on a direct Anthropic plan. An API key or a
+  `claude setup-token` token keeps the integration off even with `--chrome`.
+- Start with `claude --chrome`, or run `/chrome` once and choose "Enabled by default". In the
+  VS Code extension it is on whenever the browser extension is installed. `/chrome` shows
+  "Status: Enabled" and "Extension: Installed" when it works.
+- Sign in to `dev.dashboard.trydrawbridge.com` in that Chrome first; the basic-auth gate
+  prompts once. Claude pauses on any login page or CAPTCHA and asks you to handle it.
+
+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.
+
+## What is enforced
+
+- The `drawbridge-asana-ship-handoff` skill requires the walk before a handoff comment.
+- `conventions/rules.md` rule 8: a fact in anything written to a person is backed by something
+  read this session. A label is a fact.

package/hooks/consult-docs-gate.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// PreToolUse hook (Write/Edit/MultiEdit/NotebookEdit): the docs and the knowledge
+// graph are the source of truth, and both were being skipped (Darren, 2026-09-23).
+// conventions/docs-linkage.md and graphify.md already say "read the story first"
+// and "query the graph before grepping"; prose asks, this refuses. The first
+// source edit of a session is denied until consult-docs-record.js has seen a
+// drawbridge-docs page read and a graph query in this session.
+//
+// What is NOT gated: anything under drawbridge-docs itself, anything under a
+// .claude directory (the sync mirror), non-source files (json, md, css, ...), and
+// growth, whose docs live in its own repo. The graph half is skipped when
+// DRAWBRIDGE_SKIP_GRAPHIFY=1 or when no graphify binary is on this machine, so a
+// missing tool never locks every edit.
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const { markerPath } = require('./consult-docs-record.js')
+
+const SOURCE_EXTENSIONS = new Set([ '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs' ])
+
+const readStdin = () => {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+const deny = (reason) => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }))
+  process.exit(0)
+}
+
+const readMarker = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+const graphifyInstalled = () => {
+  if (process.env.DRAWBRIDGE_SKIP_GRAPHIFY === '1') return false
+  const result = spawnSync('graphify', [ '--version' ], { encoding: 'utf8', stdio: 'pipe' })
+  return !result.error && result.status === 0
+}
+
+const run = () => {
+  const input = readStdin()
+
+  const tool = input.tool_name || ''
+  if (!/^(Write|Edit|MultiEdit|NotebookEdit)$/.test(tool)) process.exit(0)
+  if (!input.session_id) process.exit(0)
+
+  const toolInput = input.tool_input || {}
+  const filePath = toolInput.file_path || toolInput.notebook_path
+  if (!filePath) process.exit(0)
+
+  const resolved = path.resolve(filePath).split(path.sep).join('/')
+  const segments = resolved.split('/')
+
+  if (!SOURCE_EXTENSIONS.has(path.extname(resolved).toLowerCase())) process.exit(0)
+  if (segments.includes('drawbridge-docs')) process.exit(0)
+  if (segments.includes('.claude')) process.exit(0)
+  if (/\/drawbridge-growth[^/]*\//.test(resolved + '/')) process.exit(0)
+
+  const seen = readMarker(markerPath(input.session_id))
+  const needGraph = graphifyInstalled()
+
+  const missing = []
+  if (!seen.docs) missing.push('open the user story or reference page in drawbridge-docs that covers this behaviour (Read it; the story index is user-stories/<domain>/README.md, developer lookups are reference/<file>.md)')
+  if (needGraph && !seen.graph) missing.push('run a graph query for the code you are about to change: graphify query "<what you are changing>" --graph ../drawbridge-docs/knowledge/graphs/global.json')
+
+  if (missing.length === 0) process.exit(0)
+
+  deny(
+    'Read before you write. This is the first source edit of the session and the docs and graph were not consulted yet. ' +
+    'Do this first, then retry the edit: ' + missing.map((step, index) => (index + 1) + '. ' + step).join(' ') + '. ' +
+    'See conventions/docs-linkage.md and conventions/graphify.md.'
+  )
+}
+
+try {
+  run()
+} catch (error) {
+  // Never break a user's turn because of a hook bug — fail open.
+  process.exit(0)
+}

package/hooks/consult-docs-record.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// PostToolUse hook (Read/Bash): remember, for this session, that the docs and the
+// knowledge graph were consulted. consult-docs-gate.js reads the same file before
+// the first source edit. Two halves because a hook only sees one tool call: this
+// one watches what was read, the other decides what may be written.
+//
+// Counts as consulting the docs: a Read of any markdown file under drawbridge-docs.
+// Counts as consulting the graph: a Bash command that runs a graphify query
+// (query / explain / path / affected) or the family graph bin.
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const readStdin = () => {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+// One file per session in the OS temp dir; nothing persists past it.
+const markerPath = (sessionId) => path.join(os.tmpdir(), 'drawbridge-consulted-' + String(sessionId).replace(/[^\w.-]/g, '_') + '.json')
+
+const readMarker = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+const isDocsRead = (tool, toolInput) => {
+  if (tool !== 'Read') return false
+  const filePath = String(toolInput.file_path || '')
+  const resolved = path.resolve(filePath).split(path.sep).join('/')
+  return resolved.split('/').includes('drawbridge-docs') && /\.md$/i.test(resolved)
+}
+
+// A source edit outside .claude and drawbridge-docs: what qa-gate.js keys on to
+// decide whether a session must show a QA report before it comments on Asana.
+const SOURCE_EXTENSIONS = new Set([ '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs' ])
+
+const isSourceEdit = (tool, toolInput) => {
+  if (!/^(Write|Edit|MultiEdit|NotebookEdit)$/.test(tool)) return false
+  const filePath = String(toolInput.file_path || toolInput.notebook_path || '')
+  if (!filePath) return false
+  const resolved = path.resolve(filePath).split(path.sep).join('/')
+  const segments = resolved.split('/')
+  if (!SOURCE_EXTENSIONS.has(path.extname(resolved).toLowerCase())) return false
+  if (segments.includes('.claude') || segments.includes('drawbridge-docs')) return false
+  return true
+}
+
+const isGraphQuery = (tool, toolInput) => {
+  if (tool !== 'Bash') return false
+  const command = String(toolInput.command || '')
+  return /graphify\s+(query|explain|path|affected)\b/.test(command) || /drawbridge-agents-graph\b/.test(command)
+}
+
+const run = () => {
+  const input = readStdin()
+  if (!input.session_id) process.exit(0)
+
+  const tool = input.tool_name || ''
+  const toolInput = input.tool_input || {}
+
+  const docs = isDocsRead(tool, toolInput)
+  const graph = isGraphQuery(tool, toolInput)
+  const edited = isSourceEdit(tool, toolInput)
+  if (!docs && !graph && !edited) process.exit(0)
+
+  const file = markerPath(input.session_id)
+  const current = readMarker(file)
+  const next = {
+    docs: Boolean(current.docs) || docs,
+    edited: Boolean(current.edited) || edited,
+    graph: Boolean(current.graph) || graph
+  }
+  fs.writeFileSync(file, JSON.stringify(next))
+  process.exit(0)
+}
+
+module.exports = { markerPath }
+
+// consult-docs-gate.js requires this file for markerPath; only the hook
+// invocation itself may read stdin and exit.
+if (require.main === module) {
+  try {
+    run()
+  } catch (error) {
+    // Never break a user's turn because of a hook bug — fail open.
+    process.exit(0)
+  }
+}

package/hooks/drift-check.js

@@ -83,6 +83,21 @@ const run = () => {
     }
   }
 
+  // 1b. Story checkability (blocking) — every scenario in a story touched this turn
+  //     has a Then that names something a person sees, or a tag saying where else
+  //     it shows up. Only the stories in the working tree are checked, so the
+  //     backlog of older stories never blocks an unrelated turn.
+  const changedStories = changed.filter((file) => /\/drawbridge-docs\/user-stories\/.+\.md$/.test(file.split(path.sep).join('/')))
+  const checkStories = path.join(resolvePackageRoot(cwd), 'scripts', 'check-stories.js')
+  if (changedStories.length && fs.existsSync(checkStories)) {
+    try {
+      execFileSync('node', [ checkStories, ...changedStories ], { cwd, encoding: 'utf8', stdio: 'pipe' })
+    } catch (error) {
+      const detail = ((error.stdout || '') + (error.stderr || '')).trim()
+      block(`A story changed this turn has scenarios a tester could not check as written.\n${ detail }\nGive each Then a **label** or "copy" the person sees, or tag the scenario @inbox, @sms or @offscreen, before finishing.`)
+    }
+  }
+
   const skipGraph = process.env.DRAWBRIDGE_SKIP_GRAPHIFY === '1'
 
   // 2. Graph freshness (non-blocking nudge) — a full re-extract is expensive, so alert rather
@@ -108,8 +123,11 @@ const run = () => {
     }
   }
 
-  // 3. Docs staleness (non-blocking heuristic) — code under a @story-anchored area changed but no
-  //    drawbridge-docs change is in the working tree.
+  // 3. Docs staleness (BLOCKING since 2026-09-23, Darren: the docs are the source of truth and
+  //    the nudge was being ignored) — code under a @story-anchored area changed but no
+  //    drawbridge-docs change is in the working tree. The stop_hook_active escape at the top
+  //    lets the turn end on the second attempt, so the block costs exactly one explicit
+  //    answer: update the story, or say which story was checked and why it still matches.
   const touchedAnchoredCode = changedSource.some((file) => {
     try {
       return /@story\s+[a-z0-9]/.test(fs.readFileSync(file, 'utf8'))
@@ -121,7 +139,7 @@ const run = () => {
   if (touchedAnchoredCode && !touchedDocs) {
     // `@story` is backticked so doc-link scanners (including stale node_modules
     // copies that don't skip .claude/) never read this sentence as a real tag.
-    nudge('You changed code that implements a documented behaviour (carries an `@story` anchor) without touching drawbridge-docs. Confirm the matching user story still matches, or update it in this change.')
+    block('You changed code that implements a documented behaviour (carries an `@story` anchor) and did not touch drawbridge-docs. Before ending the turn: update the matching user story or reference page in this change, or state in your reply which story you read and why it still matches as written.')
   }
 
   process.exit(0)

package/hooks/qa-gate.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// PreToolUse hook on the Asana comment tool: a session that changed source code may
+// not post to a task until the drawbridge-qa agent's report for that task exists,
+// is from the last day, and shows no failed scenario. A session that changed
+// nothing (an answer, a question) posts freely. Darren, 2026-09-23: features reach
+// Jaime "99.99% completed". See the drawbridge-feature skill.
+//
+// "Changed source code" is what consult-docs-record.js remembered for this session.
+// The report is drawbridge-tests/results/qa/<task id>.json, found by walking up from
+// cwd to the folder that holds the family (a worktree sits one level deeper).
+const fs = require('fs')
+const path = require('path')
+const { markerPath } = require('./consult-docs-record.js')
+
+const MAX_AGE_MS = 24 * 60 * 60 * 1000
+
+const readStdin = () => {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+const deny = (reason) => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  }))
+  process.exit(0)
+}
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8') || '{}')
+  } catch (error) {
+    return null
+  }
+}
+
+const findReport = (cwd, task) => {
+  let dir = cwd
+  for (let depth = 0; depth < 4; depth += 1) {
+    const candidate = path.join(dir, 'drawbridge-tests', 'results', 'qa', task + '.json')
+    if (fs.existsSync(candidate)) return candidate
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+const run = () => {
+  const input = readStdin()
+
+  if (input.tool_name !== 'mcp__claude_ai_Asana__add_comment') process.exit(0)
+  if (!input.session_id) process.exit(0)
+
+  const seen = readJson(markerPath(input.session_id)) || {}
+  if (!seen.edited) process.exit(0)
+
+  const task = String((input.tool_input || {}).task_id || '')
+  if (!task) process.exit(0)
+
+  const cwd = input.cwd || process.cwd()
+  const file = findReport(cwd, task)
+  const how = 'Dispatch the drawbridge-qa agent with the story file(s), task ' + task + ' and the dev organization id; it writes drawbridge-tests/results/qa/' + task + '.json. Fix every fail and run it again before commenting.'
+
+  if (!file) deny('QA first. This session changed source code and there is no QA report for task ' + task + '. ' + how)
+
+  const report = readJson(file)
+  if (!report || !Array.isArray(report.scenarios)) deny('QA report for task ' + task + ' is not readable (' + file + '). ' + how)
+
+  const age = Date.now() - Date.parse(report.walkedAt || 0)
+  if (!(age >= 0 && age <= MAX_AGE_MS)) deny('QA report for task ' + task + ' is older than a day (' + (report.walkedAt || 'no walkedAt') + '). ' + how)
+
+  const failed = report.scenarios.filter((scenario) => scenario && scenario.status === 'fail').map((scenario) => scenario.name || 'unnamed')
+  if (failed.length) deny('QA report for task ' + task + ' has ' + failed.length + ' failed scenario(s): ' + failed.join('; ') + '. Fix, redeploy, and run drawbridge-qa again before commenting.')
+
+  process.exit(0)
+}
+
+try {
+  run()
+} catch (error) {
+  // Never break a user's turn because of a hook bug — fail open.
+  process.exit(0)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.66",
+  "version": "0.1.70",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -14,7 +14,8 @@
   "bin": {
     "drawbridge-agents-sync": "bin/sync-claude.js",
     "drawbridge-agents-graph": "bin/graph.js",
-    "drawbridge-agents-check-docs": "scripts/check-doc-links.js"
+    "drawbridge-agents-check-docs": "scripts/check-doc-links.js",
+    "drawbridge-agents-check-stories": "scripts/check-stories.js"
   },
   "files": [
     "claude",

package/scripts/check-stories.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Every scenario in a user story must be checkable by someone with a browser.
+// Rule: each `Scenario:` has a Then, and its Then / And / But lines name at least
+// one thing the person SEES, written as **a bold label** or "quoted copy". A
+// scenario that lives somewhere a browser cannot look is tagged on the line
+// above it, and the tag says where:
+//
+//   @inbox      the outcome is an email (the QA agent reads it through Gmail)
+//   @sms        the outcome is a text message
+//   @offscreen  no screen shows it (a charge, a log line, a later job)
+//
+// Tagged scenarios are exempt from the visible-thing rule, not from the Then.
+//
+// Usage: node scripts/check-stories.js [story.md ...]   (no args = every story)
+// Exits 1 naming file:line for each scenario that fails. Darren, 2026-09-23:
+// "fix this so that there are no gaps" — the QA agent can only check what a
+// story says a person sees.
+const fs = require('fs')
+const path = require('path')
+
+const TAGS = new Set([ '@inbox', '@sms', '@offscreen' ])
+const VISIBLE = /\*\*[^*]+\*\*|"[^"]+"|“[^”]+”/
+
+const findFamilyRoot = () => {
+  let dir = process.env.INIT_CWD || process.cwd()
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'drawbridge-docs', 'user-stories'))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+const walk = (dir, out = []) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) walk(full, out)
+    else if (entry.name.endsWith('.md')) out.push(full)
+  }
+  return out
+}
+
+// Returns [{ line, name, reason }] for one story file.
+const checkStory = (text) => {
+  const problems = []
+  const lines = text.split('\n')
+  let scenario = null
+  let inFence = false
+
+  const flush = () => {
+    if (!scenario) return
+    if (!scenario.hasThen) problems.push({ line: scenario.line, name: scenario.name, reason: 'no Then line' })
+    else if (!scenario.tagged && !scenario.visible) problems.push({ line: scenario.line, name: scenario.name, reason: 'Then names nothing a person sees (no **label** or "copy"); tag it @inbox, @sms or @offscreen if no screen shows it' })
+    scenario = null
+  }
+
+  let pendingTag = false
+  lines.forEach((raw, index) => {
+    const line = raw.trim()
+    if (line.startsWith('```')) {
+      inFence = !inFence
+      // A scenario block inside a fence is still a scenario; a fence that closes ends it.
+      if (!inFence) flush()
+      return
+    }
+    if (/^#/.test(line)) { flush(); pendingTag = false; return }
+    if (/^@\w/.test(line)) {
+      pendingTag = line.split(/\s+/).some((tag) => TAGS.has(tag))
+      return
+    }
+    if (/^Scenario( Outline)?:/.test(line)) {
+      flush()
+      scenario = { line: index + 1, name: line, hasThen: false, visible: false, tagged: pendingTag }
+      pendingTag = false
+      return
+    }
+    if (!scenario) return
+    if (/^Then\b/.test(line)) scenario.hasThen = true
+    if (/^(Then|And|But)\b/.test(line) && VISIBLE.test(line)) scenario.visible = true
+  })
+  flush()
+  return problems
+}
+
+const main = () => {
+  const familyRoot = findFamilyRoot()
+  if (!familyRoot) {
+    console.error('drawbridge-agents-check-stories: could not locate drawbridge-docs; run from within the drawbridge-* family')
+    process.exit(1)
+  }
+
+  const storiesRoot = path.join(familyRoot, 'drawbridge-docs', 'user-stories')
+  const requested = process.argv.slice(2).map((file) => path.resolve(file))
+  const files = requested.length ? requested.filter((file) => file.startsWith(storiesRoot) && file.endsWith('.md')) : walk(storiesRoot)
+
+  let count = 0
+  for (const file of files) {
+    if (!fs.existsSync(file)) continue
+    for (const problem of checkStory(fs.readFileSync(file, 'utf8'))) {
+      count += 1
+      console.error(`  ${ path.relative(familyRoot, file) }:${ problem.line }  ${ problem.name }  — ${ problem.reason }`)
+    }
+  }
+
+  if (count) {
+    console.error(`drawbridge-agents-check-stories: ${ count } scenario(s) a tester could not check as written (${ files.length } file(s) scanned)`)
+    process.exit(1)
+  }
+  console.log(`drawbridge-agents-check-stories: every scenario names what the person sees (${ files.length } file(s))`)
+}
+
+module.exports = { checkStory }
+
+if (require.main === module) main()