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

package/content/interview/refactor.md

@@ -0,0 +1,379 @@
+---
+type: interview
+description: The brownfield roadmap that infers an instance from code that already exists.
+load: cold
+---
+
+# Refactor — retroactive AFM adoption roadmap
+
+> This doc is an instruction **for the agent** when the operator runs `afm refactor` (or asks for something
+> equivalent, like "adopt AFM here", "build retroactive docs for the project", "infer docs from the code").
+> The CLI runs the **autonomous code archaeology** and materializes the skeleton of `docs/`; the agent
+> fills the drafts from the report, runs **a short gap interview** and writes the forward-only rules.
+>
+> Difference from `afm path interview/bootstrap`: bootstrap interviews the operator in 7 steps about a new
+> project. Refactor scans existing code, proposes drafts, and asks only what the code cannot reveal
+> (persona, pain, intentional decisions).
+
+---
+
+## Invariant principles (do not violate)
+
+**AFM universals**: see the single canonical source, `afm path PRINCIPLES`. Refactor applies **all** of
+them: § Universals (§1-8) + § Additional (#9, a retroactive ADR is load-bearing-only). Especially
+relevant here:
+
+- **#2** (discover-first): Part A is the literal application. The CLI scans stack, folders, entities, git
+  and rules on its own. Do not ask "what is the stack" or "where is X".
+- **#4** (`[TBD]` beats invention): refactor never infers persona, pain or intent from code. Code does not
+  reveal that.
+- **#5** (do not invent an entity or module): refactor does not materialize an entity that is not in the
+  schema (or its equivalent).
+- **#6** (autonomy-first): invoking `afm refactor` **is** the approval. There is no "start?" gate and no
+  per-file confirmation. Part B materializes the docs and **reports** (summary + paths). Review happens
+  over the `git diff` of the whole set, not a stop at each write. The same applies to D.10 (forward-only
+  default) and Closing (`[TBD]` goes to reconcile).
+- **#8** (questions are data, recommendation-first): every closed confirmation or selection goes through
+  `afm ask <op>`. Free text is only for genuinely open questions (pain, persona, justify N/A).
+- **#9** (a retroactive ADR is load-bearing): this sets refactor apart from bootstrap, which forbids one.
+
+**Refactor-specific rules** (how the retroactive adoption runs, not the methodology itself):
+
+1. **Materialize and report, no gate.** Write all the docs and report a summary + paths. The operator
+   reviews via `git diff`. No "start?", "want to review?" or "adjust granularity?": the invocation is the
+   approval (#6).
+2. **Inherited hard rules are forward-only by default.** Legacy code does not need to retroactively pass a
+   strict type check or 100% coverage. Forward-only is documented in `afm.md § 3.1` with a cutoff date.
+3. **Do not ask what is discoverable.** Stack, folders, entities and broken rules all come from the scan.
+   **DoD and pre-push** also come from the scan (the CI and hooks it reports). The interview spends turns
+   only on **intent** the code cannot reveal: pain, persona, problem/MVP, load-bearing ADR, lived gotcha.
+
+---
+
+## Pre-check (before Part A)
+
+1. **Is this really brownfield?** `afm refactor --mechanical` checks all of it and refuses with the reasons
+   (exit 1) when any is false: `docs/.afm-version` does not exist (if it does, the project is already
+   bootstrapped: use `afm update` to raise the version, and the atomic ops stay available); a manifest
+   with real dependencies exists; the source root holds more than 0 non-test files; the git history has
+   more than 20 commits (a sign of a project with history, not a scaffold). A project with `docs/.template`
+   needs `afm init` (its from-template branch). Not brownfield: suggest `afm init`.
+2. **Ask the two decisions the mechanical pass needs:** `afm ask init` (the harnesses whose instruction
+   files the project covers, and the string language of the product). A brownfield project already HAS
+   strings on screen, so scan first (#2): read the UI strings the code carries, and tell the operator what
+   you found before they answer. The language is a **product** decision, declared and never enforced; it
+   goes to `prd.md § 11.1`. `afm update` reads it before a language migration and excludes those strings
+   by construction. Without it, a migration cannot tell an artifact from a string the user reads, and it
+   would translate the UI.
+3. **Announce the plan in one line and go straight in, no gate.** Invoking `afm refactor` is already the
+   approval (#6). Print: *"Running retroactive adoption: **A** — autonomous scan (stack, folders,
+   entities, README, git, CI and hooks, rule audit) · **B** — materialize the docs · **C** — short
+   interview, intent only (pain, persona, ADR, gotcha) · **D** — § 3.1 forward-only. Review at the end via
+   `git diff`."* If the operator wants to adjust or cancel, they interrupt.
+
+---
+
+## Part A — Code archaeology (autonomous, no operator turns)
+
+**Run `afm refactor --mechanical`** (add `--dry-run` first to see the plan; `--answers <file>` runs it
+headless). One command does every mechanical operation of this part and prints the facts, one
+tab-separated line each. Keep the report: Part B writes it all at once.
+
+### A.1 Stack scan
+
+The command enumerates the manifests first and reads each one, because a workspace root declares the
+tooling and none of the stacks. Reading only the root manifest answers "no stacks here" for a repository
+full of them; measured on 2026-09-04 across nine real JS/TS workspaces, 63 root-level probes were all
+empty while the same probes fired correctly inside the packages. The report records **where** each
+dependency was found, not only that it exists: a stack present in one package out of eight is a true
+finding and a different fact from a stack present throughout. `afm detect --stacks` repeats the scan.
+
+Map the stacks to the opt-in modules with `afm index --triggers` (one row per module with its `detect`
+command), never with a table kept here. A stack with no module (Nest, FastAPI, Bun, BullMQ, Sidekiq) is
+`[TBD]` in the component types of `core/ach`; consider future promotion with `afm promote`.
+
+### A.2 Folder tree scan
+
+The report lists `component<TAB><type><TAB><convention><TAB><evidence>` lines: the dominant folder patterns
+mapped to the universal component types (Procedure-like route handlers, Domain-like pure functions,
+Task-like jobs, Lib-like isolated packages, Adapter-like port implementations). The **observed** shapes stay
+literal on purpose: it is how this op recognises an existing project. Only the convention it writes into the
+consumer's `ach.md` is parameterised by the measured source root. Output: a draft of `ach.md` §1 (macro
+diagram), §2 (folder rules) and §3.1 (the component-type to concrete-stack mapping).
+
+### A.3 Entity scan
+
+The report lists `entity<TAB><name><TAB><relations>` lines read from the project schema (a Prisma schema or
+its equivalent). For each entity: the name goes to `prd.md` §10 (Glossary) with a one-line inferred role,
+and the declared relations (foreign keys, relation attributes) go to a mini ER in ASCII in `ach.md` §1.
+**Do not invent attributes** the schema does not have: if it only has an id, a creation date and a name,
+the glossary says "Entity with a name (details in the schema file)".
+
+### A.4 README + git log scan
+
+Read the README and the recent history yourself: they are prose, and judgment is the point.
+
+- **PRD §1 (Summary):** the first one or two paragraphs of the README, if they describe the product. If the
+  README is only "how to install", mark §1 `[TBD]`.
+- **PRD §4 (implicit RFs):** derived from the commits that open features. List 3-5 candidates as
+  `RF-01..RF-N` with the note *(inferred from commit `<sha>`)*.
+- **PRD §2 (Problem), §3 (Persona), §6 (MVP/success criteria):** typically NOT inferable from code. Mark
+  `[TBD]` directly and ask in Part C.
+
+### A.5 Hard-rule audit
+
+The report lists `audit<TAB><rule><TAB><violations><TAB><recommendation>` lines: the mechanical checklist
+of the hard-rule slots run against the current code. Four slots (3, 8, 9, 14) are demoted principles with
+no trigger: they are skipped, and the report says so. A rule that cannot be audited mechanically (idempotent
+tasks, saga ordering, error classification, boundary validation) gets a quick visual check on sample files,
+or is marked **N/A in the audit and applied forward-only by default**.
+
+**The path constants are measured first** (`src-path`, `domain-path`, `ext`, then the file-size limit and the
+domain prefix), the same way as in bootstrap: skipping this swaps a wrong literal for a placeholder nobody
+fills, which fails silently, this repository's most expensive defect class. The report prints
+`measured<TAB><constant><TAB><value><TAB><evidence>`. Propose each as `<constant> = <measured value>` with
+the count attached, and record `[TBD]` for any the code does not answer (#4). The file-size audit is
+reported against the measured p90, never against a number assumed here: *"p90 = 240; 7 files over the
+proposal"*.
+
+Output: a `rule | trigger | violations found | recommendation` table, for example:
+
+| Rule | Trigger | Violations | Recommendation |
+| --- | --- | --- | --- |
+| 1 — TDD | tests/src ratio | 12 / 184 (6%) | forward-only from `<DATE>` |
+| 2 — file ≤ limit | file lines | p90 = 240; 7 files over the proposal | propose the p90 rounded up, forward-only + split tickets |
+| 4 — zero `any` | typed-escape count | 23 occurrences | forward-only from `<DATE>` |
+| 11 — ADR for arch change | ADR count | 0 ADRs | apply now |
+
+This table feeds Part D (it writes § 3.1 forward-only).
+
+### A.6 Decisions inferable as retroactive ADRs (candidate list)
+
+The report lists `adr-candidate<TAB><stack>` lines. Decisions that **were probably intentional** and still
+load-bear: the chosen stack ("tRPC instead of REST", where switching breaks every typed client), the ORM
+("Prisma instead of Drizzle", declarative schema plus generated migrations), the runtime or deploy target
+("Trigger.dev instead of BullMQ", ergonomics plus observability) and the adoption of a custom design
+system. This list feeds C.9.4.
+
+**Do NOT list as candidates:** naming conventions (emergent patterns, not decisions), a dependency version
+(state, not a decision), folder structure (it goes in `ach.md` § 2, not an ADR).
+
+### A.7 CI and hooks scan (input for DoD + pre-push)
+
+The report lists `check<TAB><check><TAB><stage><TAB><source>` lines, and `pr-flow<TAB>yes` when recurring
+merges or a CODEOWNERS file show a PR flow. Each check is classified (`test`, type check, `lint`, `build`)
+and by the stage it runs at: **CI on a PR or on a push to a protected branch** is a candidate for the
+**DoD**, a **pre-push hook** for **pre-push**, and a PR flow points to a protected main branch, a candidate
+for the "no direct commits to main" rule (`afm path interview/bootstrap` § Step 5). Output: two
+pre-marked sets for C.9.6. Discovery-by-evidence is not invention (#5): what gates today is a fact. Whether
+it *should* gate is what the operator confirms.
+
+---
+
+## Part B — Draft materialization + presentation
+
+### B.7 — Fill the docs from the report
+
+`afm refactor --mechanical` already wrote the skeleton, and never over a file the operator has: `prd.md`,
+`ach.md`, `afm.md` and `ust.md` with the measured constants filled and `[TBD]` where the code answers
+nothing; `adr/0000-template.md`; empty `gotchas/` and `rules/`; every rubric and pattern; `AGENTS.md` with a
+block recording the retroactive date; the per-harness stubs; and `docs/.afm-version`. Fill the gaps from
+Part A, marking `[TBD]` for every one left:
+
+- **`docs/prd.md`:** §1 from A.4; §2 and §3 `[TBD]`; §4 from the A.4 commits with an origin note; §6
+  `[TBD]`; §10 from the A.3 entities.
+- **`docs/ach.md`:** §1 from A.2 and the A.3 mini ER; §2 from the observed tree; §3.1 the A.2 mapping; §3.2+
+  empty or `[TBD]`. Apply `modules/<stack>/ach.patch` (read it with `afm path`) for each stack detected.
+- **`docs/afm.md`:** §1.1 and §1.2 from the universals; §1.3 `[TBD]` (project-specific principles come from
+  the interview); §3 carries **all** the rules (the file numbers slots up to 21; never copy a prefix, since
+  17-20 and the INALIENABLE 21 live at the end and a "1-16" copy drops them in silence); §3.1 is filled in
+  Part D; §6 and §6.1 are `[TBD]` until C.9.6. Apply `modules/<stack>/rules.patch` for each stack.
+- **`docs/ust.md`:** reverse-engineer from existing tests whose `describe`/`it` reads like a story,
+  US-001 onward, with the origin (`*test ref:* path/to/test`). With no narrative tests leave it empty with
+  the note "*USs to be created as features evolve*". The persona in each US is `[TBD]` (it comes from
+  Part C).
+- **`docs/gotchas/`:** empty. For each detected stack with a `gotchas.seed`, **do not copy it as active**:
+  add a commented block at the end with the seeds, for the operator to review.
+- **The gate** is the CLI, so nothing is copied into `docs/tools/`. **In a brownfield project run
+  `afm gate --baseline` as soon as the first runner exists**: the code predates the rule by definition, so
+  the gate would start red, and a gate that starts red is disabled the next day. The baseline turns what
+  HEAD already breaks into declared debt that only decreases. `afm install git` arms it when the
+  operator asks.
+- **`docs/rubrics/` and `docs/patterns/`** were copied from the lists `afm index --type rubric` and
+  `afm index --type pattern` give: no hand-written names (a hand-written set of eight rubric names shipped
+  until 3.40.0 while twelve existed, and four never reached a refactored project). The path-constants
+  measurement of A.5 filled their placeholders. A pattern only ever *suggests*; it becomes a convention
+  when the operator accepts one in C.9.7.
+- **`docs/code-style/`:** **not written here.** Every code-style seed is opt-in item by item, asked in
+  C.9.7. Writing it during this no-gate step would apply what the operator has not yet seen. (`evolution/`
+  is not materialized either: it appears on demand at the first `afm evolve` cycle.)
+
+### B.8 — Report
+
+Report a summary + paths, **no review gate** (#6). Review happens via `git diff`, since the docs are
+already on disk:
+
+```
+I materialized the docs (+ rubrics/ + patterns/) in docs/ based on the scan. Summary:
+
+- prd.md: N [TBD] (problem, persona, MVP, "why now").
+- ach.md: diagram + inferred component types. 1 [TBD] in § 3.2 project-specific conventions.
+- afm.md: all hard rules + the forward-only ones (filled in the next part). DoD/pre-push pre-filled from A.7.
+- ust.md: N stories inferred from tests. Persona in [TBD].
+- gotchas/: empty. K seeds from detected modules available in a comment.
+- rubrics/, patterns/: copied. Nothing in patterns/ is a rule until you accept one, next in C.9.7.
+- code-style/: nothing yet. Coming up next, item by item.
+
+Review: git diff. To see a whole doc, just ask. Moving on to intent questions.
+```
+
+Go straight to Part C. No need to ask "want to review?".
+
+---
+
+## Part C — Short gap interview (turns with the operator)
+
+**Principles** (mirror bootstrap): ONE question per turn. Validate by rephrasing ("I understood: X.
+Correct?"), then `afm ask confirm --scope <slug>`. If the operator says "I don't know", accept `[TBD]`. Do
+not guess.
+
+### C.9 — Questions
+
+- **C.9.1 Pain (free text):** *"In 1 sentence: what pain does this product solve?"* Rephrase, validate with
+  `afm ask confirm --scope refactor-pain`, fill `prd.md` § 2.
+- **C.9.2 Persona (free text):** *"Who is the primary user, in 1 sentence (role + context)?"* Rephrase,
+  validate with `afm ask confirm --scope refactor-persona`, fill `prd.md` § 3.
+- **C.9.3 Validate the README summary:** state *"I inferred the product summary from the README as: «X»"*,
+  then `afm ask confirm --scope refactor-summary`. Correct `prd.md` § 1 per the answer.
+- **C.9.3b App-facing string language:** already answered in the pre-check by `afm ask init`: fill
+  `prd.md` § 11.1 from it. Nothing is asked twice.
+- **C.9.4 Retroactive ADR candidates:** list the A.6 decisions that still load-bear, then `afm ask refactor`. Criterion: if the operator swapped it tomorrow, would someone need a doc to explain why? Yes
+  means ADR, no means skip. For each chosen one: `afm adr new <slug> --title "<title>" --description "<one sentence>"`, then fill the sections from the A.6 reasoning and mark the status
+  `Accepted (retroactive, created by afm refactor)`. For each unchosen one: leave it out (a dead decision
+  does not become an ADR later).
+- **C.9.5 Gotcha seeds:** the same `afm ask refactor` round asks which seeds of the detected stacks the
+  team has already been bitten by (read each with `afm path modules/<stack>/gotchas.seed`). Seeds are
+  *candidates*: they activate only if the operator confirms "this has already happened here". For each
+  confirmed one: `afm gotcha new <slug> --basis bitten-twice ...` (see `afm path ops/gotcha`), and drop it
+  from the commented block. Then ask in free text: *"Do you remember other gotchas that are not on this
+  list?"* and register each through `afm gotcha`.
+- **C.9.6 DoD + pre-push, recommendation-first with the A.7 defaults:** the checks found in A.7 come
+  **already checked**. What gates today may not be the desired target, so the question is a confirmation
+  ("is this what *should* gate, or do I adjust it?"). `afm ask gates` fills `afm.md` § 6 and § 6.1. With A.7
+  empty **and** nothing checked: `[TBD]` plus the note "define before the first merge after adoption".
+- **C.9.7 Code-style seeds, one round per detected stack:** for each stack, list the files
+  `afm index --type code-style` reports under `code-style/<stack>/` plus `code-style/_any/`. Each is a house
+  convention the module's author observed in one project (naming, test placement, a file-size ceiling, an
+  error-boundary shape, an import order), never a fact of the stack. State in one line what each decides,
+  then `afm ask code-style`. Materialize only the marked items, verbatim, into
+  `docs/code-style/<stack>/<concern>.md`. An unmarked item is written nowhere. **Default = nothing marked,
+  nothing applies**: the opposite default from the rubrics and modules already copied, and deliberately so.
+
+---
+
+## Part D — Forward-only rules
+
+### D.10 — Write `afm.md` § 3.1
+
+From the A.5 table, materialize the section in `docs/afm.md`:
+
+```md
+## 3.1 Forward-only rules
+
+Retroactive adoption through `afm refactor` on <YYYY-MM-DD>. The rules below apply to **new code from this date on** and to **files you modify** (boy-scout rule). Legacy code that violates them is tracked tech debt, not a PR blocker. **This holds even for `INALIENABLE` rules.** Inalienable means the operator cannot switch the rule off. It does **not** mean the rule rewrites legacy code. A retroactive requirement would make adoption impossible in any codebase that did not start under it.
+
+| Rule | Why forward-only | Tech debt tracked in |
+| --- | --- | --- |
+| 1 — TDD | Current coverage: <X>%. A retroactive sweep would take months. | `[TBD — open an issue or an ADR]` |
+| 4 — zero `any` | <N> occurrences across <M> files. Incremental migration. | `[TBD]` |
+
+**Boy-scout criterion:** when you edit a legacy file that violates a forward-only rule, bring it into conformance in the same PR if the PR scope justifies it. Do not force a 500-line refactor to fix a typo. Otherwise open a separate issue and link it.
+```
+
+**Granularity: autonomous default (#6), no gate.** Materialize the table with **forward-only from today +
+boy-scout**, the right default in most cases, and report it with a non-blocking note: *"Forward-only from
+today + boy-scout by default. If you want a mandatory sweep (with a deadline) or rule-by-rule granularity,
+tell me."* The operator adjusts it in review if they want. Do not block materialization with a question.
+
+### D.11 — `docs/.afm-version`
+
+Written by `afm refactor --mechanical` with the version in use. Check that it is there; do not hand-write
+the version.
+
+### D.12 — Instruction files
+
+`AGENTS.md` is the canonical, tool-agnostic file and `afm refactor --mechanical` wrote it, plus a stub per
+answered harness that imports it. If the repo already had an `AGENTS.md`, only the managed AFM block was
+merged in: never duplicate a rule. The block carries the **retroactive adaptations**: the note *"This
+project adopted AFM retroactively on `<YYYY-MM-DD>`, through afm v`<VERSION>`"*, `afm.md` flagged as
+including § 3.1 forward-only (inherited rules apply only to new code plus boy-scout edits), and `adr/`
+flagged as including the retroactive ADRs from adoption. Add the ADR note once C.9.4 created any.
+
+---
+
+## Closing
+
+1. **Report the `[TBD]` items left, no gate; reconcile takes over.** List each open item (file + section,
+   for example `prd.md § 3 Persona`) in the closing summary and in the commit note. Do not force filling
+   it now: `afm reconcile` (always-on) watches the `[TBD]` items and proposes filling them as the product
+   evolves. If the operator wants to close one right away, they ask. It is not a gate.
+2. **Generate the indexes and check:** `afm index --materialize`, `afm index --check`, then `afm doctor`.
+   The PRD has § 1 + § 2 + § 3 + at least 1 RF; the ACH has a diagram + mapped component types; the AFM has
+   rules + § 3.1 forward-only + DoD (or `[TBD]`); the UST has at least 1 US (even from an existing test; if
+   not, empty with a note is fine); `.afm-version` points to the version in use; the retroactive ADRs chosen
+   in C.9.4 are in `docs/adr/`.
+3. **Suggested commit:**
+   ```
+   docs(afm): retroactive adoption through afm refactor — afm v<VERSION>
+
+   Materializes PRD/ACH/AFM/UST/gotchas from code archaeology + a gap interview.
+   Forward-only rules from <YYYY-MM-DD>: <list>.
+   Retroactive ADRs: <numbered list>.
+   Open [TBD] items: <list>.
+   ```
+4. **Reminder for the operator:** the refactor is closed. `docs/` is now a living source that evolves
+   alongside the code through passive reconcile: every session watches the signals in
+   `afm path interview/triggers` and proposes an edit to the right file, with no explicit command.
+   Forward-only in § 3.1 is not an excuse to stop: boy-scouting an edited file keeps the improvement
+   gradient going. The ops `afm gotcha`, `afm adr`, `afm rule` and `afm promote` stay available on demand.
+   The single test for memory versus doc: *if another dev needs to know it to avoid breaking things, it is
+   a doc.*
+
+---
+
+## Anti-patterns
+
+- ❌ **Inferring persona or pain from code.** Code does not reveal this. Always `[TBD]` + ask in Part C.
+- ❌ **Inventing an entity not in the schema.** If the schema has only 3 entities, the glossary has 3.
+- ❌ **Applying a retroactive hard rule without a forward-only flag.** This will lock up PRs.
+- ❌ **Writing an ADR for every inferred decision.** Only for decisions with a present symptom
+  (load-bearing). Does swapping it hurt? ADR. Does swapping it not hurt? A note in `ach.md`, or skip it.
+- ❌ **Materializing step by step and asking for confirmation.** Bootstrap does this because the answers
+  come from the operator. Refactor does an autonomous scan and materializes-and-reports. Per-file
+  confirmation is needless friction (#6).
+- ❌ **A "start?", "want to review?" or "adjust granularity?" gate.** Invoking `afm refactor` is already the
+  approval (#6). Announce, materialize, report. Review happens via `git diff`.
+- ❌ **Asking DoD/pre-push blind.** What gates merge and push is in CI and hooks, and the report lists it.
+  Confirm what was found (#2). A blank selection is only for when A.7 finds nothing.
+- ❌ **Forcing `[TBD]` items to be filled at closing.** Report the list and let `afm reconcile` propose it
+  later. `[TBD]` beats pressure for a rushed answer (#4).
+- ❌ **Skipping Part A to go straight to the interview.** Without the scan this becomes a badly-run
+  bootstrap ("tell me what you remember about the product"). The operator adopted AFM retroactively because
+  the doc did not exist; they probably do not remember everything the code does, either.
+- ❌ **Activating gotcha seeds without the operator's confirmation.** Seeds are *candidates*. They activate
+  only if the operator confirms "this has already happened here".
+
+---
+
+## Refactor success criteria
+
+- The generated doc is useful **without** the operator having to edit it by hand (except filling `[TBD]`
+  and validating retroactive ADRs).
+- No section contains invention beyond what the code shows or the operator answered.
+- Another dev can clone the repo, read `docs/`, and understand the product and the architecture, including
+  the rules in force and what is forward-only, without having to ask.
+- Forward-only never becomes an excuse to never improve legacy code. The boy-scout rule in § 3.1 keeps the
+  improvement gradient going.
+- **Only genuine intent spends a turn.** Zero ceremony gates (start, want-to-review, granularity, pending
+  items). Nothing discoverable (stack, folders, entities, DoD, pre-push) is asked: it comes from the scan.
+  What is left to ask is pain, persona, problem/MVP, load-bearing ADR and lived gotcha.

package/content/interview/triggers.md

@@ -0,0 +1,107 @@
+---
+type: interview
+description: The signals that reconcile watches to know a doc edit is due.
+load: cold
+---
+
+# Triggers — Signals for Doc Evolution
+
+> This doc gives instructions to the agent. The agent reads it every session, detects a signal and proposes an edit. The agent does not apply the edit alone.
+
+---
+
+## Single Principle
+
+Invariant principle #1 (see [`../PRINCIPLES.md`](../PRINCIPLES.md)): the agent's memory holds no project rule. It holds only the user's style. Here is the direct application:
+
+Use this one hard criterion to decide where something goes:
+
+> "If another developer (or another agent without my memory) needs this fact to avoid breaking something, it belongs in a doc, not in memory."
+
+Memory holds only:
+- The user's communication style (terse vs. verbose, no emoji, and so on).
+- A durable preference (small PRs vs. large bundles).
+- Personal context (role, years of experience, current focus).
+
+Project knowledge always goes into `/docs/`.
+
+---
+
+## Trigger Table
+
+Every session, watch for these signals. When one fires, propose the edit to the user. Do not apply it alone. The user approves, then the agent edits.
+
+| Signal observed during the session | Affected doc | The agent's action (ready-made line) |
+| --- | --- | --- |
+| A new structural decision (a new layer, a new first-class component, a new cross-module contract, a folder refactor) | `ach.md` + new `adr/NNNN-*.md` | "I just proposed X, and that is an architectural decision. Do you want me to draft an ADR and update ACH before we merge?" |
+| The same runtime/SDK surprise blocked us 2 times | `gotchas/` | "This behavior confused me before. I will log it in gotchas with an explicit trigger: 'If you edit X, read this first.'" |
+| The user corrected the approach with a reusable rule ("no, never do Z") | `afm.md` § 3 (hard rule) or § 5 (off-track signal) | "I will add this as a hard rule. What mechanical trigger detects the violation? (`grep`, a checklist, and so on)" |
+| **A catalog guardrail whose `signal` field matches this project** — run the `signal` field from `../guardrails/*.md` (it returns 0/1), and the gate is not yet installed. **One line covers the whole catalog**: the catalog grows, this row does not | `../guardrails/<id>.md` (read) + an install proposal | "This project matches guardrail `<id>`'s signal: `<the command that matched>`. Once installed, it becomes trigger `<trigger>`. Installing writes **outside `docs/`**, so I will not do it alone (bright line). I will bring you the constant to fill in and the possible surfaces, so you can choose where it runs. Want to see it?" |
+| **A hard rule whose trigger is an ad hoc command where a versioned script already exists** — the `*Verification:*` field of a § 3 rule rewrites in prose what a repo `test/*.sh` already does | `afm.md` § 3 (the rule) | "Rule N verifies with a hand-written command, and `<script>` already does this in a versioned form. Should I point `*Verification:*` at the script? Rewriting the command in prose creates a second source of truth that drifts on its own." |
+| The user accepted a counterintuitive approach ("the single bundled PR was right here") | `afm.md` § 5 (validated) or ADR | "Do you want me to log this as a validated decision? (So another agent or developer does not undo it.)" |
+| A new component appeared (a 3rd caller of a helper, a new module, a promoted library) | `ach.md` § 3 + naming convention | "I promoted X from inline code to `lib/`. Should I update ACH § 3.2 and add a canonical example?" |
+| **Primitive boilerplate grew** — the same fixed-order sequence of primitive calls repeats ≥3 times, AND the wiring hides the intent at those sites, AND a reusable grammar exists (composition, ordering, branching) | candidate `adr/NNNN-*.md` + check `rubrics/when-to-create-dsl.md` | "I noticed the same wiring sequence repeated in N places, and the boilerplate hides the intent. A DSL (builder or combinators) may help. This is an architectural change (rule 11), so **I will not build it alone**. I will bring you an API sketch and a candidate ADR for you to decide. Want to see it?" |
+| **A doc gave bad guidance at apply time** (the `reflect` behavior accumulator) — I applied a rule or section from **one** core doc, and it was ambiguous (I had to reread it, or read it two ways), it led me to an error, or the user corrected me against that specific doc ≥2 times in the session. **This accumulates** (do not propose on every turn — the default threshold is ≥2 events per session, but an explicit user complaint unlocks it right away) | suggest `afm reflect` (instructiveness refinement) | "Rule/section X guided me poorly today (ambiguous, stale, or I hit this 2 times). Running `afm reflect` lets me propose making it more assertive. I add nothing new, I only refine what exists. Want me to?" |
+| **A lived contradiction between docs** (Class B of evolve) — I followed **two** core docs that contradict each other in the same task | suggest `afm evolve` (health cycle) | "The docs contradict each other on X (I hit this 2 times in this session). This is not a one-off fix. Running `afm evolve` can diagnose the whole instance's health and propose a package. Want me to?" |
+| **Perceived bloat at apply time** (Class B of evolve) — while loading context, a notably redundant or duplicated core doc got in the task's way | suggest `afm evolve` (health cycle) | "`afm.md` or `ach.md` looks bloated or duplicated, and it got in the way just now. If you want, `afm evolve` can audit the instance (with `wc`/grep, real evidence) and propose a trim at the gate. I apply nothing without your approval." |
+| **≥2 similar gotchas accumulated** (the `generalize` mechanism) — I saw 2+ gotchas/rules in `gotchas/` that share the same abstract cause (one more general instruction would have prevented all N) | suggest `afm generalize` (semantic consolidation) | "These N gotchas say the same thing in different cases. Running `afm generalize` can merge them into one abstract rule (with a tombstone on the originals, no lost provenance). This cuts bloat at the root. Want me to?" |
+| **Staleness or misplaced info** (the `restructure` mechanism) — a doc references code that changed and was not updated (likely, per `git log`), OR I searched for guidance that **exists** but sat in the wrong doc or section | suggest `afm restructure` (context architecture) | "`<doc>` may be stale versus `<path>` (it changed since the doc's last edit), or guidance X was buried where I did not look. `afm restructure` proposes an update or a move at the gate. (If the info does **not** exist anywhere, that is a case for `afm gotcha`, not restructure.)" |
+| **A failure crossed the § 5.1 terminal condition** (a test/`tsc`/command returned non-zero and stayed unresolved past the retry cap, OR the user explicitly corrected the approach) | the failure store of the AFM state directory (the failure hook logs it) + suggest `afm remediate` | "This failure crossed the retry cap, or you corrected me. The failure hook already recorded it with the external signal (`sig=`). If it recurs (≥2 times) or you confirm, I will run `afm remediate` to turn it into a procedure (mechanical) or a learning (conceptual)." |
+| **The same failure `sig=` recurred ≥2 times** (recurrence: `afm failures promotable` lists it) | suggest `afm remediate` (CRITIC loop) | "This failure recurred. Running `afm remediate` can resolve it for good — a runbook (`procedures/`) for a mechanical sequence, or a `learnings/` entry for future agent sessions if it is conceptual. I apply nothing without your approval." |
+| **A repeatable operational sequence ran ≥2 times** (a release, deploy, or migration done by hand again) | `docs/procedures/` via `afm remediate` | "You did this sequence (release, deploy, or migration) by hand ≥2 times. I want to turn it into a `docs/procedures/` runbook with a 0/1 check per step. May I?" |
+| **An artifact was written in a language other than English**, and `prd.md` § 11.1 does not say that language is the product's own | `prd.md` § 11.1 (read first) + the artifact | "I wrote `<file>` in `<language>`. Artifacts are English (the rule), and the ONE exception is the strings your users read, which `prd.md` § 11.1 declares. That field says `<value>`, so this file is not covered by it. Should I rewrite it in English, or is this a product string that belongs in the exception?" **Read § 11.1 before you fire this.** With `[TBD]` there, ask which of the two it is — never assume the file is a violation. |
+| A feature started with no matching US | `ust.md` | "I found no matching US. Do you want me to create US-NNN before I start implementing?" |
+| A product scope change (an RF cut or addition) | `prd.md` § 4 | "This changes RF-NN. Should I update the table and note in the PRD?" |
+| The user asks to DELIVER a feature ("build feature X", "implement X", "deliver X end to end") | `deliver` flow (`afm.md` § 2.2) | "I will run the autonomous delivery: scan the code, research libraries through nasca, ask you only what I cannot infer, build the plan for one approval, and execute to the end. May I? (Say 'go' and I go straight through.)" |
+| An in-progress change reaches >200 lines / >3 files, OR it crosses layers, OR it adds a new external boundary | new `docs/features/NNN-*/` via `deliver` | "Should I promote this to a feature folder and deliver it via `afm deliver`? It runs discovery, builds a plan for one approval, and executes to the end." |
+| The user is about to start T001 in `tasks.md` for a feature, and `analyze` has not run this session | `analyze` (suggestion) | "Before starting T001 for this feature, should I run `afm analyze` to catch coverage gaps?" — suggest once per feature, do not repeat. |
+| I learned a pattern about the user (a durable style preference) | memory | save it in the agent's memory as a durable preference |
+| I learned technical knowledge about the project | doc | edit the doc (`afm`, `ach`, `prd`, `gotchas`, `adr`) |
+| The learning generalizes to any project | propose a change to the AFM template content | see `promotion.md` |
+
+---
+
+## Concrete Examples (Training)
+
+### Example 1 — A Gotcha Emerges
+
+**Session:** the user and the agent debug for 30 minutes: "this tsdown subprocess breaks with `type: commonjs`." They fix it. It works.
+
+**Signal detected:** "the same runtime surprise blocked us 2 times." The user mentioned it had confused another developer before.
+
+**Proposed action:** "I will add a `gotchas/` entry. Read it before you edit emit/package-json.ts or move the tsdown binary. `type` stays `module`, even in format=cjs. Do you also want ADR-0003 with the full decision?"
+
+### Example 2 — A New Rule Emerges from a Correction
+
+**Session:** the agent implemented `domain_X`, which imports `TRPCError`. The user flags it: "Domain code never imports a transport error. Map code to TRPCError in the procedure."
+
+**Signal detected:** "the user corrected the approach with a reusable rule."
+
+**Proposed action:** "I will add hard rule 15 to `afm.md` § 3: 'Domain code never imports TRPCError. Use DomainError({ code: ... as const }). The procedure maps it at the boundary.' Mechanical trigger: `grep -rn 'TRPCError' {{src-path}}/server/modules/**/domain/` returns 0. Correct?" (`{{src-path}}` is the project's measured source root — see `bootstrap.md` § Step 5 "Rule constants" or `refactor.md` § A.5. Pasting this example with a literal `src/` would hardcode a house layout as a consumer's hard rule for a project whose real root is `app/` or `lib/`.)
+
+### Example 3 — Promotion to the Template
+
+**Session:** a new project learned that a Stripe webhook can arrive 2 times, and it needs an idempotent UPSERT. The user confirms the rule.
+
+**Signal detected:** "the learning generalizes to any project" — this applies to every project that uses Stripe.
+
+**Proposed action:** "This rule (`idempotent webhook UPSERT via unique stripeSubscriptionId`) applies to any Stripe project. I just added it to `/docs/gotchas/`. Do you also want me to propagate it to the `modules/stripe-billing/gotchas.seed.md` of the AFM template content? Then your next project gets it for free."
+
+---
+
+## Anti-Patterns
+
+- ❌ **Apply an edit without proposing it first.** The user decides what goes into the doc.
+- ❌ **Save a project rule in memory.** This violates the single principle. Memory is not a doc.
+- ❌ **Invent a gotcha without the 2-time trigger.** A gotcha comes from real use, not imagination.
+- ❌ **Promote to the template before the user confirms.** The learning may be project-specific.
+- ❌ **Propose an edit on every turn.** Accumulate signal across the session, then propose when it carries weight.
+
+---
+
+## When NOT to Propose
+
+- A trivial change (a variable rename, a lint fix, a typo).
+- A refactor with no new learning (code moves, but behavior does not change).
+- A bug fix that reveals no rule (it was a typo, not a decision).
+- An exploratory session that has not converged — wait for it to settle.

package/content/modules/nextjs-app-router/ach.patch.md

@@ -0,0 +1,44 @@
+---
+type: module
+description: 'Adds the Server/Client Component split to the materialized ACH. The folder tree, the UI-primitive location, and the route-group/handler-delegation convention are opt-in seeds — see the pointers below.'
+load: cold
+stack: nextjs-app-router
+patches: 'docs/ach.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("next")' package.json >/dev/null 2>&1; else grep -q '"next"' package.json 2>/dev/null; fi
+---
+
+# Patch — ACH for Next.js App Router projects
+
+> This patch applies to `/docs/ach.md`. Insert the sections below at the marked points.
+
+## §2 — Add to the folder tree
+
+> Whether the App Router root sits at the repo root (`app/`) or under `src/` (`src/app/`) — Next.js
+> accepts both — and how a route group under it gets named, are house choices, not a Next.js
+> requirement. They now live as an opt-in seed at `code-style/nextjs-app-router/naming.md`
+> (concern: naming). Materialize it only if the operator accepts it.
+
+## §3 — Add the UI primitives component
+
+> The `src/components/` location this patch used to state as fact for UI primitives is the same
+> house choice as the folder root above — Next.js has no opinion on where a component lives. It
+> now lives in the same opt-in seed, `code-style/nextjs-app-router/naming.md` (concern: naming).
+
+## §6 — Add dashboard routing
+
+> The route-group split this patch used to state as fact (`(protected)/` vs `auth/`) and the
+> "route handlers stay thin and delegate to `server/`" rule are both house convention, not a
+> framework requirement. They now live as opt-in seeds at
+> `code-style/nextjs-app-router/naming.md` (concern: naming, for the route-group split) and
+> `code-style/nextjs-app-router/imports.md` (concern: imports, for the delegate-to-`server/`
+> rule). Materialize either only if the operator accepts it.
+
+## Additional hard rules
+
+(number these starting from the next free slot in `afm.md` §3)
+
+- **Server Component is the default. Use "use client" only where you need interactivity.**
+  *Verification:* `grep -rn "use client" src/app app 2>/dev/null` reviews each context. Each match must justify itself (a form, a state hook, a DOM event).
+- **Do not fetch directly in a Server Component when a typed client is available**. Use the direct server client (`trpcServer`) on the server, and React Query on the client.
+  *Verification:* `grep -rn "fetch(" --include=page.tsx src/app app 2>/dev/null` finds no raw fetch call in a page.

package/content/modules/nextjs-app-router/gotchas.seed.md

@@ -0,0 +1,78 @@
+---
+type: module
+description: 'Seed gotchas for the App Router, starting with cookies() and headers() being valid only in a Server Component or a route handler.'
+load: cold
+stack: nextjs-app-router
+patches: 'docs/gotchas/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|has("next")' package.json >/dev/null 2>&1; else grep -q '"next"' package.json 2>/dev/null; fi
+---
+
+# Gotchas seed — Next.js App Router
+
+> Each entry below is a complete gotcha file. Copy one to `docs/gotchas/NNN-slug.md` (the first `---` of the entry as line 1) only when it bites in real use. Do not copy everything proactively. Re-date `last_bite` on copy.
+
+---
+type: gotcha
+description: 'cookies() and headers() from next/headers work only in a request context (Server Component, route handler, server action) and throw everywhere else.'
+load: warm
+fires_on: event
+fires_when: 'you use cookies() or headers() from next/headers in a pure library or in a Client Component.'
+bites: 1
+last_bite: 2026-10
+refs:
+  - 'node_modules/next/dist/docs/01-app/02-api-reference/04-functions/cookies.mdx'
+---
+
+## Next.js — `cookies()` / `headers()` work only in a Server Component or route handler
+
+## Behavior
+
+Both functions work only in a request context: Server Component, route handler, or server action. Everywhere else, they throw an error at runtime.
+
+## Solution
+
+Read cookies in the Server Component or route handler. Pass the value to the client component as a prop. Never import `next/headers` in code that can run in the browser.
+
+---
+type: gotcha
+description: 'revalidatePath and revalidateTag invalidate the Next.js cache only; React Query keeps its own client cache, so a mutation must also invalidate the client query.'
+load: warm
+fires_on: event
+fires_when: 'you are in a route handler or server action and want to refresh the client cache.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Next.js — `revalidatePath` / `revalidateTag` do not invalidate React Query
+
+## Behavior
+
+`revalidatePath` invalidates the Next.js cache (RSC + fetch). React Query keeps its own cache on the client. A server action that mutates data must also invalidate the client query. This does not happen automatically.
+
+## Solution
+
+Return a signal to the client that triggers `queryClient.invalidateQueries(...)`. Or use a stack client that already integrates this, for example `@trpc/tanstack-react-query`, which invalidates automatically in `onSuccess`.
+
+---
+type: gotcha
+description: 'A root layout under a dynamic segment (app/[lang]/layout.tsx) leaves the internal _not-found route with no root layout, so the build fails or serves a raw 404.'
+load: warm
+fires_on: event
+fires_when: 'you delete app/layout.tsx and move <html>/<body> to app/[lang]/layout.tsx (an i18n pattern, for the correct lang at SSR).'
+bites: 1
+last_bite: 2026-10
+refs:
+  - 'node_modules/next/dist/docs/.../file-conventions/not-found.md (section global-not-found.js)'
+  - 'node_modules/next/dist/docs/.../layout.md (root layout under a dynamic segment)'
+---
+
+## Next.js — a root layout under a dynamic segment orphans `_not-found`
+
+## Behavior
+
+Next.js generates an internal `/_not-found` route that lives **outside** the `[lang]` segment. It then has no root layout to compose the document. The build fails (the `_not-found` page has no root layout) or serves a raw 404. Non-locale paths that escape the proxy redirect (for example `/foo.bar`, with a dot) fall into the same gap.
+
+## Solution
+
+Add `app/global-not-found.tsx`. It returns its own complete HTML document (`<html><body>…`, default lang, provider-free, because it bypasses layouts). Enable it with `experimental.globalNotFound: true` in the Next.js config (Next.js 15.4 or later). The `notFound()` of localized routes still resolves in `app/[lang]/not-found.tsx` (inside the layout, with the correct html lang and theme).