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

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

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

@@ -0,0 +1,49 @@
+---
+type: rubric
+description: Decides when code earns its own library directory.
+load: warm
+fires_on: file-shape
+trigger_min_lines: 150
+trigger_max_consumers: 1
+fires_when: 'a file passes 150 lines of logic and at most one other file imports it'
+---
+
+# Rubric — when to create `{{src-path}}/lib/<x>/`
+
+## Binary decision
+
+**Create a lib when ANY of these is true:**
+
+- ✅ You already have **3 callers** of the same inline helper (confirmed Rule of Three).
+- ✅ It is a **nameable external integration** (Stripe, S3, Resend, Slack, GitHub). It becomes `lib/<provider>/`.
+- ✅ It has **more than ~150 lines** of pure logic coupled to one consumer. Extract it to reduce reading load.
+
+**Do NOT create a lib when:**
+
+- ❌ You have 1 caller. Keep it inline. Wait for the second caller.
+- ❌ It mixes I/O with the ORM. Put it in `infra/` or inline in the procedure.
+- ❌ The helper has fewer than 10 lines and 2 callers. Simple duplication wins (KISS beats DRY here).
+- ❌ The reason is "I will need it later". This is YAGNI. Keep it inline until you need it.
+
+## Why these rules exist
+
+- **3 callers means a real pattern, not a coincidence.** Two callers can be a false convergence.
+- **An external integration deserves its own name** (`stripe_createCustomer`, not `createCustomer`). The reader then knows at once that this is a network call. This lowers the cognitive cost of scanning the code.
+- **At 150 lines, "read the whole file" costs more than "follow the call to the helper."** Below that size, inline code is cheaper.
+- The reader pays this cost either way. Extraction just moves it to the cheaper side.
+
+## Where to place it when you create it
+
+Decide in this order:
+
+1. **Is it a pure lib with no dependency on the app framework?** Use `{{src-path}}/lib/<x>/`. It must be publishable, with zero ORM, web framework, or orchestrator code.
+2. **Does it hold business logic for module X?** Use `{{src-path}}/server/modules/<X>/domain/`.
+3. **Does it serve 3 or more modules?** Use `{{src-path}}/domain/shared/`.
+4. **Is it a wrapper for an external client (a singleton with config)?** Use `{{src-path}}/server/infra/`.
+
+## Bad examples
+
+- ❌ `{{src-path}}/lib/utils/format-date.ts` with 1 caller. Keep it inline in the page that needs it.
+- ❌ `{{src-path}}/lib/auth/get-user.ts` that imports the ORM. Move it to `{{src-path}}/server/modules/auth/`. It is not a pure lib.
+- ❌ `{{src-path}}/lib/email-and-notifications/` mixes two responsibilities. Split it into `{{src-path}}/lib/email/` and `{{src-path}}/lib/slack/`.
+- ❌ `{{src-path}}/lib/stripe/` with `class StripeManager { 12 methods }`. Split it into `{{src-path}}/lib/stripe/checkout.ts`, `{{src-path}}/lib/stripe/portal.ts`, and so on, using named functions such as `stripe_createCheckoutSession`.

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

@@ -0,0 +1,39 @@
+---
+type: rubric
+description: Decides when a feature earns a top-level module.
+load: warm
+fires_on: file-shape
+trigger_new_module: 'modules'
+fires_when: 'the file would be the first one in a new top-level module directory'
+---
+
+# Rubric — when to create a top-level module in `{{src-path}}/server/modules/`
+
+## Binary decision
+
+**Create a new module when ALL of these are true:**
+
+- ✅ It has its **own entity** (a new model, not a field on an existing model).
+- ✅ It already has **2 or more planned procedures** (not one isolated procedure).
+- ✅ It has its **own state with a lifecycle** (not just a static lookup table).
+
+**Otherwise it is a sub-feature of an existing module.** Example: `notifications` that serves only `auth` belongs at `{{src-path}}/server/modules/auth/notifications/`, not as a top-level module.
+
+## Why these rules exist
+
+- **Its own entity** defines the module's natural boundary. Without an entity, it is just a feature of another module (a field, extra behavior).
+- **2 or more procedures** confirms the module has enough usage surface. One isolated procedure does not justify its own directory, router, and domain.
+- **Lifecycle** separates "a domain with state" from "static configuration." A plan (FREE/PRO) is an enum plus a lookup table. It is not a `plans/` module. It is part of `billings/`.
+
+## Review questions before you create a module
+
+1. Does this concept already exist in a current module? If yes, it is a sub-feature.
+2. Will it share `domain/`, `infra/`, or types with another module? If yes, consider `{{src-path}}/domain/shared/` instead of a new module.
+3. Will it stay untouched for more than 6 months? If yes, and it does not grow, it may be a helper, not a module.
+
+## Anti-examples
+
+- ❌ Do not create `modules/notifications/` when only `auth` sends notifications. Use `modules/auth/notifications/`.
+- ❌ Do not create `modules/plans/` to hold the `PLAN_CONFIG` constant. Use `modules/billings/plan-config.ts`.
+- ❌ Do not create `modules/utils/` to collect cross-module helpers. No `utils` module exists. Put helpers in `lib/` or inline.
+- ❌ Do not create `modules/admin/` early "because an admin panel is coming later." This is YAGNI. Wait for the first admin procedure to appear.

package/content/rubrics/when-to-evolve-methodology.md

@@ -0,0 +1,62 @@
+---
+type: rubric
+description: Chooses between the full cycle, one mechanism and a point fix.
+load: warm
+fires_on: op-call
+called_by: ["evolve", "reflect"]
+fires_when: 'a methodology finding needs a path: cycle, one mechanism, or a point fix'
+---
+
+# Rubric — the `evolve` cycle vs. a single mechanism vs. a point fix
+
+> **What "evolution" means here:** it means refining the **local documentation of this project** (the methodology instance materialized in `<consumer>/docs/`). It makes that doc leaner, clearer, current, and efficient. It is **never** AFM itself (the bundled content). For the plugin, you only **suggest** a change, through `afm promote`. Every mention of "methodology" or "methodology health" below means the local doc.
+
+> This is a **3-way decision**. Does the finding call for (1) the **full cycle** of `afm evolve` (an orchestrator: gather evidence → propose → one gate → apply → record), (2) **one mechanism à la carte** (`afm diagnose`, `afm reflect`, `afm generalize`, `afm restructure`), or (3) **a point fix** that `reconcile` proposes directly through an atomic skill (`afm gotcha`, `afm rule`, `afm adr`)? Cost decreases in that order. The cycle costs the most: it composes several mechanisms, one consolidated gate, and a record in `docs/evolution/`. A single mechanism is scoped to one axis. A point fix is cheap. Do not run the cycle for what one mechanism can fix. Do not run a mechanism for what one edit can fix.
+
+## The 3 paths
+
+### 1. The `evolve` cycle — use it when BOTH of these are true:
+
+- ✅ **The problem affects the whole instance, not one isolated axis.** You see several health findings. Or the findings cross categories: dead references **and** a rule that misled someone **and** inflation spread across files. This is a *health sweep*. It benefits from one consolidated gate and one lineage record.
+- ✅ **You have observable evidence that something is below 100%.** The evidence can be mechanical (from `diagnose`). It can be behavioral (from `reflect`). It can be a symptom the user states directly, such as "these docs are a mess." Without a signal, do not run the cycle. A healthy instance gains almost nothing from it. The cooldown refuses to run it.
+
+> **Second entry point — ex-post, from inside `reflect`.** The two criteria above are normally applied ex-ante, before acting, to pick a path. `reflect.md § 5` applies the same two criteria ex-post — after the mechanism already ran, over the findings it already collected in its own §§ 1-2 — to discover that what it found exceeds its own scope. Same criteria, no new test, no restatement. It only proposes; the user still invokes `afm evolve`. See `ops/reflect.md § 5`.
+
+### 2. A single mechanism à la carte — use it when you know exactly which lens you need:
+
+- 🔍 **`afm diagnose`** — only the **health report** (a mechanical scan of the 7 axes, read-only). Use it to answer "how healthy is the methodology here?" without proposing or applying anything.
+- 🪞 **`afm reflect`** — use it when **one specific doc misled you** at apply time (an ambiguous rule, a section that gave no guidance). It refines instructiveness, based on behavioral evidence from the session.
+- 🧬 **`afm generalize`** — use it when **2 or more similar gotchas** have piled up and should merge into one abstract rule (episodic to semantic). This is anti-inflation at the root.
+- 🗂️ **`afm restructure`** — use it for **staleness**, where a doc no longer matches the code. Use it also for **findability and partitioning**: information in the wrong place, or a doc that outgrew its shape.
+
+> A single mechanism still **self-checks and gates** what it proposes. `reflect`, `generalize`, and `restructure` each have their own gate. `diagnose` is read-only. What sets a single mechanism apart from the cycle is **scope**. It uses one lens, not the full sweep. It skips the overhead of composing every mechanism plus a cycle record.
+
+### 3. A point fix (reconcile → an atomic skill) — use it when the change is additive and local:
+
+- ❌ **You learned a new fact, decision, or gotcha.** Use `afm adr` for an architecture decision. Use `afm rule` for a rule from one correction. Use `afm gotcha` for a surprise that has bitten you 2 or more times. `reconcile` already covers this at the end of the turn. Opening a mechanism or the cycle is overhead here.
+
+  Distinction: `reconcile`, `gotcha`, and `rule` **add** knowledge. `reflect`, `generalize`, and `restructure` **refine, consolidate, or reorganize** knowledge that already exists.
+- ❌ **You need to validate ONE feature.** For coverage or consistency across spec, plan, and tasks, use `afm analyze` (read-only, per feature).
+- ❌ **You need to deliver a feature.** Use `afm deliver`.
+- ❌ **You need to promote a lesson to the plugin.** Use `afm promote`.
+
+## Why these rules exist
+
+- **An observable signal is mandatory** for paths 1 and 2. A claimed systemic problem with no evidence turns the agent into an auditor of text using only text — a self-reference loop. This is forbidden. Mechanical evidence (`diagnose`) and behavioral evidence (`reflect`) are the two valid kinds of evidence — the two sides of the Self-Harness φ. Both count.
+- **Signal beats ritual** (Self-Harness / Autogenesis). In healthy docs, the cycle returns almost nothing. An evidence-based trigger beats a fixed budget or calendar. The `evolve` cooldown refuses to run the cycle without a new signal. A single mechanism, being scoped and — for `diagnose` — read-only, carries no cooldown.
+- **Scope decides the path** (cycle vs. mechanism). If you know the lens, use the mechanism. If the problem is a multi-category sweep that deserves one consolidated gate, use the cycle. Do not compose every mechanism (`evolve`) to fix a single axis.
+- **An empty diagnosis is a valid result.** If the scan or reflection finds nothing, it reports "100%" and stops. It must **never** invent a problem to justify having run.
+- **Doc size is a signal to consolidate, never a signal to cut** (ACE vs. Configuring). A core doc above about 500 lines (the `afm doctor` A6 inflation threshold) routes to a **consolidation review**. `afm generalize` merges redundancy. `afm restructure` partitions by temperature. Neither ever cuts content based on line count alone.
+
+  ACE prunes redundancy, not lines. Brevity bias discards load-bearing detail. The line count triggers a review. It never dictates a deletion.
+
+## Counterexamples
+
+- ❌ **Running `afm evolve` weekly by ritual.** Run it on a signal, never on a calendar.
+- ❌ **Opening the cycle to log one new gotcha.** This is additive and local. `afm gotcha` (or `reconcile` proposing it) is enough.
+- ❌ **Running the full cycle just to check health.** Use `afm diagnose` instead (read-only, no gate).
+- ❌ **Claiming "this doc looks inflated" without a `wc -l` or a grep for duplication.** Without observable evidence, this is not a finding (see rule 5 above).
+- ❌ **Running `generalize` from 1 gotcha.** Without a batch of 2 or more, there is no generalization — only an invented abstraction with no evidence.
+- ❌ **Using `reflect` to soften a rule because it embarrassed you.** A violation does not mean the rule is wrong. "The agent was non-compliant" is a mandatory rival hypothesis.
+- ❌ **Using `restructure` to force tiering on a small doc.** Partitioning by temperature is opt-in. Use it only when a doc has actually grown large (YAGNI).
+- ❌ **Running the cycle again when nothing has changed.** The cooldown blocks the cycle. Running a mechanism with no new signal is theater.

package/content/skills/adr.md

@@ -0,0 +1,42 @@
+---
+name: adr
+description: |
+  Writes an Architecture Decision Record to `<consumer>/docs/adr/NNNN-slug.md`. It records context, decision, alternatives and consequence. In a refactored project, write a retroactive ADR only when it is load-bearing.
+  Activates: `afm adr`, "create ADR", "architectural decision", "record this architecture choice".
+---
+
+# AFM — ADR
+
+The CLI owns the number, the template, the frontmatter, the supersede link and the index. This skill keeps
+only the judgment.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. It does not control activation itself. A
+counterintuitive surprise belongs in `afm gotcha`. A rule with an executable trigger belongs in `afm rule`.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `afm init` (greenfield) or
+`afm refactor` (brownfield) first. Exit 4 means the shipped content does not resolve: report it, do not
+fall back silently.
+
+## Procedure (judgment only)
+
+1. Ask the status: `afm ask adr`. Collect the title, context, decision, alternatives, consequence and refs
+   as free text, because these fields carry intent.
+2. Run `afm adr new <slug> --title "<title>" --description "<one sentence>"`, with `--supersedes N` when
+   the decision replaces ADR N.
+3. Fill the sections of the printed file with what the operator said, and leave the rest `[TBD]`. Report the
+   path (#6).
+
+The "Additional step in a refactored project" in the op applies ONLY when `afm refactor` adopted the
+project (signal: `afm.md` § 3.1 forward-only exists). A greenfield project forbids a retroactive ADR.
+
+## Invariant principles
+
+Additional #9 (a retroactive ADR is
+load-bearing-only) applies ONLY in a refactored project.
+
+Passive mode (`afm reconcile`) is always on and can propose `afm adr` when it detects a "novel structural
+decision" signal. This skill covers only the active creation.

package/content/skills/analyze.md

@@ -0,0 +1,28 @@
+---
+name: analyze
+description: |
+  Cross-checks one feature against the instance. It compares `docs/features/NNN-*/{spec,plan,tasks}.md` with prd, ust, ach, afm § 3 and PRINCIPLES. It reports findings by severity in chat and writes no file.
+  Activates: `afm analyze [<feature>]`, "audit feature", "check coverage", "validate consistency before implementation".
+---
+
+# AFM — Analyze
+
+## When NOT to activate
+
+Use `afm clarify` to resolve markers interactively. Use `afm deliver` for end-to-end delivery: it runs analyze underneath, in gating mode. Use `afm diagnose` for the health of the whole doc set.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `afm init` or `afm refactor`).
+
+## Procedure
+
+Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`); a remediation that adds a task runs `afm task add`, never a hand edit of the `tasks:` list, and a task is closed only with `afm task done`. Gating mode sorts findings into buckets instead of reporting.
+
+## Invariant principles
+
+Most relevant here: #2 (detection is an autonomous scan, not a question), #5 (no finding without evidence) and #6 (analyze is read-only: it reports in chat, writes no file, and remediates only on request).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. This skill covers only active auditing.

package/content/skills/clarify.md

@@ -0,0 +1,28 @@
+---
+name: clarify
+description: |
+  Scans one feature for ambiguity. It asks the irreducible questions, recommendation first, and writes the answers to `spec.md § 7 Clarifications`.
+  Activates: `afm clarify [<feature>]`, "resolve markers", "clear up ambiguity in feature X", "clarify the spec".
+---
+
+# AFM — Clarify
+
+## When NOT to activate
+
+Use `afm analyze` for a read-only, multi-artifact validation that does not resolve markers. Use `afm deliver` for end-to-end delivery: it calls clarify underneath when needed.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `afm init` or `afm refactor`). `afm feature status <NNN> --json` lists the open markers of a feature in `blockers`.
+
+## Procedure
+
+Judgment only: a 9-category scan of the spec, a prioritized queue (at most 5 questions), auto-resolution from the code and docs before any question, then one recommendation-first question per turn. The questions come from the spec, so they are dynamic; the one fixed decision (`underspecified`) is in `afm ask clarify`. Integrate each answer into `spec.md` at once, remove the marker, and finish with the coverage summary.
+
+## Invariant principles
+
+Most relevant here: #2 is discover-first: resolve each question yourself through the scan or the docs, then ask. #4 says `[TBD]` beats invention, and a recommendation is a rejectable hypothesis, not a guess. #6 is autonomy-first: write the integration into spec § 7 and report. #8 is recommendation-first questions.
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. This skill covers only the active resolution of ambiguity.

package/content/skills/deliver.md

@@ -0,0 +1,26 @@
+---
+name: deliver
+description: |
+  Delivers one feature from discovery to reconciliation. It takes one recorded approval (`afm approve`), writes spec, plan and tasks, then runs each task as RED, GREEN, REFACTOR, COMMIT. It resumes from the correct phase when those files exist. Orchestrator: it composes specify, plan, tasks, clarify, analyze and reconcile. External research is not an AFM op; it routes to nasca.
+  Activates: `afm deliver [<feature>]`, "build feature X", "implement X end to end", "the tasks already exist, run them", "continue the delivery of feature N".
+---
+
+# AFM — Deliver (orchestrated autonomous delivery)
+
+The **orchestrator** of the delivery loop. One request takes "build feature X" from discovery to a delivered feature. It does not duplicate the sub-steps: it reads and follows `afm specify`, `afm plan`, `afm tasks`, `afm clarify`, `afm analyze` and `afm reconcile` through a suppression contract. External unknowns go through {{host:nasca-research}}, or {{host:nasca-campaign}} for a deep study; ask the operator if nasca is missing.
+
+## When NOT to activate
+
+An isolated step ("just open the spec", "just generate the tasks") is the matching atomic skill. A trivial change goes straight to the `afm.md § 2` loop.
+
+## Pre-check
+
+Run `afm preflight`. Exit 0 continues. Exit 3 means no `docs/.afm-version`: stop and suggest `afm init` (greenfield) or `afm refactor` (brownfield). Exit 4 or 5: report the line it printed. Do not fall back silently.
+
+## Most relevant here
+
+**#2** (discover-first: resolve unknowns by scan and research, ask only the irreducible part, never guess product or criteria) and **#6** (autonomy-first: approval at checkpoint granularity, the consolidated plan IS the proposal).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. It runs in parallel with `afm deliver` and takes the closing turn of Phase 4 (`core/afm.md` § 8.5 plus a passive sweep).