@drawbridge/drawbridge-agents 0.1.12 → 0.1.15

package/claude/CLAUDE.md

@@ -12,6 +12,7 @@
 @../conventions/drawbridge-packages.md
 @../conventions/sentry-sdk.md
 @../conventions/app-web-forms.md
+@../conventions/app-web-gates.md
 @../conventions/docs-linkage.md
 @../conventions/superpowers-docs.md
 @../conventions/git-branching.md

package/conventions/app-web-gates.md

@@ -0,0 +1,22 @@
+# app-web gate helpers
+
+Applies to `drawbridge-app-web` only.
+
+UI gating goes through the shared helpers in `@/lib/helpers` — never inline the
+underlying object walks:
+
+- `hasCapability( organization, key, level = 'manage' )` — capability checks by
+  dot-path (`'campaigns.settings'`, `'brands'`). Never write
+  `organization?.capabilities?.x === 'manage'` inline; a missed optional chain
+  in that pattern has crashed pages before.
+- `hasConnection( organization, slug )` — "org has an ACTIVE connection for
+  this slug". Reads `connectionItems` from the org payload (see the
+  organization-payload contract in `cross-repo-contracts.md`); never fetch
+  `/organization/:id/connections` just to gate UI.
+- `hasRestriction( object, key )` — plan-limit restrictions on an org or
+  campaign.
+
+Compose extras (`getPlanFeature(...).granted`, totals checks) explicitly at the
+call site; the helpers stay single-purpose. Pass the org from the
+`[ 'organization', id ]` query cache (or an `enabled : false` `useQuery` on
+that key when the component must re-render as it refreshes).

package/conventions/cross-repo-contracts.md

@@ -26,6 +26,12 @@ skill) so it stops living only in tribal memory.
   `queue/index.js` together.
 - BullMQ jobs are keyed on the change-stream resume token as `jobId` for HA dedup across sync
   replicas. Reusing a static `jobId` with `removeOnComplete` makes re-enqueues no-op silently.
+- Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
+  `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
+  and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
+  `render` content-hashes the rendered output — drop `render` from either side and a rendering
+  fix never ships: reuse serves the first-ever render forever (the onemethod
+  black-on-black-logo-twice bug).
 
 ## Billing / metering
 
@@ -75,3 +81,19 @@ skill) so it stops living only in tribal memory.
 - 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.
+- `SHOPIFY_REQUIRED_SCOPES` (`@drawbridge/shopify` `lib/constants.js`) must stay in lockstep with
+  `[access_scopes]` in drawbridge-shopify-app's `shopify.app.*.toml` (both files). drawbridge-api
+  diffs each store's granted scopes against it to flag "update permissions" on the connections
+  page. A scope added to the toml but not the constant silently escapes the check; one added to
+  the constant but not the toml flags every store forever.
+
+## Organization payload (api ↔ app-web)
+
+- `connectionItems` on the org payload comes only from drawbridge-api
+  `extend.organization({ connections : true })` (org GET + org menu opt in via
+  `hasOrganizationAccess`); app-web's `hasConnection` helper (`lib/helpers.js`) and api's
+  `lib/tasks.js connectionErrors` read it. Two invariants: the lookup's `$project`
+  (id/slug/status/title/shop/errors) is a **security boundary** — the org response spreads to the
+  browser, so adding a credential field ships connection tokens to every dashboard user; and api
+  deploys before app-web — the gate treats a missing field as "no connection" and silently hides
+  connection-gated UI (e.g. the campaign Shop product columns row).

package/package.json

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