@drawbridge/drawbridge-agents 0.1.33 → 0.1.36

package/.claude-template/settings.json

@@ -35,6 +35,24 @@
       "../drawbridge-website"
     ]
   },
+  "extraKnownMarketplaces": {
+    "ponytail": {
+      "source": {
+        "source": "github",
+        "repo": "DietrichGebert/ponytail"
+      }
+    },
+    "humanizer": {
+      "source": {
+        "source": "github",
+        "repo": "blader/humanizer"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "ponytail@ponytail": true,
+    "humanizer@humanizer": true
+  },
   "hooks": {
     "PreToolUse": [
       {

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

@@ -21,26 +21,49 @@ 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.
-4. **Confirm before writing.** This posts to an external system. Show the user the chosen
+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. **Run the draft through `humanizer`.** A real teammate reads this, and generated-sounding
+   prose reads as effort nobody spent. Invoke the `humanizer` skill on the drafted body: it
+   strips the AI tells — inflated claims, hedging, stock transitions, "it's worth noting",
+   restating the ask twice.
+
+   It pulls in the same direction as the word limit above, so apply it *before* the final
+   trim and re-check the result against both rules. Two things it must not touch: the
+   `<a data-asana-gid="..."/>` mention (leave the markup exactly as-is) and any concrete
+   detail from the Retest steps — if a pass makes the steps vaguer, keep the original wording.
+5. **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.
-5. **Apply** (on approval):
+6. **Apply** (on approval):
    - `asana_update_task` — set `assignee` to the last commenter's gid and `due_at` to the
      current date/time (ISO 8601).
    - `asana_create_task_story` — post the comment.
-6. **Report** the task URL, who it was assigned to, and confirm the due date was updated.
+7. **Report** the task URL, who it was assigned to, and confirm the due date was updated.
 
 ## Notes
 
 - 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/.claude-template/skills/drawbridge-ship-feature/SKILL.md

@@ -14,13 +14,22 @@ knowledge graph, and the Asana handoff so nothing drifts at ship time.
 1. **Verify it works.** Run the project's verification (the `verify` skill / build / lint /
    manual smoke — there's no unit-test framework in api/sync/app-web). Confirm the behaviour
    end-to-end, not just that it compiles.
-2. **Reconcile the spec.** Find the matching `drawbridge-docs` user story by its
+2. **Review the diff for over-engineering.** Invoke the `ponytail-review` skill on the change
+   before it merges. It reports one line per finding — reinvented stdlib, a dependency that
+   wasn't needed, a speculative abstraction, flexibility nothing calls. Act on what's real and
+   say why you're keeping anything you skip; a finding that survives review deliberately is
+   fine, one that survives because nobody looked is how the family accretes code. This is the
+   cheapest point to cut it — after merge it's someone else's inheritance.
+
+   Ponytail's baseline is already ambient (a SessionStart hook applies it at `full` intensity
+   family-wide), so this step is the explicit diff pass, not the switch that turns it on.
+3. **Reconcile the spec.** Find the matching `drawbridge-docs` user story by its
    `<domain>/<slug>` ID (or the relevant `reference/` doc). If behaviour changed, update the
    story in the same change (use `write-user-stories` for a new/edited story). If you can't,
    flag the drift explicitly. See `conventions/docs-linkage.md`.
-3. **Confirm doc anchors resolve.** Run `npx drawbridge-agents-check-docs`; fix any unresolved
+4. **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 knowledge graph — always, on every feature wrap** (not conditional on whether
+5. **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`
@@ -28,9 +37,9 @@ knowledge graph, and the Asana handoff so nothing drifts at ship time.
    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
+6. **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.
-6. **Clear the worktree.** If the feature was built in a git worktree (a sibling directory or a
+7. **Clear the worktree.** If the feature was built in a git worktree (a sibling directory or a
    `.worktrees/` folder), remove it now that the branch is merged: from the main checkout,
    `git worktree remove <path>` then `git worktree prune`. If the removal complains about
    uncommitted changes, inspect them first — add `--force` only once you've confirmed the dirt
@@ -39,6 +48,6 @@ knowledge graph, and the Asana handoff so nothing drifts at ship time.
 
 ## Notes
 
-- Steps 2–4 are what the drift-check Stop hook enforces; running them here means you won't get
+- Steps 3–5 are what the drift-check Stop hook enforces; running them here means you won't get
   blocked at turn end.
 - "Shipped" in this family means merged to `develop` (that's the deployed dev environment).

package/README.md

@@ -20,7 +20,8 @@ claude/
   CLAUDE.md                 ← aggregator — @-imports every conventions/*.md
 
 .claude-template/           ← the complete shared .claude/, mirrored into each consumer repo
-  settings.json             ← permissions, additionalDirectories, drift-check Stop hook
+  settings.json             ← permissions, additionalDirectories, drift-check Stop hook,
+                              family-wide plugin marketplaces + enabledPlugins
   skills/                   ← shared skills (drawbridge-ship-feature, -asana-ship-handoff, ...)
   hooks/  agents/  commands/
 

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.36",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {