@drawbridge/drawbridge-agents 0.1.33 → 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/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,
@@ -245,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`

package/package.json

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