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

package/content/skills/update.md

@@ -0,0 +1,56 @@
+---
+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)
+
+This is the sync skill of `afm`. The canonical procedure is the op `afm path ops/update`. 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`.
+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
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Follow #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,31 @@
+---
+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)
+
+Atomic skill of `afm`. The canonical procedure is the op `afm path ops/verify`.
+
+## 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
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. #5 is load-bearing here.

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,129 @@
+---
+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>'
+---
+
+# 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.
+>
+> **`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.
+
+> **In this file:** Vital signs · Findings (φ signature) · Evolution package · ADRs created in this cycle · Attempt memory (anti-oscillation) · Mechanical post-conditions · Suggested promotion
+
+> 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,86 @@
+---
+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
+
+> **Inferred stack:** {{read from /docs/ach.md § 1, do not reopen the discussion}}
+
+## 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,57 @@
+---
+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>'
+---
+
+# Research — Feature {{NNN}} — {{title}}
+
+> **Triggered by:** {{original marker from spec/plan OR "free investigation: <topic>"}}
+
+<!-- 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 -->
+> **Spec:** 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,67 @@
+---
+type: template
+description: 'Template rendered during materialization: Induced tasks — parameterized template.'
+load: cold
+renders_to: 'docs/templates/feature-tasks.induced.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
+  for_paths:
+    - '{{glob}}'
+  us: US-{{NNN}}            # Omit when no US is linked.
+  rf: RF-{{NN}}             # Omit when no RF is linked.
+---
+
+# Induced tasks — parameterized template
+
+<!-- guidance -->
+> **Source:** induced by `afm export-template` from a feature that is **delivered and 100% green** (`tasks.md` with all tasks `- [X]` — gate `L_eval=1` of AWM). The concrete values of the original feature are parameterized as `{variables}`.
+> **Ancestor:** 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.
+> **Use:** the next consumer of this template starts here (fills in the variables) instead of generating tasks from scratch. It keeps the TDD convention of `feature-tasks.template.md`. Each task is a cycle of `core/afm.md § 2`.
+<!-- /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 | `subscriptionCreate` |
+
+## Phase 1 — Setup
+
+- [ ] T001 [P] Create the file `{{src-path}}/domain/{domain}.ts` with exported signature `domain_{domain}`.
+- [ ] T002 [P] Create the test fixture in `{{src-path}}/domain/{domain}.fixtures.ts`.
+
+## Phase 2 — Foundation (write failing tests first)
+
+- [ ] T003 — RED: write test `domain_{domain} returns <result> given <input>` in `{{src-path}}/domain/{domain}.test.ts` (US-NNN scenario 1).
+- [ ] T004 — GREEN: add the minimal implementation of `domain_{domain}` that passes T003.
+- [ ] T005 — REFACTOR: extract a helper if DRY reaches 3 callers (rule 8).
+
+## Phase 3 — Boundary
+
+- [ ] T006 — RED: write a test for procedure `{boundary-procedure}` that calls `domain_{domain}` (US-NNN scenario 1).
+- [ ] T007 — GREEN: add the minimal procedure.
+- [ ] T008 [P] — RED: write a test for the error path of an invalid `{entity}` (US-NNN scenario 2).
+- [ ] T009 — GREEN: add Zod validation at the boundary (rule 16).
+
+## Phase 4 — Reconciliation (8.5)
+
+<!-- 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 of this phase: a final-phase bump leaves the earlier commits failing the gate.
+<!-- /guidance -->
+
+- [ ] T010 — Update `ach.md § 3` if a new component (`{domain}`/`{entity}`) was added.
+- [ ] T011 — Add an ADR if an architectural decision was made (see `ops/adr.md`).
+- [ ] T012 — Update the US status in `ust.md` to `done`.
+- [ ] T013 — Move the spec status to `done` (the `status` frontmatter key of `spec.md`, `plan.md` and `tasks.md`).
+
+---
+
+<!-- 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 and must run as a cycle of `core/afm.md § 2`. Do not skip RED (rule 1).*
+<!-- /guidance -->

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

@@ -0,0 +1,60 @@
+---
+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
+                              # same last task (Phase 4, T013) 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.
+---
+
+# Feature {{NNN}} — Tasks
+
+<!-- guidance -->
+> **Convention:** Tasks follow TDD order. `[P]` marks a task you can run in parallel, with no dependency on the task right before it. Each task is one cycle of `core/afm.md` § 2 (RED → GREEN → REFACTOR → COMMIT).
+> **Prerequisite:** `plan.md` has no open `[NEEDS CLARIFICATION:]` marker.
+<!-- /guidance -->
+
+## Phase 1 — Setup
+
+- [ ] T001 [P] {{ex: create empty file `{{src-path}}/domain/x.ts` with an exported signature}}
+- [ ] T002 [P] {{ex: create test fixture in `{{src-path}}/domain/x.fixtures.ts`}}
+
+## Phase 2 — Foundation (failing tests first)
+
+- [ ] T003 — RED: test `domain_x returns Y given Z` in `{{src-path}}/domain/x.test.ts` (US-NNN scenario 1)
+- [ ] T004 — GREEN: minimal implementation of `domain_x` that passes T003
+- [ ] T005 — REFACTOR: extract `parseInput` if DRY has 3+ callers (rule 8)
+
+## Phase 3 — Boundary
+
+- [ ] T006 — RED: test the `xCreate` procedure that calls `domain_x` (US-NNN scenario 1)
+- [ ] T007 — GREEN: minimal procedure
+- [ ] T008 [P] — RED: test the `INVALID_INPUT` error path (US-NNN scenario 2)
+- [ ] T009 — GREEN: Zod validation at the boundary (rule 16)
+
+## Phase 4 — Reconciliation (8.5)
+
+<!-- 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 of this phase: a final-phase bump leaves the earlier commits failing the gate.
+<!-- /guidance -->
+
+- [ ] T010 — Update `ach.md` § 3 if a new component landed
+- [ ] T011 — Add an ADR if an architectural decision materialized (see `ops/adr.md`)
+- [ ] T012 — Update the US status in `ust.md` to `done`
+- [ ] T013 — Move the spec status to `done` (the `status` frontmatter key of `spec.md`, `plan.md` and `tasks.md`)
+
+---
+
+<!-- guidance -->
+*Every task references US-NNN or RF-NN in the commit (rule in `core/afm.md` § 2, step 7 COMMIT).*
+*Every task runs as a `core/afm.md` § 2 cycle. Never skip RED (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}}