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

package/content/questions/init.questions.yaml

@@ -0,0 +1,41 @@
+questions:
+  - id: harnesses
+    prompt: Which harnesses should the instruction files of this project cover?
+    header: Harnesses
+    multiSelect: true
+    recommended: [claude-code]
+    options:
+      - label: claude-code
+        description: Writes a CLAUDE.md stub that imports AGENTS.md.
+      - label: opencode
+        description: Reads AGENTS.md itself, so no stub is written.
+      - label: agy
+        description: Writes a GEMINI.md stub that imports AGENTS.md.
+      - label: git
+        description: Git hooks only; no instruction file is needed.
+  - id: app-language
+    prompt: In which language does this product show its own users their strings?
+    header: App language
+    recommended: Decide later
+    options:
+      - label: English
+        description: User-facing strings are in English.
+      - label: Portuguese
+        description: User-facing strings are in Portuguese.
+      - label: Spanish
+        description: User-facing strings are in Spanish.
+      - label: Decide later
+        description: Records [TBD] in the PRD; the language migration stops and asks.
+  - id: artifact-language
+    prompt: In which language are the artifacts of this project written (docs, code comments, test names)?
+    header: Artifacts
+    recommended: en
+    options:
+      - label: en
+        description: English, the default. Nothing is recorded.
+      - label: pt-BR
+        description: Recorded with afm config set language.artifacts pt-BR; the gate skips the English-prose rules.
+      - label: es
+        description: Recorded with afm config set language.artifacts es; the gate skips the English-prose rules.
+      - label: other
+        description: Another tag. Init prints the command to run with the tag the owner names.

package/content/questions/obligations.questions.yaml

@@ -0,0 +1,17 @@
+questions:
+  - id: existing-root
+    prompt: This folder already has an obligations root. What should the mapping do?
+    header: Root
+    options:
+      - label: extend
+        description: Keep the existing entries and add or update only what the contract changes.
+      - label: stop
+        description: Change nothing; the existing root stays as it is.
+  - id: install
+    prompt: The map passes the lint. Install the git hooks for every repository below this folder now?
+    header: Install
+    options:
+      - label: install-now
+        description: Adds one includeIf entry to the global git config; every repository below the folder runs the checks, then its own hooks.
+      - label: later
+        description: Nothing is enforced until the operator runs afm obligations install.

package/content/questions/plan.questions.yaml

@@ -0,0 +1,14 @@
+questions:
+  - id: open-markers
+    prompt: The spec has open NEEDS CLARIFICATION markers. How should the plan proceed?
+    header: Markers
+    recommended: clarify-first
+    options:
+      - label: clarify-first
+        description: Run the structured clarify scan first. It records dated answers in the spec, then planning resumes.
+      - label: resolve-inline
+        description: Quick fallback. Answer each marker in free text now; no Clarifications section is written.
+      - label: keep-going
+        description: Not recommended. The plan inherits the markers and the tasks step refuses to run until they are resolved.
+      - label: cancel
+        description: Go back to the spec and plan nothing yet.

package/content/questions/refactor.questions.yaml

@@ -0,0 +1,23 @@
+questions:
+  - id: adr
+    prompt: Which of the inferred decisions still load-bear today and become a retroactive ADR? Would someone need a doc to explain why if it were swapped tomorrow?
+    header: ADRs
+    recommended: None
+    options:
+      - label: None
+        description: No retroactive ADR; a dead decision never becomes one later.
+      - label: Some
+        description: The operator names the decisions; each becomes an accepted retroactive ADR.
+      - label: All
+        description: Every listed candidate becomes an accepted retroactive ADR.
+  - id: gotcha-seeds
+    prompt: Which gotcha seeds of the detected stacks has the team here already been bitten by? Seeds are candidates, not active entries.
+    header: Gotchas
+    recommended: None
+    options:
+      - label: None
+        description: No seed is activated.
+      - label: Some
+        description: The operator names the seeds; each becomes its own gotcha file.
+      - label: All
+        description: Every seed is confirmed as already lived here and becomes its own gotcha file.

package/content/questions/reflect.questions.yaml

@@ -0,0 +1,13 @@
+# One question per refinement of a doc that guided badly in the session:
+#   afm ask reflect --scope <item-slug>
+questions:
+  - id: refinement
+    prompt: Refine this doc as proposed?
+    header: Refinement
+    options:
+      - label: Apply
+        description: Apply the refinement (rewrite, added trigger, or disambiguation) exactly as itemized.
+      - label: Report only
+        description: Do not edit the doc; keep the finding as a suggestion in the report.
+      - label: Skip
+        description: Reject it; the report records the rejection so the finding is not proposed again without new evidence.

package/content/questions/remediate.questions.yaml

@@ -0,0 +1,27 @@
+# One pair of questions per recurring failure (the scope is the sig= as a slug):
+#   afm ask remediate --scope <sig>
+questions:
+  - id: artifact
+    prompt: Which durable artifact should this failure become?
+    header: Artifact
+    options:
+      - label: Guardrail
+        description: A check a command can run with no judgment; takes precedence over the other two.
+      - label: Procedure
+        description: A repeatable sequence of steps with a 0/1 gate per step and a start trigger.
+      - label: Learning
+        description: A conceptual lesson whose value is in its cause.
+      - label: Not now
+        description: Leave the failure open; it waits for recurrence or for a user correction.
+  - id: surface
+    prompt: For a guardrail, where is the check installed?
+    header: Surface
+    options:
+      - label: Linter
+        description: The linter config the project already runs.
+      - label: CI
+        description: The CI workflow the project already runs.
+      - label: Git hook
+        description: A git hook (afm install git runs the gate there).
+      - label: Not a guardrail
+        description: The artifact is a procedure, a learning or nothing, so no check is installed.

package/content/questions/restructure.questions.yaml

@@ -0,0 +1,15 @@
+# One question per staleness, findability or dead-gotcha finding:
+#   afm ask restructure --scope <item-slug>
+questions:
+  - id: finding
+    prompt: What should be done with this finding?
+    header: Finding
+    options:
+      - label: Update the doc
+        description: Read the current code, then update the stale doc (a proposal, never an auto-fix).
+      - label: Relocate
+        description: Move the information to where it is expected, or add a pointer there; a loading-strategy ADR for a tiering finding.
+      - label: Archive
+        description: Comment the dead entry out as a tombstone; nothing is deleted.
+      - label: Leave as is
+        description: The doc is still right; the report records the review.

package/content/questions/rf-mapping.questions.yaml

@@ -0,0 +1,12 @@
+questions:
+  - id: rf
+    prompt: Which PRD requirement does this user story implement?
+    header: RF mapping
+    recommended: New RF
+    options:
+      - label: New RF
+        description: Drafts the next RF in the PRD from the story.
+      - label: Existing RF
+        description: The operator names the number or the title.
+      - label: Not yet
+        description: Records [TBD]; decided later.

package/content/questions/rule-scope.questions.yaml

@@ -0,0 +1,12 @@
+questions:
+  - id: scope
+    prompt: Where does the rule enter?
+    header: Rule scope
+    recommended: forward-only
+    options:
+      - label: universal
+        description: Section 3, applies to all code including legacy. May produce a large cleanup change.
+      - label: forward-only
+        description: Section 3.1, new code and files touched from today on. Legacy debt is tracked, not blocking.
+      - label: cancel
+        description: Nothing is written; the decision needs more thought.

package/content/questions/rule.questions.yaml

@@ -0,0 +1,12 @@
+questions:
+  - id: surface
+    prompt: Where does this trigger run?
+    header: Surface
+    recommended: pre-commit
+    options:
+      - label: pre-commit
+        description: Blocks every commit, including one made outside an agent session. Costs the trigger's runtime on each commit.
+      - label: ci
+        description: Blocks the merge, not the local commit. Only honest when the project already has CI.
+      - label: agent
+        description: Stays in the doc and runs by judgment. Honest for a heuristic trigger, not for a precise one nobody automated.

package/content/questions/specify.questions.yaml

@@ -0,0 +1,23 @@
+questions:
+  - id: heuristic
+    prompt: The change is borderline for a feature folder. Open one, or go straight to the loop?
+    header: Feature?
+    recommended: open-feature
+    options:
+      - label: open-feature
+        description: Create docs/features/NNN-slug with a spec, then plan and tasks. Best when the change spans files or has unknowns.
+      - label: straight-to-loop
+        description: Skip the folder and run the RED, GREEN, REFACTOR, COMMIT loop of core/afm.md section 2 once.
+  - id: us-link
+    prompt: Which user story does this feature correspond to?
+    header: Linked US
+    recommended: candidate
+    options:
+      - label: candidate
+        description: The story the scan matched in docs/ust.md. Confirms the link.
+      - label: other-existing
+        description: A different existing story. The operator gives its number.
+      - label: create-first
+        description: Write a new story with a Gherkin criterion in docs/ust.md before the spec.
+      - label: later
+        description: No story yet. The spec records a NEEDS CLARIFICATION marker to link it.

package/content/questions/update-artifacts.questions.yaml

@@ -0,0 +1,10 @@
+questions:
+  - id: artifact-language
+    prompt: Migrate the artifacts (docs, code comments, test names) to English?
+    header: Artifacts
+    recommended: Migrate to English
+    options:
+      - label: Migrate to English
+        description: Artifacts move to English and stop paying the token cost of a second language in every context load.
+      - label: Keep the current language
+        description: Nothing moves. The choice is recorded so the next update does not ask again.

package/content/questions/update-strings.questions.yaml

@@ -0,0 +1,14 @@
+questions:
+  - id: app-language
+    prompt: In which language does this product show its own users their strings? The PRD records none yet.
+    header: App language
+    recommended: Decide later
+    options:
+      - label: English
+        description: User-facing strings are English; nothing is excluded from the artifact migration.
+      - label: Portuguese
+        description: User-facing strings are Portuguese and stay out of the migration.
+      - label: Spanish
+        description: User-facing strings are Spanish and stay out of the migration.
+      - label: Decide later
+        description: Records [TBD]; the artifact language migration does not run until it is set.

package/content/questions/update.questions.yaml

@@ -0,0 +1,10 @@
+questions:
+  - id: apply
+    prompt: Apply the migrations the dry run listed and move the version pin?
+    header: Update
+    recommended: Apply
+    options:
+      - label: Apply
+        description: Applies every migration in order, proves each one, then moves the pin. A failed migration keeps the pin where it was.
+      - label: Not now
+        description: Nothing is applied and the pin stays; the dry run can be repeated later.

package/content/questions/verify.questions.yaml

@@ -0,0 +1,9 @@
+questions:
+  - id: reviewed
+    prompt: Did you read this document yourself and stand behind it?
+    header: Reviewed
+    options:
+      - label: Yes, I read it
+        description: Stamps the verification under your name.
+      - label: No
+        description: Nothing is stamped; a stamp asserts that a person read the content.

package/content/roles/executor.md

@@ -0,0 +1,18 @@
+---
+role: executor
+description: Writer of one bounded change. Makes the edit its brief names, test first, inside the files the brief grants, and reports what changed; dispatched with a brief.
+capabilities: read, search, write, shell
+---
+You are an executor. The message that dispatched you is your brief: follow it.
+
+You make the change the brief names, and only that change.
+
+- Touch only the files the brief grants. Another file you need is a question for the caller, not an edit.
+- Test first: a failing test (or a type that does not compile yet), then the smallest change that
+  makes it pass, then the refactor. Run the tests and the type check before you report.
+- Reuse what exists before you add a helper. Add no option, hook or abstraction the brief did not ask for.
+- Never print, write or commit a secret.
+- Never push, and never commit unless the brief says to.
+
+Reply with the files you changed, the checks you ran with their exact result, and anything you left
+undone or doubt.

package/content/roles/explorer.md

@@ -0,0 +1,22 @@
+---
+role: explorer
+description: Read-only investigator. Answers one question from the code, the docs or the web, cites what it read, and changes nothing; dispatched with a brief.
+steps: 60
+capabilities: read, search, web
+mcpTools: approve, config, detect, doctor, failures_promotable, feature_lint, feature_status, gate, index, lang, next_id, path, policy, preflight, read, sessions, sessions_signals, version
+cliDoor: false
+---
+You are an explorer. The message that dispatched you is your brief: follow it.
+
+You only read. You never edit a file, run a command that changes state, or commit.
+
+- Read only what the question needs: the sections you are about to use, not whole trees.
+- Cite every claim: a path with the line, or a source URL with the literal quote. A claim with no
+  citation is a guess, and you label it a guess.
+- Never invent a path, a line number, a URL or a quote. If you did not read it, you do not cite it.
+- Say what you could not find. Absence is a result.
+
+You have at most 60 steps. Write the answer whole, not a step at a time. If you run out, reply with
+what you have and what is still missing.
+
+Reply with the answer first, then the evidence, then the gaps.

package/content/roles/reviewer.md

@@ -0,0 +1,23 @@
+---
+role: reviewer
+description: Blind auditor. Checks one piece of work it did not write against its sources and rules, and returns a verdict with evidence; dispatched with a brief.
+capabilities: read, search, web
+mcpTools: approve, config, detect, doctor, failures_promotable, feature_lint, feature_status, gate, index, lang, next_id, path, policy, preflight, read, sessions, sessions_signals, version
+cliDoor: false
+---
+You are a reviewer. The message that dispatched you is your brief: follow it.
+
+You audit work you did not write. You read it and the sources or rules it answers to. You never
+write a fix.
+
+- Judge against the rules and sources the brief names, not against taste.
+- Verify, do not trust: open each cited path, line or quote and confirm it says what the work claims.
+- Run the checks the brief lists that the `afm` tools offer (the gate, the doctor, the index), alone and one
+  at a time, and report their exact output. You have no shell: a check that needs one is a check you did
+  not run, and you say so.
+- Report a finding only with its evidence: the path and line, the rule it breaks, and the concrete
+  input or state that fails. A suspicion with no evidence is not a finding.
+- Say what you did not check.
+
+End with one verdict line: PASS when no finding stands, FAIL otherwise, followed by the findings
+most severe first.

package/content/rubrics/enum-vs-union-vs-branded.md

@@ -0,0 +1,40 @@
+---
+type: rubric
+description: Chooses between an ORM enum, a literal union, a branded type and a parser schema.
+load: warm
+fires_on: file-shape
+trigger_ext: '.ts .tsx'
+trigger_grep: '(^[[:space:]]*(export[[:space:]]+)?(const[[:space:]]+)?enum[[:space:]]+[A-Za-z_]|\([[:space:]]*[a-zA-Z_][A-Za-z0-9_]*:[[:space:]]*string[[:space:]]*,[[:space:]]*[a-zA-Z_][A-Za-z0-9_]*:[[:space:]]*string[[:space:]]*[,)])'
+fires_when: 'a TS `enum` is declared, or a signature takes two adjacent `string` parameters'
+---
+
+# Rubric — enum vs literal union vs branded type vs Zod schema
+
+## Decision table
+
+| Case | Choice | Anti-pattern |
+| --- | --- | --- |
+| Value exists in the DB (status, role, plan) | **ORM enum** (Prisma enum, etc) — the only path that survives `generate` | Pure TS enum that mirrors the ORM enum — duplication |
+| ≤ 5 closed values, used only in code | **Literal union** (`"latest" \| "next" \| "beta"`) | Pure TS enum — produces transpiled waste, not tree-shakeable |
+| Open string with a rule (user input, free dist-tag) | **Parser schema** (Zod) + parse at the boundary | Validation inside the domain (violates hard rule 16) |
+| Primitive with a semantic invariant (sha256, userId ≠ sessionId, currency cents) | **Branded type** (`type Hash = string & { __brand: "Hash" }`) | Raw `string` — loses the check at the call site |
+| Opaque value from an external SDK (Stripe price id) | SDK type + Zod at the boundary | Re-type as branded — duplicates the SDK |
+
+## When a branded type wins
+
+- A function takes two strings with different meanings (`copy(from: string, to: string)`). A branded type stops you from swapping the order.
+- Hash, ID, currency in cents, timestamp in ms vs s. A branded type makes the conversion explicit.
+- Different domain IDs (UserId vs SessionId vs OrgId). A branded type stops you from passing a UserId where the code asked for an OrgId.
+
+## When a branded type does not pay off
+
+- A string that goes to a log, a UI, or the network. The reader gains nothing.
+- The type already comes from the SDK as an opaque string. Re-typing it just duplicates the SDK.
+- The function has one parameter. There is no ambiguity to resolve.
+
+## Anti-examples
+
+- ❌ `enum Plan { FREE = "FREE", PRO = "PRO" }` in TS when Prisma already has `enum Plan { FREE, PRO }`. Use the Prisma one directly.
+- ❌ `type DistTag = string` that accepts anything. Use a literal union if the set is closed, or Zod if it is open with a rule.
+- ❌ `copy(src: string, dst: string)` called by mistake as `copy(dst, src)`. Branded `SrcPath` and `DstPath` types fix this.
+- ❌ Branding every `string` "for consistency". This adds overhead with no check gained.

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,111 @@
+---
+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)
+
+> 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).