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

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

@@ -0,0 +1,86 @@
+---
+type: template
+description: 'Template rendered during materialization: Feature {{NNN}} — {{objective title}}.'
+load: cold
+renders_to: 'docs/features/*/spec.md'
+frontmatter_for_output: |
+  type: feature-spec
+  description: '<one sentence: what this feature does and why>'
+  load: cold
+  status: draft            # draft | clarified | planned | in_progress | done | cancelled — the ONE
+                            # lifecycle signal of the folder; the body carries no Status line. The
+                            # same value rides in plan.md and tasks.md once they exist.
+  for_paths:                # the globs this feature touches — the whole trigger `afm-index.sh
+                             # --for` matches through. Empty until plan.md § 2 names them; an
+                             # absent key is honest, a list guessed ahead of the plan is not.
+    - '{{glob}}'
+  us: US-{{NNN}}            # the linked US (step 5). Omit the key entirely when none is linked yet.
+  rf: RF-{{NN}}             # only when the feature also answers a roadmap RF. Omit otherwise.
+---
+
+# Feature {{NNN}} — {{objective title}}
+
+<!-- guidance -->
+> A spec holds the what and the why. No technology decision.
+> The linked US and the lifecycle `status` live in the frontmatter, never in the body.
+<!-- /guidance -->
+
+## 1. Problem (from PRD/UST)
+
+{{Restate the user job and the pain this feature solves, in 2-3 sentences. Name the persona from PRD § 3.}}
+
+## 2. Observable success criteria
+
+- [ ] {{verifiable from outside — example: "user X can export a report to PDF in <3 clicks"}}
+- [ ] {{metric, if any — example: "average time < 2s at p95"}}
+
+## 3. Scenarios (Gherkin, inherited from the US)
+
+```gherkin
+Scenario: {{happy path name}}
+  Given {{precondition}}
+  When {{user action}}
+  Then {{observable result}}
+  And {{verifiable side effect}}
+```
+
+```gherkin
+Scenario: {{most likely error scenario}}
+  Given {{precondition}}
+  When {{action in invalid state}}
+  Then {{expected typed error}}
+  And {{no DB side effect}}
+```
+
+## 4. Out of scope
+
+- {{things explicitly NOT included — this prevents scope creep and protects future decisions}}
+
+## 5. Assumptions / Open questions
+
+- [NEEDS CLARIFICATION: {{concrete unanswered question — someone must resolve this before plan}}]
+- {{assumption that changes the design if it is wrong}}
+
+## 6. Dependencies
+
+- US-NNN (must be `done` first — or mark as a blocker)
+- Feature {{MMM}} (shares entity X, contract Y)
+
+## 7. Clarifications
+
+<!-- guidance -->
+{{Optional section, filled in by `afm clarify`. Each session gets a subheading `### Session YYYY-MM-DD`. Each Q/A becomes a bullet. The section stays empty until the first `clarify` run.}}
+
+<!-- Example after the first session:
+### Session 2026-05-10
+- Q: Is the PDF generated server-side or client-side? → A: Server-side (cache + signed URL)
+- Q: Delivery by direct download or pre-signed URL? → A: Pre-signed URL, TTL 1h
+-->
+<!-- /guidance -->
+
+---
+
+<!-- guidance -->
+*The spec must NOT contain: stack decisions, function names, DB schema, task order. Those belong in `plan.md`.*
+*The marker `[NEEDS CLARIFICATION:]` differs from `[TBD]`. Use the first for a gap that blocks execution (resolved through `afm clarify`). Use the second for a decision the user knowingly defers.*
+<!-- /guidance -->

package/content/templates/feature-tasks.induced.template.md

@@ -0,0 +1,91 @@
+---
+type: template
+description: 'Template rendered during materialization: Induced tasks — parameterized template.'
+load: cold
+renders_to: 'docs/templates/feature-tasks.induced.md'
+ancestors: 'Agent Workflow Memory (arXiv:2409.07429): induce a reusable workflow from a successful trajectory, and parameterize the concrete values. Voyager (arXiv:2305.16291): composing from the library beats regenerating from scratch.'
+frontmatter_for_output: |
+  type: feature-tasks
+  description: '<one sentence: what this task list delivers>'
+  load: cold
+  status: planned           # draft | clarified | planned | in_progress | done | cancelled
+  for_paths:
+    - '{{glob}}'
+  us: US-{{NNN}}            # Omit when no US is linked.
+  rf: RF-{{NN}}             # Omit when no RF is linked.
+  tasks:                    # replay each item with `afm task add`, the variables filled; never by hand
+    - id: T001
+      kind: setup
+      files: ['{{src-path}}/domain/{domain}.ts']
+      refs: ['US-{{NNN}}']
+      parallel: true
+      text: 'Create the file `{{src-path}}/domain/{domain}.ts` with exported signature `domain_{domain}`.'
+      done: false
+    - id: T002
+      kind: setup
+      files: ['{{src-path}}/domain/{domain}.fixtures.ts']
+      refs: ['US-{{NNN}}']
+      parallel: true
+      text: 'Create the test fixture in `{{src-path}}/domain/{domain}.fixtures.ts`.'
+      done: false
+    - id: T003
+      kind: red
+      scenario: 1
+      files: ['{{src-path}}/domain/{domain}.test.ts']
+      refs: ['US-{{NNN}}']
+      text: 'Write test `domain_{domain} returns <result> given <input>`.'
+      done: false
+    - id: T004
+      kind: green
+      closes: T003
+      files: ['{{src-path}}/domain/{domain}.ts']
+      refs: ['US-{{NNN}}']
+      text: 'Add the minimal implementation of `domain_{domain}`.'
+      done: false
+    - id: T005
+      kind: refactor
+      refs: ['US-{{NNN}}']
+      text: 'Extract a helper if DRY reaches 3 callers (rule 8).'
+      done: false
+    - id: T006
+      kind: red
+      scenario: 2
+      refs: ['US-{{NNN}}']
+      text: 'Write a test for the error path of an invalid `{entity}` at `{boundary-procedure}`.'
+      done: false
+    - id: T007
+      kind: green
+      closes: T006
+      validates: '{boundary-procedure}'
+      refs: ['US-{{NNN}}']
+      text: 'Add the procedure `{boundary-procedure}` with Zod validation at the boundary (rule 16).'
+      done: false
+    - id: T008
+      kind: reconcile
+      text: 'Update `ach.md § 3` if a new component (`{domain}`/`{entity}`) was added, add an ADR if an architectural decision was made, set the US status in `ust.md` to `done`, and move the `status` frontmatter key of `spec.md`, `plan.md` and `tasks.md` to `done`.'
+      done: false
+---
+
+# Induced tasks — parameterized template
+
+<!-- guidance -->
+> Induced by `afm export-template` from a feature that is **delivered and 100% green** (every task of its `tasks:` list `done: true` — gate `L_eval=1` of AWM). The concrete values of the original feature are parameterized as `{variables}`.
+> The next consumer of this template starts here instead of generating tasks from scratch: fill in the variables and replay each item of the `tasks:` list above with `afm task add`, then close each one with `afm task done`. It keeps the TDD convention of `feature-tasks.template.md`: a red task, the green task that closes it, an optional refactor (`core/afm.md § 2`), and one reconcile task, last.
+<!-- /guidance -->
+
+## Variables
+
+| Variable | What it is | Example (from the induced feature) |
+| --- | --- | --- |
+| `{product-name}` | product/project name | — |
+| `{domain}` | module/domain of the feature | `billing`, `auth` |
+| `{entity}` | central entity touched | `Subscription`, `Session` |
+| `{boundary-procedure}` | boundary procedure/handler, named as its `### Boundary` of plan § 5 | `subscriptionCreate` |
+
+---
+
+<!-- guidance -->
+*Fill in the variables for this feature. The rest of the TDD structure came from a validated delivery. Every task must reference US-NNN/RF-NN in its commit. Do not skip the red task (rule 1).*
+
+> **Version bump.** In a delivery of more than one commit, the version bump is a **precondition of every commit that touches the installable surface**. It is not a task: a bump in the reconcile task leaves the earlier commits failing the gate.
+<!-- /guidance -->

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

@@ -0,0 +1,82 @@
+---
+type: template
+description: 'Template rendered during materialization: Feature {{NNN}} — Tasks.'
+load: cold
+renders_to: 'docs/features/*/tasks.md'
+frontmatter_for_output: |
+  type: feature-tasks
+  description: '<one sentence: what this task list delivers>'
+  load: cold
+  status: planned           # draft | clarified | planned | in_progress | done | cancelled — the folder's
+                              # ONE lifecycle value: `in_progress` with the first task, `done` in the
+                              # reconcile task that moves spec.md and plan.md
+  for_paths:                 # carried from plan.md § 2, unchanged
+    - '{{glob}}'
+  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.
+  tasks:                     # written by `afm task add`, corrected by `afm task set`, closed by `afm task done`; never by hand
+    - id: T001
+      kind: setup
+      files: ['{{src-path}}/domain/x.ts']
+      refs: ['US-{{NNN}}']
+      parallel: true
+      text: '{{ex: create the empty file with an exported signature}}'
+      done: false
+    - id: T002
+      kind: red
+      scenario: 1
+      files: ['{{src-path}}/domain/x.test.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: test domain_x returns Y given Z}}'
+      done: false
+    - id: T003
+      kind: green
+      closes: T002
+      files: ['{{src-path}}/domain/x.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: minimal implementation of domain_x}}'
+      done: false
+    - id: T004
+      kind: refactor
+      refs: ['US-{{NNN}}']
+      text: '{{ex: extract parseInput if DRY has 3+ callers (rule 8)}}'
+      done: false
+    - id: T005
+      kind: red
+      scenario: 2
+      files: ['{{src-path}}/procedures/x-create.test.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: test the INVALID_INPUT error path of the xCreate boundary}}'
+      done: false
+    - id: T006
+      kind: green
+      closes: T005
+      validates: '{{boundary name of plan § 5, ex: xCreate}}'
+      files: ['{{src-path}}/procedures/x-create.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: Zod validation at the boundary (rule 16)}}'
+      done: false
+    - id: T007
+      kind: reconcile
+      text: 'ach.md § 3 if a new component landed, an ADR if a decision materialized, the US status in ust.md, and the status key of spec.md, plan.md and tasks.md set to done'
+      done: false
+---
+
+# Feature {{NNN}} — Tasks
+
+<!-- guidance -->
+> The tasks live in the frontmatter `tasks:` list, never as a checklist in this body. Add each one with `afm task add {{NNN}} --kind <setup|red|green|refactor|reconcile> --text "..." [--scenario N] [--closes Txxx] [--validates <boundary>] [--files a,b] [--refs US-NNN,RF-NN] [--parallel]`: the CLI assigns the id, refuses an item that breaks a rule `afm feature lint` grades, and keeps the reconcile task last (reopening it when it was done). Correct a field with `afm task set {{NNN}} Txxx --<field> <value>`. Close each one with `afm task done {{NNN}} Txxx`: a green waits for its red, a refactor for the task before it. Never edit the list by hand.
+> A TDD cycle of `core/afm.md` § 2 is a red task (`scenario: N` of spec § 3), then a green task that closes it (`closes:` the red), then an optional refactor. `parallel: true` marks a task with no dependency on the task right before it; a green or a refactor never is.
+> Each new component of plan § 2 is in the `files:` of one task, with the exact path of the plan cell. Each boundary of plan § 5 needs a task whose `validates:` is its name (`### Boundary <name>`): the task that validates its input (rule 16).
+> One reconcile task, the last: `afm task done` refuses it while another task is open. Run `afm feature lint {{NNN}}` until it exits 0.
+> Before you start, `plan.md` has no open `[NEEDS CLARIFICATION:]` marker.
+<!-- /guidance -->
+
+## Notes
+
+{{ex: what the list does not say: the order of the phases, a dependency between tasks, a risk}}
+
+<!-- guidance -->
+> **Version bump.** In a delivery of more than one commit, the version bump is a **precondition of every commit that touches the installable surface**. It is not a task: a bump in the reconcile task leaves the earlier commits failing the gate.
+> Every task references US-NNN or RF-NN in the commit (rule in `core/afm.md` § 2, step 7 COMMIT). Never skip the red task (rule 1 — TDD).
+<!-- /guidance -->

package/content/templates/focus.template.md

@@ -0,0 +1,30 @@
+---
+type: template
+description: 'Template rendered during materialization: Current focus.'
+load: cold
+renders_to: 'docs/_focus.md'
+frontmatter_for_output: |
+  type: state
+  description: 'Where the work is now: the focus, the last steps, the next step and the blockers.'
+  load: hot
+---
+
+# Current focus
+
+<!-- guidance -->
+> This is **MUTABLE** work state (slot-state, `type: state`). The agent **OVERWRITES** it when the focus changes (`reconcile` proposes it; no hook writes the body). It does not grow by append (hard rule 20). This exempts it from rule 17, the anti-context-collapse rule. It is NOT normative knowledge. It does not enter the A1-A7 axes of `diagnose`. It answers only "where am I now". The `afm.md § 2 LER` step reads it. The SessionStart hook injects it with its age ("last updated N days ago", from the last commit or the file's mtime) and flags it as possibly stale after 7 days. It is one page only (KISS). There is no `_slots/` folder and no consolidator.
+<!-- /guidance -->
+
+```
+protocol: {{p1|p2|p3, or omit for the core/protocol.md § 2 defaults}}
+cadence: reflect={{N}} evolve={{N}}
+```
+
+<!-- guidance -->
+> The two lines above are **declarations read by a hook**, not prose. `protocol:` sets the posture (`core/protocol.md § 7`). `cadence:` overrides `REFLECT_EVERY`/`EVOLVE_EVERY` (§ 2). `reflect=off` turns off the `Stop` block. Both lines are optional. When absent, the defaults apply.
+<!-- /guidance -->
+
+- **Now:** {{the task/feature in focus}}
+- **Last steps:** {{what was just done}}
+- **Next steps:** {{the next concrete step}}
+- **Blockers:** {{what blocks progress, if anything}}

package/content/templates/gotcha.template.md

@@ -0,0 +1,31 @@
+---
+type: template
+description: One gotcha, as its own file under docs/gotchas/.
+load: cold
+renders_to: 'docs/gotchas/*.md'
+frontmatter_for_output: |
+  type: gotcha
+  description: '<what the reader LEARNS, not what the file is>'
+  load: warm
+  fires_on: event             # event | file-shape. Prefer event over a guessed path.
+  trigger_path: '{{glob}}'    # ONLY when fires_on is file-shape, and a narrow glob.
+  fires_when: '<if you edit X, or touch Y, or investigate Z>'
+  bites: 2                    # OPTIONAL. 2 when it bit twice, 1 when it is documented SDK behavior; omit it and `afm gotcha bite` starts it at 1.
+  last_bite: YYYY-MM          # OPTIONAL, with bites. The month of the latest bite.
+  refs:                       # ADR ids, paths, links. Omit the key when there are none.
+    - ADR-NNNN
+---
+
+# {{Área}} — {{título do gotcha}}
+
+<!-- guidance -->
+<!-- The counter lives in the frontmatter (`bites`, `last_bite`), ACE-style: `afm gotcha bite <id>` increments `bites` and sets `last_bite` on each new bite. A gotcha is confirmed 2 or more times on entry (qualification rule in `ops/gotcha.md`). 2 or more gotchas in the same area call for `afm generalize` (this consolidates them at the root, and prevents inflation). An old `last_bite` with `bites` stalled is a candidate for pruning in `afm restructure` (tombstone under rule 17: this measures incidence, not self-reported avoidance). -->
+<!-- /guidance -->
+
+## Behavior
+
+{{what looks intuitive + why it breaks. Cite a real reproduction or documented behavior}}
+
+## Solution
+
+{{what to do instead. Make it concrete, not "be careful"}}

package/content/templates/guardrail-runner.template.md

@@ -0,0 +1,97 @@
+---
+type: template
+description: 'Template rendered during materialization: Template — guardrail runner.'
+load: cold
+renders_to: 'docs/tools/gate/rules/*.sh'
+---
+
+# Template — guardrail runner
+
+<!-- guidance -->
+> Skeleton of the script that a guardrail of **`hard-rule` origin** runs. The consumer repo materializes it as `docs/tools/gate/rules/<NN>-<slug>.sh` (or the path the project already uses for gates).
+> **Two forms.** `afm rule new` writes a TypeScript skeleton (`<NN>-<slug>.ts`) by default and a bash one (`<NN>-<slug>.sh`) with `--runner sh`. Use TypeScript when the check is "files in a scope, a regex per line": no shell, no execute bit, and it runs on Windows. Use bash (or any executable) for a diff, a count against the ratchet, or another tool. Both obey the contract below.
+> **The runner is the only part you write.** Since 3.7.0-rc.1 the aggregator, its two libraries, the ratchet and the hook body arrive materialized in `docs/tools/gate/`. Before that they were described here and shipped nowhere, so a runner written from this template died at its own `source` line.
+<!-- /guidance -->
+
+## Contract
+
+```
+argv[1]          : "staged" | "worktree"
+env RATCHET      : path to the budget baseline (TSV: rule region count note)
+env AFM_GATE_LIB : directory holding scope.sh and ratchet.sh, exported by the aggregator
+
+stdout      : one line per finding — "<NN>\t<path>[:<line>]\t<short message>"
+exit 0      : compliant
+exit 1      : violation found
+exit 2      : COULD NOT decide (missing dependency, mode not applicable)
+```
+
+<!-- guidance -->
+**Exit 2 is mandatory. It is not decoration.** "Could not verify" must never become "failed". The first machine without the tool would turn the gate into a permanent block. A gate like that gets disabled, together with every other gate in the same aggregator.
+<!-- /guidance -->
+
+## The two classes — choose before you write
+
+| Class | Scope | Budget | Example |
+| --- | --- | --- | --- |
+| **Diff** | the index (what becomes the commit) | always 0 | plaintext secret, version bump, test that must run |
+| **Count** | the whole repo, **even in `--staged`** | ratchet, decreases only | path convention, identifier language, single source |
+
+<!-- guidance -->
+Counting a count rule over the index is a **silent false negative**. With a budget of 7, a commit that adds 1 new violation counts 1 ≤ 7 and passes clean. The ratchet means "did not grow" only if it measures the same total it recorded.
+<!-- /guidance -->
+
+## Skeleton: TypeScript (the default)
+
+`afm gate` runs the file in a child process (`afm gate ts-runner`) under the same timeout and exit contract. The default export is a function of the rule builder: it imports nothing.
+
+```ts
+export default ({ rule }) =>
+  rule("{{NN}}")
+    .in("{{glob}}")              // repeat .in to add globs
+    .except("{{glob}}")          // paths left out
+    .skipping(/{{comment}}/)     // a line that matches is ignored
+    .forbid(/{{pattern}}/, "{{message}}");   // or .require(/{{pattern}}/, "{{message}}")
+```
+
+The builder reports each match at its line and exits 0, 1 or 2 for you. Check it with `afm gate --dry-run --only {{NN}}`. Full API: `docs/tools/gate/rules/README.md`. The skeleton `afm rule new` writes throws until you replace it, so an unfinished rule exits 2 and never passes.
+
+## Skeleton: bash
+
+```bash
+#!/usr/bin/env bash
+# Hard rule {{NN}} — {{short statement}}.
+# Why a gate, not a paragraph: {{the mistake is cheap to make, expensive to review, and
+# the review that would catch it does not scale — it costs context every time the code is touched}}.
+set -u
+MODE="${1:-staged}"
+REPO="$(git rev-parse --show-toplevel)"
+# Resolve the library through the variable, never through a fixed path. The runner does not
+# know where the gate lives, which is what lets the same runner work in a project that keeps
+# it under `docs/tools/gate/` and in one that keeps it somewhere else.
+. "${AFM_GATE_LIB:?}/scope.sh"
+
+# Dependency guard — exit 2, never 1.
+# command -v {{tool}} >/dev/null 2>&1 || exit 2
+
+RC=0
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  while IFS=: read -r n _; do
+    printf '{{NN}}\t%s:%s\t{{message}}\n' "$f" "$n"
+    RC=1
+  done < <(grep -n '{{pattern}}' "$REPO/$f")
+done < <(scope_all '{{pathspec}}')   # scope_files "$MODE" ... for a DIFF rule
+
+exit $RC
+```
+
+## Before you call it done
+
+- [ ] Did the assertion **fail on the old code**? Before you accept it, run it against the code as it was before the fix (`git show HEAD:<file>`, or the parent commit). It MUST fail there. A regression test that passes on the old code proves nothing.
+- [ ] Does the command **distinguish** the violating case from the clean case? Test both. A gate that returns green without checking buys trust it cannot back up.
+- [ ] Is there a diff that **passes the trigger but violates the intent** of the rule? If yes, the rule is reward-hackable. Rewrite it, or demote it to a principle (`core/afm.md § 1.3`).
+- [ ] Does the runner fail **legitimate work** in any real case in the repo? Test this before you turn the gate on. Failing correct work is the shortest path to `--no-verify` becoming a habit.
+- [ ] Did you run `guardrails.sh --baseline` before turning the rule on? It records what HEAD already breaks as declared debt. **A gate that starts red is disabled the next day**, and it takes every other rule in the same aggregator with it.
+- [ ] Is the constant (threshold, prefix, directory list) **the operator's own**? Measure the repo and propose it together with the measurement (`ops/rule.md` 3.6). A "best practice" value set by the agent is the first thing to get turned off.
+- [ ] Was the ratchet's `count` **measured on HEAD** before you turned the gate on? A gate that starts red gets turned off the next day.

package/content/templates/guardrail.template.md

@@ -0,0 +1,63 @@
+---
+type: template
+description: 'Template rendered during materialization: Guardrail: {{title — what this gate blocks}}.'
+load: cold
+renders_to: 'docs/guardrails/*.md'
+frontmatter_for_output: |
+  type: guardrail
+  description: '<one sentence: what this gate blocks>'
+  load: warm
+  id: '<stable kebab-case slug>'
+  origin: recurring-failure | hard-rule
+  surface: pre-commit | ci | linter | type-check | script-local   # the chosen surface
+  trigger: '<the 0/1 command>'
+  cost: low | medium | high
+  signal: '<the concrete error people kept fixing by hand: import from billing into ui, a new case in the union broke nothing>'
+  installed_on: 'YYYY-MM-DD'   # omit the key while the guardrail is still a proposal
+---
+
+# Guardrail: {{title — what this gate blocks}}
+
+<!-- guidance -->
+> This is a **mechanical** gate. A 0/1 check runs it on its own. It needs no judgment and no one to remember it.
+> Family `docs/guardrails/` (v3.5.0+). One responsibility per file.
+<!-- /guidance -->
+
+**Two origins, one artifact** (the object is the same: a 0/1 check plus the burden of proof to refute it):
+
+| `origin:` | Where it comes from | Who proposes it |
+| --- | --- | --- |
+| `recurring-failure` | `sig=` recurred in the failure records (`afm failures promotable`) | `remediate.md` (CRITIC loop, `failure-classification.md` rubric — precedence destination) |
+| `hard-rule` | a hard rule already written in `afm.md § 3`, with a 0/1 trigger no one ran | `rule.md § Install the gate` |
+
+## Origin
+
+{{The failure record (sig=`<hash>`, recurred N times), "explicit user correction on <date>", OR, for `hard-rule`, the rule number and proof its trigger never ran. If the surface is a new tool, state its cost.}}
+
+## The trigger
+
+`{{comando}}` returns {{0 or nonzero}} when {{the condition}}.
+
+<!-- guidance -->
+This is the guardrail's whole contract. If the command cannot tell the violated case from the clean case, **the guardrail does not exist**. Measure it before you trust it. A gate that returns green without checking is worse than no gate. It buys trust it cannot back up.
+<!-- /guidance -->
+
+## Why mechanical, not documented
+
+{{Why a procedure or a learning was not enough here. Usually: the error is cheap to make, costly to review, and the review that would catch it does not scale. It spends context every time the code is touched.}}
+
+## Accepted cost
+
+{{What this gate charges: build time, a known false positive, ceremony on a legitimate change. An undeclared cost breeds resentment. The next agent then disables the gate without recording why.}}
+
+## What would refute this
+
+{{Mandatory. The conditions under which this guardrail stops making sense, and who carries the burden of proof to remove it.}}
+
+- {{condition 1 — e.g., "the project has only one package, so there is no boundary to cross without a graph"}}
+- {{condition 2 — e.g., "measured it, and the command misses the violation you actually have"}}
+- {{condition 3 — e.g., "the structure is still forming, so freezing it now rejects legitimate work"}}
+
+<!-- guidance -->
+> **Burden of proof.** Changing or removing this guardrail requires **refuting one of the conditions above with evidence**, not claiming that it got in the way. Friction is the gate's intended effect. Friction alone does not prove the gate is wrong. Same discipline as "a violated rule is not a wrong rule" (`ops/reflect.md § 2`).
+<!-- /guidance -->

package/content/templates/learning.template.md

@@ -0,0 +1,40 @@
+---
+type: template
+description: 'Template rendered during materialization: Learning: {{title — the lesson in one line}}.'
+load: cold
+renders_to: 'docs/learnings/*.md'
+frontmatter_for_output: |
+  type: learning
+  description: '<one sentence: the lesson, and the area it applies to>'
+  load: warm
+  fires_on: file-shape
+  trigger_path: 'the glob whose files this lesson applies to'
+  fires_when: 'if you edit <area or path>, read this file first'
+  origin: 'the failure record (sig=<hash>) or the explicit user correction that recognized the failure'
+  recognized_by: 'the external signal: a red test, tsc, a command returning non-zero, or a user correction'
+---
+
+# Learning: {{title — the lesson in one line}}
+
+<!-- guidance -->
+> This is an instructive file for **other Claude sessions** (and developers). It holds one **conceptual** lesson from a real failure.
+> This file belongs to the `docs/learnings/` family (v3.1.0+). It comes from the CRITIC loop (`remediate.md`) when the failure is conceptual or contextual. The value sits in the *cause*, not in a mechanical sequence of steps — that case belongs in a `procedure` instead. The hook `afm-pre-edit.sh` injects this file into future sessions by path match (see `trigger_path` and `fires_when` in the frontmatter). Keep one lesson per file.
+<!-- /guidance -->
+
+## What failed
+
+{{The concrete symptom, anchored in the external signal — the command that returned ≠0, or the user's correction. Do not write "I thought I failed". CRITIC requires recognition by tool, not self-judgment.}}
+
+## The lesson
+
+{{The conceptual root cause and what to do differently. This is reusable knowledge — the "why", not only the "what". If another Claude session, without this session's context, needs this fact to avoid repeating the failure, it belongs here (#1).}}
+
+## How to apply
+
+{{What the next agent must do when it touches the trigger area. Keep this concrete and actionable.}}
+
+---
+
+<!-- guidance -->
+> This file **does not become a hard rule** (it has no executable 0/1 trigger — a rule with a trigger belongs in `afm.md § 3`). It is **not a gotcha** either (a gotcha is an SDK or runtime surprise, a learning is a lesson from one's own failure). This file is injectable conceptual instruction. If the lesson later gains a mechanical trigger, promote it to a rule (`afm rule`). If 2 or more learnings converge on the same point, consider `afm generalize`.
+<!-- /guidance -->

package/content/templates/procedure.template.md

@@ -0,0 +1,47 @@
+---
+type: template
+description: 'Template rendered during materialization: Procedure: {{title — what this runbook does}}.'
+load: cold
+renders_to: 'docs/procedures/*.md'
+frontmatter_for_output: |
+  type: procedure
+  description: '<one sentence: what this runbook does>'
+  load: cold
+  fires_on: event | cadence
+  fires_when: 'the condition that starts this runbook, in one line: before cutting a release, when the build fails with X'
+  owner: 'who maintains this (optional, omit the key when nobody does)'
+  last_run: 'YYYY-MM-DD: update on each run (optional)'
+  origin: 'the failure record (sig=<hash>, recurred N times) or: operational sequence observed N times'
+---
+
+# Procedure: {{title — what this runbook does}}
+
+<!-- guidance -->
+> Repeatable runbook. A **mechanical** sequence of steps, each with a 0/1 check.
+> Family `docs/procedures/`, since v3.1.0. It starts from a mechanical failure that
+> recurred (CRITIC loop, `remediate.md`) OR from an operational sequence repeated
+> 2+ times (release, deploy, migration). One responsibility per file, 300 lines max.
+<!-- /guidance -->
+
+## Preconditions
+
+{{What must be true before you start. Reference `afm.md § 6.1` (pre-push) and current rules. Do not duplicate them — point to them.}}
+
+## Steps
+
+1. {{action}} — `{{command}}`
+   *Check:* `{{0/1 command}}` returns {{expected result}}.
+2. {{action}} — `{{command}}`
+   *Check:* `{{0/1 command}}` returns {{expected result}}.
+
+<!-- guidance -->
+> Each step has a **command** and a **0/1 check**. A step with no executable check is not a procedure. It is prose, so it becomes a `learning` instead.
+<!-- /guidance -->
+
+## Rollback
+
+{{How to undo safely if a step fails. Flag any irreversible external effect BEFORE the DB commit (saga ordering, `afm.md § 1.3`).}}
+
+## Known gotchas
+
+{{Links to the surprises in `docs/gotchas.md` that bite during this runbook. Do not copy them here — link to them.}}

package/content/templates/protocols/p1.md

@@ -0,0 +1,29 @@
+---
+type: protocol
+description: 'Template rendered during materialization: P1 — Autonomous Delivery.'
+load: cold
+---
+
+# P1 — Autonomous Delivery
+
+> POC and MVP work. Speed and no interaction matter more than depth.
+> **Granted per session, never by the repo** (`core/protocol.md` § 6).
+
+| Field | Value |
+| --- | --- |
+| `plan` | `auto` |
+| `exec` | `auto` |
+| `RETRY_CAP` | 2 |
+| `ROUND_CAP` | **0** |
+| `MAX_DISCOVERY_ROUNDS` | 2 |
+| `HALT_PER_PHASE` | off |
+| `SUPPRESS_SUBGATES` | on |
+| `UNKNOWN_POLICY` | `[ASSUMIDO: X — porque Y]` |
+| `delegation` | full |
+| `MAX_PARALLEL_SUBAGENTS` | 4 |
+
+**What "autonomous" does NOT mean here:** a hard rule with an executable trigger still stays 0/1. Safety posture stays non-negotiable (`afm.md § 1.3`). P1 relaxes **depth**: coverage, edge-case exhaustiveness, and name refinement.
+
+**How "no questions" works mechanically:** `ROUND_CAP = 0`. With no round available, every irreducible unknown falls to `UNKNOWN_POLICY`. It becomes an assumption **recorded in the artifact** — documented, never guessed in silence (principle #4).
+
+**Cadence:** run `reflect` after each deliverable. Run `evolve` every 3-4 deliverables.

package/content/templates/protocols/p2.md

@@ -0,0 +1,28 @@
+---
+type: protocol
+description: 'Template rendered during materialization: P2 — Assisted Delivery.'
+load: cold
+---
+
+# P2 — Assisted Delivery
+
+> pair programming. The human is the senior dev. The agent escalates early instead of continuing on a wrong path.
+
+| Field | Value |
+| --- | --- |
+| `plan` | `assisted` |
+| `exec` | `assisted` |
+| `RETRY_CAP` | **1** |
+| `ROUND_CAP` | 4 |
+| `MAX_DISCOVERY_ROUNDS` | 3 |
+| `HALT_PER_PHASE` | **on** |
+| `SUPPRESS_SUBGATES` | **off** |
+| `UNKNOWN_POLICY` | ask |
+| `delegation` | none |
+| `MAX_PARALLEL_SUBAGENTS` | **2** |
+
+**P2 is compositional, not introspective.** It does not mean "ask when unsure". Self-reported confidence is not a mechanical trigger (principle #3). CRITIC shows that self-critique without an external tool degrades quality. P2 sets exactly three existing knobs: suppression off, `RETRY_CAP=1` (the first red escalates), and per-phase halt.
+
+**Floor.** Below the feature-folder heuristic (`afm.md § 2.1`), the posture degrades to "report before you commit". Asking at every step of a trivial change adds noise. Noise makes people turn the protocol off, and that is worse than not having it.
+
+**Cadence:** run `reflect` after each deliverable. Run `evolve` every 3 to 4 deliverables.