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

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).

package/content/skills/diagnose.md

@@ -0,0 +1,42 @@
+---
+name: diagnose
+description: |
+  Scans the health of the local docs on 7 axes. The axes are dead reference, stale marker, instance-to-plugin drift, broken ADR chain, dead rule trigger, inflation or orphan, and cross-doc contradiction. It reads only `<consumer>/docs/` and returns evidence as `command + file:line`. It proposes no edit.
+  Activates: `afm diagnose`, "diagnose the methodology", "what is broken in the docs?", "run the AFM health check".
+---
+
+
+# AFM — Diagnose (mechanical weakness-mining, read-only)
+
+> **Carve-out (does not overlap existing ops):** `afm analyze` audits **one feature**. `diagnose` audits the **whole instance** of `/docs/`. `afm reflect` uses **behavioral** evidence, where the agent stumbled. `diagnose` is **static**, based on filesystem and git. `afm evolve` is the **orchestrator**. It combines `diagnose` (mechanical evidence) with `afm reflect` (behavioral evidence) into one proposal and one gate. `diagnose` is **read-only**. It never proposes an edit or opens a gate.
+
+## When NOT to activate
+
+This section disambiguates for a skill that already activated. It does not define activation, so it stays in the body, not in the resident listing.
+
+Validation of ONE feature is `afm analyze`. Behavioral friction, where a doc misguided the agent at apply time, is `afm reflect`. Proposing or applying a fix is `afm evolve` (the full cycle, which includes diagnose).
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm init` (greenfield) or `afm refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+
+## Procedure
+
+The procedure has two phases. **Phase 0 — Scan** is gap-driven. Run `afm doctor --json`: it checks A1-A6, staleness and dead gotchas mechanically, and every finding carries a command plus `file:line`. You add A7 yourself. All 7 axes are checked, every time.
+
+Axis A7, cross-doc contradiction, uses a paired read. That read applies an anti-false-positive layer test. An axis that cannot be covered becomes "not-covered: <reason>".
+
+**Phase 1 — Diagnosis** has the ANALYZER role. **It must not propose an edit.** The signature is φ = `(symptom, causal-status-of-behavior, mechanism)`.
+
+Phase 1 requires rival mechanisms, for example "agent non-compliant" versus "target legitimately removed". It applies an addressability filter and a self-sufficient severity matrix.
+
+**Output** is an evidence bundle ordered by severity. Run à la carte, the skill prints the report to chat. It does not write to disk. It opens no gate. Under `afm evolve`, it feeds the proposal instead.
+
+This scan has no cooldown. It is read-only and cheap. The cycle's cooldown belongs to the orchestrator.
+
+## Invariant principles
+
+Most relevant here: #2 (discover-first — diagnose with evidence before any proposal). Also #3 (mechanize-or-demote — the checks must pass the test they audit). Also #5 (no finding without evidence external to the text).
+
+**No new principle here.** `diagnose` is a composed materialization. The doctrine lives in the op file.

package/content/skills/evolve.md

@@ -0,0 +1,43 @@
+---
+name: evolve
+description: |
+  Runs the full self-evolution cycle over `<consumer>/docs/`. It combines diagnose and reflect, adds generalize, restructure, update and remediate on demand, and delivers one package through one gate (`afm ask evolve`). It conducts the mechanisms and never touches the plugin.
+  Activates: `afm evolve`, "audit the methodology", "the docs are a mess", "the rules no longer trigger", "clean up the docs", "reorganize the docs".
+---
+
+
+# AFM — Evolve (orchestrator for the self-evolution cycle)
+
+This is an orchestrator skill of AFM. The canonical procedure is the op file that `afm path ops/evolve.md` prints.
+
+> **Carve-outs (it does not override existing ops):** `afm diagnose`, `afm reflect`, `afm generalize` and `afm restructure` are the **mechanisms** (each runs à la carte). `afm analyze` audits **one feature** (read-only). Passive mode (`afm reconcile`) proposes **one single edit** at the end of a turn. `afm promote` **records** a finding meant for the plugin (it does not edit the plugin). `evolve` is the **cycle** that chains the mechanisms with one gate and one log — the level no other op covers.
+
+## When NOT to activate
+
+This section helps someone who already activated the skill decide if it fits. It is not an activation trigger, so it stays in the body, not in the resident listing.
+
+Use a single mechanism instead when the need is narrow. A report is `afm diagnose`. Refining a doc that misled you is `afm reflect`. Merging gotchas is `afm generalize`.
+
+A structure or staleness check is `afm restructure`. A version bump is `afm update`. Passive mode (`afm reconcile`) proposes a one-off additive signal (new gotcha, rule, or ADR) directly.
+
+A feature-level check is `afm analyze` or `afm deliver`. Recording a finding for the plugin is `afm promote`.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm init` (greenfield) or `afm refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+3. **Does `afm evolve gate-check` allow a cycle?** Pass `--symptom "<what the user said>"` when there is one. Exit 0 runs; exit 1 is the cooldown refusing (no new signal inside the window), so say so and stop; 3 and 4 mean not a project or undecided.
+
+## Procedure
+
+Read the op (`afm path ops/evolve.md`) end to end and follow it exactly. The op has 5 phases: evidence collection (diagnose plus reflect), proposal in 3 buckets, a single gate (`afm ask evolve`), apply with post-conditions, and the log in `docs/evolution/`.
+
+Consult the rubric `rubrics/when-to-evolve-methodology.md` (`afm path rubrics/when-to-evolve-methodology.md`) to decide between a full cycle, a single mechanism, or a one-off fix.
+
+## Most relevant principles
+
+#2 (discover-first): diagnose with evidence before you propose. #3 (mechanize-or-downgrade): evolve's own signals must pass the same test evolve applies to others. #6 (autonomy-first with self-check): the gate is the load-bearing residue, and the bright lines for #7 plugin, deletion, and push still apply. #8 (earned questions, recommendation-first).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. It may **suggest** `afm evolve` when it detects a Class B signal. That signal is a lived contradiction between docs, or perceived inflation at apply time. Only the user can invoke the full cycle.

package/content/skills/export-template.md

@@ -0,0 +1,37 @@
+---
+name: export-template
+description: |
+  Converts a bootstrapped project into an architectural template. It deletes the product files, keeps ach, afm, gotchas and adr, and writes the `docs/.template` marker. It touches `docs/` only.
+  Activates: `afm export-template`, "export as template", "turn this project into a starter".
+---
+
+# AFM — Export-template
+
+The CLI owns the plan, the diff and the marker. This skill keeps the judgment.
+
+## When NOT to activate
+
+This is a criterion for a skill already active, not an activation trigger. If the project is already a
+template (`docs/.template` exists), the op is idempotent but asks first.
+
+## Pre-check
+
+`afm template export --dry-run` does it: a project with no `docs/.afm-version` is not bootstrapped yet, so
+stop and suggest `afm init` (greenfield) or `afm refactor` (brownfield) first.
+
+## Procedure (judgment only)
+
+1. Collect the template name and version as free text. A blank answer stays `[TBD]`; never derive the name
+   from the folder.
+2. Ask what to keep: `afm ask export-template`. Put every coherence warning of the dry run to the operator.
+3. Induce the reusable task template from the latest all-green feature BEFORE `docs/features/` goes.
+4. Show the full diff with `afm template export --dry-run ...`, then ask `afm ask export-template-apply`.
+   Deleting files is a bright line: it is never applied without that confirmation.
+5. Apply with the same flags and `--yes`, and suggest the commit message the command prints.
+
+## Invariant principles
+
+Most relevant here: #5 (do not invent metadata when the operator leaves it blank: use `[TBD]` in the JSON). Also #6
+(autonomy-first, but deleting files is a bright line): confirm the diff before you delete.
+
+Passive mode (`afm reconcile`) is always on. This skill focuses only on the active conversion to a template.

package/content/skills/generalize.md

@@ -0,0 +1,31 @@
+---
+name: generalize
+description: |
+  Merges two or more similar gotchas into one abstract rule, from episodic to semantic. Merged entries become tombstones and nothing is deleted.
+  Activates: `afm generalize`, "these gotchas are all the same thing", "merge these rules", "I have 3 gotchas that say the same thing".
+---
+
+
+# AFM — Generalize (semantic consolidation of gotchas)
+
+> **Carve-out (does not overlap existing ops):** `afm promote` **registers** a finding meant for the plugin. It does not write to the plugin. `afm generalize` merges **inside the instance** (N gotchas become 1 rule in the same `/docs/`). `afm reconcile` **adds** a new gotcha. `afm generalize` **merges** gotchas that already exist. `afm reflect` refines **one** doc. `afm generalize` consolidates **many**. `afm evolve` is the **orchestrator** and it composes this skill when `afm diagnose` flags inflation from redundant gotchas.
+
+## When NOT to activate
+
+This is a disambiguation criterion for someone who already activated the skill, not an activation trigger. That is why it lives in the body, not in the resident listing.
+
+Sending ONE learning to the plugin is `afm promote`. ADDING a new gotcha or rule is `afm reconcile` -> `afm gotcha`/`afm rule` (`afm generalize` only merges what already exists). Refining the clarity of ONE doc is `afm reflect`. With fewer than 2 similar candidates, there is no generalization to do.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop and suggest `afm init` (greenfield) or `afm refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+3. **Is there a batch of >=2** similar gotchas/reflections? If not, report "nothing to generalize (no batch)" and stop. Generalizing from 1 case is forbidden (#5).
+
+## Gate
+
+The merge is load-bearing and goes through its own earned gate, `afm ask generalize` (suppressed under `afm evolve`). Merged entries become tombstones; never delete.
+
+## Most relevant here
+
+#1 (episodic `gotchas.md` -> semantic `afm.md`), #3 (a merged rule becomes hard only with an executable 0/1 trigger), #5 (no abstraction without a real batch), #6/#8 (self-verify before an earned gate; deletion is a bright line, so archive as tombstones). No new principle here: the doctrine lives in the op.

package/content/skills/gotcha.md

@@ -0,0 +1,40 @@
+---
+name: gotcha
+description: |
+  Writes a counterintuitive surprise to `<consumer>/docs/gotchas/`. The entry gate is mandatory: the issue must have bitten twice, or it must be documented behavior of an external SDK or runtime.
+  Activates: `afm gotcha`, "register a gotcha", "this has confused me before", "note this surprise for the next person".
+---
+
+# AFM — Gotcha
+
+The CLI owns the entry gate, the number, the frontmatter the trigger index reads and the index. This skill
+keeps only the judgment.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. An architectural decision belongs to
+`afm adr`. A rule with an executable trigger belongs to `afm rule`. A recurring failure with an external
+signal belongs to `afm remediate`.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `afm init` or `afm refactor` first.
+
+## Procedure (judgment only)
+
+1. Validate the entry rule BEFORE you collect content: `afm ask gotcha`. `neither` stops: reject a gotcha
+   without a 2x incidence or an external doc.
+2. Collect the area, trigger, behavior, solution and references as free text. Decide how it fires: an
+   `event` when no file shape can fire it, a `file-shape` only with a narrow glob. A guessed trigger is worse
+   than one that never fires.
+3. Run `afm gotcha new <slug> --basis <bitten-twice|documented-sdk> ...` and report the path (#6). A later
+   re-bite is `afm gotcha bite <id>`.
+
+## Invariant principles
+
+Most relevant here: #5 (do not
+invent a gotcha without a real case; the 2x entry check is a strong gate) and #6 (autonomy-first: save the
+result and report it).
+
+Passive mode (`afm reconcile`) is always on and can propose `afm gotcha` when it detects the signal "the
+same runtime surprise blocked work twice." This skill covers only active registration.

package/content/skills/init.md

@@ -0,0 +1,77 @@
+---
+name: init
+description: |
+  Bootstraps AFM in a greenfield project. The CLI materializes `<consumer>/docs/` mechanically; the skill runs the interview for what only the operator knows, asking closed questions through `afm ask`. It detects the `docs/.template` marker and branches to the from-template path. It activates ONLY on explicit invocation and never from project state.
+  Activates: `afm init`, "build the AFM doc", "bootstrap AFM".
+---
+
+# AFM — Init (greenfield bootstrap)
+
+This skill of `afm` handles **greenfield bootstrap** and the from-template branch. It has a single
+responsibility. It does not route ops (each op is its own skill).
+
+The interview script is `afm path interview/bootstrap`. This skill is a router. It **never invents a
+procedure. It always reads the source first.** The layout of the shipped content is `afm path README`.
+
+---
+
+## When NOT to activate
+
+This is a disambiguation criterion for a skill that already activated. It is not an activation trigger.
+
+If the project already has `docs/.afm-version`, use the atomic skills instead. To move to a new version, use
+`afm update`. A brownfield codebase with no docs needs `afm refactor` instead.
+
+## Pre-check (before any action)
+
+1. **`afm preflight`.** Exit 3 means there is no `docs/.afm-version`: continue. Any other exit means the
+   project is already bootstrapped. **Do not run bootstrap again.** The atomic skills stay available
+   (`afm gotcha`, `afm adr`, `afm rule`, `afm promote`, `afm specify`, `afm plan`, `afm tasks`, `afm clarify`,
+   `afm analyze`, `afm export-template`), and passive mode (`afm reconcile`) stays always-on.
+2. **Does `docs/.template` exist?** Yes means the project comes from a template: ask `afm ask init-template`
+   whether to run the from-template branch, a subset focused on the product (default `Product only`). `Full
+   interview` goes to pre-check 3.
+3. **Does the project have significant pre-existing code?** A populated source root and a manifest with real
+   dependencies, or a git log with more than 20 commits. If so this is NOT the right path: stop and suggest
+   `afm refactor`: *"This project already has code. Greenfield bootstrap would make you pretend it is new.
+   `afm refactor` infers the docs from the existing code. Want to run it?"* `afm refactor --mechanical
+   --dry-run` states the verdict with its reasons.
+4. **Is the shipped content resolved?** `afm preflight` exit 4 means it is not. Tell the operator. Do not
+   guess the content and do not fail silently.
+
+---
+
+## Procedure (greenfield bootstrap)
+
+For projects without `docs/.afm-version`:
+
+1. Read `afm path interview/bootstrap` end to end.
+2. Ask the closed decisions the mechanical pass needs: `afm ask init`. Then run `afm init --mechanical`
+   (preview with `--dry-run`, or `--answers <file>` for a headless run). It creates `docs/` and `docs/adr/`,
+   fills the skeletons with the measured rule constants and `[TBD]` where the code answers nothing, copies
+   every rubric and pattern, writes `AGENTS.md` plus the harness stubs, and writes `docs/.afm-version` last.
+3. **Run the 7-step interview literally.** One question per turn. Free text only for open descriptions. For
+   everything with closed options, ask through `afm ask <op>` with the recommendation first (invariant
+   principle #8). Validate each answer with `afm ask confirm`. Fill each step into the matching
+   `docs/<file>.md`, replacing `{{placeholders}}` with the operator's answers and leaving unknown answers as
+   `[TBD]` (invariant principle #4).
+4. Apply opt-in modules. For each stack the operator confirms, read `afm path modules/<stack>/ach.patch` and
+   `afm path modules/<stack>/rules.patch` and merge them into `docs/ach.md` and `docs/afm.md`. A
+   `gotchas.seed` is a **commented reference** only: the project's `docs/gotchas/` starts empty.
+5. Generate the indexes (`afm index --materialize`) and print a summary: list every `[TBD]` and ask which ones
+   to fill in now.
+
+**Branch from-template** (if pre-check 2 found `docs/.template`): run a subset of the steps. The subset is
+0 + 3 + 6 short + 7 adapted. Skip steps 1, 2, 4 and 5, because the template already has them. The full
+procedure is in `afm path interview/bootstrap` § Alternate branch. `.afm-version` gets an inheritance line.
+
+---
+
+## Invariant principles
+
+For this skill (greenfield), #9 (retroactive ADR, load-bearing) does NOT apply to init. Bootstrap forbids a retroactive ADR.
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) stays always-on in any AFM
+project session. This skill covers only the active bootstrap procedure.

package/content/skills/plan.md

@@ -0,0 +1,28 @@
+---
+name: plan
+description: |
+  Fills `plan.md` for the active feature. It reads the stack from `ach.md` and infers the affected components from the code. It records each decision with its rejected alternatives. It soft-blocks on an open `[NEEDS CLARIFICATION:]` in the spec.
+  Activates: `afm plan [<feature>]`, "plan feature", "draft plan for feature X".
+---
+
+# AFM — Plan
+
+## When NOT to activate
+
+There is no `spec.md` yet: run `afm specify` first. An end-to-end delivery is `afm deliver`, which composes this op.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: stop and suggest `afm init` or `afm refactor`). Run `afm feature status <NNN> --json`: a non-empty `blockers` means open `[NEEDS CLARIFICATION:]` markers in the spec, and the op asks the `open-markers` question (`afm ask plan`) before it goes on.
+
+## Procedure
+
+Read the stack from `docs/ach.md` and never reopen it. Infer the components, decisions, contracts and complexity from the code scan, and ask only for what the scan cannot resolve. Create the plan with `afm new feature-plan --feature NNN-slug` and fill it, including the first real `for_paths`. List the hard rules of `docs/afm.md` § 3 that apply, each binary. Suggest an ADR (`afm adr new <slug>`) for a load-bearing decision. Autonomy-first: write and report.
+
+## Invariant principles
+
+Most relevant here: #2 (discover-first: scan before you ask), #5 (do not invent contracts or a stack) and #8 (a question carries a recommendation).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. This skill covers only the planning.

package/content/skills/policy.md

@@ -0,0 +1,25 @@
+---
+name: policy
+description: |
+  Reports what the organisation policy bundle imposes in this project. It answers which rules apply, which gotchas apply, whether the bundle can block, and what the reader may not edit here. It reads only and writes to neither bundle.
+  Activates: `afm policy`, "what does the organisation impose here", "which rules come from outside this repository", "why can I not edit this rule".
+---
+
+# AFM — Policy (report the organisation layer)
+
+## When not to activate
+
+Never to CHANGE the policy. This skill reads. The organisation bundle belongs to whoever owns it, and no
+operation in this plugin writes to it.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop. No organisation policy configured is a valid state
+that `afm policy report` says plainly, and a bundle with no `policy.md` is not a policy bundle: report it
+and stop.
+
+## Procedure (judgment only)
+
+Run `afm policy report` and read it by family. Say plainly that a policy bundle injects context and blocks
+nothing, and name what the reader may not edit here and who owns it. Never report a policy rule as
+enforced.