@drawbridge/drawbridge-agents 0.1.49 → 0.1.51

package/claude/CLAUDE.md

@@ -14,6 +14,7 @@
 @../conventions/app-web-forms.md
 @../conventions/app-web-gates.md
 @../conventions/docs-linkage.md
+@../conventions/humanized-copy.md
 @../conventions/superpowers-docs.md
 @../conventions/git-branching.md
 @../conventions/graphify.md

package/conventions/cross-repo-contracts.md

@@ -7,7 +7,7 @@ skill) so it stops living only in tribal memory.
 
 ## Shared secrets must match across services
 
-- `OAUTH_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
+- `HMAC_OAUTH_TOKEN_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
   `assertEnv` it at boot. A mismatch silently breaks realtime token verification.
 - `HMAC_UNSUBSCRIBE_TOKEN_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** —
   both `assertEnv` it at boot. Sync signs the unsubscribe tokens it builds into notification
@@ -153,17 +153,34 @@ skill) so it stops living only in tribal memory.
   would have zeroed every invoice once the products were archived.
 - **The v2 pricing-plan layer (`bpp_*`, billing cadences) is never touched by script.** Canceling a
   billing cadence is terminal and unrecoverable. Dashboard, by hand, only.
-- **The Shopify meter handle is a config contract no code validates** (shopify ↔ Partner
-  Dashboard ↔ sync/utils). `SHOPIFY_USAGE_ORDERS_EVENT_HANDLE` in `@drawbridge/shopify`
-  (`drawbridge-orders`) must exactly match — case-sensitive, handle not display name — a usage
-  meter on the App Pricing plan version each merchant has APPROVED (meters are never
-  retroactive). A mismatch, a missing meter, or a merchant on a pre-meter plan still 202s every
-  event, logs it as a plain app event, and bills nothing; no error surfaces anywhere in code
-  (the 19/99 write-off). Any change to the handle constant, the Partner Dashboard pricing
-  config, or a plan version requires verifying a fresh order classifies as a billing event in
-  Dev Dashboard → Logs (type "App billing event"). The trace key both sides share is
-  `billed.transaction` = the event's `reference` = `drawbridge-orders.<orderId>`. Detail:
-  drawbridge-docs `reference/shopify-app.md` (Billing).
+- **The Shopify meter handle is manifest data, provider-overridable, and sender-verified
+  (≥ utils 0.0.151)** (utils ↔ sync ↔ api ↔ Partner Dashboard). The utils shopify manifest
+  publishes `events.order.handle` = `slugify('drawbridge-orders')`; the provider row's
+  `orderEventHandle` field (admin-editable, `format:'slug'` — normalized on save AND read)
+  overrides it at mint time. The order hook puts the effective handle on the billing job and
+  mints `billed.transaction` = `<handle>.<orderId>` (also the event's `reference` attribute —
+  the shared trace key). `sendAppEvent` has NO default handle any more, and sync's sender
+  REFUSES to send when the job carries none (`shopify.usage.billing.handle.missing`) or when
+  the transaction prefix disagrees (`…handle.mismatch`) — both before any provider read, both
+  page through the abandoned alert. The handle must still exactly match — case-sensitive,
+  handle not display name — a usage meter on the plan version each merchant APPROVED: meters
+  attach only at approval and are never retroactive, and a pre-meter approval 202s every event
+  and bills nothing (the 19/99 write-off; also every pre-2026-09 production approval).
+- **Shopify billing proof comes only from the Partner ledger; absence is never a verdict**
+  (utils ↔ sync ↔ api ↔ app-web). No Admin API version materializes a managed-pricing meter
+  (measured 2026-09-04), so `connection.source.metered` is a billing-PROOF reference: the
+  latest positive `CHARGE_USAGE` charge id from the Partner API (provider row fields
+  `partnerOrgId`/`partnerAppId`/`partnerToken`), `null` only from measured unmetered evidence,
+  absent = never proven — and every consumer (task card, checklist item, billing Issue,
+  presented-error status, admin badges, App Home error row) gates on the explicit null, never
+  on silence. Writers: the daily health run, the approval webhook's instant restamp, and the
+  reselect flow's stale-null lift (a completed reselect returns a null-stamped store to
+  no-verdict — the null described the approval that was just replaced). Charge rows exist only
+  at billing boundaries (usage accrues invisibly between them); each row is reconciled once
+  against its window's orders — balanced stamps `billed.receipt`, a mismatch pages
+  `shopify.usage.reconciliation.mismatch`, and admin-voided orders (`billed.void`, the
+  write-off for pre-meter losses) leave both the sums and the dashboard's unreconciled count.
+  Detail: drawbridge-docs `reference/shopify-app.md` (Billing).
 - **A subscription must open with the plan item.** It used to open with the metered actions price
   and attach the plan afterwards with `always_invoice`. With no metered item, Stripe rejects an
   itemless subscription, so the plan goes in at creation — changing the first invoice's shape.

package/conventions/humanized-copy.md

@@ -0,0 +1,25 @@
+# Humanize every word a person will read
+
+Any prose you write that a human will read as *product or communication* goes through the
+`humanizer` skill before it ships or posts. No exceptions for length — a two-line Asana
+comment counts.
+
+Covers, at minimum:
+
+- App/UI copy: labels, buttons, empty states, error and notice messages, tooltips, onboarding.
+- Asana comments and task descriptions, ship handoffs, retest instructions.
+- Docs and user stories, README prose, release notes.
+- Emails, SMS bodies, notification text, outreach drafts (growth), article/content drafts.
+- Anything else a customer, teammate, or prospect reads as writing.
+
+Does NOT cover: code, commit messages, code comments, test names, log lines, schema
+descriptions — engineer-facing text follows the code conventions instead.
+
+Rules when running it:
+
+- Run humanizer BEFORE posting/committing the copy, not after someone flags it.
+- It must not change facts, numbers, steps, or expected results — if a pass makes concrete
+  instructions vaguer, keep the original wording for those parts.
+- Leave markup intact (Asana mention tags, links, placeholders like `{name}`).
+- If the humanizer skill is not available in your session, say so and flag the copy as
+  un-humanized — do not silently skip the pass.

package/package.json

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