@drawbridge/drawbridge-agents 0.1.9 → 0.1.12

package/.claude-template/settings.json

@@ -35,6 +35,17 @@
     ]
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./node_modules/@drawbridge/drawbridge-agents/hooks/guard-superpowers-docs.js"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "",

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

@@ -20,7 +20,14 @@ knowledge graph, and the Asana handoff so nothing drifts at ship time.
    flag the drift explicitly. See `conventions/docs-linkage.md`.
 3. **Confirm doc anchors resolve.** Run `npx drawbridge-agents-check-docs`; fix any unresolved
    `@story` / `@doc` tag. Add an anchor to newly-added feature code where it maps to a story.
-4. **Refresh the graph** if the change altered cross-repo structure: `npx drawbridge-agents-graph`.
+4. **Refresh the knowledge graph — always, on every feature wrap** (not conditional on whether
+   structure "obviously" changed). The canonical graph is the committed snapshot in
+   `drawbridge-docs`, shared by the whole team; skipping it lets the shared graph drift. From the
+   `drawbridge-docs` repo: `npx drawbridge-agents-graph` (rebuilds `knowledge/graphs/global.json`
+   from every repo), then `git add knowledge/graphs/global.json && git commit -m "chore: refresh
+   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`).
 5. **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.
 

package/conventions/cross-repo-contracts.md

@@ -9,6 +9,11 @@ skill) so it stops living only in tribal memory.
 
 - `OAUTH_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
   `assertEnv` it at boot. A mismatch silently breaks realtime token verification.
+- reCAPTCHA on auth is a key pair: `GOOGLE_RECAPTCHA_SECRET` (**drawbridge-api**) + `NEXT_PUBLIC_GOOGLE_RECAPTCHA_KEY`
+  (**drawbridge-app-web**), both `assertEnv`'d at boot. The api verifies the v3 token app-web's
+  `/auth` forms attach and enforces it **unconditionally** on `/oauth/{signup,signin}/request`
+  (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`.
 
 ## Sync owns reactive side effects
 
@@ -34,6 +39,14 @@ skill) so it stops living only in tribal memory.
   sync upserts the same invoice from three concurrent webhooks (finalized/payment_succeeded/voided)
   and relies on the index to reject the losing insert so the catch can redo it as an update. Drop
   the index → silent duplicate invoice rows; remove the catch → concurrent events throw + retry.
+- The `contact` collection's **unique multikey index on `leads`** (drawbridge-api
+  `schema/contact.js`) and sync's contact resolution (`lib/contact.js` + `queue/contact.js`) are
+  one contract: a lead belongs to at most one contact. One submission enqueues two resolve jobs
+  (lead insert + totals-update events) that race; the index rejects the losing create and the
+  worker retries it into the update path. The merge path must delete duplicate contacts BEFORE
+  `$set`-ing the survivor (the expanded `leads` array collides with rows about to be deleted).
+  Drop the index → duplicate contacts, doubled segment members, double-billed `contact.create` +
+  `segment.join`; reorder the merge → every merge aborts E11000 and duplicates never heal.
 
 ## `@drawbridge/*` package coordination
 
@@ -49,3 +62,16 @@ skill) so it stops living only in tribal memory.
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`
   and throws at call time, not at import. Check `drawbridge-docs/reference/packages.md` (the
   generated export surface) when unsure.
+
+## Shopify sales channel
+
+- `@drawbridge/shopify` storefront `getProduct`/`getProductVariantsPage` throw the **exact
+  message `'Shopify product not found'`** when the Storefront API can't see a product
+  (unpublished from the Drawbridge channel / deleted); transport and GraphQL failures throw
+  `'Shopify storefront error: …'`. drawbridge-sync's product worker (`queue/product.js`)
+  string-matches the not-found message to send publish-this-product ResourceFeedback instead of
+  retrying. Reword the message → unpublished products retry-loop forever and merchants get no
+  feedback; drawbridge-api's shopifyProduct route relies on the not-found throw staying a throw.
+- The `write_resource_feedbacks` and `read_publications` scopes live in drawbridge-shopify-app's
+  `shopify.app.*.toml` but power other repos: sync's product ResourceFeedback sends and the
+  embedded app's publishing section. Removing either → silent Shopify userErrors, no crash.

package/conventions/superpowers-docs.md

@@ -13,6 +13,11 @@ This is the **only** allowed home for these working docs. Rules:
 - Do **not** create or keep superpowers plans/specs (or `docs/superpowers/`, `docs/plans/`)
   inside any other repo. When you finalize a plan or spec, write it under
   `../drawbridge-docs/superpowers/{plans,specs}/`, not the repo you're working in.
+- ⚠️ The superpowers **brainstorming** and **writing-plans** skills hardcode a save path of
+  `docs/superpowers/{specs,plans}/YYYY-MM-DD-<slug>.md` in the current repo (and tell you to
+  commit it). **Override that** — redirect the path to `../drawbridge-docs/superpowers/…`. A
+  `PreToolUse` guard hook (`hooks/guard-superpowers-docs.js`) denies writes to `docs/superpowers/`
+  and `docs/plans/` outside drawbridge-docs, so following the skill's default path will be blocked.
 - When plan mode or a superpowers skill produces a plan/spec, the finalized document goes into
   drawbridge-docs — regardless of which repo the work targets. Note the target repo in the doc.
 - `.superpowers/` (brainstorm scratch — server state, HTML mockups) is ephemeral. **Never commit

package/hooks/guard-superpowers-docs.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// PreToolUse hook (Write/Edit/MultiEdit/NotebookEdit): superpowers plans & specs must live in
+// drawbridge-docs, never in a working repo. The superpowers brainstorming / writing-plans skills
+// hardcode a `docs/superpowers/{specs,plans}/…` save path (and tell the agent to commit it),
+// which silently overrides the passive conventions/superpowers-docs.md rule at write time. A
+// convention can't out-argue a skill's explicit step, so this enforces it: deny the write and
+// tell the agent where it belongs. See conventions/superpowers-docs.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)
+}
+
+// Path segments that are never allowed outside drawbridge-docs. These are the superpowers-skill
+// defaults (`docs/superpowers/`) plus the sibling the convention also forbids (`docs/plans/`).
+const FORBIDDEN = [ 'docs/superpowers', 'docs/plans' ]
+
+const run = () => {
+  const input = readStdin()
+
+  const tool = input.tool_name || ''
+  if (!/^(Write|Edit|MultiEdit|NotebookEdit)$/.test(tool)) process.exit(0)
+
+  const toolInput = input.tool_input || {}
+  const filePath = toolInput.file_path || toolInput.notebook_path
+  if (!filePath) process.exit(0)
+
+  // Normalise to forward slashes so the match is OS-independent.
+  const resolved = path.resolve(filePath).split(path.sep).join('/')
+
+  // drawbridge-docs is the canonical home — anything there is fine.
+  if (resolved.split('/').includes('drawbridge-docs')) process.exit(0)
+
+  const hit = FORBIDDEN.find((seg) => resolved.includes('/' + seg + '/') || resolved.endsWith('/' + seg))
+  if (!hit) process.exit(0)
+
+  deny(
+    'Blocked: superpowers plans/specs must live in drawbridge-docs, not in this repo (`' + hit + '/`). ' +
+    'The brainstorming / writing-plans skills instruct you to save here and commit — override that path. ' +
+    'Write to `../drawbridge-docs/superpowers/{plans,specs}/YYYY-MM-DD-<slug>.md` instead, and note the ' +
+    'target repo inside the doc. See conventions/superpowers-docs.md.'
+  )
+}
+
+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.9",
+  "version": "0.1.12",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {