@skill-graph/cli 0.5.6

package/examples/projects/saas-stripe-postgres/db/schema.sql

@@ -0,0 +1,112 @@
+-- Canonical schema for saas-stripe-postgres example project
+-- Demonstrates: multi-tenant tables, RLS policies, provider-agnostic payment columns
+
+-- ─────────────────────────────────────────────────
+-- Organizations (tenant root table)
+-- ─────────────────────────────────────────────────
+CREATE TABLE organizations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  slug TEXT NOT NULL UNIQUE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ─────────────────────────────────────────────────
+-- Users
+-- ─────────────────────────────────────────────────
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  email TEXT NOT NULL,
+  role TEXT NOT NULL DEFAULT 'member' CHECK (role IN ('owner', 'admin', 'member')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (org_id, email)
+);
+
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE users FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY users_org_select ON users
+  FOR SELECT
+  USING (org_id = current_setting('app.current_org_id', true)::uuid);
+
+CREATE POLICY users_org_insert ON users
+  FOR INSERT
+  WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+
+CREATE POLICY users_org_update ON users
+  FOR UPDATE
+  USING (org_id = current_setting('app.current_org_id', true)::uuid)
+  WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+
+CREATE POLICY users_org_delete ON users
+  FOR DELETE
+  USING (org_id = current_setting('app.current_org_id', true)::uuid);
+
+-- ─────────────────────────────────────────────────
+-- Subscriptions
+-- ─────────────────────────────────────────────────
+CREATE TABLE subscriptions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  plan TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'past_due', 'canceled', 'trialing')),
+  current_period_end TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE subscriptions FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY subscriptions_org_select ON subscriptions
+  FOR SELECT USING (org_id = current_setting('app.current_org_id', true)::uuid);
+CREATE POLICY subscriptions_org_insert ON subscriptions
+  FOR INSERT WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+CREATE POLICY subscriptions_org_update ON subscriptions
+  FOR UPDATE
+  USING (org_id = current_setting('app.current_org_id', true)::uuid)
+  WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+CREATE POLICY subscriptions_org_delete ON subscriptions
+  FOR DELETE USING (org_id = current_setting('app.current_org_id', true)::uuid);
+
+-- ─────────────────────────────────────────────────
+-- Orders (canonical provider-agnostic schema)
+-- Post-migration 0004: uses provider/provider_order_id columns,
+-- not the Stripe-specific stripe_session_id/stripe_customer_id.
+-- ─────────────────────────────────────────────────
+CREATE TABLE orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  provider TEXT NOT NULL DEFAULT 'stripe',      -- 'stripe', 'paddle', etc.
+  provider_order_id TEXT NOT NULL,              -- was: stripe_session_id
+  provider_customer_id TEXT,                    -- was: stripe_customer_id
+  amount_cents INTEGER NOT NULL,
+  currency TEXT NOT NULL DEFAULT 'usd',
+  status TEXT NOT NULL DEFAULT 'pending',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (provider, provider_order_id)
+);
+
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY orders_org_select ON orders
+  FOR SELECT USING (org_id = current_setting('app.current_org_id', true)::uuid);
+CREATE POLICY orders_org_insert ON orders
+  FOR INSERT WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+CREATE POLICY orders_org_update ON orders
+  FOR UPDATE
+  USING (org_id = current_setting('app.current_org_id', true)::uuid)
+  WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+CREATE POLICY orders_org_delete ON orders
+  FOR DELETE USING (org_id = current_setting('app.current_org_id', true)::uuid);
+
+-- ─────────────────────────────────────────────────
+-- Webhook events (idempotency log)
+-- Not tenant-bound — events arrive before org context is known.
+-- ─────────────────────────────────────────────────
+CREATE TABLE webhook_events (
+  event_id TEXT PRIMARY KEY,   -- Stripe event.id or provider equivalent
+  provider TEXT NOT NULL DEFAULT 'stripe',
+  processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/examples/projects/saas-stripe-postgres/skills/migrate-orders-to-canonical-schema/SKILL.md

@@ -0,0 +1,149 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v6.schema.json
+schema_version: 6
+name: migrate-orders-to-canonical-schema
+description: "Use when running migration 0004 that normalizes the orders table from a Stripe-specific shape (stripe_session_id, stripe_customer_id as top-level columns) to a canonical provider-agnostic shape (provider, provider_order_id, provider_customer_id). Covers the four-phase safe migration procedure — add nullable columns, backfill from existing data, validate, drop legacy columns — and the RLS policy update that must accompany the column rename. Do NOT use for unrelated schema migrations (write a fresh skill anchored to that migration's number), for designing a new canonical schema from scratch, or for the ongoing orgQuery access pattern (use postgres-rls-pattern)."
+version: 0.1.0
+type: workflow
+category: engineering
+domain: engineering/database
+scope: codebase
+owner: saas-stripe-postgres-example
+freshness: "2026-05-18"
+drift_check:
+  last_verified: "2026-05-18"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Postgres >=14; assumes psql or pg driver. Dry-run mode requires a non-production database."
+allowed-tools: Read Grep Bash
+keywords:
+  - orders table migration
+  - canonical schema migration
+  - stripe to provider-agnostic
+  - column rename migration
+  - four-phase migration
+  - add nullable backfill validate drop
+  - provider_order_id migration
+  - rls policy update on migration
+  - 0004 orders migration
+  - safe column removal
+triggers:
+  - migrate-orders-to-canonical-schema
+paths:
+  - "db/migrations/0004_canonicalize_orders.sql"
+  - "db/schema.sql"
+  - "scripts/migrate-orders.ts"
+examples:
+  - "run the 0004 orders migration that renames stripe_session_id to provider_order_id"
+  - "safely remove the stripe_customer_id column after backfilling provider_customer_id"
+  - "update the RLS policy on orders after the column rename"
+  - "verify that every order row has a non-null provider_order_id before dropping the old column"
+anti_examples:
+  - "design a different migration for the invoices table"
+  - "add row level security to a new table"
+  - "query the orders table in an application route"
+relations:
+  boundary:
+    - skill: postgres-rls-pattern
+      reason: "postgres-rls-pattern defines the ongoing RLS access pattern; this skill owns the one-time migration that changes the table structure those policies reference"
+    - skill: payment-provider-router
+      reason: "payment-provider-router reads orders to check idempotency; this migration changes the column the idempotency check uses — coordinate migration timing with router deployment"
+  depends_on:
+    - skill: postgres-rls-pattern
+      reason: "the canonical schema migration must update RLS policies — postgres-rls-pattern defines the policy triple to follow"
+  verify_with:
+    - postgres-rls-pattern
+grounding:
+  domain_object: "Migration 0004 — the four-phase procedure that canonicalizes the orders table from Stripe-specific column names to provider-agnostic column names, with an RLS policy update in the same migration"
+  grounding_mode: repo_specific
+  truth_sources:
+    - path: examples/projects/saas-stripe-postgres/db/migrations/0004_canonicalize_orders.sql
+      note: "The migration file — source of truth for column renames and RLS policy updates"
+    - path: examples/projects/saas-stripe-postgres/db/schema.sql
+      note: "The target canonical schema the migration produces"
+  failure_modes:
+    - dropping_column_before_backfill_verified
+    - rls_policy_not_updated_to_reference_new_column_name
+    - application_code_still_references_old_column_after_drop
+    - migration_run_without_dry_run_gate_first
+    - rollback_path_not_documented_before_irreversible_step
+  evidence_priority: repo_code_first
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+lifecycle:
+  stale_after_days: 30
+  review_cadence: quarterly
+---
+
+# Migrate Orders to Canonical Schema
+
+## Coverage
+
+- The four-phase safe migration procedure applied to the orders table: *add nullable columns → backfill from existing → validate → drop legacy columns*; why collapsing any two phases is unsafe under live traffic
+- The canonical column mapping: `stripe_session_id` → `provider_order_id`, `stripe_customer_id` → `provider_customer_id`, with a new `provider` column set to `'stripe'` for existing rows
+- The RLS policy update — the existing `orders_org_select` policy must be updated in the same migration that renames the columns if the policy references them (it does not in this case, but the checklist step prevents future drift)
+- Application code audit — grepping for `stripe_session_id` and `stripe_customer_id` in the codebase to find every reference that must be updated before the old columns are dropped
+- The dry-run gate — `scripts/migrate-orders.ts` runs in `--dry-run` by default, printing the diff without committing; `--apply` is the explicit opt-in
+
+## Philosophy
+
+A column rename under live traffic is a non-trivial operation even on a small table. The temptation to write one migration that renames columns atomically and ships them fails because application code reads the old column names until the new application version deploys, and the deployment window is not instant. The four-phase procedure exists because the new column can be null during the window, the application can write both, and the old column can be dropped only after the new application version has been running for a full observation period with zero reads of the old column name in logs.
+
+## Workflow
+
+| Phase | Precondition | Action | Success criterion |
+|---|---|---|---|
+| 1. Add nullable columns | Production schema has no `provider` or `provider_order_id` | Add `provider TEXT`, `provider_order_id TEXT`, `provider_customer_id TEXT` as nullable | Build passes; existing rows unaffected |
+| 2. Backfill | Phase 1 deployed | `UPDATE orders SET provider = 'stripe', provider_order_id = stripe_session_id, provider_customer_id = stripe_customer_id WHERE provider IS NULL` | `SELECT COUNT(*) FROM orders WHERE provider IS NULL` returns 0 |
+| 3. Validate and update application | Phase 2 complete | Search codebase for `stripe_session_id` and `stripe_customer_id` references; update to `provider_order_id` / `provider_customer_id`; deploy the updated application | Zero reads of old column names in production logs for 24 hours |
+| 4. Drop legacy columns | Phase 3 observation period complete | `ALTER TABLE orders DROP COLUMN stripe_session_id, DROP COLUMN stripe_customer_id` | Schema matches `db/schema.sql`; `npm run verify` passes |
+
+## Migration SQL
+
+```sql
+-- Phase 1: Add nullable canonical columns
+ALTER TABLE orders
+  ADD COLUMN IF NOT EXISTS provider TEXT,
+  ADD COLUMN IF NOT EXISTS provider_order_id TEXT,
+  ADD COLUMN IF NOT EXISTS provider_customer_id TEXT;
+
+-- Phase 2: Backfill from Stripe-specific columns
+UPDATE orders
+SET
+  provider = 'stripe',
+  provider_order_id = stripe_session_id,
+  provider_customer_id = stripe_customer_id
+WHERE provider IS NULL;
+
+-- Phase 4 (only after Phase 3 observation period):
+-- ALTER TABLE orders
+--   DROP COLUMN stripe_session_id,
+--   DROP COLUMN stripe_customer_id;
+```
+
+## Verification
+
+- [ ] Phase 1 was deployed to production and verified (build passed, existing rows intact) before Phase 2 ran
+- [ ] Phase 2 backfill was run with `--dry-run` first; the dry-run output is committed under `db/migrations/0004-dry-run.log`
+- [ ] `SELECT COUNT(*) FROM orders WHERE provider IS NULL` returns 0 before Phase 3 begins
+- [ ] Phase 3 application code audit found and updated every reference to `stripe_session_id` and `stripe_customer_id`
+- [ ] The observation window (minimum 24 hours) elapsed with zero old-column reads in production logs before Phase 4 was run
+- [ ] Phase 4 (DROP COLUMN) is in a separate migration file from Phases 1-2, deployed only after Phase 3 sign-off
+- [ ] RLS policies were reviewed after the column rename (even if not updated — the review is recorded in the migration PR)
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `postgres-rls-pattern` | The task is the ongoing RLS access pattern, not the one-time migration |
+| (a fresh migration skill) | The task is a different migration with no relation to the 0004 orders canonicalization |
+| `payment-provider-router` | The task is updating the router to use `provider_order_id` after the migration |

package/examples/projects/saas-stripe-postgres/skills/nextjs-server-action-validation/SKILL.md

@@ -0,0 +1,154 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v6.schema.json
+schema_version: 6
+name: nextjs-server-action-validation
+description: "Use when writing a Next.js Server Action that accepts user-submitted form data, mutation parameters, or any client-originated input. Every Server Action is a public HTTP endpoint regardless of how it is called — validate with Zod and check authentication as the first two operations before touching the database. Do NOT use for GET route handlers or Server Components that fetch data (those have no user-supplied input); do NOT use for Stripe webhook handlers (use stripe-webhook-signature-verification instead)."
+version: 0.1.0
+type: capability
+category: engineering
+domain: engineering/web
+scope: portable
+owner: saas-stripe-postgres-example
+freshness: "2026-05-18"
+drift_check:
+  last_verified: "2026-05-18"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Next.js App Router >=14 with server actions enabled; Zod >=3."
+allowed-tools: Read Grep
+keywords:
+  - next.js server action validation
+  - zod input validation
+  - server action security
+  - server action auth check
+  - server action public endpoint
+  - use server directive
+  - form action security
+  - server action pattern
+  - mutation validation
+  - next.js app router actions
+triggers:
+  - nextjs-server-action-validation
+paths:
+  - "app/actions/*.ts"
+  - "lib/actions/*.ts"
+examples:
+  - "write a Server Action for the checkout form that validates the selected plan before creating a Stripe session"
+  - "secure a Server Action so it rejects unauthenticated requests"
+  - "validate user input with Zod in a Server Action before writing to Postgres"
+  - "my Server Action is being called directly via fetch — is that safe?"
+anti_examples:
+  - "validate the stripe-signature header in a webhook route handler"
+  - "fetch data in a Server Component to display on a page"
+  - "write a GET route handler that returns public product data"
+relations:
+  boundary:
+    - skill: stripe-webhook-signature-verification
+      reason: "stripe-webhook-signature-verification validates Stripe's HMAC signature on webhook route handlers; this skill validates user-submitted input on Server Actions — different trust model, different entry point"
+    - skill: postgres-rls-pattern
+      reason: "postgres-rls-pattern governs the database layer; this skill governs the action layer — both are required in a secure Server Action, but at separate tiers"
+  depends_on:
+    - skill: postgres-rls-pattern
+      reason: "Server Actions that write to Postgres must call orgQuery to enforce tenant isolation after input is validated"
+  verify_with:
+    - stripe-webhook-signature-verification
+portability:
+  readiness: portable
+  targets:
+    - skill-md
+lifecycle:
+  stale_after_days: 90
+  review_cadence: quarterly
+---
+
+# Next.js Server Action Validation
+
+## Coverage
+
+- The public endpoint reality — `'use server'` functions are exposed as POST endpoints that any HTTP client can call directly; the Next.js call graph is not a security boundary
+- Validation order — auth check BEFORE Zod parse, Zod parse BEFORE database access; any other order produces an exploitable window
+- Zod schema design for actions — using `.safeParse()` over `.parse()` to return structured errors rather than throwing; returning `{ error: ... }` shapes that the calling Client Component can render
+- Org-scoping after authentication — verifying that `input.orgId` matches the session's org, not just that the user is logged in
+- Error surface control — how `try/catch` around database calls prevents internal errors from propagating to the client response
+
+## Philosophy
+
+Server Actions are a convenience feature that makes form submission feel like a function call. That convenience obscures a critical fact: the action is a public HTTP POST endpoint. A developer who writes `const { data } = await myAction(formData)` in a Client Component is writing what looks like a local function call, but the runtime sends an HTTP request that any script can replicate. Skipping auth or validation because "it's called from our own UI" is the same reasoning that made `getServerSideProps` data-fetching functions leaky in the Pages Router — the server boundary does not restrict callers.
+
+## Standard Action Pattern
+
+```typescript
+"use server";
+import { z } from "zod";
+import { getServerSession } from "@/lib/auth";
+import { orgQuery } from "@/lib/db";
+
+const CreateOrderSchema = z.object({
+  orgId: z.string().uuid(),
+  planId: z.string().min(1),
+  quantity: z.number().int().positive(),
+});
+
+export async function createOrder(input: unknown) {
+  // 1. Auth check — before anything else
+  const session = await getServerSession();
+  if (!session?.user) {
+    return { error: "Unauthorized" };
+  }
+
+  // 2. Zod parse — structured errors, not thrown exceptions
+  const parsed = CreateOrderSchema.safeParse(input);
+  if (!parsed.success) {
+    return { error: parsed.error.flatten() };
+  }
+
+  // 3. Org-scope check — user must belong to the org they are acting on
+  if (session.user.orgId !== parsed.data.orgId) {
+    return { error: "Forbidden" };
+  }
+
+  // 4. Database write — inside orgQuery for RLS enforcement
+  try {
+    const [order] = await orgQuery(parsed.data.orgId, (tx) =>
+      tx`INSERT INTO orders (org_id, plan_id, quantity) VALUES (
+          ${parsed.data.orgId}, ${parsed.data.planId}, ${parsed.data.quantity}
+        ) RETURNING *`
+    );
+    return { data: order };
+  } catch {
+    return { error: "Failed to create order" };
+  }
+}
+```
+
+## Validation Order Rationale
+
+| Order | Risk |
+|---|---|
+| Auth → Zod → orgScope → DB | Correct — each gate eliminates the next attack surface |
+| Zod → Auth → DB | Attacker can probe the schema structure without authenticating |
+| Auth → DB (no Zod) | Malformed input reaches the query layer; injection risk |
+| DB → Auth (anywhere) | Unauthenticated database reads before rejection |
+
+## Verification
+
+- [ ] Every `'use server'` function calls `getServerSession()` as its first statement
+- [ ] Every `'use server'` function runs `Schema.safeParse()` before any database call
+- [ ] The session org ID is compared to the input org ID before the database call
+- [ ] Database calls are wrapped in `orgQuery`, not bare SQL
+- [ ] Errors returned to the client do not include stack traces or query text
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `stripe-webhook-signature-verification` | The entry point is a webhook route handler, not a Server Action |
+| (a data-fetching skill) | The function is a Server Component that fetches data, with no user-submitted input |
+| `postgres-rls-pattern` | The task is defining the database-layer policy, not the action-layer validation |

package/examples/projects/saas-stripe-postgres/skills/payment-provider-router/SKILL.md

@@ -0,0 +1,153 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v6.schema.json
+schema_version: 6
+name: payment-provider-router
+description: "Use when dispatching a verified payment event (Stripe webhook or future provider) to the correct downstream handler based on event type. Routes `checkout.session.completed` to subscription provisioning, `invoice.payment_failed` to dunning logic, and `customer.subscription.deleted` to cancellation. Do NOT use for signature verification of the incoming event (use stripe-webhook-signature-verification first) or for the actual subscription database writes (use the per-handler skill or postgres-rls-pattern)."
+version: 0.1.0
+type: router
+category: engineering
+domain: engineering/payments
+scope: portable
+owner: saas-stripe-postgres-example
+freshness: "2026-05-18"
+drift_check:
+  last_verified: "2026-05-18"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Stripe SDK >=14; event types sourced from Stripe's published event catalog."
+allowed-tools: Read Grep
+keywords:
+  - payment event routing
+  - stripe event type dispatch
+  - webhook event router
+  - checkout.session.completed
+  - invoice.payment_failed
+  - customer.subscription.deleted
+  - payment provider dispatch
+  - event type switch
+  - payment event handler
+  - multi-provider payment routing
+triggers:
+  - payment-provider-router
+paths:
+  - "lib/payments/router.ts"
+  - "app/api/webhooks/stripe/route.ts"
+examples:
+  - "route checkout.session.completed to subscription provisioning"
+  - "which handler should process invoice.payment_failed for dunning?"
+  - "add a new event type handler for customer.subscription.updated"
+  - "design the event router so it is extensible to a second payment provider"
+anti_examples:
+  - "verify that the webhook request is genuinely from Stripe"
+  - "write the database insert that creates the subscription record"
+  - "handle a failed Stripe API call when creating a payment intent"
+relations:
+  boundary:
+    - skill: stripe-webhook-signature-verification
+      reason: "stripe-webhook-signature-verification verifies the event is authentic before it reaches this router; routing an unverified event is a security failure"
+    - skill: postgres-rls-pattern
+      reason: "postgres-rls-pattern governs the database writes that each handler performs; this router decides which handler runs, not how it writes"
+  depends_on:
+    - skill: stripe-webhook-signature-verification
+      reason: "this router must only receive events that have already passed signature verification — call stripe-webhook-signature-verification first"
+  verify_with:
+    - stripe-webhook-signature-verification
+portability:
+  readiness: portable
+  targets:
+    - skill-md
+lifecycle:
+  stale_after_days: 90
+  review_cadence: quarterly
+---
+
+# Payment Provider Router
+
+## Coverage
+
+- The routing table — a typed dispatch map from `Stripe.Event["type"]` to handler functions, with a structured "unknown event" fallback that returns 200 (to prevent Stripe retry storms) and logs the unhandled type
+- Handler isolation — each handler receives only the specific event subtype it needs (e.g. `Stripe.CheckoutSessionCompletedEvent`), not the generic `Stripe.Event`, to avoid casts inside handlers
+- Provider abstraction — how to wrap the Stripe-specific router behind a `PaymentEvent` canonical type so a future provider can be added without changing handler code
+- Error surface — handlers must catch their own errors and return a structured result; an uncaught exception must not produce a 500 that triggers Stripe's retry mechanism with an exponential backoff cascade
+- Event type coverage audit — which event types are handled, which are known-ignored (acknowledged with a comment), and which are genuinely unknown
+
+## Philosophy
+
+A payment event router has the same discipline requirement as a content source router: prefer an explicit handler over an implicit fallback, surface unhandled events loudly (in logs, not in HTTP status codes — a 400 triggers a retry, a 200 with a log entry does not), and never let one handler own two semantically distinct events. The event type is the authoritative signal for which business operation to perform; ambiguity at this layer produces double-charges, missed provisioning, and unfired dunning emails.
+
+## Routing Rules
+
+```typescript
+// lib/payments/router.ts
+import Stripe from "stripe";
+import { handleCheckoutComplete } from "./handlers/checkout-complete";
+import { handlePaymentFailed } from "./handlers/payment-failed";
+import { handleSubscriptionDeleted } from "./handlers/subscription-deleted";
+
+type HandlerResult = { ok: boolean; message?: string };
+
+const EVENT_HANDLERS: Partial<
+  Record<Stripe.Event["type"], (event: Stripe.Event) => Promise<HandlerResult>>
+> = {
+  "checkout.session.completed": (e) =>
+    handleCheckoutComplete(e as Stripe.CheckoutSessionCompletedEvent),
+  "invoice.payment_failed": (e) =>
+    handlePaymentFailed(e as Stripe.InvoicePaymentFailedEvent),
+  "customer.subscription.deleted": (e) =>
+    handleSubscriptionDeleted(e as Stripe.CustomerSubscriptionDeletedEvent),
+  // Acknowledged non-actionable events — log and return OK
+  "invoice.paid": async () => ({ ok: true, message: "acknowledged" }),
+};
+
+export async function routePaymentEvent(event: Stripe.Event): Promise<HandlerResult> {
+  const handler = EVENT_HANDLERS[event.type];
+
+  if (!handler) {
+    console.warn("[payment-router] unhandled event type", { type: event.type, id: event.id });
+    // Return 200 — a 4xx or 5xx would trigger Stripe retry with backoff
+    return { ok: true, message: "unhandled_event_type" };
+  }
+
+  return handler(event);
+}
+```
+
+## Routing Decision Rules
+
+| Event type | Handler | Rationale |
+|---|---|---|
+| `checkout.session.completed` | `handleCheckoutComplete` | Provision subscription, create org record |
+| `invoice.payment_failed` | `handlePaymentFailed` | Trigger dunning, update subscription status |
+| `customer.subscription.deleted` | `handleSubscriptionDeleted` | Revoke access, archive subscription |
+| `invoice.paid` | acknowledged | No action — success is implicit from `checkout.session.completed` |
+| anything else | log + 200 | Unknown event — log for triage, do not retry |
+
+## Adding a New Event Type
+
+1. Add the Stripe event type string to `EVENT_HANDLERS` with a typed cast.
+2. Write the handler in `lib/payments/handlers/<name>.ts` — it receives the specific subtype.
+3. Add a row to the routing table above documenting what the handler does.
+4. If the event should be intentionally ignored, add it to the "acknowledged" row rather than leaving it in the unknown bucket.
+
+## Verification
+
+- [ ] Every routable event type is in `EVENT_HANDLERS` with an explicit handler or acknowledgement
+- [ ] Unknown events return 200 (not 400 or 500) to prevent Stripe retry cascades
+- [ ] Each handler receives a typed subtype, not the generic `Stripe.Event`
+- [ ] Handler errors are caught inside the handler and returned as `{ ok: false }` — they do not propagate to the router
+- [ ] `routePaymentEvent` is only called after signature verification (grep for `routePaymentEvent` — every call site should be downstream of `constructEvent`)
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `stripe-webhook-signature-verification` | The task is verifying the event's authenticity before routing |
+| `postgres-rls-pattern` | The task is writing the database statements inside a specific handler |
+| (a generic event bus skill) | The application uses an event bus that is not payment-provider-specific |