@drawbridge/drawbridge-agents 0.1.97 → 0.1.99

package/.claude-template/settings.json

@@ -21,12 +21,9 @@
       "../drawbridge-components",
       "../drawbridge-docs",
       "../drawbridge-emails",
-      "../drawbridge-games",
-      "../drawbridge-growth",
       "../drawbridge-mongodb",
       "../drawbridge-redis",
       "../drawbridge-share",
-      "../drawbridge-shopify",
       "../drawbridge-shopify-app",
       "../drawbridge-stripe",
       "../drawbridge-sync",
@@ -56,6 +53,15 @@
   },
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./.claude/hooks/guard-secrets.js"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit",
         "hooks": [

package/README.md

@@ -112,6 +112,9 @@ identical copy via the sync mirror (see "Delivery model").
   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.
+- **Secrets guard.** `hooks/guard-secrets.js` (PreToolUse on Read/Bash) denies a Read of any
+  `.env*` file and a Bash command that displays one, prints the environment, or prints an `op`
+  value without a redirect. See `conventions/secrets.md`.
 - **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

package/claude/CLAUDE.md

@@ -3,6 +3,7 @@
 @../conventions/karpathy-guidelines.md
 @../conventions/rules.md
 @../conventions/verification.md
+@../conventions/secrets.md
 @../conventions/javascript-formatting.md
 @../conventions/nested-objects.md
 @../conventions/jsx-fragments.md
@@ -24,3 +25,4 @@
 @../conventions/walk-the-app.md
 @../conventions/feature-pipeline.md
 @../conventions/workflow-step-naming.md
+@../conventions/token-budget.md

package/conventions/cross-repo-contracts.md

@@ -107,15 +107,17 @@ skill) so it stops living only in tribal memory.
   carry `organization : null` and still block everyone;
   api registers the number's SmsUrl at twilio connect (`lib/twilio.js`) and `scripts.js
   registerTwilioWebhooks` backfills — a deployed webhooks route with unregistered numbers hears
-  nothing, silently. **Since Butterscotch (release 1219790090574059; sync 762fdd7, Darren
-  2026-10-23: an opt-out is the person's choice, not one address's) `canSend` gates the
-  PERSON, not only the address**: it reads the recipient's contact in the organization (found by
-  `canonical.emails`/`canonical.phones` or by `leads`) and blocks when any canonical or raw
-  address on that contact is suppressed for the channel. `lead` is optional, so every caller
-  that knows the lead passes it, or a returning person under a new mailbox passes until their
-  contact is rebuilt with the new address. The api's draw opt-out check
-  (`route/organization-campaign-draw.js` `optedOutLeads`) applies the same rule and must stay
-  in step with it; before Butterscotch both matched the lead's own canonical address only.
+  nothing, silently. **Every message send and every draw checks the recipient's OWN canonical
+  address, never their contact** (Darren, 2026-10-29): contacts exist only once an organization
+  activates segments, and sync merges entrants who share a phone into one contact, so a
+  contact-reading gate blocked a second entrant for the first one's unsubscribe, and only where
+  segments was on. The api's draw check (`lib/opt-out.js`, used by prepare, the draw and the
+  winner send) and `canSend` without `person` must stay in step. **Since Butterscotch
+  (release 1219790090574059) the ONE caller that reads the contact is the vendor contact sync**:
+  `lib/step-runner.js` passes `person : lead.id` for the `suppressed` answer the
+  Mailchimp/Klaviyo/Attentive hooks receive, and `canSend` then blocks when any canonical or raw
+  address on the person's contact (found by `leads` or `canonical.emails`/`canonical.phones`) is
+  suppressed. A message path that passes `person` reintroduces the shared-phone bug.
 - **`audience` picks the FROM-address; `intent` picks the unsubscribe plumbing — and NOTHING
   passes the suppression gate** (utils ↔ sync ↔ api). Every suppression source blocks every
   lead-facing send, the winner claim included: api's draw route refuses up front ("Disqualify

package/conventions/secrets.md

@@ -0,0 +1,34 @@
+# Never put a secret in the transcript
+
+Nothing an agent prints, reads or echoes may carry a secret. The family's env files
+(`.env.local`, `.env.development`, `.env.production`, drawbridge-tests' `.env`) hold a 1Password
+service-account token and, in tests, live keys. A transcript is copied, summarized and shared,
+so a value that lands in one has to be rotated.
+
+The api's 1Password service-account token reached a session transcript twice, the second time
+on 2026-10-28. Darren: "That is the second time you have done that. You cannot fucking keep doing
+that." This page and `hooks/guard-secrets.js` exist so there is no third time.
+
+## The rule
+
+- Never `Read`, `cat`, `head`, `tail`, `less`, `grep`, `sed`, `awk` or `source` a `.env*` file.
+  Not to "see which Environment it names", not to copy one line, not to check it exists (`ls` and
+  `test -f` are fine; they show no content).
+- Never print `process.env`, `printenv`, bare `env`, or a value read from `op` (`op read`,
+  `op item get`, `op environment read`) to the console. Those commands are allowed only with
+  their output redirected to a file that nothing then displays.
+- Never paste a key, token, connection string, cookie or session value into a reply, a commit
+  message, an Asana comment, a doc or a script's console output.
+- A script that needs an env value runs under the repo's `scripts/op.sh`
+  (`ENV_FILE=.env.local sh scripts/op.sh node <script>`) and consumes the value inside the
+  process. `op run` conceals secret-looking strings in console output, which is why ids are
+  written to files and read back; it is not a licence to display the env file.
+- Copying an env file between checkouts (a worktree without `.env.development`) is `cp` with no
+  display, and the copy is deleted when the work is done.
+- If a secret does reach the transcript, say so at once, in one line, and name what to rotate.
+
+## Enforced
+
+`hooks/guard-secrets.js` is a PreToolUse hook on `Read` and `Bash`, mirrored into every repo's
+`.claude/hooks/`. It denies a `Read` of any `.env*` file and a Bash command that displays one,
+prints the environment, or prints an `op` value without a redirect. The denial names this page.

package/conventions/token-budget.md

@@ -0,0 +1,37 @@
+# Token budget
+
+Darren works on a subscription, and the rolling limits are metered in tokens, so a QA run or
+a full dev walk that spends fewer tokens is one that finishes before the limit lands
+(Darren, 2026-11-02: "we don't want to stop doing those things, we just want a way to use less
+tokens when we do"). Two rules, both about where the tokens actually go: tool output and
+subagents, not the prompt.
+
+## Read-only subagents run on Haiku
+
+A subagent that only locates things — `Explore`, `Plan`, a `general-purpose` agent sent to
+search or read — is spawned with `model : 'haiku'`. It returns file paths and conclusions,
+and the session model reads the files it names. Agents that judge or write keep the session
+model: `drawbridge-qa` (walks and reports), the code reviewer, anything that edits. A Haiku
+agent's "not found" is never evidence of absence under rule 6 in `rules.md`: before claiming
+nothing writes, reads or documents a thing, the session model runs that search itself.
+
+## Long output is summarised by the command, not by the model
+
+A build, test, log or list command that can print more than a screen is piped through `tail`
+for its summary AND `grep -i -E 'fail|error'` for its failures, in the same command. A bare
+`tail` hides the failing line; a bare dump spends the tokens. Before a long walk, `/compact`;
+between unrelated tasks, a new session rather than a longer one.
+
+## Locate with Serena, read with Read
+
+Serena (an MCP server, `oraios/serena`, registered at user scope) finds a symbol and its
+references through a language server. Use it to find WHERE code lives instead of reading
+whole files or paging through grep hits. It does not replace the read: rule 5 in `rules.md`
+still means the whole file is open before a claim about it, and rule 6 still means absence is
+proved by a search of the whole space. Serena only shortens the search for the file to open.
+
+Trial since 2026-11-02 on Darren's machine (install: `uv tool install -p 3.13 serena-agent`,
+then `claude mcp add --scope user serena -- serena start-mcp-server --context claude-code
+--project-from-cwd`; `**/.serena/` is in the global git ignore). The agents sync preflight
+installs it family-wide only once the trial shows file reads dropping. Serena's own README
+says never to install it from a plugin or MCP marketplace.

package/hooks/guard-secrets.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// PreToolUse hook (Read|Bash): nothing displays a secret. The family's env files carry a
+// 1Password service-account token, and that token reached a session transcript twice
+// (the second time 2026-10-28). A convention did not stop it, so this does: a Read of any
+// .env* file is denied, and so is a Bash command that displays one, prints the environment,
+// or prints an `op` value to the console. See conventions/secrets.md.
+const fs = require('fs')
+const path = require('path')
+
+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 SEE = ' See conventions/secrets.md: run the script under scripts/op.sh and let it consume the value; never display it.'
+
+// `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.example` is harmless but
+// treated the same: nothing needs to read any of them.
+const isEnvFile = (filePath) => /^\.env(\..+)?$/.test(path.basename(filePath))
+
+// A command whose argument list names an env file, by a tool that prints file content.
+const DISPLAYS_FILE = /(^|[|;&(\s])(cat|head|tail|less|more|bat|grep|rg|egrep|fgrep|sed|awk|cut|sort|uniq|strings|xxd|od|source|\.)\s+(?:[^|;&]*[\s/'"=])?\.env(\.[\w-]+)?(['"\s]|$)/m
+
+// The whole environment, printed.
+const PRINTS_ENV = /(^|[|;&(\s])(printenv|env)(\s*$|\s*[|;&)]|\s+-)/m
+
+// An `op` read whose output is not sent to a file.
+const OP_READ = /(^|[|;&(\s])op\s+(read|item\s+get|environment\s+read)\b/m
+
+const run = () => {
+  const input = readStdin()
+  const tool = input.tool_name || ''
+  const toolInput = input.tool_input || {}
+
+  if (tool === 'Read') {
+    const filePath = toolInput.file_path || ''
+    if (filePath && isEnvFile(filePath)) {
+      deny('Blocked: `' + path.basename(filePath) + '` holds a secret and is never read into the transcript.' + SEE)
+    }
+    process.exit(0)
+  }
+
+  if (tool !== 'Bash') process.exit(0)
+
+  const command = String(toolInput.command || '')
+  if (!command) process.exit(0)
+
+  if (DISPLAYS_FILE.test(command)) {
+    deny('Blocked: this command displays a .env file, which holds a secret.' + SEE)
+  }
+
+  if (PRINTS_ENV.test(command)) {
+    deny('Blocked: this command prints the whole environment, secrets included.' + SEE)
+  }
+
+  if (OP_READ.test(command) && !/>\s*\S/.test(command)) {
+    deny('Blocked: an `op` read prints a secret to the console. Redirect it to a file nothing displays, or run the consumer under scripts/op.sh.' + SEE)
+  }
+
+  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.97",
+  "version": "0.1.99",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {