voidmachine 5.0.8 → 7.0.0

package/core-assets/hooks/outcome-meter.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# Non-blocking adapter for PostToolUse and Stop canonical events.
+# PostToolUse outcomes and repeated-read advice share this non-blocking process.
+# PostToolUseFailure resets advice only; Stop retains its canonical event.
 set -uo pipefail
 
 ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"

package/core-assets/hooks/tdd-guard.md

@@ -1,90 +1,47 @@
 # `tdd-guard` hook
 
-PreToolUse hook on `Edit` / `Write`. Materializes the `void-tdd` skill's Iron Law mechanically: blocks edits to production paths that add behavior without a corresponding test change in the same staged change set, unless a legitimate bypass applies.
-
-In `strict` mode: blocks (exit 1).
-In `souple` mode: warns (exit 2).
-In `exploratory` mode: no-op (exit 0).
-
-See `docs/plans/skill-audits/void-tdd.md` for the Iron Law and the bypass rationale. See Section 0bis.3 of `docs/plans/2026-05-29-void-harness-design.md` for the list of legitimate bypasses.
-
-## Configuration
-
-Read from `.void/config.json` of the consumer project:
-
-```json
-{
-  "modes": { "tdd": "auto" },
-  "paths": {
-    "business": "apps/*/src/**",
-    "tests": "apps/*/src/**/*.test.{ts,tsx}",
-    "spikes": "apps/*/scripts/spike-*"
-  }
-}
-```
-
-If `.void/config.json` is absent, sensible defaults are used (see hook source).
-
-## Bypasses applied (in order)
-
-1. Doc-only changes (`.md`, `.mdx`, `.txt`, files under `docs/`)
-2. Config and build files (`package.json`, `tsconfig.json`, `vitest.config.*`, `next.config.*`, `tailwind.config.*`, `drizzle.config.*`, `biome.json`, `eslint.config.*`)
-3. Test fixtures and seed data (`tests/fixtures/**`, `**/__tests__/fixtures/**`, `**/seed/**`)
-4. DB migrations (`**/migrations/**`, `drizzle/meta/**`) — covered by `void-migrations` skill
-5. Spike paths (consumer-defined; default `apps/*/scripts/spike-*`)
-6. Codemods (`**/codemods/**`)
-7. Type-only changes (`*.d.ts`)
-8. Generated code (`**/__generated__/**` or `@generated` marker in the first 3 lines)
-9. The test file itself (`*.test.ts`, `*.test.tsx`, `*.spec.ts`, `*.spec.tsx`)
-10. Per-file exploratory marker (`// tdd-mode: exploratory` in the first 5 lines)
-
-## Content bypass: a module that only re-exports
-
-The ten bypasses above are properties of the **path**. One is a property of the **content**: a module whose every top-level statement is a re-export (`export … from`, `export *`, `export {}`) carries no behaviour, so the test one would write for it would assert that an export exists, which the compiler already proves. A comment, a `'use client'` directive and a type-only import do not break the detection; anything else does.
-
-Both the file as it stands and the fragment being written must hold, so a barrel that gains one line of logic is covered again on that same edit. Malformed content (an unterminated string or block comment) is undecidable and stays covered.
-
-Without it the hook blocked a one-line barrel in a consumer where 51 barrels out of 51 have no sibling test by convention, and the edit went out through `sed`, outside the traced tools: the guard did not protect, and it pushed the work out of its own field of vision.
-
-## Pure-deletion bypass
-
-If the staged diff for the file contains only deletions (no `+` non-marker lines), the hook allows. Pure deletion does not require a new failing test.
-
-## Override
-
-- Per-file: add `// tdd-mode: exploratory` (or `strict` / `souple`) at the top of the file.
-- Per-repo: set `.void/config.json` `modes.tdd` to `strict` / `souple` / `exploratory`.
-- Per-session: set env `VOIDCORP_MODE_TDD=souple` (not yet wired — open question).
-
-## Inputs (env vars set by the runner)
-
-- `VOIDCORP_HOOK_FILE` — absolute path of the file
-- `VOIDCORP_HOOK_TOOL` — `Edit` / `Write`
-- `VOIDCORP_HOOK_PHASE` — `pre` / `post` (this hook only runs on `pre`)
-- `VOIDCORP_HOOK_DIFF` — optional, the staged diff content
-- `VOIDCORP_CONFIG` — optional, defaults to `.void/config.json`
-
-## Exit codes
-
-- `0` — allow
-- `1` — block (message on stderr)
-- `2` — warn (allow, message on stderr)
-
-## Test fixtures (for `test/tdd-guard/`)
-
-The skill test suite must cover at least:
-
-- `strict` mode + production edit without sibling test → block
-- `strict` mode + production edit WITH sibling test in same staged set → allow
-- `souple` mode + production edit without sibling test → warn
-- `exploratory` mode + any edit → allow
-- Each of the 10 bypasses → allow
-- Pure deletion → allow
-- Override marker `// tdd-mode: exploratory` in file → allow
-
-## Open questions
-
-- Per-session env override (`VOIDCORP_MODE_TDD`) — wire it up in the hook or rely on `.void/config.json` only? Lean wire (faster iteration during work).
-- Glob matching for `paths.business` — current `case` statement is shell glob, fine for simple patterns but not full minimatch. Defer until a consumer needs `**` patterns more complex than `apps/*/src/**`.
-- Auto-detection of the test runner (vitest vs jest) for the sibling-test naming convention. Currently assumes `.test.ts(x)`. Make configurable in Phase D.
-- Performance — `git diff --cached --name-only` runs every edit. Cache for the duration of a session? Defer; measure first.
+The native PreToolUse manifests invoke the shared Node `tdd-order` rule for
+supported structured writes. `tdd-guard.sh` is its compatibility adapter.
+`packages/hook-runner/src/rules/tdd-order.ts` owns the structural rule and
+`enforcement/runner.ts` resolves the proposed file and evidence.
+
+This floor checks that a governed production file has an existing sibling test,
+or a valid first-line `// tdd-cover: e2e <project-relative spec>` declaration pointing
+to an existing test inside the project. It does **not** run that test, require a
+staged test modification, assess behavior coverage, or prove an observed RED.
+`void-tdd` and `void-debug` own the observed RED-before-fix/GREEN evidence.
+
+## Configuration and scope
+
+The rule reads `.void/config.json`: `modes.tdd`, `paths.business` and `paths.spikes`.
+The default business glob is `apps/*/src/**`; the default spike glob is
+`apps/*/scripts/spike-*`. The first five existing lines may declare
+`// tdd-mode: strict`, `souple` or `exploratory`.
+
+- `auto` and `strict` refuse a governed write with no test evidence.
+- `souple` allows it with a warning.
+- `exploratory` allows it.
+
+Only the supported JS/TS production paths inside business globs are governed.
+The owning rule excludes test/declaration files, docs, fixtures, seeds, migrations,
+codemods, generated paths and configured spikes. This is a path floor, not a
+semantic classifier of all configuration or generated code.
+
+A complete file deletion is exempt. A deletion-only edit to a surviving file is
+still checked. A module containing only re-exports is exempt only when both the
+original and complete proposed source meet that condition. Adding behavior removes
+the exemption. Unresolvable evidence on a governed file is refused, not guessed.
+
+## Runtime results
+
+The rule returns a verdict. Runtime adapters translate a refusal into Claude's
+blocking exit 2 or Codex's native deny response; warning and allow are successful
+responses. There are no `VOIDCORP_HOOK_FILE`, staged-diff or per-session TDD env
+inputs to this native contract. Configured does not mean invoked: the runtime must
+load and trust its hooks. Shell writes do not provide this test-content guarantee.
+
+## Proof
+
+The rule and enforcement tests cover sibling/declaration existence, modes,
+re-export detection, path escapes, deletion-only edits and unsupported evidence.
+Behavioral RED/GREEN for the changed application remains a separate required proof.

package/core-assets/hooks/viewport-screenshot-gate.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# viewport-screenshot-gate — pre-push hook
+# viewport-screenshot-gate — optional PR-text advisory (not installed in native manifests)
 #
-# Warns if a PR touching UI code lacks both mobile and desktop screenshots
+# Reports if PR text for UI changes lacks mobile and desktop capture references
 # in the PR body. Composed with the `accessibility` and
 # `frontend-design` skills (mobile-first dual-quality invariant).
 #
@@ -13,7 +13,7 @@
 # "no-ui-change: <reason>" in the body for non-UI PRs that happen to
 # touch tsx files.
 #
-# Exit codes: 0 allow, 2 warn.
+# No image validation. Missing PR/base is skipped. Exit 0 no finding, 2 advisory finding.
 
 set -euo pipefail
 

package/core-assets/packs/pack-monorepo/skills/void-dependency-direction/SKILL.md

@@ -1,160 +1,41 @@
 ---
 name: void-dependency-direction
-description: Enforce the @repo/* import direction in a Turborepo workspace. Concrete violations + fixes. Composes with core:hexagonal-architecture and the boundary-direction-check hook.
+description: Declare cross-package dependencies explicitly and preserve domain-owned ports. Use when crossing a workspace package boundary or fixing boundary-direction-check.
 ---
 
 # dependency-direction
 
-Use when adding an `import` statement that crosses a package boundary, or when fixing a `boundary-direction-check` hook violation. This skill is the **operational guide** for the rules core `void-hexagonal-architecture` and `boundary-direction-check` enforce mechanically.
+The package's `package.json` owns its permitted package dependencies. The project's
+architecture owns which dependencies make sense. A universal star topology through
+`@repo/core` is not imposed by the harness.
 
-## The rule
+## Before adding an import
 
-```
-@repo/core    →   nothing internal
-@repo/auth    →   @repo/core
-@repo/db      →   @repo/core
-@repo/ui      →   @repo/core
-@repo/<feat>  →   @repo/core   (and only @repo/core)
-apps/<app>    →   any @repo/*
-```
+1. Read the consuming package's manifest and project architecture.
+2. Keep domain code independent of concrete infrastructure; compose adapters through
+   domain-owned ports, per `void-hexagonal-architecture`.
+3. Declare an accepted dependency in the appropriate manifest section. Types create
+   dependencies too. Import the package's public API, not a sibling's private files.
+4. If the dependency would violate an accepted project boundary, reshape the port
+   and compose at the application edge. A structural exception follows `void-decide`.
+5. Run the affected package's typecheck and behavior tests.
 
-**No `@repo/*` package imports another `@repo/*` except `@repo/core`.** All composition happens at the app level. If `@repo/billing` needs the user, it defines a port; the consuming app wires `@repo/auth`'s adapter into that port.
+## Mechanical scope
 
-This sounds restrictive. It is. It is what keeps the monorepo from collapsing into a hairball.
+The shared Node `boundary-direction-check` rule rejects detected scoped imports
+that the nearest readable package manifest does not declare. It accepts self-imports
+and dependencies, devDependencies, peerDependencies and optionalDependencies.
+It skips tests/generated files and allows when no manifest can be read. Its lexical
+matcher is a guardrail, not a complete import graph or internal-layer validator.
+An `allow-boundary:` comment is a narrow escape recognized by the existing rule;
+it does not approve an architectural exception or make a missing dependency buildable.
 
-## Why core is the only allowed dependency
-
-`@repo/core` ships **primitives** with no internal deps:
-
-- `logger` (pino)
-- `env` (Zod-validated env)
-- `errors` (typed error classes)
-- `Result`, `Option`, `pipe` (functional utilities)
-
-These are leaf utilities. Everything else is composition.
-
-## Common violation: `@repo/billing` wants the user
-
-**Wrong**:
-```ts
-// packages/billing/src/billing.service.ts
-import { db } from '@repo/db';                  // ✗
-import { getCurrentUser } from '@repo/auth';    // ✗
-
-export async function cancelSubscription() {
-  const user = await getCurrentUser();
-  await db.update(subscriptions)...
-}
-```
-
-**Right** — define the port in `@repo/billing`, wire the adapter in the app:
-
-```ts
-// packages/billing/src/billing.types.ts (port)
-export interface BillingPorts {
-  readonly userRepo: { findById(id: string): Promise<User | null> };
-  readonly subscriptionRepo: { update(id: string, p: Partial<Sub>): Promise<void> };
-}
-
-// packages/billing/src/billing.service.ts (pure)
-export function makeBillingService(ports: BillingPorts) {
-  return {
-    async cancelSubscription(userId: string) {
-      const user = await ports.userRepo.findById(userId);
-      // ... domain logic only
-    },
-  };
-}
-
-// apps/web/src/adapters/billing.ts (composition)
-import { makeBillingService } from '@repo/billing';
-import { db } from '@repo/db';
-import { userRepo, subRepo } from '@/repositories';
-export const billing = makeBillingService({ userRepo, subscriptionRepo: subRepo });
-```
-
-The app is the integration point. Packages are pure capabilities.
-
-## Common violation: types from another package
-
-**Wrong**:
-```ts
-// packages/billing/src/billing.types.ts
-import type { User } from '@repo/auth';  // ✗ types still create coupling
-```
-
-**Right** — declare your own User type narrowed to what billing needs:
-
-```ts
-// packages/billing/src/billing.types.ts
-export interface BillingUser {
-  readonly id: string;
-  readonly email: string;
-  readonly orgId: string;
-}
-```
-
-If `@repo/auth`'s `User` and `@repo/billing`'s `BillingUser` should be the same shape, factor the shape into `@repo/core/types`. But almost always, each package wants a narrower projection — that's good.
-
-## Common violation: `@repo/ui` calls a service
-
-**Wrong**:
-```tsx
-// packages/ui/src/UserAvatar.tsx
-import { getCurrentUser } from '@repo/auth';   // ✗
-export function UserAvatar() {
-  const user = use(getCurrentUser());          // ✗ side effect in UI
-  return <Avatar src={user.avatarUrl} />;
-}
-```
-
-**Right**:
-```tsx
-// packages/ui/src/Avatar.tsx (dumb prop-driven)
-export function Avatar({ src, fallback }: { src: string; fallback: string }) {
-  return <img src={src} alt={fallback} />;
-}
-
-// apps/web/src/components/CurrentUserAvatar.tsx (binding, NOT in @repo/ui)
-import { Avatar } from '@repo/ui';
-import { useCurrentUser } from '@/hooks';
-export function CurrentUserAvatar() {
-  const user = useCurrentUser();
-  return <Avatar src={user.avatarUrl} fallback={user.name} />;
-}
-```
-
-`@repo/ui` exports primitives with no I/O. Bindings to actual data live in apps.
-
-## The `apps/<app>` → `apps/<other-app>` rule
-
-**Never** import from another app:
-
-```ts
-// apps/web/src/foo.ts
-import { whatever } from '../../mobile/src/...';  // ✗ — even via @repo/* alias if you set it up
-```
-
-If two apps need the same code, that code goes in a `@repo/*` package. There is no "shared/" directory between apps.
-
-## When you genuinely need cross-package access
-
-You don't. Re-read the section on ports. If after that you still think you do, write an ADR (`void-decide`) documenting the exception with the reversal cost. 90% of "I need this" turns out to be "I forgot to define the port".
-
-## Mechanical enforcement
-
-The `boundary-direction-check` hook (core) blocks Edit/Write that introduces a forbidden import. Override by tagging the import line `// allow-boundary: <reason>` — but think hard first, because each exception is a small future grind.
-
-## Workflow
-
-1. **Before adding the import**, ask: does this cross a `@repo/*` boundary?
-2. **If yes**, ask: is the destination `@repo/core`? OK. Anything else? Stop.
-3. **Define a port** in your package, wire the adapter in the app.
-4. **If the hook complains**, do not tag-and-move-on. Refactor.
+A `tsconfig` path alias changes resolution, not permission. It cannot prove a
+package boundary. Project-specific cycle or layer checks must be explicitly wired
+and verified before claiming deterministic enforcement.
 
 ## Composition
 
-- `void-hexagonal-architecture` — doctrine on ports + adapters direction (core).
-- `boundary-direction-check` hook (core) — mechanical gate.
-- `void-package-extraction` — most boundary problems come from premature extraction.
-- `void-service-package` — the 5+5 layout includes a `<name>.types.ts` precisely for owning your own types.
+- `void-hexagonal-architecture` owns ports and dependency direction inside a domain.
+- `void-service-package` applies the project package layout.
+- `void-package-extraction` decides whether a shared package is warranted.

package/core-assets/packs/pack-monorepo/skills/void-service-package/SKILL.md

@@ -52,15 +52,12 @@ service ─→ repository (port)   service ─→ helper   service ─→ types
 
 If your package needs `@repo/db` directly: stop. Move the DB-touching code into an adapter in the consuming app. The package owns the **port**, not the adapter.
 
-## Allowed imports (enforced by `boundary-direction-check`)
+## Allowed imports
 
-| This package | May import |
-|---|---|
-| `@repo/<name>` | `@repo/core` (logger, env, errors, Result/Option/pipe). Nothing else `@repo/*`. |
-
-If you find yourself needing to import another `@repo/*`, you are blurring layers. Two valid fixes:
-- Move the shared concept into `@repo/core`
-- Reshape the boundary so the consumer composes the two packages explicitly
+Follow `void-dependency-direction`: the package manifest declares dependencies;
+the project's architecture decides whether they belong. This service convention
+prefers domain-owned ports and app composition. It does not claim the shared hook
+forbids every dependency except `@repo/core`.
 
 ## `package.json` template
 

package/core-assets/packs/pack-server/skills/void-webhook-handler-pattern/.source

@@ -1,7 +1,9 @@
 Sources for `void-webhook-handler-pattern` skill (see `docs/plans/skill-audits/void-webhook-handler-pattern.md` for the full audit):
 
-- No external source audited — native distillation of canonical per-source webhook patterns.
-- Per-source patterns referenced (not vendored): Stripe, Resend, GitHub signature/idempotency/retry semantics.
+- Official provider contracts checked for the 2026-10-30 coherence correction:
+- Stripe: https://docs.stripe.com/webhooks#preventing-replay-attacks
+- GitHub: https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries
+- Provider code is not vendored; verifier and durable store remain consumer-owned.
 - Doctrine referenced: `void-async-safety` (stack-agnostic retry/idempotency/dead-letter).
 
 Strategy: distill. Per-source handler patterns distilled into the 5 non-negotiable layers; no upstream skill was copied.

package/core-assets/packs/pack-server/skills/void-webhook-handler-pattern/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: void-webhook-handler-pattern
-description: Build a webhook handler with signature verification, idempotency, and dead-letter routing. Per-source patterns (Stripe, Resend, GitHub). Self-contained — no harness wrappers required.
+description: Build a webhook handler with signature verification, idempotency, and dead-letter routing. Per-source patterns (Stripe, Resend, GitHub). Uses the shared async-safety contract.
 ---
 
 # webhook-handler-pattern
@@ -15,91 +15,22 @@ apps/<app>/src/app/api/webhooks/<source>/route.ts
 
 One folder per source. Path stable (external systems POST to a fixed URL — never rename without coordinating).
 
-## The 5 non-negotiable layers
+## Handler contract
 
-```
-1. Signature verification  — verify the event came from the source
-2. Idempotency             — same event delivered twice = one effect
-3. Zod validation          — parsed shape matches what handler expects
-4. Service call            — the business work (in apps/<app>/src/services/)
-5. Acknowledgment          — return 2xx on success; specific codes on failure
-```
+Compose `void-async-safety` for the canonical executable `withWebhookSafety` example
+and its `IdempotencyStore` contract. Keep signature/freshness verification in the provider
+SDK adapter, validate its decoded data at that boundary, and map the typed outcome to HTTP.
+Do not copy a second verify/claim/handle/mark implementation into this skill.
 
-Skipping ANY of these is a Sev-2 waiting. The pattern below shows the 5 layers explicit — no wrapper assumed.
-
-## Canonical handler (explicit, self-contained)
-
-```ts
-// apps/web/src/app/api/webhooks/stripe/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import Stripe from 'stripe';
-import { z } from 'zod';
-import { db } from '@/adapters/db';
-import { env, logger } from '@repo/core';
-import * as Sentry from '@sentry/nextjs';
-import { handleStripeEvent } from '@/services/billing/stripe';
-
-const stripe = new Stripe(env.STRIPE_SECRET_KEY);
-
-// 3. Zod schema for the parsed Stripe event (defense in depth — Stripe's
-//    own parser is trusted, but we re-shape to our service contract).
-const EventSchema = z.object({
-  id: z.string(),
-  type: z.string(),
-  data: z.object({ object: z.unknown() }),
-  livemode: z.boolean(),
-});
-
-export async function POST(req: NextRequest) {
-  const sig = req.headers.get('stripe-signature');
-  const body = await req.text();
-  const idempotencyKey = `stripe:${req.headers.get('stripe-signature')?.slice(0, 16) ?? ''}`;
-
-  let stripeEvent: Stripe.Event;
-  try {
-    // 1. Signature verification (Stripe-specific)
-    if (!sig) {
-      return NextResponse.json({ error: 'missing signature' }, { status: 401 });
-    }
-    stripeEvent = stripe.webhooks.constructEvent(body, sig, env.STRIPE_WEBHOOK_SECRET);
-  } catch (err) {
-    logger.warn({ event: 'webhook.signature_invalid', source: 'stripe' });
-    return NextResponse.json({ error: 'invalid signature' }, { status: 401 });
-  }
-
-  // 2. Idempotency — Stripe's event.id is globally unique
-  const inboxKey = `stripe:${stripeEvent.id}`;
-  const inserted = await db
-    .insert(webhookInbox)
-    .values({ key: inboxKey, source: 'stripe', eventType: stripeEvent.type, payload: stripeEvent })
-    .onConflictDoNothing()
-    .returning();
-
-  if (inserted.length === 0) {
-    // Already seen — return 2xx to stop Stripe retrying
-    logger.info({ event: 'webhook.duplicate', source: 'stripe', eventId: stripeEvent.id });
-    return NextResponse.json({ ok: true, duplicate: true });
-  }
-
-  // 3. Re-validate with our schema
-  const event = EventSchema.parse(stripeEvent);
-
-  // 4. Service call — pure dispatch
-  logger.info({ event: 'webhook.received', source: 'stripe', type: event.type, eventId: event.id });
-  try {
-    await handleStripeEvent(event);
-    await db.update(webhookInbox).set({ committedAt: new Date() }).where(eq(webhookInbox.key, inboxKey));
-    // 5. Ack
-    return NextResponse.json({ ok: true });
-  } catch (err) {
-    Sentry.captureException(err, { tags: { webhook: 'stripe', eventType: event.type } });
-    // Retryable: return 5xx so Stripe retries with backoff
-    return NextResponse.json({ ok: false }, { status: 500 });
-  }
-}
-```
+The handler's business effects and deduplication must share a transaction/outbox or use
+the same stable idempotency key. A received or pending inbox row is **not** proof of a
+completed event. Failed processing and failed completion persistence remain non-success
+and retryable; only completed events may be acknowledged as duplicates. An in-flight
+concurrent delivery must not report that unfinished processing as success.
 
-The 5 layers are explicit. No wrapper is required. If your project ships its own `withWebhookSafety` helper that bundles these 5, that's a convenience — but the pattern is the substance, and it's the same.
+A project may provide its own wrapper with this contract. The optional Next.js pack
+exports the tested implementation; it does not supply the project's verifier or durable
+store. No universal event-age limit is invented by the wrapper.
 
 ## Per-source notes
 
@@ -114,13 +45,13 @@ The 5 layers are explicit. No wrapper is required. If your project ships its own
 
 - Signature: `svix-id`, `svix-timestamp`, `svix-signature` headers → `new Webhook(secret).verify(body, headers)` from `svix` package
 - Idempotency: `svix-id` header
-- Retry: Svix retries automatically; you only see the first failure if your endpoint returns 5xx
+- Retry: use the provider's current retry schedule and delivery diagnostics; do not infer completion from receipt.
 
 ### GitHub
 
 - Signature: `x-hub-signature-256` header (HMAC SHA-256 of the body with your secret)
 - Idempotency: `x-github-delivery` header (UUID)
-- Retry: GitHub does NOT auto-retry. If you return 5xx, the event is lost. Make sure dead-letter is robust.
+- Retry: GitHub does not automatically redeliver failed deliveries; arrange manual or automated redelivery from its delivery records. A failure response is not durable acceptance.
 
 ### Custom (internal services calling each other)
 
@@ -128,64 +59,33 @@ The 5 layers are explicit. No wrapper is required. If your project ships its own
 - Idempotency: caller-generated UUID v7 in `x-idempotency-key`
 - Retry: caller's responsibility; receiver acknowledges with 2xx + the key it already saw
 
-## Inbox table
+## Durable inbox
 
-The idempotency check needs persistent storage:
-
-```sql
-CREATE TABLE webhook_inbox (
-  key text PRIMARY KEY,                         -- e.g., "stripe:evt_xxx"
-  source text NOT NULL,
-  event_type text NOT NULL,
-  received_at timestamptz NOT NULL DEFAULT now(),
-  committed_at timestamptz,
-  payload jsonb NOT NULL
-);
-CREATE INDEX idx_webhook_inbox_received ON webhook_inbox (received_at);
-```
-
-Migration follows the safe-migration pattern (see `void-drizzle-migration-safe` skill).
+Use the application's existing durable store following `void-async-safety`. Its state
+must distinguish pending claims from completed events and release/expire failed claims
+for retry. A unique key alone cannot express completion. Apply schema changes through
+`void-drizzle-migration-safe`; this skill supplies no independently evolving SQL schema.
 
 ## Dead-letter routing
 
-When the handler decides the error is permanent (validation failure, downstream API said 4xx):
-
-```ts
-catch (err) {
-  if (isPermanentFailure(err)) {
-    await db.insert(webhookDeadLetter).values({
-      key: inboxKey,
-      source: 'stripe',
-      error: err.message,
-      payload: event,
-      receivedAt: new Date(),
-    });
-    return NextResponse.json({ ok: false, retry: false }, { status: 400 });
-    // 4xx tells Stripe "permanent — stop retrying"
-  }
-  throw err;   // retryable — let the 5xx propagate
-}
-```
-
-Dead letter = a queue/table the team reviews. UI: `Settings → Webhook DLQ`. Never silently drop.
-
-## Error response codes
+A permanent failure may be recorded in a durable dead-letter destination for an operator
+before applying the provider's acknowledgment policy. Never interpret an HTTP status as
+a universal instruction to stop delivery: Stripe retries non-2xx responses, including 4xx;
+GitHub does not automatically redeliver failures. Keep provider-specific retries explicit.
+Never acknowledge a malformed event as successfully processed or silently drop a failure.
 
-| Code | Means | Sender behavior |
-|---|---|---|
-| 200/202 | Accepted | Stops retrying |
-| 401 | Invalid signature | Stops retrying (Stripe, GitHub will flag the endpoint) |
-| 4xx (other) | Permanent failure (bad event shape) | Stops retrying — log this for investigation |
-| 5xx | Transient failure | Retries with backoff (Stripe/Svix); GitHub doesn't retry |
+## Error responses
 
-NEVER return 200 to a malformed event (you'd accept invalid data). 4xx with a logged DLQ entry is the right pattern.
+The canonical wrapper rejects verifier failures with 400 and returns 500 for handler or
+store failures. The HTTP adapter preserves those outcomes. A 200 means completed work or
+a previously completed duplicate, never an in-progress claim. If a queue/outbox is used,
+its separate acceptance contract must mean durable responsibility for eventual processing.
 
 ## Anti-patterns
 
 - ✗ **No signature verification** — anyone with the URL can forge events
 - ✗ **Idempotency key = `Date.now()`** — re-delivery NOT detected; double-charges
-- ✗ **Calling services synchronously for slow work** — if the handler takes > 10s, the sender retries. Enqueue background jobs for slow work (see `void-background-job-pattern`).
-- ✗ **Returning 5xx to "make sender retry" without enqueueing** — sender's backoff is unpredictable; use your own queue
+- ✗ **Calling services synchronously for slow work** — work exceeding the provider's response deadline is a failed delivery; retry policy varies by provider. Enqueue background jobs for slow work (see `void-background-job-pattern`).
 - ✗ **One handler for all sources** (`/api/webhooks/route.ts` switching on `source`) — different signatures, different idempotency keys, different retry semantics. One folder per source.
 - ✗ **`==` for HMAC comparison** — use `crypto.timingSafeEqual`. Constant-time compare prevents timing attacks.
 

package/core-assets/skills/void-accessibility/SKILL.md

@@ -198,7 +198,7 @@ Every UI is designed mobile-first AND must reach first-class quality on both vie
 - No mobile-only nor desktop-only features without an explicit decision recorded through the `void-decide` skill.
 - Both viewports screenshot-reviewed before merge.
 
-The companion `viewport-screenshot-gate` hook (shared with `void-frontend-design`) fails PRs lacking both screenshots.
+The companion `viewport-screenshot-gate` hook (shared with `void-frontend-design`) is an optional PR-text heuristic; it does not validate images or enforce a native/CI gate. Review the actual mobile and desktop captures before merge.
 
 ---
 
@@ -229,7 +229,7 @@ The design system handles this by default in `pack-nextjs`. Specific animations
 ## Companion hooks
 
 - `axe-precommit` (pre-commit on UI changes) — axe-core static analysis, blocks on AA violations. ≤ 80 LOC.
-- `viewport-screenshot-gate` (pre-PR on UI changes, shared with `void-frontend-design`) — fails PRs lacking both mobile and desktop screenshots. ≤ 60 LOC.
+- `viewport-screenshot-gate` (pre-PR on UI changes, shared with `void-frontend-design`) — optional PR-text heuristic, not a wired native/CI gate or image validation. Review actual captures.
 
 ---