@drawbridge/drawbridge-agents 0.1.31 → 0.1.35

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

@@ -21,13 +21,25 @@ need to retest. Use this right after merging the work to `develop` (which deploy
    (`type` / `resource_subtype` is a comment, not a system story), take the **most recent**
    one's `created_by`. This is the reassignee — do not hardcode a person. If there are no
    comments, ask the user who to assign to.
-3. **Draft the comment.** A concise summary of what changed (not a changelog dump), then an
-   explicit **Retest & verify** section: the exact steps and expected results to confirm the
-   fix, and any data/setup needed. Ground the retest steps in the actual behaviour that
-   changed. **Open the comment with an @-mention of the reassignee** — use `html_text` and
-   start the body with `<a data-asana-gid="<their user gid>"/>` (Asana expands it into a
-   proper mention). A comment without a mention may notify no one; reassignment alone is
-   easy to miss.
+3. **Draft the comment — short.** Two parts, nothing else: what changed (and, if they
+   reported a bug, what actually caused it), then a **Retest** section with the steps and
+   the expected result. Ground the steps in the behaviour that actually changed.
+
+   **Hard limit: ~200 words, and never more than 6 short paragraphs/bullets.** These
+   comments have been far too long — reading them costs the reader more than the fix did.
+   Cut: the investigation narrative, why the bug shipped, code/file/commit detail, anything
+   restating what they already reported, and any sentence that would not change what they
+   do next.
+
+   **Short is not partial.** Include everything they need in ONE comment — every scenario to
+   retest, any setup or data gotcha, and anything about the result that would otherwise look
+   wrong (an odd amount, a delay, a cosmetic leftover). A follow-up comment correcting or
+   completing this one is the failure this limit exists to prevent, so check the draft for
+   omissions *before* trimming words.
+
+   **Open with an @-mention of the reassignee** — use `html_text` and start the body with
+   `<a data-asana-gid="<their user gid>"/>` (Asana expands it into a proper mention). A
+   comment without a mention may notify no one; reassignment alone is easy to miss.
 4. **Confirm before writing.** This posts to an external system. Show the user the chosen
    assignee and the drafted comment and get a go-ahead, unless they've told you to proceed
    without asking.
@@ -42,5 +54,7 @@ need to retest. Use this right after merging the work to `develop` (which deploy
 - If the Asana MCP isn't connected, stop and tell the user to authorize it — don't fabricate a
   handoff.
 - Keep the comment user/QA-facing: what to test and expect, not internal implementation detail.
+  The reader is verifying behaviour, not reviewing the fix — if a sentence only makes sense to
+  someone who has read the diff, it does not belong in the comment.
 - Consider running `drawbridge-ship-feature` instead if docs/graph updates for this ship
   haven't been done yet — this skill is the final step of that flow.

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

@@ -54,6 +54,24 @@ skill) so it stops living only in tribal memory.
   index manually is not enough; until the boot collMod lands, every insert carrying the field
   fails Mongo 121 (not E11000), so keyed-idempotency writers silently drop their writes
   (2026-07-30 `notification.key` dev outage, Sentry DRAWBRIDGE-SYNC-32).
+- **Absent keys become BSON null on validated writes** (api ↔ sync): neither app's MongoClient
+  sets `ignoreUndefined`, so a JS `undefined` property serializes as an explicit `null` — which
+  strict validators reject wherever the key is typed non-nullable (bare `bsonType : 'string'`).
+  Submission `fields` items legally lack `label` (nothing per-item is required), so any consumer
+  copying them into a **validated** write must include keys conditionally
+  (`...( typeof label === 'string' && { label } )`), never `label : maybeUndefined`. Violated by
+  sync `buildContact` until 2026-08-22: contact CREATE is the one validated write in the upsert
+  (updates bypass), so one label-less lead failed the insert with Mongo 121 and killed the org's
+  entire nightly segment sync (Sentry DRAWBRIDGE-SYNC-32, prod).
+- **Share-page freshness is invalidation-driven, not TTL-driven** (sync ↔ api ↔ share). The api
+  render cache (`lib/render-cache.js`, 5 min TTL) and share's HTML cache (SWR, 60 s soft) are
+  both busted ONLY through sync's seam: `RENDER_AFFECTING` in
+  `lib/render-affecting-collections.js` → `render-invalidate` worker →
+  `invalidateSubdomainPageKeys`. Any collection baked into the public page payload MUST be in
+  that allowlist or its edits sit stale for the full TTL with no error anywhere — `product` was
+  missing until 2026-08-13 (Shopify renames took 5+ min to reach share pages). Product scope is
+  special: the doc carries no campaign/org refs, so the worker resolves featuring campaigns via
+  `campaign.products[]`, per-page org (canonical product docs can span orgs).
 - 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,
@@ -116,6 +134,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 +188,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
@@ -208,6 +263,32 @@ skill) so it stops living only in tribal memory.
   parsed milliseconds — `frameMilliseconds` in api `route/organization-file.js`, `lib/frames.js`
   in app-web.
 
+## File uploads (utils ↔ api ↔ sync ↔ app-web)
+
+- `drawbridge-utils/lib/upload.js` is the ONLY allowlist of what may be uploaded, and now also
+  owns `maximumUploadBytes` + `uploadPartSize()`. api validates against it, sync mimes-checks
+  against it, app-web derives its `accept` attribute, "Accepted formats" row and uploader
+  restrictions from it. Adding a format = edit + publish utils + bump the pin in all three; a
+  hand-written copy anywhere is how a format gets accepted by one side and rejected by another.
+- **app-web must compute the part size itself**, not read it from the create response — Uppy's
+  `MultipartUploader` builds its chunk array in its constructor, *before* `createMultipartUpload`
+  is called. Both sides call the same `uploadPartSize()` so the boundaries cannot disagree.
+- **Never derive a file's extension from the mime subtype.** That works only where subtype ==
+  extension; an iPhone `.mov` is `video/quicktime`, so the naive split sends `quicktime` and the
+  upload 400s before a byte moves. app-web `fileParts()` in `lib/helpers.js`.
+- **api and sync deploy together for multipart.** The presigned routes create the `file` doc
+  BEFORE the bytes (`status: 'pending'`, `bytes: 0`), so without sync's update-side
+  `fileBytesDelta` the file counts as ZERO toward `organization.totals.storage` forever — the
+  storage restriction passes indefinitely and we under-bill, with nothing erroring.
+- **Spaces bucket CORS must set `ExposeHeaders: [ ETag ]`** for the dashboard origin. Without it
+  `@uppy/aws-s3`'s `uploadPartBytes` cannot read the part ETag and returns without resolving or
+  rejecting — the upload hangs forever with no error, no retry and no timeout.
+- Abandoned multipart parts are BILLED by Spaces while invisible to bucket listings, so the
+  `file.sweep` job in drawbridge-sync (hourly, 6h window) is not optional. Golden Retriever's
+  `expires` in app-web must match that window.
+- `sizes.original` must be set when a multipart upload completes, not at create — the resize
+  worker reads it as its source, and a file without it is shaped unlike every other file.
+
 ## Import surfaces
 
 - Import names against a package's **actual exports** — a missing export resolves to `undefined`
@@ -220,9 +301,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.35",
   "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.'
-	};
-
-});