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

package/content/code-style/_any/naming.md

@@ -0,0 +1,72 @@
+---
+type: code-style
+description: 'Decides the shape of an export name — prefix or suffix, and action-first or entity-first.'
+load: cold
+concern: naming
+---
+
+# Code style — Export naming
+
+## The decision
+
+This is not about which word to use — it is about the SHAPE the decision takes. Two independent
+axes decide the shape of an exported name, and a codebase needs an answer on each:
+
+1. **Where does the layer tag sit** — as a prefix (`domain_createUser`), as a suffix
+   (`createUserDomain`), or nowhere in the name at all, left to the folder the file lives in?
+2. **What comes first inside the name** — the action (`createUser`) or the entity
+   (`userCreate`)?
+
+## Axis 1 — Prefix, suffix, or no tag
+
+- **Prefix** (`domain_<action><Entity>`): sorted alphabetically, every export in a layer clusters
+  together — `grep '^export const domain_'` finds the whole layer's public surface in one
+  command, independent of file location. **Cost:** the identifier now carries information the
+  file's own path already carries, and the two can drift — a file that moves to a different layer
+  keeps a prefix that no longer describes it until someone renames the export too.
+- **Suffix** (`<action><Entity>Domain`): reads as a noun phrase — "createUserDomain" parses as
+  "the Domain [operation] for creating a User" the way English adjectives-after-noun sometimes
+  read more naturally in code completion, where the base name (`createUser`) still autocompletes
+  first, and the layer qualifier appears as a refinement. **Cost:** same drift risk as a prefix,
+  and alphabetical clustering by layer is lost — sorting now clusters by action or entity instead.
+- **No tag, layer signaled by path alone**: the shortest name, and the file's directory is the
+  single source of truth for its layer, so there is nothing in the identifier that can drift out
+  of sync with reality. **Cost:** nothing greppable-by-name marks the boundary. Enforcing "domain
+  code never imports the transport layer" now needs a path-based rule instead of a name-based one
+  — which is not necessarily worse, but it is a different mechanism, and re-exports through a
+  barrel file can make the path itself ambiguous.
+
+## Axis 2 — Action-first or entity-first
+
+- **Action-first** (`createUser`, `deleteUser`, `createOrder`): matches how the code reads at the
+  call site — a verb phrase. Typing the action ("create…") surfaces every creator across every
+  entity, which is how "what CRUD operations exist" gets scanned.
+- **Entity-first** (`userCreate`, `userDelete`, `orderCreate`): typing the entity ("user…")
+  surfaces every operation on that one entity, which is how "what can I do to a User" gets
+  scanned. This is the axis that matters more when most work is "go deep on one entity" rather
+  than "go wide across one action."
+
+Neither axis has a universally right answer — the right answer is whichever one matches how this
+team actually searches its own codebase more often, which the measurement below settles instead
+of guessing.
+
+## How to measure which shape this codebase already follows
+
+Look at the exports that already exist before proposing a shape:
+
+```sh
+grep -rhoE '^export (async )?function [a-zA-Z_]+' src \
+  | sed 's/.* //' | sort | uniq -c | sort -rn | head -20
+```
+
+Read the output for a dominant prefix (`^[a-z]+_`), a dominant suffix, or neither. If a majority
+already follows one shape, propose codifying it — do not introduce a third shape into a codebase
+that has already, even informally, converged on one.
+
+## Consequence of mixing both
+
+A codebase with `domain_createUser` next to `createOrderDomain` next to `handleWebhook` (no tag at
+all) cannot be greped for "every domain export" by any single pattern — the search has to know,
+file by file, which shape that file happened to use. The mechanical boundary check that a
+consistent shape would give for free (one `grep`, one hard rule) degrades into a manual read of
+every file, which is the exact cost a naming convention exists to avoid.

package/content/code-style/_any/test-placement.md

@@ -0,0 +1,57 @@
+---
+type: code-style
+description: 'Decides where a test file lives relative to the source file it tests.'
+load: cold
+concern: test-placement
+---
+
+# Code style — Test placement
+
+## The decision
+
+A test file needs a fixed address relative to the source it tests. Two shapes answer that, and a
+codebase drifts the moment both are in use at once.
+
+## Option A — Neighbor file
+
+`<name>.test.ts` sits in the same directory as `<name>.ts`.
+
+- **For:** the test is one file-tree hop from the code, so opening one strongly suggests the
+  other. Deleting or moving the source and forgetting the test is rare — the two sit side by side
+  in every directory listing and every diff.
+- **Against:** a directory that holds ten source files now holds twenty entries. A quick `ls` of
+  "what does this module do" is diluted by an equal count of test files.
+
+## Option B — A `__tests__/` directory
+
+Tests for a module collect under a sibling `__tests__/` folder instead of sitting next to the
+source.
+
+- **For:** the source directory stays a pure listing of what the module does. Tooling that treats
+  "test" as a separate concern (a coverage report, an editor's file-tree filter) has one folder to
+  point at instead of a naming pattern to match.
+- **Against:** the link between a source file and its test is now a path convention, not
+  proximity. Renaming `foo.ts` to `bar.ts` and forgetting `__tests__/foo.test.ts` produces an
+  orphaned test that nothing flags — the file still runs, just against code that no longer exists
+  under that name.
+
+## How to measure which one this codebase already follows
+
+Count both shapes before proposing either one — the codebase has usually already chosen:
+
+```sh
+find src -name "*.test.*" -o -name "*.spec.*" | grep -v '__tests__' | wc -l   # neighbor count
+find src -type d -name "__tests__" | wc -l                                    # __tests__ dirs present
+```
+
+A clear majority on one side settles it. Propose codifying what already dominates, not the
+option either of you prefers in the abstract — a rule that fights the existing grain gets
+routed around at the first deadline.
+
+## Consequence of mixing both
+
+A codebase with both shapes present can't grep its way to "did this file get a test" — the search
+has to check two locations, and a script that checks only one silently under-reports coverage.
+Worse, a reviewer scanning for the test of a changed file checks the neighbor first, finds
+nothing, and assumes untested when the test is one level away in `__tests__/`. Pick one, and let
+the measurement above decide which one costs less to enforce.

package/content/code-style/nextjs-app-router/imports.md

@@ -0,0 +1,50 @@
+---
+type: code-style
+description: 'Proposes a rule that a route handler stays thin and delegates logic to a server/ layer, instead of embedding business rules in the App Router route file.'
+load: cold
+stack: nextjs-app-router
+concern: imports
+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
+---
+
+# Code style — Next.js route handlers delegate to server/
+
+> This is a **proposal**, not a fact about Next.js. Next.js has no opinion on whether a
+> `route.ts` file contains business logic or calls out to another layer — this is a
+> layer-direction choice, the same kind covered generally in `code-style/_any/imports.md`.
+> Materialize it into `docs/ach.md` and `docs/afm.md` §3 only if the operator accepts it. Nothing
+> here is `(mandatory)`.
+
+## The convention
+
+- A route handler under `src/app/api/.../route.ts` validates input, calls into a `server/` layer,
+  and returns the response. It contains no inline business rule.
+- The `server/` layer (or whatever a project already calls its business/domain code) owns the
+  actual logic; the route file is a thin adapter between the HTTP boundary and that layer.
+
+## Why this works
+
+A route handler that only adapts input to a call and a result to a response stays small enough to
+read in one pass, and the same business logic becomes reachable from a second entry point (a cron
+job, a CLI, another route) without duplicating it. Keeping the rule qualitative — "delegate, don't
+embed" — rather than a line-count threshold avoids the trap the line-count version of this rule
+fell into: a fixed number with no measurement behind it. A project that wants a mechanical
+backstop for file size can add one from `code-style/_any/file-size.md` instead, with a threshold
+it actually measured against its own files.
+
+## The trade-off
+
+"Delegate to server/" assumes a project already has, or wants, a server/domain layer distinct from
+the route file — a small project with three routes and no other consumer of that logic gets pure
+indirection for no reuse benefit. And the rule itself is not mechanically checkable: nothing greps
+"this route file contains a business rule" reliably, so it stays a review-time principle unless a
+project also has file-size or complexity tooling that catches a route file growing past what
+adapting alone should need.
+
+## If the operator accepts this
+
+Materialize it into `docs/ach.md` §6 as a §1.3 principle (review, not a grep trigger) — there is
+no mechanical check for "no inline business rule." A project that also wants a numeric backstop
+should adopt `code-style/_any/file-size.md` separately, with a threshold measured against its own
+route files, not an imported constant.

package/content/code-style/nextjs-app-router/naming.md

@@ -0,0 +1,50 @@
+---
+type: code-style
+description: 'Proposes rooting the App Router at src/app/, a src/components/ location for UI primitives, and a naming convention for route groups.'
+load: cold
+stack: nextjs-app-router
+concern: naming
+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
+---
+
+# Code style — Next.js App Router folder naming
+
+> This is a **proposal**, not a fact about Next.js. Next.js accepts the App Router rooted at
+> `app/` **or** `src/app/` — either works with no config. Where UI primitives live and how a route
+> group is named are house choices on top of that, not a framework requirement. Materialize any
+> part of this into `docs/ach.md` and `docs/afm.md` §3 only if the operator accepts it — item by
+> item, at bootstrap. Nothing here is `(mandatory)`.
+
+## The convention
+
+- Root the App Router at `src/app/`, not the repo-root `app/` — keeps every source file under one
+  `src/` tree, alongside `src/lib/`, `src/server/`, and the like.
+- Put UI primitives (shadcn-style components, feature components) in `src/components/`. No direct
+  fetch — data arrives through the project's transport client, never a component-level `fetch`.
+- Group authenticated routes under a named route group, for example `(protected)/`, and
+  unauthenticated ones under a plain folder, for example `auth/` — so the URL path and the auth
+  boundary read the same way in the file tree.
+
+## Why this works
+
+`src/` as a single root means a contributor never has to ask "is this file at the repo root or
+under `src/`" — there is one answer, and tooling (a `tsconfig.json` `baseUrl`, an ESLint
+`import/no-relative-parent-imports` rule) can assume it. A named route group for the auth boundary
+makes the split visible in a file listing, before opening any file.
+
+## The trade-off
+
+Next.js's own default is `app/` at the repo root, with no `src/` at all — a project that starts
+there and later adds a `src/` tree for everything else pays a one-time move, and any doc or
+tutorial written against the plain-`app/` default needs a mental translation. Route-group naming
+is invisible to the URL (Next.js strips the parens), so it only pays off if the team actually
+reads folder names during review; a team that navigates by IDE search alone gets no benefit from
+the convention and only the extra folder nesting.
+
+## If the operator accepts this
+
+Materialize the tree into `docs/ach.md` §2 and the route-group convention into §6. There is no
+mechanical check for "is this the right root" — Next.js accepts either — so this stays a §1.3
+principle, not a §3 hard rule, unless the project also adds a lint rule that fails on the
+unwanted root.

package/content/code-style/prisma-postgres/error-boundary.md

@@ -0,0 +1,55 @@
+---
+type: code-style
+description: 'Proposes a soft-delete convention — a deletedAt column, a filter-by-default query rule, and a scheduled hard-delete job — as one boundary a query must respect, not a Prisma requirement.'
+load: cold
+stack: prisma-postgres
+concern: error-boundary
+detect: |
+  test -f prisma/schema.prisma
+---
+
+# Code style — Prisma + Postgres soft-delete boundary
+
+> Soft delete is a **design choice**, not a Prisma fact — Prisma has no opinion on whether a row
+> ever leaves the table. This is a proposal for one way to implement it, framed as a boundary a
+> query must respect: a soft-deleted row must not cross from storage into application code unless
+> the caller explicitly asked for it. Materialize it into `docs/ach.md` and `docs/afm.md` §3 only
+> if the operator accepts it. Nothing here is `(mandatory)`.
+
+## The convention
+
+- Add `deletedAt: DateTime?` to a model that needs soft delete.
+- Mark the retention SLA with a schema comment next to the column, for example
+  `// hard-delete after 180d`.
+- Every query against a soft-deletable model filters `deletedAt: null` by default. An admin or
+  audit path may opt out explicitly — never silently.
+- A scheduled job performs the actual hard delete once the SLA elapses, separate from the request
+  path that sets `deletedAt`.
+
+## Why this works
+
+Without a default filter, a soft-deleted row is indistinguishable from a live one to every query
+that does not remember to exclude it — and that memory is exactly what a hard rule replaces. Two
+grep-able boundaries make it mechanical: which models declare `deletedAt` at all, and whether
+every read against them filters it.
+
+## The trade-off
+
+A default filter on every query is easy to forget for a *new* soft-deletable model — the check
+below only fires once a model already has `deletedAt`, so nothing enforces adding the column in
+the first place. It also adds a `WHERE` clause and often a partial index to every query against
+that model, for a feature many projects never use (a hard delete plus an audit-log row is simpler
+when no product requirement asks for undo or a retention window). A project without that
+requirement should skip this entirely rather than add the column speculatively.
+
+## If the operator accepts this
+
+Materialize the convention into `docs/ach.md` §6 and add a hard rule to `docs/afm.md` §3, verified
+by:
+```sh
+grep -rn "deletedAt" {{src-path}}/server/modules/
+```
+Every match is a query against a soft-deletable model; each one either filters `deletedAt: null`
+or is an admin/audit path that says so in a comment. List the models that actually declare
+`deletedAt` first (`grep -n "deletedAt" prisma/schema.prisma` or the project's schema files) —
+the check only means something once at least one model has the column.

package/content/code-style/prisma-postgres/imports.md

@@ -0,0 +1,61 @@
+---
+type: code-style
+description: 'Proposes a schema-file split, a generated-client output path, and three layer-direction import rules for a Prisma + Postgres project.'
+load: cold
+stack: prisma-postgres
+concern: imports
+detect: |
+  test -f prisma/schema.prisma
+---
+
+# Code style — Prisma + Postgres schema layout and import direction
+
+> This is a **proposal**, not a fact about Prisma. Prisma itself only requires one
+> `schema.prisma` file that a `generator client` block points at some output path — where split
+> files live, what the output folder is called, and which layer may import the generated client
+> directly are all house choices. Materialize any part of this into `docs/ach.md` and
+> `docs/afm.md` §3 only if the operator accepts it — item by item, at bootstrap. Nothing here is
+> `(mandatory)`.
+
+## The convention
+
+**Schema layout**
+- Split the schema by domain: `prisma/schemas/<module>.prisma`, one file per domain, merged by a
+  `prisma.config.ts` (Prisma 5.15+ multi-file schema).
+- Output the generated client to `.prisma/` at the repo root (gitignored). Reference it with a
+  relative import: `../../.prisma/client`, `../../.prisma/enums`.
+
+**Import direction**
+- `{{src-path}}/server/modules/<f>/domain/*` may import types from `.prisma/enums`. It does not
+  import the Prisma client directly — it receives `db` through `ctx`.
+- `{{src-path}}/lib/*` never imports `.prisma/*` — `lib/` is publishable outside this project, and
+  a generated-client import would tie it back to this schema.
+- `{{src-path}}/trigger/*` may import `.prisma/*` through a context-constructor helper, if the
+  project has one.
+
+## Why this works
+
+A fixed schema-split location and a single generated-client path give every contributor the same
+two answers ("where do I add a model", "where does the client come from") without asking. The
+import-direction rules turn "domain code should not couple to Prisma's client type, and `lib/`
+should stay portable" from a review-time reminder into something a hard rule can check by path.
+
+## The trade-off
+
+None of this is required by Prisma itself. A project with a single-schema file, a different
+output path (Prisma's own default is `node_modules/.prisma/client`), or no `lib/`/`trigger/`
+split at all gets nothing from importing this layout — the value is internal consistency, not a
+Prisma constraint. The `db`-through-`ctx` rule also asks every domain function to accept a `ctx`
+argument even where it feels like ceremony for a one-line query; a smaller project may prefer the
+simplicity of importing the client directly and accept the harder-to-mock trade-off instead.
+
+## If the operator accepts this
+
+Materialize the layout into `docs/ach.md` §2 (the folder tree) and the import rules into
+`docs/afm.md` §3, verified per rule by:
+```sh
+grep -rnE "from.*prisma/client|new PrismaClient" {{src-path}}/server/modules/*/domain/
+grep -rn "\.prisma/" {{src-path}}/lib/
+```
+Both must return 0 for the rule to hold; fill `{{src-path}}` with the project's actual root
+before pasting either grep — an unresolved placeholder matches nothing and passes vacuously.

package/content/code-style/shadcn-ui/naming.md

@@ -0,0 +1,48 @@
+---
+type: code-style
+description: 'Proposes separate directories for copied shadcn primitives and for feature components that compose them.'
+load: cold
+stack: shadcn-ui
+concern: naming
+detect: |
+  test -f components.json
+---
+
+# Code style — shadcn primitive vs. feature component layout
+
+> This is a **proposal**, not a fact about shadcn. Materialize it into `docs/ach.md` only if the
+> operator accepts it — item by item, at bootstrap. Nothing here is `(mandatory)`.
+
+## The convention
+
+```
+src/
+  components/
+    ui/              # shadcn primitives — CLI-copied, then edited in place
+    <feature>/        # components that compose primitives with feature logic
+```
+
+`components/ui/` holds only what `npx shadcn add` copied in, plus your in-place edits to it.
+Anything that combines a primitive with data, feature logic, or app-specific composition goes in
+its own `components/<feature>/` directory instead.
+
+## Why this works
+
+Keeping the copied primitives in one directory makes it obvious, at a glance, which files are
+"vendored" shadcn code you have edited versus app code written from scratch — useful the day you
+want to diff a primitive against an upstream shadcn update.
+
+## The trade-off
+
+A project with only a handful of components total does not need the split yet — one flat
+`components/` directory is simpler until the primitive/feature distinction starts to matter. A
+design system that already dictates its own component directory convention (the `vireya-ui`
+module, for one) should not have this layered on top of it — the two conventions are for
+different stacks and are not meant to combine.
+
+## If the operator accepts this
+
+Materialize the directory split into `docs/ach.md`, under the UI primitive component type. This
+convention has no mechanical check of its own — `components.json`'s `aliases.ui` path is the
+only part shadcn itself enforces, and nothing distinguishes a "feature" component from a
+misplaced primitive except review.

package/content/code-style/stripe-billing/naming.md

@@ -0,0 +1,76 @@
+---
+type: code-style
+description: 'Proposes a file layout and naming scheme for a Stripe billing module: one way to organize it, not a Stripe requirement.'
+load: cold
+stack: stripe-billing
+concern: naming
+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
+---
+
+# Code style — Stripe billing naming and layout
+
+> Seed for `docs/code-style/stripe-billing/naming.md`. A proposal, materialized only if the
+> operator accepts it during the interview. Stripe imposes none of this; it is one way to
+> organize a multi-plan billing module, offered so a project does not have to invent the layout
+> from zero.
+
+## Proposal: an SDK-wrapper directory with a prefixed export name
+
+- Put every direct call into the Stripe SDK behind a thin wrapper, in its own directory (for
+  example `src/lib/stripe/`), so a reader can tell at a glance which functions cross the network
+  and which are local logic.
+- Name every exported wrapper function with the same lowercase prefix (for example
+  `stripe_createCustomer`, `stripe_verifyWebhook`), so a call site reads as "this touches Stripe"
+  without opening the import.
+- Export one client-getter function (for example `stripe_getClient()`) instead of a module-level
+  singleton instance. A getter is easier to mock in a test and easier to reconfigure per request
+  (multi-tenant API keys, test mode) than a value captured at import time.
+
+**Trade-off.** The prefix is redundant once the directory name already says "stripe" — a project
+that values shorter names over grep-ability may skip it and rely on the import path alone. The
+getter-over-singleton choice costs one extra function call at every use site; a project with a
+single, static API key and no test doubles to satisfy may prefer the plain singleton.
+
+## Proposal: a dedicated billing domain with a capability matrix
+
+For a subscription product with more than one paid plan, keep the mapping from plan to
+capabilities in one place instead of scattering `if (plan === 'pro')` checks through the
+codebase:
+
+- A **plan-to-price config**: one constant per paid plan (lookup key, amount, interval), plus a
+  map from the app's own plan identifier to that config, and the reverse lookup (a Stripe Price
+  lookup key back to the app's plan identifier) that a webhook handler needs.
+- A **capability matrix**: one file that is the single source of truth for which capability each
+  plan unlocks — a table or map from plan to a set of boolean flags, one flag per gated feature.
+- A **billing-state resolver**: a pure function from the current subscription (status, plan) to
+  the resolved capability flags. A subscription in good standing (active, trialing, or a
+  grace-period past-due) carries its plan's capabilities; a suspended subscription (unpaid,
+  incomplete, paused) drops to the free tier's capabilities even while the stored plan label
+  still shows what the customer was nominally on, so an account page can say "you were on the
+  Pro plan" instead of silently forgetting it.
+- A **webhook dispatcher** that resolves the plan from the event's Price lookup key and calls the
+  resolver.
+
+**Trade-off.** This earns the indirection once there are two or more paid plans with different
+capabilities — below that, a single `isPaid: boolean` flag is simpler, and the matrix is YAGNI.
+The four-file split also assumes a `domain/` layer already exists in this codebase's module
+convention; a project without one should collapse it to fewer files rather than manufacture the
+layer just to hold this pattern.
+
+## Proposal: gate every capability check through one accessor shape, server-side
+
+Expose the resolved capability flags on the request context under one dot-path (for example
+`ctx.user.billing.canX`), and have every procedure that performs a gated action check that flag
+before it runs — never only in the frontend, since a client-side check is UX, not a boundary an
+attacker cannot cross.
+
+*Suggested verification, once a project adopts this shape (point the glob at where this
+project's procedures actually live):* `grep -rnE "billing\.can" <procedures-dir>` should show
+every gated procedure checking the flag before it acts.
+
+**Trade-off.** A single dot-path accessor is convenient once many procedures gate on it, but it
+couples every caller to that exact context shape. A project that already has its own
+authorization layer (a policy object, a decorator, a middleware) should express the same
+"check server-side, never trust the client" principle through its own shape instead of adopting
+this one.

package/content/code-style/trigger-dev-v4/imports.md

@@ -0,0 +1,58 @@
+---
+type: code-style
+description: 'Proposes an import boundary for task files and a shared context helper for their DB access.'
+load: cold
+stack: trigger-dev-v4
+concern: imports
+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
+---
+
+# Code style — task import boundary and context helper
+
+> This is a **proposal**, not a fact about Trigger.dev. Materialize it into `docs/ach.md` and
+> `docs/afm.md` §3 only if the operator accepts it — item by item, at bootstrap. Nothing here is
+> `(mandatory)`.
+
+## The convention
+
+A task file may import `lib/`, `domain/`, and the ORM client, but not the request-layer
+procedures (tRPC routers, REST handlers, and so on) — a task is triggered, not called, so
+importing a procedure the same way an HTTP handler would defeats the boundary the task runs
+behind.
+
+To avoid every task constructing its own DB client by hand, route the ones that need one through
+a single helper that wraps the ORM singleton, for example:
+
+```ts
+// src/lib/trigger.ts
+export function createTriggerContext() {
+  return { db: prismaClient /* , ...whatever else every task needs */ };
+}
+```
+
+## Why this works
+
+One place constructs the client, so pool sizing and connection reuse are decided once instead of
+once per task file. It also gives every task the same starting shape, which lowers the cost of
+reading the next one.
+
+## The trade-off
+
+A single task, or a set of tasks with no DB access at all, does not need a shared helper — a
+direct import is simpler, and the helper would be a speculative abstraction (YAGNI). A project
+that already has a context-building convention for its request layer gains nothing from a second,
+task-only version — reuse the existing one instead. The import boundary itself is also only as
+good as the discipline behind it: nothing in Trigger.dev enforces it, so a project that adopts it
+needs a mechanical check, not just a convention nobody reads.
+
+## If the operator accepts this
+
+- Materialize the import boundary and the context-helper pattern into `docs/ach.md`, under the
+  Task component type.
+- Add a hard rule to `docs/afm.md` §3, verified by (point the glob at where this project's tasks
+  actually live):
+  ```sh
+  grep -rnE "prismaClient|new PrismaClient" {{src-path}}/trigger/
+  ```
+  Zero results required, except the file that **defines** the context helper.

package/content/code-style/trigger-dev-v4/naming.md

@@ -0,0 +1,49 @@
+---
+type: code-style
+description: 'Proposes a directory tree and file-naming pattern for Trigger.dev v4 tasks.'
+load: cold
+stack: trigger-dev-v4
+concern: naming
+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
+---
+
+# Code style — Trigger.dev v4 task layout
+
+> This is a **proposal**, not a fact about Trigger.dev. Materialize it into `docs/ach.md` only if
+> the operator accepts it — item by item, at bootstrap. Nothing here is `(mandatory)`.
+
+## The convention
+
+```
+src/
+  trigger/                        # Trigger.dev v4 tasks
+    cron-<X>.ts                   # cron / schedules
+    <stage>-<entity>.ts           # subtasks
+    start-<entity>-workflow.ts    # orchestrators
+```
+
+One directory, one file per task, and the file name states the task's role (`cron-`,
+`start-…-workflow`, or a bare `<stage>-<entity>`) before you open it.
+
+## Why this works
+
+Grepping `src/trigger/` lists every task the project runs, in one place, sorted by what kind
+each one is — no need to open a file to learn whether it is a cron, an orchestrator, or a
+subtask.
+
+## The trade-off
+
+A monorepo that already splits tasks per package has its own layout, and forcing this tree onto
+it adds a migration with no payoff. A project with only one or two tasks does not need a
+dedicated subtree yet — inline them where they are triggered from, and adopt this once a third
+task shows up (Rule of Three). The prefixes themselves are also redundant with the `id` passed to
+`tasks.task(...)`, which already states the same thing at the call site.
+
+## If the operator accepts this
+
+Materialize the tree and the three file-name prefixes into `docs/ach.md`, under the Task
+component type. This convention has no mechanical check of its own beyond the directory existing
+— naming a task file correctly is check-able only by parsing each file's exported task `id`
+against its filename, which duplicates the kebab-case convention already stated as fact in
+`docs/ach.md`. Do not add a redundant hard rule for the prefixes alone.

package/content/code-style/trigger-dev-v4/test-placement.md

@@ -0,0 +1,61 @@
+---
+type: code-style
+description: 'Proposes co-locating an idempotency test with each task, and an atomic-upsert pattern for the state it guards.'
+load: cold
+stack: trigger-dev-v4
+concern: test-placement
+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
+---
+
+# Code style — Trigger.dev v4 idempotency test placement
+
+> This is a **proposal**, not a fact about Trigger.dev. Materialize it into `docs/ach.md` and
+> `docs/afm.md` §3 only if the operator accepts it — item by item, at bootstrap. Nothing here is
+> `(mandatory)`.
+
+## The convention
+
+**Neighbor test.** Every task a rerun could touch twice (a webhook retry, a `triggerAndWait`
+failure that reruns its parent, a manual replay from the dashboard) gets a test co-located with
+it — `<task>.test.ts` in the same directory as `<task>.ts` — asserting that a second run does not
+corrupt state: an early return on a terminal state, or a no-op on an already-applied write.
+
+**One way to make the write itself safe:** an atomic upsert guarded by the field that tracks the
+run:
+
+```ts
+await db.thing.updateMany({
+  where: { id, runId: null },
+  data: { runId },
+});
+```
+
+`runId` is written once; a rerun with the same `runId` finds no row where it is still `null`, so
+it updates nothing.
+
+## Why this works
+
+A task that silently double-applies its write on a retry is a production incident, not a style
+nit — Trigger.dev retries by design, so idempotency is the one thing every task must get right.
+Testing it next to the task keeps the two in sync when either one changes.
+
+## The trade-off
+
+A task with no side effect a rerun could double-apply (a pure fan-out, a read-only report) does
+not need this test — write one only where a second run has something to corrupt. A project whose
+test layout is centralized instead of co-located should keep the idempotency test there too — the
+co-location is the suggestion, the idempotency test itself is not. The `updateMany`/`runId`
+pattern also assumes a DB row already exists to guard; a task whose idempotency depends on an
+external system (an upstream API that is itself idempotent by request key) needs a different
+guard entirely.
+
+## If the operator accepts this
+
+- Materialize the neighbor-test convention into `docs/ach.md`, under the Task component type.
+- Add a hard rule to `docs/afm.md` §3, verified by (point the glob at where this project's tasks
+  actually live):
+  ```sh
+  grep -rLE "rerun|retry|already.*processed" {{src-path}}/trigger/*.test.ts
+  ```
+  Lists tasks with no idempotency test — review the list, it is not a pass/fail count.