@drawbridge/drawbridge-agents 0.1.31 → 0.1.33

package/.root-template/CLAUDE.md

@@ -0,0 +1 @@
+@./node_modules/@drawbridge/drawbridge-agents/claude/CLAUDE.md

package/bin/sync-claude.js

@@ -16,10 +16,18 @@ const rmrf = (p) => {
 
 const copied = []
 
-// Root-template files are stored dotless and the leading dot is restored on mirror. This is
-// required for `npmrc` (npm strips a literal `.npmrc` from published tarballs) and applied to
-// the rest for one consistent rule: template files never start with a dot.
+// The complete manifest of what .root-template installs, as stored name -> installed name.
+// EVERY file in .root-template needs an entry, including one that installs under its own name:
+// test/package.test.js asserts the map covers the directory, and that only works as a tripwire
+// if the map is exhaustive. Adding a file without an entry is the mistake being guarded against
+// — a dotfile stored dotless would land in consumers without its dot and silently do nothing.
+//
+// Dotfiles are stored dotless because npm strips a literal `.npmrc` from published tarballs;
+// the rest follow for one consistent rule: nothing in a template directory starts with a dot.
+// CLAUDE.md is not a dotfile and installs unchanged — its entry is an identity mapping, which
+// is a deliberate declaration rather than an oversight.
 const RENAME = {
+  'CLAUDE.md': 'CLAUDE.md',
   editorconfig: '.editorconfig',
   'mcp.json': '.mcp.json',
   nvmrc: '.nvmrc',

package/conventions/cross-repo-contracts.md

@@ -116,6 +116,12 @@ skill) so it stops living only in tribal memory.
   `schema/action.js`) is a shared dependency: sync's `computeCycleActions` (billing, by `createdAt`
   window) AND api's date-ranged reporting (`route/organization-usage.js`) both match on it. Drop it
   → COLLSCAN on every invoice + usage query.
+- An `action` row's **`units` are BILLABLE units, never a display metric**. A `submission` row
+  carries accepted entries on a giveaway (drawbridge-sync `stream/submission.js`) but 1 per
+  submission on a default campaign, which collects no entries at all (drawbridge-api
+  `route/subdomain-submission.js`) — so both writers stamp the real count at `meta.entries`, and
+  reporting (`route/organization-usage.js`) reads that. Reading `units` as Entries made the Usage
+  page's Entries card mirror Submissions for every default campaign (Asana 1217406893229252).
 - The `action` ledger is **permanent — no TTL** (drawbridge-api `schema/action.js`): the
   proof-of-billing record AND the source for date-ranged usage reporting, both read as raw rows by
   `createdAt`. Re-adding a TTL shorter than any billing interval silently under-bills long cycles
@@ -164,6 +170,37 @@ skill) so it stops living only in tribal memory.
   land on the wrong day). The param rides each endpoint's existing query shape (top-level vs
   `filters`) — do NOT normalise the shapes.
 
+## OTC dispatch: silence is never success (api ↔ app-web ↔ sync)
+
+- The auth request endpoints (`/oauth/signin/request`, `/oauth/signup/request`) answer `200
+  { result : { otcId : null } }` for a malformed address and for an internal error — deliberately
+  shaped like success so neither can be probed. **A missing `otcId` means NOTHING was dispatched;
+  a client must never advance to a "we sent you a code" screen on one.** app-web enforces this in
+  one place, `lib/otc.js` `requestOtc()`. Advancing anyway is invisible to every alarm we have:
+  the user waits on mail that does not exist and nothing anywhere records a failure.
+- The **reCAPTCHA verdict is NOT an enumeration signal** — it is computed before the email is
+  parsed — so an auth block answers explicitly (403 refresh / 503 outage), unlike the email-shape
+  branches. Don't "harmonise" it back to the silent 200.
+- `google.recaptcha.verify()` **throws** on both a refused token and a Google outage (the outage
+  carries `status: 503`). Express 4 does not route a rejected promise to the error handler, so any
+  async middleware calling it MUST try/catch and `next( error )` — unguarded it dangles the request
+  with no response at all (`route/organization-issue.js` did exactly this).
+- Auth code emails are dispatched by **sync** (`stream/otc.js`, on the change-stream update that
+  writes `code.text`) and must state the window **api** enforces: `lifetimes.code` from
+  drawbridge-utils (15 min). The prize-draw branch is a genuinely different 5 min
+  (api `route/otc.js` CODE_TTL_MINUTES) — the two are not interchangeable.
+
+## Growth attribution tags (growth ↔ api)
+
+- drawbridge-growth `lib/tags.js` MIRRORS drawbridge-api `lib/utm.js` — allow-listed keys, trim,
+  255 cap then lowercase `source`/`medium`, in that order. The API side is what actually stores a
+  tag when a click lands; a drifted mirror shows salespeople a tuple that never existed. Growth's
+  `test/tags.test.js` asserts parity against the API's source file — changing `lib/utm.js` fails
+  growth's suite, which is the intended tripwire, not an accident.
+- `campaign.destination.utm.id` is the ONLY key a signup joins back on and is unique-indexed
+  (partial, `$type: 'string'`) in growth's schema. Two campaigns sharing a utm_id don't split
+  signups — each claims all of them and both read as working, invisibly.
+
 ## `@drawbridge/*` package coordination
 
 - Pins are version-exact across the whole family; bumping one package means auditing every
@@ -220,9 +257,28 @@ skill) so it stops living only in tribal memory.
   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.
+  string-matches the not-found message to deactivate the product and send 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.
+- **`sendProductResourceFeedback` returns `null` for states Shopify won't carry — that is not a
+  failure.** Shopify accepts product feedback only for a product published to the calling app's
+  channel, and refuses anything else with `'… not available to the channel'`. That is exactly
+  the state REQUIRES_ACTION describes (unpublished, or drafted — drafting also removes it), so
+  the refusal is matched and returned as `null` rather than thrown. Treating `null` as an error
+  re-creates the 2026-08-12 QA finding: a per-sync failure report for an expected condition,
+  which is what buried the real defect. The embedded app's publishing section is the surface for
+  these products (App Store 5.7.8/5.7.11), not the product page.
+- **Feedback must forward the product's own `updatedAt`, never a fresh timestamp.** Shopify
+  versions feedback on `productUpdatedAt` and refuses a payload older than the version it holds,
+  so stamping `new Date()` records a version ahead of the product and every later send comes back
+  `'Feedback for a later version of this resource was already accepted'`. `@drawbridge/shopify`
+  reads it (costing one extra `read_products` query per send) so callers cannot get this wrong.
+- **ResourceFeedback messages are format-validated by Shopify, not by us**: one message, ≤ 100
+  characters, leading capital, trailing period, not all caps. A breach fails the whole send.
+- Feedback failures in sync go through `logger.error`, never `logger.warn` — a warn reaches
+  Sentry **Logs** but not **Issues**, which is how a feedback path failing on every send survived
+  two rounds of QA that were explicitly pointed at Issues.
 - 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/package.json

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

package/scripts/channels.js

@@ -1,88 +0,0 @@
-// What communication channels are actually flowing, HubSpot's count against ours.
-//
-// Exists because "the integration is connected" and "the data is arriving" are
-// different claims, and the second is the only one that matters here. HubSpot's
-// communication object holds SMS, WhatsApp and LinkedIn messages, told apart by
-// channel — so whatever writes LinkedIn messages into that object, this pipeline
-// reads. The question is never whether we can read them; it is whether anything is
-// writing them.
-//
-// Same shape as the `missing` figure on the contact ingest, which is what caught 50
-// contacts that had been silently absent for the life of the project.
-
-const { growth } = require( '../lib/mongodb' );
-const { enabled, request } = require( '../lib/hubspot' );
-const { run } = require( '../lib/cycle' );
-
-// The channels HubSpot files under the communication object. PHYSICAL_MAIL is
-// hidden on this portal but counted anyway, because a hidden property still holds
-// records.
-const CHANNELS = [
-	'LINKEDIN_MESSAGE',
-	'SMS',
-	'WHATS_APP',
-	'PHYSICAL_MAIL',
-	'CUSTOM_CHANNEL_CONVERSATION'
-];
-
-run( 'channels', async () => {
-
-	if( ! enabled() ) return { skipped : 'HUBSPOT_ACCESS_TOKEN not set' };
-
-	const { db, database } = await growth();
-
-	const report = {};
-
-	for( const channel of CHANNELS ){
-
-		const body = await request({
-			body : {
-				filterGroups : [
-					{
-						filters : [
-							{
-								operator : 'EQ',
-								propertyName : 'hs_communication_channel_type',
-								value : channel
-							}
-						]
-					}
-				],
-				limit : 1
-			},
-			method : 'POST',
-			path : '/crm/v3/objects/communications/search'
-		});
-
-		const inHubspot = Number( body?.total || 0 );
-
-		// Ours is counted on the touch, which is one row per contact on the message,
-		// so it can legitimately exceed HubSpot's count of messages.
-		const held = await database.collection( 'touch' ).countDocuments({
-			channel,
-			type : 'communication'
-		});
-
-		report[ channel ] = {
-			held,
-			inHubspot,
-			// The number that answers "is anything writing this channel".
-			missing : inHubspot === 0 ? 0 : Math.max( 0, inHubspot - held )
-		};
-
-	}
-
-	const flowing = Object.entries( report )
-		.filter( ( [ , value ] ) => value.inHubspot > 0 )
-		.map( ( [ key ] ) => key );
-
-	return {
-		byChannel : report,
-		// Empty means nothing outside email, calls, meetings, notes and tasks is
-		// reaching HubSpot at all - which is a setup answer, not a pipeline answer.
-		flowing : flowing.length ? flowing : 'nothing beyond email/calls/meetings/notes/tasks',
-		note : 'LINKEDIN_MESSAGE at 0 means no tool is writing LinkedIn messages into'
-			+ ' HubSpot. Whatever writes them, this pipeline already reads them.'
-	};
-
-});