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

package/content/skills/remediate.md

@@ -0,0 +1,33 @@
+---
+name: remediate
+description: |
+  Reads the open failures of the state store (`afm failures promotable`) and proposes the durable artifact: a procedure when the fix is mechanical, a learning when it is conceptual. A failure enters by external signal, never by self-judgment.
+  Activates: `afm remediate`, "this failed again, fix it for real", "create a runbook for this", "record this lesson for the next agent sessions".
+---
+
+
+# AFM — Remediate (CRITIC loop)
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. It is not an activation trigger. That is why it lives in the body and not in the resident listing.
+
+Use `afm.md § 5.1` for an in-task retry at the moment of the error. Use `afm gotcha` for an SDK surprise with no failure of its own. Do not invent a failure. Only act on a recorded failure that `afm failures promotable` lists, or on an explicit user correction.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm init` for a greenfield project or `afm refactor` for a brownfield project.
+2. **Is there an open failure?** Run `afm failures promotable`. With `no failure is promotable` and no explicit user correction, report "nothing to remediate" and stop. An empty diagnosis is a valid result.
+3. **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 op includes the promotion gate (#5): 1 user correction OR at least 2 mechanical occurrences promote a failure. A transient failure does not promote. It also includes classification through the rubric `rubrics/failure-classification.md` (`afm path rubrics/failure-classification.md`). For each delta, propose the artifact (procedure or learning) and cite the source `sig=` (hard rule 19). Ask the artifact question with `afm ask remediate --scope <sig>`, materialize the result, close the signature with `afm failures close --sig <sig> --as remediated`, and report it (#6).
+
+## Invariant principles
+
+Most relevant here: #3 (CRITIC corollary — recognition by tool, not self-judgment). See also #5 (do not promote a failure without recurrence or an oracle) and #6 (propose only, the human approves).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. It reads `afm failures promotable` at the end of the turn and can propose remediation with no explicit command. The `afm evolve` cycle uses the failure events as evidence for `afm reflect`, toward a final remediation. This skill is the active record of the loop.

package/content/skills/restructure.md

@@ -0,0 +1,46 @@
+---
+name: restructure
+description: |
+  Checks the context architecture of the local docs. It looks at staleness against the code, findability across layers, and the hot versus on-demand partition. It relocates content that already exists and writes no new content.
+  Activates: `afm restructure`, "the doc is stale versus the code", "this should load only on demand", "the guidance exists but I cannot find it in the doc".
+---
+
+
+# AFM — Restructure (context architecture health)
+
+> **Carve-out (does not overlap existing ops):** `afm diagnose` A1 finds a **dead reference** (the path does not exist). `restructure` staleness finds a path that **exists but changed** while the doc did not. `afm reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `afm reflect` targets **clarity**. `restructure` targets **location and freshness**. `afm evolve` is the **orchestrator** that composes this skill when `afm diagnose` flags staleness or bloat.
+>
+> **Maturity (honest YAGNI):** the actionable core today is **staleness** (from git) plus **findability**. **Temperature tiering** (always-hot vs on-demand) is an **opt-in** ADR proposal, only for a doc that has actually outgrown its size. Small docs do not need it.
+
+## When NOT to activate
+
+This is a disambiguation guide for a skill that has already activated. It does not gate activation, so it stays in the body, not in the resident listing.
+
+A path that does not exist belongs to `afm diagnose` (A1). Staleness means the path exists but changed. Information never documented belongs to passive mode (`afm reconcile`) → `afm gotcha` or `afm rule`. An ambiguous doc belongs to `afm reflect`. Merging gotchas belongs to `afm generalize`. The full cycle belongs to `afm evolve`.
+
+## 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. **Is git available?** The staleness scan needs the git history. Without git, `afm doctor` marks this axis "not covered: no git". Never omit it.
+
+## Procedure
+
+Use these five steps.
+
+1. **Staleness scan.** `afm doctor --json` runs it (findings with axis `staleness` and `dead-gotcha`); read them. The git trigger fires in two cases. First case: a path cited in the doc has a later last commit than the doc. Second case: the doc has been stale for more than N commits. A hit is a candidate, not a verdict. The scan never rewrites the doc on its own.
+2. **Findability.** Relocate or cross-reference information that exists but sits buried or in the wrong doc. Cite both locations. Route information that is genuinely missing to passive mode (`afm reconcile`).
+3. **Temperature partition.** Propose a hot/on-demand loading strategy as an opt-in ADR. Do this only when a doc has outgrown its size. Preserve 100% of the content.
+4. **Its own gate.** This gate is load-bearing and earned, one `afm ask restructure --scope <item-slug>` per finding. It follows the **shared-proposal discipline** in `evolve.md` (`afm path ops/evolve.md`), instead of a duplicate copy of that discipline. `afm evolve` suppresses this gate when it runs.
+5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `afm promote` if the finding generalizes.
+
+## Invariant principles
+
+Most relevant here:
+
+- #2: get git evidence before you propose a change.
+- #3: staleness needs an executable git trigger.
+- #4/#5: missing product content becomes `[TBD]` or goes to passive mode (`afm reconcile`). Never invent it.
+- #6/#8: self-check the work, then pass an earned gate.
+
+**No new principle here.** `restructure` is a composed materialization. The doctrine lives in the op file.

package/content/skills/rule.md

@@ -0,0 +1,43 @@
+---
+name: rule
+description: |
+  Adds a hard rule to `<consumer>/docs/afm.md § 3`. A mechanical trigger is mandatory and must return 0 or 1, such as `grep`, `wc -l`, `git diff` or `tsc`. A code review or a PR template is not a trigger. Without a trigger the entry becomes a principle in § 1.3.
+  Activates: `afm rule`, "new hard rule", "this should be a rule".
+---
+
+# AFM — Rule
+
+The CLI owns the number, the rule file, the index line and the runner skeleton, and refuses a rule with no
+honest trigger form. This skill keeps only the judgment.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. Use `afm adr` for a one-off architectural
+decision. Use `afm gotcha` for a counterintuitive surprise. Use `afm generalize` to merge rules or gotchas
+that already exist.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `afm init` or `afm refactor` first.
+
+## Procedure (judgment only)
+
+1. Confirm the mechanical trigger as free text, and push back hard: no trigger means a principle in § 1.3.
+   Run the anti-Goodhart test: can a diff pass the trigger while it breaks the rule's intent? If yes, rewrite
+   or downgrade it.
+2. Measure the repo for any constant and propose the value with the measurement. An unanswered constant is
+   `[TBD]`. Check for an existing versioned script and cite it.
+3. Choose the surface: `afm ask rule`. Run `afm rule new <slug> --trigger '<command>' --surface <surface>` and
+   report the paths (#6). For `pre-commit` or `ci`, follow "Install the gate" in the op: `afm gate --baseline`
+   before the gate goes on.
+4. In a refactored project only, ask where the rule enters: `afm ask rule-scope` (universal § 3 or
+   forward-only § 3.1). The scope decision reflects intent, so it stays fixed once made.
+
+## Invariant principles
+
+Most relevant here: #3 (a hard rule needs
+a mechanical trigger, or it is a principle instead) and #6 (autonomy-first: materialize the change and
+report it).
+
+Passive mode (`afm reconcile`) is always on and can propose `afm rule` when it detects the signal "the user
+corrected an approach with a reusable rule".

package/content/skills/specify.md

@@ -0,0 +1,28 @@
+---
+name: specify
+description: |
+  Opens a feature folder at `docs/features/NNN-slug/spec.md`, linked to a user story. A mechanical heuristic decides first, because a feature folder for a trivial change is overhead.
+  Activates: `afm specify <slug>`, "open a feature", "start a new feature", "create a feature folder".
+---
+
+# AFM — Specify
+
+## When NOT to activate
+
+A trivial change (no feature folder needed) goes straight to the `afm.md § 2` loop. A full end-to-end delivery is `afm deliver`, which composes this op.
+
+## Pre-check
+
+Run `afm preflight`. Exit 3 means no `docs/.afm-version`: stop and suggest `afm init` or `afm refactor`. Exit 4 or 5: report the line it printed.
+
+## Procedure
+
+The number comes from `afm next-id feature`, never by hand. What is left to you is judgment: compute the trigger heuristic from the scan (ask the `heuristic` question only when borderline), find the linked US in `docs/ust.md` before asking (`afm ask specify`), create the spec with `afm new feature-spec <slug>` (the generator writes the frontmatter the template names) and fill its body, update the `Spec:` line of the US, and report the open `[NEEDS CLARIFICATION:]` items. Autonomy-first: write and report, review through `git diff`.
+
+## Invariant principles
+
+Most relevant here: #2 (discover-first: compute the heuristic and the US from the scan), #5 (never invent a success criterion) and #6 (autonomy-first).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. This skill covers only the opening of the feature.

package/content/skills/tasks.md

@@ -0,0 +1,24 @@
+---
+name: tasks
+description: |
+  Generates the `tasks:` list of `tasks.md` in TDD order with `afm task add`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
+  Activates: `afm tasks [<feature>]`, "generate the tasks", "break the feature into tasks".
+---
+
+# AFM — Tasks
+
+## When NOT to activate
+
+There is no `plan.md` yet: run `afm plan` 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` is an open `[NEEDS CLARIFICATION:]` in the plan. That is a hard refusal with no override, not a question.
+
+## Principles
+
+Most relevant here: #5 (every task traces to a US or RF) and rule 1 (TDD: no green task without the red task it closes).
+
+## Continuous doctrine
+
+Passive mode (`afm reconcile`) is always on. This skill covers only the task list.

package/content/skills/update.md

@@ -0,0 +1,58 @@
+---
+name: update
+description: |
+  Syncs `<consumer>/docs/` with the current plugin version. It materializes the consumer-facing deltas between the pinned version and the shipped version, then moves the pin. It reads the plugin and never edits it.
+  Activates: `afm update`, "bump the methodology version", "sync docs with the new plugin", "my `.afm-version` is behind".
+---
+
+# AFM — Update (sync instance-plugin)
+
+The CLI runs the codemod registry, proves each op and moves the pin. This skill keeps the judgment.
+
+> **Carve-out (does not overlap existing ops):** `afm init` and `afm refactor` **create** the instance
+> (bootstrap). `update` brings an **existing** instance forward, the path that `afm refactor` refuses.
+> `afm diagnose` only **detects** drift on axis A3 (read-only). `update` **resolves** it. `afm promote`
+> **records** a finding meant for the plugin. `update` reads the plugin and materializes it into the
+> instance, and neither touches the shipped content: an absolute boundary (#7). `afm evolve` is the
+> **cycle** that composes `update` on axis A3.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. Use `afm init` or `afm refactor` if no instance
+is bootstrapped yet. Skip `update` if the pinned version already equals the shipped version (no drift). Use
+`afm promote` to carry a learning from the instance TO the plugin (the opposite direction). Use
+`afm diagnose` to only CHECK for drift. Use `afm evolve` for the full cycle.
+
+## Pre-check
+
+`afm update --dry-run` does it: exit 3 means no instance (suggest `afm init` or `afm refactor`), exit 4 means
+the shipped content does not resolve (report it, do not fall back silently), and "already up to date" ends
+the run. A pin **ahead** of the binary is an anomaly: report it, never roll it back.
+
+## Procedure (judgment only)
+
+1. Read the dry run as one package and show it as evidence. Ask `afm ask update`. Under `afm evolve` this gate
+   is suppressed.
+2. Run `afm update`. It moves the pin only at the end, and keeps it where it was when a codemod fails.
+3. Exit 6 means agent tasks are pending: do each one inside its scope (`afm lint --fix <path>` fixes the
+   frontmatter findings), then run `afm update` again. `afm update --accept <path>` closes a sync on a file
+   you merged by hand. An opt-in delta is reported and never applied. Exit 5 (a major crossing) is
+   `afm migrate`.
+4. **Language migration** (when the instance is not English): read `prd.md` § 11.1 FIRST and derive the
+   excluded scope from it, and only then read a file. `[TBD]` there stops the step and asks
+   `afm ask update-strings`. It never picks a language. The artifacts question is
+   `afm ask update-artifacts`. On migrate, run the rewrite as one orchestrated batch through
+   {{host:workflow}}, with a light model per agent ({{host:light-model}}) for the rewrite and the loss
+   check. Escalate only a flagged file to a capable model. The session model keeps the excluded scope and
+   the final gate.
+5. Post-conditions: `afm index --check` returns 0 and the plugin boundary stays clean. Report in chat what
+   migrated and what stayed pending. Under `afm evolve`, feed it to `docs/evolution/`.
+
+## Invariant principles
+
+Most relevant here: #2 (discover-first): the proof of
+need is the grep that shows what is missing. Follow #4/#5: materialize only what the plugin already provides
+ready-made, and never invent missing product content. Follow #6 (autonomy-first with a gate). Bright line
+#7 applies: only **read** the plugin, and write only to the instance.
+
+**No new principle here.** `update` is composed materialization. The doctrine lives in the op file.

package/content/skills/verify.md

@@ -0,0 +1,29 @@
+---
+name: verify
+description: |
+  Stamps a human verification on one doc under `docs/`. It writes the OKF `verified` field and is the only writer of that field. Use it when a person states they reviewed a document.
+  Activates: `afm verify <path>`, "I reviewed this rule", "mark this gotcha as verified", "sign off on this ADR".
+---
+
+# AFM — Verify (stamp a human review)
+
+## When not to activate
+
+Never on ordinary work, and never on your own output. This skill records that a PERSON read a document. An
+agent stamping its own writing produces a lie the trust tier cannot detect.
+
+## Pre-check
+
+1. `afm preflight`. Exit 3 means there is no instance: stop.
+2. **Did a person state they reviewed the file?** If not, stop and ask: `afm ask verify`. Inference is not
+   review.
+3. The file must carry a frontmatter block, or there is no contract to stamp.
+
+## Procedure (judgment only)
+
+Run `afm verify <path under docs/>` (add `--as <id>` when no git user name is set). The command refuses an
+agent actor. Report the tier that resulted and what it means.
+
+## Invariant principles
+
+Most relevant here: #5 is load-bearing.

package/content/templates/adr.template.md

@@ -0,0 +1,51 @@
+---
+type: template
+description: 'Template rendered during materialization: ADR-NNNN — {{short title on the decision, not on the problem}}.'
+load: cold
+renders_to: 'docs/adr/*.md'
+frontmatter_for_output: |
+  type: adr
+  description: '<one sentence: the decision and why it matters>'
+  load: warm
+  status: proposed           # proposed | accepted | superseded | deprecated. Set from step 2's
+                              # `afm ask adr` answer; `afm adr --supersedes` sets superseded.
+  date: YYYY-MM-DD           # The day the decision was written down.
+  decided_by: '<who>'        # `[TBD]` when nobody said.
+  supersedes: ADR-NNNN       # ONLY when this decision replaces an earlier one. Omit otherwise.
+  superseded_by: ADR-NNNN    # ONLY when status is superseded by a later decision. Omit otherwise.
+  relates_to: [ADR-NNNN]     # ONLY when it depends on or refines other ADRs. Omit otherwise.
+  trigger_path: '{{glob}}'   # ONLY when this decision constrains one path or family of paths.
+                              # Most decisions bind none: omit the key rather than guess one.
+---
+
+# ADR-NNNN — {{short title on the decision, not on the problem}}
+
+## Context
+
+{{What was happening, what problem appeared, which constraints (time, scope, security, cost) limit the decision. 3-5 sentences. Cite the concrete symptom that forced the decision. Do not invent a retroactive motivation.}}
+
+## Decision
+
+{{What was decided, in one header sentence.}}
+
+{{Operational details. What changes in the code, in which file, with which contract. Use a concrete, absolute path and a snippet when useful.}}
+
+## Alternatives considered
+
+- **{{alternative A}}** — why it was NOT chosen (cost / risk / simplicity).
+- **{{alternative B}}** — why it was NOT chosen.
+
+<!-- guidance -->
+(List 1-3 alternatives. If you considered none, write "Direct decision — no alternatives evaluated because {{reason}}".)
+<!-- /guidance -->
+
+## Consequence
+
+{{What becomes easy now. What becomes hard now. Accepted technical debt. A gotcha other developers will hit (link to `gotchas.md` if it applies).}}
+
+## References
+
+- Commit: `{{sha}}`
+- Related US/RF: US-NNN / RF-NN
+- Canonical doc: `/docs/{{file}}.md` §X
+- External issue / PR: {{link}}

package/content/templates/evolution-report.template.md

@@ -0,0 +1,132 @@
+---
+type: template
+description: 'Template rendered during materialization: Evolution cycle {{NNNN}} — {{data YYYY-MM-DD}}.'
+load: cold
+renders_to: 'docs/evolution/YYYY-MM-DD-NNN.md'
+frontmatter_for_output: |
+  type: evolution-report
+  description: '<one sentence: what this cycle found and changed>'
+  load: cold
+  mechanism: evolve | reflect | restructure | generalize   # WHICH mechanism wrote this report
+  date: 'YYYY-MM-DD'
+  cycle_trigger: '<explicit invocation or the symptom stated by the user: cite it>'
+  new_signal: '<which Class A delta or symptom released the cooldown>'
+  resolves: []   # optional: fingerprints (from `afm sessions signals`) of the friction this cycle fixed
+---
+
+# Evolution cycle {{NNN}} — {{date YYYY-MM-DD}}
+
+<!-- guidance -->
+> **File name: `YYYY-MM-DD-NNN.md`, date first.** The cadence counter picks the last report by
+> sorting these names, and an ordinal-first name sorts by ordinal before date — a low ordinal on
+> a recent date rewinds the window in silence. `NNN` is now only a same-day tiebreak.
+>
+> **`resolves:` (frontmatter, optional)** lists the signal fingerprints this cycle fixed. `afm sessions signals`
+> marks a signal with one of them `resolved` when it happened before this report's date, and `regressed` when
+> it happens again after it (the fix did not hold).
+>
+> **`mechanism:` (frontmatter) is mandatory and it is not decoration.** `reflect`, `evolve` and `restructure`
+> all write into this one directory, and each one's cadence window is "since MY last report".
+> Without the field the windows collapse into one, and the cheap mechanism starves the expensive
+> one: measured on 2026-08-30, five reports, all five `reflect`, and `evolve` had never run.
+
+> This is a report of one `afm evolve` cycle (auto-evolution of **this project's local documentation** — the materialized instance of the methodology in `docs/`, never the plugin). It is the **auditable lineage** and the **memory of past attempts** for future cycles. It is not the evolved artifact itself (the edits live in the touched local docs). It is the record of the diagnosis and the gate decisions.
+<!-- /guidance -->
+
+---
+
+## Vital signs
+
+| Signal | Before | After (measured in dry-run / post-apply) |
+| --- | --- | --- |
+| Dead refs (A1) | {{n}} | {{n}} |
+| `[TBD]`/`[NEEDS CLARIFICATION:]` markers above threshold (A2) | {{n}} | {{n}} |
+| Version drift (A3) | {{instance X vs plugin Y / ok}} | {{...}} |
+| Broken ADR chain (A4) | {{n}} | {{n}} |
+| Non-parseable § 3 triggers (A5) | {{n}} | {{n}} |
+| Inflation — core docs above threshold (A6) | {{which / ok}} | {{...}} |
+
+---
+
+## Findings (φ signature)
+
+<!-- guidance -->
+> Each finding is `(symptom, behavior causal status, mechanism)` plus evidence (`command` + `file:line`) and severity. Non-addressable findings go in the observations section, with no proposal.
+<!-- /guidance -->
+
+| ID | Symptom (evidence) | Causal status | Mechanism | Severity | Addressable? |
+| --- | --- | --- | --- | --- | --- |
+| D01 | {{what the command flagged + file:line}} | {{does this imply a methodology behavior?}} | {{miswritten trigger / obsolete rule / orphan doc / agent non-conformance}} | {{CRITICAL/HIGH/MEDIUM/LOW}} | {{yes / no → observation}} |
+
+### Observations (non-addressable findings — no proposal)
+
+- {{example: "user did not answer the `[TBD]` items in §X for >180 days — human behavior, not a doc problem. No edit fixes this"}}.
+
+---
+
+## Evolution package
+
+### Bucket (a) — auto-applicable (restorative, non-semantic)
+
+<!-- guidance -->
+> Only fixes that **restore what the doc already states**, proven by git or the file system. Never touch a `*Verification:*` command in § 3, or a path the hooks parse.
+<!-- /guidance -->
+
+| ID | Surface | Edit | Mechanical proof | Gate decision |
+| --- | --- | --- | --- | --- |
+| A01 | {{file}} | {{corrected path ref / corrected ADR link}} | {{git log --follow / ADR-NNNN exists}} | {{approved / refused}} |
+
+### Bucket (b) — load-bearing (earned gate questions)
+
+<!-- guidance -->
+> A 4-field audit record per item. Downgrading or removing a hard rule, and any deletion, need item-by-item approval. This is unavoidable, even without a "go" — evolve has no "go".
+<!-- /guidance -->
+
+| ID | Targeted pattern | Edited surface | Expected effect | Regression risk / what to preserve | What breaks if this is wrong | Flip-flop? | Decision |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| B01 | {{finding D0N}} | {{file:section}} | {{...}} | {{passing behaviors to preserve}} | {{load-bearing consequence}} | {{⚠ cycle NNNN / —}} | {{approved / refused}} |
+
+### Bucket (c) — cosmetic/deferrable
+
+- {{note — becomes `[TBD]` or waits for reconcile. Not edited in this cycle}}.
+
+### Overflow staged (above the cap of 8 items/cycle)
+
+- {{items that did not fit — carried to the next cycle}}.
+
+---
+
+## ADRs created in this cycle
+
+<!-- guidance -->
+> Itemized in the gate (Phase 3). Not materialized after the gate without approval.
+<!-- /guidance -->
+
+- {{ADR-NNNN — title — status proposed/approved}}.
+
+---
+
+## Attempt memory (anti-oscillation)
+
+<!-- guidance -->
+> Future cycles read this. Re-proposing a refused or reverted item needs **new evidence**. Touching a surface with an opposite history carries a flip-flop flag.
+<!-- /guidance -->
+
+### Refused in this cycle
+- {{ID — proposal — reason the user refused it}}.
+
+### Approved-then-reverted (by mechanical post-condition)
+- {{ID — edit — why it was reverted (hook format broke / plugin got dirty) — flagged dependent items}}.
+
+---
+
+## Mechanical post-conditions
+
+- [ ] `afm doctor --json`, `afm index --check` and `afm detect --for <file>` over the touched docs kept the format the hooks parse.
+- [ ] The content root (`afm path`) is clean: `git -C <content-root> status --porcelain` is empty, or, with no git there, no file under it is newer than T0 (no edit leaked into the bundled content).
+
+---
+
+## Suggested promotion
+
+- {{finding that generalizes to any instance → suggest `afm promote` (its own gate, evolve only suggests it). Or "none"}}.

package/content/templates/feature-plan.template.md

@@ -0,0 +1,84 @@
+---
+type: template
+description: 'Template rendered during materialization: Feature {{NNN}} — Plan.'
+load: cold
+renders_to: 'docs/features/*/plan.md'
+frontmatter_for_output: |
+  type: feature-plan
+  description: '<one sentence: the approach this plan commits to>'
+  load: cold
+  status: planned            # draft | clarified | planned | in_progress | done | cancelled — the folder's
+                              # ONE lifecycle value; `planned` once this plan exists, in step with spec.md
+  for_paths:                 # § 2's affected components, as globs — this is where the list
+    - '{{glob}}'              # spec.md seeded empty gets its first real entries
+  us: US-{{NNN}}             # carried from spec.md. Omit when spec.md omits it.
+  rf: RF-{{NN}}              # carried from spec.md. Omit when spec.md omits it.
+---
+
+# Feature {{NNN}} — Plan
+
+## 1. Approach in 3 sentences
+
+{{What to build, in which layer, linked to which component-types from `ach.md` § 3.}}
+
+## 2. Affected components
+
+| Component-type | File / module | New or edit | Why |
+| --- | --- | --- | --- |
+| {{Procedure-like}} | `{{src-path}}/server/routers/{{x}}.ts` | edit | adds endpoint Y |
+| {{Domain-like}} | `{{src-path}}/domain/{{x}}.ts` | new | business rule Z |
+
+## 3. Data model (delta)
+
+{{Mini ASCII ER diagram if there is a new entity. For new fields only, list field + type + reason. If nothing changes, write "no delta".}}
+
+## 4. Architectural decisions
+
+{{Each decision that would deserve an ADR goes here FIRST. If it becomes load-bearing later, materialize an ADR (see `ops/adr.md`). Bullet list:}}
+
+- **Decision:** {{X}}. **Rejected alternative:** {{Y}}. **Why:** {{concrete reason — cost, risk, simplicity}}.
+
+## 5. Contracts (external boundaries)
+
+{{For each new boundary — request/response shape, error codes, status. Keep it inline. Promote to `./contracts/` only when there are more than 3 boundaries OR the schema comes from tooling.}}
+
+### Boundary {{name}}
+
+```ts
+// input
+{ field: type }
+
+// output (success)
+{ field: type }
+
+// errors (codes)
+"NOT_FOUND" | "INVALID_INPUT" | "..."
+```
+
+## 6. Complexity tracking
+
+{{Log each complexity that exceeds the "obviously simple" baseline, with a justification. An empty table is a valid answer — it means the baseline stayed simple.}}
+
+| Accepted complexity | Rejected simple alternative | Why it was not simple |
+| --- | --- | --- |
+| {{ex: in-memory cache + TTL}} | {{no cache}} | {{p95 would be 800ms vs 80ms}} |
+
+## 7. Validation against invariants
+
+- [ ] Does not violate the hard rules in `afm.md` § 3 (list the ones that apply, by number, e.g. "rule 11 — structural change confirmed with the user at {{turn}}").
+- [ ] Follows the universal principles in `PRINCIPLES.md`.
+- [ ] `[NEEDS CLARIFICATION:]` is at zero OR listed in § 9 with a resolution plan.
+
+## 8. Risks
+
+- {{1-3 risks, each with a concrete mitigation}}.
+
+## 9. Open questions
+
+- [NEEDS CLARIFICATION: {{question}}]
+
+---
+
+<!-- guidance -->
+*The plan does NOT contain a granular task list (that goes in `tasks.md`). The plan does NOT choose the stack — it reads the stack from `ach.md`. If the relevant `ach.md` layer is `[TBD]`, flag it here and block tasks until it is resolved.*
+<!-- /guidance -->

package/content/templates/feature-research.template.md

@@ -0,0 +1,56 @@
+---
+type: template
+description: 'Template rendered during materialization: Research — Feature {{NNN}} — {{title}}.'
+load: cold
+renders_to: 'docs/features/*/research.md'
+frontmatter_for_output: |
+  type: feature-research
+  description: '<one sentence: what this research investigates>'
+  load: cold
+  status: open              # open | closed — `closed` once the findings were applied to spec.md or plan.md
+  consumed_by: '<the artifact that cites this research; omit until one does>'
+  context: '<the marker from spec.md or plan.md this answers, or "free investigation: <topic>">'
+---
+
+# Research — Feature {{NNN}} — {{title}}
+
+<!-- guidance -->
+{{For each topic investigated, repeat the block below. Put multiple topics in the same file if they went to the subagent in the same round.}}
+<!-- /guidance -->
+
+## {{topic 1 — concrete question}}
+
+**Decision (proposed):** {{X}}
+
+**Rationale:**
+- {{bullet 1 with concrete evidence — number, benchmark, documented case}}
+- {{bullet 2}}
+- {{bullet 3}}
+
+**Alternatives considered:**
+- **{{alt A}}** — rejected because {{concrete reason — cost, risk, simplicity, compat}}.
+- **{{alt B}}** — rejected because {{reason}}.
+
+**Sources:**
+- {{real URL or ref}}
+- {{real URL or ref}}
+
+---
+
+## {{topic 2}}
+
+<!-- guidance -->
+(Same as the previous block if more topics exist.)
+<!-- /guidance -->
+
+---
+
+<!-- guidance -->
+*Research is input. It is not a decision. To add it to the project, follow these steps.*
+
+*1. Edit the feature's `spec.md` or `plan.md`. Cite this research as the source.*
+
+*2. If the decision is load-bearing (a change would break something visible), make it an ADR with `afm adr`.*
+
+*3. After you add it, set this file's frontmatter `status` from `open` to `closed`.*
+<!-- /guidance -->