@tenkara/afm-linux-arm64 0.0.0-stage → 4.0.0-alpha.10

package/content/modules/nextjs-app-router/rules.patch.md

@@ -0,0 +1,35 @@
+---
+type: module
+description: 'Hard rules for App Router projects — Server Component by default, every "use client" carries a stated reason, and <html lang> renders in the localized segment. The route-handler-thinness rule this module used to state as a fixed 80-line trigger is an opt-in seed now.'
+load: cold
+stack: nextjs-app-router
+patches: 'docs/rules/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("next")' package.json >/dev/null 2>&1; else grep -q '"next"' package.json 2>/dev/null; fi
+---
+
+# Patch — Hard rules for Next.js App Router projects
+
+> Insert after the last existing hard rule in `/docs/afm.md` §3.
+
+- **Server Component is the default.** Use `"use client"` only where the code needs real interactivity (state, DOM events, browser hooks). Each `"use client"` needs a clear reason.
+  *Verification:* `grep -rn '"use client"' src/app app 2>/dev/null` — each match has a clear reason in the diff.
+
+> This module used to add a hard rule here that route handlers stay thin, verified by a fixed
+> "all files under 80 lines" check — an arbitrary constant with no measurement behind it and no
+> placeholder. The qualitative convention ("a route handler delegates to `server/`, it does not
+> embed business logic") is not a Next.js fact either; it now lives as an opt-in seed at
+> `code-style/nextjs-app-router/imports.md` (concern: imports). A project that wants a numeric
+> line-count backstop should adopt `code-style/_any/file-size.md` instead, with a threshold it
+> measured against its own files — not this module's unmeasured 80.
+
+- **A page Server Component does not call raw `fetch()` when a typed client exists.** Use the stack's server-side client instead. For example, use a tRPC server caller to keep the types.
+  *Verification:* `grep -rn "fetch(" --include='page.tsx' src/app app 2>/dev/null`.
+- **The system renders `<html lang>` in the `[lang]` segment, never with a fixed default in the root layout**. Localized routes (`app/[lang]/...`) need the correct locale in `<html lang>` at SSR/SSG time. Crawlers and screen readers read this value before hydration. A fixed root render (`<html lang="pt-BR">`) plus a client-side fix serves the wrong `lang` on `/en/*`. The client-side fix is a `useEffect` that sets `document.documentElement.lang`.
+
+  Next.js supports a root layout under a dynamic segment. **Delete `app/layout.tsx`.** Make `app/[lang]/layout.tsx` render `<html lang={...}>`. Take `lang` from `params.lang` (SSG-safe, no `headers()` call).
+
+  This has a required consequence: without a root layout, the `_not-found` route and non-locale paths become orphans. Add `app/global-not-found.tsx` (its own HTML document). Set `experimental.globalNotFound: true` in the Next.js config.
+
+  Move the styled `not-found.tsx` to `app/[lang]/not-found.tsx`.
+  *Verification:* `grep -rn 'html lang' src/app app 2>/dev/null` — the only dynamic-lang match is in `app/[lang]/layout.tsx` (the fixed default is allowed only in `app/global-not-found.tsx`). `grep -rn 'documentElement.lang' src/app app 2>/dev/null` returns empty (no client-side hack). `ls src/app/layout.tsx app/layout.tsx 2>/dev/null` shows the file does not exist.

package/content/modules/prisma-postgres/ach.patch.md

@@ -0,0 +1,65 @@
+---
+type: module
+description: 'Adds the always-run-generate rule and the optimistic-locking pattern to the materialized ACH. Schema layout, generated-client path, and soft-delete are opt-in seeds — see the pointers below.'
+load: cold
+stack: prisma-postgres
+patches: 'docs/ach.md'
+detect: |
+  test -f prisma/schema.prisma
+---
+
+# Patch — ACH for Prisma + Postgres projects
+
+> Apply this to `/docs/ach.md`. It adds the generate-after-edit rule and the multi-actor locking
+> pattern.
+
+## §2 — Add to the tree
+
+```
+prisma/
+  schema.prisma                   # config + datasource
+  seed.ts                         # seed script (also wired as the Prisma seed cmd)
+```
+
+> Prisma 5.15+ also supports splitting the schema across several files, merged by a
+> `prisma.config.ts`, and the generated client's output path is configurable per project. Where
+> those files live and where the client lands — and the three layer-direction import rules this
+> patch used to state as fact alongside them — are house convention, not a Prisma requirement.
+> They now live as an opt-in seed at `code-style/prisma-postgres/imports.md` (concern: imports).
+> Materialize it only if the operator accepts it.
+
+## §6 — Add schema conventions
+
+```md
+### Schema conventions
+
+- **Always run `npx prisma generate`** after you (a) clone the repo, (b) edit any schema file, or
+  (c) update the Prisma version. Without this step, the generated-client imports do not resolve.
+```
+
+> The soft-delete convention this patch used to state as fact — `deletedAt`, a hard-delete SLA
+> comment, the default query filter, and a scheduled cleanup job — is a design choice, not a
+> Prisma fact: Prisma has no opinion on whether a row ever leaves the table. It now lives as an
+> opt-in seed at `code-style/prisma-postgres/error-boundary.md` (concern: error-boundary).
+> Materialize it only if the project actually needs soft delete.
+
+## §6 — Multi-actor concurrency
+
+```md
+### Optimistic locking for multi-actor entities
+
+An entity that more than one actor can edit concurrently (example: a record with a status or
+version field that a background job and a user action can both update) needs a **conditional
+update**, not a plain `update`:
+
+```ts
+const result = await db.record.updateMany({
+  where: { id, version: expectedVersion },
+  data:  { version: nextVersion, ...changes },
+});
+if (result.count === 0) throw new DomainError({ code: "STALE_WRITE" });
+```
+
+Without this pattern, the last write wins silently. For a side-effect-once endpoint (anything that
+should not re-run if a stale client retries), use the same pattern and add a race-condition test.
+```

package/content/modules/prisma-postgres/rules.patch.md

@@ -0,0 +1,28 @@
+---
+type: module
+description: 'Principle for Prisma and Postgres projects: migrations must stay forward-compatible for a rolling deploy. Ships no hard rule of its own — the two this module used to state are opt-in seeds now.'
+load: cold
+stack: prisma-postgres
+patches: 'docs/rules/*.md'
+detect: |
+  test -f prisma/schema.prisma
+---
+
+# Patch — Hard rules for Prisma + Postgres projects
+
+> Hard rules (with an executable trigger) go after the last hard rule in `/docs/afm.md` §3.
+> Principles (verification by review only) go in `/docs/afm.md` §1.3.
+
+## Hard rules (executable trigger)
+
+None. The two rules this module used to state as fact here — a domain function must receive `db`
+through `ctx` instead of importing `PrismaClient` directly, and every query against a
+soft-deletable model must filter `deletedAt: null` — are house conventions, not Prisma facts:
+Prisma has no opinion on dependency injection or on whether a row is ever really deleted. Both are
+now **opt-in seeds**, proposed rather than imposed, at `code-style/prisma-postgres/imports.md`
+(concern: imports) and `code-style/prisma-postgres/error-boundary.md` (concern: error-boundary).
+Materialize either only if the operator accepts it.
+
+## Principles (insert in §1.3 — review, not a trigger)
+
+- **Migrations must stay forward-compatible**. A destructive column drop or rename needs a dual-read phase. Without it, a rolling deploy across N nodes creates an error window. *(No grep can prove rolling-deploy safety — this is a review checklist: "is this migration safe for a rolling deploy?")*

package/content/modules/shadcn-ui/ach.patch.md

@@ -0,0 +1,42 @@
+---
+type: module
+description: 'Adds shadcn-style UI primitive conventions, the Tailwind layer, and the component boundary to the materialized ACH.'
+load: cold
+stack: shadcn-ui
+patches: 'docs/ach.md'
+detect: |
+  test -f components.json
+---
+
+# Patch — ACH for projects with shadcn-style UI primitives
+
+> Apply this to `/docs/ach.md`. It adds conventions for components, Tailwind, and primitives.
+
+## §3.2 — UI primitives
+
+```md
+#### UI primitives
+
+- **What it is:** base components in the shadcn style (Button, Input, Dialog, Sheet, ...). The CLI copies them in through `components.json`. You then edit them in place in the project.
+- **Responsibility:** pure primitives. No domain logic, no fetch, no global state.
+- **Stack:** Tailwind v4 (`@tailwindcss/postcss`), `tw-animate-css`, Radix UI underneath.
+- **Modification:** primitives are copied, not a dependency. Edits stay permanent. Use `npx shadcn add` for new components, then treat them as your own code.
+```
+
+> Where primitives and feature-composed components live (`src/components/ui/*` versus
+> `src/components/<feature>/`) is house convention, not a shadcn fact — shadcn only prescribes
+> where the CLI copies primitives *within* whatever `components.json` points at. That layout now
+> lives as an **opt-in seed** at `code-style/shadcn-ui/naming.md`. Materialize it only if the
+> operator accepts it. How a feature component fetches its data (tRPC, REST, GraphQL, a plain
+> `fetch`) is a different stack's decision entirely — this module does not make it.
+
+## §6 — Conventions
+
+```md
+### shadcn / Tailwind
+
+- `components.json` defines paths and config. Do not edit it by hand. Use the CLI.
+- Use `class-variance-authority` (cva) for variants, typed for autocomplete.
+- Use the `cn()` helper (`clsx` + `tailwind-merge`) as the standard way to compose classes.
+- Components export `Component` plus a `ComponentProps` type. This makes extension easier.
+```

package/content/modules/stripe-billing/ach.patch.md

@@ -0,0 +1,46 @@
+---
+type: module
+description: 'Adds the canonical webhook and the Stripe Subscription Schedule conventions for billing to the materialized ACH.'
+load: cold
+stack: stripe-billing
+patches: 'docs/ach.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("stripe")' package.json >/dev/null 2>&1; else grep -q '"stripe"' package.json 2>/dev/null; fi
+---
+
+# Patch — ACH for projects with Stripe billing
+
+> Applies to `/docs/ach.md`. Adds conventions for the canonical webhook and Stripe Subscription
+> Schedule handling. A file layout for the billing domain, an SDK-wrapper naming scheme, and a
+> server-side gating accessor shape are proposed separately, as an opt-in code-style seed — see
+> `code-style/stripe-billing/naming.md` — because none of the three is a fact about Stripe.
+
+## §6 — Add Billing conventions
+
+```md
+### Billing (webhook-driven state)
+
+### Hard rules for billing
+
+- **The webhook is the canonical source** for subscription state, but a mutation procedure that
+  changes a subscription (a plan change, a cancellation, a checkout self-heal) also writes the
+  new state synchronously. That write is an idempotent upsert, so a webhook that arrives late
+  converges to the same state instead of creating a duplicate or a conflict.
+
+### Stripe Subscription Schedules
+
+A multi-plan subscription flow uses four Stripe operations:
+
+- An immediate Price swap with proration, for an upgrade that should take effect now.
+- Creating or updating a `SubscriptionSchedule` for a Price change that should take effect at the
+  end of the current billing cycle, for a downgrade.
+- Releasing an attached `SubscriptionSchedule`. The release call is a no-op, not an error, when
+  the subscription carries no schedule, so it is safe to call unconditionally before a mutation.
+- Setting `cancel_at_period_end: true` on the subscription, for a cancellation that takes effect
+  at cycle end rather than immediately.
+
+**Critical gotcha:** a subscription with an attached `SubscriptionSchedule` rejects any direct
+mutation through the Subscriptions API (`subscription is managed by subscription schedule`).
+Release the schedule before you mutate a subscription that may be carrying a pending downgrade.
+See the gotcha for the exact error and remedy, and ADR-0002 (if one exists).
+```

package/content/modules/stripe-billing/gotchas.seed.md

@@ -0,0 +1,73 @@
+---
+type: module
+description: 'Seed gotchas for Stripe billing, starting with a subscription that carries a SubscriptionSchedule being immutable.'
+load: cold
+stack: stripe-billing
+patches: 'docs/gotchas/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("stripe")' package.json >/dev/null 2>&1; else grep -q '"stripe"' package.json 2>/dev/null; fi
+---
+
+# Gotchas seed — Stripe billing
+
+> Each entry below is a complete gotcha file. Copy one to `docs/gotchas/NNN-slug.md` (the first `---` of the entry as line 1) only when it bites in real use. Re-date `last_bite` on copy.
+
+---
+type: gotcha
+description: 'A subscription attached to a SubscriptionSchedule rejects every direct update, so release the schedule before you mutate it.'
+load: warm
+fires_on: event
+fires_when: 'you edit a procedure that mutates a subscription (changePlan, cancelSubscription, createCheckout self-heal).'
+bites: 1
+last_bite: 2026-10
+---
+
+## Stripe — a sub with SubscriptionSchedule is immutable
+
+## Behavior
+
+A sub attached to a `SubscriptionSchedule` returns `subscription is managed by subscription schedule` on any direct `subscription.update`. This blocks immediate upgrade and cancel when the user has a pending downgrade.
+
+## Solution
+
+Call `stripe_releaseSubscriptionSchedule(subscriptionId)` before you mutate. The helper returns `null` when there is no schedule, so it is safe to call unconditionally. `changePlan({ planKey: currentPlan })` releases the schedule and clears `pendingPlan` (the "undo pending" pattern).
+
+---
+type: gotcha
+description: 'Changing a Price lookupKey in Stripe forces a new Product and unanchors the existing subscription base.'
+load: warm
+fires_on: event
+fires_when: 'you rename a plan, change a price, or edit planConfig.ts.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Stripe — a Price `lookupKey` is immutable after publish
+
+## Behavior
+
+Changing a Price's `lookupKey` in Stripe forces creation of a **new Product**. Existing subs stay anchored to the old Product, so this unanchors the whole base. A `productName` rename in code is cosmetic only.
+
+## Solution
+
+Stripe requires a manual rename in the dashboard. Or use a new lookupKey only for **new** subs. Keep the old lookupKey valid for the current base.
+
+---
+type: gotcha
+description: 'Stripe delivers webhook events at least once, so a handler with a direct INSERT creates duplicates.'
+load: warm
+fires_on: event
+fires_when: 'you implement a webhook handler, for example for customer.subscription.updated.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Stripe — `customer.subscription.updated` can arrive more than once
+
+## Behavior
+
+Stripe can deliver the same event more than once (at-least-once delivery). A handler that runs a direct INSERT creates a duplicate.
+
+## Solution
+
+Use an idempotent UPSERT keyed on the unique `stripeSubscriptionId`. Detect a plan transition (`existing.plan !== incoming.plan`) and act only on the real transition.

package/content/modules/stripe-billing/rules.patch.md

@@ -0,0 +1,30 @@
+---
+type: module
+description: 'Hard rules for Stripe billing, split between executable triggers and review-only principles.'
+load: cold
+stack: stripe-billing
+patches: 'docs/rules/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("stripe")' package.json >/dev/null 2>&1; else grep -q '"stripe"' package.json 2>/dev/null; fi
+---
+
+# Patch — Hard rules for Stripe billing
+
+> Hard rules (with an executable trigger) go in after the last hard rule in `/docs/afm.md` §3.
+> Principles (verification by review only) go in `/docs/afm.md` §1.3.
+
+## Hard rules (executable trigger)
+
+- **Card data NEVER touches the backend.** Checkout and Portal run hosted on Stripe.
+  *Verification:* `grep -rnE "card.*number|cvc|cvv" {{src-path}}/` returns 0.
+
+> A server-side gate on every billing-restricted procedure is a genuine requirement — a
+> frontend-only check is UX, not a boundary — but the exact accessor shape and its grep
+> verification are one codebase's convention, not a Stripe fact. See
+> `code-style/stripe-billing/naming.md` for that as an opt-in proposal.
+
+## Principles (insert in §1.3 — review, not a trigger)
+
+- **A subscription-mutation procedure writes to the DB synchronously. It does not rely only on the webhook.** The webhook is canonical. The procedure is convergent. It uses upsert for idempotency. *(Review: each procedure that changes a subscription — a plan change, a cancellation — upserts the Subscription record after the Stripe call.)*
+- **Before it mutates a subscription, the procedure checks whether a `SubscriptionSchedule` is attached and releases it first.** Stripe rejects a direct mutation on a subscription that has a schedule. *(Review: ask "can this procedure run on a subscription that carries a pending downgrade?".)*
+- **The webhook verifies the signature BEFORE any lookup.** Without a valid signature, it does not touch the DB. *(Review: the Stripe SDK's signature-verification call is the first line of the route handler, before any DB read.)*

package/content/modules/trigger-dev-v4/ach.patch.md

@@ -0,0 +1,64 @@
+---
+type: module
+description: 'Materializes the Task-like component type with Trigger.dev v4 vocabulary in the ACH.'
+load: cold
+stack: trigger-dev-v4
+patches: 'docs/ach.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trigger.dev/sdk")' package.json >/dev/null 2>&1; else grep -q '"@trigger.dev/sdk"' package.json 2>/dev/null; fi
+---
+
+# Patch — ACH for Trigger.dev v4 projects
+
+> Applies to `/docs/ach.md`. Materializes Task-like with Trigger.dev vocabulary.
+
+## §3.1 — Task-like → Trigger.dev v4 task
+
+```md
+#### Task (Trigger.dev)
+
+- **What it is:** an async, idempotent, retry-safe unit of work. The Trigger.dev v4 infrastructure runs it.
+- **Single responsibility:** one workflow step, or a cron orchestrator. It reads canonical state from the DB. It returns early on terminal states. It updates the DB atomically. It triggers the next task when needed.
+- **When to use it:**
+  - Cron (crawler's `schedules.task`).
+  - A long workflow that needs retry (build + publish).
+  - An external integration with variable latency or expected failure.
+- **When NOT to use it:**
+  - The work fits in under 5 seconds with no retry. Use a procedure instead.
+  - The logic is pure with no I/O. Use domain instead.
+- **Convention:** the task `id` matches the file name in kebab-case. Example: `start-deployment-workflow.ts` becomes `tasks.task("start-deployment-workflow", ...)`. This is Trigger.dev's own convention — the dashboard and CLI both key a run on it — so it stays here as fact, unlike the file-tree layout and import boundary below, which are one operator's choice.
+
+##### Pattern: a thin parent calls subtasks through `triggerAndWait`
+
+A multi-stage workflow is a thin parent that coordinates, plus subtasks that do the work. Each subtask has its own `runId`, its own retry, its own log stream, and its own machine size. The parent only calls `triggerAndWait`.
+
+Example topology:
+
+~~~
+start-deployment-workflow  (orchestrator — machine: small-1x)
+  ├── triggerAndWait("build-sdk",   { buildId })   — machine: large-1x
+  └── triggerAndWait("publish-sdk", { publishId })  — machine: medium-1x
+~~~
+
+Benefits: granular retry (publish alone, with no rebuild), isolated logs, a machine size tuned per stage, and composability (`retag-publish` reuses auth and the registry without a rebundle).
+```
+
+> The task directory tree (`src/trigger/` with `cron-<X>.ts` / `<stage>-<entity>.ts` /
+> `start-<entity>-workflow.ts`), the import boundary between tasks and the rest of the codebase,
+> and the `createTriggerContext()` DB-access helper are house convention, not Trigger.dev facts —
+> nothing about Trigger.dev requires this layout or this helper. They now live as an **opt-in
+> seed**, proposed rather than imposed, at `code-style/trigger-dev-v4/naming.md` and
+> `code-style/trigger-dev-v4/imports.md`. Materialize either only if the operator accepts it.
+
+## §6 — Trigger conventions
+
+```md
+### Trigger config (`trigger.config.ts`)
+
+- `build.external` — deps that must NOT be bundled (for example, `tsdown` when used as a runtime subprocess).
+- `machines` — sizing per task. The topology above sizes the orchestrator small, build large, and publish medium; size each stage against its own workload.
+```
+
+> Where the project ID lives — pinned in `trigger.config.ts` versus read from env — is an
+> operator call this module does not make either way; state it in the project's own docs if it
+> matters there.

package/content/modules/trigger-dev-v4/gotchas.seed.md

@@ -0,0 +1,53 @@
+---
+type: module
+description: 'Seed gotchas for Trigger.dev v4, starting with the run id changing between attempts of the same run.'
+load: cold
+stack: trigger-dev-v4
+patches: 'docs/gotchas/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trigger.dev/sdk")' package.json >/dev/null 2>&1; else grep -q '"@trigger.dev/sdk"' package.json 2>/dev/null; fi
+---
+
+# Gotchas seed — Trigger.dev v4
+
+> Each entry below is a complete gotcha file. Copy one to `docs/gotchas/NNN-slug.md` (the first `---` of the entry as line 1) only when it bites in real use. Re-date `last_bite` on copy.
+
+---
+type: gotcha
+description: 'ctx.run.id differs on each retry attempt, so a runId persisted to track one execution points at the last attempt instead.'
+load: warm
+fires_on: event
+fires_when: 'you write a new Trigger.dev task, especially one that persists a runId in a row.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Trigger.dev — `params.ctx.run.id` changes between attempts
+
+## Behavior
+
+`ctx.run.id` differs on each retry attempt. A task that persists runId to track one execution loses the link on retry. It ends up pointing to the last run instead.
+
+## Solution
+
+Make the runId that tracks a process **immutable after the first write**. Use `updateMany({ where: { id, runId: null }, data: { runId } })` for an atomic upsert. Keep canonical state in the DB, not in the run id.
+
+---
+type: gotcha
+description: 'Trigger.dev bundles everything a task imports, which breaks binaries the task runs as a subprocess unless they are listed in build.external.'
+load: warm
+fires_on: event
+fires_when: 'you update Trigger.dev, edit trigger.config.ts, or remove a binary used as a subprocess at runtime.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Trigger.dev — put `tsdown` (or similar) in `build.external`
+
+## Behavior
+
+Trigger.dev tries to bundle everything a task imports. Binaries invoked as a subprocess (`tsdown`, `esbuild`, `rollup`) break when bundled. The task expects a file but receives a module instead.
+
+## Solution
+
+Keep the binary listed in `trigger.config.ts` `build.external`. Document this in the config's comment.

package/content/modules/trigger-dev-v4/rules.patch.md

@@ -0,0 +1,35 @@
+---
+type: module
+description: 'Hard rules for Trigger.dev v4 projects, split between executable triggers and review-only principles.'
+load: cold
+stack: trigger-dev-v4
+patches: 'docs/rules/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trigger.dev/sdk")' package.json >/dev/null 2>&1; else grep -q '"@trigger.dev/sdk"' package.json 2>/dev/null; fi
+---
+
+# Patch — Hard rules for Trigger.dev v4 projects
+
+> Hard rules (with an executable trigger) go in after the last hard rule in `/docs/afm.md` §3.
+> Principles (verified by review only) go in `/docs/afm.md` §1.3.
+
+## Hard rules (executable trigger)
+
+None. Both rules this module used to state as a hard, path-bound trigger — routing task DB
+access through `createTriggerContext()` instead of `prismaClient` directly, and requiring an
+idempotency test co-located with each task — are house convention, not Trigger.dev facts:
+nothing about Trigger.dev requires either helper or that test layout. Worse, the first one gated
+an invented helper at an invented path (`src/lib/trigger.ts`) as if it were framework law. Both
+verifications also hardcoded one operator's `src/trigger/` directory, so they would fail
+vacuously on any project laid out differently. They now live as an **opt-in seed**, proposed
+rather than imposed, at `code-style/trigger-dev-v4/imports.md` (the context helper) and
+`code-style/trigger-dev-v4/test-placement.md` (the idempotency test, plus the `runId`
+atomic-upsert example that guards it). Materialize either only if the operator accepts it.
+
+## Principles (insert in §1.3 — review, not a trigger)
+
+None currently. The `runId`-immutability principle that lived here was tied entirely to the
+idempotency-test hard rule above and had no separate grep trigger of its own — it moved with
+that rule to `code-style/trigger-dev-v4/test-placement.md`, as the worked example of the atomic
+upsert. Add a principle here only for a genuine Trigger.dev fact that mechanical review, not a
+grep, has to catch.

package/content/modules/trpc-v11/ach.patch.md

@@ -0,0 +1,56 @@
+---
+type: module
+description: 'Materializes the Procedure-like and Domain-like component types with tRPC v11 vocabulary in the ACH.'
+load: cold
+stack: trpc-v11
+patches: 'docs/ach.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trpc/server")' package.json >/dev/null 2>&1; else grep -q '"@trpc/server"' package.json 2>/dev/null; fi
+---
+
+# Patch — ACH for tRPC v11 projects
+
+> Apply this to `/docs/ach.md`. It materializes Procedure-like and Domain-like with tRPC vocabulary.
+
+## §3.1 — Procedure-like → tRPC procedure
+
+```md
+#### Procedure (tRPC)
+
+- **What it is:** a tRPC handler with Zod input, auth through middleware, and a typed return the frontend can consume.
+- **Single responsibility:** orchestrate (< ~5s) — validate → authorize → call domain/lib → persist → respond.
+- **When to use it:** every synchronous UI ↔ server interaction. REST `/api/v1/*` is derived through `trpc-to-openapi` when applicable.
+```
+
+> Naming (export and file), the neighbor-test rule, and the subrouter's location are house
+> convention, not a tRPC fact — a project can name and place these however it wants and the
+> handler shape above still holds. They now live as an opt-in seed at
+> `code-style/trpc-v11/naming.md` (naming) and `code-style/trpc-v11/test-placement.md`
+> (test placement). Materialize either only if the operator accepts it.
+
+## §3.1 — Domain-like → function with `DomainInput<T>`
+
+```md
+#### Domain (per module)
+
+- **What it is:** pure business-rule functions. Signature: `({ ctx, input }: DomainInput<T>) => …`. Always use `{ ctx, input }`, even when `ctx` is unused, for consistency.
+- **Domain does NOT import `TRPCError`.** `TRPCError` is a transport type — importing it in domain code couples business logic to the tRPC boundary. Use `DomainError({ code: "..." as const })` or `Result<T, E>` instead; the procedure maps the code to `TRPCError` at the boundary.
+```
+
+> How many functions live in one file, and the file/export naming, are house convention — they
+> now live as an opt-in seed at `code-style/trpc-v11/file-size.md` (one function per file) and
+> `code-style/trpc-v11/naming.md` (export/file naming). A mechanical, path-bound check for the
+> "no `TRPCError` in domain" principle above — which needs the project's actual domain-layer
+> path — is also in the seed, at `code-style/trpc-v11/error-boundary.md`.
+
+## §6 — ISP through `Pick<TRPCContext, ...>`
+
+```md
+- A domain function declares only the `ctx` fields it uses: `ctx: Pick<TRPCContext, "db" | "log">`. It does not receive the full `TRPCContext`. This keeps tests smaller and makes the dependency explicit.
+```
+
+> The remaining house conventions this module used to state as fact — the subrouter's exact
+> directory (`modules/<f>/router.ts`) and a specific `makeTestCtx` test helper naming one file
+> path that exists in exactly one repo — are not a tRPC fact either. See
+> `code-style/trpc-v11/naming.md` and `code-style/trpc-v11/test-placement.md` for the proposals
+> that replace them.

package/content/modules/trpc-v11/rules.patch.md

@@ -0,0 +1,34 @@
+---
+type: module
+description: 'Hard rules for tRPC v11 projects, including domain code that never raises a transport error.'
+load: cold
+stack: trpc-v11
+patches: 'docs/rules/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trpc/server")' package.json >/dev/null 2>&1; else grep -q '"@trpc/server"' package.json 2>/dev/null; fi
+---
+
+# Patch — Hard rules for tRPC v11 projects
+
+> Hard rules (with an executable trigger) go after the last hard rule in `/docs/afm.md` §3.
+> Principles (verified only by review) go in `/docs/afm.md` §1.3.
+
+## Hard rules (executable trigger)
+
+None. Every rule this module used to state as a hard, path-bound trigger — the
+`procedure_<action><Module>` / `domain_<action><Module>` export naming, and the ban on a
+`__tests__/` folder — is house convention, not a tRPC fact: nothing about tRPC requires a
+particular export prefix or test-file location. They now live as an **opt-in seed**, proposed
+rather than imposed, at `code-style/trpc-v11/naming.md` and
+`code-style/trpc-v11/test-placement.md`. Materialize either only if the operator accepts it.
+
+## Principles (insert into §1.3 — review, not a trigger)
+
+- **A transport error type must not reach the domain layer.** `TRPCError` is tRPC-specific;
+  a domain function that imports it couples business logic to the transport boundary and makes
+  the domain layer harder to reuse outside tRPC (a queue worker, a CLI, a test). The procedure
+  maps a domain error code to `TRPCError` at the edge instead.
+  *(This is a genuine layering fact, but a mechanical check for it needs the project's actual
+  domain-layer path, which is house layout and varies by repo. A concrete, path-bound grep that
+  verifies it is proposed — not imposed — at `code-style/trpc-v11/error-boundary.md`.)*
+- **A domain function uses `Pick<TRPCContext, ...>` instead of the full TRPCContext** when it needs only part of ctx. *(No grep can tell partial use from full use — this needs review. Flag a procedure that receives full ctx but uses only part of it.)*