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

package/content/ops/evolve.md

@@ -4,11 +4,35 @@ description: 'Runs the self-evolution cycle: five mechanisms plus update, under
 load: warm
 writes: ["docs/evolution/*.md"]
 composes: ["diagnose", "reflect", "generalize", "restructure", "update", "remediate"]
+ancestors: the Reflect→Select→Improve→Evaluate→Commit loop from Autogenesis (arXiv 2604.15034), and the Weakness-Mining→Proposal→Validation loop from Self-Harness (arXiv 2606.09498).
+sections:
+  - heading: 'Design notes (conductor, the name, Commit κ)'
+    read_when: 'you ask why evolve is a conductor, or change a Commit κ step'
+  - heading: 'What `evolve` is NOT'
+    read_when: 'tempted to run evolve as an atomic mechanism, optimizer, daemon or `[TBD]` resolver'
+  - heading: 'Cooldown criteria'
+    read_when: 'you need the new-signal definition, the window or the override'
+  - heading: 'Phase 1 procedure'
+    read_when: 'starting Phase 1'
+  - heading: 'Proposal discipline (shared)'
+    read_when: 'proposing any edit, before the gate'
+  - heading: 'Phase 2 procedure'
+    read_when: 'building the package or when A3 flags version drift'
+  - heading: 'Phase 3 procedure'
+    read_when: 'presenting the package at the gate'
+  - heading: 'Phase 4 procedure'
+    read_when: 'applying an approved item or running a postcondition'
+  - heading: 'Phase 5 procedure'
+    read_when: 'writing the evolution report'
+  - heading: 'Whitelist — evolvable vs. protected surfaces'
+    read_when: 'an item edits anything but gotchas, afm.md sections 3 and 1.3, other rubrics, ADR status or the doc-map bridge'
+  - heading: 'Suppression contract (the honest DRY guarantee)'
+    read_when: 'the cycle composes another op (diagnose, reflect, rule, update, remediate and so on)'
+  - heading: 'Conditional anti-patterns'
+    read_when: 'you compose an op, fix a non-restorable reference, or downgrade, renumber or re-propose a rule or item'
 ---
 # Sub-flow: orchestrator for the AFM local documentation self-evolution cycle (`evolve`)
 
-> **In this file:** What `evolve` is / is not · Pre-check · Phase 1 — Evidence collection · Proposal discipline · Phase 2 — Proposal · Phase 3 — Single gate (≈ Commit κ) — always ha… · Phase 4 — Application + postconditions · Phase 5 — Record + promote · Whitelist — evolvable vs. protect… · Suppression contract · Anti-patterns
-
 
 > **Form** — effect: `docs/evolution/<date>-NNN` · trigger: `afm evolve`, **cadence** · precondition: `.afm-version`, cooldown 14d · composed of: — (orchestrator) · **degree of freedom: medium**
 
@@ -30,6 +54,8 @@ Triggers:
 > - **To the plugin, only RECORDS:** if a lesson applies to **any** instance (not only this project), the cycle suggests `afm promote`. That op **records the finding** with `afm findings record`, in the project state, with mechanical evidence. No one applies it to the plugin from here. The boundary is absolute (#7). The maintainer applies it, in the plugin repo.
 >
 
+### Design notes (conductor, the name, Commit κ)
+
 > **The name.** `evolve` is a codename (not descriptive of purpose) — chosen by the framework owner. Natural-language activation does **not** depend on the name: it lives in the skill's `when_to_use`. Renaming it is a **major** change (moves a file under `ops/` and `skills/`).
 >
 > **The `composes:` list has six entries and the cycle has five mechanisms. Both are right.**
@@ -41,8 +67,6 @@ Triggers:
 >
 > This materializes, with no new principle, the combination of invariants #2 (discover-first: diagnose with evidence before proposing), #3 (mechanize-or-downgrade: the invocation signals themselves pass the test that evolve audits in others), #6 (autonomy-first with self-check: *produce → self-check → report*, with the gate as the load-bearing residue), and #8 (earned question, recommendation-first). See [`../PRINCIPLES.md`](../PRINCIPLES.md).
 >
-> **Ancestors:** the Reflect→Select→Improve→Evaluate→Commit loop from Autogenesis (arXiv 2604.15034), and the Weakness-Mining→Proposal→Validation loop from Self-Harness (arXiv 2606.09498).
->
 >     Commit(proposal):
 >       1. ε := Evaluate(proposal)                                    # measured, per the Autogenesis order: ε before κ
 >       2. HeldOutSet := a re-runnable set that scores ε empirically
@@ -78,6 +102,8 @@ design and not an omission:
    - The last cycle **with `mechanism: evolve`** in `docs/evolution/` is **recent** (default under 14 days). Override this with `cooldown-days=` on the `<!-- evolve: ... -->` line of `docs/.afm-version`.
    - **No new signal** appeared since then.
 
+### Cooldown criteria
+
    "New signal" means either:
    - (a) a delta in the `diagnose` checks (Class A/A7) since the last cycle date. Verify this with the findings of `afm doctor --json` against the date of the newest report in `docs/evolution/`, **never** with self-written content. Pass `--signal` only when that delta is real.
    - (b) the stated symptom from step 3 (`--symptom`).
@@ -90,12 +116,16 @@ design and not an omission:
 
 ## Phase 1 — Evidence collection (composes `diagnose` + `reflect`)
 
+Run `diagnose` and `reflect` through the suppression contract and consolidate their bundles into one set of findings. An empty diagnosis is a valid result: report "100%" and stop. Exit: one consolidated set of findings.
+
+### Phase 1 procedure
+
 `evolve` **does not reimplement** the scan or the reflection. It runs them through the suppression contract and consolidates the bundles. This is gap-driven: the symptom from the pre-check sets the depth.
 
 0. **Capture `T0=$(date +%s)`** before any read. This is the baseline for the boundary postcondition (Phase 4.3) when the content root is not a git repo. Without it, the no-git branch has nothing to compare against.
 
-1. **Run `diagnose`** (**mechanical** evidence): `afm doctor --json` for A1-A6, staleness and dead gotchas, plus the A7 paired reading, as `diagnose.md` describes (Phase 0 scan of the 7 axes, plus Phase 1 φ/addressability/severity diagnosis). It returns the evidence bundle. (Run à la carte, `diagnose` prints the bundle. Here it feeds the cycle. `diagnose` does not write `docs/evolution/` — that is Phase 5.)
-2. **Run `reflect`** (**behavioral** evidence). Follow `reflect.md` §§ 1-2 (collect the φ_b signatures seen in the session, plus the self-check "was it me, not the doc"). Suppress `reflect`'s own gate — it moves to the single gate. With no friction in the session, the behavioral axis stays empty. That is a valid result.
+1. **Run `diagnose`** (**mechanical** evidence): `afm doctor --json` for A1-A6, staleness and dead gotchas, plus the A7 paired reading, the `tier-drift` axis (docs and sections whose `load:` tier no longer matches their use) and the `fade` axis (cold orphan docs with no use), as `diagnose.md` describes (Phase 0 scan of the 7 axes, plus Phase 1 φ/addressability/severity diagnosis). It returns the evidence bundle. (Run à la carte, `diagnose` prints the bundle. Here it feeds the cycle. `diagnose` does not write `docs/evolution/` — that is Phase 5.)
+2. **Run `reflect`** (**behavioral** evidence). Follow `reflect.md` §§ 1-2 (collect the φ_b signatures seen in the live session and in the project's sessions since the last evolve cycle, from `afm sessions --since evolve --json` and `afm sessions signals --since evolve --json`, plus the self-check "was it me, not the doc"), with the same weighting: the live session counts on one signal, a past-session signal only when it repeats across 2 or more sessions, is an explicit correction, or is `regressed` (and `regressed` first); a `repeatedPrompt` signal is a first-class finding (see `reflect.md` Pre-check 3). The evolve report also carries `resolves:` with the fingerprints the cycle handled, and every session record covered gets `reflection:` filled. Suppress `reflect`'s own gate — it moves to the single gate. With no friction in the whole window, the behavioral axis stays empty. That is a valid result.
 3. **On-demand proposal mechanisms** (through suppression, own gate suppressed, gap-driven — with no signal, they do not run):
    - `diagnose` axis A3 flags **version drift** (pinned instance ≠ plugin `VERSION`). This composes `update` — a delta-by-delta migration proposal for consumer-facing changes (see Phase 2.2).
    - `diagnose` axis A6 flags **2 or more redundant gotchas** → composes `generalize` (merge proposal).
@@ -106,7 +136,7 @@ design and not an omission:
      This is the cycle's "self-reflection on failures". `diagnose`/rule 19 **flag** the unfixed repeat failure. The cycle **resolves** it at the gate. `remediate`'s own gate is suppressed — it moves to the single gate. This is gated by #5 (negative filters — a transient failure does not get promoted).
 
 3.5. **Guardrail axis — what is still caught by hand, and should be caught by a command**. This axis joins two sources that no one cross-checks today:
-   - the **guardrail candidates** from `reflect § 1.2` — a defect the agent fixed by hand 2 or more times in the session.
+   - the **guardrail candidates** from `reflect § 1.2` — a defect the agent fixed by hand 2 or more times in the window (`--since evolve`).
    - the failures of `afm failures promotable` that the rubric classified as **mechanizable** — a precedence destination.
 
    For each one, run the **surface discovery** from `remediate.md` step 3.5. Look at the linter, type check, CI, or git hooks the project **already** runs. Propose where the check should land.
@@ -179,7 +209,11 @@ For each **addressable** finding, before it reaches the gate:
 
 ## Phase 2 — Proposal (IMPROVER role, in staging)
 
-Apply the **Proposal discipline (shared)** above to each consolidated finding from Phase 1. The mechanisms that already propose changes (`reflect`/`generalize`/`restructure`) bring their proposals ready — they already passed the discipline. `evolve` adds the proposals for the purely mechanical `diagnose` findings — downgrade, archive, merge. This is the logic that **originates here**. `evolve` consolidates everything into one package.
+Apply the proposal discipline to each finding from Phase 1; the package asks at most 8 (b) questions per cycle. Exit: one consolidated package.
+
+### Phase 2 procedure
+
+Apply the **Proposal discipline (shared)** (the section of this file with that title) to each consolidated finding from Phase 1. The mechanisms that already propose changes (`reflect`/`generalize`/`restructure`) bring their proposals ready — they already passed the discipline. `evolve` adds the proposals for the purely mechanical `diagnose` findings — downgrade, archive, merge. This is the logic that **originates here**. `evolve` consolidates everything into one package.
 
 1. **Package cap:** the cap counts **only (b) questions**. It is measured **per cycle** (8 (b) questions total, maximum). `afm evolve gate-check --critical <n> --high <n> --medium <n> --low <n>` computes it: it prints how many to ask now, in how many calls (for example `2 calls (4+4)`), and how many to stage. Present them in **at most 2 calls of at most 4 questions each** (NEVER more than 4 in one call). One **(b) item equals one `multiSelect` option** (including the A2 stance question and the A3 migration). Listed **(a) items do not use a slot**. They are seen, not asked — the user confirms the batch at the same gate.
    - **5 to 8 (b) items are NOT an "overflow"**. They fit in up to 2 calls (4 plus the rest). Staging is required only **above 8**.
@@ -195,6 +229,10 @@ Apply the **Proposal discipline (shared)** above to each consolidated finding fr
 
 ## Phase 3 — Single gate (≈ Commit κ) — **always happens, never skippable**
 
+The single gate always opens, even for an (a)-only package. Each (b) item is its own `afm ask evolve` scope, never a monolithic approve. Exit: a recorded decision per item.
+
+### Phase 3 procedure
+
 `evolve` **requires a gate under every protocol**. It is a first-class exception alongside the bright lines ([`core/protocol.md`](../core/protocol.md) § 4), not the absence of a flag.
 
 The safety valve that makes "go" safe in `deliver` **does not exist here**. That valve halts on the first task that depends on an assumption. There is no execution phase in `evolve`. The doc edit *is* the effect. There is no future boundary where the human would catch drift. So the gate cannot be skipped.
@@ -214,6 +252,10 @@ Even a package with **only (a) items** opens the gate. The ceremony cost is the
 
 ## Phase 4 — Application + postconditions (≈ Commit κ applied)
 
+Apply the approved items through the suppression contract, then run the two mechanical postconditions: step 4.2 (parseable format) and step 4.3 (the instance/plugin boundary). A format break rolls the edit back and is reported. Any dirt in the plugin content root means rollback plus a CRITICAL report. Exit: applied edits with both postconditions green.
+
+### Phase 4 procedure
+
 1. **Apply** the (a) items and the approved (b) items, through the **suppression contract**:
    - A rule edit follows `rule.md`.
    - A gotcha follows `gotcha.md`.
@@ -245,6 +287,10 @@ Even a package with **only (a) items** opens the gate. The ceremony cost is the
 
 ## Phase 5 — Record + promote (auditable lineage)
 
+Write `docs/evolution/<date>-NNN.md` with `mechanism: evolve`, keep the rejected and reverted items, suggest `afm promote` for a finding that generalizes, and hand off to `reconcile`. Exit: the closed report.
+
+### Phase 5 procedure
+
 1. **Materialize or close** `<consumer>/docs/evolution/<date>-NNN.md` (`afm next-id evolution` prints the free NNN), with `afm new evolution-report --mechanism <...>` (fix findings with `afm lint --fix`). Include the φ findings (mechanical and behavioral), the buckets, and the audit records. Include the **rejected AND approved-then-reverted items** too — the attempt memory for future cycles. Include the before/after vital signs, and the date (`afm evolve gate-check` reads it for the cooldown). This is the Self-Harness h₀→h₁ lineage.
 2. **Does it generalize?** If a finding applies to any instance ("every pre-rc.5 instance has this drift"), **suggest** `afm promote`. Never skip its own gate (#7) — `evolve` only suggests.
 3. **Hand off to `reconcile`** to watch the effect of the changes in later sessions. This is AFM's possible form of "re-run". With no held-out set, real validation is observed future behavior.
@@ -301,17 +347,20 @@ Even a package with **only (a) items** opens the gate. The ceremony cost is the
 ## Anti-patterns
 
 - ❌ **Running by ritual or calendar** — it runs by signal. A cycle with no new signal gets a cooldown refusal (Autogenesis: an adaptive trigger beats a fixed budget).
-- ❌ **Reimplementing the scan or the reflection** — `evolve` composes `diagnose`/`reflect` through suppression. It does not duplicate their procedure.
 - ❌ **Treating an empty diagnosis as a failure** — a healthy instance means the cycle reports "100%" and stops. It never invents a problem to justify the invocation.
-- ❌ **Inventing the target for a non-restorable fix**. Examples: a dead reference with no proven rename, an ADR with no NNNN target, a trigger with no historical path. These go to the gate as options — archive, redirect, recreate. Never guess a path or ADR (#5).
 - ❌ **Classifying a trigger/hook-path edit as (a)** — it is always (b). This is the agent reducing its own oversight.
 - ❌ **Skipping the gate** — there is no "go" in `evolve`. Even a package with only (a) items opens the gate.
 - ❌ **A monolithic plan-approve** — the gate is item by item, one `afm ask evolve` scope per (b) item (the edits are independent).
-- ❌ **Downgrading a rule because it was violated** — a violation does not mean the rule is wrong. Downgrading needs proof the rule is *wrong* (a false positive, impossible to satisfy, or an intent proven obsolete by git). Consider "the agent was non-compliant" as the rival explanation first.
 - ❌ **Deleting** — archive it instead, with a tombstone. Deletion is a bright line and gets its own gate item. A superseded ADR, a dead gotcha, or an old marker stay institutional memory until the human says otherwise.
-- ❌ **Renumbering a rule** — a removed one becomes `*(removed — lives in §X)*`.
 - ❌ **Materializing after the gate what the gate did not see**. ADRs and edits must be itemized in Phase 3, or they do not happen.
 - ❌ **Editing the bundled content** — the Phase 4.3 boundary postcondition (two branches) catches this. Any dirt means rollback plus CRITICAL. A generalization is **recorded** through `promote`, never applied from here (#7).
-- ❌ **Re-proposing a rejected or reverted item with no new evidence**. Attempt memory, plus the per-surface flip-flop flag, catch this.
 - ❌ **Resolving `[TBD]` alone**. Age is a signal to ask if the stance still holds. It is not a reason to invent an answer (#4/#5).
+
+### Conditional anti-patterns
+
+- ❌ **Reimplementing the scan or the reflection** — `evolve` composes `diagnose`/`reflect` through suppression. It does not duplicate their procedure.
+- ❌ **Inventing the target for a non-restorable fix**. Examples: a dead reference with no proven rename, an ADR with no NNNN target, a trigger with no historical path. These go to the gate as options — archive, redirect, recreate. Never guess a path or ADR (#5).
+- ❌ **Downgrading a rule because it was violated** — a violation does not mean the rule is wrong. Downgrading needs proof the rule is *wrong* (a false positive, impossible to satisfy, or an intent proven obsolete by git). Consider "the agent was non-compliant" as the rival explanation first.
+- ❌ **Renumbering a rule** — a removed one becomes `*(removed — lives in §X)*`.
+- ❌ **Re-proposing a rejected or reverted item with no new evidence**. Attempt memory, plus the per-surface flip-flop flag, catch this.
 - ❌ **Composing `reflect.md` past § 2 in Phase 1.2**. Reading further would reach the § 5 escalation step and let `reflect` propose `afm evolve` from inside the very cycle running it. The recursion guard depends on Phase 1.2 stopping at §§ 1-2 — see `§ Suppression contract`.

package/content/ops/export-template.md

@@ -62,7 +62,7 @@ what to keep, the task-template induction and the final confirmation.
    the selection.
 5. **Induce a task template before `features/` goes (AWM, from a green trajectory).** Run this step only
    when the dry run lists `docs/features/`. Take the **most recent** `docs/features/NNN-*/tasks.md` with
-   **ALL tasks `- [X]`**: it passed its own test, and never induce from incomplete work. The dry run
+   **ALL tasks `done: true`** in its `tasks:` list, and never induce from incomplete work. The dry run
    names the feature, or says there is none, in which case skip the step. Turn concrete values into named
    variables (product, entity, procedure, domain become `{product-name}`, `{entity}`,
    `{boundary-procedure}`, `{domain}`), following `afm path templates/feature-tasks.induced.template`, and

package/content/ops/generalize.md

@@ -4,11 +4,10 @@ description: Merges several gotchas that repeat into one abstract rule.
 load: warm
 writes: ["docs/gotchas/*.md", "docs/rules/*.md", "docs/afm.md", "docs/evolution/*.md"]
 composes: []
+ancestors: the *MetaReflect* step of MetaReflection (arXiv 2405.13009).
 ---
 # Sub-flow: semantic consolidation of gotchas into an abstract rule (`generalize`)
 
-> **In this file:** What `generalize` is / is not · Pre-check · 1. Identify the batch (clustering, ≥2) · 2. MetaReflect: propose the abstract rule (follow the shared discipline) · 3. ShowsImprovement + backtracking (validation before the gate) · 4. Own gate (à la carte) — suppressed under `evolve` · 5. Registration + handoff · Suppression contract (back-pointer) · Anti-patterns
-
 > **Form** — effect: rule + tombstones · trigger: `afm generalize`, composition · precondition: ≥2 similar gotchas · composed by: `evolve` 1.3 · **degree of freedom: medium**
 
 Triggers: `afm generalize`. Also natural-language **consolidation** requests. Examples: "these gotchas are all the same thing", "merge these rules". Also: "this became a pattern — generalize it", "I have 3 gotchas that say the same thing".
@@ -17,8 +16,6 @@ Triggers: `afm generalize`. Also natural-language **consolidation** requests. Ex
 >
 > **Mechanism, not conductor.** `generalize` is the mechanism-skill that **merges a batch of similar gotchas/reflections into one abstract rule** (episodic memory → semantic memory). It runs **à la carte** (its own gate) OR inside the `evolve` cycle (which composes it when `diagnose` flags inflation from redundant gotchas, and its own gate is suppressed).
 >
-> **Ancestor:** the *MetaReflect* step of MetaReflection (arXiv 2405.13009).
->
 >     Generalize(gotchas, batch):
 >       1. read the current gotchas and the batch                     # |batch| >= 2
 >       2. emit one abstract rule that covers the batch — ADD it, and MERGE the batch into tombstones

package/content/ops/policy.md

@@ -7,8 +7,6 @@ composes: []
 ---
 # Sub-flow: report the organisation policy (`policy`)
 
-> **In this file:** What policy is / is not · Procedure · What it must never do · Invariants
-
 > **Form** — effect: a report in chat, no file written · trigger: `afm policy` · precondition: `.afm-version` · **degree of freedom: low**
 
 Triggers: `afm policy`. Also natural language about the organisation layer. Examples: "what does the

package/content/ops/reflect.md

@@ -1,14 +1,13 @@
 ---
 type: op
-description: Refines a doc that guided the agent wrong, using evidence from the session itself, and proposes the full cycle when that evidence outgrows one doc.
+description: Refines a doc that guided the agent wrong, using evidence from the live session and the project's sessions since the last cycle, and proposes the full cycle when that evidence outgrows one doc.
 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)
@@ -41,7 +38,7 @@ Triggers: `afm reflect`. Also natural language about a **doc that guided badly**
 
 Examples: an ambiguous rule applied wrong, a doc that misled, a section that did not guide. Also a contradiction lived in practice, or the user correcting the agent against the doc.
 
-The evidence is **the session's trajectory** — the agent stumbled. It is not the static artifact. It produces **(a)** proposals to make the doc **more assertive and clear**. This refines what already exists. It also produces **(b)** suggestions for the human in the loop.
+The evidence is **the trajectory of the live session plus the project's sessions since the last cycle** — the agent stumbled. It is not the static artifact. It produces **(a)** proposals to make the doc **more assertive and clear**. This refines what already exists. It also produces **(b)** suggestions for the human in the loop.
 
 **It is NOT:**
 - `reconcile` (code→docs, **additive**: the agent learns a new fact, then proposes a new gotcha or rule). `reflect` is **docs→docs refinement**: an existing doc guided badly, so it proposes making that doc assertive. *It never adds knowledge. It only improves the instructiveness of what is already there.*
@@ -56,7 +53,11 @@ The evidence is **the session's trajectory** — the agent stumbled. It is not t
 
 1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm init` or `afm refactor` first.
 2. **Does `afm preflight` exit 0?** A non-zero exit says why: the docs are not bootstrapped, the bundled content does not resolve, or the pin does not match. Report it to the user. Do not fall back silently.
-3. **Capture the events lived in this session.** The `reflect` trigger is in-session — see `interview/triggers.md`. Note which core docs the agent read or followed, and where they guided badly. With no lived event this session, and no clear symptom, stop: there is no reflection to do. Report "no doc friction observed in this session", then **record the outcome**: run `afm cadence close --arm reflect --reason "no doc friction observed"`. That writes the durable record that resets the cadence counter, so the same task and deliverable counts do not block the next Stop again. Then end. Reflection with no behavioral evidence is the agent inventing a disease. Rule #5 forbids this.
+3. **Capture the events lived in the evidence window: the live session plus the project's sessions since the last cycle.** The `reflect` trigger is in-session — see `interview/triggers.md` — but the evidence is wider. Run `afm sessions --since reflect --json` (it lists the project's sessions in every supported harness; `source` is `record`, `harness` or `both`) (pass the live session id with `--exclude <id>`) for the window, then `afm sessions signals --since reflect --json` for its deterministic signals: user turns, with a `correction` flag set by a fixed marker list, tool-error groups, AFM injection sizes and repeated reads. The signals are a heuristic that points at friction. You judge them. The command skips sessions whose record already names a `reflection:` (pass `--include-covered` to read them again), groups tool errors by tool and command, carries the repeated prompt rituals of the last 30 days under `repeatedPrompts` (`--repeat-window <N>d`; `--scope user` clusters them across every project of the user, listing the projects of each cluster), and gives every signal a `fingerprint` and a `status`: `new`, `resolved` (an evolution report listed its fingerprint in `resolves:`) or `regressed` (the signal recurs after that report, so the earlier fix did not hold).
+   - **Weight.** The live session is read directly, so one signal there is enough evidence. A signal from a past session counts only when it repeats across 2 or more sessions, is an explicit correction, or is `regressed`. A `resolved` signal is not a finding.
+   - **Order.** Take the `regressed` signals first: each one says an earlier fix did not hold, so revisit that report's change before proposing a new one.
+   - **Repeated prompts.** A `repeatedPrompt` signal is a first-class finding: the user types the same thing again and again. Propose the artifact that stops the retyping (a procedure, a preset in a skill, an op step, or a config default), citing the cluster sample and its sessions. A cluster that carries `suggests: procedure` (the `[runbook?]` marker in text mode) is a run of operational verbs, so propose it as an `afm new procedure` in the project where it repeats, with the steps in the order the user asks them.
+   - **Read-only bound.** Open a raw transcript only when a signal needs context, and read only the turns around its `ts`. Note which core docs the agent read or followed, and where they guided badly. With no lived event in the window, no signal, and no clear symptom, stop: there is no reflection to do. Report "no doc friction observed in the window", then **record the outcome**: run `afm cadence close --arm reflect --reason "no doc friction observed"`. That writes the durable record that resets the cadence counter, so the same task and deliverable counts do not block the next Stop again. Then end. Reflection with no behavioral evidence is the agent inventing a disease. Rule #5 forbids this.
 
    > **If the operator would rather skip the reflection**, run `afm cadence skip --session <id> --reason "<text>"` (the id is the one the Stop message gives; `--session` is required). It records the skip as debt in the state store and does not reset the counter. Never edit the session store by hand.
 
@@ -64,21 +65,21 @@ The evidence is **the session's trajectory** — the agent stumbled. It is not t
 
 ## 1. Behavioral evidence collection (≈ *Reflect* — traces → hypotheses)
 
-Core docs include `afm.md`, `ach.md`, `prd.md`, `ust.md`, the rules under `rules/`, the gotchas under `gotchas/`, and the rubrics. Find each point this session where a core doc guided badly. Record a **behavioral signature** for it: `φ_b = (symptom-lived, causal-status-of-the-doc, mechanism)`.
+Core docs include `afm.md`, `ach.md`, `prd.md`, `ust.md`, the rules under `rules/`, the gotchas under `gotchas/`, and the rubrics. Find each point in the window (the live session and the signals of the earlier sessions) where a core doc guided badly. Record a **behavioral signature** for it: `φ_b = (symptom-lived, causal-status-of-the-doc, mechanism)`.
 
 - *symptom-lived* — what happened, with an anchor. Example one: the agent applied rule N of `afm.md § 3` wrong, and had to re-read it twice. The user then corrected the agent against it, in `<file>`. Example two: the agent followed `ach.md § 3.1`, and the part it named no longer existed. Example three: two docs gave opposite guidance on the same task.
 - *causal-status-of-the-doc* — was **the doc** causally implicated? This slot is the *causal status*, not "who is to blame."
 - *mechanism* — **why** the doc produced the stumble. Options include an ambiguous rule that reads two ways, or a rule with no executable trigger. Such a rule fails a 0/1 check. Other options: an outdated example, guidance buried where nobody finds it, or a contradiction with another doc.
 
-**Golden rule:** every signature cites **the doc passage** (`file:section`). It also cites **the session event** — what the agent did, or what the user said. Without both sides, it is not evidence. It is only an impression.
+**Golden rule:** every signature cites **the doc passage** (`file:section`). It also cites **the session event** as `session:<id>@<ts>` — what the agent did, or what the user said. The id and the timestamp come from the live session or from a signal of `afm sessions signals`. Without both sides, it is not evidence. It is only an impression.
 
 ### 1.2 — The second sweep: what I corrected by hand more than once
 
-Beyond a doc that guided badly, `reflect` sweeps the session for **an error caught by non-mechanical review, and that came back**. Look for the same defect type fixed in two places. Or an ad-hoc `grep` run again, or a review repeated because no command did it for the agent.
+Beyond a doc that guided badly, `reflect` sweeps the window for **an error caught by non-mechanical review, and that came back**. Look for the same defect type fixed in two places. Or an ad-hoc `grep` run again, or a review repeated because no command did it for the agent.
 
-Each occurrence becomes a **guardrail candidate**: `(the defect, how many times this session, how the agent caught it by hand)`. The promotion gate is the rubric's, from `rubrics/failure-classification.md`. It needs 2 or more occurrences, or one explicit user correction.
+Each occurrence becomes a **guardrail candidate**: `(the defect, how many times in the window, how the agent caught it by hand)`. The promotion gate is the rubric's, from `rubrics/failure-classification.md`. It needs 2 or more occurrences, counted across the sessions of the window, or one explicit user correction.
 
-> **Why this lives in `reflect`, and not only in `remediate`.** `remediate` consumes the failure events of the state store (`afm failures promotable`). Those only record a failure recognized by a **terminal external signal** — a red test, a nonzero `tsc` result, a nonzero command result. An error the agent caught itself, while reading the diff, **never reaches those events**. It gets fixed before it becomes a signal. This is the most expensive class of error. Its cost is the agent's own context, invisible on the ledger. `reflect` is the only point in the cycle that sees it, because its evidence is the lived trajectory alone.
+> **Why this lives in `reflect`, and not only in `remediate`.** `remediate` consumes the failure events of the state store (`afm failures promotable`). Those only record a failure recognized by a **terminal external signal** — a red test, a nonzero `tsc` result, a nonzero command result. An error the agent caught itself, while reading the diff, **never reaches those events**. It gets fixed before it becomes a signal. This is the most expensive class of error. Its cost is the agent's own context, invisible on the ledger. `reflect` is the only point in the cycle that sees it, because its evidence is the lived trajectory alone, across the project's sessions of the window.
 
 Before proposing a candidate, run the same **surface discovery** as `ops/remediate.md` step 3.5. Check the linter, type-check, CI, and any git hooks the project already has. A candidate with no surface to land on stays an observation. It does not become a proposal.
 
@@ -110,8 +111,8 @@ For each addressable finding, follow the **shared proposal discipline** of the e
   - **Add the executable trigger** that was missing. A rule with no `*Verification:*` 0/1 gains a trigger, or moves down to § 1.3 as a principle (rule #3).
   - Disambiguate a contradiction, or itemize an ADR for it.
   - Move buried guidance, or point to it from a clearer spot.
-- **(c) Guardrail candidate** (from § 1.2) — the defect the agent corrected by hand 2 or more times this session. State the existing surface where the check would land and the estimated cost. This goes to the gate as an **installation proposal**. Installing writes outside `docs/`, so it is always bucket (b). It never auto-applies, and if approved, it materializes `docs/guardrails/<slug>.md` with `afm new guardrail`, with the mandatory `## What would refute this`. Then propose the config edit to the operator.
-- **(b) Suggestion for the human** — for friction a text edit cannot fix, but that is still a real signal. Examples: "rule N cost you 3 corrections this session. Worth rethinking the approach, not just the text." Or: "that old `[NEEDS CLARIFICATION:]` keeps blocking every session. Do you want to decide?" This goes to the report as a recommendation. It is not an edit.
+- **(c) Guardrail candidate** (from § 1.2) — the defect the agent corrected by hand 2 or more times in the window. State the existing surface where the check would land and the estimated cost. This goes to the gate as an **installation proposal**. Installing writes outside `docs/`, so it is always bucket (b). It never auto-applies, and if approved, it materializes `docs/guardrails/<slug>.md` with `afm new guardrail`, with the mandatory `## What would refute this`. Then propose the config edit to the operator.
+- **(b) Suggestion for the human** — for friction a text edit cannot fix, but that is still a real signal. Examples: "rule N cost you 3 corrections in the window. Worth rethinking the approach, not just the text." Or: "that old `[NEEDS CLARIFICATION:]` keeps blocking every session. Do you want to decide?" This goes to the report as a recommendation. It is not an edit.
 
 An edit can touch a `*Verification:*` command in `afm.md § 3`. Or it can touch a path the hooks parse, like a gotcha's `trigger_path` key. Either edit is **always bucket (b), load-bearing**. It never auto-applies, for the same reason as `evolve`: narrowing your own oversight carries more weight than convenience.
 
@@ -131,7 +132,7 @@ After approval, apply the change through the writing ops — `rule.md` or `gotch
 
 ## 5. Record + session closing + handoff
 
-1. **Materialize or append** the reflection bundle in `<consumer>/docs/evolution/<date>-NNN.md`. Create it with `afm new evolution-report --mechanism reflect` (fix findings with `afm lint --fix`). Include the φ_b signatures, and what got self-critiqued as "it was me" (anti-oscillation memory). Also include the refinements approved or rejected, and the suggestions for the human. À-la-carte, `reflect` generates or closes this report on its own. Under `evolve`, it feeds the cycle's report instead.
+1. **Materialize or append** the reflection bundle in `<consumer>/docs/evolution/<date>-NNN.md`. Create it with `afm new evolution-report --mechanism reflect` (fix findings with `afm lint --fix`). Include the φ_b signatures (each with its `session:<id>@<ts>` cite), list in `resolves:` the fingerprints of the signals this cycle handled (an applied or approved refinement; the next window reads it to tell `resolved` from `regressed`), and what got self-critiqued as "it was me" (anti-oscillation memory). Also include the refinements approved or rejected, and the suggestions for the human. À-la-carte, `reflect` generates or closes this report on its own. Under `evolve`, it feeds the cycle's report instead.
 
 > **The report name is `YYYY-MM-DD-NNN.md` and its frontmatter MUST carry `mechanism: reflect`.**
 > Three mechanisms write into `docs/evolution/`, and each one's cadence window is "since MY last
@@ -146,7 +147,7 @@ After approval, apply the change through the writing ops — `rule.md` or `gotch
    - **`## what was asked`** — the agent's own reading of the user's request, including where that reading changed mid-session. This is not a transcript. It is the interpretation that guided the work.
    - **`## how it was executed`** — how AFM was used: which ops ran, which rules fired, and where the harness helped. Also note where it got in the way. This is the data no other artifact has. Git records what changed, not how the agent used the method.
    - **`## afm_findings`** — what generalizes to the plugin, in the format of `ops/promote.md` step 4, with `evidence:`. An explicit empty result is a valid result.
-   - **`reflection:`** — the link to the `docs/evolution/<date>-NNN` file from step 1. This field replaces a `docs_findings` field. What `reflect` found **and fixed** in the local docs already lives there. Duplicating it would be the inflation `reflect` itself forbids.
+   - **`reflection:`** — the link to the `docs/evolution/<date>-NNN` file from step 1. Fill it for **every session record the window covered**, not only the live one, with `afm sessions mark <id…> --reflection docs/evolution/<file>.md` (never by editing the store; a covered record is skipped by the next `afm sessions signals`), so the next window starts after them. This field replaces a `docs_findings` field. What `reflect` found **and fixed** in the local docs already lives there. Duplicating it would be the inflation `reflect` itself forbids.
 
    **No session with real work means no record**, because the hook writes nothing. In that case, this step is a no-op. It is not a reason to create one. The handoff block (`state:`, `open_questions`, `next_steps`) stays episodic. `state: consumed` marks **the handoff** as read, not the record itself as dead. See `rubrics/episodic-vs-semantic-boundary.md` for this dual-tier rule.
 2. **Does it generalize?** If the friction fits any instance, record it through `afm promote`. For example, every instance might share the same ambiguous rule. Attach evidence. Never apply it directly (rule #7). The destination is the `afm_findings` field of the session record from step 1.5. It is the same place, not two.
@@ -167,7 +168,7 @@ There, the signal is the task's own test or `tsc` result. The "re-run" is litera
 
 ## Anti-patterns
 
-- ❌ **Reflecting with no lived event** — for example "this rule seems ambiguous" with no actual stumble this session. That is an impression, not evidence (rule #5). No friction observed: report "no friction", run `afm cadence close --arm reflect --reason "no doc friction observed"` and stop.
+- ❌ **Reflecting with no lived event** — for example "this rule seems ambiguous" with no actual stumble in the window. That is an impression, not evidence (rule #5). No friction observed: report "no friction" only when the whole window has no signal, then run `afm cadence close --arm reflect --reason "no doc friction observed"` and stop.
 - ❌ **Weakening a rule that embarrassed me**. A violated rule is not a wrong rule. The "it was me" hypothesis is mandatory, and it kills the refinement whenever the doc was clear.
 - ❌ **Adding new knowledge** — that is the job of `reconcile`, `gotcha`, or `rule`. `reflect` only refines the instructiveness of what already exists. Output (c) is not an exception. It converts repeated manual analysis into a check. It adds no new knowledge, because the knowledge was already in the manual correction.
 - ❌ **Proposing a guardrail from a single occurrence**. The same rubric gate applies here: 2 or more times, or one user correction. A gate born from a single case becomes a dead constraint (rule #5).
@@ -176,5 +177,6 @@ There, the signal is the task's own test or `tsc` result. The "re-run" is litera
 - ❌ **Editing the bundled content** — absolute boundary #7. Generalization gets **recorded** through `promote`. It never gets applied. See the boundary postcondition in `evolve.md § Phase 4.3`.
 - ❌ **Transcribing the session** in the session record — the transcript already exists, and `session_ref` (harness and id) points to it. The two timeline sections hold **interpretation** — what the agent understood, how it used AFM — not a log. Transcribing adds inflation and a reading cost.
 - ❌ **Pasting a credential into the narrative**. Quoting the command run is the common leak path. Write the command with the secret redacted. Hard rule 13 covers it.
+- ❌ **Reading a raw transcript when the signals suffice**, or **quoting text that did not pass the redaction**. `afm sessions signals` already extracts and redacts what the cycle needs. A raw read costs context and risks a secret. Quote only signal text. If a signal is not enough, say so in the report instead of opening the transcript.
 - ❌ **Confusing this with `diagnose`** — `reflect` does not run the static 7-axis scan. Its evidence is behavioral. For the mechanical sweep of the instance, use `afm diagnose` instead.
 - ❌ **Reaching § 5 step 3 while running under `evolve`** — the recursion guard. `evolve` Phase 1.2 composes only `reflect.md §§ 1-2`. The escalation step is scoped out of that composition on purpose. Escalating from inside the cycle that is already running `reflect` would be `reflect` calling back into its own caller.

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
@@ -43,7 +40,7 @@ Triggers: `afm restructure`, or natural language about **structure/staleness** (
 1. **Staleness** — a doc references code that changed. The doc was not updated.
 2. **Findability** — guidance exists but sits in the wrong layer or place. Retrieval failed even though the content was present.
 3. **Partition by temperature** — what is always-read vs. deep on-demand reference. This is an opt-in loading-strategy proposal.
-4. **Dead-gotcha pruning** — a gotcha whose last-bite date is old and whose count has stopped. A dry incidence is a tombstone candidate.
+4. **Dead-gotcha pruning** — a gotcha whose last-bite date is old and whose count has stopped. A dry incidence is a tombstone candidate. The `fade` axis of `afm doctor` generalizes this: a cold orphan doc with no inject, read or edit in the window and no recent bite is a tombstone candidate too.
 
 **It is not:**
 - `diagnose` axis A1 (**dead reference** = the path does not exist). `restructure` staleness means the path **still exists but changed** while the doc did not. The two do not overlap.
@@ -97,7 +94,7 @@ Apply this only when a doc has **actually grown too large** (a `diagnose` A6 sig
 
 - Propose a **loading strategy** mark. *Hot-always* content is needed every turn — conventions, commands, § 3 rules. *On-demand* content is deep subsystem reference. It becomes an appendix, read only when needed. The paper's split is hot / per-task / on-demand.
 - The change is **an ADR proposal** (a doc architecture decision), **not** an automatic cut. Moving content to an on-demand appendix keeps 100% of the content (only re-partitions it) and follows the minimal-change discipline.
-- **Opt-in:** without a real inflated doc, **do not propose** tiering. Small docs do not need it (YAGNI), and forced tiering is ceremony. This is the only `restructure` axis that can have zero findings in a healthy instance.
+- **Opt-in:** without a real inflated doc, **do not propose** tiering. Small docs do not need it (YAGNI), and forced tiering is ceremony. This is the only `restructure` axis that can have zero findings in a healthy instance. The evidence for a tier change is the `tier-drift` axis of `afm doctor` (a cold doc used often, an idle hot or warm doc, an on-demand section read in most runs of its op). It stays a proposal at the gate: nothing changes `load:` on its own.
 
 ---
 

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,9 +159,36 @@ 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.
+   comments, the test names. Each file gets a rewrite of its language and writing style. Then an
+   adversarial check asks what fact, number, path, marker or caveat disappeared. The checker reports; it
+   never rewrites.
+
+   **Run the fan-out as one orchestrated batch, never file by file in the main session.** A file-by-file
+   rewrite in the session context spends the capable model on mechanical volume and fills the context
+   with text it reads once. Use the orchestration primitive of the harness: a workflow script (an
+   ultracode run, where the harness has one) or, failing that, its batch of parallel subagents. Build
+   the file list from step 3 BEFORE the batch starts, and pass it to the batch as data. A file the list does not name is never touched.
+
+   **The model tier follows the task tier** (`afm.md` § 1, the fan-out principle). Translation and
+   style rewrite under a fixed contract is mechanical, high-volume work:
+   - **Rewrite: the light tier** (a Haiku-class model, Haiku 5.5 today). Set the model on each
+     agent call, never once for the whole run. Give each agent a chunk of files, not one file, so the
+     concurrency stays inside `MAX_PARALLEL_SUBAGENTS`.
+   - **Check: the light tier too.** Its contract is a comparison, not a judgment: list the facts,
+     numbers, paths, markers (`[TBD]`, `[NEEDS CLARIFICATION:]`), code spans and caveats of the original,
+     and report each one the rewrite lost. Escalate ONLY a file the check flags to a capable model, for
+     one more rewrite of that file.
+   - **The orchestrator keeps the judgment**: the excluded scope, the final gate and the report to the
+     operator. Those stay on the session model.
+
+   Each rewrite brief carries the same contract: translate the prose, keep every code span, path,
+   identifier, frontmatter key and marker byte for byte, keep the headings structure, and never shorten
+   (hard rule 17). After the batch, `afm lang` reports the language of each file: a file still in the
+   old language goes back into the batch once, then to the operator.
 6. **Never touch the excluded scope.** Not the UI strings, not the user-facing error messages, not the
    email copy, not the seed data a user reads. An ambiguous file stays.
 

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.