@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/.claude/luminaries/vaughn-vernon.md

@@ -0,0 +1,50 @@
+---
+tier: lite
+name: Vaughn Vernon
+slug: vaughn-vernon
+claimed_by: [architect]
+referenced_by_skills: [decompose, architect-review]
+primary_domain: architecture
+depth: stub
+description: "\"DDD is implementable. Here's how.\""
+---
+
+# Vaughn Vernon
+
+## Signature
+
+*"DDD is implementable. Here's how."*
+
+Author of **Implementing Domain-Driven Design** (the "red book") and
+**Domain-Driven Design Distilled**. The canonical operational voice for
+DDD — where Evans provides the philosophy, Vernon provides the code.
+
+## Core methods
+
+- **Bounded Context Canvas** — Structured workshop output that defines a
+  bounded context's purpose, strategic classification, domain roles,
+  ubiquitous language, and inbound/outbound communication.
+- **Context mapping patterns** — Partnership, Shared Kernel,
+  Customer/Supplier, Conformist, Anticorruption Layer, Open Host Service,
+  Published Language, Separate Ways, Big Ball of Mud. Vocabulary for how
+  bounded contexts relate.
+- **Aggregate design rules** — Small aggregates; reference other
+  aggregates by ID only; update one aggregate per transaction; use
+  eventual consistency between aggregates.
+- **Event Storming (via Alberto Brandolini)** — Vernon popularized this
+  modeling method as the pragmatic entry point to DDD for teams new to it.
+
+## Sources
+
+- *Implementing Domain-Driven Design* — Vernon, Addison-Wesley (2013)
+- *Domain-Driven Design Distilled* — Vernon, Addison-Wesley (2016)
+- *Strategic Monoliths and Microservices* — Vernon, Jaskuła (2021)
+- kalele.io — Vernon's consultancy and ongoing DDD content
+
+## Related luminaries
+
+- **Eric Evans** — Vernon operationalizes Evans; pair them always.
+- **Alistair Cockburn** — Hexagonal Architecture pairs naturally with
+  bounded contexts; aggregates live inside hexagons.
+- **Gregor Hohpe** — EIP's anticorruption-layer aligns with Vernon's
+  context mapping.

package/substrate/.claude/luminaries/w-edwards-deming.md

@@ -0,0 +1,158 @@
+---
+tier: lite
+name: W. Edwards Deming
+slug: w-edwards-deming
+claimed_by: [builder, architect, closer, shaper]
+primary_domain: engineering
+depth: full
+description: "\"A bad system will beat a good person every time.\""
+---
+
+# W. Edwards Deming
+
+## Signature
+
+*"A bad system will beat a good person every time."*
+
+W. Edwards Deming (1900–1993) was a statistician who taught Japanese
+industry to read the system, not the person, when results disappoint.
+His finding from decades of plant data: roughly **94% of variation in
+outcomes traces to the system**, and roughly **6% traces to people**.
+The implication was strict — every time results land badly and the
+default reaction is "the person should have been more careful," the
+default is wrong 94% of the time. Deming's full discipline ran from the
+ground up: a cycle for improvement (**PDSA / PDCA**), a framing for
+what management owed the system (**14 Points**), and a system view
+called the **System of Profound Knowledge** that tied it all together.
+
+## Core methods
+
+- **PDCA / PDSA cycle (Plan-Do-Check-Act, later Plan-Do-Study-Act)** —
+  the discipline of substrate improvement. Plan a change. Do it small
+  first. Study what actually happened. Act on the finding (standardize
+  or revise). Loop. Use when the change is non-trivial AND the team is
+  about to ship without a structured way to learn from the result.
+- **14 Points for Management** — the duties of leadership in a system
+  that produces variation. Headline points: drive out fear; break down
+  barriers between departments; cease dependence on inspection (build
+  quality in); institute leadership; remove arbitrary numerical quotas.
+  Read the full 14 when shaping team structure or substrate-discipline
+  rules — many bassclef rules are 14-Points applied to agents.
+- **System of Profound Knowledge** — four lenses applied together:
+  appreciation for a system (the whole, not the parts); theory of
+  variation (special vs common causes); theory of knowledge (no
+  knowledge without prediction); psychology (people respond to
+  systems). Use when the question is "what kind of fix is this" —
+  process-level, structural, learning, or human.
+- **Common cause vs special cause** — variation has two flavors. Common
+  cause is built into the system (every run produces it). Special
+  cause is a specific event (a one-time trigger). The diagnosis path is
+  different for each. Use when picking remediation: common cause needs
+  a system change; special cause needs a single intervention.
+
+## When to channel this luminary
+
+Channel Deming whenever the default explanation reaches for
+operator-forgetfulness, agent-laziness, adopter-skill-gaps, or any
+"person should have been more careful" framing. Deming forces the
+question: is the system designed to make the right behavior easy? If
+not, the system is the defect.
+
+Also channel when shaping a hardening pass. The four lenses of the
+System of Profound Knowledge are the architect-review lenses Deming
+would apply in order. Specifically:
+
+- Appreciation for a system → C4 Context + Container diagrams; see the
+  whole substrate before zooming into hooks
+- Theory of variation → distinguish substrate-wide failure classes
+  (common cause) from one-off PR breakage (special cause)
+- Theory of knowledge → every hardening proposal predicts an outcome;
+  no prediction means no learning when the result lands
+- Psychology → adopters respond to substrate friction; reduce the
+  friction rather than asking adopters to push through it
+
+## Stack translation
+
+Bassclef's hooks, rules, validators, and skills are the **system**
+Deming describes. Operators and Claude Code agents are the **people**.
+When a defect surfaces:
+
+- If the same defect surfaces across three sessions, that is common
+  cause — patch the system (hook, validator, rule)
+- If the defect is a one-time slip (a typo, a missed paste), that is
+  special cause — fix the instance; do not change the substrate
+- If the defect surfaces because the discipline is methodology-only
+  (no mechanical gate), the system is the defect — escalate to hook
+
+PDCA maps onto substrate evolution: a /promote ticket is the **Plan**.
+Shipping the rule + hook is the **Do**. Watching for stuck-signal
+diagnostics across the next month is the **Study**. Closing or revising
+the rule based on usage data is the **Act**. Bassclef's
+`stuck-signal-diagnostic.md` rule is Deming's Study phase made
+mechanical.
+
+## Anti-patterns it prevents
+
+- **Operator-forgetfulness framing** — When a SessionStart hook fires
+  on a missing field, the first instinct can be "the operator forgot
+  to add it." Deming asks: is the hook design such that the field is
+  obvious? Is the bootstrap row shipped with the validator? If the
+  answer to either is no, the system is the defect — not the operator.
+- **Inspection-as-quality** — When a substrate gate fires repeatedly
+  and the answer is "more vigilance," that is inspection-instead-of-
+  quality-built-in. Deming Point #3: cease dependence on inspection.
+  Instead, build the validation INTO the surface that produces the
+  artifact (template that includes the required field; schema
+  validation at write time; pre-commit gate that emits the missing
+  row).
+- **Quota-driven scope-cutting** — When a session's appetite framing
+  drives toward (a) narrow fix because (c) full audit feels too big,
+  Deming Point #11 fires: remove arbitrary numerical quotas. Appetite
+  is a budget for shape-picking, not a quota for cause-categorization.
+  Run fishbone first; THEN pick the scope that fits the cause.
+
+## Worked example
+
+2026-06-24 chronicle reads: "Operator-side rot has structural cause,
+not operator forgetfulness." That single sentence is Deming applied.
+The 51-hour-stale `~/.claude/hooks/bassclef-sync.sh` did not happen
+because the operator forgot to update; it happened because the cp-list
+in §3 of the sync script omitted the script itself — the hook could
+not update itself. ADR-034 closed the gap with the two-stage rocket
+pattern — a SYSTEM change, not a person change.
+
+The four 2026-06-24 substrate defects all share the same Deming class:
+
+| Defect | System fix shipped | If Deming had been ignored |
+|---|---|---|
+| Operator-side rot | ADR-034 two-stage bootstrap | Tell operator to remember to sync |
+| 32 unwired hooks | #319 + #320 audit | Tell agent to remember to wire |
+| /kiss skip on PRs | bassclef#915 → hook | Tell agent to remember /kiss |
+| Public-scripts origin | #320 audit + WU-2 C4 Container | Tell operator to remember |
+
+The right-column reactions are the 6% framing. The left-column fixes
+are the 94% framing. Bassclef ships the 94% reactions by default; this
+luminary names the discipline.
+
+## Sources
+
+- *Out of the Crisis* — Deming (1986)
+- *The New Economics for Industry, Government, Education* — Deming (1993)
+- *Statistical Quality Control* — Deming (1939)
+
+## Related luminaries
+
+- **Walter Shewhart** — Deming's mentor; originator of PDCA (then
+  PDSA). Bassclef does not yet ship a Shewhart entry; the discipline
+  comes through Deming.
+- **Kaoru Ishikawa** — fishbone categorizes; PDCA improves. Use
+  Ishikawa to see the categories; use Deming to run the improvement
+  cycle.
+- **Taiichi Ohno** — Five Whys traces one chain; Deming asks whether
+  the chain is common-cause or special-cause variation.
+- **Linus Torvalds** — "we do not break userspace" is Deming Point #1
+  (constancy of purpose) applied to kernel stability. Bassclef's
+  adopter-respect rule is the same shape.
+- **John Ousterhout** — deep modules hide complexity; Deming would
+  call this designing the system so the surface is easy to use
+  correctly.

package/substrate/.claude/rules/accessor-library-discipline.md

@@ -0,0 +1,138 @@
+---
+tier: lite
+description: State spine consumers (skills, hooks, rules, scripts) MUST go through the typed accessor library lib/state.sh to read or write bassclef state.
+---
+
+# Accessor Library Discipline
+
+State spine consumers (skills, hooks, rules, scripts) MUST go through
+the typed accessor library `lib/state.sh` to read or write bassclef
+state. Direct filesystem access (cat, jq, awk, grep over JSON state
+files) is forbidden when an accessor exists.
+
+This rule is the Adapter discipline that preserves cxdb portability —
+exit criterion 1 of the 7 in canvas v4 §"Adapter discipline":
+
+> **Accessor library is the ONLY consumer of cxdb APIs.** No skill,
+> hook, rule, or script invokes cxdb directly. All access goes through
+> `lib/state.sh`.
+
+Same principle applied at v0 (where the storage backend IS the
+filesystem): no consumer reaches around the accessor to the raw files.
+
+## Why this rule exists
+
+When cxdb adoption ships (bassclef#300), the implementation of
+`lib/state.sh` swaps from JSON-on-git to cxdb's Turn DAG + Blob CAS.
+**This swap is invisible to consumers IF and ONLY IF every consumer
+goes through the accessor.** Any consumer that reads
+`docs/whereami.json` directly today will need editing tomorrow.
+
+Beyond cxdb portability, this rule also enforces:
+
+- **Replay-determinism** — accessors carry the "derive from history,
+  never cache" rule per canvas v4 SWF mining. Bypassing the accessor
+  bypasses the discipline (this is what produced bassclef#296
+  compliance-counter floor-lift).
+- **Schema validation** — accessors that mutate (add/set/update_status)
+  invoke the validator before writing. Direct file writes skip this
+  gate.
+- **Single-source consistency** — if Whereami's storage shape changes
+  (e.g., schema field rename), only `lib/state.sh` needs updating.
+
+## What this rule forbids
+
+In any skill, hook, rule, or script:
+
+- `cat docs/whereami.json` → use `state_whereami_get`
+- `jq '.field' docs/whereami.json` → use `state_whereami_get | jq '.field'`
+- `find state/markers -name '*.json' | wc -l` → use `state_marker_count`
+- `awk '/gates_fired:/' chronicle/*.md` → use `state_chronicle_gate_evidence`
+- `ls docs/deferred-actions/*.md | grep -v completed` → use `state_deferred_action_pending`
+- `cat docs/iteration-bets/<slug>.md | yq frontmatter` → use `state_iteration_bet_get`
+
+In general: any pattern that reaches into a state file (JSON or
+markdown frontmatter) is the violation. Read the contract at
+`standards/state-spine-contract.md` for the bassclef accessor surface.
+
+## What this rule allows
+
+- **Reading the accessor library itself** — `source lib/state.sh` and
+  call its functions. That's the entire point.
+- **Reading non-state markdown content** — body sections of Shape B
+  entities (the narrative parts, not the YAML frontmatter) can be
+  read directly. Example: `awk '/## Procedure/,/^## /' docs/iteration-bets/<slug>.md`
+  to extract the Procedure section is fine; that's narrative content,
+  not state.
+- **Reading non-spine files** — `cat .claude/skills/<skill>/SKILL.md`,
+  `cat README.md`, etc. State spine entities are enumerated in
+  `standards/state-spine.md`; other files aren't governed.
+- **Direct JSON writes during one-shot migrations** (e.g., WU-4
+  migration script). Migration scripts are explicitly out-of-band —
+  they bootstrap state into the spine from prior shapes.
+
+## What about new accessors that don't exist yet?
+
+If a consumer needs an accessor not yet in `lib/state.sh`:
+
+1. **Check if a generic verb suffices** — `state_<entity>_get`,
+   `state_<entity>_list`, `state_<entity>_count` cover most reads.
+2. **If a special-purpose accessor is needed**, propose it to the
+   contract first (`standards/state-spine-contract.md` §"Special-purpose
+   accessors"), then implement in `lib/state.sh`, then consume.
+3. **Do NOT bypass with direct file access** "just for now." That's
+   the path that produced bassclef#296.
+
+The cost of adding a new accessor is small (~5-10 lines + tests). The
+cost of accumulating ad-hoc bypass patterns is large and compounds
+(every consumer needs a fix when the storage backend changes).
+
+## Enforcement
+
+### Methodology level
+
+This rule loads into every session via `additionalDirectories`. Agents
+self-check against it before reading or writing state. Code review
+flags any direct state-file access in PRs.
+
+### Mechanical level (paired with WU-3)
+
+The `state-validate.sh` PreToolUse hook (WU-3) detects direct writes
+to state files and BLOCKs unless the change is going through an
+accessor. Read-side enforcement is harder to mechanize but the
+write-side gate covers the most damaging case.
+
+### Future mechanical level (post-v0)
+
+A pre-commit hook could grep for forbidden patterns (`cat docs/whereami.json`,
+`jq.*docs/whereami.json`, etc.) in staged changes and BLOCK unless an
+override comment is present. Defer to v1 once empirical violation rate
+is observable.
+
+## Override
+
+`SKIP_ACCESSOR_DISCIPLINE=1 <command>` — logged to trace per existing
+bassclef hook idiom. Use only for genuinely-not-yet-covered cases
+where adding the accessor is in flight; not as a habitual workaround.
+
+## Relationship to other rules + standards
+
+- `standards/state-spine.md` — entity catalog + storage shapes
+- `standards/state-spine-contract.md` — the accessor surface this rule
+  enforces consumption through
+- `lib/state.sh` — the implementation
+- `.claude/rules/state-schema-validation.md` (paired with WU-3) —
+  write-time validation; the accessor's `add`/`set`/`update_status`
+  methods invoke this validator before writing
+- canvas v4 §"Adapter discipline" — the source of this discipline; one
+  of 7 exit criteria for cxdb portability
+- bassclef#296 — the compliance-counter floor-lift incident that
+  motivates pure-derivation discipline (this rule + replay-determinism)
+
+## Retirement condition
+
+This rule retires only if the accessor library itself retires (very
+unlikely — the library is the substrate primitive other state work
+builds on). If a future architectural shift moves accessors elsewhere
+(e.g., into per-entity files like `lib/state/whereami.sh`), this rule
+amends to point at the new location; the discipline persists.

package/substrate/.claude/rules/adr-discipline.md

@@ -0,0 +1,120 @@
+---
+tier: lite
+description: "Every load-bearing architectural decision MUST be recorded as an ADR (Architecture Decision Record) per Michael Nygard's lifecycle: proposed → accepted → deprecated → superseded."
+---
+
+# ADR Discipline
+
+Every load-bearing architectural decision MUST be recorded as an ADR (Architecture Decision Record) per Michael Nygard's lifecycle: `proposed` → `accepted` → `deprecated` → `superseded`.
+
+ADR discipline lives at the rule layer (this file) plus the mechanical layer (`.claude/hooks/adr-discipline-check.sh` — PreToolUse hook on architectural-decision paths). Both load-bearing for adopter architecture quality.
+
+## Why this rule exists
+
+ADR discipline previously lived only in the Architect agent persona. Sequential-mode adopter sessions skip Architect role entirely; architectural decisions ship without records.
+
+INSTEAD: this rule mechanizes ADR discipline at the decision boundary via PreToolUse hook. The hook fires regardless of which agent role is active.
+
+Eugene-supplements `apps/web` made 4+ architectural decisions (Postgres over SQLite, Server Actions over Express, Prisma over Drizzle, single-app over monorepo) with zero ADRs. The cost compounds: future maintainers can't reconstruct why; future architectural decisions can't be measured against the original rationale; deprecation requires re-deriving the decision context months later.
+
+## When this rule fires
+
+Any session writing or editing a file matching architectural-decision shape:
+
+- `prisma/schema.prisma` or per-ORM schema equivalent (schema-change)
+- `docker-compose*.yml` or `docker-compose*.yaml` (deployment-topology-change)
+- `src/middleware.ts` or per-stack middleware equivalent (middleware-change)
+- `*/alembic/versions/*.py` / `*/db/migrate/*.rb` / `*/migrations/*.go` (schema-migration)
+- `package.json` / `pyproject.toml` / `Gemfile` / `go.mod` / `Cargo.toml` on Write only (dependency-manifest-change)
+
+When match fires, the hook checks for an ADR marker at `state/markers/adr/<decision-slug>-*.md`. The marker is required — generic ADRs in `docs/adrs/` or `architecture/decisions/` are not sufficient because they may be unrelated to the current decision class. When the marker is absent, the hook BLOCKs with template + writeup prompt.
+
+## Load-bearing definition
+
+A decision is load-bearing when:
+
+- It establishes an invariant future decisions must respect
+- Reversing it would require substantial migration work (>1 day operator time)
+- Multiple parts of the codebase depend on it
+- It crosses a bounded context boundary (per Evans DDD)
+- It changes a cross-cutting concern (auth, logging, multi-tenancy, observability stack)
+
+Non-load-bearing (skip ADR):
+
+- Bug fixes within existing patterns
+- Component-level library choices (icon library, date-picker)
+- Cosmetic refactors (renames, file reorganizations without behavior change)
+- Test additions
+- Documentation edits
+
+When in doubt, write the ADR. Ten-minute cost; high-value record.
+
+## ADR format
+
+Use `standards/adr-template.md`. Required sections:
+
+- Frontmatter: id, title, status, date, supersedes, superseded_by
+- Context — what motivated the decision
+- Decision — the choice + rationale
+- Status — proposed / accepted / deprecated / superseded
+- Consequences — what becomes easier / harder / enables / blocks
+- References — related ADRs, external sources, source incidents
+
+## Marker convention
+
+After writing the ADR, touch the marker:
+
+```bash
+mkdir -p state/markers/adr
+touch state/markers/adr/<decision-slug>-ADR-NNN.md
+```
+
+The marker is the audit trail: the hook reads it; reviewers can grep for it; chronicle Gate Evidence sections can cite it.
+
+## Override path
+
+`SKIP_ADR_CHECK=1 <command>` — logged via trace-helper. Use rarely:
+
+- Trivial revert of a previously-decided architectural change (the revert is reversing the prior decision per its `superseded_by` field)
+- Emergency rescue when the hook itself misclassifies (file substrate-defect)
+- One-shot migration script that touches many architectural files (operator has reviewed externally)
+- Bulk dependency-manifest regen where every dep was already declared in a prior ADR
+
+INSTEAD of overriding for routine work: write the ADR. The ten-minute cost is one of the cheapest substrate disciplines to follow.
+
+## Tech-stack-aware composition
+
+ADR discipline is stack-agnostic. The same template applies across stacks. Per-stack ADR examples may ship as siblings under `standards/adr-examples/<stack>.md` over time, with the discipline itself staying the same across stacks.
+
+## What the rule does NOT cover
+
+- ADR review process (operator + Architect agent collaboration)
+- ADR retirement (status change to `deprecated` or `superseded`; the file stays in place)
+- Cross-project ADR sharing (bassclef's ADRs and adopter's ADRs stay in separate directories)
+- ADR templates for non-software architecture (deployment-process ADRs, team-structure ADRs — out of scope for this rule)
+
+INSTEAD: each of the above lives in a sibling rule or template if it becomes relevant.
+
+## Composition with other rules
+
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on hook + tests (this hook + its test file land Tier 0)
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires
+- `.claude/rules/oo-ad-entry-point.md` — `/decompose` evidence is sister discipline at Construction boundary
+- `.claude/rules/schema-management.md` — schema-change ADR aligns with migration-discipline
+- `standards/adr-template.md` — the template the rule references
+
+## Refs
+
+- bassclef#1149 — this rule's filing ticket (T17 of cold-adopter promote drop)
+- bassclef#1134 — ARCH-T1 grandparent (adopter inheritance umbrella)
+- bet 2026-06-20e — WU-11 ships this rule + template + hook
+- `.claude/hooks/adr-discipline-check.sh` — the mechanical implementation
+- `.claude/hooks/tests/adr-discipline-check.test.sh` — Tier 0 test coverage
+- `standards/adr-template.md` — the ADR template
+- `@luminary michael-nygard` — anchor for ADR lifecycle (Cognitect, 2011)
+
+## Retirement condition
+
+This rule retires only if ADRs themselves cease to be a bassclef architecture-record format. The mechanical layer (hook) may evolve to detect more decision shapes; the methodology of recording load-bearing decisions persists.
+
+Closes adopter architecture-record gap surfaced by Eugene-supplements 2026-06.

package/substrate/.claude/rules/api-conventions.md

@@ -0,0 +1,125 @@
+---
+tier: lite
+description: Universal API design principles — REST conventions, response shapes, status codes, auth, validation. Stack-specific globs + helpers live in per-stack siblings under standards/api-conventions/.
+---
+
+# API Conventions
+
+Universal API design principles for any HTTP API surface. Stack-specific instantiations (Next.js App Router, FastAPI, Rails, Express, Go) live in per-stack siblings under `standards/api-conventions/`. The loader (future ticket) reads adopter's `tech_stack.frontend` + `tech_stack.backend` from `.claude/bassclef-configs.jsonc` and loads the matching sibling.
+
+When no sibling exists for the adopter's stack, the universal principles below still apply.
+
+## Universal principles
+
+These hold regardless of stack.
+
+### Route naming
+
+- RESTful: `/api/[resource]` for collections, `/api/[resource]/[id]` for items
+- Nested resources: `/api/[parent]/[parentId]/[child]`
+- Actions (non-CRUD): `/api/[resource]/[id]/[action]` (e.g., `/api/deals/123/archive`)
+- Lowercase, hyphenated: `/api/deal-pipeline`, not `/api/dealPipeline`
+
+### Response shapes
+
+Standard wrapper for successful single-item responses:
+
+```json
+{
+  "data": { ... },
+  "meta": { "timestamp": "2026-04-05T10:00:00Z" }
+}
+```
+
+Standard wrapper for successful collection responses:
+
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "total": 42,
+    "page": 1,
+    "pageSize": 20,
+    "timestamp": "2026-04-05T10:00:00Z"
+  }
+}
+```
+
+Standard error shape:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description",
+    "details": [ ... ]
+  }
+}
+```
+
+### HTTP status codes
+
+| Code | When |
+|------|------|
+| 200 | Success (GET, PUT, PATCH) |
+| 201 | Created (POST) |
+| 204 | No content (DELETE) |
+| 400 | Validation error, bad input |
+| 401 | Not authenticated |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, stale update) |
+| 500 | Unexpected server error |
+
+### Pagination
+
+Default: cursor-based for lists > 20 items. Offset-based acceptable for admin/internal endpoints.
+
+```
+GET /api/deals?cursor=abc123&pageSize=20
+→ { data: [...], meta: { nextCursor: "def456", hasMore: true } }
+```
+
+### Auth
+
+- Every route that modifies data requires auth — no exceptions
+- Read routes may be public if explicitly marked (e.g., `// PUBLIC: [reason]` comment)
+- Auth check happens at the route boundary, not inside handlers
+- Tenant context resolved at the route boundary, passed through to queries
+
+### Validation
+
+- Validate all input at the route handler boundary
+- Use a schema-validation library (Zod, Pydantic, JSON Schema, etc.) for request body validation
+- Never trust client-provided IDs for authorization decisions
+- Use parameterized queries to prevent injection (every ORM has its own mechanism)
+
+## Per-stack siblings
+
+Per ARCH-T0 #1133 Path A — stack-specific instantiations live in their own files. Loader reads adopter's `tech_stack` from `.claude/bassclef-configs.jsonc`.
+
+| Adopter's `tech_stack.frontend` | Sibling loaded |
+|---|---|
+| `nextjs` | `standards/api-conventions/nextjs.md` |
+| `fastapi` | `standards/api-conventions/fastapi.md` *(future — file `/promote` to author)* |
+| `rails` | `standards/api-conventions/rails.md` *(future)* |
+| `express` | `standards/api-conventions/express.md` *(future)* |
+| `none` or unset | universal principles only |
+
+When the matching sibling does not exist, the universal principles above apply; sibling-specific guidance is skipped until the operator declares the stack and a sibling ships.
+
+## Path A treatment
+
+This rule shipped under ARCH-T0 #1133 Path A — additive, no content removed. Existing Next.js App Router specifics (formerly in this file) moved to `standards/api-conventions/nextjs.md`. Adopters following the rule pre-split keep working: the universal principles match what was already documented; the Next.js specifics are still discoverable via the sibling.
+
+Loader infrastructure that reads sibling per `tech_stack` is a future ticket. Until it ships, the cross-reference table above is the discovery path.
+
+## Refs
+
+- ARCH-T0 #1133 — operator-stack-leakage audit + remediation (parent)
+- ARCH-T1 #1134 — Bassclef-as-Platform full adopter inheritance (grandparent)
+- bassclef#1309 — this sub-ticket (api-conventions Path A)
+- bassclef#1150 T18 — sister Path A (migration-discipline)
+- `.claude/rules/schema-management.md` — precedent rule for Path A additive shape
+- `.claude/rules/new-dependency-check.md` — sister precedent
+- `standards/api-conventions/nextjs.md` — Next.js App Router sibling