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

package/content/rubrics/episodic-vs-semantic-boundary.md

@@ -0,0 +1,37 @@
+---
+type: rubric
+description: Separates what decays from what is permanent, and says where each one lives.
+load: warm
+fires_on: op-call
+called_by: ["reconcile", "reflect"]
+fires_when: 'an artifact needs a tier: does it decay or is it permanent'
+---
+
+# Rubric — episodic vs semantic boundary (what decays vs what is permanent)
+
+> This rubric applies invariant principle #1 ("if another agent without my memory needs to know it, it is doc") on the **time** dimension. Not every artifact in `/docs/` is permanent knowledge. v3.1.0+ (Phase 3 of the v3.2 initiative). Ancestor: CoALA (arXiv 2309.02427) — **episodic** memory (what happened) differs from **semantic** memory (what is known) and from **procedural** memory (how to do it).
+
+## The tiers in AFM
+
+| Tier | What it is | Where it lives | Does it decay? | Enters diagnose axes A1-A7? |
+|---|---|---|---|---|
+| **Semantic** | durable knowledge: rules, architecture, decisions, surprises | `afm.md`, `ach.md`, `prd.md`, `ust.md`, `gotchas.md`, `adr/`, `learnings/`, `rubrics/` | **No** — superseded (ADR Superseded, tombstone), never deleted | **Yes** |
+| **Procedural** | repeatable sequences | `procedures/` | frequency/staleness (`restructure`) | Yes (inherited coverage) |
+| **Episodic** | what happened in one session: work state, handoff | handoff block in `sessions/`, `_focus.md` (current focus) | **Yes** — an aged `open` handoff decays (A2). `_focus` is OVERWRITE | **NO** (it is state, not knowledge) |
+| **Telemetry** | append-only log of events/failures. **real use of the methodology** | `.afm-log/`, `.afm-log-failures/`. **timeline and `afm_findings` in `sessions/`** | only by rotation/retention. audit trail = git | **NO** (append-only) |
+
+> **`sessions/` is dual-tier** (v4/F9). One file carries both parts. The **handoff block** decays: `state: open|consumed` governs **only that block**. `consumed` means "already read", never "file is dead". The **telemetry** part does not decay: what was asked, how AFM was used, `afm_findings`. This part is versioned and travels with the repo. It is what an agent in the plugin repo reads to improve AFM from real use. Rule 17's exclusion still applies by closed path — the file is append-per-session, never rewritten.
+
+## Decision criteria
+
+- **Does another agent without my memory need this to avoid breaking something?** Then it is **semantic**: permanent, enters diagnose, never decays on its own. This is #1.
+- **Is it "where I was" or "what happened in this session"?** Then it is **episodic**: it decays and stays out of diagnose. Giving this permanence fills diagnose with noise.
+- **Promotion from episodic to semantic is the point of `reconcile`.** An episode can reveal a load-bearing decision, rule, or gotcha. When it does, `reconcile` proposes materializing it in the semantic tier. This proposal needs a human gate (#6). The episode is the **buffer** where evolution finds candidates, not the evolution itself.
+
+## Anti-patterns
+
+- ❌ **Treating handoff or `_focus` as a normative doc.** This fills diagnose (A1-A7) with volatile state. These artifacts are episodic.
+- ❌ **Reading `state: consumed` as "the file can disappear".** `state` governs only the handoff block. The telemetry from the same session stays alive and versioned.
+- ❌ **Letting semantic knowledge decay.** A rule, decision, or gotcha does not decay with age. It is superseded (ADR) or consolidated (`generalize`). It is never deleted for age (#5: institutional memory).
+- ❌ **Letting `_focus.md` grow.** It must stay small state that gets overwritten (rule 20), not a log.
+- ❌ **Promoting an episode to semantic without checking against #1.** Not everything that "happened" is something another agent needs to know.

package/content/rubrics/error-classification.md

@@ -0,0 +1,98 @@
+---
+type: rubric
+description: Separates a domain error from a procedure error and from an infrastructure error.
+load: warm
+fires_on: file-shape
+trigger_path: '*/domain/*'
+trigger_grep: '(\b(TRPCError|HttpException|HTTPException|ApiError|ResponseError)\b|throw[[:space:]]+new[[:space:]]+Error\()'
+fires_when: 'a transport error type or a bare `Error` is raised inside a `domain/` path'
+---
+
+# Rubric — error classification (Domain vs. Procedure vs. Infra)
+
+## The 3 levels
+
+### Domain error — a business rule is violated
+
+**Who throws it:** `domain_*` functions (pure business rules).
+
+**How to represent it:**
+
+```ts
+// Option A: Result<T, E> (preferred for clean flow control)
+type Result<T, E> =
+  | { ok: true; value: T }
+  | { ok: false; code: E };
+
+const result = await domain_createUserAuth({ ctx, input });
+if (!result.ok) {
+  switch (result.code) {
+    case "EMAIL_TAKEN": ...
+    case "WEAK_PASSWORD": ...
+    default: {
+      const _exhaustive: never = result.code;
+      throw new Error(`unhandled domain code: ${_exhaustive}`);
+    }
+  }
+}
+
+// Option B: throw DomainError when the caller rarely handles each case
+class DomainError<C extends string> extends Error {
+  constructor(public readonly code: C, message?: string) { super(message); }
+}
+throw new DomainError("MAGIC_LINK_INVALID");
+```
+
+**The code must be a literal `as const`.** The switch then guarantees coverage in the caller, as long as `default` assigns the rest to `never` (see example). Without a literal code, a refactor breaks silently.
+
+### Procedure error — transport boundary
+
+**Who throws it:** procedures (tRPC handlers, route handlers, controllers).
+
+**How to represent it:** `TRPCError` (or the framework equivalent — `HTTPException` in FastAPI, `BadRequestException` in Nest).
+
+**The boundary is one-way.** The procedure knows Domain and maps code to HTTP status. Domain never imports `TRPCError` (hard rule 15).
+
+```ts
+// the procedure does the translation
+const result = await domain_createUserAuth({ ctx, input });
+if (!result.ok) {
+  switch (result.code) {
+    case "EMAIL_TAKEN":
+      throw new TRPCError({ code: "CONFLICT", message: "Email já cadastrado" });
+    case "WEAK_PASSWORD":
+      throw new TRPCError({ code: "BAD_REQUEST", message: "Senha fraca" });
+    default: {
+      const _exhaustive: never = result.code;
+      throw new Error(`unhandled domain code: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+### Infra error — external resource failure
+
+**Who throws it:** no one on purpose. It rises from the HTTP client, the ORM, or the queue.
+
+**How it propagates:**
+- In a **Task-like** context (Trigger.dev, BullMQ): let it rise. The orchestrator's retry policy handles it.
+- In a **Procedure-like** context: catch at the final boundary, log it, and map it to `INTERNAL_SERVER_ERROR`. Never leak the stack trace to the client.
+
+## Anti-patterns
+
+- ❌ **Domain imports `TRPCError`.** This couples Domain to the transport layer. Hard rule 15 checks it: `grep -rn "TRPCError" {{src-path}}/server/modules/**/domain/` must return 0.
+- ❌ **`throw new Error("generic string")` in domain code.** Without a literal code, the caller cannot handle the error specifically. Use `DomainError({ code: "..." as const })` instead.
+- ❌ **A generic try/catch around every `await`.** Typed errors beat a generic catch. Catch only when you will act on the error — map it, log it specifically, or apply a deliberate fallback. Otherwise let it rise.
+- ❌ **A procedure that returns `{ error: "..." }` instead of throwing.** This breaks the framework contract and forces the client to check `data.error` instead of using the standard mechanism.
+- ❌ **Mixing Domain error and Infra error in the same switch.** Domain code is closed — you know every case. Infra is open — the network can fail in N ways. Handle them separately.
+- ❌ **An "exhaustive" switch with no `never` branch.** When a new code is added to a Domain error, existing callers still compile. They silently ignore the new case. Hard rule 4 catches this only when `default` assigns the rest to `never`.
+
+## Decision flow
+
+```
+Where am I?
+├── domain function → Result<T, E> with a literal `as const` code
+├── procedure        → maps Domain code to TRPCError; lets Infra rise
+├── task             → carries idempotency; lets Infra rise (retry handles it)
+└── pure library      → Result<T, E> or DomainError with a discriminant code
+```

package/content/rubrics/failure-classification.md

@@ -0,0 +1,113 @@
+---
+type: rubric
+description: Routes a recognized failure to a guardrail, a procedure, a learning or to nothing.
+load: warm
+fires_on: op-call
+called_by: ["remediate", "reflect"]
+fires_when: 'a failure was recognized by an external signal and needs a destination'
+---
+
+# Rubric — failure classification (mechanizable → guardrail | mechanical → procedure | conceptual → learning | transient → nothing)
+
+> **In this file:** Entry gate (common to all three) · The four destinations · Decision flow · Anti-patterns
+
+> The CRITIC loop (`ops/remediate.md`) uses this rubric to remediate a failure recognized and recorded in the state store (`afm failures record`). The discriminator is **executable**. It is not a "feeling". Ancestor: CRITIC (arXiv 2305.11738) — recognize a failure only by external signal. Self-criticism without a tool degrades (PRINCIPLES #3).
+
+## Entry gate (common to all three)
+
+A failure **exists only** if an **external signal** recognized it.
+
+Signals: a test stays red (cap of §5.1 used up), or `tsc`/type-check returns non-zero.
+
+Other signals: a step command returns non-zero, or a hard rule breaks after the fact (trigger fired on the wrong side).
+
+A user's explicit correction is also a valid signal. "I think I made a mistake" is **not** a failure (CRITIC).
+
+Every failure becomes **one record** in the state store, written by `afm failures record --sig <signature>` (the recurrence key).
+
+## The four destinations
+
+### Mechanizable → `docs/guardrails/<slug>.md` (**takes precedence**)
+
+**Both conditions apply:** (1) a **0/1 check can detect the failure without judgment** — a lint rule, type-check, `grep`, test, or verification script. (2) It recurred (same promotion gate as the other destinations: `sig=` appears ≥2 times **OR** the user gave 1 explicit correction).
+
+**Why this destination takes precedence over procedure and learning.** The two destinations below produce **documents that inform a reader**. They depend on someone remembering to open the runbook or having read the lesson. A guardrail **does not depend on memory**. The gate fires on its own, in the development environment, before the error reaches review. When a failure fits both categories, choose guardrail. A repeated error fixed by non-mechanical analysis fits exactly this case: the analysis costs context every time, but the check costs effort only once.
+
+*Examples:* a broken boundary between modules (an import crossing a layer). A union of literals that does not break code that skips the new case. A required order in an internal DSL. An identifier outside the language required by rule 21.
+
+**Where the check lands — discovery is mandatory before any proposal.** Before you propose an installation, **read the verification surfaces the project already has**.
+
+Examples: linter config, `tsconfig`/type-check, CI steps, git hooks, test scripts.
+
+The proposal **extends an existing surface** — a new rule in the linter that already runs, a step in the workflow that already exists. **Introducing a new tool is a last resort.** State that choice explicitly in the proposal, with its cost. A guardrail that forces the operator to adopt an extra tool to catch one error is often more expensive than the error.
+
+**Installing writes outside `docs/`.** So it is a **proposal to the operator**, with surface options (linter · CI · git hook · free text).
+
+AFM materializes only the record at `docs/guardrails/<slug>.md`, from [`../templates/guardrail.template.md`](../templates/guardrail.template.md). The record holds `signal:`, `trigger:` once installed, and the chosen `surface:` — the same frontmatter keys the catalog uses.
+
+It also holds `origin: recurring-failure`, `Origin: sig=`, and the required **`## What would refute this`** (What would refute this) section.
+
+> **There is one procedure for installation**, in [`../../ops/rule.md` § Install the gate](../ops/rule.md) — it covers finding the existing surface, building the runner from the template, measuring HEAD before you turn it on, cost, doc-to-runner sync, and the record. This destination **composes** that procedure. It does not repeat it (rule 34).
+>
+> **`docs/guardrails/` has two origins, and this rubric produces one of them.** `origin: recurring-failure` starts here, from a recurring `sig=`. The other, `origin: hard-rule`, starts from a hard rule already written in `afm.md § 3` whose 0/1 trigger nobody ran. Same artifact, same burden of refutation, different entry point. These are not two families. Describing the same object in two vocabularies is the drift that rule 34 exists to prevent.
+
+> **Why the rationale is mandatory.** A future agent who finds the check inconvenient will want to loosen it. The `## What would refute this` section reverses that burden. Changing the guardrail requires **refuting the recorded reason**, not just claiming friction. This is the same discipline as "a broken rule is not a wrong rule" (`ops/reflect.md § 2`), applied to the gate instead of the text.
+
+### Mechanical → `docs/procedures/<slug>.md`
+
+**All three conditions apply:** (1) it is a **repeatable sequence of steps** with a 0/1 gate per step. (2) It recurred: `afm failures promotable` lists `sig=<hash>` with a count ≥2.
+
+A user correction also counts as recurrence, because the user is the oracle. (3) It has a **mechanical start trigger** ("when X, run this runbook").
+
+*Example:* the build breaks with `type:module` in tsdown, and this recurred. It became a runbook: "when you edit the emit step, do A, then B, then C, and check 0/1".
+
+### Conceptual → `docs/learnings/<slug>.md`
+
+**Condition:** the value is in the **cause** (a counterintuitive lesson), not in a mechanical sequence of steps. Same promotion gate (1 user correction OR ≥2 mechanical recurrences). It carries a `**Trigger:**` (trigger) by path, and `afm-pre-edit.sh` injects it for anyone who edits that area.
+*Example:* "I assumed the webhook arrives once. It arrived twice. Always handle it as idempotent." This became a learning with trigger `webhook`.
+
+### Transient → nothing (only evidence stays in the log)
+
+**Condition:** the retry in §5.1 resolved it (it never reached the terminal). Or no durable fix exists. Or the claim **does not survive a fix to its cause**.
+
+Example of the last case: "tool X is broken" hardens into a future refusal even after the tool is fixed — a negative filter.
+
+It stays as a line in `.afm-log-failures/`. It does **not** become an artifact. This is principle #5 (do not invent a constraint without a durable case) and the negative filter from Phase 4.
+
+## Decision flow
+
+```
+Failure recognized by an external signal? ── no → NOT a failure (CRITIC). Stop.
+   │ yes
+   ▼
+Record it in the state store (afm failures record, sig=).
+   │
+Resolved by the §5.1 retry / no durable antidote / claim dies when the cause is fixed?
+   ├── yes → TRANSIENT: stays as evidence, is not promoted.
+   └── no
+        │
+   1 user correction OR sig= recurred ≥2×?
+        ├── no → still only evidence (waits for recurrence).
+        └── yes
+             │
+        Detectable by a 0/1 check without judgment (lint/type/grep/test)?
+             ├── yes → GUARDRAIL (docs/guardrails/ + installation proposal)
+             └── no
+                  │
+             Repeatable step sequence with 0/1 gates + a start trigger?
+                  ├── yes → PROCEDURE (docs/procedures/)
+                  └── no → LEARNING  (docs/learnings/)
+```
+
+## Anti-patterns
+
+- ❌ **Recognizing a failure by self-judgment** (with no external signal). CRITIC: this degrades results.
+- ❌ **Promoting one mechanical failure** to an artifact (creates noise, a dead constraint). Wait for ≥2 recurrences, except a user correction, which counts as 1.
+- ❌ **Promoting a transient failure** resolved in §5.1. It never reaches the terminal, so it is not logged as a failure.
+- ❌ **Sending everything to `procedures/`**. A procedure is a *mechanical sequence*. A conceptual lesson is a `learning`.
+- ❌ **Sending everything to `learnings/`**. A repeatable runbook is a `procedure`.
+- ❌ **Writing a procedure or learning for what a check can catch** — this is the central anti-pattern of this rubric. A document that depends on memory loses to a gate that fires on its own. If the check exists, the destination is guardrail.
+- ❌ **Proposing a new tool without reading what the project already runs** — the existing surface comes first. A new tool is a last resort, and you must state its cost.
+- ❌ **A guardrail with no `## What would refute this`** — without the recorded burden of refutation, the next agent loosens the gate by claiming friction.
+- ❌ **Installing the guardrail alone** — installing writes outside `docs/`, so it is a proposal to the operator (#6).
+- ❌ **A procedure, learning, or guardrail with no source `sig=` cited** (traceability — hard rule 19 / R3).

package/content/rubrics/negative-filters.md

@@ -0,0 +1,38 @@
+---
+type: rubric
+description: Rejects what must not become a durable doc, because a false constraint is poison.
+load: warm
+fires_on: op-call
+called_by: ["remediate", "reconcile"]
+fires_when: 'something is about to become a durable doc'
+---
+
+# Rubric — negative-filters (what NOT to promote to durable doc)
+
+> This is a rejection checklist for the entry gate of `gotcha`/`reconcile`/`remediate`. It is the negative side of principle #5 ("do not invent"): **a false constraint is poison**. It is worse than no doc, because it hardens into a future wrong refusal or error. This applies from v3.1.0 (Phase 4 of the v3.2 initiative). Field evidence (ai-memory): in one real corpus, about 28% of pages were low-signal sessions that only polluted retrieval.
+
+## Reject (this does NOT become a gotcha, learning, rule, or procedure)
+
+| Anti-pattern | Why it is poison | What to do instead |
+|---|---|---|
+| **Negative claim about a tool** ("tool X is broken", "library Y does not work") | It hardens into a **fossil refusal**. After the tool is fixed, the doc still makes the next agent avoid it for no reason. | Record the concrete *workaround*, if it is durable. Do not record the verdict "it is broken". Remove the entry when the cause is fixed, because it is transient. |
+| **Transient failure** (fixed on retry, see § 5.1, a missing credential or binary at that moment, a setup state) | It becomes a **dead constraint**. The condition no longer exists, so the doc lies to the future reader. | Keep it as evidence in the state store, not as an artifact. Capture the *retry or fix pattern*, not the temporary failure. |
+| **One-off narrative** ("in this session I did A, B, C") | The timeline already lives in the event ledger and the session handoffs, in the state store. As a normative doc, it is only noise. | Use an episodic handoff, not a semantic doc. |
+| **User-visible status** ("the build passes now", "deploy ok") | This is a momentary state, not knowledge. | Use `_focus.md` (state) or a handoff. Do not use `gotcha` or `adr`. |
+| **Release marker or smoke test** ("v0.1.1 published", "echo ok") | This is operational, not a reusable lesson. | Use `notes` or a log. Never a rule or gotcha. |
+| **Vibe-rule with no trigger** (KISS, DRY treated as a "rule") | Without an executable 0/1 trigger, it is not a hard rule (see #3). | Record it as a principle in `afm.md § 1.3`, not in § 3. |
+
+## Promotion test (pass the gate IF)
+
+1. **Does it have a durable antidote?** It must be a concrete action that prevents the problem, not just a verdict.
+2. **Does the claim survive a fix to its cause?** If it "goes away when X is fixed", it is transient. Reject it.
+3. **Does another agent without my memory need this to avoid breaking something?** (#1 — otherwise it is memory or state, not doc.)
+4. **Did it happen ≥2 times?** Or is it a user correction? Or is it external SDK documentation? (#5 — otherwise it is evidence, not yet an artifact.)
+
+All four **yes** answers promote the item. Any structural **no** keeps it as evidence or state, not a durable doc.
+
+## Anti-patterns (of the gate itself)
+
+- ❌ **Do not promote out of caution** ("better to record it just in case"). A false constraint is worse than nothing (#5).
+- ❌ **Do not confuse transient with durable.** The test is always "does it survive a fix to its cause?".
+- ❌ **Do not treat every error as a gotcha.** A recognized error goes to the CRITIC loop (`remediate`), which applies this filter.

package/content/rubrics/solid-triggers.md

@@ -0,0 +1,121 @@
+---
+type: rubric
+description: Turns each SOLID principle into a mechanical trigger instead of folklore.
+load: warm
+fires_on: file-shape
+trigger_basename: 'utils.* helpers.* util.* helper.* *-utils.* *-helpers.* *_utils.* *_helpers.* *-manager.* *_manager.* manager.* *-and-*'
+trigger_any: yes
+trigger_grep: 'switch[[:space:]]*\([[:space:]]*[a-zA-Z_.]*(provider|adapter|driver|backend|strategy|channel|kind|variant)'
+fires_when: 'a file name collects unrelated responsibilities, or a provider `switch` is spread across files'
+---
+
+# Rubric — SOLID as a concrete trigger (not folklore)
+
+> **In this file:** SRP — Single Responsibility · OCP — Open/Closed: extend without modifying · LSP — Liskov Substitution: interchangeable implementations · ISP — Interface Segregation: minimal port · DIP — Dependency Inversion: domain does not know infra · Summary — what to ask when
+
+
+SOLID is easy to use as an argument and hard to use as a trigger. This rubric converts each principle into a **mechanical trigger** — when to apply it, the anti-pattern, an example.
+
+## SRP — Single Responsibility (already hard rule 5)
+
+**Trigger:** the file or function name has "and" / "manager" / "utils" / "helpers" without a domain prefix.
+
+**Apply:** split it. One file, one responsibility.
+
+Anti-pattern: `notification-and-billing.ts`, `user-manager.ts`, `helpers.ts`.
+
+## OCP — Open/Closed: extend without modifying
+
+**Trigger:** you are about to add a **new provider**. Examples: registry NPM/GitHub/Custom, storage S3/R2/MinIO, a new plan, a new payment method, a new notification channel.
+
+**Apply:** add a **new file** that implements a typed port. A central registry injects it. **No** `switch (provider)` spread across 2+ files.
+
+```ts
+// ✅ port + adapters + registry
+type RegistryAdapter = {
+  publish(tarball: Buffer, opts: PublishOpts): Promise<PublishResult>;
+};
+const adapters: Record<RegistryKind, RegistryAdapter> = {
+  npm:     npmAdapter,
+  github:  githubAdapter,
+  custom:  customAdapter,
+};
+
+// ❌ switch spread across 3 files
+function publish(kind: RegistryKind, ...) {
+  if (kind === "npm") { /* npm logic */ }
+  else if (kind === "github") { /* github logic */ }
+  // ... and again in other functions
+}
+```
+
+## LSP — Liskov Substitution: interchangeable implementations
+
+**Trigger:** you have **2+ implementations of the same port** (RegistryAdapter, StorageAdapter, EmailAdapter).
+
+**Apply:** all implementations return the **same classified result shape**. Adapter A must not return `null` on conflict while adapter B throws an exception.
+
+```ts
+// ✅ every implementation returns the same discriminated Result
+type PublishResult =
+  | { code: "PUBLISHED"; version: string }
+  | { code: "CONFLICT"; existingVersion: string }
+  | { code: "FAILED"; reason: string };
+
+// ❌ adapter A: returns null on conflict
+async function publishNpm(): Promise<{ version: string } | null> { ... }
+// ❌ adapter B: throws an exception
+async function publishGithub(): Promise<{ version: string }> {
+  throw new ConflictError(...);
+}
+```
+
+## ISP — Interface Segregation: minimal port
+
+**Trigger:** a domain function receives the whole `ctx: TRPCContext` but uses only `ctx.db` and `ctx.log`.
+
+**Apply:** declare only what you use: `ctx: Pick<TRPCContext, "db" | "log">`. Otherwise the test must mock everything.
+
+```ts
+// ✅ minimal port
+async function domain_createSessionAuth({
+  ctx,
+  input,
+}: {
+  ctx: Pick<TRPCContext, "db" | "log">;
+  input: { userId: string };
+}): Promise<Result<IssuedSession, "USER_NOT_FOUND">> { ... }
+
+// ❌ whole ctx, hides the real dependency
+async function domain_createSessionAuth({ ctx, input }: DomainInput<...>) {
+  // uses only ctx.db, but the test must mock ctx.user, ctx.session, ctx.headers, ...
+}
+```
+
+## DIP — Dependency Inversion: domain does not know infra
+
+**Trigger:** a domain function or pure lib is about to import something from a framework (`TRPCError`, `req.headers`, a direct ORM client with no abstraction).
+
+**Apply:** invert the direction. Domain defines the interface. Infra implements it. Domain imports only from layers below it (pure lib, types).
+
+```
+✅ correct direction (all paths rooted at {{src-path}}/):
+  app/   →   server/   →   server/modules/X/   →   domain/X/   →   lib/   →   types
+  
+  Each layer knows the layer below it, never the layer above it.
+
+❌ common inversions:
+  - {{src-path}}/domain/X/ importing TRPCError (transport leaks up into domain)
+  - {{src-path}}/lib/Y/ importing from server (lib is no longer publishable)
+  - {{src-path}}/lib/Y/ importing an ORM type (couples lib to infra)
+```
+
+## Summary — what to ask when
+
+| Symptom | Principle | Fix |
+| --- | --- | --- |
+| File is growing, doing 2+ things | SRP | Split it |
+| You are adding a 4th variant of something | OCP | Port + adapters, not a switch |
+| 2 implementations of the same thing return different shapes | LSP | Standardize on a discriminated Result |
+| Function receives a giant ctx but uses 2 fields | ISP | Pick / minimal interface |
+| Domain wants to import something from above | DIP | Invert: domain defines, infra implements |

package/content/rubrics/template-vs-streaming-precedence.md

@@ -0,0 +1,34 @@
+---
+type: rubric
+description: Picks one source when the frozen template and the streaming learning disagree.
+load: warm
+fires_on: op-call
+called_by: ["export-template", "reconcile"]
+fires_when: 'frozen template knowledge and a streaming learning are in conflict'
+---
+
+# Rubric — frozen template (offline) vs. streaming learning (online): precedence, never sum
+
+> **Load-bearing finding from AWM (arXiv:2409.07429):** offline knowledge (the frozen architectural template from `export-template`) and online knowledge (the learning that `reconcile`/`restructure` accumulate in streaming during the project life) are **non-additive**. Combining the two hurts. The combined result falls *between* the two and matches neither. AFM has both layers. AFM needs an explicit rule of **precedence + tombstone**. AFM must never merge the two.
+
+The single rule: when offline and online conflict, **pick ONE and tombstone the other**. Keep the provenance. Never keep both as a "sum". Never merge the content.
+
+## Decision table
+
+| Situation | Rule |
+| --- | --- |
+| The project has a **template origin** (`docs/.template` was the seed) AND `reconcile` proposes a rule or gotcha that **contradicts** an artifact inherited from the template | **Streaming wins locally.** Apply the new rule or gotcha. Mark the inherited artifact with `*(overridden — see reconcile NNN / cycle NNN)*`. **Do not merge** the two. Non-additivity means mixing is worse than either alone. |
+| The **same knowledge** exists in the frozen template **and** in a streaming learning (a duplicate, not a conflict) | **Pick ONE** (usually the more recent, local copy). Tombstone the other. Do not keep both copies as a "sum". That creates the inflation `diagnose A6` later flags. |
+| `export-template` is about to **freeze** a project that already accumulated streaming learnings | Consolidate the streaming learnings **via `afm generalize` BEFORE** the export. They become part of the frozen template (offline), not a parallel layer. This avoids freezing half the knowledge and leaving the other half to collide with the consumer's own reconcile later. |
+
+## Why not merge
+
+- **AWM measured this:** combined offline and online knowledge lands *between* the two and matches neither. Silent fusion is the worst outcome.
+- **Tombstone, not deletion:** precedence preserves provenance. The losing artifact becomes a note. It does not disappear. This matches the discipline of `generalize` (a merged gotcha becomes a tombstone) and principle #6 (deletion is a bright line).
+- **`reflect` and `generalize` stay valid** *within* each layer. This rubric forbids only mixing **between** layers without deciding precedence.
+
+## Counter-examples
+
+- ❌ Do not keep the inherited template rule **and** the new reconcile rule that contradicts it, hoping "both count". This violates non-additivity. Decide the precedence instead.
+- ❌ Do not let `export-template` freeze a project with pending streaming learnings unconsolidated. The consumer then inherits a partial layer that will fight its own reconcile.
+- ❌ Do not merge the text of both into a third "combined" version. That is exactly the *between-the-two* result AWM showed to be worse.

package/content/rubrics/validation-boundary.md

@@ -0,0 +1,94 @@
+---
+type: rubric
+description: Says where the parser goes, so the domain never validates its own input.
+load: warm
+fires_on: file-shape
+trigger_path: '*/domain/*'
+trigger_grep: '(from[[:space:]]+[''"]zod[''"]|require\([''"]zod[''"]\)|\bz\.(object|string|number|enum|array)\()'
+fires_when: 'a schema parser is used inside a `domain/` path'
+---
+
+# Rubric — where Zod (or the parser) goes
+
+## The single rule
+
+The schema parser (Zod or the stack equivalent) **validates in exactly 2 places**:
+
+1. **Procedure input / transport handler** — request to validated type.
+2. **External payload parsing** — webhook, crawled source, env var, queue message, DB JSON with unknown shape.
+
+**Domain receives an already validated, typed shape.** Pure lib code does too. Re-validating inside domain "for safety" duplicates the schema's source of truth.
+
+## Why this rule exists
+
+- **Validating twice wastes effort** (CPU cost, plus a schema kept in 2 places).
+- **Domain tests logic, not parsing.** A mock input with the wrong type does not compile. TS is already the barrier.
+- **Schema lives near the boundary** where external data arrives, not wherever "seemed like a good idea."
+
+## Examples
+
+### ✅ Correct: procedure validates input before it calls domain
+
+```ts
+const router_apps = router({
+  procedure_createApps: publicProcedure
+    .input(z.object({
+      packageName: z.string().min(1),
+      schemaUrl: z.string().url(),
+    }))
+    .mutation(async ({ ctx, input }) => {
+      // input is already { packageName: string; schemaUrl: string }
+      const result = await domain_createApps({ ctx, input });
+      // ...
+    }),
+});
+```
+
+### ✅ Correct: webhook handler validates the external payload
+
+```ts
+export async function POST(req: Request) {
+  const raw = await req.text();
+  const event = stripe_verifyWebhook(raw, signature);  // validates the signature
+  const payload = zStripeEvent.parse(event);            // validates the shape
+  await domain_handleStripeEventBillings({ ctx, input: payload });
+}
+```
+
+### ❌ Wrong: domain re-validates "for safety"
+
+```ts
+async function domain_createApps({ ctx, input }: DomainInput<{ packageName: string; schemaUrl: string }>) {
+  // ❌ Wrong: the procedure already validated this. It adds noise and duplicates the schema.
+  const validated = z.object({
+    packageName: z.string().min(1),
+    schemaUrl: z.string().url(),
+  }).parse(input);
+}
+```
+
+### ✅ Correct: pure lib receives the shape and does not validate
+
+```ts
+// lib/sdk-generator/index.ts
+export function generateSdk({ schema, options }: { schema: OpenApiV3; options: GenOpts }): SdkFiles {
+  // No z.parse call here. The schema arrives already validated from the caller.
+  // If the caller passed the wrong shape, that is the caller's bug, not something the lib must guard against.
+}
+```
+
+## When "validate at the boundary" grows
+
+Suppose 6 similar procedures all validate the same `apps` shape.
+
+- Extract the schema to `{{src-path}}/server/modules/apps/schemas.ts`.
+- Each procedure imports it: `.input(zCreateAppsInput)`.
+- The schema is still declared **once**, but reused across procedures.
+- This stays a boundary pattern. Only the duplication is gone.
+
+## More anti-patterns
+
+- ❌ Wrong: validating input inside a domain function "for DI" or "for defense in depth." TS plus the boundary schema already cover this.
+- ❌ Wrong: declaring a schema inside the domain file. Move it to `schemas.ts` or `*.types.ts` in the module (hard rule 7).
+- ❌ Wrong: `z.unknown().parse(...)` to dodge a type. This validates nothing and gives false safety. Use a real `z.object({...})` or accept the upstream type.
+- ❌ Wrong: validating env vars with scattered `process.env.X || throw` calls. Centralize this in `{{src-path}}/server/env.ts` with Zod, and validate once at boot.

package/content/rubrics/when-to-create-dsl.md

@@ -0,0 +1,65 @@
+---
+type: rubric
+description: Decides when a DSL is worth suggesting, and when it is premature.
+load: warm
+fires_on: repo-shape
+detector: dsl
+fires_when: 'three or more call sites repeat one fixed-order sequence'
+---
+
+# Rubric — when to create a DSL (suggest, do not build)
+
+> DSL here means any domain mini-language that collapses repeated boilerplate of primitive calls: a fluent builder, a combinator pipeline, a declarative object that gets interpreted, or a parsed language. **DSL-first is the complement of the Rule of Three, not the opposite of KISS.** The agent does not abstract early. But when primitive boilerplate scales AND has grammar, a DSL pays for itself. The agent **suggests** (proposes and sketches). The agent **does not build alone** (hard rule 11 — a DSL is a first-class layer or abstraction, so it stops and asks).
+
+## Binary decision
+
+**Suggest a DSL only when BOTH signals are true:**
+
+- ✅ **Repetition (Rule of Three of sequence):** 3 or more call sites repeat the same sequence of N or more primitive calls, in fixed order. This is not 3 loose calls. The *sequence* itself repeats. Only the parameters vary, not the structure.
+- ✅ **Boilerplate dominates the intent (ratio):** at these sites, most lines are mechanical wiring, setup, or glue, not real business logic. The reader cannot see *what* the code wants through *how* it wires the primitives together.
+
+**A third condition tells a DSL apart from "extract a function":**
+
+- ✅ **Reusable grammar exists** — composition, required ordering, branching, or chaining that repeats. This is what makes a DSL pay more than a helper. Without grammar (just "call 5 functions in the same fixed sequence"), **a named helper wins.** That case is not a DSL.
+
+**Do NOT suggest a DSL when:**
+
+- ❌ **Fewer than 3 repeated sequences.** The Rule of Three has not been met. Wait for the third case (YAGNI).
+- ❌ **A simple helper or builder already collapses the boilerplate.** KISS beats DSL here. A named function (`stripe_createCheckoutSession`) or a one-level builder wins over a mini-language. Use a DSL only when the helper cannot capture the grammar.
+- ❌ **The "boilerplate" is real per-site logic.** Genuine variation between sites is not boilerplate. Abstracting it would hide a difference that matters.
+- ❌ **"This will scale" or "we can parametrize everything."** This is YAGNI. Do not build a speculative DSL for the general case before 3 real cases exist.
+
+## Why these rules
+
+- **Both signals together, not one.** Repetition without dominant boilerplate: a helper solves it. High boilerplate without repetition (1 site): it is just a large function — split it or inline it. A DSL is expensive (new layer, indirection, a learning curve, debugging through the abstraction). It pays off only at the intersection of both signals.
+- **Grammar is the DSL-versus-helper discriminator.** Extracting a function removes duplication. A DSL gives you a *language* to express the intent. If there is nothing to "compose," a function is enough, and cheaper.
+- **Suggest, do not build (rule 11 / autonomy principle 6, bright line d).** Creating a DSL introduces a first-class layer or abstraction. This is a load-bearing architectural decision. The agent brings the proposal, with an API sketch and a candidate ADR. The architecture owner decides. Building a DSL on its own would cross the bright line.
+
+## Form — pick the lightest one that removes the boilerplate (KISS inside the DSL)
+
+In increasing order of cost — **stop at the first form that captures the grammar:**
+
+1. **Fluent builder / factory function** — simple chaining (`q().where().limit()`). This is the cheapest form. It covers most cases.
+
+   **Purity:** chain methods only assemble immutable data. IO stays in one terminal call (`.exec()` or `.run()`). A side effect in the middle of the chain forces you to mock the world to test a pure rule. This is the "mock that simulates more than needed" smell (see § 5). **Hard rule 7** separates pure domain from glue for this exact reason. A builder placed outside `{{src-path}}/<domain>/` escapes that separation.
+
+   Counter-example: `checkout().comValor(v).cobrarNoStripe().comDesconto(d)`. Here `cobrarNoStripe()` sits mid-chain and mixes IO with data assembly.
+2. **Combinators / pipeline** — small functions that compose (`pipe(parse, validate, persist)`). Use when the grammar is composition.
+3. **Declarative interpreted object** — data-driven config that a runner walks through. Use when the "language" is a data structure.
+4. **Parsed mini-language** (string to AST to exec) — **last resort**, rarely justified in a product app. It needs a parser, error handling, and tests for the parser itself. Use it only when the 3 forms above genuinely cannot express the grammar.
+
+## Before proposing — self-check (verification corollary 6)
+
+1. Do the 3 sites repeat the same *sequence*, or do they just use the same primitives in different orders? (Different orders mean it is not one DSL.)
+2. Would a one-level helper collapse 80% of the boilerplate? If yes, propose the helper, not the DSL.
+3. Does the proposed DSL hide a real difference between the sites? If yes, it will leak — rethink the boundary.
+4. Which form above is the lightest one that captures the grammar? Do not propose a parser if a builder solves it.
+5. Is there a required order between chain steps? If yes, the proposed form must reject the wrong order at **compile time**, not a runtime `throw`. Use type-state: each method returns a type that exposes only the next legal methods. **If type-state gets expensive, do not propose the builder.** A single function with all required arguments solves the same problem without the technique.
+
+## Counter-examples
+
+- ❌ Building a standalone query DSL at the 2nd call site — the Rule of Three has not been met. Wait for the third case, or use a helper.
+- ❌ Proposing a parsed mini-language for 3 sequences that a 20-line fluent builder would solve — too expensive a form (use level 1 instead).
+- ❌ Calling 3 handlers that check different things "boilerplate" — this is per-site logic, not repeated wiring. A DSL would hide the difference.
+- ❌ Building the DSL alone because "it is obviously needed" — this is rule 11. Propose it, sketch the API, and open a candidate ADR. The human approves the new layer.
+- ❌ A DSL for the general case ("supports any future provider") built from 3 real providers — this is YAGNI. Model the 3 real cases and generalize when a 4th case actually diverges.