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

package/content/ops/remediate.md

@@ -0,0 +1,143 @@
+---
+type: op
+description: Turns a failure that repeats into a durable artifact, recognized by an external signal.
+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
+
+> **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`.
+It also triggers on natural language that asks to **resolve a failure for good**.
+Example phrases:
+
+- "this failed again, let's fix it for real"
+- "make a runbook for this"
+- "record this lesson for the next agents"
+- "why do I keep getting this wrong?"
+
+> **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.
+
+---
+
+## What `remediate` is / is not
+
+**Is:** the loop **recognize → understand/classify → remediate** over the failures the failure-capture hook recorded in the state store (`afm failures promotable` lists the signatures that recurred).
+It reads the failures that are still open: not closed by a record or by `afm failures close`.
+It classifies each one using [`../rubrics/failure-classification.md`](../rubrics/failure-classification.md).
+Then it **proposes** the correct durable artifact: **guardrail** (mechanizable — takes precedence), **procedure** (mechanical), or **learning** (conceptual).
+Gate #5 and the negative filters control this step.
+
+**Is not:**
+- A new failure **detector**. The `afm.md § 5.1` terminal recognizes failures (external signal). `remediate` consumes what was already recorded.
+- The short in-task loop (`§ 5.1`). That loop retries GREEN right away (ephemeral). `remediate` runs cross-turn and cross-session (durable).
+- A plugin editor (#7) or an auto-applier (#6 — it proposes, the human approves).
+
+---
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop and suggest `afm init` or `afm refactor`.
+2. **Is there an open failure?** Run **`afm failures promotable`**. It lists each `sig=` that recurred (twice or more) with its `count`, `first` and `last` date, minus those already closed. With `no failure is promotable`, and with no explicit user correction to record, report "nothing to remediate" and stop.
+   An empty result is a valid outcome — do not invent a failure.
+
+---
+
+## Procedure
+
+1. **Recognize (already done — consume the record)**.
+   Each failure is an event in the state store (`~/.afm/state/<project>/`, never the repository), keyed by `sig=<signature>` (the recurrence key).
+   The failure-capture hook writes it, or the `§ 5.1` terminal does, or the agent does when it records an explicit user correction.
+   The record carries an **external signal** (oracle plus command plus output) and a `task/feature`.
+   A failure with no external signal does not exist (CRITIC).
+   Do not invent one.
+
+2. **Promotion gate (#5 + negative-filters)**. For each `open` failure, decide whether it becomes an artifact now:
+   - **Explicit user correction → promote at count 1** (the user is the oracle).
+   - **Mechanical → requires recurrence:** the `sig=` must appear in `afm failures promotable` (its `count` is 2 or more).
+   - **Transient → do not promote:** the § 5.1 retry resolved it, or no durable antidote exists.
+     Also reject a claim that dies once you fix the root cause — "tool X was broken" is a fossil.
+     Close it with `afm failures close --sig <sig> --as transient` and move on. A closed signature stops counting: only failures after the close are counted again.
+     This is the negative filter — Phase 4 formalizes the checklist.
+   - A failure that does not clear the gate stays open (waits for recurrence). It becomes nothing yet.
+
+3. **Classify (executable discriminator)** by applying the `failure-classification.md` rubric to failures that passed the gate.
+   The first question is the **precedence** question: *can a 0/1 check detect this with no judgment call*?
+   If yes, the target is **guardrail**.
+   A document that relies on memory loses to a gate that fires on its own.
+   If no, choose between two targets: **procedure** is a repeatable sequence with 0/1 gates and a start trigger.
+   **Learning** is a conceptual lesson, valuable for its cause.
+
+3.5. **Read the mechanical surface the project already has**.
+   Do this before you propose a guardrail, never before.
+   That way you do not pay for the read when nobody needs it.
+   Find out what **already runs** in this repo:
+
+   - linter config (`eslint*`, `biome*`, `ruff*`, `.golangci*`, or the stack's equivalent).
+   - type-check (`tsconfig.json`, `mypy.ini`, `go vet`).
+   - CI (`.github/workflows/*`, `.gitlab-ci.yml`).
+   - git hooks (`.husky/`, `.git/hooks/`, `lefthook*`, `pre-commit`).
+   - verification scripts already versioned (`test/`, `scripts/`, `Makefile`, `package.json` scripts).
+
+   The proposal **extends what exists**. A new tool is a **last resort**.
+   State it explicitly, with its cost declared.
+   A gate that needs one more tool often costs more than the error it catches.
+   If nothing mechanical exists in the project, that gap is the finding.
+   Propose the minimal surface, not the complete one.
+
+   > **Context economy is the point.** The failure that triggered the guardrail used to be caught by non-mechanical analysis — reading, ad-hoc `grep`, review. That costs context **every time the code is touched**. A check costs once. This is the economic case for the precedence target, and it applies to both the human and the agent.
+
+   > **Red on the old code.** Before you accept any assertion that guards the fix (a guardrail check, a regression test), run it against the old code: `git show HEAD:<file>` or the parent commit. It MUST fail there. A regression test that passes on the old code proves nothing. If it passes, the assertion does not catch the failure: rewrite it before you propose it.
+
+4. **Propose the artifact (a delta, never a rewrite — rule 17)**.
+   - **Guardrail** → new `docs/guardrails/<slug>.md`, written by `afm new guardrail <slug> --origin recurring-failure --surface <surface> --cost <low|medium|high> --description "..."` (the generator fills the frontmatter from the template; fix findings with `afm lint --fix`).
+     The `origin` key cites the `sig=`, and the `## What would refute this` section is **mandatory**.
+     Installing the check (editing the linter config, the CI workflow, or a git hook) writes outside `docs/`.
+     Because of that, the agent **proposes it to the operator**.
+     It offers surface options — linter, CI, git hook, or free text — and never applies the check itself.
+     Until the operator installs it, the `installed_on` key stays `[TBD]`.
+   - **Procedure** → new `docs/procedures/<slug>.md`, written by `afm new procedure <slug> --fires-on <event|file-shape> --description "..."`.
+     The `origin` key cites the `sig=` value(s) for traceability (**hard rule 19**).
+     The folder appears on demand, mirroring `adr/`.
+   - **Learning** → new `docs/learnings/<slug>.md`, written by `afm new learning <slug> --fires-on file-shape --trigger-path "<glob>" --description "..."`. The `trigger_path` key uses a path (for injection through the pre-edit hook). The `origin` key cites the `sig=`.
+   - Before creating, **`grep` for an equivalent** (retrieval-before-create). If a guardrail, procedure, or learning already covers this `sig=`, **update it** (append or update-in-place) instead of duplicating it. If 2 or more learnings converge, suggest `afm generalize`.
+
+   **Gate (à la carte).** Show the evidence (the `sig=`, the count, the oracle output) and the proposed delta, then run `afm ask remediate --scope <sig>`. The `artifact` question confirms the target with the classification as the recommendation (`guardrail`, `procedure`, `learning`, or `not now`). For a guardrail, the `surface` question asks where the check is installed (linter, CI, git hook, or free text). The scope is the `sig=` turned into a slug (lowercase words joined by `-`, starting with a letter), so each failure keeps its own answers.
+
+5. **Close the failure**.
+   Once the agent proposes the artifact and the user approves it, close the signature: `afm failures close --sig <sig> --as remediated --detail "<path of the artifact>"`.
+   Do **not** delete the failure (provenance — append-only, rule 18). The close is itself one more event, so the history stays.
+
+6. **Report the outcome**.
+   List which failures became a guardrail (and on which surface), which became a procedure, and which became a learning.
+   List which failures stayed open or were closed as `transient`, and why.
+
+---
+
+## Composition (suppression contract)
+
+| Who uses it | Reuses | Suppresses |
+| --- | --- | --- |
+| `reconcile` (passive) | reads `afm failures promotable` at end of turn and **proposes** the remediation | nothing — reconcile already proposes-not-applies (#6) |
+| `evolve` (cycle) | the failure events are **evidence** for `reflect` (a lived failure) → **final** remediation happens at the cycle's gate | `remediate`'s own gate (folds into the single gate) |
+
+À-la-carte (`afm remediate`) has its own gate: one `afm ask remediate` question per artifact proposed (`questions/remediate.questions.yaml`). Under `reconcile` or `evolve`, approval moves up to their flow.
+
+---
+
+## Anti-patterns
+
+- ❌ **Recognizing a failure with no external signal** (self-judgment) — CRITIC: this degrades quality (#3).
+- ❌ **Promoting a single mechanical failure**, or a **transient** one — only 2+ occurrences (or 1 user correction) qualify. Transient failures never qualify (negative filter).
+- ❌ **Writing a procedure or learning that omits the `sig=`** — this violates rule 19's traceability requirement.
+- ❌ **Deleting the failure when remediating it** — close it with `afm failures close --as remediated`, never delete it (provenance).
+- ❌ **Auto-applying the fix** — `remediate` proposes, the human approves (#6).
+- ❌ **Forcing everything into one target** — guardrail, procedure, and learning are distinct (see the rubric).
+- ❌ **Writing a procedure or learning for what a check can catch** — the mechanizable target takes precedence. A document that relies on memory loses to a gate that fires on its own.
+- ❌ **Proposing a guardrail without reading the existing surface** (step 3.5). A new tool by default is the fastest way for the operator to turn the mechanism off.
+- ❌ **Installing the check alone** — installing writes outside `docs/`. The agent must propose it instead (#6).

package/content/ops/restructure.md

@@ -0,0 +1,142 @@
+---
+type: op
+description: Checks the health of the context architecture and finds what went stale.
+load: warm
+writes: ["docs/evolution/*.md"]
+composes: []
+ancestors: Codified-Context (arXiv 2602.20478).
+---
+# Sub-flow: context architecture health (`restructure`)
+
+
+> **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**
+
+Triggers: `afm restructure`, or natural language about **structure/staleness** ("the doc is out of date vs. the code", "this should load only on demand", "reorganize what is always-read vs. on-demand", "I cannot find the guidance in the doc, but it exists").
+
+> **Target = this project's local docs (`<consumer>/docs/`), never the plugin.** `restructure` updates, relocates, or re-partitions **only** the docs materialized in this repo. It never touches the canonical framework (the bundled content, bright line #7). A loading strategy that fits any instance is only **recorded** through `afm promote` (a finding with evidence). See [`evolve.md § The target of evolution`](./evolve.md).
+>
+> **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).
+>
+>     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
+>       3. Staleness(doc, path) := doc cites `path` AND path's last commit postdates doc's last commit
+>                                   AND doc stayed unchanged for more than N commits                # PRINCIPLES.md #3
+>       4. NullRetrieval(query) := an answer to query exists in the docs, but retrieval missed it
+>       5. Gate := opens only after GitEvidence and self-verify confirm the finding                 # PRINCIPLES.md #6, #8
+>       6. if NullRetrieval -> create or relocate a doc
+>
+> A doc versions its content by memory temperature. Two documented cases show a stale spec
+> misleading the agent — the paper's only confirmed failure mode. See [`../PRINCIPLES.md`](../PRINCIPLES.md).
+
+> **Maturity (honest YAGNI).** The paper's full tiering (108k lines of code, 3 tiers, a retrieval MCP) is **future** robustness — an AFM consumer's docs are small today. The **actionable core now** is **staleness** (git trigger) plus **findability/partition** (information exists but sits in the wrong layer). **Tiering by temperature** (marking hot-always vs. on-demand) enters only as an **opt-in ADR proposal**, never as enforcement — only when a doc has actually grown too large.
+
+---
+
+## What `restructure` is / is not
+
+**It is:** the check of the instance's **context architecture**. It covers four items.
+
+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. 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.
+- `reconcile` "missing doc": if information is **genuinely absent** (never documented) → that is `reconcile`/`gotcha`/`rule` (adds new knowledge). `restructure` targets information that **exists but was not found** because it sits in the wrong place (relocation, not creation).
+- `reflect` (a doc misled because it was **ambiguous**). `restructure` targets **location/freshness**, not writing clarity.
+- `generalize` (merges gotchas). `restructure` reorganizes/updates. It does not consolidate content.
+- A content rewriter. `restructure` moves, updates, and re-partitions. Missing product **content** becomes `[TBD]` (#4) or goes to `reconcile` — it is never invented (#5).
+
+---
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop and suggest `afm init` or `afm refactor`.
+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. Do not fall back silently.
+3. **Is git available?** The staleness scan depends on the git history. Without git, `afm doctor` reports the staleness axis as "not covered: no git" (never omit it). Findability and partition still run.
+
+---
+
+## 1. Staleness scan (git trigger — the paper's confirmed failure mode)
+
+**`afm doctor --json` runs this scan** and returns each candidate as a finding with axis `staleness` (command, `file:line` and the path's commits as evidence). Read those findings; do not redo the scan by hand. What it checks, for each core doc that **references code** (`ach.md § 3.1` component-to-file map, gotchas with a path, ADRs with a path):
+
+- Extract the paths cited (in backticks). For each path, find the **date of the last commit that touched it** (`git log -1 --format=%cd -- <path>`). Compare it with the **date of the last commit that touched the doc** (`git log -1 --format=%cd -- <doc>`).
+- **Path changed after the doc** (code evolved, doc stayed still) → **staleness candidate**. Report the doc's `file:line` and the path's commit range. Default threshold: the path changed in at least 1 commit after the doc. The doc must also have gone untouched for more than N commits (default 20, override with `<!-- evolve: stale-commits=N -->` in `docs/.afm-version`).
+
+> Staleness is a **signal**, not a verdict. The doc may still be correct while the code change is unrelated to the documented part. The finding goes to the gate as "this doc may be out of date vs. `<path>` (it changed in N commits since the doc's last update) — review it?" It never rewrites the doc on its own. The correct content requires reading the current code, so it becomes a proposal, not an auto-fix.
+
+### 1.1 Dead-gotcha pruning (last-bite — incidence, not avoidance)
+
+This applies the same staleness logic to a gotcha's **usefulness**. It uses a **falsifiable** signal: the frontmatter `bites` and `last_bite` fields (from `templates/gotcha.template.md`, filled in by `ops/gotcha.md`). `afm doctor --json` checks it for each gotcha in `gotchas/` and reports the candidates with axis `dead-gotcha`.
+
+- **Old last bite** (`last_bite` more than N months ago — a conservative default of 12, override with `<!-- evolve: stale-gotcha-months=N -->`; the `bites` line must also be unmoved in git, and a line whose age is unknown counts as unmoved) **and** `N` unchanged since then → **prune candidate**. It goes to the gate as "this gotcha may be dead (last bite `<date>`, count `N` unchanged) — archive it?"
+- Apply the approval as a **tombstone**: comment out the block, do not delete it. This preserves history and *adds* lines, so it does **not** trigger hard rule 17 (the same pattern as `generalize`). Never hard-delete.
+
+> **Why incidence, not avoidance:** the signal is "how many times the gotcha **bit**" (observable in git or in the session), never "how many times it **avoided** an error." Avoidance is counterfactual, unfalsifiable, and *reward-hackable* (the agent could freely self-report avoidance — exactly what the STOP guard in `PRINCIPLES.md` #3 forbids). Pruning by dry incidence is what the Reflexion paper approximates without violating that hardening.
+
+---
+
+## 2. Findability (information exists but is misplaced)
+
+**Behavioral plus structural** signal: during the session, the agent looked for guidance in `ach.md` or `gotchas/`/rubrics and **did not find it**. The information **does exist** in another doc or section, proven by a grep that finds it outside the expected place. This is the paper's "null-retrieval" seen from the **structure** angle, not the absence angle:
+
+- If the information **exists but sits buried or in the wrong doc** → propose a fix. Relocate it, or add a pointer to it. Move it to the expected section, or add the pointer there. Cite both places (`where I looked` vs. `where it was`).
+- If the information **does not exist anywhere** → **this is not `restructure`**. Route it to `reconcile` (adding new knowledge is `gotcha`/`rule`/a new section). `restructure` does not create missing knowledge (#5).
+
+---
+
+## 3. Partition by temperature (opt-in loading-strategy proposal)
+
+Apply this only when a doc has **actually grown too large** (a `diagnose` A6 signal: inflation). Part of it must also be **deep reference rarely needed**.
+
+- 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. 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.
+
+---
+
+## 4. Own gate (a-la-carte) + application — suppressed under `evolve`
+
+Follow the **shared proposal discipline** in `evolve.md § Proposal discipline (shared)`. Read it and follow it. Do not duplicate it — the numbered procedure lives only there.
+
+The findings carry **weight**. Staleness changes what the agent believes. Relocation changes where information lives. Tiering is an architecture decision. For this reason, the findings need an item-by-item, earned gate through `afm ask restructure` (`questions/restructure.questions.yaml`, one `--scope <item-slug>` per finding).
+
+A-la-carte opens its own gate with that command. Under `evolve`, the process suppresses it.
+
+On approval, apply the change. Update the stale doc after reading the current code. Relocate the information, and materialize the loading-strategy ADR if approved. Use the write ops where applicable (`afm adr new <slug>` for the loading-strategy ADR), and suppress their `afm ask`.
+
+**Post-condition:** `afm doctor --json`, `afm index --check` and `afm detect --for <file>` over the touched docs must preserve the format the hooks parse. If it does not, report a rollback. The two-branch check in [`evolve.md § Phase 4.3`](./evolve.md#phase-4--application--postconditions--commit-κ-applied) must also report a green boundary.
+
+---
+
+## 5. Record + handoff
+
+1. **Materialize or append** to `docs/evolution/<date>-NNN.md` (create it with `afm new evolution-report --mechanism <...>`; fix findings with `afm lint --fix`): the staleness candidates (with git evidence), the relocations, and the tiering decision.
+2. **Does it generalize?** If the loading strategy fits any instance, **record** it through `afm promote`. Give it a finding with evidence. Never apply it directly (#7).
+3. **Hand off to `reconcile`** to watch whether the relocated or updated doc gets found in later sessions.
+
+> **The report name is `YYYY-MM-DD-NNN.md` and its frontmatter MUST carry `mechanism: restructure`.**
+> Three mechanisms write into `docs/evolution/`, and each one's cadence window is "since MY last
+> report". A report with no `mechanism:` is invisible to every window, and an ordinal-first name
+> makes the selector order by ordinal before date. Both were live defects until 3.13.0.
+
+---
+
+## Suppression contract (back-pointer)
+
+`restructure` **reuses** the proposal discipline, the bucket partition, and the post-conditions from `evolve.md`. Read and follow them. It also reuses the write ops: `adr.md` for the loading strategy, and it suppresses that op's `afm ask`. Under `evolve`, the process suppresses the § 4 gate. The authoritative table is in `evolve.md § Suppression contract`.
+
+---
+
+## Anti-patterns
+
+- ❌ **Staleness without git evidence** — "it looks out of date" is not a finding. `git log` on the path vs. the doc is one (#5).
+- ❌ **Rewriting the stale doc alone** — staleness is a signal. The correct content requires reading the current code, so it goes up as a proposal, not an auto-fix.
+- ❌ **Creating missing knowledge** — information that does not exist anywhere belongs to `reconcile`/`gotcha`, not `restructure`. `restructure` only relocates what already exists (#5).
+- ❌ **Forcing tiering on a small doc** — partition by temperature is opt-in. Use it only when the doc has actually grown too large (YAGNI). Small docs do not need it.
+- ❌ **Hard-deleting a gotcha or pruning by avoidance** — gotcha pruning is a **signal**. The signal is an old last bite plus an unchanged `N`. Send it to the gate. Apply it as a **tombstone** (rule 17), never an auto-delete. The signal must be observable incidence, never a self-reported "avoided N errors" claim. That claim is unfalsifiable and conflicts with STOP/#3.
+- ❌ **Cutting content while re-partitioning** — moving content to an on-demand appendix keeps 100% of it. That is re-partition, not pruning. Pruning is a `diagnose`/A6 decision that goes to the gate.
+- ❌ **Editing the bundled content** — **record** a loading strategy for the plugin through `promote`. Never apply it directly (absolute boundary #7). The boundary post-condition is in `evolve.md § Phase 4.3`.

package/content/ops/rule.md

@@ -0,0 +1,170 @@
+---
+type: op
+description: Creates a hard rule, and refuses one that has no mechanical trigger.
+load: warm
+writes: ["docs/rules/*.md", "docs/afm.md", "docs/tools/gate/rules/*.sh", "docs/tools/gate/rules/*.ts", "docs/guardrails/*.md"]
+composes: []
+---
+# Sub-flow: new hard rule
+
+> **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").
+
+The CLI owns the mechanics: the next number, the rule file, the `N. **title** — [link]` index line in
+`afm.md § 3` (a parsing contract two hooks read), the gate runner and the index. This op owns the
+judgment the CLI cannot make: is the trigger honest, is the constant the operator's, where does it run.
+
+## Procedure
+
+1. `afm preflight`. Exit 3: no instance, run `afm init` or `afm refactor` first. Read `afm.md § 3`
+   (format and numbering) and `afm path interview/triggers` § "hard rule".
+2. **Confirm an executable trigger** the agent can run, for example `grep`, `wc -l`, `git diff` or
+   `tsc`, each returning 0 or 1. Ask for it as free text: the trigger needs description, not closed
+   options. "Code review", "PR template" and "manual review" do **not** count, because they describe a
+   human process no agent session has. `afm rule new` refuses them.
+
+   No executable trigger means the item is a **principle**, not a hard rule. Put it in `afm.md § 1.3`
+   instead (invariant principle #3 in `afm path PRINCIPLES`). **Insist hard here:** a rule nobody can
+   run is a rule nobody applies.
+   - **Anti-Goodhart guard (arXiv:2310.02304):** does the trigger measure the thing that matters, or a
+     proxy that is easy to satisfy? Test it before you accept it: can a diff pass the trigger while it
+     breaks the rule's intent? If yes, the trigger is reward-hackable. **Rewrite** it to target what
+     matters, or **downgrade** it to a principle. A `grep "test"` passes with an empty test, because
+     it counts a string and not coverage. A line count under 300 passes with one giant line. A
+     gameable trigger is worse than an honest principle.
+3. **Check whether the trigger already exists as a versioned script**: a `test/*.sh` file, a package
+   script or a project hook may already do the check. If so, the rule cites the script, not the full
+   command. Two sources of truth for the same check drift apart: the one the human reads stops being
+   the one that runs. Also check the catalog under `afm path guardrails/README`: an entry whose
+   `sinal` matches this project has a trigger better tested than one improvised now.
+4. **The rule's constant belongs to the operator, not to you**: a numeric limit, a name prefix, a
+   directory list. **Measure the repo, and propose the value with the measurement** ("your file p90
+   is 240 lines, I propose 300"). Never set a "best practice" value yourself. An unanswered question
+   becomes `[TBD]`, and the rule stays without a trigger until someone fills it in (#4). An invented
+   number creates a rule the owner disables at the first friction, because he never chose it.
+5. **Choose the surface before you write the rule.** A 0/1 trigger that stays only as prose works only
+   while someone remembers to run it, and the agent forgets exactly when context gets tight. Ask
+   `afm ask rule` (questions in `content/questions/rule.questions.yaml`). The recommendation follows
+   what the project already runs (#2): `pre-commit` unless there is a reason against it.
+   - `pre-commit`: blocks every commit, including one made outside an agent session.
+   - `ci`: blocks the merge, not the local commit. Only if the project already has CI.
+   - `agent`: stays in the doc, run by judgment. Honest for a heuristic trigger that could reject
+     correct work. **Not** honest for a precise trigger nobody automated.
+6. **Write the rule**: `afm rule new <slug> --trigger '<command returning 0 or 1>' --title "<title>" --statement "<one sentence>" --surface <pre-commit|ci|agent> [--runner ts|sh] [--does-not-cover '<text>']`. The command writes
+   `docs/rules/NN-<slug>.md` (frontmatter `type: rule`, `description`, `load: warm`, `rule_number`),
+   the `*Verification (<surface>):*` line, the index line in `afm.md § 3`, and, for `pre-commit` and
+   `ci`, a runner skeleton. `NN` in the file name IS the identity and never renumbers. A rule written
+   only as a file never reaches a session, and one written only as an index line has no body: the
+   command writes both. It prints each path and refreshes the index.
+   When the Verification command is narrower than the statement, the statement names that scope, or the
+   two are made to match. State what the gate does not check with `--does-not-cover "<text>"` (for
+   example "checks that a frontmatter exists, not the per-type schema"), so a green result is not read
+   as more than it proves. Never write boilerplate such as "edge cases". The option is optional.
+7. **Report the paths** (invariant principle #6, autonomy-first). The operator reviews with `git diff`.
+   For `pre-commit` and `ci` continue with the next section.
+
+## Install the gate
+
+> Canonical procedure for "hard rule → executed guardrail". Composed of this op (step 5) and of
+> `afm remediate` when the recurring failure is mechanizable. **Do not duplicate these steps in
+> another file** (rule 34): point to this one.
+
+0. **The aggregator is the CLI.** `afm gate` is the aggregator, the libraries, the ratchet reader and
+   the hook body. Do not write an aggregator or copy one from another project. You write the runner
+   body only. A project that maintains the plugin keeps its gate under `./test/`, and `afm gate`
+   resolves that fork itself. A project whose gate directory is missing is behind the plugin: it runs
+   `afm update`.
+1. **Find the surface the project ALREADY has** (#2, mandatory before any proposal): linter config,
+   type-check, CI steps, git hooks, the test script. The proposal **extends what already runs**. A new
+   tool is a last resort, stated explicitly with its cost. A guardrail that needs a new tool to catch
+   one error usually costs more than the error.
+2. **Pick the runner form: TypeScript is the default.** `afm rule new` writes
+   `docs/tools/gate/rules/NN-<slug>.ts`, a skeleton that throws (exit 2, never a pass) until you write the rule:
+   `({ rule }) => rule("NN").in(glob).except(glob).skipping(re).forbid(re, message)` (or `.require(re, message)`).
+   It needs no shell and no execute bit, runs on Windows, and `afm gate` runs it in a child process
+   (`afm gate ts-runner`) under the same exit contract. Check it with `afm gate --dry-run --only NN`. Full API:
+   `docs/tools/gate/rules/README.md`. Logic the builder cannot say (a diff, a count against the ratchet, another
+   tool) needs a bash runner: pass `--runner sh` to `afm rule new` in step 6 and the rest of this step applies to it.
+   Finish the runner that `afm rule new` generated. Its template (both forms) is
+   `afm path templates/guardrail-runner.template.md`. Decide the **class** there. A *diff* rule measures the index
+   with a zero budget. A *count* rule measures the whole repo against the ratchet. Swapping the two is
+   a silent false negative. Exit 0 compliant, 1 violated (one `NN<TAB>path:line<TAB>message` line),
+   2 could not decide. Exit 2 is mandatory: "could not verify" must never become "failed".
+   The generated runner takes each line the trigger PRINTS as a violation (a grep with no match exits 1
+   and passes), so the trigger prints its violations: `grep -rn`, never `grep -q` or a bare `test`.
+3. **Measure HEAD before you turn the gate on**: `afm gate --baseline`. It runs every runner that has
+   no ratchet row, records what it measures as declared debt, and says which rules it skipped. **A gate
+   that starts red gets disabled the next day**, and it takes every other rule in the aggregator with
+   it. The mode only ever appends: it never touches a rule somebody already decided about.
+4. **Measure the cost** and record it. A runner above the operator's budget drops to the `agent`
+   surface. The whole gate does **not** become optional because one runner is expensive.
+5. **Doc-to-runner sync is mechanical:** `afm gate --audit` cross-references the rule and the runner in
+   both directions. A rule with a gate surface and no runner is a **phantom gate**, worse than no gate
+   because it buys trust it cannot back up. A runner with no rule is an orphan.
+6. **Record the guardrail** with `afm new guardrail <slug> --origin hard-rule --surface <surface> --cost <low|medium|high> --description "..."`
+   (never by hand from the template). Use the `surface` chosen and the `cost` measured in step 4, then fill the
+   mandatory `## What would refute this` section. Fix any finding with `afm lint --fix`.
+7. **Activate it: find the manager the project already uses, and propose that one.** Never ask the
+   operator to edit git config by hand. A repository cannot declare its own hooks (if it could, a
+   clone would be remote code execution), so one opt-in step is irreducible. Escalate in this order
+   (#2, the existing surface comes first):
+
+   | Tier | Signal in the repo | Where the gate lives |
+   | --- | --- | --- |
+   | 1 | `.husky/`, `lefthook.y*ml`, `.pre-commit-config.yaml` | **in the manager already there**: add `afm gate --staged` to its config |
+   | 2 | `package.json` (and the operator agrees) | propose **husky** (or **lefthook**, for a binary with no Node) and run its install |
+   | 3 | neither one nor the other | `afm install git`, which writes the pre-commit, commit-msg and post-commit hooks into the repository's hooks directory |
+   | 4 | none of these fit (no local git, CI-only) | a CI step that runs `afm gate --worktree` |
+
+   The table is a recommendation, not a rail. **Introducing a new manager into a project with none is a
+   new tool** (step 1): state the cost explicitly, and it loses to tier 3 when the project is not Node.
+
+   **Running the install is allowed. Auto-installing is not.** The activation writes outside `docs/`,
+   so it runs only when the operator asks. When they ask, the agent runs it. What stays forbidden is
+   the gate arming itself inside a session-start or inside another hook: an opt-in that installs
+   itself is not opt-in.
+
+7.5. **If no native surface exists** (no husky, no `core.hooksPath`), the harness hook that runs
+   `afm gate --staged` before a shell commit is the last resort. It works only as tier 3, and it steps
+   back as soon as a native surface appears: a duplicate gate reports the same finding twice and
+   teaches the operator to ignore the output. The blocking carve-out is justified by **damage
+   asymmetry**: blocking a commit delays work, blocking an edit disables the whole session.
+
+> **The limit, stated in full.** An installed gate can be bypassed (`--no-verify`, `# noqa`,
+> `eslint-disable`). That is not a design failure: friction is the intended effect, and a gate with no
+> escape gets uninstalled. What the record from step 6 buys is that **bypassing leaves a trace, and
+> removing it requires refuting the reason**, not that bypassing is impossible.
+
+## Inalienable rule
+
+A rule marked `INALIENABLE` in `afm.md § 3` **cannot be removed or marked N/A** by this op: `afm rule na` and `afm rule remove` refuse, under explicit invocation and under a suppressed sub-gate alike. A
+request to do so **stops and reports**. This op is not the right channel; the right channel is the
+plugin maintainer, with the repo open (`afm promote` records the argument with evidence).
+
+What this op **can** do to an inalienable rule: fill in its `{{placeholder}}` (the `{{src-path}}` of
+rule 21, for example) and adapt the `*Verification:*` line to the stack. The **form** belongs to the
+framework, and the **constant** belongs to the operator (step 4).
+
+**The limit, stated in full:** `docs/afm.md` is a file in the operator's repo, and nothing stops them
+from editing it by hand. This op refuses to do so. The `afm doctor` check A5b flags the absence as
+CRITICAL. Detection is not prevention, and promising prevention would misstate what the architecture
+delivers.
+
+An ordinary rule that no longer applies: `afm rule na <id> --reason "<why>"` keeps the number and
+marks the index line N/A. `afm rule remove <id>` deletes the rule file and its runner, and its line in `docs/afm.md` § 3.
+
+## Additional for a refactored project
+
+> Applies only if the project was adopted through `afm refactor`. For a greenfield project skip it:
+> every new rule goes straight into § 3.
+
+**Consider whether the rule enters as forward-only** (`afm.md § 3.1`), because applying it
+retroactively would break a lot of existing code. Ask `afm ask rule-scope` (questions in
+`content/questions/rule-scope.questions.yaml`). The rule's scope is a matter of intent, not a
+discoverable state.
+
+- `universal`: § 3, applies to all code including legacy. May generate a large cleanup change.
+- `forward-only`: add the rule to the § 3.1 table by hand, with the reason and where the debt is
+  tracked. New code and boy-scout edits only; tracked tech debt, not a PR blocker.
+- `cancel`: undo with `afm rule remove <id>` if the rule was already written.

package/content/ops/specify.md

@@ -0,0 +1,62 @@
+---
+type: op
+description: Opens the feature folder and writes the spec, the what and the why with no technology.
+load: warm
+writes: ["docs/features/*/spec.md", "docs/ust.md"]
+composes: []
+---
+# Sub-flow: open feature folder (`specify`)
+
+> **Form** — effect: `features/NNN/spec.md` · trigger: `afm specify`, composition · pre-condition: `.afm-version`, `ust.md` · composed by: `deliver` 1.B · **degree of freedom: low**
+
+Triggers: `afm specify <slug>`, or natural language ("open feature", "start new feature", "spec for feature X").
+
+> **Autonomy-first (#6):** running this op alone IS the approval to open the feature. The agent computes the heuristic and the linked US from the scan (discover-first #2), writes the spec and reports the result. Review happens through `git diff`. **Under the assisted-planning protocol** (`plan=assisted`, run `afm protocol` to read it) this rule does NOT apply and the op keeps its own gate. With no protocol declared, the default applies (autonomous). See [`core/protocol.md`](../core/protocol.md) § 2. **In orchestrated mode** (called by [`deliver.md`](deliver.md)) approval moves to the single gate; see its suppression contract.
+
+The fixed questions of this op are data: `questions/specify.questions.yaml`. Ask them with `afm ask specify --scope <slug>` and record one answer with `afm answer specify <id> <label> --scope <slug>`. A free-text value (the slug, a US number) is not a question-file entry: ask for it in plain words.
+
+Procedure:
+
+1. **Pre-check.** Run `afm preflight`. Exit 3 means no `docs/.afm-version`: stop and redirect to `afm init` (greenfield) or `afm refactor` (brownfield). Exit 4 or 5: report the line it printed and stop.
+
+2. **Trigger heuristic — discover-first (#2): compute it from the scan, do not ask a blank question.** Run a quick scan (search plus the estimated change size). Does **any** criterion match: `>1 day OR >200 lines OR >3 files OR new layer/component (rule 11) OR new external boundary OR >2 unknowns`?
+   - Clearly **not** a match: stop and suggest the `core/afm.md` § 2 loop directly, with no feature folder. This applies KISS to the method itself.
+   - Clearly a match: go to step 3.
+   - **Only** if the case is borderline, ask the question `heuristic`.
+
+2.5. **Retrieval before generate (Voyager/AWM): before you open a new folder, check whether this extends something.** Run `grep -rliE "<feature-tokens>" docs/features/*/spec.md docs/adr/ 2>/dev/null`. This is the same check as [`deliver.md` Phase 0.A0](deliver.md): a link, not a copy. If an equivalent feature or ADR exists, **propose extending it** and do not open a new number. An empty result means proceed.
+
+3. **Next number.** Run `afm next-id feature`. It prints the zero-padded `NNN` (`001` when `docs/features/` does not exist yet).
+
+4. **Slug.** The kebab-case of the `<slug>` the operator gave, or derived from the linked US. If it is empty, ask in plain words.
+
+5. **Linked US — discover-first: search `docs/ust.md` before you ask.** Look for a US that matches the feature (title, persona, criteria). If there is an obvious candidate, propose it. Then ask the question `us-link`:
+   - `candidate` (recommended when a candidate was detected): confirms the link.
+   - `other-existing`: a different existing US; ask for its number in plain words.
+   - `create-first`: run the mini US flow, which mirrors `interview/bootstrap.md` § 3 to write a Gherkin criterion, and add the new US to `docs/ust.md`.
+   - `later`: mark `[NEEDS CLARIFICATION: link the US]` in the spec.
+
+6. **Create `docs/features/NNN-slug/spec.md`** with `afm new feature-spec <slug> --description "..."` (add `--us US-NNN` when step 5 linked one; the command takes the next feature number and writes the frontmatter), then fill in the body:
+   - the title and the date.
+   - § 1 from the US description (if linked); with no US, mark `[NEEDS CLARIFICATION:]`.
+   - § 3 Gherkin scenarios copied from the US (if linked).
+   - § 5 with at least one `[NEEDS CLARIFICATION:]` that states the main gap. Do not invent it.
+   - Keep the other `{{placeholders}}` for later.
+
+   **The generator writes the frontmatter the template's own `frontmatter_for_output:` names** (hard rule 39: an op declares the keys it writes): `type: feature-spec`, `description`, `load: cold`, `status: draft` (the folder's ONE lifecycle value, no Status line in the body), `for_paths: []`, and `us: US-NNN` when step 5 linked one. `for_paths` starts empty: `plan.md` fills it once the components are known. `afm index --for <path>` routes a code path to the feature through it, and `status` tells the reader whether a route still applies (a `done` or `cancelled` feature no longer governs). A feature born without those keys stays invisible to the index.
+
+7. **Write and report** (#6): write `spec.md`, print a summary, the path and the open `[NEEDS CLARIFICATION:]` items. Review happens through `git diff`; no blocking question.
+
+8. **Update `docs/ust.md`**: add the line `Spec: docs/features/NNN-slug/spec.md` to the linked US metadata (if any). Write it directly (#6).
+
+9. **Output to the operator:** the path of the spec, the numbered list of open `[NEEDS CLARIFICATION:]` items, and the suggested next step: "Resolve the clarifications and run `afm plan`, now or later." Check where the delivery stands with `afm feature status <NNN>`.
+
+## Anti-patterns
+
+- ❌ Do not invent a success criterion the operator did not state (universal #5, see [`../PRINCIPLES.md`](../PRINCIPLES.md)).
+- ❌ Do not create a spec with no linked US **and** no `[NEEDS CLARIFICATION: link the US]`.
+- ❌ Do not skip the trigger heuristic. A feature folder for a trivial change is overhead.
+- ❌ Do not ask a blank question about the heuristic or the US. The scan or `ust.md` already show it (#2).
+- ❌ Do not block with a question before each write. Autonomy-first (#6): write and report.
+- ❌ Do not decide the stack or a function name in the spec. That is `plan.md` territory.
+- ❌ Do not pick the number by hand. `afm next-id feature` is the only source.

package/content/ops/tasks.md

@@ -0,0 +1,67 @@
+---
+type: op
+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: []
+needs: ["feature"]
+---
+# Sub-flow: make tasks for the feature (`tasks`)
+
+> **Form** — effect: `features/NNN/tasks.md` · trigger: `afm tasks`, composition · precondition: `plan.md` has no marker · composed by: `deliver` 1.D · **degree of freedom: low**
+
+Triggers: `afm tasks`, or natural language ("make the tasks", "break the feature into tasks").
+
+> **Autonomy-first (#6):** running this op IS the approval to generate `tasks.md`. The agent materializes and reports (review through `git diff`), with no per-artifact question. **Under the assisted-planning protocol** (`plan=assisted`, run `afm protocol` to read it) this rule does NOT apply and the op keeps its own gate. With no declared protocol, the default applies (autonomous). See [`core/protocol.md`](../core/protocol.md) § 2. The **HARD block** for `[NEEDS CLARIFICATION:]` (step 2) STAYS: it is a mechanical refusal, not a question. **Orchestrated mode** (called by [`deliver.md`](deliver.md)): the HARD block becomes a CRITICAL finding at the single gate; see its suppression contract.
+
+This op asks nothing a question file could hold. Choosing among several candidate features is a dynamic list: ask it in plain words.
+
+Procedure:
+
+1. **Pre-check.** Run `afm preflight` (exit 3: no `docs/.afm-version`, redirect to `afm init` or `afm refactor`). Find the feature: with zero plans, stop and suggest `afm plan` first. With several, **auto-detect the active feature** (discover-first #2): the branch `feat/NNN-*`, then the operator's hint, then the one `afm feature status <NNN> --json` reports with `phase` `tasks`. Ask in plain words only when two or more candidates are genuinely ambiguous.
+
+2. **HARD block on an open `[NEEDS CLARIFICATION:]` in the plan.** `afm feature status <NNN> --json` lists them in `blockers`. When it is not empty, refuse to run and answer:
+
+   > "The plan has N open `[NEEDS CLARIFICATION:]` marker(s):
+   > - plan.md:LINE: «question text»
+   >
+   > Resolve these first (edit the plan, or run `afm plan` again to answer them), then call me back. Tasks generated with open clarifications come out incoherent."
+
+   There is no "proceed anyway" override: this is a hard gate. (`[TBD]` in the plan does **not** block. It only shows up as a flag in the output.)
+
+3. **Read `spec.md` and `plan.md`** in full, for the feature.
+
+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 `--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`** (`--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 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, `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 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, 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 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 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.
+- ❌ 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.