@tenkara/afm-linux-arm64 4.0.0-alpha.7 → 4.0.0-alpha.8

package/content/ops/reflect.md

@@ -4,11 +4,10 @@ description: Refines a doc that guided the agent wrong, using evidence from the
 load: warm
 writes: ["docs/evolution/*.md"]
 composes: []
+ancestors: the *Reflect* operator from Autogenesis (arXiv 2604.15034 — execution traces build causal hypotheses of failure), composed with the *MetaReflect* step of MetaReflection (arXiv 2405.13009 — self-reflection on failure is **episodic memory**).
 ---
 # Sub-flow: behavioral self-reflection on the docs (`reflect`)
 
-> **In this file:** What reflect is / is not · Pre-check · 1. Behavioral evidence collection · 2. Self-critique: doc-wrong vs agent-non-conforman… · 3. Proposal: make the doc more assertive + s… · 4. Own gate (à-la-carte) — suppressed und… · 5. Record + session closing + handoff · Suppression contract · Anti-patterns
-
 
 > **Form** — effect: edits + `evolution/<date>-NNN` + `sessions/<...>` + candidates for `guardrails/` · trigger: `afm reflect`, composition, **cadence** · precondition: friction lived in the session · composed by: `evolve` 1.2, `deliver` 4.D · proposes: `afm evolve` (§ 5, à-la-carte only) · **degree of freedom: medium**
 
@@ -18,8 +17,6 @@ Triggers: `afm reflect`. Also natural language about a **doc that guided badly**
 >
 > **Mechanism, not conductor.** `reflect` is one of the mechanism skills in the self-evolution cycle. `evolve` is the orchestrator that composes it. `reflect` runs **à-la-carte** (this doc, with its own gate). Or it runs inside the `evolve` cycle, which suppresses the own gate and consolidates results — see `evolve.md § Suppression contract`.
 >
-> **Ancestors:** the *Reflect* operator from Autogenesis (arXiv 2604.15034 — execution traces build causal hypotheses of failure), composed with the *MetaReflect* step of MetaReflection (arXiv 2405.13009 — self-reflection on failure is **episodic memory**).
->
 >     Reflect(session_trace) -> φ_b:
 >       1. scan session_trace for a point where a core doc guided the agent badly
 >       2. φ_b := (symptom-lived, causal-status-of-the-doc, mechanism)

package/content/ops/remediate.md

@@ -4,11 +4,10 @@ description: Turns a failure that repeats into a durable artifact, recognized by
 load: warm
 writes: ["docs/procedures/*.md", "docs/learnings/*.md", "docs/guardrails/*.md"]
 composes: []
+ancestors: "CRITIC (arXiv 2305.11738) — failure recognition is anchored in an **external tool or signal**. Self-critique with no tool degrades (PRINCIPLES #3). This op complements the short in-task loop in `afm.md § 5.1` (ephemeral Reflexion, cap 2). `remediate` is the **long loop**: when a failure crosses the § 5.1 terminal (non-transient) and recurs, it becomes a **durable** remediation."
 ---
 # Sub-flow: remediation of a recognized failure (`remediate`) — CRITIC loop
 
-> **In this file:** What `remediate` is / is not · Pre-check · Procedure · Composition (suppression contract) · Anti-patterns
-
 > **Form** — effect: `guardrails/`, `procedures/`, or `learnings/` · trigger: `afm remediate`, composition · precondition: a failure in the state store that `afm failures promotable` lists · composed by: `evolve` 1.3, `reconcile` · **degree of freedom: medium**
 
 Triggers: `afm remediate`.
@@ -23,8 +22,6 @@ Example phrases:
 > **Installing a guardrail uses one procedure.** When the rubric classifies the failure as *mechanizable* and the target is `docs/guardrails/`, follow [`rule.md` § Install the gate](./rule.md) — it covers discovery of the surface the project already runs, the runner built from [`../templates/guardrail-runner.template.md`](../templates/guardrail-runner.template.md), **measuring HEAD before turning the gate on** (a gate that starts red gets turned off the next day), measured cost, doc-runner sync, and recording with `origin: recurring-failure`. This op does not repeat those steps (rule 34): the origin differs, but the install path is the same.
 
 > **Target = this project's local docs (`<consumer>/docs/`), never the plugin.** Like every AFM write family, `remediate` writes to `<consumer>/docs/` (guardrails/procedures/learnings) and **proposes** — the human approves (#6). No op writes to the plugin: `afm promote` only records a finding for it.
->
-> **Ancestor:** CRITIC (arXiv 2305.11738) — failure recognition is anchored in an **external tool or signal**. Self-critique with no tool degrades (PRINCIPLES #3). This op complements the short in-task loop in `afm.md § 5.1` (ephemeral Reflexion, cap 2). `remediate` is the **long loop**: when a failure crosses the § 5.1 terminal (non-transient) and recurs, it becomes a **durable** remediation.
 
 ---
 

package/content/ops/restructure.md

@@ -4,11 +4,10 @@ description: Checks the health of the context architecture and finds what went s
 load: warm
 writes: ["docs/evolution/*.md"]
 composes: []
+ancestors: Codified-Context (arXiv 2602.20478).
 ---
 # Sub-flow: context architecture health (`restructure`)
 
-> **In this file:** What restructure is / is not · Pre-check · 1. Staleness scan · 2. Findability · 3. Partition by temperature · 4. Own gate (a-la-carte) + application — s… · 5. Record + handoff · Suppression contract · Anti-patterns
-
 
 > **Form** — effect: edits + opt-in ADR · trigger: `afm restructure`, composition · pre-condition: git + `bites`/`last_bite` · composed by: `evolve` 1.3 · **degree of freedom: medium**
 
@@ -18,8 +17,6 @@ Triggers: `afm restructure`, or natural language about **structure/staleness** (
 >
 > **Mechanism, not conductor.** `restructure` is the mechanism skill that checks whether the docs are **structured to load efficiently** and **keep pace with the code**. It runs **a-la-carte** (own gate) OR inside the `evolve` cycle (which composes it when `diagnose` flags staleness or a badly partitioned doc — the own gate is then suppressed).
 >
-> **Ancestor:** Codified-Context (arXiv 2602.20478).
->
 >     CodifiedContext(doc, path):
 >       1. Tier(content) := its memory temperature: hot-always (every turn) | per-task | on-demand (deep reference)
 >       2. GitEvidence(claim) := a `git log` comparison that confirms or refutes claim              # PRINCIPLES.md #2

package/content/ops/rule.md

@@ -7,8 +7,6 @@ composes: []
 ---
 # Sub-flow: new hard rule
 
-> **In this file:** Procedure · Install the gate · Inalienable rule · Additional for a refactored project
-
 > **Form** — effect: one file under `docs/rules/` plus its index line in `afm.md § 3` (or a principle in `§ 1.3`) · trigger: `afm rule`, composition · precondition: executable 0/1 trigger · composed by: `evolve`, `reflect`, `generalize` · **degree of freedom: low**
 
 Triggers: `afm rule`, or natural language ("new hard rule", "this should be a rule").

package/content/ops/tasks.md

@@ -1,6 +1,6 @@
 ---
 type: op
-description: Breaks a plan into tasks in TDD order, each one a cycle of the loop.
+description: Breaks a plan into the tasks list of tasks.md in TDD order, added with afm task add.
 load: warm
 writes: ["docs/features/*/tasks.md"]
 composes: []
@@ -31,37 +31,37 @@ Procedure:
 
 3. **Read `spec.md` and `plan.md`** in full, for the feature.
 
-4. **Make the tasks** with `afm new feature-tasks --feature NNN-slug --description "..."` (it writes the frontmatter and the template body), then fill the body:
-   - **Phase 1 — Setup:** empty files with a signature and the test fixtures. Typically `[P]` (parallel with each other).
-   - **Phase 2 — Foundation:** for each Gherkin scenario of spec § 3, at least two tasks: a RED test task and a GREEN implementation task. REFACTOR becomes its own task when it adds expected clarity.
-   - **Phase 3 — Boundary:** for each new component of plan § 2, one creation task and one test task. For each boundary of plan § 5, one Zod validation task (rule 16) and one procedure task.
-   - **Phase 4 — Reconciliation (8.5):** fixed tasks. Update `ach.md § 3` if a component is new. Add an ADR (`afm adr new <slug>`, see [`adr.md`](adr.md)) if the work materializes an architectural decision. Set the US status to `done`. **The last task** sets the `status:` frontmatter key of `spec.md`, `plan.md` and `tasks.md` to `done` (or `cancelled` for a feature dropped; hard rule 39). No body line carries the status. It must be last: those edits change the hashed documents, so the delivery approval (`afm approve --check`) goes stale by design and nothing may run after it.
+4. **Make the tasks.** Create the file with `afm new feature-tasks --feature NNN-slug --description "..."` (it writes the frontmatter and the template body), then add every task with `afm task add <NNN>`. The tasks live in the frontmatter `tasks:` list, never as a checklist in the body. The CLI assigns the id, validates the item and refuses one that breaks a rule `afm feature lint` grades (exit 1, the findings printed); you fill only the fields. The body is free prose (phases, notes). Build the list in this order:
+   - **Setup:** empty files with a signature and the test fixtures: `--kind setup --files <paths> --refs <US/RF> --text "..."`, typically `--parallel`.
+   - **Foundation:** for each Gherkin scenario `N` of spec § 3, a red task (`--kind red --scenario N --files <test path>`), then the green task that closes it (`--kind green --closes <the red's id> --files <code path>`). A refactor (`--kind refactor`) follows a green or another refactor, when it adds expected clarity.
+   - **Boundary:** each new component of plan § 2 is in the `--files` of one task, with the exact path of the plan cell. For each boundary of plan § 5 (`### Boundary <name>`), a red task and the green task with the Zod validation (rule 16), added with `--validates <name>`: the lint matches the boundary by that field, never by the task text.
+   - **Reconciliation (8.5):** one task, `--kind reconcile`, always the last (`afm task add` keeps it last, and reopens it when a task lands after it was done): update `ach.md § 3` if a component is new, add an ADR (`afm adr new <slug>`, see [`adr.md`](adr.md)) if the work materializes an architectural decision, set the US status to `done`, and set the `status:` frontmatter key of `spec.md`, `plan.md` and `tasks.md` to `done` (or `cancelled` for a feature dropped; hard rule 39). No body line carries the status. It is last because those edits change the hashed documents, so the delivery approval (`afm approve --check`) goes stale by design and nothing may run after it. `afm task done` refuses it while another task is open, a green while its red is open, and a refactor while the task before it is open.
 
-5. **Mark `[P]`** where a task has no dependency on the task immediately before it. Heuristic:
-   - Fixture tasks, tasks that touch different test files and doc tasks are typically `[P]`.
-   - A GREEN task always depends on the RED task immediately before it: never `[P]`.
-   - A REFACTOR task depends on its GREEN task: never `[P]`.
+5. **Mark `--parallel`** where a task has no dependency on the task immediately before it. Heuristic:
+   - Fixture tasks, tasks that touch different test files and doc tasks are typically parallel.
+   - A green task depends on the red task it closes: never parallel.
+   - A refactor depends on its green task: never parallel.
 
-6. **Every task references `US-NNN` or `RF-NN`.** The rule is `core/afm.md` § 2, step 7 COMMIT: a commit references a US or RF. If the feature has no linked US, fail earlier, at the pre-check.
+6. **Every task references `US-NNN` or `RF-NN`** (`--refs`; the CLI refuses a task without one, except the reconcile task). The rule is `core/afm.md` § 2, step 7 COMMIT: a commit references a US or RF. If the feature has no linked US, fail earlier, at the pre-check.
 
-7. **Mechanical validation before you report** (auto-correct, do not ask). Run `afm feature lint <NNN>`. It checks the structure of `tasks.md` (task lines present, a RED before each GREEN, a US or RF on every task, scenario and component coverage) and exits 1 on CRITICAL or HIGH. For a task without a reference, **add the US linked in the `spec.md` header** at the end of the task: a deterministic fix, no question. Re-run until the exit is 0. Step 6 is the declarative rule; this step is the safety net for an attention lapse.
+7. **Mechanical validation before you report** (auto-correct, do not ask). Run `afm feature lint <NNN>`. It reads the `tasks:` list and checks: each spec scenario has a red task with its number and a later green that closes it, a green closes an earlier red (CRITICAL), a refactor follows a green or a refactor, no green or refactor is parallel, each new plan component is in the `files` of a task, each plan boundary has a task whose `validates` is its name, there is exactly one reconcile task and it is last, every `US-NNN` exists in `ust.md` and every `RF-NN` in `prd.md`, and no checklist line is left in the body. It exits 1 on CRITICAL or HIGH. Fix a finding with `afm task add` (a missing task), `afm task set <NNN> <Txxx> [--kind] [--text] [--files] [--refs] [--scenario] [--closes] [--validates] [--parallel|--no-parallel] [--clear <field>]` (the field the finding names; `--clear scenario|closes|validates|files|refs` clears one), or `afm task remove <NNN> <Txxx>` (a task that should not exist; refused while a green closes it), then re-run until the exit is 0. `afm task set` and `afm task remove` run the same rules as `afm task add` and write only the lines they change; a new `--kind` brings its own needs (a green `--closes`, a red `--scenario`). Step 6 is the declarative rule; this step is the safety net for an attention lapse.
 
 8. **Materialize and report** (#6, see [`../PRINCIPLES.md`](../PRINCIPLES.md)): `tasks.md` is written by step 4; print the summary (step 9) with the path. Review happens through `git diff`; no blocking question.
 
-   **Check the frontmatter the template's `frontmatter_for_output:` names** (hard rule 39): `type: feature-tasks`, `description`, `load: cold`, and `for_paths`/`us`/`rf` carried from `plan.md`, unchanged, and `status: planned`. `status` moves to `in_progress` with the first task and to `done` only in the last Reconciliation task (step 4), never earlier.
+   **Check the frontmatter the template's `frontmatter_for_output:` names** (hard rule 39): `type: feature-tasks`, `description`, `load: cold`, and `for_paths`/`us`/`rf` carried from `plan.md`, unchanged, `status: planned`, and the `tasks:` list. `status` moves to `in_progress` with the first task and to `done` only in the reconcile task (step 4), never earlier.
 
 9. **Output to the operator:**
    - The path of `tasks.md`.
-   - The summary `N tasks total / M parallelizable ([P]) / 4 phases`.
+   - The summary `N tasks total / M parallel / red, green, refactor and reconcile counts`.
    - The `[TBD]` markers still in the plan (a flag, not a block).
-   - **Next step:** "Before you start T001, consider `afm analyze` to cross-check coverage between scenarios, tasks and hard rules. It is a read-only report in chat, a safety net and not a gate. After that, each task is one cycle of `core/afm.md` § 2: start with T001. When a task is done, mark it with `afm task done <NNN> <Txxx>`."
+   - **Next step:** "Before you start T001, consider `afm analyze` to cross-check coverage between scenarios, tasks and hard rules. It is a read-only report in chat, a safety net and not a gate. After that, run the tasks in list order: a red task, the green task that closes it, an optional refactor (`core/afm.md` § 2). When a task is done, close it with `afm task done <NNN> <Txxx>`."
 
 ## Anti-patterns
 
-- ❌ Skip RED. This violates rule 1 (TDD).
+- ❌ Skip the red task. This violates rule 1 (TDD).
 - ❌ Create a task with no US or RF reference.
 - ❌ Write a subjective task ("clean up code", "improve naming") with no mechanical criterion.
-- ❌ Mark `[P]` on a GREEN task that depends on the RED task immediately before it.
+- ❌ Mark a green task `--parallel`: it depends on the red task it closes.
 - ❌ Block with a question before writing. Materialize and report; review through `git diff`.
 - ❌ Tolerate an open `[NEEDS CLARIFICATION:]` in the plan. The block is hard: a mechanical refusal, not a question.
-- ❌ Tick a box by hand-editing `tasks.md` during execution. `afm task done` marks it atomically.
+- ❌ Write a task as a checklist line in the body, or edit the `tasks:` list by hand. `afm task add` adds a task, `afm task set` corrects one (its kind included), `afm task remove` drops one and `afm task done` closes it, atomically. When the CLI cannot write an edit it prints `held:` and a `task:` line with its verify; follow that task.

package/content/ops/update.md

@@ -7,8 +7,6 @@ composes: []
 ---
 # Sub-flow: sync of the materialized instance with the current plugin version (`update`)
 
-> **In this file:** What update is / is not · Procedure · What the codemods can do · Instances older than 4.0 · 1.6 Language migration · Opt-in deltas · Post-conditions · Suppression contract · Anti-patterns
-
 > **Form** — effect: deltas in the instance + bump · trigger: `afm update`, composition · precondition: pin ≠ the shipped version · composed by: `evolve` 2.2 · **degree of freedom: low**
 
 Triggers: `afm update`, or natural language for **version bump / sync with the plugin**. Examples:
@@ -161,6 +159,9 @@ noticing during the work, and that is the branch that damages a product.
    scope empty, and the rest is unchanged. `afm lang` reports the language each file is written in.
 4. **Ask ONE question about the artifacts: `afm ask update-artifacts`** (questions in
    `content/questions/update-artifacts.questions.yaml`). Ask it once, never per file. `Keep the current language` records the choice, because the next update must not ask again.
+   Record the answer with `afm config set language.artifacts <tag>` (for example `pt-BR`). The command
+   validates the tag and edits `.afm/config.toml` in place. Never write that key by hand. A language agent task the
+   update prints (`artifact-language:*`) names the exact command; run it, then its 0/1 check.
 5. **On migrate, fan out over the artifacts outside the excluded scope**: the local `docs/`, the code
    comments, the test names. Each file gets a rewrite. Then an adversarial check asks what fact, number,
    path, marker or caveat disappeared. The checker reports; it never rewrites.

package/content/ops/verify.md

@@ -7,8 +7,6 @@ composes: []
 ---
 # Sub-flow: stamp a human verification (`verify`)
 
-> **In this file:** What verify is / is not · Why only a human · Procedure · What it must never do · Invariants
-
 > **Form** — effect: adds `verified:` to the frontmatter of one file · trigger: `afm verify <path>` · precondition: `.afm-version` · **degree of freedom: low**
 
 Triggers: `afm verify <path>`. Also natural language that states a person checked a document.

package/content/questions/init.questions.yaml

@@ -26,3 +26,16 @@ questions:
         description: User-facing strings are in Spanish.
       - label: Decide later
         description: Records [TBD] in the PRD; the language migration stops and asks.
+  - id: artifact-language
+    prompt: In which language are the artifacts of this project written (docs, code comments, test names)?
+    header: Artifacts
+    recommended: en
+    options:
+      - label: en
+        description: English, the default. Nothing is recorded.
+      - label: pt-BR
+        description: Recorded with afm config set language.artifacts pt-BR; the gate skips the English-prose rules.
+      - label: es
+        description: Recorded with afm config set language.artifacts es; the gate skips the English-prose rules.
+      - label: other
+        description: Another tag. Init prints the command to run with the tag the owner names.

package/content/rubrics/failure-classification.md

@@ -9,8 +9,6 @@ fires_when: 'a failure was recognized by an external signal and needs a destinat
 
 # Rubric — failure classification (mechanizable → guardrail | mechanical → procedure | conceptual → learning | transient → nothing)
 
-> **In this file:** Entry gate (common to all three) · The four destinations · Decision flow · Anti-patterns
-
 > The CRITIC loop (`ops/remediate.md`) uses this rubric to remediate a failure recognized and recorded in the state store (`afm failures record`). The discriminator is **executable**. It is not a "feeling". Ancestor: CRITIC (arXiv 2305.11738) — recognize a failure only by external signal. Self-criticism without a tool degrades (PRINCIPLES #3).
 
 ## Entry gate (common to all three)

package/content/rubrics/solid-triggers.md

@@ -11,8 +11,6 @@ fires_when: 'a file name collects unrelated responsibilities, or a provider `swi
 
 # Rubric — SOLID as a concrete trigger (not folklore)
 
-> **In this file:** SRP — Single Responsibility · OCP — Open/Closed: extend without modifying · LSP — Liskov Substitution: interchangeable implementations · ISP — Interface Segregation: minimal port · DIP — Dependency Inversion: domain does not know infra · Summary — what to ask when
-
 
 SOLID is easy to use as an argument and hard to use as a trigger. This rubric converts each principle into a **mechanical trigger** — when to apply it, the anti-pattern, an example.
 

package/content/skills/analyze.md

@@ -19,7 +19,7 @@ Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `afm init`
 
 ## Procedure
 
-Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`). Gating mode sorts findings into buckets instead of reporting.
+Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`); a remediation that adds a task runs `afm task add`, never a hand edit of the `tasks:` list, and a task is closed only with `afm task done`. Gating mode sorts findings into buckets instead of reporting.
 
 ## Invariant principles
 

package/content/skills/deliver.md

@@ -24,10 +24,10 @@ The CLI holds the state; the skill keeps only the judgment. Drive the loop with
 - **Discovery:** scan scoped to the feature, external unknowns through the nasca research flow (`nasca-research`, or `nasca-campaign` for a deep study; ask the operator if nasca is missing), unknowns sorted into resolved-by-scan, researchable and irreducible. One batched, recommendation-first round, capped by the protocol (`afm protocol`).
 - **Draft:** spec, plan and tasks, verified with `afm feature lint <NNN>` plus the judgment passes of `analyze`.
 - **Gate:** the earned questions plus the `outcome` question (`afm ask deliver`), then `afm approve <NNN>`. An explicit "go" skips the questions, never the record.
-- **Execute:** each task is one `core/afm.md` § 2 cycle, checked with `afm gate --staged`, then `afm task done <NNN> <Txxx>`. Halt on a non-`[P]` failure after the capped retry.
+- **Execute:** the tasks of the `tasks:` list run in order (`core/afm.md` § 2: a red task, the green task that closes it, an optional refactor), each checked with `afm gate --staged`, then closed with `afm task done <NNN> <Txxx>`. Tasks are added with `afm task add`, never by hand. Halt on the failure of a task that is not `parallel` after the capped retry.
 - **Reconcile:** § 8.5 plus a passive sweep.
 
-If artifacts already exist, resume from the correct phase, including "tasks already exist, run from the first `[ ]`".
+If artifacts already exist, resume from the correct phase, including "tasks already exist, run from the first task that is not done".
 
 ## Invariant principles
 

package/content/skills/tasks.md

@@ -1,7 +1,7 @@
 ---
 name: tasks
 description: |
-  Generates `tasks.md` in TDD order, and marks the parallel tasks with `[P]`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
+  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".
 ---
 
@@ -19,11 +19,11 @@ Run `afm preflight` (exit 3: stop and suggest `afm init` or `afm refactor`). Run
 
 ## Procedure
 
-Break the plan into four phases (Setup, Foundation RED/GREEN, Boundary, Reconciliation) from the generator (`afm new feature-tasks --feature NNN-slug`). Mark `[P]` only where a task does not depend on the one before it; a GREEN never is. Give every task a `US-NNN` or `RF-NN`. Then run `afm feature lint <NNN>` and fix what it reports until it exits 0. The last task closes the `status:` keys. Autonomy-first: write and report.
+Create the file with the generator (`afm new feature-tasks --feature NNN-slug`), then add every task with `afm task add <NNN> --kind <k> --text <t>`: setup tasks, then for each spec scenario a red task (`--scenario N`) and the green task that closes it (`--closes Txxx`), an optional refactor, the validation task of each plan boundary (`--validates <boundary name>`), and one reconcile task, last. Never write a task by hand: the tasks live in the frontmatter `tasks:` list, and the CLI assigns the id and validates the item. Mark `--parallel` only where a task does not depend on the one before it; a green never is. Give every task a `US-NNN` or `RF-NN` (`--refs`). The CLI refuses an item that breaks a lint rule. Then run `afm feature lint <NNN>` and fix what it reports until it exits 0: a missing task with `afm task add`, a wrong field or kind with `afm task set <NNN> <Txxx> --<field> <value>` (`--clear <field>` clears one), a task that should not exist with `afm task remove <NNN> <Txxx>`. Never edit the YAML by hand. The reconcile task closes the `status:` keys; close each task with `afm task done`. Autonomy-first: write and report.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #5 (every task traces to a US or RF) and rule 1 (TDD: no GREEN without the RED before it).
+Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #5 (every task traces to a US or RF) and rule 1 (TDD: no green task without the red task it closes).
 
 ## Continuous doctrine
 

package/content/templates/adr.template.md

@@ -10,7 +10,7 @@ frontmatter_for_output: |
   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.
+  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.

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

@@ -25,8 +25,6 @@ frontmatter_for_output: |
 > 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 -->
 

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

@@ -17,8 +17,6 @@ frontmatter_for_output: |
 
 # 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.}}

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

@@ -9,12 +9,11 @@ frontmatter_for_output: |
   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}}
 
-> **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 -->

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

@@ -21,7 +21,7 @@ frontmatter_for_output: |
 # Feature {{NNN}} — {{objective title}}
 
 <!-- guidance -->
-> **Spec:** the what and the why. No technology decision.
+> 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 -->
 

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

@@ -3,6 +3,7 @@ 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>'
@@ -12,14 +13,64 @@ frontmatter_for_output: |
     - '{{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 -->
-> **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`.
+> 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
@@ -29,39 +80,12 @@ frontmatter_for_output: |
 | `{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`).
+| `{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 and must run as a cycle of `core/afm.md § 2`. Do not skip RED (rule 1).*
+*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

@@ -9,52 +9,74 @@ frontmatter_for_output: |
   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
+                              # 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 -->
-> **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.
+> 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 -->
 
-## Phase 1 — Setup
+## Notes
 
-- [ ] 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`)
-
----
+{{ex: what the list does not say: the order of the phases, a dependency between tasks, a risk}}
 
 <!-- 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).*
+> **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/protocols/p1.md

@@ -6,7 +6,7 @@ load: cold
 
 # P1 — Autonomous Delivery
 
-> **For:** POC and MVP work. Speed and no interaction matter more than depth.
+> 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 |

package/content/templates/protocols/p2.md

@@ -6,7 +6,7 @@ load: cold
 
 # P2 — Assisted Delivery
 
-> **For:** pair programming. The human is the senior dev. The agent escalates early instead of continuing on a wrong path.
+> pair programming. The human is the senior dev. The agent escalates early instead of continuing on a wrong path.
 
 | Field | Value |
 | --- | --- |

package/content/templates/protocols/p3.md

@@ -6,7 +6,7 @@ load: cold
 
 # P3 — Planned Autonomous Delivery
 
-> **For:** the middle ground — P2 quality with P1 interaction. You plan together. The agent executes alone.
+> the middle ground — P2 quality with P1 interaction. You plan together. The agent executes alone.
 
 | Field | Phase 1 (planning) | Phase 2 (execution) |
 | --- | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tenkara/afm-linux-arm64",
-	"version": "4.0.0-alpha.7",
+	"version": "4.0.0-alpha.8",
 	"description": "The afm binary (CLI and MCP server) for linux-arm64.",
 	"license": "UNLICENSED",
 	"publishConfig": {

package/plugin/agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "afm",
-  "version": "4.0.0-alpha.7",
+  "version": "4.0.0-alpha.8",
   "description": "AFM (Agent Flow Methodology): hooks and an MCP server that keep a project's docs and its code in step.",
   "license": "UNLICENSED"
 }