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

package/content/code-style/trpc-v11/error-boundary.md

@@ -0,0 +1,51 @@
+---
+type: code-style
+description: 'Proposes a path-bound grep that verifies TRPCError never appears in the domain layer, for a project that keeps domain code under a fixed path.'
+load: cold
+stack: trpc-v11
+concern: error-boundary
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trpc/server")' package.json >/dev/null 2>&1; else grep -q '"@trpc/server"' package.json 2>/dev/null; fi
+---
+
+# Code style — tRPC v11 error-boundary check
+
+> The principle behind this — a transport error type must not reach the domain layer — is a
+> genuine tRPC layering fact, kept in `modules/trpc-v11/rules.patch.md` as a §1.3 principle. What
+> is a **proposal** here, not a fact, is the concrete mechanical check below: it is bound to one
+> house layout (`{{src-path}}/server/modules/*/domain/`), and a project that lays out its domain
+> code differently needs a different glob, or none at all.
+
+## The convention
+
+Add a hard rule to `docs/afm.md` §3 that mechanically enforces the principle, verified by:
+
+```sh
+grep -rn "TRPCError" {{src-path}}/server/modules/*/domain/
+```
+
+Zero results required. `TRPCError` appearing anywhere under a project's domain path means a
+transport type leaked past the procedure boundary.
+
+## Why this works
+
+Review alone misses this reliably — `TRPCError` is a normal, typed import, and nothing about
+using it inside a domain function raises a compiler error or a lint warning on its own; the
+violation is architectural, not syntactic. A path-bound grep turns "domain must not import
+TRPCError" from a principle a reviewer has to remember into a check a hook runs on every commit.
+
+## The trade-off
+
+The check is only as good as the glob. A monorepo with more than one domain root, a project mid
+-migration to a new folder layout, or one that does not separate "domain" into its own directory
+at all gets a check that is silently vacuous (matches nothing, so it always passes) rather than
+one that fails loudly. Confirm the glob actually matches existing domain files before trusting a
+green result — an empty match set means either the boundary holds, or the path is wrong.
+
+## If the operator accepts this
+
+Materialize the hard rule into `docs/afm.md` §3 with `{{src-path}}` resolved to the project's
+actual domain-layer root (fill the placeholder at bootstrap, the way `docs/afm.md` fills every
+other `{{src-path}}` site). Do not paste the grep with the placeholder left in — a rule with an
+unresolved `{{src-path}}` runs against a literal, nonexistent directory and passes vacuously on
+every project.

package/content/code-style/trpc-v11/file-size.md

@@ -0,0 +1,44 @@
+---
+type: code-style
+description: 'Proposes exactly one domain function per file, with shared constants and schemas factored to a sibling file.'
+load: cold
+stack: trpc-v11
+concern: file-size
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trpc/server")' package.json >/dev/null 2>&1; else grep -q '"@trpc/server"' package.json 2>/dev/null; fi
+---
+
+# Code style — tRPC v11 domain file granularity
+
+> This is a **proposal**, not a fact about tRPC. Materialize it into `docs/ach.md` only if the
+> operator accepts it — item by item, at bootstrap. Nothing here is `(mandatory)`.
+
+## The convention
+
+One domain function per file. Shared constants, Zod schemas, or types that more than one domain
+function needs move to `<name>.ts` in the module — never added as a second export in a domain
+file.
+
+## Why this works
+
+A domain file's name (`<action>-<module>.ts`) then names exactly one thing, so `git blame` and
+`git log --follow` on that file tell the history of one business rule, not several interleaved
+ones. It also keeps a domain file's diff small and reviewable — a change to one rule cannot
+accidentally touch the body of an unrelated one two exports down.
+
+## The trade-off
+
+Two domain functions that are always read and changed together (a `create` and its matching
+`validate`) end up in two files a reviewer has to open side by side anyway, and a module with
+many small, closely related domain functions accumulates many small files, which has its own
+navigation cost. A project that already caps files by line count rather than by function count
+gains nothing extra from this — it addresses a different axis.
+
+## If the operator accepts this
+
+Materialize it into `docs/ach.md` under the Domain-like component type. This convention has no
+practical mechanical check of its own — "one function per file" is check-able only by parsing
+exports per file, which the existing naming check (`code-style/trpc-v11/naming.md`) already
+covers as a side effect: if every domain file matches `^export const domain_` for exactly one
+export, a second export in that file (a hand-added constant, say) would itself be a naming-rule
+violation with a different shape. Do not add a redundant hard rule for this alone.

package/content/code-style/trpc-v11/naming.md

@@ -0,0 +1,60 @@
+---
+type: code-style
+description: 'Proposes a fixed export/file naming pattern for tRPC procedures and domain functions, plus a fixed location for module subrouters.'
+load: cold
+stack: trpc-v11
+concern: naming
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trpc/server")' package.json >/dev/null 2>&1; else grep -q '"@trpc/server"' package.json 2>/dev/null; fi
+---
+
+# Code style — tRPC v11 naming
+
+> This is a **proposal**, not a fact about tRPC. Materialize it into `docs/ach.md` and
+> `docs/afm.md` §3 only if the operator accepts it — item by item, at bootstrap. Nothing here is
+> `(mandatory)`.
+
+## The convention
+
+- **Procedure export:** `procedure_<action><Module>` — camelCase, action first, plural module
+  after. Example: `procedure_getApps`, `procedure_createRegistries`.
+- **Procedure file:** `<action>-<module>.ts` — kebab-case, same stem as the export.
+- **Domain export:** `domain_<action><Module>` — same shape as the procedure, so the two read as
+  a matched pair.
+- **Domain file:** `<action>-<module>.ts` — kebab-case, same pattern as the procedure.
+- **Module subrouter:** lives at `modules/<f>/router.ts`. It imports the module's procedures and
+  exports a tRPC subrouter — aggregation plus namespacing, never a business rule.
+
+Anti-examples for the procedure prefix:
+- ❌ `procedure_signOut` — missing the module.
+- ❌ `signOutProcedure` — suffix instead of prefix.
+- ❌ `procedure_AuthSignOut` — module before the action.
+
+## Why this works
+
+A fixed prefix makes `grep -rn "^export const procedure_"` a complete inventory of every
+tRPC entry point, and the matching `procedure_`/`domain_` pair makes the transport-to-business
+mapping readable by name alone, without opening either file. The `modules/<f>/router.ts` location
+gives every module the same subrouter address, so a new contributor finds the aggregation point
+without asking.
+
+## The trade-off
+
+The prefix is redundant with the file's own location (`server/modules/x/procedures/get-apps.ts`
+already says "this is a procedure in module x") and with the tool tip / import statement a caller
+sees. A project that already has a naming scheme — feature-first folders, a different subrouter
+layout, no `modules/` tier at all — gains nothing from importing this one; the value is
+consistency **within** a project that adopts it, not a property of tRPC itself.
+
+## If the operator accepts this
+
+- Materialize the naming rule and anti-examples into `docs/ach.md` (Procedure-like /
+  Domain-like sections).
+- Add a hard rule to `docs/afm.md` §3, verified by:
+  ```sh
+  grep -rn "^export const procedure_" {{src-path}}/server/modules/*/procedures/*.ts
+  grep -rn "^export const domain_" {{src-path}}/server/modules/*/domain/*.ts
+  ```
+  Every export returned must match the pattern — an empty result on a project with procedures
+  means the convention was not followed, not that the check passed vacuously; confirm at least
+  one procedure file exists first.

package/content/code-style/trpc-v11/test-placement.md

@@ -0,0 +1,52 @@
+---
+type: code-style
+description: 'Proposes a neighbor-test layout for tRPC procedures and domains, and a single shared test-context factory.'
+load: cold
+stack: trpc-v11
+concern: test-placement
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("@trpc/server")' package.json >/dev/null 2>&1; else grep -q '"@trpc/server"' package.json 2>/dev/null; fi
+---
+
+# Code style — tRPC v11 test placement
+
+> This is a **proposal**, not a fact about tRPC. Materialize it into `docs/ach.md` and
+> `docs/afm.md` §3 only if the operator accepts it — item by item, at bootstrap. Nothing here is
+> `(mandatory)`.
+
+## The convention
+
+- **Neighbor test.** `<action>-<module>.test.ts` lives in the SAME directory as
+  `<action>-<module>.ts` — no separate `__tests__/` folder.
+- **One shared context factory.** Every test that needs a `TRPCContext` (procedures) or a
+  `DomainContext` (domains) builds it through one helper — for example
+  `makeTestCtx(override?)`, returning a fresh, deep-copied ctx — instead of constructing the
+  context object by hand in each test file.
+
+## Why this works
+
+A neighbor test is found by the same file-explorer sort that finds the source file, and a
+directory listing shows source and test side by side, which makes an untested file visible at a
+glance. A single context factory means a `TRPCContext` field added once is available to every
+test through one function, instead of a hand-rolled object per test file quietly drifting from
+the real shape.
+
+## The trade-off
+
+`__tests__/` (or a top-level `test/` mirror) is itself a legitimate, widely used layout — it
+keeps a directory listing free of test files for someone scanning source only, and some test
+runners default to it. A hand-built context per test can also be the right call for a test that
+deliberately exercises a malformed or partial context — forcing every test through one factory
+can hide that case behind an `override` parameter nobody reads closely. Pick the layout that
+matches how the team already scans the codebase; do not adopt this because it is here.
+
+## If the operator accepts this
+
+- Materialize the neighbor-test convention into `docs/ach.md` (Procedure-like / Domain-like).
+- If a shared context factory is adopted, name and locate it explicitly in `docs/ach.md`
+  (project-specific — do not copy a path from another repo).
+- Add a hard rule to `docs/afm.md` §3, verified by:
+  ```sh
+  find {{src-path}}/server -name "__tests__" -type d
+  ```
+  Zero results required.

package/content/core/ach.md

@@ -0,0 +1,265 @@
+---
+type: core
+description: 'The architecture guide: the component types and where each one lives.'
+load: warm
+materializes_to: 'docs/ach.md'
+---
+
+# ACH — Architecture Guide
+
+> Live architecture guide for {{nome do projeto}}.
+> **Author:** owner of the architecture. Changes go through review before merge.
+>
+> This document answers: "Where do I put this logic?", "How do I structure this new module?", "How much testing does this change need?".
+>
+> **Related docs:** [`/docs/afm.md`](./afm.md) (process + hard rules), [`/docs/gotchas/`](./gotchas/) (counterintuitive surprises), [`/docs/adr/`](./adr/) (versioned decisions).
+
+> **In this file:** 1. Macro Architecture · 2. Folder Architecture · 3. Components · 4. Test Strategy · 5. Cross-cutting Principles · 6. Code Conventions
+
+
+---
+
+## 1. Macro Architecture
+
+```
+{{Diagrama ASCII das camadas. Fluxo principal. Dataflow de artefatos entre serviços externos.
+
+Convenção: setas unidirecionais (→ camada chama camada). Boxes pra serviços externos. Texto curto identificando o tech (ex: "Postgres", "Redis", "S3-compatible").}}
+```
+
+**Canonical entities:**
+- **{{Entidade A}}** — {{descrição em 1 linha}}.
+- **{{Entidade B}}** — {{descrição em 1 linha}}.
+
+**Dataflow:**
+- **{{Storage primário}}** — source of truth for {{X}}.
+- **{{Storage secundário}}** — source of truth for {{Y}}.
+
+---
+
+## 2. Folder Architecture
+
+```
+{{árvore de pastas comentada — uma linha por pasta importante explicando o que vive ali}}
+```
+
+### Import rules
+
+```
+{{layer X}}    → can import: {{lista}}
+                 NEVER imports: {{lista}}
+
+{{layer Y}}    → can import: {{lista}}
+                 does NOT import directly, receives via parameter: {{lista}}
+```
+
+**Promotion to `domain/shared/`:** a function/value object in `modules/<X>/domain/` moves to `{{src-path}}/domain/shared/` when used by **3+ modules** (Rule of Three).
+
+---
+
+### Boundary exit
+
+A boundary holds from the first need: a primitive needed on the forbidden side moves to the lowest layer both sides may import, never copied and never injected. The Rule of Three decides when a domain value becomes shared; it never decides whether a boundary may be crossed.
+
+## 3. Components
+
+### 3.1 First-class components
+
+This section defines the **project vocabulary**. It maps universal component types to concrete tools in the chosen stack. The interview (`afm path interview/bootstrap.md`) fills this in.
+
+#### Procedure-like — handler sync request/response
+
+- **Universal concept:** handler for a short synchronous operation (< ~5s). Input is validated, auth is checked, and the return is typed for the frontend.
+- **Stack implementation:** {{ex: tRPC procedure / Express route handler / Nest Controller / FastAPI endpoint}}.
+- **Single responsibility:** orchestrate — validate → authorize → call domain/lib → persist → respond.
+- **When to use:** every synchronous UI ↔ server interaction.
+- **When NOT to use:**
+  - Heavy logic → delegate to Domain-like.
+  - Long-running, retryable, or scheduled work → delegate to Task-like.
+- **Naming convention:** {{ex: `procedure_<action><Module>` + arquivo `<action>-<module>.ts`}}.
+- **Canonical example:** {{path real do projeto}}.
+- **Anti-examples (do not do this):**
+  - ❌ {{exemplo de naming errado com porquê}}.
+  - ❌ {{exemplo de pasta errada com porquê}}.
+
+#### Domain-like — pure business rule function
+
+- **Universal concept:** a pure function that applies a business rule. No un-abstracted I/O. No undeclared side effects. Testable without infra.
+- **Stack implementation:** {{ex: função TS exportada com prefixo `domain_` / Use Case do DDD / função Python pura}}.
+- **Canonical contract:** {{ex: `({ ctx, input }: DomainInput<T>) => Result<T, DomainErrorCode>`}}.
+- **ONE domain function per file. No exceptions.** Shared constants and types go into `<nome>.{{ext}}` in the module. Never add them as a second export in the domain file.
+- **When to use:**
+  - Logic that survives a transport change (HTTP today, CLI tomorrow).
+  - A rule you can test without a real DB.
+- **When NOT to use — Domain is NOT:**
+  - ❌ **A data-access helper.** Building a query, mapping to a DTO, or forming a JOIN is infra or procedure work.
+  - ❌ **Transport glue.** HTTP headers, webhook parsers — those live in lib or procedure.
+  - ❌ **Orchestration between modules.** That is procedure or task responsibility.
+  - ❌ **Un-abstracted I/O** (fetch, spawn, direct S3 calls).
+  - ❌ **A file with only types or constants.** Move it out of `domain/` into `*.types.{{ext}}`.
+  - ❌ **Importing a transport error type** (hard rule 15).
+- **Anti-examples (do not do this):**
+  - ❌ {{exemplo `domain_xWhereClause` retornando query parcial}}.
+  - ❌ {{exemplo arquivo com 2 `domain_*` exports}}.
+
+#### Shared Domain — rule used by 3+ modules
+
+- **Universal concept:** value objects, rules, and types shared across multiple modules.
+- **When to use:** on the third confirmed duplicate across modules — promote it (Rule of Three).
+- **When NOT to use:** on the first or second occurrence — keep it in `modules/<X>/domain/`.
+
+#### Task-like — retry-safe async unit of work
+
+- **Universal concept:** async work that can retry without corrupting state. It reads canonical state from the DB, early-returns on terminal states, updates atomically, and triggers the next task when needed.
+- **Stack implementation:** {{ex: Trigger.dev v4 task / BullMQ Job / Celery task / AWS Step Function}}.
+- **When to use:**
+  - Cron or scheduled jobs.
+  - Long workflows with retry (build, publish).
+  - External integrations with variable latency.
+- **When NOT to use:**
+  - It fits in < 5s with no retry → use procedure.
+  - It is pure logic with no I/O → use domain.
+
+##### Orchestration pattern: thin parent calls subtasks
+
+A multi-stage workflow = a thin parent that coordinates, plus subtasks that do the work. Each subtask has its own retry, its own log, and its own sizing. The parent only calls `triggerAndWait`.
+
+#### Lib-like — isolated, publishable package
+
+- **Universal concept:** a self-contained package with no dependency on the app runtime (no ORM, no web framework, no orchestrator). It must be safe to `publish`.
+- **Stack implementation:** {{ex: a folder under `{{src-path}}/lib/` with an `index.ts` and zero framework imports}}.
+- **Responsibility:** a self-contained feature.
+- **When to use:** any of these:
+  - The same helper already has 3 callers.
+  - It wraps a nameable external integration (Stripe, S3, etc.).
+  - It holds > ~150 lines of coupled pure logic.
+- **When NOT to use — a Lib is NOT:**
+  - ❌ **A lib that imports an ORM type.** Accept a minimal structural shape instead.
+  - ❌ **A lib with an implicit singleton** (a module-level variable caching a client). Export a factory instead.
+  - ❌ **A lib with a God object** (a class or object with 8+ methods). Use named functions instead.
+  - ❌ **A lib that logs on its own.** Receive `log` by DI, or return a `Result`.
+  - ❌ **A lib that defines errors with no literal discriminant** (`code: "..." as const`).
+  - ❌ **A lib with 1 caller.** YAGNI.
+  - ❌ **A lib with a huge options bag** (≥ 6 optional fields).
+  - ❌ **A lib that imports from a layer above it.** Layer order follows this project's Import rules in § 2. It is not a hardcoded example.
+
+#### Adapter-like — implementation of a typed port
+
+- **Universal concept:** a concrete implementation of a port (a typed interface). Examples: a registry adapter (NPM/GitHub/Custom), a storage adapter (S3/R2/MinIO), an email adapter (Resend/SES).
+- **LSP in action:** every implementation of the same port returns the same classified result shape (e.g., `PUBLISHED|CONFLICT|FAILED`). Adapter A cannot return `null` on conflict while adapter B throws an exception.
+- **OCP in action:** adding a new provider means a new file that implements the port, **with no** `switch (provider)` scattered around.
+
+### 3.2 Supporting components (second class)
+
+#### Module router — aggregation inside the module namespace
+
+{{Implementação no stack — ex: `modules/<f>/router.ts` que junta procedures num subrouter tRPC}}.
+
+#### Infra — cross-cutting utilities
+
+Singleton clients, rate-limit wrappers, email senders, and test context factories. **Contains no business rules.**
+
+#### UI primitives
+
+Presentation components. No direct fetch — data comes via {{cliente do stack — ex: tRPC + React Query}}.
+
+---
+
+## 4. Test Strategy
+
+### 4.1 Levels (classic pyramid + strong XP)
+
+| Level | What it tests | Where it lives | Target ratio |
+| ----- | ----------- | --------- | -------------- |
+| **Unit** | Pure logic, domain, pure libs | {{paths}} | ~70% |
+| **Integration** | Contracts between layers with real I/O | {{paths}} | ~25% |
+| **E2E** | End-to-end user flow | {{paths}} | ~5% |
+
+### 4.2 Strict TDD + types-as-test
+
+```
+1. RED    — write a test (or a type signature) that fails for the right reason
+2. GREEN  — minimal implementation that passes
+3. REFACTOR — remove duplication, improve names, type-check + tests
+```
+
+`tsc --noEmit` is part of the red/green loop, just like the tests.
+
+### 4.3 Regression
+
+**Bug found → write a reproducing test BEFORE the fix.** No exceptions. Production hotfix: add the test in the same PR.
+
+### 4.4 Types as tests
+
+`unknown` or `any` in a helper you own is a missing type test. Fix the inference.
+
+### 4.5 Target coverage by layer
+
+{{Tabela: por camada/pasta, qual cobertura mínima e se é policiada por CI ou só guideline.}}
+
+**No global threshold in CI** — the metric is easy to game. Confidence comes from the reviewer plus AFM, not from a number.
+
+---
+
+## 5. Cross-cutting Principles
+
+- **XP + Pragmatic** — DRY, YAGNI, KISS, Broken Windows, Design by Contract, Rubber Duck. Daily practices in [`/docs/afm.md`](./afm.md).
+- **Task idempotency** — every task is retry-safe. Canonical state lives in the DB. Early return on terminal states is the rule.
+- **{{Storage primário}} = source of truth for {{X}}. {{Storage secundário}} = source of truth for {{Y}}.** Resolve any divergence by always reading from the authoritative source per type.
+- **Types instead of comments.** The name and type carry the *what*. Use a comment only to explain a surprising *why*.
+- **Observability by design.** Every async operation leaves a traceable trail (run id, correlation id, etc.).
+- **Auditable schema — state with a lifecycle gets its own model.**
+  - State with a cycle (start → update → end) is NOT a scalar field on the owner.
+  - Use a separate model with one row per instance instead.
+  - Rule of thumb: if X is recreated, do you want its history?
+  - If yes, add a model with an FK to the owner.
+  - Lifelong 1:1 external identifiers can stay as a plain field.
+
+{{Adicione princípios transversais específicos do projeto.}}
+
+---
+
+## 6. Code Conventions (cheat sheet)
+
+### Decision rubrics
+
+Check the rubrics in [`rubrics/`](rubrics/) **before** you choose:
+
+- [`when-to-create-lib.md`](rubrics/when-to-create-lib.md) — triggers for creating `{{src-path}}/lib/<x>/`.
+- [`when-to-create-module.md`](rubrics/when-to-create-module.md) — triggers for creating a top-level module.
+- [`when-to-create-dsl.md`](rubrics/when-to-create-dsl.md) — DSL-first: when primitive boilerplate scales (≥3 repeated sequences, wiring dominates, and a grammar exists), suggest a DSL. Rule 11: do not build it yourself.
+- [`enum-vs-union-vs-branded.md`](rubrics/enum-vs-union-vs-branded.md) — which type to use for an enumerable value.
+- [`error-classification.md`](rubrics/error-classification.md) — Domain vs Procedure vs Infra.
+- [`failure-classification.md`](rubrics/failure-classification.md) — a failure recognized by an external signal (CRITIC) → procedure (mechanical) | learning (conceptual) | nothing (transient). Used by the CRITIC loop (`remediate`).
+- [`episodic-vs-semantic-boundary.md`](rubrics/episodic-vs-semantic-boundary.md) — what decays (episodic: session handoffs, `_focus.md`) vs. what is permanent (semantic: rules/decisions/gotchas). Defines what belongs in the diagnose axes.
+- [`negative-filters.md`](rubrics/negative-filters.md) — what NOT to promote to durable docs (a negative tool claim, transient failure, one-off narrative, or status update). The rejection checklist for the `gotcha`/`reconcile`/`remediate` gate. A false constraint is poison (#5).
+- [`solid-triggers.md`](rubrics/solid-triggers.md) — OCP/LSP/ISP/DIP with a concrete trigger.
+- [`validation-boundary.md`](rubrics/validation-boundary.md) — where the Zod parser (or equivalent) fits in.
+- [`when-to-evolve-methodology.md`](rubrics/when-to-evolve-methodology.md) — when to run an `afm evolve` cycle (health of this project's whole local doc set) vs. a one-off fix (`afm gotcha`/`afm rule`/`afm adr` via reconcile).
+- [`template-vs-streaming-precedence.md`](rubrics/template-vs-streaming-precedence.md) — when a frozen template (`export-template`) and streaming learning (`reconcile`) collide: precedence plus tombstone, never additive (AWM non-additivity).
+
+### Naming (fill in during the interview)
+
+| Layer | Export pattern | File pattern |
+| ----- | ---- | ---- |
+| Procedure-like | {{ex: `procedure_<action><Module>`}} | {{ex: `<action>-<module>.ts`}} |
+| Domain-like | {{ex: `domain_<action><Module>`}} | {{ex: `<action>-<module>.ts`}} |
+| External lib | {{ex: `<libname>_<action>`}} | {{ex: `<action>.ts`}} |
+| Test file | {{ex: same name + `.test.{{ext}}`}} | {{ex: same directory, no `__tests__/`}} |
+
+### Size and responsibility
+
+- ≤ 300 lines per file.
+- One responsibility per file.
+- Shared types → `*.types.{{ext}}` next to the file.
+- Constants → `*.constants.{{ext}}` next to the file.
+
+### Types: explicit at boundaries, inferred elsewhere
+
+- **Explicit:** return types of exported functions, public parameters, ctx/input of procedures and domain functions, props of exported components.
+- **Inferred:** local variables, closure return values, `.map` output, chained calls.
+- **Never `any` / `unknown` in a helper you own.**
+
+---
+
+*Changes here follow hard rule 11: an architectural change stops and asks. The surface is `afm approve` for a plan, or `afm ask <op>` for a question, whichever the situation calls for.*