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

package/content/interview/bootstrap.md

@@ -0,0 +1,417 @@
+---
+type: interview
+description: The greenfield interview that materializes a new instance.
+load: cold
+---
+
+# Bootstrap — interview script
+
+> This doc is an instruction **for the agent** when the operator runs `afm init` (or asks for something
+> equivalent, like "set up the project doc"). The CLI materializes everything a repository can answer; this
+> script runs the interview for what only the operator knows, a 7-step one, and fills the result into `docs/`.
+
+---
+
+## Invariant principles (do not violate)
+
+**AFM universals**: see the single canonical source, `afm path PRINCIPLES` § Universals (§1-8). They apply
+here. In particular:
+
+- **#2** (discover-first): `afm init --mechanical` already scanned the repo. Where it found a signal (a
+  manifest with real dependencies, existing CI or hooks), bring it as the recommendation BEFORE you offer
+  options. Do not ask a blank question about what the repo already shows.
+- **#4** (`[TBD]` beats invention): bootstrap never guesses the operator's answer.
+- **#5** (do not invent an entity, rule or module): write only what the operator said.
+- **#8** (questions are data, recommendation-first): every confirmation or selection with closed options
+  goes through `afm ask <op>`, whose questions live in `content/questions/<op>.questions.yaml` and carry
+  the recommended option. Free text is only for genuinely open questions (describe the product or the pain,
+  list entities, describe a flow).
+
+**Specific to the bootstrap interview** (rules for *running* the interview, not for the methodology):
+
+1. **A pre-filled suggestion beats a blank question, wherever a signal exists (#2 + #8).** The report of
+   `afm init --mechanical` is the signal. Every suggestion still needs the operator's confirmation: the
+   stack is the operator's decision, so nothing is final without their agreement. Open free-text
+   questions are only for what you cannot infer: product, pain, persona, entities, flows. Ask one thing
+   at a time.
+2. **Validate before you move on.** After each free-text answer, restate it in one line, then
+   `afm ask confirm --scope <step-slug>` (for example `step0-product`). Move on only after `Yes, exact`
+   (or after you process the fix).
+3. **Record what the operator said, nothing more.** If they described 3 RFs, write 3 RFs. Do not add
+   "RF-04 security" because "every project needs it" (universal #5 in the interview context).
+4. **At the end, list every `[TBD]`.** The operator decides whether to fill them in now or later.
+
+---
+
+## Initial setup (before step 1)
+
+1. `afm preflight`. Exit 3 means there is no `docs/.afm-version`: a real greenfield, continue. Any other
+   exit means the project is already bootstrapped: **do not run bootstrap again**. The atomic ops stay
+   available (`afm gotcha`, `afm adr`, `afm rule`), and a newer version is `afm update`.
+2. **Detect the `docs/.template` marker.** If it exists, go to § Alternate branch below.
+3. **Ask the two decisions the mechanical pass needs:** `afm ask init` (harnesses whose instruction files
+   the project covers, and the product's string language). The language is a **product** decision, not a
+   rule: it goes to `prd.md § 11.1`, is declared and never enforced, and is what makes the english-first
+   exception mechanical. Without it, a later language migration (`afm update`) cannot tell an artifact
+   from a string the user reads, and it would translate the UI. `Decide later` records `[TBD]`.
+   The same `afm ask init` asks the artifact language (`en`, `pt-BR`, `es`, `other`), and
+   `afm init --mechanical` records a tag itself through `afm config set language.artifacts <tag>` (the
+   CLI validates the tag and edits `.afm/config.toml`). On `other` it prints that command: run it with the
+   tag the owner names. Never write the key by hand.
+4. **Materialize:** `afm init --mechanical` (add `--dry-run` first to preview). It creates, and never
+   overwrites a file the operator already has:
+   - `docs/{prd,ach,afm,ust}.md` from the shipped skeletons, the project name from the manifest and every
+     placeholder filled by what the code answers, `[TBD]` where it does not;
+   - the five rule constants **measured, not assumed**: the source root and extension (the root with the
+     most non-test files), the file-size limit, the domain-function prefix and its subfolder. The report
+     prints each as `measured<TAB><constant><TAB><value><TAB><evidence>`;
+   - empty `docs/gotchas/` and `docs/rules/`, `docs/adr/0000-template.md`, every rubric and every pattern
+     the index lists (no hand-written list of names: `afm index --type rubric` is the list);
+   - `AGENTS.md` (the tool-agnostic file, canonical) and one stub per answered harness that imports it;
+   - `docs/.afm-version` last, so a run that stops half way can simply be run again.
+   The gate is the CLI (`afm gate`): nothing is copied into `docs/tools/` for it.
+5. **Read the report back to the operator** and go to step 0. A project that maintains the plugin itself
+   calls the shipped content through `afm path` instead of copying it (hard rule 34, one canonical source).
+
+---
+
+## Alternate branch — from-template (active only if setup detected `docs/.template`)
+
+Scenario: the project comes from an architectural template (a clone of a starter with an inherited
+`ach.md`, `afm.md` and `gotchas/`). Stack, rules and architecture are already decided. The interview
+covers only the product.
+
+1. **Read the metadata** from `docs/.template` (JSON). Accept an empty file with the fallback
+   `{"template-name": "<unknown>", "template-version": "<unknown>", "exported-from-afm": "<unknown>"}`.
+   If metadata is missing, record it as unknown; do not invent it (#5).
+2. **Confirm the branch:** `afm ask init-template`. `Product only` runs steps 0, 3, 6 short and 7 adapted;
+   `Full interview` follows the standard flow and ignores the marker for this session (it stays on disk).
+3. On `Product only`, run `afm ask init` and `afm init --mechanical` as in setup: it writes the product
+   docs and the version marker and leaves the inherited `ach.md`, `afm.md` and `gotchas/` untouched. Then
+   **load the technical context** by reading those three inherited files (read-only). Note the stack
+   internally, to cite component types from `ach.md § 3.1` at closing.
+4. Tell the operator: *"Stack, architecture and rules are already set in the template. I will ask only
+   about the product."* Go to step 0.
+
+### Step subset in from-template mode
+
+- **Step 0** (product, pain, persona, metric): full, materializes `prd.md`.
+- **Step 3** (critical flows): full, materializes `ust.md`.
+- **Step 6**, **short version**: one question, `afm ask gates` pre-checked from the inherited DoD in
+  `afm.md § 6`. The operator keeps it or lists the edits.
+- **Step 7**, **adapted**: if the inherited `gotchas/` has entries, keep them unchanged and offer to add a
+  file (do not erase prior discovery, #5). If it is empty, follow the standard flow. Inherited `adr/`
+  files stay. New ADRs are born on demand through `afm adr`.
+
+**Explicit skip:** steps 1 (stack), 2 (data model), 4 (component mapping) and 5 (inherited rules). All of
+that is in the template. Asking again is redundant, and it would break principle #5 if the agent tried to
+"validate" what was already decided.
+
+### Adapted closing (when from-template)
+
+1. **List the pending `[TBD]` items** (usually few: only steps 0 and 3). The operator replies with the ones
+   to fill in now.
+2. **Quick check:** the PRD has §1 + §2 + §3 + at least one RF. The UST has at least US-001. The inherited
+   `ach.md`, `afm.md` and `gotchas/` are unchanged. `docs/rubrics/` exists: if it is missing (a template
+   exported before 3.0.0-rc.5), `afm init --mechanical` copies it without touching what is inherited.
+3. **Add the inheritance line** under the version `afm init` wrote into `docs/.afm-version`:
+   ```
+   <version of the afm in use>
+
+   Inherited from template "<template-name>" v<template-version> (exported with afm v<exported-from-afm>)
+   ```
+4. **Origin note.** Add one bullet in the `## Canonical documentation` section of `AGENTS.md`: the project
+   started from architectural template `<template-name>` v<template-version>; stack, rules and
+   architecture are inherited (`docs/ach.md`, `docs/afm.md`, `docs/gotchas/`).
+5. **Generate the indexes:** `afm index --materialize`, then `afm index --check`.
+6. **Suggested commit:**
+   ```
+   docs(afm): bootstrap from-template — template "<template-name>" v<template-version>
+
+   Materializes PRD/UST from a product-focused interview.
+   Architecture and rules inherited from the template, untouched.
+   Open [TBD] items: <list>.
+   ```
+7. **Reminder for the operator:** the bootstrap is done; `docs/` is now a living source that evolves
+   through passive reconcile (every session watches the signals in `afm path interview/triggers` and
+   proposes edits); the atomic ops (`afm gotcha`, `afm adr`, `afm rule`, `afm promote`, `afm specify`,
+   `afm plan`, `afm tasks`, `afm clarify`, `afm analyze`) stay available on demand. The
+   single test for memory versus doc: *if another dev needs it to avoid breaking something, it is a doc.*
+
+### Anti-patterns of the from-template branch
+
+- ❌ Re-check the inherited stack or rules through a re-ask. It breaks trust in the template; the operator
+  is responsible for keeping the template current.
+- ❌ Modify the inherited `ach.md`, `afm.md` or `gotchas/` during this branch. They are read-only in this
+  session. Changes come through passive reconcile or the on-demand ops.
+- ❌ Invent product details if the operator did not answer step 0 or 3. Use `[TBD]` (#4 and #5).
+- ❌ Skip marker detection in setup: the branch only activates if setup confirmed that `docs/.template`
+  exists.
+
+---
+
+## Step 0 — Problem context (becomes PRD §1, §2, §3)
+
+**Goal:** understand the product, the pain point and the persona. Materializes into `prd.md`.
+
+**Questions (free text; a genuine description does not fit closed options):**
+
+1. *"In 3 sentences, what product are you building, and who is the user?"*
+2. *"What hurts today in this user's flow, without your product?"*
+3. *"What is the success criterion for a session? How do you know the user's job is done?"*
+
+**Validation after each answer:** restate it ("I restated it as: «X»"), then `afm ask confirm --scope step0-q<N>`. Move to the next question only after `Yes, exact` (or after you process the fix).
+
+**Materializes into `prd.md`:**
+
+- §1 Summary: 1 paragraph drawn from answer 1.
+- §2 Problem & Opportunity: the pain (answer 2) plus why now (`[TBD]` if the operator did not say).
+- §3 Persona: extracted from answer 1.
+- §6 MVP acceptance criteria + metric: derived from answer 3.
+- §11.1 App-facing string language: the answer of `afm ask init` from setup, or `[TBD]`.
+
+**Do not invent:** market size; target companies, if none was named; "why now", if no reason was given.
+
+---
+
+## Step 1 — Tech stack (becomes ACH §1, §2)
+
+### 1.0 — The stack scan is already done (gap-driven #2: infer before you ask)
+
+`afm init --mechanical` enumerated the manifests, read each one and printed the stacks per manifest, **and
+where each was found**. Do not re-derive it. A workspace root declares the tooling and none of the stacks,
+so a root-only scan answers "no stacks here" for a repository full of them; the report is per manifest for
+that reason. A stack present in one package out of eight is a true finding and a different fact from a
+stack present everywhere: the operator needs the second half to judge the first. Report the union of the
+stacks and say **where** each was found. `afm detect --stacks` repeats the scan on demand.
+
+- **Signal found:** each layer comes with its evidence (the installed dependency), not with popularity.
+  The question becomes a **confirmation of a suggestion**, not a blank choice. A layer with no signal gets
+  no guessed recommendation: it stays blank for the operator.
+- **Nothing found** (empty repo, no stack named in step 0): ask the layers as open questions in plain
+  conversation (web framework, API layer, DB + ORM, async tasks), with sensible defaults offered where one
+  exists.
+
+### 1.1 — Confirm the stack and the modules
+
+Ask `afm ask bootstrap-stack` (questions in `content/questions/bootstrap-stack.questions.yaml`): the stack
+as reported, and whether to apply the detected opt-in modules. `Leave as TBD` marks the layer `[TBD]` in
+`ach.md` and says: *"I leave the pending layers as `[TBD]` instead of recommending now; a recommendation
+works better once you have also defined what you do NOT want."* An answer outside the options is recorded
+as given, without inventing a module.
+
+**Materializes into `ach.md`:** §1 Macro architecture (an ASCII diagram of the layers based on the fixed
+stack; an open component is a `[TBD]` box) and §2 Folders (a tree following the stack's conventions).
+
+**Opt-in modules.** `afm index --triggers` lists one row per module with its stack and its `detect`
+command; a zero exit means the stack is present. Apply every file under `modules/<stack>/` (read each
+with `afm path modules/<stack>/<file>`) for each hit, unless the operator opted the module out. Do not
+maintain a list of modules here: it was a hand-written list of six stacks until 3.31.0 while seven
+existed, because the prose that named the modules was not the directory that held them. A stack with no
+module (Nest, FastAPI, BullMQ) is `[TBD]` in the component types of `core/ach`. **Do not invent a
+module**: promote it to the shipped content later (`afm promote`) once the learning is proven. A
+`gotchas.seed` is a **commented reference** only, never an active gotcha: the project's `docs/gotchas/`
+starts empty.
+
+**Code-style seeds are opt-in item by item, never wholesale.** For each stack that hit, list the files
+`afm index --type code-style` reports under `code-style/<stack>/` and `code-style/_any/`. Unlike a module
+(applied whole, opt-out), a code-style file is one house convention its author observed in a single
+project: naming, test placement, a file-size ceiling, an error-boundary shape, an import order. It is never
+a fact of the stack. Applying it wholesale would rebuild the defect the split fixed, a `(mandatory)`
+naming convention the operator never got a say in. State what each file decides in one line, then ask
+`afm ask code-style`. **Materialize only what the operator marks**, verbatim, into
+`docs/code-style/<stack>/<concern>.md`. An unmarked item is written nowhere: not as a note, not as a
+commented-out stub. **Default = nothing marked, nothing applies**: the opposite default from modules and
+rubrics, and deliberately so. Silent opt-in is the defect, not a shortcut around it.
+
+---
+
+## Step 2 — Core data model (becomes PRD §10 + ACH §1)
+
+**Question (free text):** *"List the 3-5 core entities of the product and the relation between them, one
+sentence each."*
+
+**Materializes:** a mini ER diagram in ASCII into ACH §1, and one PRD §10 Glossary entry per entity.
+
+**Validate:** show the restated ASCII ER diagram, then `afm ask confirm --scope step2-er`.
+
+**Do not invent** attributes the operator did not mention, nor a relation they did not describe.
+
+---
+
+## Step 3 — Critical flows (becomes UST + PRD §4)
+
+**Questions (one at a time):**
+
+1. *"Describe the main user flow, from the first click to the success state."* Materializes as **US-001**
+   in `ust.md`, with a happy-path Gherkin scenario.
+2. *"And the most likely error flow?"* Materializes as **US-002** or an extra scenario in US-001
+   (depending on scope).
+
+**For each US written, ask** `afm ask rf-mapping --scope <us-id>` (for example `us-001`): which PRD RF it
+implements. A new RF is drafted from the story as RF-01, RF-02 and so on in PRD §4; an existing one is
+named by the operator; `Not yet` records `[TBD]`.
+
+---
+
+## Step 4 — Mapping to the meta-framework (becomes ACH §3)
+
+**Present the generic component types:**
+
+> "AFM works with 5 component types:
+> 1. **Procedure-like**: sync request/response, under 5s.
+> 2. **Domain-like**: a pure business-rule function.
+> 3. **Task-like**: async, retry-safe.
+> 4. **Lib-like**: an isolated, publishable package.
+> 5. **Adapter-like**: a typed port implementation (registries, storages, etc).
+>
+> In your stack:
+> - Procedure-like = {{tool inferred from step 1, e.g. a tRPC procedure}}
+> - Domain-like = {{e.g. an exported TS function with the measured domain prefix}}
+> - Task-like = {{e.g. a Trigger.dev v4 task}}
+> - Lib-like = {{e.g. a folder under the source root with no framework import}}
+> - Adapter-like = {{e.g. a port implementation under `<src-path>/lib/<provider>/<adapter>`}}"
+
+**Confirm:** `afm ask bootstrap-mapping`. **Materializes into `ach.md` §3.1** with the stack's concrete
+naming convention.
+
+---
+
+## Step 5 — Inherited and new rules (becomes AFM §3)
+
+**The inherited rules are already in `afm.md § 3`**: `afm init --mechanical` copied every one. List them
+for the operator with the numbers and headlines **read from `afm.md § 3`**, not from memory. The file
+numbers slots up to 21; four of them (3, 8, 9, 14) are **demoted principles** that live in § 1.3 and carry
+no trigger, so there is nothing to opt out of, and slot 21 is **INALIENABLE**. **Do not renumber to close
+the gap**: the number is the rule's identity, and `afm doctor` compares the instance against the plugin by
+number.
+
+Ask `afm ask bootstrap-rules`. **Default = keep all.** For each rule the operator opts out of, ask why in
+free text and record it with `afm rule na <id> --reason "<why>"`: the index line in `afm.md § 3` becomes
+"N/A — <reason>" and the number stays. **Rules marked `INALIENABLE` do NOT enter this question.** They are
+not silently omitted: list them, with a note that they apply to every project and are not opt-out. Offering
+an opt-out and then refusing it would be worse than not offering one at all (`afm rule na` refuses them).
+
+### Rule constants: measured first, then proposed, never assumed
+
+Five values belong to the **operator, not the framework**: the line limit (rule 6), the domain-function
+prefix (rule 7), the source root, the domain-function subfolder inside it and the source-file extension. A
+default disguised as best practice is invention (#5), and a rule whose constant the owner did not choose is
+a rule the owner turns off at first friction. `afm init --mechanical` already **measured** them from the
+code, and its report carries each value with the evidence. Propose each one with that measurement
+attached: *"your file p90 is N lines, I propose a limit of N rounded up"*; *"your code already uses
+`<prefix>` in X files, I propose it as the domain prefix"*; *"domain-prefixed functions already live under
+`<subfolder>`"*. The operator accepts or changes each.
+
+- **Greenfield project (nothing to measure):** the report proposes `300`, `domain_`, `src`, `ts` (or the
+  extension the chosen stack generates) and `domain`. **State that these are template defaults**, not a
+  measurement. The difference between an assumed default and a chosen default decides whether the rule
+  survives.
+- **The operator does not answer, for any of the five:** the constant stays `[TBD]`. **Say that the rule
+  or path has no trigger until someone fills it in** (#4). Do not invent a value "to make it work": a
+  wrong literal replaced by an unfilled placeholder still fails silently.
+
+**Free-text question:** *"Does your team have a specific rule that applies from day one?"* Examples:
+"every PR needs 2 reviewers", "commits are always in English", "no direct commits to main". A ready-made
+trigger for the last one: `git rev-parse --abbrev-ref HEAD | grep -qE '^(main|master)$'`. If yes, write it
+with `afm rule` (numbers 18–29 are reserved for the template's universal rules; the command picks the next
+free number). Each new rule MUST have a mechanical trigger; without one it becomes a principle in §1.3.
+
+---
+
+## Step 6 — Validation rituals (becomes AFM §6 + §6.1)
+
+**Signal first (gap-driven #2).** The `afm init` report lists the checks the repo already runs (CI on a
+PR, a pre-push hook, a lint-staged entry, a script, a Makefile target) as `check<TAB><check><TAB><stage>`.
+Bring them **pre-marked**: CI on a PR maps to the merge DoD, a pre-push hook to pre-push. The question
+becomes a confirmation. No signal means nothing is pre-marked.
+
+**Ask `afm ask gates`** (two multi-selects, because DoD and pre-push are independent lists). Marking
+nothing in either leaves that section `[TBD]` with the note "define before the first merge". If the
+pre-push sequence needs a specific order or a custom command, ask a follow-up in free text: *"Any extra
+command or specific order for pre-push?"*
+
+**Materializes into `afm.md`:**
+
+- §6 Definition of Done: the options marked for the merge DoD.
+- §6.1 Pre-push validation: the command sequence for a push (for example tests, then the type check, then
+  the build) from the pre-push answer plus the optional free text.
+
+---
+
+## Step 7 — Gotchas and ADRs (start empty)
+
+`afm init --mechanical` already created the structure; this step only decides what stays empty:
+
+- `gotchas/`: empty. A gotcha is one file per entry, and `afm gotcha` writes the first.
+- `rules/`: empty. A hard rule is one file per rule; section 3 of `afm.md` carries one index line per rule
+  in the `N. **title**` shape two hooks parse, and `afm rule` writes both sides.
+- `adr/0000-template.md` exists; `adr/` is otherwise empty. ADRs are born when a real decision happens.
+- `rubrics/` and `patterns/` hold every file the index lists, copied verbatim. They are runnable,
+  stack-agnostic decision tables, the highest-value content at apply time, and the placeholders in them
+  (the source root, domain path and extension) were filled by the measurement of step 5. A pattern only
+  ever *suggests*: it becomes a project norm solely when the operator accepts it, and only then does it
+  materialize into `code-style/`, `ach.md` or an ADR. The copy is not that acceptance.
+- `evolution/` is **not** materialized now. It is born on demand at the first `afm evolve` cycle.
+  `docs/research/` is born the same way, at the first research.
+
+**Do not write a retroactive ADR during the interview.** An ADR is a real decision with a concrete
+symptom. If one comes up during development and is non-obvious, create the ADR at that moment (see
+`afm path interview/triggers`).
+
+---
+
+## Closing
+
+After the 7 steps:
+
+1. **List every `[TBD]`** (file and section, for example `prd.md § 3 Persona`) and let the operator reply
+   with the ones to fill in now. Marked items become free-text questions, one at a time. Unmarked items
+   stay `[TBD]` in the doc and are recorded in the commit note.
+2. **Generate the indexes:** `afm index --materialize`, then `afm index --check`. It writes an `index.md` in
+   every documentation directory plus the bundle-root `index.md` that declares `okf_version`. Hard rule 39
+   fails on a missing or stale index, so a bootstrap that skips this step hands the owner a red gate on the
+   first commit.
+3. **Quick check** with `afm doctor` and `afm gate --worktree`: the PRD has §1 + §2 + §3 + at least RF-01;
+   the ACH has a diagram plus component types mapped to the stack; the AFM has hard rules plus DoD plus
+   pre-push; the UST has at least US-001; `.afm-version` points to the version in use.
+4. **Instruction files.** `AGENTS.md` and the per-harness stubs were written by the mechanical pass. Add
+   the libraries detected in step 1 where the block asks for them. If the repo already had an
+   `AGENTS.md`, only the managed AFM block was merged in, never a duplicated rule.
+5. **Suggested commit:**
+   ```
+   docs(afm): initial bootstrap — afm version <version>
+
+   Creates PRD/ACH/AFM/UST/gotchas/adr from a guided interview.
+   Open [TBD] items: <list>.
+   ```
+6. **Reminder for the operator:** the bootstrap is done. `docs/` is now a living source that evolves with
+   the project through passive reconcile: every session watches the signals in
+   `afm path interview/triggers` (architectural decision, runtime surprise 2x, correction with a reusable
+   rule, gotcha, etc.) and proposes an edit to the right file. There is no need to run `afm init` again.
+   The ops `afm gotcha`, `afm adr`, `afm rule` and `afm promote` stay available on demand, for when the
+   operator wants to be explicit. The single test for memory versus doc: *if another dev needs it to avoid
+   breaking something, it is a doc.*
+
+---
+
+## Interview anti-patterns
+
+- ❌ Fire 5+ free-text questions in the same turn: the operator loses context. (`afm ask` renders several
+  structured questions together, and that is fine: each one is a click, not typing.)
+- ❌ "Do you want X or Y?" without having heard the problem first: a premature recommendation.
+- ❌ Ask about the stack blank when the report shows one, or when the operator already named it in step 0.
+  Bring the inference as the recommendation to confirm (#2). An inference anchored in an installed
+  dependency is not a premature recommendation: the first has evidence, the second does not.
+- ❌ Materialize before you validate: it produces a wrong doc the operator has to fix.
+- ❌ Invent an RF "because it is best practice": write only what the operator asked for.
+- ❌ Add a gotcha proactively: gotchas start empty and get discovered over time.
+- ❌ Skip a `[TBD]` by guessing: invention is worse than a pending item.
+- ❌ Write a retroactive ADR during the interview: an ADR is a real decision, not proactive documentation.
+
+## Interview success criteria
+
+- The generated doc is useful **without** the operator having to edit it by hand (except to fill in `[TBD]`).
+- No section contains invention that goes beyond what the operator said.
+- Another dev who clones the repo and reads `docs/` can understand the product, the architecture and how
+  to contribute, with no need to ask.

package/content/interview/promotion.md

@@ -0,0 +1,115 @@
+---
+type: interview
+description: The criteria that move a local learning into the plugin.
+load: cold
+---
+
+# Promotion — when to promote `/docs` to `framework-template/`
+
+> This doc gives instructions **to Claude**. It detects a promotion candidate and proposes a PR.
+
+
+---
+
+## Principle
+
+A learning in the project's `/docs/` can be:
+- **Specific to the project** → it stays in `/docs/`.
+- **Valid for any project with the same stack** → promote it to `framework-template/modules/<stack>/`.
+- **Valid for any project, regardless of stack** → promote it to `framework-template/core/`.
+
+**Promotion here means registering a candidate. It does not mean writing to the plugin.** The table below decides the finding's `target:` field. The maintainer applies the change, in the plugin's own repo, from the `afm_findings` entries. The boundary is absolute (`PRINCIPLES.md` #7). From inside an adopting project, the reachable `framework-template/` is only the **install cache** — a copy the next `plugin update` discards.
+
+---
+
+## Decision table
+
+| Learning in the project's `/docs/` | Promote? | Where to |
+| --- | --- | --- |
+| Depends on a project entity (`SdkSource`, `App`, `Order`) | ❌ | Stays in `/docs/` |
+| Local naming convention ("we prefix routes with X") | ❌ | Stays in `/docs/` |
+| Current project status (auth wired? RFs pending?) | ❌ | Stays in `/docs/` |
+| Valid for any project with the same stack (tRPC, Trigger, Stripe, etc.) | ✅ | `modules/<stack>/` |
+| SDK or external library gotcha (Stripe Schedule, tsdown subprocess) | ✅ | `modules/<lib>/gotchas.seed.md` |
+| Universal hard rule (valid in any project, any stack) | ✅ | `core/afm.md` §3 |
+| Universal anti-pattern (a Lib that imports an ORM, a Domain that imports TRPCError) | ✅ | `core/ach.md` or `rubrics/` |
+| Universal principle (saga ordering, error classification) | ✅ | `core/afm.md` §1.3 or §3 |
+| Decision rubric (when to create X, which type to use) | ✅ | `rubrics/<name>.md` |
+
+---
+
+## Promotion flow
+
+When Claude detects a candidate:
+
+### 1. Ask the user
+
+> "I just added X to `/docs/{{file}}.md`. Does this learning **apply to any project {{with tRPC | with Stripe | universally}}**, not just this one? Do you want me to register it as a finding for the AFM plugin? `afm findings record` stores it in the project state for the maintainer to collect. This project does not change."
+
+### 2. If the user approves:
+
+a. Check the **mechanical evidence**. Find the command that proves the learning: a passing test, `tsc`, or a `grep`/`test -e` that shows the defect. With no reproducible command, do not register it (#5).
+
+b. Decide the `target:` field with the table above (`core/` vs. `modules/<stack>/`).
+
+c. Append the entry to the session file's `afm_findings`. Use the issue-body format from `ops/promote.md` step 4. Include an imperative title, `target:`, `evidence:`, and `origin:` — project plus the version pinned in `docs/.afm-version`. Add 1-3 sentences on why the learning applies to any instance.
+
+d. Report where the entry went. **Do not bump `VERSION`/`CHANGELOG`, and do not open a PR or commit in the plugin.** That is maintenance work. It happens in the plugin's repo.
+
+### 3. If the user declines:
+
+The learning stays in the project's `/docs/`. Add an internal note ("X is specific to {{project}}").
+
+---
+
+## Criterion for "valid for any project"
+
+Validation questions to ask before proposing:
+
+1. **Does the rule or gotcha reference a project-specific entity or model?**
+   If yes → it stays. If no → it might promote.
+2. **Does the solution depend on stack-specific tech?**
+   If yes → it goes to `modules/<stack>/`, not `core/`.
+3. **Would another project without this stack break without this rule?**
+   If yes → `core/`. If no → `modules/`.
+4. **Would the rule still hold if we changed the language?**
+   If yes → it is universal, and goes to `core/`.
+5. **Can I describe the rule without naming anything specific to the project?**
+   If yes → universal. If no → rewrite it as generic before promoting.
+
+---
+
+## Anti-patterns
+
+- ❌ **Writing to `framework-template/`.** The boundary is absolute (#7). From here you can only register a candidate. The reachable path is the install cache. The edit dies at the next `plugin update`, with no error and no signal.
+- ❌ **Registering a candidate without confirming with the user.** It might be specific to the project.
+- ❌ **Registering a rule that names a project entity** ("App.healthStatus must...") without generalizing it first.
+- ❌ **Registering an ADR.** An ADR is a decision for this project. A learning from that decision (a gotcha, a rule) can become a finding. The ADR itself cannot.
+- ❌ **Registering a candidate with no reproducible mechanical evidence.** A finding with no command is just an impression (#5). The maintainer needs to be able to rerun it and see the same result.
+- ❌ **Registering a candidate ahead of need** ("it will be useful later"). Register on demand, with a real case.
+
+---
+
+## Concrete example
+
+### Scenario
+
+The `sdk.mapree.dev` project found that `package.json.type` must be `"module"` even in `format=cjs`, because of a tsdown subprocess.
+
+### Decision
+
+- Goes to the project's `/docs/gotchas/`, one file per entry. ✅
+- Goes to `framework-template/modules/trigger-dev-v4/gotchas.seed.md`? **Not directly** — it is not a Trigger.dev gotcha.
+- Goes to `framework-template/modules/sdk-generator/`? **This module does not exist.** It is specific to this project.
+- **Conclusion:** it stays in `/docs/`. No promotion (this learning lives in the project, not in the template).
+
+### Scenario 2
+
+The `sdk.mapree.dev` project found that a Stripe webhook can arrive twice, and needs an idempotent UPSERT.
+
+### Decision
+
+- Goes to the project's `/docs/gotchas/`, one file per entry. ✅
+- `target: modules/stripe-billing/gotchas.seed.md`? **Yes** — every Stripe project runs into this.
+- Register it in `afm_findings`. Use the title "Gotcha: Stripe webhook is at-least-once — needs an idempotent UPSERT". Add `evidence:` the test that reproduced the repeated delivery. Add `origin:` sdk.mapree.dev plus the pinned version.
+- The `VERSION` bump and the `CHANGELOG` entry happen **in the plugin's repo**, when the maintainer collects the finding. Not here.