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

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.

package/content/ops/update.md

@@ -0,0 +1,252 @@
+---
+type: op
+description: Brings a materialized instance up to the current plugin version.
+load: warm
+writes: ["docs/.afm-version", "docs/evolution/*.md"]
+composes: []
+---
+# Sub-flow: sync of the materialized instance with the current plugin version (`update`)
+
+> **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:
+"update AFM here", "bump the methodology version", "sync `docs/` with the new plugin", "migrate to the new
+AFM version", "my `.afm-version` is behind".
+
+> **The write target is the local docs (`docs/`), NEVER the plugin.** `afm update` reads the shipped
+> content only to **discover the deltas**. It **materializes** the consumer-facing ones
+> in the local instance. It never edits the plugin (bright line #7). See `afm path ops/evolve` § The
+> target of evolution.
+>
+> **Sync mechanism, not orchestrator.** `update` resolves the **instance-to-plugin version drift** (axis
+> A3, which `afm diagnose` *detects* but does not fix). It runs à la carte (this doc, with its own gate)
+> or inside the `evolve` cycle, which composes it when `afm diagnose` flags A3, with the own gate
+> suppressed (see § Suppression contract).
+
+The command owns everything mechanical: reading the pin, comparing versions, running the **codemod
+registry** of every release between the pin and the binary (ADR-0013), proving each op, keeping the manifest
+and moving the pin at the end. This op owns the three things it cannot do: the agent tasks, the language
+migration and the post-conditions.
+
+## When it is another op instead
+
+- `init` / `refactor` (bootstrap) **create** the instance from zero. `update` assumes the instance
+  **already exists** and only brings it forward. `afm refactor` refuses a project with `.afm-version`;
+  `update` is the correct path for that case.
+- `diagnose` only **detects** A3 (read-only). `update` **resolves** it. Diagnose finds it, update fixes it.
+- `evolve` is the full health cycle. `update` is **one lens** (version sync), composed when A3 fires.
+- `promote` **logs** a finding meant for the plugin. `update` goes plugin to **instance**. Neither op
+  touches the shipped content: an absolute boundary (#7).
+- Not a resolver of `[TBD]`. Not an inventor of product content (#4/#5). It materializes only what the
+  plugin already provides: stack-agnostic rubrics, hygiene rules, template sections. It never fills in a
+  product decision.
+
+## Procedure
+
+1. **Preview:** `afm update --dry-run`. It runs the pre-check and prints every codemod with its result
+   against an overlay of the docs, writing nothing:
+   - Exit 3: no `docs/.afm-version`. Stop and run `afm init` (greenfield) or `afm refactor` (brownfield).
+   - Exit 5: the pin and the binary differ by a major version. Run `afm migrate` (the 3.x to 4.0 bridge),
+     then `afm update` again.
+   - *already up to date*: no drift means nothing to do, and an empty diagnosis is a valid result.
+   - *anomaly*: the pin is **ahead** of the binary. Someone edited the instance by hand, or the binary
+     is old. Report it, upgrade the binary, and never roll the pin back.
+2. **Read the preview as one package, not N loose items.** The tally counts what each op did:
+   - *applied*: the op wrote (a literal replacement, a move, a created or synced file, a frontmatter key,
+     a section, a regenerated surface).
+   - *already applied or absent*: the proof of need failed (the old text is not there), so the delta was
+     already applied or never existed in this instance. Silent, and not work done.
+   - *held*: `[TBD]` content protects the text (#4), or the owner edited a file a codemod would delete.
+     **Stop and report it**: the owner's stance wins.
+   - *failed*: a proof of application did not hold. The pin stays; fix the cause and run again.
+   - *agent task(s) pending*: work only judgment can do (below).
+   - a release with nothing to materialize counts toward the bump and prints no line. Do not invent work
+     where the plugin declared there is none.
+3. **Own gate (à la carte).** Show the preview as evidence (which version to which version, what each
+   codemod changes in the instance), then ask `afm ask update` (questions in
+   `content/questions/update.questions.yaml`). Under the `evolve` cycle this gate is **suppressed**: the
+   migration item moves up to the orchestrator's single gate.
+4. **Apply:** `afm update`. It runs every codemod, proves each one, prints the tally and **moves
+   `docs/.afm-version` only at the end**. The exit code tells what is left:
+   - Exit 0: done, the pin moved.
+   - Exit 1: a codemod failed (or the pin is ahead). The pin stays (marker honesty: never bump as if the
+     migration were complete). Fix it and run again.
+   - **Exit 6: agent tasks are pending.** Do them (step 5), then run `afm update` again. The pin stays until
+     every task passes its check.
+   - **Protected surfaces** are never materialized by an update: the shipped content itself,
+     `PRINCIPLES`, `[TBD]` content, the format the hooks parse, the rubric that decides when the evolution
+     cycle runs (`when-to-evolve-methodology`) and the `triggers` entries that fire the evolution
+     mechanisms. That is self-reference: the sync does not materialize the document that decides when
+     the cycle runs. New stack-agnostic rubrics, yes.
+5. **Do each agent task** listed after the tally. A line reads `agent <codemod>: <brief> (scope: <paths>)`
+   followed by the lines of its check that still fail. Work only inside the scope, through the write ops
+   (`afm adr`, `afm gotcha`, `afm rule`, `afm new <type>`), suppressing each op's own per-artifact
+   question. Run `afm lint <path>` to see the frontmatter findings and `afm lint --fix <path>` to fix
+   the ones that have one exact answer. Never invent content: what the operator did not say stays `[TBD]`.
+   A `[TBD]` placeholder alone lints clean and does not hold the pin.
+   An agent task is mechanical disambiguation: fan it out on the light model tier, per the fan-out principle
+   of `afm.md` § 1, and let the codemod do the write (re-run `afm update --dry-run` until the file is no longer
+   held; never write a `tasks:` list by hand).
+   When the run prints `commit .afm/config.toml: it is the project's AFM config`, commit that file with the update: `.afm/` holds nothing else (machine state lives in `~/.afm/state`).
+6. **Close a sync on an edited file** with `afm update --accept <path>`. When a codemod would overwrite a
+   materialized file the owner edited (its hash in the manifest no longer matches), it hands the merge to
+   the agent instead. Merge the new shipped text into the owner's file, then run
+   `afm update --accept docs/<path>`: it records the file as it is now as the accepted version. It never
+   edits the file.
+7. **Run `afm update` again** until it prints `pin: <from> -> <to>` (or *already up to date*). Then the
+   **post-conditions** (below) and the **log**.
+
+## What the codemods can do
+
+A release is a module in `packages/core/src/features/codemod-releases/data/` with an ordered list of typed ops. The rules that
+make them safe are 0/1 and none depends on judgment:
+
+| Op | What it does | Proof of need | When it hands over |
+| --- | --- | --- | --- |
+| `replace` | literal substitution in one file | the old text is in the file | `[TBD]` there: *held* |
+| `move` | renames a file or a folder | the source exists | a target that already exists |
+| `create` | writes a shipped file the instance lacks | the file is absent | never overwrites |
+| `sync` | overwrites a materialized file with the new shipped text | the manifest hash still equals the file | an edited file becomes an agent task (`--accept`) |
+| `delete` | removes a file the plugin retired | the manifest hash still equals the file | an edited file is *held* |
+| `frontmatter` | sets or renames a key | the key is missing or old | `[TBD]` there: *held* |
+| `section` | adds a section to a doc | the heading is absent | never rewrites an existing one |
+| `regenerate` | rebuilds a generated surface (agents block, stubs, index) | the surface is stale | none |
+| `custom` | a program for what the others cannot say (the OKF lift) | its own | its own agent tasks |
+| `agent` | what only judgment can do (a rewrite, a merge) | its own | always, with a mechanical check |
+
+**The rules:**
+
+1. **Proof of need before a file is touched.** Zero matches means already applied: skip it silently.
+2. **Literal substitution, never a regular expression.** A pattern on an instance the owner edited by
+   hand is how a sync destroys text nobody asked to change.
+3. **Proof of application afterwards.** The old text is gone **and** the new text appears at least as often.
+4. **A file missing from the instance is skipped.** A doc the consumer never materialized does not arrive
+   through the back door, except through an explicit `create`.
+5. **`[TBD]` is untouchable** (#4): text inside a block the owner marked this way is *held*.
+6. **The manifest is the memory of what AFM wrote.** `docs/.afm-manifest.json` maps each file AFM wrote to
+   the hash of the text it wrote. `sync` and `delete` act only on a file whose hash still matches. A file
+   the owner changed is never overwritten or removed silently: the old "update never deletes" is now
+   "update never deletes what the owner changed". Commit the manifest with the docs.
+7. **The proof of need decides, not only the pin.** A codemod whose precondition still holds runs even when
+   the pin is past its release.
+8. **The pin moves last**, and only when every agent task passes its check.
+
+> **Discover-first (#2):** the proof of need is the discover-first rule. A delta the operator already copied
+> by hand never reappears.
+
+## Instances older than 4.0
+
+`afm update` refuses to cross a major version (exit 5). A 3.x instance goes through `afm migrate` first
+(`--dry-run` to preview): the bridge to 4.0, the split of `docs/gotchas.md` into `docs/gotchas/` and of
+`afm.md` section 3 into `docs/rules/`, and the report names. Run it once and **commit before anything
+else** (a structural migration mixed with a content edit hides both in the diff). Then run `afm update`
+to receive the codemods of the 4.x releases (the OKF frontmatter lift among them), and
+`afm index --materialize` (hard rule 39 fails on a missing or stale index).
+
+## 1.6 Language migration (runs when the instance is not English)
+
+Artifacts are English: the docs, the code, the comments, the tests, the rule text. The ONE exception is
+the strings the product shows its own users, and that is a product decision.
+
+**The order below is the mechanism, and reversing it is the defect.** Read the field. Derive the excluded
+scope. Only then read a file. "Scan first, remember to skip" makes the exclusion depend on the agent
+noticing during the work, and that is the branch that damages a product.
+
+1. **Read `docs/prd.md` § 11.1 FIRST.** It holds the app-facing string language. An instance
+   materialized before this field existed has no such section, which reads the same as `[TBD]`.
+2. **`[TBD]` or absent: stop and ask `afm ask update-strings`** (questions in
+   `content/questions/update-strings.questions.yaml`). Never choose a language. The irreducible mistake
+   is "no field, so nothing is a product string, so migrate everything". A translated UI is not something
+   `git revert` gives back to the user who saw it.
+3. **Derive the excluded scope from the answer, before any file is read.** The exclusion is a file and
+   directory list computed once, not a judgment made per file. An English app language makes the excluded
+   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 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.
+
+**Post-condition.** `prd.md` § 11.1 is unchanged by this step. The migration reads that field and never
+writes it. The product language is the owner's decision, not a consequence of a version bump.
+
+## Opt-in deltas: a release that adds a capability, not a requirement
+
+A capability delta is not a migration. Nothing breaks when the operator ignores it, and `update` must not
+apply it silently, because opting in is the operator's decision. The release notes (`content/CHANGELOG.md`) name it, and no codemod applies it.
+Report an opt-in delta, and never apply it. A project that has not opted in has not decided against the
+feature: it has not been asked.
+
+| Release | Capability | How to opt in | What happens if you do nothing |
+| --- | --- | --- | --- |
+| 3.10.0 | organisation policy | set `[org] dir` in the global config, pointing at a bundle that holds `policy.md` that your user owns (it was the `AFM_GLOBAL_DIR` variable before 4.0) | nothing. Every reader returns before any file test when no bundle is set |
+| 3.11.0 | `policy_blocking` is REMOVED | delete the key if an instance added it | nothing. It decided nothing while it existed |
+
+## Post-conditions
+
+1. **Parseable format.** Re-extraction by the hooks over the touched docs must preserve the format:
+   `afm lint` exits 0, `afm index --check` returns 0 and `afm gate --audit` is no worse than before. Otherwise roll back the
+   delta and report it. Never fail silently.
+2. **The instance/plugin boundary is MECHANICAL.** Run the two-branch check in `afm path ops/evolve`
+   § Phase 4.3 at the end. The boundary must come back clean: any change in the shipped content means
+   **rollback + report CRITICAL**. `update` only reads the plugin.
+
+## Log and handoff
+
+- **À la carte:** report in chat what migrated (applied deltas, pending deltas, the newly pinned version).
+  A simple sync does not need its own `docs/evolution/` entry.
+- **Under `evolve`:** it feeds the cycle report (the A3 migration becomes one line in
+  `docs/evolution/<date>-NNN.md`).
+- **Handoff to `afm reconcile`** to watch, in the following sessions, whether the materialized delta now
+  guides well.
+
+## Suppression contract (back-pointer)
+
+`evolve` **composes `update`** on axis A3. Under the cycle, `evolve` suppresses the gate of step 3 and
+moves the item up to its single gate; the log feeds the cycle report. The authoritative table lives in
+`afm path ops/evolve` § Suppression contract. À la carte, `update` runs on its own, with its own gate.
+
+## Anti-patterns
+
+- ❌ **Editing the shipped content.** `update` only **reads** the plugin to discover deltas. It writes
+  only to the instance.
+- ❌ **Materializing a consumer-noop release.** A plugin-internal patch with no content to materialize
+  only bumps the version. Do not invent work.
+- ❌ **Re-materializing a delta that is already in the instance.** The proof of need exists for this.
+- ❌ **Overwriting or deleting a file the owner edited.** The manifest hash is the guard: merge by hand and close it with `afm update --accept <path>`.
+- ❌ **Materializing a protected surface:** the evolution cycle's own rubric, the evolution `triggers`,
+  and `[TBD]`. This is self-reference, and it is the operator's own stance.
+- ❌ **Bumping `.afm-version` as if the migration were complete.** If a delta was left out, the marker
+  must show the gap honestly.
+- ❌ **Inventing product content.** `update` materializes only what the plugin already provides
+  (stack-agnostic). A missing product decision stays `[TBD]`, for `afm reconcile` to handle (#4/#5).
+- ❌ **Running as bootstrap.** A missing instance calls for `init` or `refactor`, not `update`.

package/content/ops/verify.md

@@ -0,0 +1,67 @@
+---
+type: op
+description: Stamps a human verification on a doc, the only writer of the OKF `verified` field.
+load: warm
+writes: ["docs/**/*.md"]
+composes: []
+---
+# Sub-flow: stamp a human verification (`verify`)
+
+> **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.
+Examples: "I reviewed this rule", "mark this gotcha as verified", "sign off on this ADR".
+
+## What `verify` is, and is not
+
+OKF v0.2 §5.2 keeps two facts apart. `generated` records what PRODUCED the content. `verified`
+records who CONFIRMED it. They are separate because the writer and the checker are different
+actors, and a document can change without re-confirmation.
+
+From those two fields OKF derives a trust tier (§5.3):
+
+| `verified` | Tier |
+| --- | --- |
+| absent | **unverified** |
+| present, no `human:` actor | **machine-confirmed** |
+| present with a `human:<id>` actor | **human-reviewed** |
+
+AFM is autonomy-first. `reflect`, `reconcile` and `remediate` all WRITE documentation. Without this
+operation, "an agent wrote this and no person read it" and "a person approved it" look the same.
+
+## Why only a human, and why only here
+
+An automatic writer would destroy the field. The agent commits under the operator's git identity. A
+hook that stamps `verified` on every commit would claim human review of every agent commit. That is
+worse than no field: it converts an honest absence into a confident lie.
+
+So the rule is one line. **Absence means unverified, and only an explicit human stamp writes it.**
+The command enforces it: it refuses when `AFM_ACTOR` names a role or a machine instead of a person.
+
+## Procedure
+
+1. `afm preflight`. Exit 3: no instance, stop.
+2. **Confirm that a person read the file.** Show it, or ask `afm ask verify` (questions in
+   `content/questions/verify.questions.yaml`). Never infer review from ordinary work. `No` stops.
+3. **Stamp it:** `afm verify <path under docs/>`. The actor is `human:<id>`, where `<id>` comes from
+   `--as <id>`, from `AFM_ACTOR=human:<id>` or from the git `user.name` in lowercase with no space.
+   The command appends `verified: [{ by: "human:<id>", at: <ISO 8601 UTC> }]`, keeps every other
+   key, and adds an entry when `verified` is already a list. A second check is a second event; the
+   tier reads the latest `at`.
+4. **Report the tier that resulted**, and say what it means. The command prints it.
+
+A file with no frontmatter carries no contract to stamp, and the command says so.
+
+## What it must never do
+
+- Never stamp a file the person did not read.
+- Never write `verified` from a hook, a gate, a commit, or another op.
+- Never remove a verification. A doc that changed after a verification stays verified at that date,
+  and the date is the signal. Silently dropping it hides that the content moved.
+- Never write `generated` here. That belongs to whoever produced the content.
+
+## Invariant principles
+
+The single canonical source is `afm path PRINCIPLES`. Universals §1-8 apply. #5 applies hardest:
+this operation records a fact about a person. Inventing one is the worst kind of invention, because
+nothing downstream can tell.