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

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

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"}}