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

package/content/CHANGELOG.md

@@ -0,0 +1,4320 @@
+# Changelog — framework-template
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning [SemVer](https://semver.org/lang/pt-BR/).
+
+> **Older releases live in [`CHANGELOG-archive.md`](./CHANGELOG-archive.md).** Everything
+> from `3.0.0-rc.1` through `3.4.0-rc.7` moved there on 2026-08-23, verbatim and
+> uncompressed. `ops/update.md` must read the archive too when the version range reaches
+> back before `3.5.0`.
+
+## [Unreleased]
+
+## [4.0.0-alpha.10] - 2026-10-21
+
+### Changed
+
+- **`ops/rule.md` and `templates/guardrail-runner.template.md` teach the TypeScript runner.** `afm rule new` writes a `.ts` skeleton by default (`--runner sh` for bash); step 2 of "Install the gate" says when each form fits.
+- **G2: `ops/evolve.md` 3.B** says the labels are Apply, Skip or Stage, and `--recommend` is case-insensitive.
+- **G3, G7: `ops/update.md` step 5** sends agent tasks to the light model tier (the codemod does the write) and tells the agent to commit `.afm/config.toml` when the update prints that line.
+
+### Consumer migration
+
+- **record-pristine-alpha10.** A docs file already equal to what afm init writes today is recorded in the manifest as AFM's own. (ops: custom)
+
+## [4.0.0-alpha.9] - 2026-10-15
+
+The docs learn from use: what is used stays in evidence, what is not fades, and reflect reads every session of the project in every harness.
+
+### Added
+
+- **Cross-session reflect (ADR-0023).** `ops/reflect.md` and `ops/evolve.md` read the live session plus the project's sessions since the last cycle, through `afm sessions` and `afm sessions signals` (deterministic signals: corrections, tool-error groups, AFM injections, rereads, repeated prompts). A φ_b cites `session:<id>@<ts>`; the 2-occurrence gate counts across sessions; a covered session is marked with `afm sessions mark`; a cycle lists what it handled in `resolves:`, and a signal that comes back after it is `regressed`.
+- **Repeated prompts become artifacts.** A prompt the owner retypes is a finding; a cluster of operational verbs (commit, push, deploy, release…) is flagged `[runbook?]` and becomes an `afm new procedure` proposal in the project where it repeats.
+- **On-demand sections (ADR-0024).** An op declares `sections:` in its frontmatter; `afm read ops/<op>.md` prints the core with a one-line stub per on-demand section, and `--section <slug>` prints one. `ops/evolve.md` is the first op split this way (about 10 KB of core out of 36 KB).
+- **Relevance tiers act at run time (ADR-0024).** `load:` decides what a hook delivers: a `hot` doc is listed at session start, a `cold` one reaches a write only through its file-shape trigger. `afm doctor` proposes tier changes (`tier-drift`) and tombstones for cold orphan docs nobody uses (`fade`), always through the gate.
+
+### Changed
+
+- **Skills name the host's own tools.** A skill writes `{{host:<term>}}` and `afm render` writes each harness's wording (ADR-0022); the render also injects the op pointer and the principles and version footer, so the skills carry neither.
+- **Skills are pointers to their op**: `evolve`, `deliver`, `tasks` and `generalize` keep only what the op lacks.
+- **`ops/update.md` runs the language migration as one orchestrated batch on a light model**, with a light-model loss check and escalation of a flagged file only.
+
+### Consumer migration
+
+- **rules-canonical-sync-load-tiers.** A PLUGIN-<n> hard rule of docs/afm.md whose text an earlier release shipped takes the current canonical text (PLUGIN-39 now says what each load: tier does); an edited rule is held; a retired rule and a project rule are never touched. (ops: custom)
+- **record-pristine-alpha9.** A docs file the codemods above brought to exactly what afm init writes today is recorded in the manifest as AFM's own. (ops: custom)
+
+## [4.0.0-alpha.8] - 2026-10-13
+
+Metadata lives only in the frontmatter, and what the model used to judge is data the CLI owns: the tasks of a feature, the artifact language and the hard rules.
+
+### Changed
+
+- **No table of contents.** `> **In this file:**` is gone from every doc; the headings say it. `core/ach.md` also loses `Author` and `Related docs`.
+- **Feature templates.** `feature-plan` drops `Inferred stack` (it lives in `ach.md` § 1), `feature-research` writes its trigger as the frontmatter `context:`, and the guidance callouts of `feature-spec` and `feature-tasks` are plain prose.
+- **Ancestors in the frontmatter.** The ops and the induced tasks template carry `ancestors:` instead of a body line. The protocols and the Vireya module lose their `For:` and `Context:` labels.
+- **A feature's tasks are a frontmatter list (ADR-0020).** `tasks.md` holds `tasks:` (`kind` red, green, refactor, setup or reconcile; `scenario`, `closes`, `files`, `refs`, `validates`, `parallel`, `done`) and no checklist. The ops tell the agent to write it with `afm task add`, `afm task set` and `afm task remove` and close a task with `afm task done`, never by hand; `core/afm.md` § 2 says one TDD cycle is a red task, the green task that closes it and an optional refactor.
+- **The artifact language is a config key.** `core/afm.md` points at `[language] artifacts` in `.afm/config.toml`, recorded with `afm config set language.artifacts <tag>`; the init questions ask it (`artifact-language`), and `ops/update.md` and the bootstrap interview leave nothing to judge.
+- **PLUGIN-41 and PLUGIN-42 are declared in `core/afm.md` § 3** (ADR-0021), each scoped by `.afm/config.toml` (`architecture.features.roots`, `architecture.limits.folder_include`); undeclared scope means the rule skips with the reason stated.
+
+### Fixed
+
+- **The ADR template carries no open marker.** The `decided_by` comment names `[TBD]` in a code span, so `afm doctor` no longer reports the template as an open marker.
+- **The ask scope of `ops/deliver.md` is the feature folder name** (`NNN-slug`), which `afm ask --scope` now accepts verbatim.
+
+### Consumer migration
+
+- **tasks-frontmatter-list.** Every docs/features/NNN-slug/tasks.md moves its checklist into the frontmatter tasks: list (ADR-0020), mapped against the spec.md and plan.md next to it; a checklist with no single mapping is left unchanged and handed to the agent. (ops: custom)
+- **artifact-language-to-config.** An artifact language declared in docs/afm.md moves to [language] artifacts in .afm/config.toml; a declaration it cannot move (not a language tag, inside a sentence, against another configured tag), or Portuguese docs with none, is handed to the agent with afm config set. (ops: custom)
+- **rules-canonical-sync.** A PLUGIN-<n> hard rule of docs/afm.md whose text an earlier release shipped takes the current canonical text; an edited rule is held (afm update --refresh docs/afm.md#PLUGIN-<n>); a retired rule and a project rule are never touched. (ops: custom)
+- **rules-add-missing.** A builtin PLUGIN-<n> rule that § 3 of docs/afm.md lacks entirely (PLUGIN-41 and PLUGIN-42 before this release) is added with the canonical text at its numeric position; a retired rule is never resurrected. (ops: custom)
+- **afm-md-task-cycle.** docs/afm.md § 2 says a TDD cycle in a feature folder is a red task, the green task that closes it and an optional refactor of the tasks: list, closed with afm task done. (ops: insert x2, replace)
+- **repair-wrapped-trigger.** A gotcha whose fires_when the old lift cut mid-sentence gets the wrapped Trigger lines back from the body. (ops: custom)
+- **record-pristine.** A docs file the codemods above brought to exactly what afm init writes today is recorded in the manifest as AFM's own. (ops: custom)
+
+## [4.0.0-alpha.5] - 2026-10-08
+
+A shipped copy of the framework whose provenance is proven untouched is brought up to date by the update.
+
+### Fixed
+
+- **A feature folder takes one status.** A file that declares none takes the value its declaring siblings agree
+  on; a folder whose files disagree is held and named in the output, never silently. A prose mention of a
+  `status` key is not a declaration.
+- **An approval of a plan is not a lifecycle state.** `Plan status: approved` stays as prose and no longer holds
+  a done folder.
+- **A `research.md` inside a feature folder** written as `type: research` becomes `feature-research`, and its
+  3.x status (`draft`, `reviewed`, `applied`) maps to `open` or `closed`, the word kept as prose.
+- **A trigger that agrees is not a contradiction:** a truncated prefix of the body `Trigger`, a value equal to it
+  once whitespace and punctuation are normalised, a glob that covers a path the body names, or a glob beside a
+  body sentence that names no path (the glob becomes `trigger_path`).
+- **`afm update --refresh <path>` and `--all-shipped`** are two alternatives with a clear usage error.
+
+### Consumer migration
+
+- **shipped-copy-sync.** A materialized rubric, pattern or ADR template whose provenance is proven untouched (its manifest hash, or a text an earlier release shipped) is replaced with the current shipped text; a copy of unknown provenance or an edited one is left for afm update --refresh. (ops: custom)
+
+## [4.0.0-alpha.4] - 2026-10-08
+
+A feature folder with no status gets one derived from its tasks.md.
+
+### Consumer migration
+
+- **feature-status-derived.** A feature folder (docs/features/NNN-slug/) where no file declares a status takes one derived from its tasks.md (all ticked: done, some: in_progress, none: planned, no tasks.md: draft) in the frontmatter of its spec, plan and tasks. (ops: custom)
+
+## [4.0.0-alpha.3] - 2026-10-08
+
+Templates mark their explanatory passages as guidance, so a generated document carries only what its
+author fills in.
+
+### Changed
+
+- **Fifteen templates** wrap their explainers (blockquotes, italic footers, example comments) in
+  `<!-- guidance -->` ... `<!-- /guidance -->`; `afm new`, `afm adr` and `afm gotcha` strip them.
+- **The gotcha template** marks `bites` and `last_bite` optional.
+- **The core spec** knows `materializes_to` and `status: deprecated`.
+
+### Consumer migration
+
+- **adr-template-guidance-markers.** The ADR template (docs/adr/0000-template.md) marks its explanatory passages as guidance, which afm adr strips from the ADRs it writes. (ops: sync)
+
+## [4.0.0-alpha.2] - 2026-10-08
+
+The review of wave B: the lift, the lint and the codemod engine stop guessing, and the doctrine text says
+what a number or a rule may claim.
+
+### Fixed
+
+- **The OKF lift** hands a contradiction (a body value that disagrees with the frontmatter) to the agent
+  instead of picking one, and a learning is injected from its frontmatter. A lifted `Trigger:` line that
+  names a path in backticks becomes `fires_on: file-shape` with that `trigger_path`, so the pre-edit hook
+  delivers the lifted gotcha or learning; with no path it stays an `event`.
+- **`afm lint`** stays inside the roots the index reads and judges only the scope it was given, and
+  `--fix --json` carries the items the lift could not resolve.
+- **`afm rule --does-not-cover`** refuses a blank value instead of writing a rule that fails its schema.
+- **The codemod engine**: `sync` has three outcomes (overwrite a pristine file, hold a file the owner
+  accepted against the same shipped text, hand any other edited file to the agent), the shipped hash is
+  recorded at `--accept` time, and `--dry-run --accept <path>` writes nothing.
+- **The failure-classification rubric** has its decision tree in English.
+
+### Changed
+
+- **Rules and guardrails** state what they do not cover (`does_not_cover`), and a rule statement names
+  its scope.
+- **Deliver** numbers carry provenance; **remediate** needs a red proof first; **analyze** has an
+  invention class; the architecture guide says how an import-rule exit is read; the feature-tasks
+  template notes the version bump.
+- **The ADR template** no longer carries a body metadata block.
+
+### Consumer migration
+
+- **record-untouched-files.** A materialized file with no manifest entry whose text is what init writes today, or exactly what an earlier release wrote for the failure-classification rubric or the ADR template, is recorded as untouched so the syncs below can update it. (ops: custom)
+- **failure-classification-english.** The failure-classification rubric's decision tree is in English, and its guardrail origin keys name the English frontmatter. (ops: sync)
+- **adr-template-no-body-metadata.** The ADR template (docs/adr/0000-template.md) keeps status, date and decider in the frontmatter only, with no body metadata block. (ops: sync)
+
+## [4.0.0-alpha.1] - 2026-10-07
+
+Metadata moves into the frontmatter, one strict schema per OKF type (ADR-0014), and `afm update` runs
+typed codemods instead of reading prose (ADR-0013).
+
+### Added
+
+- **One schema per OKF type** (`packages/core/src/dsl/okf/schema/`): an unknown type or a retired `kind:` is an
+  error, a missing frontmatter is a warning outside a declared family, and a write that breaks a
+  blocking family (adr, rule, gotcha, feature-spec, feature-plan, feature-tasks, guardrail) is refused.
+- **The codemod registry**: each release declares ordered, typed ops (replace, move, create, sync,
+  delete, frontmatter, section, regenerate, custom, agent). The run proves each op's need before a
+  write, hands judgment to the agent as a task with a 0/1 check, and moves the pin only when no task is
+  pending.
+- **`docs/.afm-manifest.json`**: the hash of every file AFM materialized, so an update overwrites only a
+  file the owner never edited. `afm update --accept <path>` records an edited file the agent merged.
+
+### Changed
+
+- **Hard rule PLUGIN-39 and the architecture guide** name the per-type schema, `afm lint` as its verification, and `okf/` and `codemods/` in the folder map. Op docs write documents through `afm adr`, `afm gotcha`, `afm rule` and `afm new <type>`; the shipped guardrail catalog is type `guardrail-suggestion`.
+- **Metadata lives only in the frontmatter.** A body starts at its H1: no `> **Status:**`,
+  `**Trigger:**` or `- **Origin:**` lines. A feature folder has one `status` (draft, clarified,
+  planned, in_progress, done, cancelled); a gotcha keeps `bites`, `last_bite` and `refs` in the
+  frontmatter and its Behavior and Solution as `## Behavior` and `## Solution` sections; a guardrail
+  cost is low, medium or high.
+
+### Consumer migration
+
+- **okf-lift.** Every docs file in an OKF family, or with a frontmatter, moves its metadata into a frontmatter its type's schema accepts; what cannot be converted exactly goes to the agent. (ops: custom)
+- **manifest-bootstrap.** An instance with no manifest records every rubric, pattern and ADR template that still equals what init writes today; any other file stays unrecorded and is treated as edited. (ops: custom)
+- **plugin-39-per-type-schema.** Hard rule PLUGIN-39 in docs/afm.md says each type has its own schema and that afm lint is the verification. (ops: replace x2)
+- **rule-does-not-cover.** Hard rules in docs/afm.md say a rule or guardrail may state, in an optional does_not_cover key, what its gate does not check. (ops: replace)
+- **ach-boundary-exit.** The import rules in docs/ach.md say a boundary holds from the first need: a primitive needed on the forbidden side moves to the lowest shared layer. (ops: section)
+
+## [3.43.0] — 2026-09-17
+
+`web_read` leaves `afm`. It moves to the new `research` plugin, which stores each page once and
+scores sources across campaigns (ADR 0027).
+
+### Removed
+
+- **The `research` MCP server** (`mcp/`, `.mcp.json`). `afm` no longer starts an MCP server, and
+  the lazy `npm install` and build on first use are gone with it.
+
+### Changed
+
+- **`ops/research.md`** names the `research` plugin as the source of `web_read`. Without that
+  plugin, the op runs in WebFetch mode, as it already did when the server could not start. The op
+  also points a large, many-subject corpus to `/research:campaign`.
+
+### Consumer migration
+
+- **Consumer-noop.** `CONSUMER_VERSION` stays at `3.41.0`. Nothing materialized into
+  `<consumer>/docs/` changes. To keep `web_read`, install the `research` plugin.
+
+## [3.42.0] — 2026-09-11
+
+`afm-capture-failure.sh` mislabeled three shapes of oracle output — measured in this repository
+and in kandex — filling the `remediate` substrate with signatures no procedure could fix.
+
+### Fixed
+
+- **A signal exit was not a timeout.** The guard was a literal `Exit code 124|143` list, and any
+  process killed by a signal exits 128+N — so `Exit code 144` (a `pkill -f` that matched its own
+  shell, recorded 10 times in this repository's own ledger:
+  `docs/.afm-log-failures/2026-09-03-test-exit-code.md`, and 3 times in kandex) and `Exit code 137`
+  (SIGKILL) both slipped past the guard and were counted as real oracle failures. The guard now
+  checks the FIRST line for `Exit code N` with `N` equal to 124 or in `129..159` (128 + every
+  signal number 1-31). The crash signals stay oracle failures: SIGILL, SIGTRAP, SIGABRT, SIGBUS,
+  SIGFPE and SIGSEGV (132-136, 138, 139). A test runner that aborts or segfaults reports on the
+  code under test, the same as an assertion does. The guard also skips a line that STARTS with
+  `Command timed out after`, which Claude Code can insert on its own. A test whose name only
+  mentions a timeout still counts.
+- **The signature keyed on a stable banner, not on the error.** vitest prints `Testing types with
+  tsc and vue-tsc is an experimental feature.` on every run, right after the exit code — and the
+  old signature normalized the WHOLE error text, so two different failing tests collapsed into one
+  `sig=test-testing-types-…`, and a fixed test still looked like the same recurring failure. The
+  signature source is now the first error-looking line (`error|fail|✗|×|assert|TS[0-9]+`,
+  case-insensitive) found AFTER the `Exit code N` line, falling back to the old whole-text
+  normalization when there is no such line — so a payload with no exit code (an older capture, a
+  non-Bash tool) keeps working exactly as before. A runner summary such as `Tests: 1 failed, 24 passed`
+  prints on every failing run whatever failed, so a line that says `passed` is never the key.
+- **A heredoc's body is data, and its words read as oracle verbs.** An `ste-lint` probe whose
+  scratch heredoc happened to say "run the test suite and check the build" was captured as
+  `sig=test-…` (`docs/.afm-log-failures/2026-09-05-test-exit-code-block-s1-file-procedure-senten.md`),
+  even though `ste-lint` itself was never the failure. Heredoc BODIES (the lines between the
+  opening `<<DELIM` and the closing `DELIM`) are now stripped from the command before verb
+  matching, on the raw command and before the existing quote-stripping. The strip is bodies only,
+  never the whole command: a real oracle chained after a heredoc (`cat > f.json <<EOF\n{}\nEOF\nnpm
+  test`) still counts, which a guard that skipped every heredoc-bearing command outright would have
+  lost. This also exposed a second latent bug in the same guard — the `cat …` reader-shortcut
+  matched a heredoc's opening `cat > file <<EOF` line too (a WRITE, not a read) and, being a shell
+  `case` glob, matched across the newlines into whatever came after it, so the real oracle
+  chained after the heredoc never got a chance to be classified. The shortcut now steps aside
+  whenever the command contains a heredoc redirect.
+
+  New asserts pin this in `hooks/test/run.sh`, next to the existing failure-substrate
+  section, using the real payloads above.
+
+### Consumer migration
+
+- **Consumer-noop.** `CONSUMER_VERSION` stays at `3.41.0` — nothing materialized into
+  `<consumer>/docs/` changes. Every change here is in `hooks/`, which ships with the plugin copy
+  and reaches an instance through `claude plugin update`, never through materialization.
+
+## [3.41.0] — 2026-09-04
+
+The structural writing gate this repository ships as a plugin now runs on the methodology written
+next to it. See [ADR 0025](../../../docs/adr/0025-o-portao-de-escrita-roda-no-proprio-plugin.md).
+
+### Added
+
+- **Hard rule 35 — the methodology text passes `ste-lint --scope strict`**, with a runner at
+  `test/rules/35-ste-strict.sh` wired into `test/guardrails.sh`.
+
+  **Why, measured.** `CHANGELOG.md:505` records a past release: *"29 `block` findings in
+  `ste-lint --scope strict` across 7 op files… Now 0 across all 48 skills and ops."* Run by hand,
+  declared zero, wired to nothing — `grep -rn ste-lint test/ .githooks/` returned nothing.
+  Measured again on 2026-09-04: `ops/` was back to **25** and `core/` had **89**, which had never
+  been in scope. `skills/` was still 0. A number that only a person remembers to measure is not a
+  measurement, it is a memory.
+
+  **It is a LOCAL rule and never reaches a consumer.** Under ADR-0021 a plain `<n>` stays here.
+  ASD-STE100 is this project's convention for its own text; imposing a writing style on the ~37
+  projects that adopted AFM is the imposition 3.40.0 removed when it split `modules/` from
+  `code-style/`. Only `block` fails — `advise` never does, for the reason the linter's own header
+  gives.
+
+### Changed
+
+- **The 114 blocking findings are fixed, so the gate enters at 3 and not at 114.** A gate that
+  starts red is turned off the next day. The 3 that remain are declared in
+  `test/baseline/ratchet.tsv`: three `*Verification:*` lines whose facts cannot be cut and whose
+  line cannot be split — `afm-health.sh`'s A5 axis selects LINES matching `verifica` and reads the
+  backticked paths off them, so a second physical line silently drops every path on it.
+
+- **Prose names the native tool it means.** *"stop and ask"* becomes *"stop and ask through
+  `AskUserQuestion`"* where the sentence is about asking.
+
+  **And it stays abstract where the framework abstracts on purpose.** Three of the first six
+  namings were rejected by the adversarial pass, correctly: `core/protocol.md`'s P3 gate was named
+  `ExitPlanMode`, but `templates/protocols/p3.md:45` says the opposite in the same breath — *"the
+  native mode changes the approval surface, never the criterion"*. Hard rule 11's gate is
+  dual-surface by design (`core/afm.md`: *"`ExitPlanMode`, or `AskUserQuestion`"*), so it keeps its
+  abstraction. Naming one surface where two are documented is a narrowing, not precision.
+
+- **`PLUGIN-2`'s verification gains a native tier, and keeps its fallback.** Where the project
+  already configures the no-explicit-any rule in ESLint or Biome, that command is the trigger.
+  Where it does not, the `grep` stays, unchanged. A repository with no linter behaves exactly as
+  before, byte for byte. Same reasoning as ADR-0015 for the commit gate, applied to a rule trigger.
+
+  The rule ids are spelled out rather than quoted as paths: A5 resolves every backticked path on a
+  `*Verification:*` line against the disk, and a package-scoped rule id looks exactly like one.
+  Writing it the obvious way created a false vital sign, caught before commit.
+
+- **Five `> **Ancestor:**` blockquotes become pseudo-algorithms.** In `generalize`, `restructure`,
+  `reflect`, `evolve` and `diagnose`, the citation's prose was the file's ONLY definition of a term
+  the body then reused — `ShowsImprovement` 6 times, `Staleness` 7, `Reflect` 6, `Commit` 5,
+  `ANALYZER` 4. The citation stays on the first line and the prose becomes a named algorithm that
+  defines each term with `:=`. `ops/remediate.md` keeps its blockquote: there the citation really
+  is only attribution. **No citation was deleted** — 15 before, 15 after.
+
+### The invariants this release was measured against
+
+Every one held, verified by diff and not by count: the 34 rule headlines
+`afm-session-start.sh:46` extracts are **byte-identical**; the 22 paths A5 reads off
+`*Verification:*` lines are **byte-identical**; 47 `{{placeholders}}`, 151 `✅`/`❌`, 15 `arXiv`,
+2 `[TBD]`.
+
+Ten deliveries went through an adversarial verifier and **five were rejected**, all for the same
+class: a qualifier dropped to satisfy a word count. A conditional turned unconditional in the saga
+rule, *"or you said 'go'"* deleted from a trigger whose own headline still named it, *"only"* and
+*"and correct"* and *"against the approach"* removed. Each was restored by splitting the sentence
+instead of cutting the qualifier, which is what the gate asks for in the first place.
+
+### Consumer migration
+
+- **Consumer-facing.** `CONSUMER_VERSION` moves to `3.41.0`. `core/*.md` and `PRINCIPLES.md`
+  materialize into an instance.
+- **The delta worth taking is `PLUGIN-2`'s tiered verification** — if your project runs ESLint or
+  Biome with the no-explicit-any rule, that command becomes the trigger and the `grep` stops
+  producing false positives on identifiers that merely contain `any`.
+- **The STE rewrite is the plugin's own hygiene, and `update` will not force it on you.**
+  `ops/update.md:216` — *"update never deletes"* — so `update` materializes what your instance
+  lacks and never rewrites prose you edited by hand. Hard rule 35 is local to the plugin's
+  repository and is **not** materialized: your `docs/` is not subject to ASD-STE100 unless you
+  choose it.
+
+## [3.40.3] — 2026-09-04
+
+The resident surface stops carrying what is not resident-worthy. A skill's frontmatter is loaded
+into every turn; its body and its `ops/*.md` are read only when the skill runs. Procedure had
+accumulated in the wrong one of the two.
+
+This came out of an external audit of the plugin, whose telemetry was real and reproduced exactly,
+and whose conclusions did not survive measurement — see the release notes below for what was
+rejected and why.
+
+### Changed
+
+- **The 25 skill descriptions carry routing, not procedure.** Each one now states what the skill
+  writes or decides, then lists every trigger phrase under `Activates`. What left is execution
+  contract that already lives in `ops/*.md` and in the skill body: `specify`'s six overhead
+  thresholds, `diagnose`'s "Role: ANALYZER / does not open a gate / an empty diagnosis is valid",
+  and similar. Frontmatter goes from **11,010 to 9,804 chars** (~300 tokens per turn), and
+  `ste-lint --scope flavored` goes from **42 findings to 9**.
+
+  **No trigger phrase was removed**, and that is the assertion that matters: routability is what
+  `docs/adr/0012-*` certified with 100 eval trials, so touching it would mean re-running
+  `test/evals/`. A mechanical diff against the previous frontmatter confirms every quoted phrase
+  survives; three were *split* rather than dropped (`"clean up/reorganize the docs"` became two
+  explicit phrases), which is strictly more matchable.
+
+- **`plugin.json`'s description goes from 2,013 chars to 172.** It was a catalogue of the 25
+  skills — every one of which already ships its own resident description. That is hard rule 34
+  (a fact stated twice drifts, and the copy goes stale first), and it routes nothing: skills route.
+  ~460 tokens per turn.
+
+### Not changed, and why
+
+An external report proposed five cuts. Twelve agents tested them, one arguing for and one against
+each, and the measurements are in `docs/research/` if they are wanted later. The short form:
+
+- **Merging 25 skills into 5** — `docs/adr/0003-*` already built exactly that (router skills over
+  N operations) and reverted it: the router "hid the operations behind a router" and made
+  natural-language activation hard. ADR-0012 then certified the current shape with 100 trials.
+- **Removing the blocking `Stop` arm** — reflect ran 23 times, evolve twice, and the three ops
+  with no trigger ran zero. That is one measurement of 115 invocations, not three anecdotes.
+- **Silencing `PreToolUse`** — it costs **681 tokens per 1000 responses** in this repo against
+  5,098 in the audited sample, which is pinned at `3.5.0-rc.1`. The cost was fixed 35 releases ago.
+- **Cutting `SessionStart` to three lines** — every AFM hook together injected 61,635 tokens
+  against 560,987,629 read in the audited sample: **0.011%**. `afm-token-audit.sh` reports a true
+  per-1000-responses rate that invites a false comparison against per-turn context.
+
+### Consumer migration
+
+- **Consumer-noop.** `CONSUMER_VERSION` stays at `3.40.0`. Nothing materialized into
+  `<consumer>/docs/` changes; `skills/` and `.claude-plugin/` ship with the plugin copy and reach
+  an instance through `claude plugin update`.
+
+## [3.40.2] — 2026-09-04
+
+Three defects in `hooks/`, found by an adversarial pass over the eleven gaps left open after
+3.40.1. They share a shape: each mechanism reported a state it had not measured. One counted
+commits that never happened, one went quiet because the artifact it polled is written once, and
+both `Stop` arms printed an escape hatch neither of them read.
+
+### Fixed
+
+- **The commit event counted mentions.** The classifier was `case "$CMD" in *"git commit"*)` — a
+  glob over the command STRING, so any command that merely CONTAINED the text produced a
+  `task | commit` event: an `echo`, a heredoc, and (measured on 2026-09-04) a `grep` reading this
+  very line. That counter arms the reflect `Stop` arm, so every phantom pulled the cadence
+  forward. The substring stays as the pre-filter and **git is now the discriminator**: HEAD must
+  have moved within the last two minutes, and its SHA must not already be in the ledger — so a
+  mention right after a real commit resolves to the commit already recorded. The event now
+  carries the SHA it claims. Not `tool_response`: its field names are documented nowhere here and
+  `git commit -q` prints no success line, so a stdout pattern would trade false positives for
+  silent false negatives. Regression tests run in **both** directions — three real mention shapes
+  record nothing, and a real commit through `xargs`/`sh -c` with `-q` is still recorded.
+- **The reflect arm saturated.** It gated on the session file's `reflection:` field being empty.
+  That field is **write-once**: filled the first time and still filled ten days later, so a
+  resumed session was answered once and never asked again. Measured on this repository: **164
+  tasks against a threshold of 20** — eight crossings — and one reflection. The gate is removed
+  (and `afm_reflection_pending` with it — nothing else called it); what unblocks is the counter,
+  which falls when a real cycle lands on disk. That is still 0/1 over an artifact, and it is one
+  that moves. See [ADR 0024], which supersedes that one clause of ADR 0013 — and which states the
+  limit this inherits: `afm_count_since` compares dates at **day granularity**, so work done on
+  the same calendar day as a recorded cycle stays invisible to the counter until the next day.
+  That predates the change and bounds it; the motivating case (ten days, no cycle) counts fine.
+- **G2 counted sessions, not crossings.** One block per `session_id` is a lifetime allowance for a
+  session that never ends. The flag now carries the crossing index and the cycle epoch, so another
+  full threshold of work re-arms the block, and crossing 1 *after* a recorded cycle is a new event
+  rather than the one already answered. Applies to both arms.
+- **The reflect arm counted in the evolve window.** `afm_count_since deliverable evolve`, inside
+  `reflect_arm` — so the arm could block on a number that `/afm:reflect`, the remedy its own
+  message prescribes, cannot lower: only an evolve cycle resets that window. ADR 0020 already
+  required the opposite (*"the window belongs to the mechanism"*). The old `reflection:` gate hid
+  it by unblocking unconditionally; removing the gate exposed it, and an adversarial pass
+  reproduced the arm re-blocking on the very next `Stop` right after the operator complied.
+- **The `debt: true` escape hatch was prose.** Both arms print "add `debt: true` to the session
+  file's frontmatter" as their second path, and neither read the marker:
+  `docs/sessions/2026-08-25-1734-cb06b3.md` had carried it since 2026-08-25 and the evolve arm
+  blocked regardless. Now honoured, and **session-scoped** on purpose, unlike the crossing cap:
+  the cap bounds how often a mechanism speaks unprompted, while the marker is the operator having
+  answered, and re-asking at every threshold would be nagging against a declaration. The debt
+  stays visible — `afm-health.sh` reports it in every SessionStart digest.
+
+  A first draft of this marked the crossing as handled on the debt path, which made the
+  suppression **irreversible**: withdrawing `debt: true` left the flag on disk, the cap fired
+  before the marker was re-read, and the arm went silent for good on that crossing. The suite
+  passed, because the test cleared the flag in between — scaffolding the real hook never runs.
+  That is this repository's signature defect reproduced inside the fix for it. The marker is now
+  read before the cap and writes no flag, and the regression test asserts the withdrawal
+  **without** clearing anything.
+
+### Added
+
+- **`hooks/lib/afm-root.sh`** — one answer to *which root does this event belong to*.
+  `afm-pre-edit.sh` and `afm-capture.sh` each carried their own copy of the same three
+  `case "$PWD"/*` arms, and `docs/research/011-afm-em-monorepo.md` found the copies already
+  disagreeing with each other and with `tools/afm-detect.sh`; all four candidate monorepo designs
+  failed on that. A missing library falls back to an **inline** definition of the same functions,
+  never to nothing — an unset `afm_root` under `set -u` would collapse the guard's `"$_r"/*` arm
+  to `/*`, which matches every absolute path, and the hooks would act on other repositories while
+  every test still passed.
+
+  **This closes only half the gap, and says so.** Six of the eight hooks receive no file path at
+  all in their payload. That is a harness limit, not an AFM one, and no resolver can close it; the
+  federated monorepo designs stay blocked on it.
+
+### Consumer migration
+
+- **Consumer-noop.** `CONSUMER_VERSION` stays at `3.40.0` — nothing materialized into
+  `<consumer>/docs/` changes, and no instance needs `/afm:update`. Every change here is in
+  `hooks/`, which ships with the plugin copy and reaches an instance through
+  `claude plugin update`, never through materialization.
+- **One behavioural note for an operator running a long session.** A resumed session that used to
+  be asked for a reflection once will now be asked once per accumulated threshold. If that is not
+  wanted, the two declared ways to stop it are unchanged and both still work: `debt: true` in the
+  session file (now actually read), or `cadence: reflect=off` / `evolve=off` in `docs/_focus.md`.
+
+[ADR 0024]: ../../../docs/adr/0024-o-desbloqueio-da-reflect-e-o-contador-nao-o-campo.md
+
+## [3.40.1] — 2026-09-04
+
+The two fixes the monorepo research isolated as true regardless of which architecture is eventually
+chosen (`docs/research/011-*`). Neither needs an answer to the federated-versus-single question, so
+neither waits for one.
+
+### Fixed
+
+- **A stack detector selected the package that PRODUCES the scope.** The five dependency-based
+  `detect:` commands grepped the whole manifest, so a package whose own `"name"` matched the
+  pattern fired the module built for its consumers. Measured on one design system: **seven of its
+  packages** selected `vireya-ui` against themselves. Each detector is now a `jq` query scoped to
+  `dependencies`/`devDependencies`/`peerDependencies` — a `"name"` field is never inside those
+  three objects, so the self-match closes structurally rather than by a better pattern. Verified:
+  the package that only produces stopped matching, the two that genuinely depend on the scope
+  still match. Where `jq` is absent the command falls back to the previous `grep`, so a machine
+  without it keeps exactly today's behaviour and loses nothing.
+- **The stack scan stopped at the front door.** Both interviews ran each `detect:` once, at the
+  consumer root. A workspace root declares the tooling and none of the stacks, so the scan
+  answered "no stacks here" for a repository full of them: measured across the nine real JS/TS
+  workspaces in the operator's tree, **63 root-level probes, 63 empty**, while the same commands
+  fire correctly inside the packages — Next.js in seven different `apps/*`, tRPC in five places.
+  `bootstrap` and `refactor` now enumerate the manifests first and scan each, and both are told to
+  record **where** each stack was found: a stack present in one package out of eight is a true
+  finding and a different fact from one present throughout.
+
+### Consumer migration
+
+- **Consumer-noop.** `CONSUMER_VERSION` stays at `3.40.0` — nothing materialized into
+  `<consumer>/docs/` changes, and no instance needs `/afm:update`. What changes is which modules a
+  **future** `/afm:init` or `/afm:refactor` selects, and that is read from the plugin at the moment
+  it runs. An instance bootstrapped inside a workspace before this release selected no stack
+  modules at all; re-running the stack scan by hand is the only way to recover that, and the owner
+  decides whether it is worth it.
+
+## [3.40.0] — 2026-09-04
+
+Three defects with one root: the plugin declared as norm what it should have proposed, and
+proposed what it should have mechanized. Measured across 115 `/afm:*` invocations in 26 projects,
+`reflect` ran 23 times, `evolve` 2, and the three operations `evolve` conducts —
+`generalize`, `restructure`, `remediate` — ran **zero**. The cause was mechanical, not cultural:
+`reflect` had a blocking `Stop` arm and `evolve` had a printed suggestion. Separately, ~40% of
+`modules/` turned out to be one operator's house convention shipped under `(mandatory)`, and
+`core/` carried a literal `src/` in eleven places next to the placeholder that was supposed to
+replace it.
+
+### Added
+
+- **`reflect` escalates to `evolve`.** `ops/reflect.md` § 5 gains a step between the `promote`
+  branch and the `reconcile` handoff: when the findings cross categories, it proposes
+  `/afm:evolve` carrying the φ_b evidence already collected in §§ 1-2, never as a bare
+  suggestion. The discriminant is not new — `rubrics/when-to-evolve-methodology.md` already
+  defined it and declared `called_by: ["evolve"]`; `reflect` now consults it too. The recursion
+  guard is **declared**, not inherited: `evolve` runs `reflect §§ 1-2` only, so the escalation in
+  § 5 was already unreachable from inside the cycle — but that was accidental scoping, and there
+  was no recursion guard anywhere in `ops/` or `core/`.
+- **`patterns/`** — seven design patterns that answer a code smell. `type: pattern` with `smell`,
+  `when_to_use` and `when_not_to_use`; the last of those is what keeps a library from producing a
+  Strategy with one strategy. It only ever suggests: a pattern becomes norm when the operator
+  accepts it and it materializes into `code-style/`, `ach.md` or an ADR. Excluded from PLUGIN-40
+  for the same reason `rubrics/` is — illustrative paths produced 44 false findings there.
+- **`code-style/`** — the conventions the operator decides, as opt-in seeds.
+  `code-style/<stack>/<concern>.md` plus `code-style/_any/` for what belongs to no stack. A
+  directory-unit family like `modules/`, so it reuses the index's existing one-level descent. The
+  interview asks item by item and does not write what the operator declines.
+- **Both families join `INDEXED`** in `tools/afm-index.sh` and in the `PLUGIN-39` gate.
+  `--triggers` emits one `code-style` row per stack, not one per file, and a `pattern` row
+  carrying its smell.
+
+### Changed
+
+- **`EVOLVE_EVERY` stops being decorative.** It was read in exactly one place,
+  `afm-health.sh`, which built a string and printed it at `SessionStart`. `afm-session-end.sh`
+  read the cadence triple and **discarded** the evolve value — the underscore in
+  `read -r REFLECT_EVERY _EVOLVE_EVERY REFLECT_TASKS` marked the discard as deliberate. It now
+  has its own blocking arm, with its own one-block-per-session flag, its own `off` switch, and
+  the same debt escape hatch the reflection arm carries. A gate that starts red is switched off
+  the next day.
+- **The stack modules stop imposing.** House convention moves out of all seven and into
+  `code-style/` seeds: naming prefixes, test placement, folder layouts, an arbitrary 80-line
+  ceiling with no measurement behind it, an invented helper at an invented path, and — the worst
+  case — four fully-qualified file paths plus six identifiers from one product's billing module.
+  Genuine stack fact stays: the `<html lang>` dynamic-segment constraint in Next.js, Stripe's
+  `SubscriptionSchedule` immutability, `ctx.run.id` changing per retry attempt, the Prisma
+  optimistic-locking pattern, the Vireya token system. The three `gotchas.seed.md` files were not
+  touched — they measured ~95% genuine.
+- **`core/` paths become `{{src-path}}`.** Eleven literals in `core/afm.md` and `core/ach.md`,
+  and the equivalent sites in `rubrics/`, `templates/` and `interview/`. The archaeology table in
+  `interview/refactor.md` keeps its literals on the left — that column is how brownfield detection
+  recognizes a project — and parameterizes only the right, which emits the consumer's text. The
+  interview gains a measurement step for `{{src-path}}`, `{{domain-path}}` and `{{ext}}`, which
+  had no filling step in any op: a placeholder nobody fills fails silently, which is worse than a
+  wrong literal.
+- **`core/protocol.md` stops disagreeing with the code.** It declared `REFLECT_TASKS` default `4`;
+  `lib/afm-cadence.sh` has hardcoded `20` since 3.9.0-rc.9, with a measurement behind it. The doc
+  now matches the code, and the `EVOLVE_EVERY` row names its new consumer.
+
+### Fixed
+
+- **The interviews stopped naming rubrics by hand.** `bootstrap.md` and `refactor.md` each
+  hardcoded eight rubric filenames; twelve ship. Four rubrics had never been materialized into any
+  instance this framework bootstrapped. Both now query the index, the way the module list was
+  fixed in 3.31.0.
+- **`learning.template.md` and `procedure.template.md` emitted `kind:`**, a retired key the
+  `PLUGIN-39` gate rejects. Two templates were generating documents that failed the project's own
+  gate.
+- **`--for` could not read a `trigger_path` holding more than one glob.** Five ADRs write the
+  value as a whitespace-separated list, and `cmd_for` handed the whole string to the matcher as
+  ONE pattern, so it matched nothing: `--for plugins/afm/hooks/hooks.json` returned empty while
+  ADR-0004 declared exactly that path. Those five were unreachable through the routing the
+  frontmatter had just given them — a silent miss.
+- **`--type protocol` printed every protocol twice.** `templates` and `templates/protocols` are
+  both in `INDEXED`, and the one-level descent added for `modules` re-emitted what the deeper
+  entry already emitted. The descent now skips a subdirectory that is itself an `INDEXED` entry;
+  the `PLUGIN-39` gate carried the same overlap and would have reported one finding as two.
+- **The unit cache could suppress a body that was never delivered.** `afm-pre-edit.sh` marked a
+  gotcha or rule as seen while assembling the payload, but three later exits can still discard
+  it — so editing a Portuguese code file marked the rule body, delivered only the language line,
+  and answered the next edit with `(already delivered this session)` for something the agent had
+  never received. Marking is now deferred until the payload has actually left. This cache exists
+  to stop repetition, never to cause silence.
+- **`--triggers` printed every feature's full path list**, which made `feature` the largest family
+  in the index at 4,218 bytes and pushed the whole output to 2.55× its previous size — against a
+  ratio that is the index's entire reason to exist. The row now carries the path count and points
+  at `--for`, which answers the question by matching instead of making the reader scan. A feature
+  with no paths still gets no row at all.
+- **The index cost claim was stale in three places** (`CLAUDE.md`, `docs/prd.md`, the SessionStart
+  injection). It advertised ~2,200 tokens against ~35,000 of bodies; measured today it is ~3,700
+  against ~214,000. The ratio improved and the number was wrong, which is its own defect: the
+  claim is what convinces a reader to query instead of read.
+- **`afm-detect.sh` shipped an unused second rubric directory.** `RUBRIC_DIR2` had no caller, no
+  test, and no guard against being set to the same path as the first, which would have doubled
+  every match against the cap. Removed — YAGNI.
+
+### Consumer migration
+
+- **Consumer-facing.** `CONSUMER_VERSION` moves to `3.40.0`.
+  **This release carries two changes the bump table classifies as major** — a change in `core/`
+  and a move inside `framework-template/` — under a minor number, because `4.0.0` is reserved for
+  a paradigm change. The reason is recorded in `docs/adr/0023-*`; the bump table is not amended.
+  **No existing instance changes when this lands.** `ops/update.md` forbids removal and never
+  rewrites materialized content, and a module patch is applied once at bootstrap by an agent
+  reading prose — there is no re-application path. What changes is what a **new** bootstrap
+  materializes.
+  **What became obsolete, for an instance that wants to act on it:** the naming, test-placement,
+  file-size and import conventions that arrived from `modules/<stack>/` as `(mandatory)` are no
+  longer shipped as norm. An instance that wants them keeps them — they are its own now, and the
+  decision is recorded where the operator can see it rather than inherited from a `grep` on
+  `package.json`. An instance that never wanted them can delete them; `update` will not, because
+  deleting instance content is destructive and destructive is a bright line.
+  New instances receive `patterns/` and `code-style/`; the latter is offered item by item and
+  writes nothing the operator declines.
+
+## [3.31.0] — 2026-09-03
+
+Measured, on 79 sessions across 26 consumer projects, what release 3.30.0 did to the token
+bill. The frontmatter index worked: document text pulled into context fell 20% per 1000
+responses, and re-reading the same document inside one session fell 74%. A hook ate the win.
+`PreToolUse` injections went from 41.1 to 67.1 per 1000 responses (+63%) and from 14,565 to
+19,304 tokens per 1000 (+33%), because the structural migration split `gotchas.md` into 29
+files and `afm.md` § 3 into 15, and the dedup cache keys on the FILE — so one gotcha body was
+re-sent once per edited file. This release closes that leak, extends the index to the families
+it could not see, and versions the instrument that measured all of it.
+
+### Added
+
+- **`hooks/lib/afm-text.sh`** — `afm_truncate`, one word-safe truncation for what were ten
+  copies of `head -c` across three hooks. A real session received injected text ending in
+  "659 e": the byte cut lands mid-word, and mid-character on accented text. The helper backs
+  off to the last word boundary and repairs a severed UTF-8 sequence with `iconv -c`. Each
+  caller carries a no-op fallback, because the hook contract is "never break the session" and
+  a missing lib would otherwise be a hard "command not found".
+- **`tools/afm-token-audit.sh`** — reads the Claude Code transcripts and reports responses,
+  context per turn, and hook injection cost normalized per 1000 responses. It encodes four
+  measured facts, each next to the code that depends on it: `message.id` repeats, so the naive
+  sum inflates output 2.2×; `output_tokens` in a subagent transcript is a partial streaming
+  snapshot and unusable; the authoritative subagent figure exists only as text in the harness
+  notification; and hook injections live in `attachment.stdout`, not in message content. When
+  the figure is absent it reports `unavailable` and never estimates.
+- **Frontmatter for the seven stack modules.** `modules/<stack>/*.md` was the last family the
+  plugin shipped with none: 17 files that `promote` routes findings to (`target:
+  modules/<stack>/`) and that `bootstrap` selects from, where the only way to learn a module
+  existed was to list the directory. Each now carries `type: module`, `stack:`, `patches:` and a
+  `detect:` block scalar — one mechanical command per stack, verified against real consumer
+  repositories. `modules` joins `INDEXED` in the index and in the `PLUGIN-39` gate, and
+  `--triggers` emits ONE row per stack rather than one per file, because the three files of a
+  stack are applied together and share one `detect:`.
+- **Routing frontmatter for five document families.** `features` gain `status`, `for_paths`,
+  `us`; `adr` gains `status`, `trigger_path`, `superseded_by`; `research` and `protocols` gain
+  `fires_on`/`fires_when`, plus `consumed_by` for a dossier something already used; `evolution`
+  gains `status` only. `--triggers` emits them and `--for` matches through `for_paths` and
+  `trigger_path`. Before this, `afm-index.sh --for plugins/afm/hooks/afm-pre-edit.sh` returned
+  nothing while a feature spec, an ADR and a research dossier all governed that file.
+
+### Changed
+
+- **`afm-pre-edit.sh` deduplicates by CONTENT, not only by file.** A gotcha, rule or policy
+  body already delivered in this session emits a one-line pointer instead of the body. The key
+  is a hash of the emitted text, never `path+mtime` — `git checkout`, stash and rebase reset
+  mtime without changing content, and that key would suppress a body that is genuinely
+  different. It stays a pointer rather than going silent, because a mechanism that fails by
+  silence is this project's most expensive defect: the gotcha is relevant again 300 turns
+  later, when the body has scrolled out of attention. Rubric rows and the legacy monolith
+  branches are deliberately out of scope.
+- **`SessionStart` no longer re-injects on resume.** It fired on `startup`, `resume` and
+  `compact` — 1.43 injections per session against 0.88 before — re-sending about 1141 tokens
+  already resident. The matcher now reads `startup|clear|compact` and the script itself
+  branches on the payload's `source`. Both layers, deliberately: `test/run.sh` invokes the
+  scripts directly and never through `hooks.json`, so a matcher-only fix would ship with no
+  coverage. `compact` keeps injecting — the summary may not carry the doctrine.
+
+### Fixed
+
+- **`interview/bootstrap.md` named six stack modules while seven shipped.** `vireya-ui` existed
+  in the plugin and no bootstrap could ever select it, because the prose that listed the modules
+  was not the directory that held them. The step now reads the index instead of a hand-written
+  list.
+- **Hard rule `PLUGIN-36` failed the tree over its own evidence.** It excluded `docs/sessions/`
+  as a machine-written append-only record and missed the two siblings, `docs/.afm-log/` and
+  `docs/.afm-log-failures/`. On 2026-09-03 the CRITIC hook recorded a failing command verbatim —
+  the point of the record — and the absolute path inside that command failed the gate. Rewriting
+  the record to satisfy the rule would destroy what the record exists to hold, and rules 17/18
+  forbid rewriting either substrate.
+- **A Portuguese write to a code file burned that file's rule injection for the whole
+  session.** The per-file flag was written unconditionally, then `LANG_EMITTED` discarded the
+  whole payload, so every later edit of that file — English ones included — hit the cache and
+  received nothing. The flag now means "delivered", not "attempted". The regression assert is
+  the one that proves it: Portuguese write, then English write of the same file, must deliver.
+
+### Consumer migration
+
+- **Consumer-facing.** `CONSUMER_VERSION` moves to `3.31.0`. Two deltas reach a materialized
+  instance: the five templates now seed the routing keys so a new document is born routable,
+  and `docs/tools/` gains `afm-token-audit.sh` where the instance materializes tools. The new
+  frontmatter keys are **optional** in the `PLUGIN-39` gate — making them required would break
+  every instance pinned below 3.30.0 in one release. An instance may run `/afm:update` and
+  backfill its own documents when it chooses.
+
+## [3.30.0] — 2026-08-30
+
+Closes the AFM 4.0 line. Seven of its ten phases had shipped, one was cancelled by its own
+evidence, and what remained turned out not to be a major. Feature
+`docs/features/010-close-the-v4-line/`.
+
+### Why this is 3.30.0 and not 4.0.0
+
+`4.0.0` was a major because of F4 — consolidating and removing operations, the one change in this
+plugin that breaks a materialized instance. `docs/adr/0012-*` removed that input with 100 eval
+trials: all seven zero-usage operations score 5/5 on sonnet, so none is removed. What was left
+renames nothing, removes nothing, and breaks no reference. A version number describes what a
+release does to whoever depends on it, and this one adds a hook.
+
+### Added
+
+- **`hooks/afm-capture-op.sh` — the ledger records WHICH OPERATION ran.** A `PostToolUse` hook on
+  matcher `Skill` appends `- [ISO] op | s=<sid6> | afm:<name>`.
+
+  It exists because ADR-0012 stated its own limit in the same breath as its verdict: a synthetic
+  eval measures **routability**, never **organic frequency**, and merging two operations depends on
+  the second question. The ADR named the event ledger as the only source that could answer it.
+  Measured on 2026-08-30, that ledger held **659 events** and `grep 'afm:'` across all of them
+  returned **zero** — it recorded the artifact written, never the operation that ran. The clock the
+  ADR said to wait for had never been wound.
+
+  Three properties are load-bearing. It records **`afm:*` only** — counting another plugin's skill
+  would poison the ratio the event exists to produce. It records the **invocation, not the
+  outcome** — an operation that ran and failed still answers "was it reached". And `op` joins the
+  ledger's closed vocabulary as a **telemetry** kind, so `reconcile` filters it out alongside
+  `task`/`deliverable`/`failure`. **No reader ships with it:** a counter over four events would
+  invite exactly the conclusion ADR-0012 warned against.
+
+  The design turned on one unknown — does `PostToolUse` fire for the `Skill` tool? It was probed
+  with a throwaway plugin and `claude -p --model haiku` before a line of the plan depended on it
+  (#2). It fires, and `tool_input.skill` carries the qualified name.
+
+### Changed
+
+- **`CLAUDE.md` of this repository: 26,878 → 6,850 characters.** Criterion #5 of the v4 intent said
+  the resident cost must not grow. The skill listing obeyed it (14,182 → 10,264 when `when_to_use`
+  was merged away); this file went the other way and became the largest resident block in the
+  project, larger on its own than the listing of all 25 skills. The criterion applied was
+  duplication, never a character target: every block that `/docs` already held became a one-line
+  pointer, and what has no other home — the machine-local install state, the credential map, the
+  `{{placeholder}}`/`[TBD]` conventions, the three asymmetries that look like drift — stayed. One
+  whole section described `.creator/`, a directory that no longer exists.
+
+- **The 80% prune, on the four densest files** (`core/afm.md`, `ops/{deliver,evolve,update}.md`).
+  Yield: **2,254 characters of about 141,000 — 1.6%** — and the number refutes the premise the v4
+  intent wrote the prune on. Those files are not full of generic prose; measured block by block,
+  almost everything carries a number, a counter-example or a paid bug, which the plan's own
+  guardrail forbids cutting. What did come out was **rule-34 drift**, not verbosity: `deliver.md`
+  § 3.B.1 restated the whole `core/afm.md § 2` loop, `evolve.md` said "never the plugin" three
+  times, and `core/afm.md § 1.2` restated the Pragmatic-Programmer canon whose two load-bearing
+  halves already lived at their point of use.
+
+### Fixed
+
+- **Two dead cross-references inside hard rules' own verification lines.** `PLUGIN-1` and
+  `PLUGIN-21` handed their judgment half to "§ 5.1" — the GREEN-fails retry loop nested under § 2 —
+  when the section they meant is § 5, *Signs you are off-track*. Same family as `PLUGIN-40`: the
+  writer moved and the reader did not.
+
+- **`docs/adr/0012-*` cited a path no clone had.** The two v4 dossiers sat at the repository root,
+  uncommitted and outside `docs/`, where no rule covered them. They are now
+  `docs/research/008-afm-v4-intent.md` and `009-afm-v4-phased-plan.md`, with the OKF frontmatter,
+  and the citation resolves.
+
+### Consumer migration
+
+- **Consumer-noop.** Nothing materialized into `<consumer>/docs/` changes, so `CONSUMER_VERSION`
+  stays where it is and no instance needs `/afm:update`. The new hook lives in
+  `plugins/afm/hooks/`, which travels with the plugin install and not with the instance: a
+  consumer that updates the plugin gets the `op` event on its next session, and one that does not
+  keeps working exactly as before with the ledger it already had. Nothing is renamed, nothing is
+  removed, and no reference changes.
+
+## [3.22.0] — 2026-08-30
+
+Closes the known gaps that were open work rather than defects. Feature
+`docs/features/009-app-facing-language/` plus the reconciliation of feature 003.
+
+### Added
+
+- **`prd.md § 11.1` — the app-facing string language.** Hard rule `PLUGIN-37` says the prose of an
+  artifact is English, and it has exactly one exception: the strings a product shows its own users
+  are a product decision. Measured on 2026-08-30, that exception existed on **no surface a machine
+  can read** — `grep` across `core/prd.md`, both interviews, `triggers.md` and `ops/update.md`
+  returned zero.
+
+  The gap has a direction. A language migration could not tell an artifact from a product string,
+  so it would translate the UI, and `git revert` does not give a user back the screen they saw.
+  See `docs/adr/0022-*`.
+
+- **`ops/update.md § 1.6` — the language migration step.** The order is normative: read
+  `prd.md § 11.1`, derive the excluded scope from it, and only then read a file. Scan-then-skip
+  makes the exclusion depend on the agent noticing during the work. `[TBD]` or an absent section
+  stops the step and asks. It never picks a language.
+
+- **The interview asks it.** One closed question inside `bootstrap.md` step 0 (recommendation-first,
+  `[TBD]` accepted) and `refactor.md` C.9.3b, which scans the UI strings the code already carries
+  and offers what it found first (#2).
+
+- **`triggers.md` — a `reconcile` signal** for an artifact written in another language. It reads
+  § 11.1 **before** it fires, so it can separate a violation from the declared exception.
+
+### Fixed
+
+- **`afm-health.sh` A2 over-counted markers.** The filter excluded a backtick immediately before
+  the marker, which only catches `` `[TBD]` `` written alone. It missed every longer code span, so
+  `` `grep [NEEDS CLARIFICATION:]` `` and `` `protocol: [TBD]` `` counted as open gaps. On
+  2026-08-30 the hook reported 5 open markers and all five were docs quoting the notation. The
+  filter now strips inline code spans before it counts. A counter that reports work nobody has to
+  do is read once and then ignored, which costs the same as reporting zero.
+
+- **Three ops named the OLD Portuguese guardrail frontmatter keys.** `rule.md` and `remediate.md`
+  still instructed the writer to fill `origem:`, `superficie` and `custo`, renamed to `origin:`,
+  `surface:` and `cost:` in the schema rename. The writers moved and these readers did not — the
+  same shape the 3.20.0 and 3.21.0 defects had.
+
+- **29 `block` findings in `ste-lint --scope strict`** across 7 op files (26 S1, 2 S4, 1 S3), the
+  acceptance check of feature 003 phase B that had never been run. Now 0 across all 48 skills and
+  ops.
+
+### Changed
+
+- **Six ops link to `PRINCIPLES.md`** where they cite an invariant principle. This clears the
+  `34 ops` ratchet row, carried since 2026-08-22.
+
+### Consumer migration
+
+- **`prd.md` gains § 11.1, "App-facing string language".** Add it after § 11 with the value
+  `[TBD]` unless you already know the answer. An instance without the section is treated exactly
+  like `[TBD]`: the migration asks instead of assuming.
+- Nothing else in a materialized instance changes. The interview, `triggers.md` and
+  `ops/update.md` are plugin surfaces.
+
+## [3.21.0] — 2026-08-30
+
+The first full `/afm:evolve` cycle this instance has ever run. Report:
+`docs/evolution/2026-08-30-005.md`.
+
+### Added
+
+- **Hard rule `PLUGIN-40` — a normative doc cites no path that does not exist**, with its runner
+  in `tools/gate/core-rules/`. It promotes the `diagnose` A1 axis from a SessionStart report into
+  a commit-time refusal. The axis had detected the defect that same day and reported it; the
+  report was read and the work continued. Detection at the start of a session and refusal at the
+  commit are not the same event, and only the second arrives while the change is still in the
+  hands of whoever made it.
+
+  The scope is the normative families only — `afm.md`, `ach.md`, `prd.md`, `ust.md`, `_focus.md`,
+  `adr/`, `rules/`, `gotchas/`, `learnings/`, `guardrails/`, `procedures/`. Pointed at every doc
+  it produced 44 findings that were all correct notation: a rubric teaches with an illustrative
+  path, a research dossier quotes a hypothetical one, a feature's `tasks.md` names paths as they
+  were. A gate that starts red is switched off the next day.
+
+  A cited path resolves **from the repository root OR from the directory of the file that cites
+  it**. Both conventions are alive in a real instance, and a checker that knows only one invents
+  findings — the same end as a gate that finds nothing, reached from the other side.
+
+### Fixed
+
+- **Seven rule files named a `*Verification:*` target that had just moved.** 3.20.0 updated the
+  link and left the visible label saying `test/rules/<n>-*.sh`. The reader was sent to a file
+  that does not exist. The same rename defect the release was about, one layer down.
+- **`PLUGIN-37` was invisible to the phantom-gate check.** Its header read
+  `*Verification (two moments, one measurement):*`, which is not a surface keyword, so
+  `rule_surface` answered `agent` — for that rule and no other. Deleting its runner would have
+  left the audit green.
+- `CLAUDE.md` still said "hard rule 37" after the id became `PLUGIN-37`.
+
+### Documentation
+
+- `docs/learnings/uma-asercao-de-regressao-vale-contra-o-codigo-antigo.md` — a regression
+  assertion is worth nothing until it has been run against the OLD code and gone red. Written
+  after two fixtures went green against the broken code on 2026-08-30, both because they used the
+  new file-name shape against the old parser. Injected by path match on `test/**`.
+
+### Consumer migration
+
+`/afm:update` copies the `PLUGIN-40` runner and materializes the rule into `afm.md § 3`. Run
+`guardrails.sh --baseline` afterwards: an instance with historical citations starts with declared
+debt instead of a red gate. Three such rows exist in this repository, each with its reason — two
+ADRs and one user story that quote a path **because** it stopped existing.
+
+## [3.20.0] — 2026-08-30
+
+The plugin shipped rules it never shipped runners for. A consumer's `afm.md` stopped at rule 21.
+
+The version jumps from 3.13 to 3.20 on the owner's call: the change is large, and 4.0.0 is
+reserved for the v4 line.
+
+### Added
+
+- **`tools/gate/core-rules/` — seven runners that travel with the plugin.** `PLUGIN-13` secrets,
+  `PLUGIN-21` code language, `PLUGIN-35` gate completeness, `PLUGIN-36` absolute path,
+  `PLUGIN-37` prose language, `PLUGIN-38` parser marker, `PLUGIN-39` OKF frontmatter. They
+  enforce the contract of the `docs/` AFM materializes, which is not something a consumer
+  chooses. `core/afm.md § 3` gains the text of `PLUGIN-35` to `PLUGIN-39`; until now those five
+  rules existed only in the plugin's own repository. `PLUGIN-35` was the sharpest case: it
+  demands a versioned runner behind every 0/1 trigger, and it shipped as prose with no runner.
+- **`ratchet_exempt`** in `gate/lib/ratchet.sh`. An exemption is a row whose count column is the
+  literal `exempt`, not a budget of zero. It moves a path exclusion out of a `case` arm inside a
+  runner — where only one repository could have it, and no reviewer would see it — into a
+  versioned table.
+- `--core-rules` on the aggregator, plus `AFM_GATE_CORE_RULES` and `AFM_GATE_REPO`.
+
+### Changed
+
+- **Two namespaces replace the reserved number range** (ADR 0021). `PLUGIN-<n>` is a rule the
+  plugin ships; a plain `<n>` is a rule this project wrote about its own code; 100+ stays the
+  organisation policy. `core/afm.md` used to reserve 18-29 and tell a project to start at 30 — a
+  promise about numbers that was already broken, since this repository had spent 35-39 on rules
+  that turned out to be universal. Seven parsers now read `(PLUGIN-)?<n>`: the aggregator's
+  `rule_number`, `rules_declared` and `rule_surface`, `afm-session-start.sh`, `afm-pre-edit.sh`,
+  `afm-migrate-okf.sh` and `afm-index.sh`.
+- `gate/rules/README.md` no longer says the directory is empty on purpose without qualification.
+  It names the two classes and points at `core-rules/`.
+- `interview/{bootstrap,refactor}.md` and `ops/update.md` materialize `core-rules/` and the
+  `PLUGIN-` renaming of the inherited rules.
+
+### Fixed
+
+Four defects that only appeared once the shipped runners actually ran. Each had been reporting
+green.
+
+- **The runner glob `[0-9]*.sh` never matched a namespaced name.** The whole `core-rules/`
+  directory was invisible to the aggregator, and a glob that matches nothing reports nothing.
+- **`rule_surface` had read only `afm.md` since the 3.9.1 split**, where § 3 became an index and
+  the `*Verification*` lines moved into `rules/*.md`. It answered `agent` for every rule, so the
+  phantom-gate branch could never fire. Deleting a runner produced no finding at all — from the
+  one check whose purpose is to catch a rule that promises a gate nobody runs. It now reads both
+  layouts, inline first.
+- **A nested aggregator call re-resolved the rule directories from the defaults.** `PLUGIN-35`
+  invokes the aggregator, and the nested run reported every shipped rule as a phantom gate — a
+  failure invented by the check itself.
+- **An `exempt` row acted as a region with a budget of zero**, so it absorbed every finding under
+  that path and failed there instead of skipping it. The exemption became its opposite.
+
+Also: every runner derived the repository as `$(cd "$(dirname "$0")/../.." && pwd)`, correct only
+while it sat two levels below the root. Five levels down that pointed at `tools/`, and
+`PLUGIN-37` reported "cannot be decided" against a file that was right there. They read
+`AFM_GATE_REPO` now, and `PLUGIN-35` resolves the aggregator through `$0` instead of a repository
+path.
+
+### Consumer migration
+
+Run `/afm:update`. It copies `gate/core-rules/`, materializes `PLUGIN-35` to `PLUGIN-39` into
+`afm.md § 3`, and renames the inherited rules into the namespace — the number in the index, the
+`rules/<n>-*.md` filename, the `rule_number:` frontmatter and the ratchet `rule` column move
+together. An instance that has already written its own rule 35 keeps it: the namespaces do not
+collide.
+
+## [3.13.0] — 2026-08-30
+
+`/afm:evolve` had never run once. Three defects, and each one alone was enough.
+
+The owner named the diagnosis correctly: a mechanism that never fires is not a fact about
+one repository, it is a defect in the plugin. All three were measured in the plugin's own
+instance before anything was changed.
+
+### Fixed
+
+- **The capture substrate was blind to an edit made with Bash.** `afm-capture.sh` handled
+  `tool_name == "Bash"` by looking for `git commit` and then exiting, unconditionally, before
+  ever reaching the branch that classifies `tool_input.file_path`. Every document written with
+  `sed -i`, a heredoc, `tee`, `cp` or `mv` was invisible. The cost was not a missing log line:
+  the `deliverable` transition that gates the whole cadence is emitted from that branch.
+  Measured: features 006, 007 and 008 closed 80 tasks and produced **zero** `feature-tasks`
+  events, and the ledger held **2** `deliverable` events across **7** closed features.
+  The classification is now one function with two callers (rule 34). The Bash branch extracts
+  write TARGETS — anchored on a write verb, then filtered to paths under `docs/` that exist on
+  disk — so `grep -rn foo docs/afm.md 2>/dev/null` still emits nothing.
+
+- **`reflect` starved `evolve` through a shared cadence window.** Both write into
+  `docs/evolution/`, and the counter read "the newest file in that directory" as "the last
+  cycle" for both. `reflect` runs every N tasks and drops a report there; `evolve` needs N
+  deliverables accumulated *after* the last cycle. So every `reflect` run reset the `evolve`
+  window, and the threshold was unreachable by construction. The disk showed the exact
+  outcome: five reports, all five from `reflect`, `evolve` never. Each report now declares
+  `mechanism:`, and `afm_count_since <kind> [mechanism]` scopes the window to that mechanism's
+  own last report.
+
+- **The report selector ordered by ordinal before date.** The name was `NNN-YYYY-MM-DD.md` and
+  the selector was `sort | tail -1`. Two `001-*.md` already existed, so a low ordinal on a
+  recent date rewound the window in silence. The name is now `YYYY-MM-DD-NNN.md`, the ordinal
+  is only a same-day tiebreak, and the reader accepts both shapes during migration.
+
+- **A section title in the hooks smoke test ran a command.** `sec "… swept into \`doc\` =="`
+  put backticks inside a double-quoted string, so the harness executed `doc` and printed
+  `command not found` while the title came out blank. It never failed a test, which is why it
+  survived.
+
+### Added
+
+- `tools/afm-migrate-okf.sh --evolution` — the structural migration. It renames to date-first,
+  reads the mechanism out of the report's own prose, and **refuses to guess**: a report that
+  does not say what wrote it is reported and left alone, and the command exits non-zero
+  (#5). Live pointers in `docs/` move with the file; `docs/.afm-log/` is append-only (rule 18)
+  and is left exactly as it was written.
+- 10 assertions in `plugins/afm/hooks/test/run.sh` (171 → 181), one per defect, with legacy
+  `NNN-YYYY-MM-DD` fixtures. The first draft of the D2/D3 fixtures used the **new** name shape
+  against the **old** parser and went green against 3.12.2 — proving nothing. That is the
+  "verifier that measures the near thing instead of the right thing" family this repo has
+  already recorded; the fixtures were rebuilt to be genuinely red.
+
+### Changed
+
+- `templates/evolution-report.template.md`, `ops/{reflect,evolve,restructure,generalize}.md`:
+  `mechanism:` is mandatory in the report frontmatter, and the name is date-first.
+- `ops/evolve.md`: the cooldown and the resumability check now read the newest report **with
+  `mechanism: evolve`**, not the newest file in the directory.
+
+## [3.12.2] — 2026-08-29
+
+Feature 008, item 9. English, and the debt that was never going to be paid.
+
+### Changed
+
+- **`CLAUDE.md`, `README.md` and `guide/tutorial_afm.md` are English under STE.** `CLAUDE.md` is
+  the one that mattered: every agent session in this repository reads it, and it published rule 37
+  while breaking it. It was translated sentence by sentence rather than rewritten, so no caveat was
+  traded for brevity.
+- **The ratchet learned to say `declared` instead of `debt`.** A note that opens with `PERMANENT:`
+  is a declaration, not a debt. Two regions qualify by their nature, not by their size:
+  `docs/sessions` is episodic history that only grows, and translating a past session rewrites a
+  record. `test/evals` holds fixtures that simulate a consumer's `/docs`, and the assertions match
+  their content, so translating without touching the assertion is the failure the fixture exists to
+  catch.
+
+  Carrying those as debt forever made the debt list mean less every time it was read. The count is
+  still the ceiling, so a real increase is still caught.
+
+- The root region drops from 5 to 2. What remains is `afm_v4_idea.md` and `afm_v4_plan.md`, 16,607
+  words of planning dossiers that are not a reading surface. Declared, not hidden.
+
+### Notes
+
+- **Consumer-noop.** Nothing a consumer materializes changed. The ratchet convention travels with
+  the gate, and an instance with no `PERMANENT:` note behaves exactly as before.
+
+## [3.12.1] — 2026-08-29
+
+Feature 008, item 8. The cadence, and the defect that made its number fiction.
+
+### Fixed
+
+- **A GENERATED file poisoned the cadence counter.** `afm_count_since` picks the last evolution
+  cycle with `ls docs/evolution/*.md | sort | tail -1`. Since 3.9.1 an `index.md` is generated into
+  every directory, and `index.md` sorts after `004-2026-08-25.md`. The date extraction then yields
+  nothing, and the counter silently switches from "since the last cycle" to "since the beginning of
+  time".
+
+  **Measured: it reported 222 tasks overdue against a real 150.** That number was read as "the
+  cadence has been ignored 55 times" and nearly bought a threshold change on its own.
+
+- **Three more globs had the same poisoning**, all introduced by the generated index: axis A7
+  counted the indexes into the doc-to-code ratio, the rule-trigger extractor read `rules/index.md`,
+  and this repository's own rehearsal counted protocol presets. `index.md` and `log.md` are OKF
+  RESERVED names (SPEC v0.2 §3.1), never concept documents, and every glob that assumes otherwise
+  is wrong the same way.
+
+### Changed
+
+- **The reflection cadence threshold is 20, and the measurement is beside it.** Tasks closed per
+  session in this repository: **8, 17, 18, 29 and 150 — a median of 18.** The old default of 4 came
+  due four times inside a median session, and G2 caps the mechanism at ONE block per session, so
+  the threshold was saturated by construction. It blocked every session that did any work, which
+  reads as noise and gets ignored.
+
+  20 is one median session of work. Change it when the pace changes, and put the new measurement
+  next to it — a threshold with nothing behind it is what this replaced.
+
+- **The threshold lived in four places**, and only two of them had been found before: the key
+  default, the reader's initial value, the out-of-range clamp, and the fallback in each of the two
+  hooks that read it. Same shape as the `core.hooksPath` misread of 3.11.4. When a value has many
+  readers, changing one is changing none.
+
+### Notes
+
+- `hooks/test/run.sh`: 170 → 171 assertions, including one that proves a generated index cannot be
+  mistaken for the last cycle.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.12.1).** An instance that materialized indexes
+  has an under-counting cadence. After this update its counter reads the real number, which may be
+  higher than what it was reporting.
+
+## [3.12.0] — 2026-08-29
+
+Feature 008, item 6. The structural migration has a rehearsal.
+
+### Added
+
+- **`test/update-rehearsal.sh` rehearses the 3.9.1 structural migration** on a second, disposable
+  consumer built in the pre-3.9.1 shape. The fixture carries the shapes that broke the tool: a
+  heading with a colon, one with a double quote, an entry with no `**Trigger:**` line, rule bodies
+  inside section 3, and `kind:` frontmatter.
+
+  It runs the documented sequence from `ops/update.md` § Structural migrations and asserts the four
+  failures this migration actually produced. **A rehearsal that asserts success proves nothing.**
+
+  | Assert | The defect it catches |
+  | --- | --- |
+  | no entry is lost, in or out | the count guard the script claims |
+  | no rule body survives in section 3 | 3.11.3 — the split left every rule in two places |
+  | every frontmatter parses as YAML | 3.10.1 — a colon in a heading made a file unreadable |
+  | `--check-index` returns 0 | rule 39 fails on a missing index, so a skipped `--materialize` lands the operator red |
+
+  **Both were reintroduced on purpose and both turned it red.** An assertion never seen failing is
+  an assertion nobody has tested — which is how `--check-index` spent hours verifying itself.
+
+- `ops/update.md` says the rehearsal exists and what it answers. A unit test in `tools/test/run.sh`
+  asks whether one command behaves. The rehearsal asks whether an operator who follows the page
+  ends with a correct instance.
+
+### Notes
+
+- The rehearsal went from 11 to 22 assertions.
+- Writing it, the repository's own gotcha 004 bit: a backtick inside a double-quoted string became
+  command substitution. The gotcha exists, and it still catches the person who wrote it down.
+- **Consumer-noop.** No file a consumer materializes changed.
+
+## [3.11.6] — 2026-08-29
+
+### Fixed
+
+- **`ops/evolve.md` said five mechanisms and its `composes:` listed six.** Both were right, and the
+  fix was not a number. `diagnose`, `reflect`, `generalize`, `restructure` and `remediate` are the
+  mechanisms. `update` is composed too, on axis A3, and it is not a mechanism. The file now states
+  the distinction so the next reader does not "correct" either count into the other.
+
+  Rule 39 caught the first attempt at that fix: the new `description` carried a colon and stopped
+  being parseable YAML, which is the exact defect 3.10.1 removed, reintroduced an hour later by the
+  person who removed it. The gate working is the answer to that, and it is why it exists.
+
+### Added
+
+- **`docs/research/007-afm-next-steps-by-roi.md`** — the backlog ranked by return on investment,
+  with the scoring model written before any number arrived. Fifteen candidates, sized by agents
+  that had to run the check rather than read the changelog. Four dropped, three of them correcting
+  a premise of the person who proposed them.
+
+### Notes
+
+- **Consumer-noop.**
+
+## [3.11.5] — 2026-08-29
+
+Three more readers that the 3.9.1 split left behind, and one of them had been silently wrong for
+two months.
+
+### Fixed
+
+- **The capture substrate stopped seeing gotchas on 2026-08-29.** `afm-capture.sh` classified by
+  path and its table still named `docs/gotchas.md`, so every gotcha written after the split was
+  recorded as a generic `doc`. **Measured: 42 `gotcha` events in the ledger, the newest dated
+  2026-08-28, against 28 gotcha files on disk.** A rule written under `docs/rules/` had the same
+  problem.
+
+  This is not a wrong label. The ledger is what the self-evolution loop counts: `generalize` fires
+  on "two or more similar gotchas accumulated", and it was counting zero. A misclassification here
+  makes a mechanism blind, and a blind mechanism reports nothing to fix.
+
+- **`afm-subagent-start.sh` pointed a sub-agent at the deleted monolith.** It checked
+  `[ -f ./docs/gotchas.md ]`, which is false since the split, so the sub-agent was told nothing
+  about gotchas at all.
+
+- **`ops/rule.md` step 0 conflated the two reasons `docs/tools/gate/` can be missing.** A project
+  that maintains the plugin skips that copy on purpose (hard rule 34) and its gate lives at
+  `./test/`. Any other project with no such directory is behind the plugin. The op said only the
+  second, so a plugin-maintaining project was told to run `/afm:update` for something correctly
+  absent — and then to write its runner into a directory nothing would read.
+
+  The asymmetry is the point, and it is the inverse of the one fixed in 3.11.2: here the READERS
+  were already right. `afm-session-start.sh`, `afm-health.sh` and `afm-pre-commit.sh` all try
+  `docs/tools/gate` and fall back to `./test/`. The writer was the only one that did not.
+
+### Notes
+
+- `hooks/test/run.sh`: 168 → 170 assertions.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.11.5).** An instance that migrated to the split
+  has an event ledger with a gap. The history cannot be rebuilt — the events were written with the
+  wrong kind and rule 18 makes the substrate append-only — but the gap ends here.
+
+## [3.11.4] — 2026-08-29
+
+### Fixed
+
+- **The same absolute-`core.hooksPath` bug lived in `afm-pre-commit.sh`.** 3.11.1 fixed it in the
+  health axis. Here the consequence is different: the hook decided it was the only gate surface
+  while git was already running the same gate through the native hook, so **the gate ran twice per
+  commit** — and the refusal message told the operator they had no native surface while they were
+  reading its output.
+
+  One bug, two hooks, found a day apart because the first symptom was a false alarm and the second
+  was a doubled cost. Both directions are now covered in `hooks/test/run.sh`: an absolute path
+  makes the tier-3 hook yield, and an unset one keeps it denying a red gate.
+
+### Notes
+
+- Worth carrying: **when a defect is a misread of a config value, grep for every reader of that
+  value.** `git config --get core.hooksPath` had two readers and both were wrong the same way.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.11.4).** Any instance whose operator set an
+  absolute `core.hooksPath` was paying for the gate twice on every commit.
+
+## [3.11.3] — 2026-08-29
+
+### Fixed — the rules split only did half the job
+
+`afm-migrate-okf.sh --rules` copied every rule body into `docs/rules/NN-slug.md` and left section 3
+of `afm.md` exactly as it was. A consumer who followed the documented sequence ended with **every
+rule in two places**, and the duplicate is the dangerous half: the two copies drift and the reader
+has no way to tell which one is current.
+
+This repository's own section 3 was rewritten **by hand** after the split, and the procedure
+documented no such step. A tool has to do what the maintainer did, or the maintainer's result is
+not reproducible.
+
+The same command now splices section 3 into the index, preserving three things a naive rewrite
+would lose: the section intro, section 3.1, and the exact `N. **title**` shape that
+`afm-session-start.sh` and `afm-health.sh` parse. It warns when an indented `*Verification*` line
+survives, which means something in the source did not match the expected shape.
+
+- `ops/rule.md` writes **both halves** now: the file under `rules/` and the index line in section
+  3. It says why the second is not optional — a rule written only as a file never reaches a
+  session, and a rule written only as an index line has no body.
+- `tools/test/run.sh`: 60 → 65 assertions. Four of the five check what a naive splice destroys.
+
+### Notes
+
+- Found by an adversarial sizing pass that was asked to actually RUN the documented update
+  sequence on a fixture consumer instead of reading it.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.11.3).** An instance that already ran `--rules`
+  between 3.9.1 and 3.11.2 has duplicated bodies. Re-running is not the fix — section 3 no longer
+  matches the pattern. Delete the numbered bodies from section 3 by hand and keep the index lines.
+
+## [3.11.2] — 2026-08-29
+
+### Fixed — the ops still wrote to the file 3.9.1 deleted
+
+Found while ranking the backlog by return on investment, and it outranked everything on the list.
+
+`/afm:gotcha` declared `writes: ["docs/gotchas.md"]` in its frontmatter and instructed *"append to
+`<project>/docs/gotchas.md`"*. That file has not existed since 3.9.1. A gotcha registered today
+would have **recreated the monolith beside the directory**, where `afm-pre-edit.sh` — which prefers
+`docs/gotchas/` — would never look at it. A gotcha written and never delivered, which is the exact
+failure feature 006 existed to remove, reintroduced by the operation that creates them.
+
+`afm-index.sh --writes docs/gotchas.md` answered `gotcha` and `generalize`. Asking who writes
+`docs/gotchas/001-x.md` answered only `verify`, through an unrelated glob.
+
+- **Three output contracts corrected**: `gotcha` → `docs/gotchas/*.md`, `generalize` → gotchas and
+  rules as directories, `rule` → `docs/rules/*.md` alongside `afm.md`.
+- **`ops/gotcha.md` now writes one file with its frontmatter**, and says why the frontmatter is the
+  delivery mechanism rather than decoration: the detector reads `trigger_basename`, `trigger_path`
+  and `trigger_grep` and nothing else, so an entry without one never reaches anybody. It repeats
+  the measured lesson — prefer an honest `event` over a guessed `file-shape`, because 17 of the 26
+  gotchas in this repository are events and the old text match fired them on coincidence.
+- **Eleven stale READS swept.** This is the quieter half: `grep ./docs/gotchas.md` against a file
+  that does not exist returns nothing and reports nothing. The `reconcile` duplicate check would
+  never find a duplicate. The `deliver` discovery step would find zero gotchas in the area, and it
+  was still grepping the pre-3.6.0 Portuguese field name. `diagnose` axis A1 covered nothing.
+- **Universal rule 19's verification command** grepped the monolith, so a failure remediated inside
+  a gotcha reported `NO REMEDIATION`. It now reads `gotchas/` and `rules/`.
+- **`core/gotchas.md` is an orphan** — bootstrap stopped materializing it in 3.9.1. It carries a
+  tombstone and is **proposed for removal** rather than deleted, because deleting a canonical file
+  is a bright line that stops and asks (PRINCIPLES #7).
+- `templates/gotcha.template.md` renders to `docs/gotchas/*.md`, and its auto-generated description
+  is written properly.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.11.2).** Any instance on 3.9.1 through 3.11.1 has
+  an operation that would write to the wrong path. This is the release that makes `/afm:gotcha`
+  work again after the split.
+- The general shape: **a rename is finished when the WRITERS and the READERS both move.** 3.9.1
+  moved the files and the hooks and left the operations behind, and nothing failed loudly, because
+  a read against a missing file is silent by construction.
+
+## [3.11.1] — 2026-08-29
+
+### Fixed
+
+- **The vital sign called a correctly armed gate disarmed.** `core.hooksPath` can be absolute —
+  `git config core.hooksPath "$PWD/.githooks"` is a common way to set it — and the axis prefixed
+  `./` to whatever it read, producing `.//home/...`, which never exists. This repository has had
+  the gate armed since 3.7.0 and was told every session that it was not.
+
+  A vital sign that cries wolf is worse than a missing one. The operator learns to skip the line,
+  and it takes the true signals in the same bullet down with it. Covered in both directions by
+  `hooks/test/run.sh`: an absolute path is read correctly, and an unset one still reports disarmed.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.11.1).** Any instance whose operator set an
+  absolute `core.hooksPath` was seeing the false alarm.
+
+## [3.11.0] — 2026-08-29
+
+The deferred question from 3.10.0 is answered, and the answer removes code instead of adding it.
+
+### Changed
+
+- **Nothing in a policy bundle is ever executed.** The bundle injects CONTEXT. Its rules and
+  gotchas reach the session as text, named and marked as not editable here, and no file in it is
+  run. ADR 0019 is revised with the decision and its reason, which this repository had already
+  written down in `ops/rule.md`: *a repository cannot declare its own hooks, because if it could,
+  `git clone` would be remote code execution.* An environment variable pointing at a shared mount
+  is the same shape one level up.
+
+### Removed
+
+- **`blocking: claim` and `policy_blocking: accept`, and `afm_policy_blocking` with them.** They
+  existed to make execution safe. With execution decided against, they decided nothing — and a
+  field that decides nothing is the phantom gate this repository refuses everywhere else, because
+  it buys trust it cannot back up. They lasted one release and no instance carried them.
+
+### Added
+
+- **A bundle that anyone can write is REFUSED**, and so is one owned by neither this user nor
+  root. Every reader refuses it silently and the health check is the one place that says why. No
+  attacker is assumed: the ordinary mistake is `AFM_GLOBAL_DIR` pointing at `/tmp/something`,
+  where any process on the machine rewrites what every session of every repository is told to
+  follow.
+
+### The path to enforcement, unchanged
+
+An organisation that wants a rule enforced writes a runner into the project's own
+`docs/tools/gate/rules/`, through `ops/rule.md`. That code is versioned, arrives through a diff,
+and is reviewed like any other script. The organisation authors it. The project runs it, or does
+not. A pinned-hash execution from the bundle was considered and rejected: it is safer than
+executing blindly and still worse than a diff, and re-pinning after an upstream change is exactly
+the moment nobody reads carefully.
+
+### Notes
+
+- `hooks/test/run.sh`: 159 → 164 assertions, including one that asserts `afm_policy_blocking` does
+  NOT exist. A removal is worth a test when the thing removed was documented.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.11.0).** An instance that added
+  `policy_blocking` to `docs/afm.md` should delete the key. It never did anything.
+
+## [3.10.6] — 2026-08-29
+
+Three more from the same review. They were filed under "refuted", and five of the seven
+refutations were worthless: the skeptic's worktree was a stale snapshot, so it answered "cannot
+reproduce, the file does not exist here". That is not a refutation, and re-checking them by hand
+found two real defects and one undeclared intent.
+
+### Fixed
+
+- **The pass 0 skip was printed as a FINDING.** The runner contract says stdout carries one line
+  per finding and the aggregator counts them, so `39\t(pass 0)\tSKIPPED` reported a rule 39
+  violation on every machine without the `yaml` module. An audible skip has to be audible, not a
+  false failure. It goes to stderr now, and the gate emits zero stdout lines when it skips.
+- **A concept file with NO frontmatter escaped pass 0.** Pass 0 checks that a block PARSES and
+  skips a file that has none, which is correct for it — but the families that must have one were
+  only half enumerated. `docs/` itself, `sessions/`, `evolution/`, `research/`, `protocols/`,
+  `measurements/` and `guardrails/` were unchecked, so OKF clause 1 was unenforced for them.
+
+### Changed
+
+- **Rule 39 declares itself a COUNTING rule**, the way rule 36 does. It accepts the mode argument
+  and deliberately ignores it: "is every indexed file readable" is a question about the TREE, and a
+  staged-only answer would call a bundle conformant because this commit happened not to touch the
+  broken file.
+
+### Notes
+
+- The lesson about the review itself is worth more than the three fixes. **A verifier that cannot
+  see the code does not refute anything.** Five of seven refutations here said the file was absent
+  from their checkout. Read the reason, never the verdict.
+- **Consumer-noop.**
+
+## [3.10.5] — 2026-08-29
+
+An adversarial review of this release line, eight lenses with an independent skeptic per finding,
+confirmed 14 defects. The nine that were real and not already fixed are below.
+
+### Fixed — the migration
+
+- **A heading with a colon produced frontmatter no YAML parser could read.** `description: Gotcha:
+  the reason` is a nested mapping to YAML. The count check passed and reported success while
+  writing a file no OKF reader can open — the exact silent failure the script's own header claims
+  to prevent.
+- **A heading with a double quote broke the quoted scalar**, through the `fires_when` fallback that
+  never went through the quote sanitiser.
+- **A CRLF source carried a carriage return into every field**, and into the visible heading.
+- All three are one fix: a `yaml_scalar` helper that single-quotes, doubles the inner quote, and
+  strips CR. Single quotes process no escape, so a regex survives them.
+- **`## 3.1` re-opened section 3.** The pattern `^## 3\.` matches `## 3.1`, so everything in the
+  forward-only section bled into the LAST rule's file. Anchored on `^## 3. ` now.
+- **The splitter now WARNS when a rule block cites another rule's verification.** Found in this
+  repository: rule 38's verification paragraph was written after rule 39's block, so the split put
+  it in the wrong file — faithfully, because a splitter is only as correct as the order of the
+  monolith. It cannot repair that automatically. It can report it.
+
+### Fixed — the hooks
+
+- **A path segment was interpolated into an ERE unescaped.** A directory named `app[beta]` became
+  the character class `[beta]` and matched b, e, t or a anywhere, injecting unrelated rules and
+  gotchas. A `(` made grep fail outright and the channel went silent instead.
+- **The health cache key ignored `AFM_GLOBAL_DIR`.** A session that exported a BROKEN pointer was
+  served the answer from before it was exported, for the rest of the day — silence on the one axis
+  built to break silence.
+- **A policy value had no cap and no sanitiser.** It is interpolated into the markdown that tells
+  the agent what is not editable, so a value carrying `**` or a newline could close that framing
+  and write its own. Values fold to one line, lose markdown emphasis, and stop at 200 characters.
+- **The `>= 100` floor was documented and tested, never enforced.** A bundle numbering a rule 37
+  would have collided with the local 37 in every injection, and only the health check would have
+  said so. The floor is applied in the one function every reader goes through.
+- **The session digest still named `docs/gotchas.md`**, a file this release line deleted.
+
+### Fixed — the gates
+
+- **`refs-lint`'s materialization reading accepted a target that climbs.** `../../PRINCIPLES.md`
+  resolved from the bundle root walks OUT of the plugin, where a coincidentally named file lets a
+  genuinely dead link pass. The exception now applies only to a target with no `..`.
+
+### Corrected — a claim
+
+- The CHANGELOG said three baseline sizes were "held by a test". No test read that file. The sizes
+  are a dated measurement now, with `test/unset-baseline.sh` to re-measure, and the text says what
+  a test actually holds: with `AFM_GLOBAL_DIR` unset the policy layer contributes nothing. They are
+  deliberately not a gate — every one moves when a document changes, and a gate that fires on an
+  ordinary doc edit is a gate somebody disables.
+
+### Notes
+
+- `hooks/test/run.sh`: 155 → 159 assertions. `tools/test/run.sh`: 57 → 60.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.10.5).** An instance migrated before 3.10.5 may
+  hold frontmatter written by the old splitter. Rule 39 pass 0 names every unparseable file.
+
+## [3.10.4] — 2026-08-29
+
+### Fixed
+
+- **The migration produced a file name that was not ASCII.** `tr` and `sed` in a UTF-8 locale read
+  a multi-byte letter as a letter, so a heading with an accent survived the character class that
+  was supposed to remove it. Measured: `002-acentuação-não-ascii-e-emoji.md`. The function
+  documented ASCII and did not deliver it. `LC_ALL=C` makes the byte the unit.
+- **An empty heading produced `003-.md`**, a name whose only content is a number. It falls back to
+  `untitled` now.
+
+Both are covered by `tools/test/run.sh`, which grew from 57 to 60 assertions.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.10.4)** only for an instance that has not
+  migrated yet. A project already split before 3.10.4 may hold a non-ASCII file name from the old
+  slug. `git mv` fixes it, and the reference is the frontmatter, not the name.
+
+## [3.10.3] — 2026-08-29
+
+### Fixed
+
+- **A repository-wide scan counted an ephemeral agent worktree.** `.claude/worktrees/` holds full
+  checkouts that an isolated agent fan-out creates, so a walk of the FILESYSTEM sees every file
+  twice. Measured with eight worktrees on disk: the skill listing budget read 59,764 characters
+  against a baseline of 31,524, and the gate failed on a tree nobody ships. `afm-detect.sh` had the
+  same exposure in its repository-wide report. Both now exclude the path.
+
+### Notes
+
+- The general shape, worth carrying: **a gate that walks the filesystem measures whatever happens
+  to be on disk.** A gate that walks git measures the repository. When the two disagree, the
+  filesystem is the one that invents work.
+- **Consumer-noop.**
+
+## [3.10.2] — 2026-08-29
+
+### Fixed
+
+- **`--check-index` regenerated the tree it was supposed to be checking.** `DOCS` was bound once at
+  load, so the `AFM_DOCS_DIR` the check exports for its temporary copy was ignored. The check ran
+  `--materialize` against the REAL documentation, then compared it with itself. It could not fail
+  for the reason it exists, and hard rule 39 depended on it. The directory now resolves at call
+  time.
+- **`--check-index` could not see a DELETED `index.md`.** It walked only the regenerated side,
+  where a missing file is skipped instead of reported — and a deleted index is the exact failure it
+  exists to catch. It passed at exit 0. The comparison now runs in both directions and reports
+  `missing index`, `stale index` and `orphan index` separately.
+- **A tab or a newline inside a value corrupted `docs/.afm-index.tsv`.** A description holding a
+  literal tab produced 10 fields where the header declares 9, so every reader that indexes by
+  position read the wrong field with no error. Values are sanitised on write, for the TSV and for
+  the markdown bullet.
+
+### Notes
+
+- All three were found by reviewing this session's own work, and all three share one shape: the
+  check passed for a reason that had nothing to do with what it was checking. A green gate is
+  evidence only when its failure has been observed.
+- **Consumer-noop.** The changes are inside the tool, which travels with the plugin.
+
+## [3.10.1] — 2026-08-29
+
+### Fixed
+
+- **The frontmatter was declared OKF-conformant and no parser had ever read it.** Clause 1 of OKF
+  conformance is "every non-reserved `.md` contains a parseable YAML frontmatter block" (SPEC v0.2
+  §11). **59 files** across the plugin and the instance could not be read by any YAML parser. Every
+  reader in this repository is grep-based, and grep never parses, so the break was invisible.
+
+  Two causes, both introduced earlier in the same release line:
+
+  ```yaml
+  description: Session record: some-name    # a colon-space inside a plain scalar
+  trigger_grep: "awk.*\\."                  # a backslash escape in a double-quoted one
+  ```
+
+  Values that carry a colon or a regex are now **single-quoted**, the YAML style that processes no
+  escape sequence, so a pattern survives it intact.
+
+- **`afm-index.sh` read only the double-quoted style.** After the fix above it printed the quotes
+  as content, into the generated index and into every line the hook injects. Both of its readers
+  now handle the single-quoted form and undouble the `''` escape.
+
+- **The `Stop` hook could write an unparseable session file.** The label it derives from the
+  touched files can carry a colon. It now single-quotes `description` and `name`, and the smoke
+  test parses what the hook wrote instead of grepping for field names.
+
+- **The three catalogue guardrails carried no `type:`.** They declared `id` and `title`, so they
+  were non-conformant from the day OKF was adopted.
+
+- **The two templates with `{{placeholders}}` now quote them.** That makes the RENDERED file valid,
+  not only the template.
+
+### Added
+
+- **Hard rule 39 gains pass 0.** `python3` parses every frontmatter and requires a non-empty
+  `type` — OKF clauses 1 and 2. It **skips audibly** when `python3` or its `yaml` module is
+  absent, the same discipline the shellcheck skip follows: a silent skip reports coverage the gate
+  does not have. Proven by reintroducing the double-quoted regex and watching the gate fail.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.10.1).** An instance materialized during 3.9.1
+  through 3.10.0 holds unparseable frontmatter. `/afm:update` must single-quote any value that
+  contains `: `, a `"`, or a backslash. Running rule 39 names every file.
+- The lesson generalises past YAML. **A format is only adopted once something that did not write
+  the files can read them.** This repository declared conformance to a shared format and kept
+  reading with the tool that hides exactly this class of break.
+
+## [3.10.0] — 2026-08-29
+
+Feature 007. An organisation can now impose documentation on every project on a machine, through
+one environment variable, and a project that never heard of the feature pays nothing.
+
+### Added
+
+- **`AFM_GLOBAL_DIR` names a second OKF bundle.** Feature 006 is what makes this small: the global
+  directory is an ordinary bundle, with the same `type`, `fires_on` and `trigger_*` keys, so no
+  new format exists and every reader already knows how to read one.
+- **`hooks/lib/afm-policy.sh`**, sourceable and not a hook. It answers where the bundle is, who it
+  belongs to, whether it may block, and which files a family contributes. Five surfaces need those
+  answers, and five copies of a precedence rule is five places for it to drift.
+- **`/afm:policy`** — a new op and skill. It reports what the organisation imposes here, read only.
+  It never writes to either bundle.
+- **A vital sign.** A broken pointer, a bundle with no `organization:`, an organisation rule below
+  the 100 floor, and a number that collides with a local rule. This axis is the ONE place that
+  says the pointer is broken, because every reader stays silent by design.
+
+### Changed
+
+- `afm-session-start.sh` lists the organisation rules after the local ones, named, and says they
+  are not editable in this repository.
+- `afm-pre-edit.sh` injects a matching organisation rule and gotcha as a separate, named block.
+- `afm-index.sh --triggers` marks the bundle's rows with an `org:` prefix and the organisation
+  name. `--materialize` never writes into the bundle.
+- `core/afm.md` documents the optional `policy_blocking` key.
+
+### The decisions, and the two that carry weight
+
+| Question | Decision |
+| --- | --- |
+| Precedence | per family. Rules and guardrails go to the organisation. Gotchas, learnings and rubrics accumulate. Product documents never participate |
+| Rule numbering | an organisation rule is numbered 100 or higher, so the number stays the identity |
+| Blocking | two consents: `blocking: claim` in the bundle AND `policy_blocking: accept` in `docs/afm.md` |
+| Read or copy | read live. Hard rule 34 |
+| Identity | the injected text names the organisation |
+
+**Why the product family never participates.** It is the defence against a mistyped variable. A
+path pointing at another PROJECT instead of a policy bundle cannot leak that project's `prd.md`
+into this session. Requiring `policy.md` is the second half: a directory without one is not read
+as an organisation.
+
+**Why blocking needs two consents.** An environment variable is exported by whoever runs the
+shell. One consent would let that person fail every commit in every repository on the machine.
+
+### Deliberately not built
+
+- **No runner from the policy bundle executes.** A guardrail from the organisation arrives as
+  context, and the gate that decides stays the project's own. Executing shell from a path an
+  environment variable names is a different risk class from reading markdown from it. ADR 0019
+  records it, so the next reader does not treat the absence as an oversight.
+- **`afm-detect.sh` did not gain a list parser.** The caller already invokes it once per root with
+  a different `AFM_RUBRIC_DIR`. A list would be a second way to do what one variable already does.
+
+### Measured
+
+- **The unset case is byte-identical**, measured on the day: pre-edit injection 3,644 characters.
+  The three sizes are recorded in `test/baseline/007-unset-baseline.tsv` as a dated measurement,
+  and `test/unset-baseline.sh` re-measures them. They are NOT a gate: every one of them moves when
+  a document changes, and a gate that fires on an ordinary doc edit is a gate somebody disables.
+  What a test does hold is the behaviour — with `AFM_GLOBAL_DIR` unset the policy layer
+  contributes nothing at all, asserted in `hooks/test/run.sh`.
+- The hooks smoke test went from 138 to 154 assertions.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.10.0), and it is an OPT-IN.** `ops/update.md`
+  gained a section for that shape: a capability delta is reported and never applied, because
+  opting in is the operator's decision. A project that has not exported the variable has not
+  decided against the feature. It has not been asked.
+
+## [3.9.3] — 2026-08-29
+
+### Known gap — retired
+
+The eight gaps declared in 3.9.0-rc.7 were re-verified against the tree, one command each, with the
+default posture that a gap stays open until something proves otherwise. **Six of the eight are
+closed**, and two more that lived in this repository's instance were checked with them.
+
+| Gap | State | Proof |
+| --- | --- | --- |
+| session-start named a `docs/tools/` path no procedure creates | **closed** | the hook now resolves through a helper that tries `docs/tools/` then `PLUGIN_ROOT`, and emits nothing when neither exists |
+| the skill count disagreed with what ships | **closed** | 24 directories, and `plugin.json`, `README.md` and `README-light.md` all say 24. `core/protocol.md` names `/afm:protocol` |
+| `--worktree` never saw an untracked file | **closed** | an untracked probe file appears in `scope_files`, `scope_diff` and `scope_all` |
+| `ratchet_region` matched a bare prefix | **closed** | `docs/research-extra/x.md` no longer lands in the `docs/research` budget |
+| the `git commit` detector missed `-c` and `-C` | **closed** | both forms produce `permissionDecision: "deny"` end to end |
+| `REFLECT_TASKS` was never de-hardcoded | **closed** | `cadence: … tasks=7` reaches both readers through `afm_cadence_read` |
+| `hooks/README.md` said only `Stop` blocks | **closed** | it now names both carve-outs |
+| `afm-index.sh --self-test` read the caller's live `./docs/` | **closed** | it passes from `/tmp` at 23 ok |
+| this repository's `CLAUDE.md` counted 7 hooks | **closed today** | it says 8, and names both blocking hooks |
+| this repository's `docs/.afm-version` was pinned at 3.5.0-rc.8 | **closed today** | see below |
+
+### The pin was lying, and the discovery proved it
+
+`/afm:update`'s discovery step ran against this repository across the 22 consumer-facing releases
+since the pin. **Zero deltas are missing.** Ten were already applied, and twelve do not apply here
+at all, because they copy files into `docs/tools/` and a project that maintains the plugin skips
+that copy on purpose (hard rule 34).
+
+The pin now reads 3.9.2, and vital sign A3 stops reporting a drift that was not there. The lesson
+generalises: an unverified pin reports the version someone last typed, not the version the content
+is at.
+
+### Changed
+
+- Every feature document carries the contract. The six spec files got a description that says what
+  the feature delivers, not what kind of file it is — the same standard applied to the rest.
+
+### Notes
+
+- **Consumer-noop.** No file a consumer materializes changed in this release.
+
+## [3.9.2] — 2026-08-29
+
+### Changed
+
+- **The hard-rule channel caps at two rules, and 1,200 characters each.** Injecting a whole rule
+  instead of a grep line was the right move, and it made that channel the loudest one in the hook:
+  2,787 characters of the 5,098 an edit of a hook script produced. The rubrics and the gotchas
+  already cap at two for the same reason. A channel that is always loud gets ignored, which looks
+  exactly like coverage while providing none.
+
+### Measured
+
+- One edit of `plugins/afm/hooks/afm-capture.sh`, every family together: **5,098 → 3,644
+  characters.** The two matching gotchas are 1,582 of that, and they arrive complete.
+
+### Notes
+
+- **Consumer-noop.** The change is inside the hook, which travels with the plugin. An instance
+  needs nothing.
+
+## [3.9.1] — 2026-08-29
+
+The OKF profile closes. `ops/update.md` now carries the migration an instance needs, and
+`interview/{bootstrap,refactor}.md` materialize the new shape from the start.
+
+### Added
+
+- **`ops/update.md` § Structural migrations.** A replacement edits text inside a file. A structural
+  migration changes which files exist, so it cannot be a table of strings, and it must not be prose
+  that every operator re-derives. The plugin ships the migration as an executable and the op runs
+  it: four rows, each with its command, its proof of need and its proof of application.
+- The section also states what the operator gets for migrating, with the measured numbers, and what
+  happens if they never do: nothing, because every reader carries a legacy branch.
+
+### Changed
+
+- **`interview/bootstrap.md`** materializes `docs/gotchas/` and `docs/rules/` as empty directories
+  instead of a `gotchas.md` seed, and runs `afm-index.sh --materialize` before the final check.
+  Hard rule 39 fails on a missing index, so a bootstrap without that step handed the owner a red
+  gate on their first commit.
+- **`interview/refactor.md`** follows the same shape.
+- **ADR 0018** in this repository records the three-layer decision and, more importantly, why the
+  gate stays strict while the instance stays OKF-conformant.
+- **`CLAUDE.md` documents four plugins.** `ste` has existed since 0.1.0 and was never listed.
+
+### Fixed
+
+- **The rule 30 runner called a release a move backwards.** Its watermark check used `sort -V`,
+  which orders `3.9.1` BEFORE `3.9.1-rc.4` because it reads the hyphen as more text. Semver says
+  the opposite: a pre-release precedes its own release (spec §11.3). Cutting rc.4 to the final
+  3.9.1 is the last step forward, and the gate blocked it. Found while cutting exactly that
+  release. The comparator now reads the numeric core first, and only then lets the suffix decide.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.1).** An instance that migrates runs three
+  commands and then commits: `afm-migrate-okf.sh --gotchas`, `afm-migrate-okf.sh --rules`, and
+  `afm-index.sh --materialize`. The `kind:` to `type:` rename is one `sed`. Every step proves it
+  was needed before it runs and proves it applied afterwards.
+
+## [3.9.1-rc.4] — 2026-08-29
+
+### Changed
+
+- **`core/rubrics/` moved to `rubrics/`, and `core/templates/` moved to `templates/`.** `core/`
+  now holds only the six canonical documents an instance materializes: `afm`, `ach`, `prd`, `ust`,
+  `gotchas` and `protocol`. It was carrying three different things under one name — the canonical
+  docs, a decision-table catalogue and a set of render templates.
+- 287 references rewritten (211 relative, 76 absolute). `git mv` first, references second, with
+  no content edit in the same commit: a rename mixed with an edit hides both in the diff.
+
+### Fixed
+
+- **`refs-lint.sh` now reads a `core/` template the way it will be materialized.** A file under
+  `framework-template/core/` becomes a file at the ROOT of the consumer's `docs/`, where
+  `rubrics/x.md` is a sibling. In the plugin it is not, because the template sits one directory
+  deeper. The lint accepts either reading. Without this, the move would have forced every link to
+  be correct in the plugin and broken in every instance.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.1-rc.4).** Nothing changes in a materialized
+  instance: the moved directories are internal to the plugin, and the materialized names
+  (`docs/rubrics/`, `docs/features/`) were already flat. `/afm:update` needs no step for this.
+
+## [3.9.1-rc.3] — 2026-08-29
+
+### Added
+
+- **`afm-index.sh --materialize`** writes an `index.md` in every documentation directory, plus the
+  bundle-root `index.md` that declares `okf_version: "0.2"` — the one place OKF permits it (§12).
+  The entries follow the OKF shape `* [Title](path) - description` and carry no frontmatter (§8).
+- **`afm-index.sh --check-index`** regenerates into a temporary copy and compares. OKF endorses
+  generating an index and its conformance never checks one against the directory it describes
+  (§11 is structural only), so that check belongs to the producer. Hard rule 39 now runs it.
+- **`docs/.afm-index.tsv`**, the machine index: one line per concept file with `type`, `load`,
+  `fires_on`, the trigger fields, the path and the description. It is a second artifact because an
+  `index.md` carries no frontmatter, and a regular expression inside a markdown bullet is
+  unreadable for a person and fragile for a parser.
+- **`/afm:verify <path>`** — a new op and skill, and the ONLY writer of the OKF `verified` field.
+  OKF derives a trust tier from it: absent means unverified, a non-human actor means
+  machine-confirmed, a `human:<id>` actor means human-reviewed (§5.3). AFM is autonomy-first and
+  its own ops write documentation, so until now nothing separated "an agent wrote this and nobody
+  read it" from "a person approved it".
+
+### Changed
+
+- **Hard rule 39 covers the instance families** (`docs/gotchas/`, `docs/rules/`, `docs/adr/`,
+  `docs/rubrics/`) with the same three-key contract, and it exempts the OKF reserved names
+  `index.md` and `log.md`, which are not concept documents (§3.1).
+
+### Measured
+
+- **69 instance files gained the contract**: 15 sessions, 5 evolution reports, 3 protocols, 7
+  research files and 12 rubrics by mechanism, 29 by judgment. The 12 rubrics reuse the canonical
+  frontmatter from the plugin instead of a second hand-written description.
+- The machine index holds **86 lines** for the whole instance.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.1-rc.3).** `/afm:update` must run
+  `afm-index.sh --materialize` once after it migrates an instance, or hard rule 39 fails on a
+  missing index. The op file carries that step.
+- **Why no automatic writer for `verified`.** A hook that stamped it on commit would claim human
+  review of every agent commit, because the agent commits under the operator's git identity. That
+  turns an honest absence into a confident lie, which is worse than having no field.
+
+## [3.9.1-rc.2] — 2026-08-29
+
+### Changed
+
+- **A gotcha is a file, and a hard rule is a file.** `docs/gotchas.md` became `docs/gotchas/NNN-slug.md`
+  (26 entries) and section 3 of `docs/afm.md` became `docs/rules/NN-slug.md` (13 rules). Section 3
+  keeps one index line per rule, in the exact `N. **title**` shape that `afm-session-start.sh` and
+  `afm-health.sh` parse, so no hook lost its contract. `afm.md` went from 216 lines to 147.
+- **`afm-pre-edit.sh` injects the entry, never a pointer.** It used to grep the monolith and then say
+  "read the whole entry", which cost the agent 374 lines to use about 15.
+- **The gotcha match now uses the SAME shape detector the rubrics use**, pointed at another directory
+  through `AFM_RUBRIC_DIR`. A gotcha fires on `trigger_basename`, `trigger_path` or `trigger_grep`,
+  never on a word that happens to appear in its prose.
+- **`afm-index.sh` reads both families as files**, with the legacy branch kept for an instance that
+  has not migrated.
+- **`tools/afm-migrate-okf.sh`** is new. It splits either monolith, counts before and after, and
+  refuses to finish on a difference. It writes no trigger it cannot derive from the text.
+
+### Fixed
+
+- **`afm-detect.sh` never fired on a file that does not exist yet.** A `Write` of a new file is
+  exactly when the advice is worth most, because the mistake has not happened. The name and path
+  triggers now apply, and only the content conditions skip. Self-test covers it.
+
+### Measured
+
+- The trigger index: **8,628 characters and 46 entries → 6,602 characters and 58 entries.** About 500
+  tokens cheaper while covering 12 more decision surfaces.
+- **9 of the 26 gotchas have a mechanical trigger. The other 17 declare `fires_on: event`** and say
+  why. That is not a gap. It is the honest count: two thirds of the gotchas describe a moment a human
+  recognises, and the old text match fired them on coincidence.
+- **`load:` saves nothing yet, and the measurement file says so.** The index never scanned a cold
+  family, so the skip has no work to do until the generated index lands.
+
+### Notes
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.1-rc.2).** An instance keeps its monolith until
+  `/afm:update` runs. Every reader — the pre-edit hook, the index, the health check — carries a
+  legacy branch, so an unmigrated instance loses nothing. Without that branch, updating the PLUGIN
+  would silently switch off rule injection in every instance that had not migrated, and nothing
+  would report it.
+
+## [3.9.1-rc.1] — 2026-08-29
+
+### Changed
+
+- **The frontmatter contract becomes OKF v0.2.** `kind:` is now `type:`, the one key the
+  Open Knowledge Format requires. 82 files renamed. The AFM extension keys (`fires_on`,
+  `trigger_*`, `writes`, `composes`) are untouched, because OKF protects unknown keys and
+  forbids a consumer from rejecting a document that carries them.
+- **Two keys join it on every indexed file.** `description:` is one sentence, and the index
+  prints it instead of opening the body. `load:` is `hot`, `warm` or `cold`, and it tells the
+  index what it may skip. 62 files carry all three.
+- **Hard rule 39** now demands the three keys, and rejects the retired `kind:`.
+- **Hard rule 36** now forbids a FILESYSTEM absolute path. A leading `/` means the bundle
+  root, which is the link form OKF recommends because it survives a file move.
+- **`afm-index.sh` reads `type`.** The `--kind` flag is now `--type`. No compatibility shim:
+  the rename is mechanical and the gate proves it landed.
+- **The `Stop` hook writes the contract** on a session file: `type`, `description` and
+  `load: cold`.
+
+### Fixed
+
+- **`refs-lint.sh` used to skip every `/`-prefixed link.** That made the safest link form the
+  only unverified one. It now resolves a bundle-relative link from the bundle root, with a
+  self-test in both directions.
+
+### Notes
+
+- **`tier:` was already taken.** The `Stop` hook has written `tier: dual|episodic` on session
+  files since 3.4.0-rc.7, meaning the CoALA memory tier. The new key is `load:`, which names
+  what it controls. No history was rewritten.
+- **Rule 39 used to forbid a `summary:` key**, because a derived duplicate goes stale in
+  silence. `description:` reverses that decision. The reversal is written into the rule with
+  the trade named. The objection is sound, and it is paid for one reason: without a stated
+  description the index cannot say what a file is without reading it.
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.1-rc.1).** An instance materialized before
+  3.9.1 carries `kind:` in its frontmatter, and no `description:` or `load:`. The index in that
+  instance reads `type:` after `/afm:update`, so the rename must land in the instance too.
+  `/afm:update` renames the key, and reports every file that still needs a `description:` — it
+  never invents one, because a wrong description is worse than an absent one (principle #5).
+- Version **3.9.1**, not 4.0.0. The convention calls a layout change a major bump. The owner
+  reserved 4.0.0 for a larger change, and decided this exception on 2026-08-29.
+
+## [3.9.0-rc.12] — 2026-08-28
+
+### Fixed
+
+> **A second validation pass rebuilt each rc.11 fix and hunted its neighbours.** Five of six were
+> closed only for the input that had been named. The sixth — the commit detector — turned out not
+> to be closeable by enumeration at all, and is now bounded and declared instead of quietly widened
+> one more time.
+
+- **The commit detector anchored on the wrong concept: the first token, not COMMAND POSITION.**
+  Eight everyday spellings ran a real commit with the gate red and the hook silent, each verified
+  by executing it: `(git commit)`, `{ git commit; }`, `command git commit`, `env git commit`,
+  `/usr/bin/git commit`, `"git" commit`, `sh -c "git commit"`, and `git --attr-source TREE commit`.
+  The anchor now accepts the shell's own command-opening constructs, a path prefix, a quote, and a
+  **closed list** of exec wrappers and shells — closed because no regex can tell `command git`
+  (executes) from `echo git` (does not). `--attr-source` joins the value-taking globals.
+
+- **The limitation is now declared where a reader looks.** `hooks/README.md` states plainly that
+  tier 3 is a **nudge for the common path, not a boundary**: it cannot see a command built at
+  runtime (`eval`, a variable, a script on disk), because a regex over a command string cannot
+  enumerate a shell. The boundary is `--install`, which writes git's own `pre-commit` hook — git
+  runs that however the command is spelled. Every release that widens the regex buys one more
+  spelling, not closure, and saying so is worth more than the next widening.
+
+- **The hooks harness fabricated the failure it was looking for.** `pc()` interpolated the command
+  into a JSON string, so any probe containing a double quote built INVALID json; the hook's `jq`
+  returned empty, the hook exited 0, and the assert read that silence as "the detector missed it".
+  Two cases were accused of slipping past a hook that was in fact denying them. It now encodes
+  through `jq -n --arg`.
+
+- **A repeated cadence key resolved to the LAST occurrence.** The `sed` had a greedy leading `.*`,
+  so an operator who wrote `tasks=7 (raised from tasks=2)` silently got 2 — the value they had just
+  moved away from. `afm_cadence_key` now tokenizes the line and takes the first match, which also
+  gives the word boundary for free instead of encoding it in a pattern.
+
+- **A tool whose plugin root was unresolvable answered EMPTY with exit 0.** The symlink walker
+  added in rc.11 covers a symlink; a hard link carries no back-reference, and neither does a copy
+  of the script dropped elsewhere. The check moved to the RESULT instead of the invocation shape:
+  no `ops/` under the resolved root means `afm-index.sh` prints what is wrong on stderr and
+  abstains with **exit 2**. An empty answer with exit 0 reads as "the plugin declares nothing".
+
+- **A ratchet budget bash cannot compare.** The TSV is hand-written, and an all-digit value beyond
+  the 64-bit range survives `awk` and then breaks `[ -le ]` itself with *integer expression
+  expected*, which evaluates falsy — the finding counted as over budget and stderr filled up on
+  every run. `ratchet_budget` clamps anything above 9 digits to 0, the same answer an unregistered
+  rule gets: a budget nobody can read is a budget nobody measured.
+
+- **`gate_skill_count` had two blind spots.** A declared count of **0** was conflated with "no
+  count declared", which silently exempted the whole plugin from the second pass; `max` and
+  `found` are now separate. And the singular — "three atomic skill", "skill count: 23" — evaded
+  both passes, which looked only for the plural.
+
+- **`hooks/README.md` claimed `afm-session-end.sh` had a `SessionEnd` fallback.** `hooks.json` has
+  never carried that key and the script never read one.
+
+- **Two harness blocks vanished with no output when `git` was absent.** About 25 asserts in
+  `hooks/test/run.sh` — the session-end handoff block and the whole `Stop` cadence block, which
+  covers the only hook authorized to block — sat inside `if command -v git` with no else branch.
+  A block that disappears silently is indistinguishable from a block that passed. The harness
+  gained a `skip()` that always speaks and a skip count in its summary line, matching the sibling
+  harness. Proven by running it with `git` off `PATH`.
+
+- **The sibling harness had the same hole, in the place that already knew about it.** The comment
+  above the repo-shim walk-up in `tools/test/run.sh` records that those two asserts "skipped in
+  silence for the whole run" — the walk-up was fixed then and the silence was not, so the pass
+  count still moved between 55 and 57 depending on where the file sat. **A harness whose pass
+  count moves with its location is reporting its location, not its coverage.**
+
+- **One more JSON-interpolation site.** `CAP` built a capture payload by interpolating a command
+  into a JSON string, the exact trap that `pc()` had just been fixed for. It had not bitten only
+  because no probe there carries a quote, and "not yet" is not a property.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.0-rc.12).** An instance that materialized
+  `docs/tools/gate/` holds a stale `lib/ratchet.sh`: without the clamp, a hand-typed budget can
+  make every finding in that region count as over budget while stderr fills with *integer
+  expression expected*. `/afm:update` re-copies `gate/lib/ratchet.sh`. The instance's
+  `gate/rules/` and `gate/ratchet.tsv` are never touched.
+
+## [3.9.0-rc.11] — 2026-08-28
+
+### Fixed
+
+> **Every residue the validation left behind is closed.** rc.10 fixed the two routes the probe
+> ranked highest and *declared* the rest. Declaring is cheaper than fixing only while the list
+> is short — this empties it.
+
+- **`git --config-env NAME=ENVVAR commit` reached a commit and the detector stayed silent.**
+  Measured: `MYVAL=false git --config-env core.autocrlf=MYVAL commit -m x` creates a real
+  commit. It joins the enumerated value-taking globals. Two siblings a probe reported alongside
+  it are deliberately **not** enumerated: `--super-prefix` exits 129 as an unknown option, and
+  `--html-path` prints a path and exits before `commit` is ever parsed. Neither can commit, and
+  a form that cannot commit is not a bypass — adding it would only widen the pattern.
+
+- **A cadence key was matched as a substring, not as a word.** `*tasks=*` also matched
+  `subtasks=9`, so a neighbouring key silently donated its value to the threshold; the same
+  weakness had been there for `reflect=` and `evolve=` since v3.5.0, and `tasks=` copied it
+  verbatim in rc.9. All three keys now go through one `afm_cadence_key` helper that matches at a
+  word boundary. **A parser that answers confidently from a key nobody wrote is worse than one
+  that answers the default.**
+
+- **A value bash cannot compare was treated as a threshold.** An all-digit number beyond the
+  64-bit range passed the "is it numeric" sanitizer and then broke `[ -lt ]` itself with
+  *integer expression expected*, which evaluates falsy — so the `Stop` hook fell **through to
+  block** on a threshold the operator had declared as astronomically high, printing stderr noise
+  on every session end. Values above 9 digits now fall back to the documented default.
+
+- **A tool invoked through a symlink could not find its own plugin tree.** `dirname "$0"`
+  answers the symlink's directory, so `ROOT` pointed somewhere with no `ops/` and the
+  plugin-controlled queries came back **empty** — which reads exactly like "the plugin declares
+  no rubrics" and would be believed. `afm-index.sh` and `afm-detect.sh` now walk the symlink
+  chain (a six-line loop, not `readlink -f`, which is GNU-only). The resolver is duplicated in
+  the two scripts on purpose: a shared library would itself have to be located, and locating it
+  is the problem this solves. `tools/test/run.sh` now runs every self-testing tool through a
+  symlink as well as directly.
+
+- **`gate_skill_count` went quiet when a count was reworded out of shape.** It reads the literal
+  `N (atomic )?skills`; spell the number out and the file stopped matching, and "no match" meant
+  "nothing to check" — the file passed while carrying a stale claim. A second pass now names any
+  file that mentions skills and declares no countable number, **but only in a plugin where a
+  sibling file does declare one**: `learn`, `seo` and `ste` state no count anywhere, and
+  demanding one from them would be a different rule than this.
+
+- **The `Wiring` bullet in `hooks/README.md` listed one `PreToolUse` entry; `hooks.json` has
+  two.** The missing one is `afm-pre-commit.sh`, the entry that can refuse. A reader scanning
+  the inventory bullet would have come away with the same wrong picture rc.8 corrected in the
+  two other bullets.
+
+### Consumer migration
+
+- **Consumer-noop.** `afm-index.sh` and `afm-detect.sh` are not materialized by any consumer
+  procedure — the session-start hook resolves them from the plugin since rc.8. `CONSUMER_VERSION`
+  stays at 3.9.0-rc.9.
+
+## [3.9.0-rc.10] — 2026-08-28
+
+### Fixed
+
+> **Found by validating rc.8 and rc.9, not by reading them.** Each of the eight closed gaps was
+> rebuilt as a scenario, run against the pre-fix commit to prove it went red, then run against
+> the fix. Seven held. The eighth held only for the defect as declared — the same hook was
+> reachable by two neighbouring routes nobody had named.
+
+- **The `git commit` detector anchored on the wrong thing.** rc.9 widened the option group and
+  left the ANCHOR untouched: `(^|[;&|][[:space:]]*)git` demands `git` at position 0 or right
+  after a separator, so two everyday shell forms stayed invisible — an inline environment
+  assignment (`GIT_AUTHOR_NAME=x git commit`, which is how authorship gets set on one line) and
+  leading whitespace (which comes free with any indented heredoc). Both execute normally, and
+  both left the tier-3 gate silent. The anchor now allows leading whitespace and a run of
+  `NAME=value` assignments. An assignment is never a bare word, so `foo git commit` — git as an
+  argument to something else — still does not match. Verified in both directions: seven commit
+  forms denied, six read-only forms untouched.
+
+- **`gate_skill_count` had no `--self-test` coverage.** The gate added in rc.8 was proven only
+  by the real run, which can say nothing stronger than "the numbers agree today". This
+  repository already paid for that once: an `is_known_debt` assert named a real baseline row,
+  the row left the baseline, and the assert stayed red for months because no gate ran
+  `--self-test`. Four synthetic-fixture asserts now prove the gate catches a 24th skill, names
+  every stale file, **stays red while any single file is stale** (the per-file property that
+  stops a corrected README masking a stale `plugin.json`), and tolerates a smaller historical
+  count in the prose. The gate reports through the harness counters, so each probe runs inside
+  a command substitution and only the delta comes back.
+
+### Known gap
+
+- **Two low-severity residues, declared rather than fixed.** `afm_cadence_read` matches its keys
+  with unanchored globs, so a future key ending in `tasks=` would be mis-read — no such key
+  exists today. And `afm-index.sh` resolves its own directory without `readlink -f`, so invoking
+  it through a symlink points `ROOT` at the symlink's directory; nothing in the shipped wiring
+  invokes it that way. Both are written down here so the next probe does not re-find them.
+
+### Consumer migration
+
+- **Consumer-noop.** No file a consumer materializes changed. `CONSUMER_VERSION` stays at
+  3.9.0-rc.9.
+
+## [3.9.0-rc.9] — 2026-08-28
+
+### Fixed
+
+> **The last four gaps declared in `3.9.0-rc.7` are closed.** With rc.8 this closes all eight.
+> Every fix landed with the failing assert first.
+
+- **`afm-pre-commit.sh` did not recognize a `git commit` carrying a global option that takes a
+  value.** The option group accepted dash-tokens only, so in `git -c core.hooksPath= commit` the
+  value token matched nothing, the whole pattern failed, and the hook exited 0 — **the tier-3
+  gate no-opped instead of denying, and from the outside a no-op is indistinguishable from a
+  green gate**. `git -C <dir> commit` is the same shape, and it is how an agent commits inside
+  another worktree. The list of value-taking globals is **enumerated** (`-c`, `-C`,
+  `--git-dir`, `--work-tree`, `--namespace`, `--exec-path`), not a general "any token":
+  widening the group to any token would have made `git log --grep commit` a denial. Five
+  asserts cover both directions.
+
+- **A ratchet region matched as a character prefix, with no path boundary.** `index(p,$2)==1`
+  meant `docs/research-extra/x.md` started with the characters of `docs/research` and spent the
+  neighbouring region's budget. A budget that absorbs a directory nobody measured stops meaning
+  anything, and it fails toward green. The prefix must now end at a `/` or at the end of the
+  path; the match stays literal (no regex — a path holding `.` or `+` would become a
+  metacharacter). A trailing slash written by hand is tolerated.
+
+- **`REFLECT_TASKS` was never actually de-hardcoded.** `hooks/README.md` said the thresholds had
+  stopped being hardcoded in v3.5.0 and were declarable through the `cadence:` line, and
+  `core/protocol.md § 2` declared the parameter with a default of 4 — but `afm_cadence_read`
+  parsed only `reflect=` and `evolve=`. The value therefore survived as a bare literal in
+  **both** readers: `REFLECT_TASKS=4` in `afm-session-end.sh` (the hook that blocks) and a bare
+  `-ge 4` in `afm-health.sh`. The library exists so two readers cannot drift, and on this one
+  parameter they had already drifted in form. `afm_cadence_read` now returns three fields and
+  the `cadence:` line takes `tasks=`, with `tasks=off` disabling the per-task arm alone —
+  symmetric with the other two keys, because a key that takes a number but not `off` while its
+  neighbours take both is the inconsistency that becomes a gotcha later.
+
+- **`afm-index.sh --self-test` asserted against the caller's live `./docs/`.** The consumer half
+  of `--triggers` reads `./docs/procedures`, `./docs/learnings`, `./docs/gotchas.md` and
+  `./docs/afm.md` relative to the caller, and the self-test ran it from wherever the operator
+  stood — with a hardcoded count of 3 procedures. It was green only from the root of the
+  repository that maintains the plugin, never green in a consumer, and `tools/test/run.sh` was
+  red when invoked from its own documented directory. **A self-test that mirrors the caller
+  tests nothing; it reports where you were standing.** It now builds its own consumer fixture
+  and runs that half inside it, while `ROOT` stays on the real plugin for the asserts that are
+  genuinely about what ships. Verified green from three different working directories,
+  including the one that was red.
+
+### Changed
+
+- **`hooks/README.md` and `core/protocol.md § 2` now show the cadence line in full** —
+  `cadence: reflect=1 evolve=3 tasks=4` — and state that every key accepts `off`.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.0-rc.9).** An instance that materialized
+  `docs/tools/gate/` holds a stale `lib/ratchet.sh`: without the boundary fix, a region in its
+  ratchet silently covers every sibling directory that shares the same prefix. `/afm:update`
+  re-copies `gate/lib/ratchet.sh`. The instance's `gate/rules/` and `gate/ratchet.tsv` are
+  **never** touched. Expect the gate to start reporting findings that were being charged to a
+  neighbouring budget; that is the fix working, not a regression.
+
+- **New optional key in `docs/_focus.md`:** `cadence:` accepts `tasks=N` (or `tasks=off`)
+  alongside `reflect=` and `evolve=`. Nothing changes for an instance that does not write it —
+  the default stays 4, exactly the literal that used to be hardcoded.
+
+## [3.9.0-rc.8] — 2026-08-28
+
+### Fixed
+
+> **Four of the eight gaps declared in `3.9.0-rc.7` are closed.** Each one landed with the
+> failing assert first: the harness reproduced the gap, then the fix turned it green. The four
+> that remain (the `git -c`/`git -C` blind spot in `afm-pre-commit.sh`, the ratchet prefix that
+> bleeds into a neighbouring region, `REFLECT_TASKS` still hardcoded, and `afm-index.sh
+> --self-test` asserting against the caller's live `docs/`) stay declared in rc.7, unfixed.
+
+- **`afm-session-start.sh` no longer names a path that does not exist.** It gained the
+  `PLUGIN_ROOT` its sibling `afm-pre-edit.sh` already had, and now resolves the frontmatter
+  index in three steps: the materialized `docs/tools/afm-index.sh` when the consumer has it,
+  the plugin copy otherwise, and — when neither resolves — **it omits the bullet entirely**.
+  The old text hardcoded the consumer path unconditionally, so following the injected
+  instruction exited 127 both in a fresh consumer and in a project that maintains the plugin,
+  where `bootstrap.md` Step 7 says the copy is skipped on purpose. An instruction that exits
+  127 costs more than a missing instruction; the hook now abstains instead of teaching a
+  broken command. Four asserts in `hooks/test/run.sh` cover the three branches.
+
+- **`hooks/README.md` said only `Stop` can refuse. `afm-pre-commit.sh` refuses too.** The file
+  documented the second carve-out in its own body since 3.5.0-rc.14 and still opened with "one
+  named, enumerated exception", including in the `Output` bullet — the line somebody reads to
+  learn what can stop them. Both lines now name the two: `decision:"block"` on `Stop` and
+  `permissionDecision:"deny"` on `PreToolUse`.
+
+- **The plugin ships 23 skills and said 22.** Corrected in `README.md` (twice),
+  `README-light.md` and `plugin.json`. `protocol` now appears in the skill tree, in the
+  overview list of `README.md`, in `README-light.md`, and `core/protocol.md` finally names
+  `/afm:protocol` — until now the only file `PRINCIPLES.md` links for the protocol layer
+  never told the reader which skill drives it. **The count is now mechanical:**
+  `test/skills-lint.sh` gained `gate_skill_count`, which compares the number a human typed
+  against the number `ls` answers. It checks per file and on the largest count in that file,
+  because `README.md` legitimately cites historical counts ("before v2.0.0 the plugin had only
+  2 skills"). Per file and not per plugin on purpose: a plugin-wide maximum would have let the
+  corrected `README.md` hide the `plugin.json` that was still wrong — which is the exact shape
+  this bug had.
+
+- **The gate saw the working tree without the files that had just been created.**
+  `scope_files worktree` asked `git ls-files` and `scope_diff worktree` asked `git diff HEAD`,
+  and an untracked file is in neither. A brand new secret (rule 13) or a brand new document in
+  the wrong language (rule 37) passed at **exit 0** — and exit 0 from a gate reads as "I looked
+  and it is clean", never as "I did not look". `worktree` now adds `git ls-files --others
+  --exclude-standard`, and `scope_diff` synthesizes the missing diff with `git diff --no-index
+  /dev/null <file>`, which is read-only (`git add -N` would give the same output by writing to
+  the index, and a gate does not write). `--staged` deliberately still ignores them: a file
+  nobody added is not entering this commit, and failing on it would be the false positive that
+  makes people work around the gate. Measured on this repository after the fix: an untracked
+  doc carrying an absolute path takes `--worktree` to exit 1 and leaves `--staged` at 0.
+
+### Changed
+
+- **`plugin.json`'s `description` is now English** (hard rule 37). It was the largest piece of
+  Portuguese prose left on a consumer-facing surface — it is what the marketplace displays.
+
+- **`scope_all` reads `AFM_GATE_MODE`**, exported by `guardrails.sh`. Its signature stays
+  `scope_all [pathspec...]`: every runner in this repository, and every runner a consumer has
+  already written, calls it that way, so growing a mode parameter would have been a breaking
+  change for consumers.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.9.0-rc.8).** An instance that materialized
+  `docs/tools/gate/` holds a **stale copy of `lib/scope.sh`**, which is the file that decides
+  what `--worktree` can see. `/afm:update` re-copies `gate/lib/scope.sh` and
+  `gate/guardrails.sh` over the instance's copies. The instance's own `gate/rules/` and
+  `gate/ratchet.tsv` are **never** touched: a runner encodes that project's rule and the
+  ratchet holds measured debt. Expect `--worktree` to find debt it could not see before; that
+  is the point of the fix, and it is not a reason to rebaseline the ratchet without looking.
+
+- The hook and documentation fixes need nothing from the consumer: hooks travel with the
+  plugin, and no materialized file changed because of them.
+
+## [3.9.0-rc.7] — 2026-08-27
+
+### Known gap
+
+> **This release changes no behaviour.** It is a declaration. An external probe of the plugin
+> at three intensities produced 12 findings; each one was then handed to an independent
+> validator whose default posture was REFUTED and whose job was to reproduce it against the
+> real tree. **Two were refuted** and are recorded below so they are not re-found. The eight
+> that survived are declared here, unfixed, because a gap that is written down is cheaper to
+> reason about than a gap that is fixed in the same breath it is discovered.
+
+**Reachability — the two that reach a consumer first.**
+
+- **`afm-session-start.sh` names `docs/tools/afm-index.sh` and `afm-detect.sh` in the context it
+  injects into every session, and no procedure ever puts those two files there.**
+  `interview/bootstrap.md` and `interview/refactor.md` enumerate a closed list for
+  `<consumer>/docs/tools/` — `afm-cost-ledger.sh`, `afm-outcome-join.sh`, `README.md`, `gate/` —
+  and `afm-index.sh`, `afm-detect.sh`, `afm-lang.sh` appear in no consumer-facing procedure at
+  all. Following the injected instruction exits **127**, in a fresh consumer and in this
+  repository today. The sibling hook already does it right: `afm-pre-edit.sh` resolves the same
+  scripts through `${CLAUDE_PLUGIN_ROOT}/framework-template/tools/`. The session-start hook has
+  no `PLUGIN_ROOT` at all — it hardcodes a consumer-relative path into prose.
+
+  Note the shape: **the index the whole of 3.9.0 was built to make cheap is the thing the
+  consumer cannot run.** `bootstrap.md` states that a project maintaining the plugin *skips*
+  the copy on purpose, so pointing at a consumer-relative path unconditionally is wrong on both
+  sides of that fork, not merely stale.
+
+- **`README.md`, `README-light.md` and `plugin.json` all say 22 atomic skills; 23 ship.**
+  `protocol` is the one missing from every newcomer-facing enumeration, and `core/protocol.md`
+  — the only file `PRINCIPLES.md` links for the protocol layer — never names `/afm:protocol`.
+  A skill absent from the surface a newcomer reads is a skill that does not exist for them.
+  `CHANGELOG.md` already counts 23, so the disagreement is internal.
+
+**Mechanism — a gate that answers when it should abstain, or abstains where it should answer.**
+
+- **`--worktree` never sees an untracked file.** `scope_diff`, `scope_files` and `scope_all` in
+  `tools/gate/lib/scope.sh` build their scope from `git diff HEAD` and `git ls-files`. A file
+  that was just created and never staged is in neither. A brand-new secret (rule 13) or a
+  brand-new Portuguese doc (rule 37) passes the worktree gate at **exit 0** — and exit 0 from a
+  gate is read as "checked and clean", not as "did not look".
+
+- **`ratchet_region` matches a region as a bare character prefix.** `index(p, $2) == 1` in
+  `tools/gate/lib/ratchet.sh`, with no path-boundary test, so `docs/research-extra/…` is
+  absorbed into the budget configured for `docs/research`. Debt lands in a neighbour's budget
+  and the gate stays green. Same family as the count that always answers zero: it fails in the
+  direction that looks like it works.
+
+- **The `git commit` detector in `afm-pre-commit.sh` misses `git -c K=V commit` and
+  `git -C DIR commit`.** The pre-subcommand group tolerates only single-token global options,
+  so any global option carrying a separate-token value slips the match and the tier-3 gate
+  **no-ops instead of denying**. The fix has to enumerate the separate-value options rather
+  than accept a wildcard token, or it will deny on a pathspec.
+
+**Doc-versus-code.**
+
+- **The `REFLECT_TASKS` threshold was never actually de-hardcoded.** `hooks/README.md` states
+  the thresholds "stopped being hardcoded in v3.5.0" and are "declarable per project via the
+  `cadence:` line", but `afm_cadence_read()` in `lib/afm-cadence.sh` parses only `reflect=` and
+  `evolve=` and echoes two fields. The task threshold is the literal `REFLECT_TASKS=4` in
+  `afm-session-end.sh` and a bare `-ge 4` in `afm-health.sh`. The single-source library exists
+  precisely to stop two readers from drifting, and the two readers have already drifted in
+  form — one names a variable, the other does not. The hook that **blocks** holds one of the
+  two copies.
+
+- **`hooks/README.md` still says no hook returns `decision:"block"` except `Stop`.**
+  `afm-pre-commit.sh` returns `permissionDecision: "deny"`. The file names that script once and
+  contradicts it in the bullet a reader consults to learn what can stop them.
+
+- **`afm-index.sh --self-test` asserts against the caller's live `./docs/`, not a fixture.**
+  It passes only when the cwd is this repository's root, and its hardcoded count of three
+  procedures can never be green in a consumer project — so the documented smoke test
+  (`tools/README.md` § Self-test, `./test/run.sh`) is red from its own documented directory. A
+  self-test that reads the tree it is meant to be independent of measures the caller, not the
+  code.
+
+**Refuted — recorded so they are not re-found.**
+
+- *"The Portuguese `**Gatilho:**` spelling is invisible to `afm-pre-edit.sh`."* The behaviour
+  reproduces, and it is already declared verbatim in this changelog's own consumer-migration
+  note for 3.6.0, and again as a known gap in 3.9.0-rc.6. Declared is not defective.
+- *"`--writes` reports a path that does not exist."* A misreading. An op's `writes:` is a
+  consumer-relative **output contract**, not an assertion about a path in the plugin tree.
+
+**Two more sit in this repository's instance, not in the plugin**, and are recorded in
+`docs/_focus.md` rather than here: `CLAUDE.md` counts 7 hook scripts where 8 ship and calls
+`Stop` the only blocking hook, and `docs/.afm-version` is pinned at `3.5.0-rc.8` against a
+`3.9.0-rc.6` watermark, so vital sign A3 reports drift on every session.
+
+- **Consumer-noop.** No file a consumer materializes changed. `CONSUMER_VERSION` stays at
+  `3.9.0-rc.6`.
+
+## [3.9.0-rc.6] — 2026-08-27
+
+### Added
+
+- **Every family with a trigger reaches the index — 58 entries across six of them.** Rubric
+  (12), gotcha (26), hard rule (13), guardrail (3), procedure (3), learning (1). The whole
+  index is **~2,157 tokens** against the **~35,465 tokens** of the bodies it stands in for.
+
+- **`fires_on` gained `event` and `cadence`**, and those two values are the honest part of this
+  release. They mark a trigger that **cannot fire on its own** — a moment a human recognizes.
+  A `procedure` that starts "when a release is about to be cut" will never be fired by a hook,
+  and it still belongs in the index, because the question it answers is not "what fires now"
+  but "is there a runbook for this".
+
+  An `event` or `cadence` entry carries **no `trigger_*` key**, and hard rule 39 now fails one
+  that does. Fabricating a mechanical field for a human judgment would dilute exactly what the
+  mechanical families earned by being genuinely mechanical.
+
+### Fixed
+
+- **The survey in 3.9.0-rc.5 answered the wrong question, and the owner caught it.** Four
+  families were assessed and all four said no. Every one of those verdicts was about
+  **firing at write time**, which needs a mechanical file-shape trigger — and on that question
+  they were right. None of them was about **discovery**, which needs nothing mechanical at all:
+  only the condition written where a reader can see it without opening the body.
+
+  Two separable benefits behind one word. Procedures are the family where the second one pays
+  most: three runbooks whose start condition lived in a `When to run it` bullet inside the
+  body, so answering "is there a runbook for this?" meant opening all three. This repository
+  reached 2026-08 with **26 gotchas and 3 procedures**, and the family nobody creates is the
+  family nobody can find.
+
+### Changed
+
+- **Gotchas and hard rules are indexed WITHOUT frontmatter**, and that is deliberate. Each is a
+  section of one file, never a file of its own, so there is no frontmatter block to carry and
+  there never will be. They are already structured — a `**Trigger:**` line under a heading, a
+  numbered rule with a `*Verification:*` — so the index reads that structure directly. The
+  point is one cheap line per decision surface, not one YAML block per artifact.
+
+- The gotcha reader accepts **both spellings** of the field. A consumer bootstrapped before the
+  english-first migration still writes the Portuguese one, and reading only the English
+  spelling would make every gotcha in such a project invisible to the index — the exact failure
+  hard rule 38 exists to catch, reached by "fixing" the parser.
+
+- `procedure.template.md` and `learning.template.md` declare the frontmatter their output
+  needs, so a new runbook is born discoverable instead of being retrofitted.
+
+### Verification
+
+- `afm-index.sh` 14 → **16** asserts, tools harness **49**, hooks **101**, gate green. Two of
+  the new asserts are structural rather than behavioural: the set of families in the index is
+  compared as a whole, so a refactor of `cmd_triggers` that silently drops one fails; and a
+  procedure reaching the index with a non-empty condition is asserted, because an entry with an
+  em dash where the condition should be looks identical to a family that was never wired.
+
+### Known gap
+
+- **The `learning` entry declares `trigger_path` and nothing new fires it.** `afm-pre-edit.sh`
+  already greps the `Trigger:` line in the body by path match, and duplicating that in the
+  detector would be a second mechanism for one fact (rule 34). The frontmatter serves discovery
+  here; the existing hook still serves firing.
+
+- **`afm-pre-edit.sh` matches only the English `Trigger:` in gotchas.** The index reads both
+  spellings now; the hook does not. A consumer bootstrapped before the migration gets its
+  gotchas in the index and not at write time.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.9.0-rc.5` → `3.9.0-rc.6`. `/afm:update` adds the
+  frontmatter block to `docs/procedures/` and `docs/learnings/` where it is missing, and never
+  rewrites a `When to run it` bullet the owner wrote.
+
+## [3.9.0-rc.5] — 2026-08-27
+
+### Added
+
+- **Every rubric declares its own trigger in frontmatter, and the detector interprets instead
+  of hardcoding.** The keys are flat, because AFM frontmatter is flat and the reader is shell:
+  `fires_on` (`file-shape` | `repo-shape` | `op-call`), `trigger_path`, `trigger_ext`,
+  `trigger_basename`, `trigger_grep`, `trigger_min_lines`, `trigger_max_consumers`,
+  `trigger_new_module`, `trigger_any`, `fires_when`. A new rubric now ships with a trigger and
+  touches no shell.
+
+  This closes a violation of hard rule 34 that release 3.9.0-rc.4 had created: the six
+  detectors were shell functions holding numbers (`3` sites, `150` lines) transcribed by hand
+  from the prose of the rubrics they implement. Two sources of truth for one trigger, in the
+  file that exists to deliver the rubrics.
+
+- **`afm-index.sh --triggers`** — the cheap index for ordinary research, not for a hook. The
+  hook answers "does this rubric fire on the file I am writing"; an agent reasoning about work
+  that has no file yet asks "what does AFM have a trigger for at all", and the only way to
+  answer that used to be reading twelve rubrics. `afm-session-start.sh` names the command once
+  per session, which is what makes it reachable outside a hook.
+
+### Fixed
+
+- **`says:` was renamed `fires_when:`, and the rename was earned by a measurement.** A routing
+  experiment gave one arm the 417-token index and another the 13,152 tokens of rubric bodies,
+  over five scenarios. The cheap arm routed correctly in 4 of 5 — and in `when-to-create-lib`
+  it named the right rubric and then **advised the opposite of what that rubric says**, because
+  the agent read the one-line value as the rubric's guidance instead of as a pointer.
+
+  `tools/README.md` had already written the rule this broke: *"There is no `summary:` key on
+  purpose — a summary is a derived duplicate, and when it goes stale the reader believes a
+  wrong fact and never opens the file to find out."* A field named `says` invites exactly that
+  reading. Every value is now a condition with no verdict in it, and the index output opens
+  with `# these are TRIGGERS, not decisions. Open the named file to decide.` — asserted,
+  because the failure existed before the line did.
+
+- **`solid-triggers` declared only its SRP trigger.** The fifth scenario was an OCP case (a
+  provider `switch` spread across two files) and the index simply did not contain that shape,
+  so no agent could route to it. A rubric with five principles needs a trigger for each one
+  that has a shape. `trigger_any: yes` makes the conditions a disjunction — SRP fires on the
+  file NAME and OCP on the CONTENT, and requiring both would mean neither ever fires.
+
+- **Re-tested, both defects gone.** Same two scenarios, after the change: correct rubric,
+  guidance judged `equivalent` to the full-bodies arm, and both agents reported
+  `read_index_as_advice: false`.
+
+### Measured
+
+- **The honest saving is about 8x, not 33x.** The index alone is 33x smaller than the bodies,
+  but in the fixed round both agents did what the design intends: read the index, then open the
+  ONE rubric it named. That is ~1,513 tokens against ~13,152 — and it is the correct number to
+  quote, because the alternative reading (417 tokens, file never opened) is precisely the
+  failure this release removed.
+
+- **Four other families were surveyed for the same technique and all four say no**, with
+  different reasons. `gotchas` (26): half have a path trigger and half have no path at all —
+  a spoken cue, a runtime 403, an agent-output signal — so declaring keys would either split
+  the family in two or fabricate mechanical confidence that dilutes what rubrics and guardrails
+  earned by being genuinely mechanical. `learnings` (1): nothing to index across, and the
+  trigger carries an open clause no glob captures without silently narrowing it.
+  `procedures` (3): two fire on an event in a DIFFERENT repository or on release cadence, and
+  the third's trigger is already hard rule 30's, owned elsewhere. `hard rules` (13): already
+  carry a versioned runner in the gate; frontmatter would be a third representation.
+
+  The technique fits when the trigger is "the file I am about to write matches a pattern".
+  Rubrics and guardrails are the two families that satisfy that. The others answer a different
+  question, and forcing the shape on them would cost more than it returns.
+
+### Verification
+
+- `afm-index.sh` 10 → **14** asserts, `afm-detect.sh` **23**, tools harness **49**, hooks
+  **101**, all at 0 fail. Repo parity held exactly through the rewrite: the same 33 findings
+  before and after the detector stopped hardcoding. Per-file cost measured at **48-53 ms**,
+  inside the hook budget.
+
+- Hard rule 39 now covers the rubric contract: no `fires_on:` in the closed vocabulary and no
+  `fires_when:` fails the gate, so a rubric cannot be born invisible to the index.
+
+- Three parser defects were caught by the asserts on the way, all of the same family — the data
+  and the parser disagreeing. YAML-style escapes read raw (`\\(` became an empty group);
+  `fm()` truncating prose at the first comma because it was built for lists; and
+  `grep -c '^rubric\t'` counting zero because `\t` is not a tab escape in a POSIX pattern.
+  **That last one reads exactly like "no rubric declares a trigger"**, and would have been
+  believed.
+
+### Known gap
+
+- **The `op-call` rubrics have no mechanical check that their caller still calls them.** Five
+  rubrics declare `called_by: [...]` and nothing verifies the named op still reads the file —
+  which is the same class as the dead parsers found in 3.9.0-rc.2, one level up.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.9.0-rc.4` → `3.9.0-rc.5`. `/afm:update`
+  materializes the rubric frontmatter and both tools through the existing rows.
+
+## [3.9.0-rc.4] — 2026-08-27
+
+### Added
+
+- **Six more rubrics gained a code-shape detector**, so every rubric in the catalogue now has a
+  delivery. `afm-detect.sh` grew `validation-boundary` (a schema parser inside a `domain/`
+  path), `error-classification` (a transport error type or a bare `Error` raised from the
+  domain), `enum-vs-union-vs-branded` (a TS `enum` declaration, or two adjacent `string`
+  parameters — the rubric's own `copy(from, to)` example), `solid-triggers` (SRP: a file named
+  for a manager, a utils bag, or two responsibilities), `when-to-create-lib` and
+  `when-to-create-module`.
+
+- **`--rubrics`**, the repo-wide uncapped report, next to the per-file `--for` the hook calls.
+
+### Fixed
+
+- **The gap was 6, not 11.** Release 3.8.0-rc.2 recorded "the other 11 rubrics still have no
+  trigger". Five of those eleven were never untriggered: they have a **caller**, which is the
+  other valid form of delivery. `failure-classification` is read by `ops/remediate.md`,
+  `negative-filters` by `remediate` and `reconcile`, `episodic-vs-semantic-boundary` by
+  `reconcile` and `reflect`, `template-vs-streaming-precedence` by `export-template` and
+  `reconcile`, `when-to-evolve-methodology` by `ops/evolve.md`. An op that reads a rubric in
+  order to decide IS that rubric being delivered. Counting a listing in `README.md` and a
+  caller in an op as the same thing is what produced the wrong number.
+
+### Verification
+
+- **Two orphaned self-tests were never being run, and that is why the detector could rot.**
+  The tools harness named its tools one by one, so `afm-detect.sh` (23 asserts) and
+  `afm-index.sh` (10) were each shipped with a self-test that no harness ever executed — 33
+  asserts that reported nothing because nothing asked them. The harness now DISCOVERS every
+  tool carrying `--self-test` instead of listing them, which is the only version of this fix
+  that survives the sixth tool. It goes 47 → **49** at the harness level, and the 33 asserts
+  underneath now actually run.
+
+- The detector self-test goes 5 → **23**, the hooks harness 98 → **101**, both at 0 fail.
+  Every detector carries a negative assert beside its positive one, because a detector that
+  fires on an ordinary file makes the whole channel ignorable — and an ignored channel still
+  looks like coverage.
+
+- **Two measured traps, both self-tested now.** The lib row reads "more than ~150 lines of pure
+  logic **coupled to one consumer**", and shipping the size half alone produced **48 hits over
+  426 source files** here, almost all of them large modules with many importers. Adding the
+  consumer count brought it to 17. Inside that fix, a second trap: the count was anchored at
+  the basename, and TypeScript under NodeNext writes `from "./mod.js"` for a `.ts` file, so it
+  matched nothing and reported "0 consumer" for every file in a real package. **A filter that
+  always answers zero is not a filter**, and it fails in the direction that looks like it works.
+
+- One assert in the hooks harness failed for the same reason a gate failed earlier in this
+  release line: it counted every occurrence of `docs/rubrics/`, and the header of the injected
+  block quotes that path itself. **A check over a literal needs a positional anchor when the
+  text around it discusses the literal.** Third time this exact shape has been paid for here.
+
+### Known gap
+
+- **Noise is bounded but not measured in use.** 33 findings across 426 source files in this
+  repository, capped at 2 per file. Whether that reads as signal at the moment of an edit is a
+  judgment only real sessions can return.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.9.0-rc.1` → `3.9.0-rc.4`. `/afm:update`
+  materializes the widened `docs/tools/afm-detect.sh` through the existing `docs/tools/` row.
+
+## [3.9.0-rc.3] — 2026-08-27
+
+### Changed
+
+- **The 7 Portuguese-named gate runners were renamed.** The rule NUMBER is the identity and it
+  never moved; only the slug did. The 5 runners already in English were not touched.
+
+  | before | after |
+  | --- | --- |
+  | `13-segredos.sh` | `13-secrets.sh` |
+  | `21-idioma.sh` | `21-code-language.sh` |
+  | `34-fonte-unica.sh` | `34-single-source.sh` |
+  | `35-portao-completo.sh` | `35-gate-complete.sh` |
+  | `36-path-absoluto.sh` | `36-absolute-path.sh` |
+  | `37-idioma-prosa.sh` | `37-prose-language.sh` |
+  | `38-marcador-de-parser.sh` | `38-parser-marker.sh` |
+
+  19 references moved across 6 files. Nothing about the gate's behaviour changed: the
+  aggregator discovers `rules/*.sh` and parses the leading number, and the ratchet is keyed by
+  rule and region, never by file name.
+
+- **The 3.9.0-rc.2 "Known gap" reasoning was wrong, and this release says so rather than
+  editing it.** That entry argued the rename would leave historical CHANGELOG links dead by
+  construction, because history is not editable. The distinction it missed: a dead POINTER is a
+  defect whatever the age of the prose around it, while a NAME that a sentence makes a claim
+  about is content. So the paths moved everywhere, no sentence was reworded, and the one place
+  where an old name is the SUBJECT of a claim — the rc.2 gap entry itself, which says the names
+  are still Portuguese — keeps the old spelling. A path-only rewrite there would have produced
+  a sentence saying the names are still Portuguese while naming the English ones.
+
+  That single spot is also what the three verification lenses did not catch. All three came back
+  clean, correctly: the edit WAS path-only, so a collateral-damage lens looking for reworded
+  prose had nothing to find. The defect was semantic, and no lens was asked about meaning.
+
+- **Consumer-noop.** `test/` does not travel and no consumer materializes a runner. The
+  watermark stays at `3.9.0-rc.1`.
+
+## [3.9.0-rc.2] — 2026-08-27
+
+### Fixed
+
+- **Three dead mechanisms, found by translating the gates that were exempt from finding them.**
+  Rule 38 catches "the data was translated and the parser was not". `test/` was exempt from it
+  by an explicit decision — those gates speak to the maintainer and are not distributed
+  surface. The operator overturned that on 2026-08-27: code, a test, and a comment are English,
+  and no request overrides it. Lifting the exemption and translating the 19 scripts turned up
+  three parsers left on a spelling nothing produces any more:
+
+  1. **Rule 34's check (a) had matched zero files since the english-first migration.** It
+     grepped the Portuguese `princípio invariante #` while the ops had become
+     `invariant principle #`. It looked healthy because the ratchet still recorded 6 and 0 is
+     under 6 — **a dead check and a satisfied budget are the same shape from outside.** With
+     the right spelling the count is 6 again, the number the debt entry always described.
+  2. **The plugin-effect boundary in `refs-lint.sh` extracted the empty string from every op.**
+     The `sed` matched `**Forma** — efeito:` while the check immediately above already required
+     the English `> **Form** —`. This is the guard that no op declares an effect on the plugin —
+     a bright line, silently unguarded. Revived, and it passes clean.
+  3. **`update-rehearsal.sh` asserted that a Portuguese heading was absent** from hook output
+     that had said `Current protocol` for releases. The assert could only pass.
+
+  A fourth was found next to them, of a different kind: `skills-lint.sh --self-test` had been
+  red since commit `4bb5d95` because it named a real debt row that the same commit fixed. **No
+  gate ran it.** The fixture is now synthetic — an assert about the LOGIC of `is_known_debt`
+  must not depend on what the repo currently owes — and rule 31's runner now runs the self-test
+  before the lint, so it cannot rot in silence again.
+
+- **`refs-lint.sh` is green for the first time.** `interview/triggers.md` (104 lines, 5
+  sections) had no scope indicator.
+
+### Changed
+
+- **`test/` is no longer exempt from rule 38**, and `ste-batch-check.sh` no longer carries its
+  own Portuguese dictionary — it calls `tools/afm-lang.sh`, so it and rule 37 can no longer
+  disagree about the same file (rule 34). Its old dictionary included words the measured list
+  deliberately excludes.
+
+- Three exemptions remain, and each one is data rather than instruction: the multibyte fixture,
+  the Portuguese paragraph that is the INPUT of the new language assert, and the dictionary of
+  `afm-lang.sh` itself. Translating that last one would turn rule 37 off entirely.
+
+### Known gap
+
+- **The runner file names are still Portuguese** (`13-segredos.sh`, `37-idioma-prosa.sh`, and
+  the rest). Renaming them is mechanical but it breaks the links in `docs/afm.md` and leaves
+  every historical CHANGELOG entry pointing at a name that no longer exists — history is not
+  editable, so those links would stay dead by construction. It is a separate decision, not a
+  side effect of this one.
+
+- **Consumer-noop.** `interview/` is read from the plugin and never materialized, and `test/`
+  does not travel. The watermark stays at `3.9.0-rc.1`.
+
+## [3.9.0-rc.1] — 2026-08-27
+
+### Added
+
+- **`tools/afm-lang.sh` — the language rule, moved to the moment of writing.** Hard rule 37
+  said the prose of an artifact is English and held a runner that ran at commit time over
+  `*.md` alone. The rule was never wrong. It arrived after the write.
+
+  Measured 2026-08-27, and the measurement is this session: the operator asked in Portuguese,
+  the agent wrote the artifact in Portuguese, and the block came minutes later from the commit
+  gate. **A request made in Portuguese is not a request FOR Portuguese** — that conflation is
+  the failure mode, and no amount of restating the rule in a document had removed it.
+
+  The tool holds the measurement: density of Portuguese function words in prose, the threshold
+  of 1.0 measured in 2026-08 between an English population that peaks at 0.69 and a Portuguese
+  one that bottoms at 1.52. It answers a verdict AND the tier the text belongs to.
+
+- **Rule 37 gained two tiers, and they are not the same strength.** Code, a test, and a
+  comment are **inalienable** — no explicit request overrides them, which restates rule 21 for
+  the surface rule 21 had left in judgment. A **document is English by default and the
+  operator may override it explicitly**, because a doc has one human audience and that choice
+  is theirs. The override has to be stated, never inferred from the language of the request.
+
+### Changed
+
+- **`afm-pre-edit.sh` runs the language verdict before the `docs/` guard** — the only family
+  that does. Every other one is about product code, so skipping meta-work is right for them;
+  the language rule is broken precisely inside a document. The line names the tier, so the
+  agent is told which of the two it is looking at.
+
+- **`test/rules/37-prose-language.sh` delegates to the tool instead of holding a copy** of the
+  threshold (rule 34). Two copies of a measured threshold drift apart in silence, and the
+  commit gate would then contradict the hook that had just approved the write. Proved
+  behaviour-preserving: the same 31 files, byte for byte, before and after the delegation.
+
+  The delegation had one defect on its first run and the calibration caught it: `if ! cmd`
+  cannot tell an accusation (exit 1) from an abstention (exit 2, text too short to be a
+  ratio), and collapsing the two reported **83 extra files** — every short eval fixture.
+
+### Verification
+
+- The tools harness goes 43 → **47**, the hooks harness 94 → **98**, both at 0 fail. The
+  asserts that carry weight: a Portuguese doc under `docs/` gets the line at all (it is past
+  the guard that used to eat it), code and doc get *different* tiers, English stays silent,
+  and a `docs/` write with no content is still a no-op — that last one fails if the language
+  block is ever moved below the guard.
+
+### Known gap
+
+- **Rule 37 is still local to this repository.** Promoting it into `core/afm.md`, where every
+  consumer would inherit it, is a methodology change under hard rule 11 and belongs to its own
+  decision, not to the release that built the mechanism.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.8.0-rc.2` → `3.9.0-rc.1`. `/afm:update`
+  materializes `docs/tools/afm-lang.sh` through the existing `docs/tools/` row.
+
+## [3.8.0-rc.2] — 2026-08-27
+
+### Fixed
+
+- **The failure capture named runners, and a runner is what changes per project.** The oracle
+  guard in `afm-capture-failure.sh` was a closed list of literal toolchain strings
+  (`npm test`, `jest`, `pytest`, `go test`, `tsc`, `eslint`, `cargo build`) with `exit 0` on
+  default. The closure was right about noise and wrong about coverage.
+
+  Measured across 24 AFM projects on 2026-08-27: **4 failure records in total**, and **no
+  signature ever reached the 2 occurrences hard rule 19 requires**. So `remediate` had never
+  had valid input anywhere, and the three artifact families that only it can create were never
+  born: **5 procedures, 1 learning, 1 guardrail across 24 projects** — against 395 gotchas and
+  261 ADRs, and every one of those 7 hand-made in the AFM repository itself. The families that
+  work are the ones whose creation does not route through this pipe.
+
+  In one monorepo, 3 of its 4 scripts matched nothing: `turbo run test`, `biome check .` and
+  `bun test` were invisible, while `turbo run typecheck` matched only by the accident of
+  containing the substring.
+
+  The guard now matches the **verb**, which is stable across toolchains, instead of the runner.
+  Quoted text is stripped first, so `git commit -m "fix the test"` is not a test oracle, and a
+  deny-list keeps reader commands (`grep`, `cat`, `--help`) out. `bun`, `deno`, `cargo clippy`,
+  `rake`, `mix`, `make` and any `<runner> run <verb>` now land in the right bucket.
+
+### Added
+
+- **`tools/afm-detect.sh` — delivery for the rubrics whose trigger is a code shape.** Every
+  other family AFM injects at write time matches on a path. The rubrics have none:
+  `when-to-create-dsl.md` fires on "3 or more call sites repeating the same fixed-order
+  sequence", which no path match can see. Measured before this release:
+  `grep -c rubric afm-pre-edit.sh` returned **0**, and the only mention of rubrics in the whole
+  runtime was one clause of one SessionStart bullet — a pointer, not a trigger. The best
+  content in the framework reached the agent never.
+
+  The detector finds repeated call sequences across files, filtering test paths, generated
+  code and assertion vocabulary. On one real repository: 173 raw candidates fell to **39** after
+  filtering, in **89 ms**, and the survivors are genuine — a form-action wiring repeated across
+  7 components, the `addEventListener`/`removeEventListener` pair across 6, zod schema
+  construction across 11.
+
+  `afm-pre-edit.sh` now injects **one line** when the file being edited is one of the sites,
+  naming the sequence and the rubric. It names the rubric rather than quoting it: the point is
+  to let the agent open the decision table, and a hook that pastes the table has defeated
+  itself.
+
+- 10 asserts in the hooks harness (84 → **94**): the verb guard across six toolchains, the
+  three adversarial non-oracles, the rubric reaching a file that is a site, and — the one that
+  matters for noise — a file that is *not* a site getting nothing.
+
+### Known gap
+
+- **One detector, one rubric.** The other 11 rubrics still have no trigger. Generalizing the
+  detector before a second real shape exists would be inventing the abstraction (YAGNI); the
+  next shape decides the interface.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.8.0-rc.1` → `3.8.0-rc.2`. `/afm:update`
+  materializes `docs/tools/afm-detect.sh`.
+
+## [3.8.0-rc.1] — 2026-08-27
+
+### Added
+
+- **Frontmatter across the methodology, and an index that reads it.** All 62 files under
+  `ops/`, `core/`, `rubrics/`, `templates/`, `templates/protocols/` and
+  `interview/` now carry frontmatter. `tools/afm-index.sh` answers "which file matters for
+  what I am doing" from that metadata alone: `--writes`, `--composes`, `--used-by`,
+  `--orphans`, `--kind`, `--for`, plus `--self-test` with 10 asserts.
+
+  Measured on the 21 ops: the whole index is **314 tokens** against **58,839 tokens** of
+  bodies — 0.5%. "Who writes `tasks.md`" costs 83 bytes through the index; guessing at it
+  costs about 11.6k tokens of speculative reading.
+
+  Before this, frontmatter existed only where a machine already read it — 23/23 skills,
+  the guardrails, the session records. The files an agent must decide whether to open had
+  none: `ops/` was 0 of 21. The retrieval key was already there in four dialects (a prose
+  `Trigger:` in gotchas, the same in learnings, real frontmatter in guardrails,
+  `when_to_use` in the skills), so this consolidates as much as it adds.
+
+- **Hard rule 39** — an indexed file declares a `kind:`, an op declares `writes:` and
+  `composes:`, and a `composes:` must resolve to a real op. Runner:
+  `test/rules/39-frontmatter-ops.sh` in the AFM repository. It found a real gap on its
+  first run: `guardrail.template.md` had frontmatter and no `kind:`.
+
+### Decided
+
+- **No `summary:` key.** Every key is a property OF the file, so no edit to a body can make
+  its frontmatter false. A summary is a derived duplicate; when it goes stale the reader
+  believes a wrong fact and never opens the file to find out, because skipping the file was
+  the whole point. `used_by` is a fact about the rest of the tree, so it is derived on
+  every call rather than stored, for the same reason the index itself is never written to
+  disk.
+
+### Fixed
+
+- `templates/guardrail.template.md` gained `kind:` and `renders_to:`, keeping the
+  `id`/`origin`/`surface`/`trigger`/`cost` keys it already had.
+
+### Known gap
+
+- **Nothing calls the index yet.** Wiring it into `afm-pre-edit.sh` was built and then
+  reverted: that hook exits on `*/docs/*` by design, and every path an op writes to is
+  under `docs/`, so the branch was dead on arrival. Until a caller exists this is a
+  documented step rather than a mechanism. Rule 39 keeps the metadata true; it does not
+  make anything consult it.
+
+### Found
+
+- `templates/protocols/p2.md` is referenced by nothing, while `p1.md` and `p3.md` are.
+  Surfaced by `--orphans` as a byproduct. Not changed — it may be deliberate.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.7.0-rc.2` → `3.8.0-rc.1`. `/afm:update`
+  materializes `docs/tools/afm-index.sh`. The frontmatter itself rides on files the
+  consumer reads from the plugin, so nothing else changes in the instance.
+
+## [3.7.0-rc.4] — 2026-08-26
+
+### Fixed
+
+- **The health cache served the answer from before the bump.** `afm-health.sh` keys its daily
+  cache by project and day. A bump is exactly when vital sign A3 has something new to say, so
+  the operator asked on the one day it mattered and read yesterday — the `3.7.0-rc.3` fix was
+  invisible in the same session that shipped it. The watermark is now part of the key, so a
+  bump invalidates the cache the moment it lands. Measured with the cache warm: the reported
+  watermark follows the file inside one session.
+
+- **This release exists because hard rule 30 refused the amend, and it was right.** Under
+  `git commit --amend` the bumps already sit in `HEAD`, so the index does not carry them and
+  the runner reported a surface change with no bump. A change to `hooks/` is installable
+  surface and earns its own version.
+
+- **Consumer-noop.** `hooks/` is read from the plugin, never materialized. The watermark stays
+  at `3.7.0-rc.2`.
+
+## [3.7.0-rc.3] — 2026-08-26
+
+### Fixed
+
+- **The watermark stopped moving, and vital sign A3 went blind.** `CONSUMER_VERSION` sat at
+  `3.6.0-rc.6` while `VERSION` reached `3.7.0-rc.2`. A3 in `afm-health.sh` compares the
+  instance against the watermark, not against `VERSION`, so every instance pinned at
+  `3.6.0-rc.6` or later was told there was no drift — and nobody was told to run
+  `/afm:update`. The four releases skipped were `3.6.0-rc.10`, `3.6.0-rc.11`, `3.7.0-rc.1`
+  and `3.7.0-rc.2`, and two of them carry the largest consumer-facing delta the plugin ever
+  shipped: `tools/` and `tools/gate/`, both declared new in `ops/update.md`. The gate the
+  previous two releases went to the trouble of distributing reached no consumer at all.
+  The four entries now declare their consumer impact and the watermark moves to
+  `3.7.0-rc.2`, which is the newest release with materializable content.
+
+### Added
+
+- **Hard rule 30 now checks the declaration, not only the three files.** The declaration
+  discipline was documented in the maintainer runbook, and it held for about 24 releases
+  before it lapsed in silence four times in a row. Hard rule 35 asks that a documented human
+  step with a 0/1 trigger get a versioned runner, and this one has a clean trigger inside the
+  repository: a staged bump of `VERSION` whose release block declares neither
+  `Consumer-facing` nor `Consumer-noop` is a violation, and a block that declares
+  `Consumer-facing` without `CONSUMER_VERSION` in the same index is a violation. The
+  objection that kept `marketplace-sync.sh` out of the gate does not apply — that one reads
+  `~/.claude/plugins/cache`, which is machine state, while both files here are versioned.
+
+- **Consumer-noop.** The runner is a repository-level gate in the AFM project. It is not
+  materialized, and nothing in `<consumer>/docs/` changes. The watermark stays at
+  `3.7.0-rc.2`.
+
+## [3.7.0-rc.2] — 2026-08-26
+
+### Fixed
+
+- **`--repo` was decorative.** The aggregator accepted the flag, and never entered the
+  directory. `git ls-files` answers about the CURRENT directory, so `scope_all` and
+  `scope_files` measured whatever tree the operator happened to stand in, and reported it under
+  the target's name. Called from the AFM repository with `--repo <other project>`, the gate
+  returned findings in `plugins/afm/`. From a subdirectory of the right repository it would
+  silently measure only that subdirectory — a false negative in exactly the class `scope.sh`
+  warns about. The aggregator now enters `$REPO` before it runs anything, after making every
+  path absolute. A regression assert fails when the `cd` is removed.
+
+### Verified
+
+- **The refutation of ADR 0017 was tested, and did not refute.** Four unrelated repositories on
+  one machine, none of them AFM consumers, three plausible TypeScript rules, nothing written
+  into any of them. All four started red, `--baseline` recorded debt between 0 and 26 findings,
+  and all four ended green. That test is what found the `--repo` defect above.
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.6.0-rc.6` → `3.7.0-rc.2`. The fix is inside
+  `tools/gate/guardrails.sh`, which the instance materializes — a consumer that copied the
+  rc.1 aggregator has the defective one.
+
+## [3.7.0-rc.1] — 2026-08-26
+
+### Added
+
+- **`tools/gate/` — the plugin distributes the gate, not only a description of it.** The
+  aggregator (`guardrails.sh`), the two sourceable libraries (`lib/scope.sh`, `lib/ratchet.sh`),
+  the ratchet seed and an empty `rules/` now materialize into `<consumer>/docs/tools/gate/`.
+  Before this release `ops/rule.md` carried six mature steps to turn a hard rule into an
+  executed guardrail and no executable code stood behind any of them.
+- **`--baseline`, the mode that makes the export survive.** It measures HEAD, records what it
+  finds as declared debt, and says out loud which rules it skipped. A gate turned on in a
+  repository that already breaks the rule starts red, and a gate that starts red is disabled the
+  next day — taking every other rule in the same aggregator with it. The mode appends only, and
+  never touches a rule that already has a row, because a measured region boundary is the one
+  thing in the ratchet that cost real work.
+- **`AFM_GATE_LIB`**, exported by the aggregator to every runner. A runner resolves its library
+  through the variable and never through a fixed path, so the same runner works in a project
+  that keeps the gate under `docs/tools/gate/` and in one that keeps it somewhere else.
+- **Path parameterization:** `--repo`, `--rules`, `--ratchet`, `--afm-doc`. A consumer that took
+  the materialized layout passes nothing; a project with its own layout passes flags.
+- **`--install` writes the hook it arms.** It creates `.githooks/pre-commit` when absent, then
+  sets `core.hooksPath`. Arming a hooks directory that holds no hook was a silent no-op.
+
+### Fixed
+
+- **`templates/guardrail-runner.template.md` shipped a dead premise and a dead path.** It
+  claimed `framework-template/` is Markdown by design — untrue since 3.6.0-rc.11 — and told the
+  consumer to source `test/lib/scope.sh`, a file that exists only in the AFM repository. A
+  runner written from the template died at its own `source` line.
+- **`afm-pre-commit.sh` and `afm-health.sh` could not see a materialized gate.** Both looked at
+  `test/` only, so a consumer with the gate under `docs/tools/gate/` was reported as having no
+  gate — the same silence the health check exists to break.
+
+### Decided
+
+- **The machine ships; the rules do not.** A runner encodes one project's hard rule (31 is about
+  `SKILL.md`, 32 about `${CLAUDE_SKILL_DIR}`, 33 about `hooks/`). Shipping runners would make
+  every consumer inherit rules nobody chose. See `docs/adr/0017-*` in the AFM repo.
+- **No standalone `pre-commit` file in the distribution.** `--install` already writes it, and a
+  second copy of the same three lines is the drift rule 34 exists to prevent.
+- **Consumer-facing.** `/afm:update` materializes `docs/tools/gate/`. The watermark moves in
+  the rc.2 entry, which is the newest consumer-facing release of this train.
+
+## [3.6.0-rc.11] — 2026-08-25
+
+### Added
+
+- **`tools/` — the first executable component the plugin distributes.** Until this
+  release `framework-template/` held zero `.sh` files: every gate a consumer had was one
+  it built by hand. The guardrails research of 2026-08-25 measured that gap and named it
+  the real one — the rules were never the problem, the distribution was. Two tools ship
+  now, both read-only, both without a dependency beyond `python3`:
+  - **`tools/afm-cost-ledger.sh`** (level 0) reads the session transcripts the CLI
+    already writes and prices each session: tokens by model, the time window, the branch.
+  - **`tools/afm-outcome-join.sh`** (level 1) joins those rows to git, taking the gate
+    verdict inside an **ephemeral worktree at each commit**. It answers "did the gate go
+    green without a human repairing it, and at what token cost". A verdict read at `HEAD`
+    answers a different question and cannot tell a commit that was born green from one
+    somebody repaired later.
+  - **`tools/README.md`** carries the contract, and **`tools/test/run.sh`** carries 21
+    asserts plus fixtures. It says out loud when `shellcheck` is absent: a silent skip is
+    how a repository believes it has static coverage that it does not have.
+
+### Fixed
+
+- **Five measured traps in the transcript data**, each of which produces a plausible
+  wrong number. (1) One API response is written as many JSONL lines that repeat the same
+  `usage` object — a naive sum inflated the AFM repo by **2.2x**, so the count
+  deduplicates by `message.id`. (2) `subagent_tokens` in the harness notification is
+  **not** an output count: it is `output + input + cache_creation`, matched to 1.6% on a
+  measured run, so it lives in its own column and is never compared to `out`. (3) That
+  notification covers **workflow runs only** — a plain subagent reports nothing, and
+  13,175 output tokens were invisible in one session — so subagent cost is summed from
+  the transcripts, which cover both. (4) The subagent `output_tokens` field is reliable
+  on CLI 2.1.238 and 2.1.241 (ratio 0.3–0.8 across 30 runs) and broken on 2.1.245 (ratio
+  20.4), so a per-run plausibility check marks it `suspect` and the column is read as a
+  floor. (5) A session that *discusses* the format writes the element into its own
+  transcript, and the ledger read its own fixture as a real run; a figure now counts only
+  inside a `queue-operation` line carrying a `<task-notification>`, once per `task-id`.
+
+### Decided
+
+- **No gate over the cost number**, and no ratchet. Cost per session moves with the task,
+  so a threshold would fire for no reason, and a gate that fires for no reason is turned
+  off. The tools report. See `docs/adr/0016-*` in the AFM repo.
+- **Consumer-facing.** `/afm:update` materializes `docs/tools/`. The watermark moves in the
+  `3.7.0-rc.2` entry.
+
+## [3.6.0-rc.10] — 2026-08-25
+
+### Added
+
+- **`core/afm.md` §1.3 — "In a fan-out of agents, the model tier follows the task tier".**
+  A workflow, or any batch of parallel subagents, no longer gives every agent the same
+  model. The light tier takes the mechanical, high-volume stages (search, read, collect,
+  `grep`, extract, label). The capable tier takes the stages where a wrong answer
+  contaminates everything downstream (synthesis, judgment, design, adversarial
+  verification, the final report). The criterion is **cost per unit of risk**: a research
+  agent that misses one file costs one more search, and a synthesis agent that reasons
+  wrong writes the conclusion the human then acts on. The model is set **per agent call**,
+  never once for the whole run, and the tier of each phase goes in the workflow metadata
+  so the choice is auditable. No 0/1 trigger separates a mechanical stage from a synthesis
+  stage, so this is a principle, not a hard rule (#3).
+
+  **Consumer-facing:** a new bullet in `docs/afm.md` §1.3. `/afm:update` materializes it. The
+  watermark moves in the `3.7.0-rc.2` entry.
+
+## [3.6.0-rc.9] — 2026-08-24
+
+> **Five subagents read the plugin as a first-time consumer would. A mechanical sweep then
+> found what they could not see.** Together they surfaced **14 instances of one failure**:
+> the data was translated and the parser was not. Three of them had killed a mechanism in
+> silence. None had ever been caught by a gate.
+
+### Fixed — three mechanisms that reported healthy and measured nothing
+
+- **Vital sign A4 (broken ADR chain) found zero, always.** `afm-health.sh` matched
+  `Substituída por ADR-`, `templates/adr.template.md` offered `Superseded by ADR-NNNN`,
+  and the real ADR wrote `Replaced by [ADR-0005](...)`. **Three spellings, zero agreement.**
+  Canonicalized on `Superseded by`, and the pattern now accepts the markdown-link form the
+  instance actually writes. Counter-proved in four directions: it fires on the bare form and
+  on the link form, and stays silent both on the dead Portuguese spelling and on a healthy
+  chain. `ops/diagnose.md` axis A4 carried the same dead pattern.
+- **`/afm:restructure` was inert.** Its declared precondition is `git + Bites:` and it prunes
+  by reading `last:`. Both were written as `Mordidas:` / `última:`, which the template never
+  produces. The op could not trigger, and the dead-gotcha prune could never find anything.
+  `ops/gotcha.md` also told the agent to fill the two fields under their dead names.
+- **The guardrail catalog documented keys nobody reads.** `guardrails/README.md` described the
+  frontmatter as `sinal` / `gatilho` / `superficie` / `parametros`; the real files use
+  `signal:` / `trigger:` / `surface:` / `params:`. A maintainer following the README would
+  write a guardrail the hook never sees. The three guardrail `title:` fields were also still
+  Portuguese — and that is text **injected into the agent's context**.
+
+### Fixed — a test suite that was orphaned from the gate and rotted
+
+`plugins/afm/hooks/test/smoke-v32.sh` is the integration test for hard rules 17-20. **Nothing
+ran it**, so nobody saw it go red. Three of its asserts matched hook output that had been
+translated: `AFM ativo` → `AFM active`, `Learnings que casam` → `Matching learnings`,
+`Handoff pendente` → `Pending handoff`. Now 17/17.
+
+A fourth assert was worse, because it was **green**: `grep -q 'gatilho(s)'` as a **negative**
+assert. No hook prints `gatilho` any more, so it passed vacuously — it would have passed with
+axis A5 completely broken. It now matches the real English output, and breaking A5 on purpose
+makes it fail.
+
+- **Rule 33's runner now runs every executable smoke in `hooks/test/`, not only `run.sh`.**
+  A test that no gate runs is indistinguishable from a test that does not exist.
+
+### Fixed — the interview would have taught the wrong rules
+
+- **`interview/bootstrap.md` step 5 offered rule labels that pointed at the wrong rules.**
+  Ten of sixteen were wrong. The worst: `13 — No dead feature flag`, where **real rule 13 is
+  "tokens and secrets never leak"** — a user opting out of what they read as a feature-flag
+  rule would have marked the secrets rule N/A. The table is rebuilt from `core/afm.md § 3`,
+  and now carries the instruction to read the file first and distrust the table on conflict.
+- **The count is 16 and that was right for the wrong reason.** § 3 numbers slots to 21; 3, 8,
+  9 and 14 are demoted principles with no trigger, and 21 is INALIENABLE. The doc now says why,
+  and says not to renumber — `diagnose` A5b compares instance against plugin **by number**.
+- **`interview/refactor.md` said "§ 3 (rules 1-16) → copy from core/afm.md".** That silently
+  drops 17, 18, 19, 20 and the INALIENABLE 21. It now says to copy every rule and never a prefix.
+- **`INALIENÁVEL` vs `INALIENABLE`** in `bootstrap.md`, `ops/diagnose.md` and `ops/rule.md`:
+  `core/afm.md` says `INALIENABLE`, so all three matched zero rules. Effect: the interview would
+  have **offered rule 21 (code in English) as opt-out**, `diagnose` A5b would never report the
+  CRITICAL, and `/afm:rule` would have agreed to delete it.
+- **D.12 told the agent to edit README sections that do not exist** (`Documentação canônica`,
+  `Doutrina`, `Comandos` — the headings are English), and to paste a Portuguese sentence into an
+  english-first `CLAUDE.md`. Both commit templates and the materialized `## 3.1 Regras
+  forward-only` block were still Portuguese — that block is **written into the consumer**.
+- **The rubric count was hardcoded, drifted twice** (7 in one place, 8 in another, **12** on
+  disk). The number is gone; the docs now point at `rubrics/`.
+
+### Fixed — dead references
+
+- **Four dead anchors.** `evolve.md#phase-4--aplicação--pós-condições--commit-κ-efetivado` in
+  `ops/{update,generalize,reflect,restructure}.md`. The heading became English; the slug did not.
+- **`core/afm.md § 2.7` does not exist** (`ops/tasks.md`, `templates/feature-tasks.template.md`
+  — the second **materializes into every consumer**). The heading is `### 7. COMMIT` inside
+  `## 2. Task flow`. `§ 2.1` and `§ 2.2` are real, which is what made `§ 2.7` look plausible.
+- **15 stale `§` citations** to headings renamed during the migration: `§ O alvo da evolução`,
+  `§ Disciplina de proposta (compartilhada)`, `§ Contrato de supressão`, `§ Instalar o portão`,
+  across `ops/{deliver,diagnose,generalize,restructure,update}.md`,
+  `rubrics/failure-classification.md` and `templates/guardrail.template.md`. Plus
+  `ach.md § convenções` (now `§ 6`) and `evolve.md § Shared proposal discipline` (the heading is
+  `Proposal discipline (shared)`). **`refs-lint.sh` does not see this class** — it resolves file
+  links, not `§` anchors.
+
+### Added — hard rule 38, the remediation for the class
+
+`test/rules/38-parser-marker.sh`. Since the repo is english-first (rule 37), an accented
+word inside a `.sh`, or inside a backtick span in a plugin `.md`, is a **candidate**. It does not
+prove drift; it says where drift lives, and a human triages. It complements rule 37, which
+measures prose **density** in `.md` only and is blind both to shell and to one stray literal.
+
+**Two implementation notes that are themselves paid bugs.** The prototype reported **0 findings
+against a corpus with 6 known cases**, twice:
+1. It required the literal to sit **inside quotes within a `grep`/`awk`**. Real drift appears as
+   a bare word (`for scope in strict flavored ambos`).
+2. It used the range `[A-Za-zÀ-ÿ]`, which is **invalid outside a UTF-8 locale**, and sent the
+   error to `/dev/null`. `grep` aborted and the script printed "0 findings". **A gate that
+   swallows its own error is indistinguishable from a gate that passed** — precisely the bug it
+   exists to hunt. It now pins `LC_ALL=C`, uses explicit alternation, and fails hard.
+
+Backticks are paired with `awk` on even-indexed fields, never with `` `[^`]*…[^`]*` `` — that
+pattern also matches the **gap between** two code spans, which is how the first version reported
+"à la carte" as a Portuguese marker. Six exemptions are justified in the script, including
+`core/afm.md` (it quotes `criarPedidoComEndereço` as an example of what rule 21 **forbids**) and
+`ops/deliver.md` (the ephemeral-override phrases are **user speech**, and rule 37 already says a
+reply follows the speaker's language).
+
+### Fixed — `seo` runtime strings, and `ste` enums
+
+- **23 Portuguese runtime strings in 6 `seo` packages.** Comments and zod descriptions had been
+  migrated; the **output** had not — `gate.ts` (the verdicts that decide whether a page is
+  created), `metadataRules.ts` (what `/seo:audit` reports), `indexingSubmit.ts`, `contentBrief.ts`,
+  `clusterLinks.ts`, `internalLinkSuggest.ts`. The earlier sweep counted **comments**, not string
+  literals, which is why it missed them. Five test assertions matched those strings — including
+  one named *"flags title problems (warn) with PT messages"*. **1731/1731 tests, equal to baseline.**
+- **`ste` documented enum values that no longer exist.** `rules/README.md` described the scope as
+  `ambos` and the severity as `planejada`; `bin/ste-lint` compares `both` and `planned`. A
+  maintainer following the README would add **a rule that never fires**. `test/run.sh` passed
+  `--scope ambos` literally, exercising a phantom value, and passed anyway because it only checks
+  `rc<=1`.
+- **`ste-lint`'s real default `--scope both` was undocumented** — its own usage line listed only
+  `strict|flavored`. Measured on `PRINCIPLES.md`: **10 findings** without the flag, **6** with
+  `--scope flavored` (what `SKILL.md` prescribes for prose). The usage now states both defaults.
+
+### Fixed — repo gate documentation
+
+- **Rule 30's prose named `seo`/`learn`; the runner covers four plugins** including `ste`.
+- **Rule 37's exemption list said two exclusions; the script had three**, and the third
+  (`plugins/ste/rules/*-pt.tsv`) was **dead code** — the scan is `scope_all '*.md'`. Removed.
+- **`test/lib/scope.sh` claimed diff-rules always carry budget 0.** The ratchet grants rule 33 a
+  budget of 1 for `plugins/seo`. The comment misled anyone reading only it.
+
+### Consumer migration
+
+1. **`docs/gotchas.md` — rename the incidence field to `**Bites:** N (last: YYYY-MM)`** if your
+   instance uses `Mordidas:`/`última:`. `/afm:restructure` reads the English names to prune dead
+   gotchas; with the old names its precondition never holds and it does nothing, silently.
+2. **`docs/adr/*.md` — write `Superseded by ADR-NNNN`** (the markdown-link form works too).
+   `afm-health.sh` A4 reads that literal. `Substituída por` and `Replaced by` are not recognized.
+3. **`docs/guardrails/*.md` — the frontmatter keys are `signal:`, `trigger:`, `surface:`,
+   `params:`.** The Portuguese key names were never read by anything.
+4. Everything in the rc.7 block still applies to an instance pinned below `3.6.0-rc.1`.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.6.0-rc.7` → `3.6.0-rc.9`.
+
+## [3.6.0-rc.8] — 2026-08-24
+
+> **The changelog itself was still Portuguese, and the section references were dead.**
+> This release finishes the english-first migration inside the plugin: it rewrites both
+> changelogs, and it turns "the prose of an artifact is English" into a gate that measures.
+
+### Added — hard rule 37, with a measured threshold
+
+- **Hard rule 37 in `afm.md § 3` + [`test/rules/37-prose-language.sh`](../../../test/rules/37-prose-language.sh).**
+  Rule 21 covers only an identifier or a test name with a non-ASCII character. It is blind to
+  prose: a `.md` written entirely in Portuguese passes it clean. **That is how this repo reached
+  2026-08 with 175 Portuguese doc files while the gate said green.**
+
+  The signal is the **density** of Portuguese function words in prose, not their presence.
+  Presence is a guaranteed false positive: every doc here quotes `agente` and the old
+  `**Gatilho:**` — literals the gates need to stay Portuguese.
+
+  **The threshold is measured, not chosen.** The English population (n=117) peaks at **0.69**,
+  the Portuguese population (n=29) bottoms at **1.52**, and **1.0** falls in the gap.
+  `MIN_HITS=3` removes the two 2-hit outliers at the top of the English population.
+  The word list deliberately omits `no`, `com`, `de`, `os` and `ou`: `example.com` tokenizes to
+  `com`, which produced a systematic false positive across every `.ts` file on 2026-08-23.
+
+  **The exemption is counter-proved, not assumed.** `plugins/ste/test/fixtures/*-pt.md` is
+  excluded because the `ste` plugin lints Portuguese and those files are the input its test
+  proves something about. Removing the exclusion makes the runner report all three (densities
+  23.53, 21.43, 16.00). Putting it back silences them. The gate green with the exemption is not
+  the same as the gate blind.
+
+  **31 files are registered as measured debt** in `test/baseline/ratchet.tsv`: 14 in
+  `docs/sessions`, 9 in `test/evals`, 5 at the root, 2 in `docs/research`, 1 in `plugins/seo`.
+  The count can only decrease.
+
+### Changed — both changelogs are English, and the markers were renamed
+
+- **`CHANGELOG.md` and `CHANGELOG-archive.md` rewritten in ASD-STE100 English** — 52 entries,
+  one agent per entry, each one read back against the Portuguese original in git by a second
+  agent that hunts **loss, invention and inversion**. 12 defects were found and fixed. The three
+  that mattered: an **inversion** in the rc.13 dogfooding notes (the English said the threshold
+  belonged to the operator when the source says it belonged to the agent — the opposite of the
+  lesson), an **invented** `### Consumer migration` heading in `3.0.0-rc.1` where the source has
+  none, and a Portuguese `NÃO podar por tamanho` left standing inside an otherwise English bullet.
+
+- **The consumer-migration heading is now `### Consumer migration`, one spelling.** `ops/update.md`
+  reads it to decide what a consumer materializes. The source had **two** spellings —
+  `### Migração de consumer` (4 times) and plain `### Migração` (9) in the active file. The
+  instruction "never translate this marker" then made verifiers normalize in three different
+  directions, including one `### Migration`. Machine-read markers do not tolerate a synonym.
+  All **40** blocks now carry the single English form, and `ops/update.md` reads that form.
+
+- **`**Substituições**` → `**Replacements**` and the table schema `Arquivo | De | Para` →
+  `File | From | To`,** with the six application rules in `ops/update.md` renamed to match.
+  A parser and its data renamed in the same commit — the discipline the previous batches broke
+  four times.
+
+### Fixed — 15 dead section references
+
+The batches translated the headings and left the citations pointing at the Portuguese names.
+`§ O alvo da evolução`, `§ Disciplina de proposta (compartilhada)`, `§ Contrato de supressão`
+and `§ Instalar o portão` appeared **15 times** across `ops/{deliver,diagnose,generalize,restructure,update}.md`,
+`rubrics/failure-classification.md` and `templates/guardrail.template.md`. Every one
+of them told an agent to go read a section that no longer exists under that name. Two more were
+individually wrong: `ach.md § convenções` (now `ach.md § 6`) and `evolve.md § Shared proposal
+discipline` (the real heading is `Proposal discipline (shared)`).
+
+**`refs-lint.sh` does not see this class** — it resolves file links, not `§` anchors.
+The 17 were found by a one-off script, not by the gate.
+
+### Fixed
+
+- **`refs-lint.sh` was blind to `CHANGELOG-archive.md`.** The exclusions matched `*CHANGELOG.md`,
+  and the archive file created in rc.7 does not match that glob. **10 false FAILs.** One of the
+  three exclusion sites was `grep -v 'CHANGELOG.md'`, where the `.` is a regex wildcard that
+  still failed to match the new name.
+
+### Corrected — a number from rc.7 was wrong
+
+The rc.7 entry said the split preserved "51 entries" and "30 migration blocks". Measured again
+against `git show HEAD`: **52 entries** (21 active + 31 archived) and **40** migration blocks
+(13 + 27). The 30 came from counting only the long-form heading and missing the 10 plain
+`### Migração`. The entry now carries the measured numbers.
+
+### Consumer migration
+
+Nothing beyond the block already written for the whole `3.6.0` line in rc.7. Rule 37 and its
+runner are a **repo gate of the plugin**; they are not materialized. `CONSUMER_VERSION` stays
+at `3.6.0-rc.7`.
+
+## [3.6.0-rc.7] — 2026-08-24
+
+> **The changelog got too large to be read, and no summary was safe.** Two ultracode merge
+> rounds tried to compress it. Both lost measured data. This release moves the old releases
+> instead. Nothing is compressed, and nothing is lost.
+
+### Changed — releases before `3.5.0` moved to `CHANGELOG-archive.md`
+
+`CHANGELOG.md` had **1832 lines** (~25k words). `ops/update.md` reads it to materialize the
+deltas of a consumer, so its size is a real cost on every `/afm:update`.
+
+**The measured reason a summary is not possible.** The 1832 lines hold **322 file paths, 96
+measured numbers, 50 table rows, 32 migration blocks and 10 arXiv IDs**. There is almost no
+ornament to cut. Round 1 (effort `low`) invented `## [3.2.0]` release headers — **no minor of
+this project was ever finalized**, all 51 entries are `-rc`. Round 2 (effort `medium`, with an
+explicit instruction to never drop a measured number) still lost 4 arXiv IDs, whole `Changed`
+sections with their file paths, and one migration block.
+
+**What was done instead:** releases `3.0.0-rc.1` through `3.4.0-rc.7` moved to
+`CHANGELOG-archive.md` **verbatim**. The active file keeps `3.5.0` and `3.6.0`.
+
+| file | lines | releases |
+| --- | --- | --- |
+| `CHANGELOG.md` | 1051 (−43%) | `3.5.0-rc.*`, `3.6.0-rc.*` |
+| `CHANGELOG-archive.md` | 802 | `3.0.0-rc.1` … `3.4.0-rc.7` |
+
+Verified after the split: **52 entries** (was 52) and **40 `### Consumer migration` blocks**
+across the two files.
+
+- **`ops/update.md` step 1 must read the archive too** when the version range reaches back
+  before `3.5.0`. The archived releases still carry their migration blocks. An instance pinned
+  to an old version needs them, and missing the archive means the consumer **silently** never
+  receives those deltas.
+
+### Fixed
+
+- **`core/prd.md` line 52 still said `*[A DEFINIR.]*`.** The `[A DEFINIR]` → `[TBD]` rename of
+  rc.1 missed it. `afm-health.sh` counts only `[TBD]` and `[NEEDS CLARIFICATION:`, so a marker
+  in the old spelling is **invisible to the vital signs** — an open decision that never shows.
+
+### Consumer migration
+This block covers the whole `3.6.0` line (`rc.1` … `rc.7`), because the english-first migration
+landed across the six releases as one change. An instance pinned below `3.6.0-rc.1` applies all
+of it.
+
+1. **`docs/gotchas.md` — rename `**Gatilho:**` to `**Trigger:**` in every entry.** This is the
+   one step that is **not** cosmetic. `afm-pre-edit.sh` greps for `trigger.*` to decide which
+   gotcha to inject at write time. An instance that keeps the old spelling gets **zero gotchas
+   injected, silently, with every gate green**. The same applies to the `trigger:` frontmatter
+   key of `docs/learnings/*.md`.
+2. **Replace `[A DEFINIR]` with `[TBD]`** everywhere under `docs/`. `afm-health.sh` counts only
+   `[TBD]` and `[NEEDS CLARIFICATION:`; the old spelling is invisible to the A2 vital sign.
+3. **`docs/afm.md § 1.3` — the language principle inverted.** The old text said *"match the
+   language of the file (PT-BR default). Never translate an existing section."* That is now
+   **false**. Every artifact — docs, code, DB, comments, tests — is written in **English under
+   ASD-STE100**. The chat reply follows the language the user speaks; a reply is not an
+   artifact. **The end-user-facing strings of the app are the exception:** the app language is a
+   product decision, it lives in `docs/prd.md`, and it is never forced.
+4. **Scope indicators, if your docs use them:** `> **Neste arquivo:**` → `> **In this file:**`,
+   `> **Forma** —` → `> **Form** —`, and `grau de liberdade: alto|médio|baixo` →
+   `degree of freedom: high|medium|low`. Cosmetic in a consumer (the lint that reads them is a
+   repo gate of the plugin, and it does not travel), but keep one spelling per instance.
+5. **Do not translate enum literals.** `agente`, `ambos` and `planejada` are matched by string
+   in the gates. Translating the data and leaving the parser behind is the failure class this
+   whole migration produced **four** times. Translate the prose, never the token a `grep` or an
+   `awk` compares against.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.5.0-rc.11` → `3.6.0-rc.7`.
+
+## [3.6.0-rc.6] — 2026-08-23
+
+### Fixed — `refs-lint.sh` was blind on 41 points
+
+This is the most costly finding of the migration, and it **did not come from any checker**. It came from
+running a repo lint that the earlier batches had not run.
+
+`test/refs-lint.sh` matches **literal Portuguese markers** that the translation changed:
+
+| the lint matched | the docs now say | effect |
+| --- | --- | --- |
+| `^> \*\*Neste arquivo:\*\*` | `> **In this file:**` | 21 files "with no scope indicator" |
+| `^> \*\*Forma\*\* —` | `> **Form** —` | 21 ops "with no declared shape" |
+| `grau de liberdade: (alto|médio|baixo)` | `degree of freedom: (high|medium|low)` | degree never extracted |
+| `*REMOVIDO*` in the exclusion | `**REMOVED**` | a command documented as removed became a "dead command" |
+
+**And the lint's own self-test failed too**, because its fixtures generate
+`> **Forma** — grau de liberdade:` while the `sed` already looked for the English. A gate whose
+self-test fails proves nothing.
+
+**Drift only the lint would find:** 6 of the 21 ops translated `**Forma**` as `**Shape**` and
+the other 15 as `**Form**`. Same marker, two translations, no agent seeing both.
+Normalized to `**Form**`.
+
+**Measured consequence of the 9% word-count growth:** `PRINCIPLES.md` (119 lines),
+`ops/remediate.md` (135), and `rubrics/failure-classification.md` (102) crossed the
+100-line threshold and started to **require** the scope indicator they lacked.
+Added to all three. STE bloat is not just token cost — it changes which rule applies.
+
+The `REMOVED` exclusion accepts **both spellings**: a consumer materialized before
+3.6.0 still writes `REMOVIDO`.
+
+### Added
+
+- **Episodic `docs/` in English** (batch B8, 27 files): 15 ADRs, 4 evolution
+  reports, features 001 and 002, and 2 research dossiers.
+
+### Fixed during the rewrite
+
+- **Invented "the team" for the third time** (`adr/0002`), from Portuguese sentences
+  **with no subject** (*"uma melhoria de método é feita"*, *"exige disciplina"*). Portuguese
+  elides the subject, English needs one, and the translator filled the gap with a fact. The owner is
+  **solo**, and the doc itself says so.
+- **Swapped referent** (`adr/0014`): *"desfazer parte da 001"* — **feature** 001 —
+  became *"Undoing part of ADR 0013"*. In a doc whose job is precise cross-reference.
+- **Logical inversion** (`evolution/001`): *"exigem exatamente o gate que eu pulei"* became
+  *"require the opposite gate"*. The point of the paragraph is that the required gate and the skipped one are
+  **the same** — the evidence of the agent's non-conformance. "Opposite" destroys the argument.
+- **`tasks.md` of feature 002 translated the enum literal `agente`** to `agent`. The
+  `test/guardrails.sh` **prints and matches** `agente` (lines 140/142/161). `afm.md` and
+  `plan.md` kept it; only `tasks.md` did not.
+- **`adr/0011` was left with 3 dead references** to `gotchas.md` section titles that
+  batch B7 translated.
+- **`evolution/003` lost "uma das TRÊS razões"** — and that count *is* the evidence of the
+  very finding the paragraph records.
+
+## [3.6.0-rc.5] — 2026-08-23
+
+### Added
+
+- **The 16 `hooks/` files in English** (batch B6): the 7 hooks, `lib/afm-cadence.sh`,
+  the `README.md`, the 84-assert smoke test, and the container harness. This text enters
+  the context of **every session**, so it is the purest `strict` case in the toolkit.
+
+### The verifier said clean and the suite found 9 failures
+
+This is not a contradiction. These are layers that see different things.
+
+The adversarial verifier reads **one file at a time** and answers *"did this translation
+preserve this file?"*. For the 12 hooks the answer was yes, and it was correct: **zero
+code-change**, no `grep`/`awk` pattern touched, `bash -n` clean on all of them.
+
+The failures came from **coupling between files**. `test/run.sh` asserted
+`test("AFM ativo")`, and the hook started to emit `AFM active in this project`. No agent
+looking at one file in isolation could see this. There were 10 asserts across 8 distinct
+patterns.
+
+**This is the same lesson from rc.2, in the good direction.** There, a translated doc plus
+an untranslated parser meant a **blind and green** gate, which is the silent way to fail.
+Here, a translated hook plus an untranslated test meant a **red** test, which is the noisy
+way. The difference between the two cases is only whether a test points at it.
+
+### Green measured
+
+`hooks/test/run.sh` **84 ok / 0 fail** · `bash -n` clean on the 12 scripts · zero PT above
+the threshold in the 16 files · **live** proof (not a fixture): `pre-edit` matches real
+gotchas by the `**Trigger:**` field from rc.2, and `session-start` injects the digest in
+English.
+
+## [3.6.0-rc.4] — 2026-08-23
+
+### Added
+
+- **The 23 `SKILL.md` files in English STE** (batch B5). This is the surface that
+  matters most for routing: the `description` and `when_to_use` of the frontmatter are
+  the text that decides **which skill activates**. `skills-lint.sh` 38 ok / 0 fail — the
+  listing budget did not grow, and it is unidirectional (shrink passes, grow fails).
+
+### Fixed
+
+- **`skills/promote/SKILL.md` gained the word "another"** where the Portuguese source
+  does not have it. *"Desambiguação — critério de quem já ativou"* became *"once ANOTHER
+  skill has already activated"*, which changes the purpose of the section: it talks
+  about **itself** already activated, not about a sibling skill. A single invented word,
+  with a semantic effect.
+- **`skills/remediate/SKILL.md` lost the rationale** for why the disambiguation lives in
+  the body and not in the resident listing — the reason is resident context cost.
+
+### The batch stopped midway, and the design held
+
+B5 hit the session limit with **23 of 27 agents dead**. Nothing got lost, for two
+reasons worth keeping as a harness lesson:
+
+1. **The agent writes the file before it reports.** The 17 that had already run were on
+   disk. What got lost was their verification, not their work.
+2. **Resume worked by MEASURED DENSITY, not by `git status`.** `remediate/SKILL.md` was
+   at `1.6` — half translated. By `git status` it counted as "done" and would have
+   stayed silently bilingual. The count caught it.
+
+## [3.6.0-rc.3] — 2026-08-23
+
+### Added
+
+- **`interview/`, `guardrails/`, the 17 `modules/` patches, `PRINCIPLES.md`, and the two
+  READMEs in English STE** (28 files, batch B3).
+
+### Fixed during the rewrite
+
+- **`PRINCIPLES.md` got an INVENTED sentence that contradicted itself.** The English
+  stated *"a cheap re-runnable signal allows one retry"* — a claim the Portuguese does
+  not have anywhere — and the **next** sentence of the same paragraph said *"the cap is
+  2 retries"*. An internal contradiction in a normative doc. The **invention** checker,
+  added after B1, caught it. Without it, this would have passed.
+- **`PRINCIPLES.md § 1` lost the criterion that justifies the file itself:** *"ou outro
+  agente sem minha memória"*. The English collapsed this to "someone else" and dropped
+  the case of an agent with no memory, which is the reason `/docs/` exists. The two
+  concrete examples (`sem emojis`, `PRs pequenas vs bundles grandes`) also disappeared,
+  and in § 8, the cap on **questions per call** (≤4) was lost, leaving only the item cap.
+- **`guardrails/dsl-com-ordem-obrigatoria.md` had its THESIS inverted.** The Portuguese
+  says a mandatory-order builder *"que só falha em runtime"* is a deferred bug — the
+  condition is the point, because the whole doc argues that **type-state makes
+  mandatory order safe**. The English stated unconditionally that the builder *is* a
+  bug, the opposite of what the file argues.
+- **`modules/prisma-postgres/ach.patch.md` lost the outer ```` ```md ```` fence** of
+  § 6. Patches use it to mark the **literal insertable** content. Without it, the
+  heading became a live heading of the patch itself. 10 markers in the original,
+  8 in the English.
+- **`ops/rule.md` lost "Insistência forte aqui"** — a behavioral emphasis directive,
+  not decoration: the user pushes to call something a hard rule when it has no trigger.
+- **`ops/deliver.md` lost 4 of the 6 ephemeral-override phrases.** Restored **in
+  Portuguese on purpose** — `vai`, `pode ir`, `direto`, `não precisa revisar` are
+  **user utterances**, not artifact text, and the conversation follows the language
+  the user speaks. The English equivalents were added alongside.
+- **`ops/export-template.md` diluted "verde e commitado" into "clean, committed"**,
+  losing the AWM criterion of **passing tests** and duplicating the `git status` check
+  from the next sentence.
+
+### Changed
+
+- **The rest of the guardrail frontmatter is now in English:** `titulo:`/`sinal:`/
+  `parametros:`/`fonte:` → `title:`/`signal:`/`params:`/`source:`, with the two `awk`
+  calls in `afm-pre-edit.sh` (lines 101 and 109) in the same commit. Completes the
+  rename from rc.2.
+
+### New gotcha
+
+- **`ste-lint` lints inside a NESTED fence again.** The emitter treats a fence as a
+  toggle, so ```` ```ts ```` inside ```` ```md ```` flips the parity and the patch's
+  literal text becomes `S2`/`S3`. A pure false positive, and a false positive is how a
+  gate gets turned off. Recorded in `docs/gotchas.md` with the fix cost stated.
+
+## [3.6.0-rc.2] — 2026-08-23
+
+> **The literal markers are English now too.** They were the MOST parsed text in
+> the repo and the last one in Portuguese. Atomic rename: 121 files, docs and parsers in the same
+> commit.
+
+### Changed (BREAKING for a materialized instance)
+
+| before | now | who parses it |
+| --- | --- | --- |
+| `**Gatilho:**` | `**Trigger:**` | `afm-pre-edit.sh` (gotchas + learnings) |
+| `*Verificação:*` | `*Verification:*` | `guardrails.sh --audit` |
+| `[A DEFINIR]` | `[TBD]` | `afm-session-start.sh`, `afm-health.sh`, `PRINCIPLES.md` #4 |
+| `## o que foi pedido` | `## what was asked` | `afm-session-end.sh` **prints it literally** |
+| `## como foi executado` | `## how it was executed` | same |
+| `## O que refutaria isto` | `## What would refute this` | guardrail template (mandatory) |
+| `não-coberto:` | `not-covered:` | `diagnose` output tag |
+| frontmatter `origem:`/`superficie:`/`gatilho:`/`custo:` | `origin:`/`surface:`/`trigger:`/`cost:` | `afm-pre-edit.sh` (`awk /^trigger:/`) |
+| `falha-recorrente` / `regra-dura` | `recurring-failure` / `hard-rule` | `origin:` enum values |
+
+`[A DEFINIR]` became **`[TBD]`**, not `[NEEDS CLARIFICATION:]`. The two markers have
+distinct semantics, and `feature-spec.template.md` documents this: `[TBD]` is a decision the
+owner deferred on purpose, `[NEEDS CLARIFICATION:]` is a gap that blocks execution.
+Merging them would erase the distinction that `afm-health.sh` counts separately.
+
+### The silent break the rename almost caused
+
+Renaming the doc without renaming the parser leaves the hook **blind, and green**. It happened here:
+`docs/gotchas.md` moved to 25 `**Trigger:**` and 0 `**Gatilho:**` while
+`afm-pre-edit.sh` still ran `grep -iEn "gatilho.*"`. The hook would inject zero gotchas and
+no test would fail. Worse: two asserts in `hooks/test/run.sh` check for the **absence**
+of the string `Verificação` — with the doc translated, they would pass by vacuity.
+
+This is why the rename is one commit. A doc and its parser out of sync is how supervision dies in
+silence.
+
+### Green, measured
+
+`hooks/test/run.sh` 84 ok / 0 fail · `guardrails.sh --audit` 9 rules ↔ 9 runners ·
+`--self-test` 11 ok / 0 fail · `update-rehearsal.sh` 13 ok / 0 fail (with `[TBD]`
+preserved untouched) · `ste-batch-check.sh` over `ops/` rc=0 · `ste-lint --scope strict`
+0 block in `ops/`.
+
+### Added
+
+- **All of `ops/` in English STE** (21 files, batch B2). The adversarial
+  checker found 5 CRITICAL, **all** of the same class: a parsed string literal
+  translated as if it were prose. No invention, no Portuguese left.
+
+## [3.6.0-rc.1] — 2026-08-23
+
+> **The toolkit becomes english-first.** Every artifact the AFM produces is born in English under
+> ASD-STE100. The chat conversation follows the language the user speaks — a reply is not an
+> artifact, no one reads it later.
+
+### Changed
+
+- **The whole `core/` was rewritten in English STE** (37 files: `afm.md`, `protocol.md`,
+  `ach.md`, `prd.md`, `ust.md`, `gotchas.md`, 12 rubrics, 19 templates). Each file went
+  through a rewrite and an **independent adversarial check** — a second
+  agent reads the Portuguese original and the English result and reports what got lost.
+
+### Measured, and smaller than promised
+
+- **Tokens: 41,400 → 40,050 (−3.3%)**, 29 of the 37 files shrank. The ones that shrank
+  most are the hot ones: `afm.md` −322, `protocol.md` −191. In WORDS the text
+  **grew 9%** — STE forbids the semicolon and caps a sentence at 20-25 words, so
+  one dense Portuguese sentence becomes two or three English ones, each repeating the subject.
+- **The original estimate was −37% and it was wrong by an order of magnitude.** This stays
+  on record because the estimate drove a scope decision. The real gain from
+  english-first is not compression: it is unambiguous text for a parser, more reach
+  in distribution, and reasoning in the language most of the code was written in.
+
+### Fixed during the rewrite itself
+
+- **`rubrics/when-to-create-dsl.md` had its CRITERION changed by the translation.** The
+  Portuguese said `≥ 3 call-sites repetem a mesma sequência de ≥ N chamadas primitivas`,
+  with **N deliberately unspecified**. The first rewrite collapsed the two
+  thresholds into 3. This is the class of damage that no count catches, only adversarial
+  verification does. Restored.
+- **32 occurrences of `✅`/`❌` became `YES`/`NO`** in 5 rubrics, despite an
+  explicit instruction to preserve emoji. Restored.
+- **One sentence was INVENTED** in `when-to-create-lib.md` — a rationale the original did not
+  have. The first round's verifier hunted only for loss, not invention, so it did not
+  catch it. The prompt now reports `loss | invention | inversion`, with invention
+  weighted the same: the file is the source of truth, and an invented clause becomes doctrine.
+
+## [3.5.0-rc.14] — 2026-08-22
+
+> **A repository cannot declare its own hooks** — if it could, `git clone` would be remote code
+> execution. The single opt-in step is irreducible in git. What did not need to be irreducible
+> was the operator **typing** the command by hand, with a silent chance to forget it.
+
+### Added
+
+- **`ops/rule.md` step 7 becomes a 4-tier surface escalation** — tier 1: the manager the project
+  **already** has (husky/lefthook/pre-commit); tier 2: propose husky or lefthook for a Node
+  project; tier 3: `core.hooksPath` through the aggregator's own `--install`; tier 4: CI. The
+  operator can ask for another manager — the table is a recommendation, not a rail. **Running the
+  install is allowed. Self-installing is not** — an opt-in that installs itself is not an opt-in.
+- **`hooks/afm-pre-commit.sh` (`PreToolUse`, matcher `Bash`)** — the **tier 3** gate, for a
+  project with no native surface at all. It blocks `git commit` with `permissionDecision:
+  "deny"` when the consumer's aggregator exits 1. **Second carve-out** of the hooks golden rule
+  (ADR 0015, amendment to 0013), by the **same** criterion: harm asymmetry. Blocking a commit
+  delays; blocking an `Edit` disables the session — and the `Edit|Write` matcher stays forbidden.
+- **`templates/guardrail-runner.template.md`** gets the activation step with the tiers.
+
+### Changed
+
+- **The whitelist of blocking hooks has two names and stays a whitelist.** The smoke test assert
+  moved from "only Stop" to "only Stop and pre-commit", and it fails a third one — it also fails
+  if the blocking hook is wired on the `Edit|Write` matcher. **9 new asserts** cover the tiers,
+  `--no-verify`, the prose mention, exit 2, and the no-op outside an AFM project (74 → 84).
+- **`hooks/README.md`** and **`ach.md § 3.1`** updated: the `hook` component-type decides in
+  **two** named cases.
+
+### Notes
+
+The aggregator's `--install` stopped just **printing** the command and now executes it: running
+something named `--install` is the authorization. It refuses to overwrite another manager's
+`core.hooksPath` — silently disarming someone else's gate is the failure mode this mechanism
+fights.
+
+## [3.5.0-rc.13] — 2026-08-22
+
+> **The hard rule was already executable — and no one ran it.** Eight rules, eight 0/1 triggers
+> written in prose inside the doc, zero automated: no CI, no git hook, no husky. A trigger
+> that depends on someone remembering fails exactly when context gets tight, and that is how the
+> marketplace cache fell ten releases behind. This release closes the *rule → gate* path.
+
+### Added
+
+- **`ops/rule.md` § Instalar o portão** — canonical procedure for "a hard rule with a 0/1
+  trigger becomes a check that fires on its own". Seven steps, in the order that matters:
+  find the surface the project **already runs** (a new tool is a last resort, with declared
+  cost) → write the runner → **measure HEAD before you switch it on** → measure the cost →
+  prove doc↔runner sync → register the guardrail → propose activation to the operator. No new
+  op and no new skill: installing the gate continues the op that creates the rule. It is not a
+  separate operation.
+- **Step 3.7 in `ops/rule.md`** — the surface (`pre-commit` | `ci` | `agente`) is chosen
+  **before** the rule is written, and the line becomes `*Verification (<superficie>):*` citing
+  the runner. `agente` is honest for a heuristic trigger, not for a precise trigger no one
+  automated.
+- **`templates/guardrail-runner.template.md`** — the runner contract (exit **0/1/2**), the
+  skeleton, and the "before you call it done" checklist. `framework-template/` stays
+  markdown-only: the runner travels as a fenced block, because the only distributed shell is in
+  `hooks/`, which has its own smoke test.
+- **`docs/guardrails/` gains `origin:`** — `recurring-failure` (from the CRITIC loop) and
+  `hard-rule` (from a rule already written that no one ran). **One family, two entry doors**:
+  the artifact is the same object — a 0/1 check plus a burden of refutation — and describing the
+  same thing in two vocabularies is the drift rule 34 exists to stop.
+
+### Changed
+
+- **`rubrics/failure-classification.md`** and **`ops/remediate.md`** now **compose** the
+  install procedure instead of describing it: the *mechanizable* destination points to
+  `rule.md § Instalar o portão` (rule 34 — a procedure lives in one place only).
+- **`templates/guardrail.template.md`** gains frontmatter (`id`/`origem`/`superficie`/
+  `gatilho`/`custo`) and the two-origin table.
+
+### Notas do dogfooding (este repo como primeira instância)
+
+The mechanism was built here before it was described: `test/guardrails.sh` + 9 runners +
+ratchet + a versioned `pre-commit`. Three lessons became normative text above:
+
+1. **A count rule measured over the index is a silent false negative.** With a budget of 7, a
+   commit that adds 1 new violation counts 1 ≤ 7 and passes clean. A *diff* rule measures the
+   index with a budget of 0; a *count* rule measures the whole repo, always.
+2. **Exit 2 ("could not verify") must be distinct from 1 ("violated").** Rule 21 depends on
+   `grep -P`; the first machine without GNU grep would turn the gate into a permanent block.
+3. **A gate that fails half the repo measures a bad threshold, not drift.** The "inline
+   numbered procedure" check flagged 13 of 23 `SKILL.md` files — including legitimate
+   `init`/`refactor` interviews. It was **removed**, not loosened. And the threshold belonged to
+   the agent, when the constant is the operator's (3.6).
+
+The gate, on its first real use, rejected the commit that installed it — for violating rule 30.
+
+## [3.5.0-rc.12] — 2026-08-21
+
+> **The session that committed everything looked the same as the session that did nothing.** The
+> rc.11 gate failed exactly in the disciplined case, and it failed silently. This is the tenth
+> occurrence of the same family in this line of work — this time inside the mechanism built to
+> stop it.
+
+### Fixed
+
+- **The "session with work" signal ignored committed work.** `afm-session-end.sh` measured work
+  only by `git diff --name-only HEAD` — **uncommitted** change. A session that delivered a lot and
+  committed everything leaves a clean tree, and the hook exited with exit 0 before any evaluation:
+  no handoff, no reflection charge. Measured in the plugin repo right after the rc.11
+  commit: **clean tree, 23 events from this session in the ledger**. Now the signal is
+  disjunctive — uncommitted diff **or** `s=<sid6>` events in the append-only ledger, which
+  `afm-capture.sh` already writes on every commit. `files_touched` does not invent a list when
+  everything was committed. It says so and points to `summary`.
+- **Two defects in the gate's own fixture**, both in the class "the assert does not prove what it
+  claims": the fixture appended events **after** the commit (dirtying the tree that the
+  precondition assert required clean), and it wrote `s=` in the wrong field — the real ledger
+  format is `<kind> | s=<sid6> | <título>`, with the sid in the middle. With the field swapped,
+  the hook's `grep` did not match, and the assert failed for the wrong reason.
+
+### Added
+
+- **`$schema` in `hooks/hooks.json`** for IDE typing. No published schema exists for a plugin's
+  `hooks.json` — SchemaStore has five Claude Code schemas (`settings`, `plugin-manifest`,
+  `marketplace`, `keybindings`, `launch`) and none matches this file by `fileMatch`. It points to
+  the `settings.json` one, which defines the `hooks` block in full (31 events, `$defs/hookMatcher`,
+  `hookCommand`) and has `additionalProperties: true` at the top. The trade-off is recorded in
+  `_schema_note` inside the file itself. `plugin.json` and `marketplace.json` are already typed
+  automatically by `fileMatch` — they do not need the key.
+- **Regression assert** in the smoke test: a session with **committed** work still blocks, with an
+  explicit clean-tree precondition (otherwise the next assert proves nothing).
+
+### Consumer migration
+None. `CONSUMER_VERSION` stays at `3.5.0-rc.11` — the fix is in the hook, which travels with the
+plugin, and the `$schema` key is IDE tooling.
+
+## [3.5.0-rc.11] — 2026-08-21
+
+> **`reflect` depended on the model remembering to call it — and it did not remember.** The operator ran
+> several protocols with not one reflection. This release swaps the invitation for a gate: `Stop`
+> now enforces it, cadence moves from the script to the project artifact, and a recurring failure
+> that a command would catch stops turning into a document.
+
+### Added
+
+- **`docs/guardrails/` — the fourth failure destination, with precedence.** `rubrics/failure-classification.md`
+  had three destinations (`procedure`, `learning`, `transiente`), and the first two are **documents
+  that inform a reader**: they depend on someone remembering to open the runbook or having read the
+  lesson. A **mechanizable** recurring failure — a boundary break between modules, a non-exhaustive
+  union, a mandatory order in a DSL — now has its own destination: a 0/1 check that fires on its own.
+  The precedence is explicit: when a failure fits both, it is a guardrail. New
+  `templates/guardrail.template.md` with the mandatory `## What would refute this` section,
+  which flips the burden onto whoever wants to loosen the gate later.
+- **Mandatory surface discovery before proposing a guardrail** (`ops/remediate.md` step 3.5).
+  Reads what the project **already runs** — linter, type-check, CI, git hooks, versioned scripts —
+  and extends that. A new tool is a last resort, explicit and with a stated cost: a gate that
+  requires adopting one more tool tends to cost more than the error it catches.
+- **`ops/reflect.md § 1.2` — the second sweep.** `remediate` consumes `.afm-log-failures/`, which
+  logs a failure only with a **terminal external signal**. The error the agent caught while reading
+  its own diff never reaches there — it was fixed before it became a signal. It is the costliest
+  class, because its cost is context, invisible in the ledger. `reflect` is the only point in the
+  cycle that sees it.
+- **`ops/evolve.md` Phase 1.3.5 — a guardrail axis in the cycle.** Cross-checks `reflect`'s
+  candidates against the mechanizable failures in the substrate and sees the **pattern across
+  failures**: three different defects that share the same missing surface are a finding that none
+  of them alone reveals.
+- **`REFLECT_EVERY` / `EVOLVE_EVERY` / `REFLECT_TASKS`** in `core/protocol.md § 2`. The `cadence`
+  field was declared in § 1 with **no parameter line at all** — a field without a parameter.
+  Declarable per project on the `cadence:` line of `docs/_focus.md`.
+- **`hooks/lib/afm-cadence.sh`** — single source (rule 34) for the count and for reading cadence,
+  now that there are two readers: `afm-health.sh` reports on `SessionStart`, `afm-session-end.sh`
+  enforces on `Stop`.
+
+### Changed
+
+- **NAMED CARVE-OUT FROM THE HOOKS GOLDEN RULE (ADR 0013).** `Stop` can return
+  `decision:"block"`, and **only it can**, and **only** for reflection cadence. The other six hooks
+  stay forbidden — the original reason still holds: a hook that blocks an `Edit` turns a hook bug
+  into an unusable session. `Stop` is different because blocking there does not stop work, it
+  delays closing; **the damage asymmetry is the whole argument**. Three independent guards:
+  `stop_hook_active` (loop), a cap of 1 block per session, and the `cadence: reflect=off` opt-out.
+  A new smoke-test gate fails if any other hook copies the pattern.
+- **The unblock is 0/1 on an artifact, never on the agent's word** — a non-empty `reflection:`
+  in the session file. A block that clears with a mere statement is not a block.
+- **"Skip this one" is logged debt, not disappearance.** `reflection: skipped — <reason>` + `debt: true`
+  in the frontmatter; `afm-health.sh` counts and reports it, `evolve` treats it as evidence. Without
+  the record, skipping would be indistinguishable from never happening.
+- **P3 uses native Plan Mode as a mechanism, not as an analogy** (`templates/protocols/p3.md`):
+  `EnterPlanMode` in phase 1, `ExitPlanMode` at the transition. Degradation is declared — without
+  the mode, it falls back to summary + `AskUserQuestion`, and **the gate criterion is the same in
+  both**.
+- **`ops/deliver.md`** drops the outdated premise *"a skill does not force the session into plan
+  mode"* — true when written, false today.
+- **`afm-session-end.sh` locates the session file by a `sid` glob**, not by a recomputed name.
+  The dedup flag in `$TMPDIR` was doing `exit 0` on the second `Stop`, killing the block evaluation
+  exactly where the re-check matters.
+
+### Fixed
+
+- **The P3 transition gate was vacuously red.** `grep '[NEEDS CLARIFICATION:]'` fails a plan that
+  only **mentions** the marker inside a code span — describing the gate itself. Measured in
+  delivery 001: the only hit was the line documenting the gate. The command now strips code spans
+  before searching (`sed 's/`[^`]*`//g'`). A gate that fails for talking about itself is as useless
+  as a gate that passes without looking.
+- **Cadence anchored only on `deliverable` would be a dead trigger.** The event fires only when a
+  `docs/features/*/tasks.md` zeroes out its `- [ ]`; work that never opens a feature folder never
+  emits it. Measured on the plugin repo: **25 `task` events, zero `deliverable`** over two months.
+  The block condition is disjunctive now. A gate that never fires is indistinguishable from one
+  that works — caught before shipping, in the fixture.
+
+### Consumer migration
+1. **`docs/_focus.md`** can gain the line `cadence: reflect=1 evolve=3` (optional — if absent,
+   the defaults apply). `reflect=off` turns off the `Stop` block.
+2. **`docs/guardrails/`** is born on demand, like `procedures/` and `learnings/`. Nothing to create
+   by hand.
+3. **New visible behavior:** at the end of a session with work done and cadence reached, closing
+   is blocked **once** with an instruction to run `/afm:reflect` or log the debt. Anyone who does
+   not want this declares `cadence: reflect=off`.
+
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.5.0-rc.8` → `3.5.0-rc.11`.
+
+## [3.5.0-rc.10] — 2026-08-20
+
+> **The guardrail suggestion was inert, and the eval proved it.** rc.6 put the trigger in a file
+> nobody reads during common work. This release moves it to where it bites.
+
+### Fixed
+
+- **The guardrail now proposes itself at `PreToolUse`, at write time.** rc.6 put the signal in
+  `interview/triggers.md`, and the `guardrail-sinal-casa` eval failed **0/5**: the transcript shows
+  the agent doing the right task, **noticing** the exhaustiveness gap, and dismissing it as "out of
+  scope". `SessionStart` never mentioned the catalog, and the agent does not read `triggers.md`
+  during code work. `PreToolUse` is already the mechanism that **provably** fires — it is what
+  delivers gotcha, learning, and rule by path-match. The block runs the `sinal` of the catalog
+  entries, skips the ones already installed, and proposes **once per session** (never per file),
+  only on code edits — proposing a code guardrail when editing a `.md` file is noise. Measured:
+  **34 ms** per edit.
+- **The catalog signals matched inside `node_modules`.** `dsl-com-ordem-obrigatoria` was proposed
+  because the `ajv` dependency has `return this` — **30 hits**, none in the project code. It only
+  showed up because the hook runs in a clean subshell, **without the shell aliases of the person
+  who wrote the catalog**: validating the signal on the command line gave "no match", and the hook
+  gave "match". A new gate requires `--exclude-dir=node_modules` on every recursive signal.
+- **The `SessionStart` signal enumeration was stale, and got removed, not updated.** The line
+  listed **5** signals against **24** in `triggers.md` — a second source of truth, out of sync
+  since before this session. Enumerating the 24 would cost 1,050 chars per session, and the eval
+  had already shown that enumerating **does not** make the agent propose anything. Listing 5 of 24
+  did not inform: it misinformed. The line now points to the file and says where the guardrail
+  proposal actually arrives. It got **31 chars shorter**.
+
+### Verification
+
+Hook: fires on a code edit, stays silent on the second edit of the same session, stays silent on
+`.md`. Smoke 62 → **63** asserts. The end-to-end eval was triggered but **has not returned yet**
+as this commit is written — what is proven here is the hook's behavior, not the change in the
+agent's conduct. If the eval keeps failing, the diagnosis is wrong and the finding goes back to
+the table.
+
+### Consumer migration
+- **Consumer-noop.** `hooks/` and `guardrails/` are read from the plugin, not materialized.
+  `CONSUMER_VERSION` stays at `3.5.0-rc.8`.
+
+## [3.5.0-rc.9] — 2026-08-20
+
+> **The MCP stops charging users who never use it, and now says what to do when it fails.**
+> Reverts, with a better design, two refusals recorded in rc.2.
+
+### Added
+
+- **Lazy bootstrap.** `mcp/bootstrap.mjs` had two paths and now gets both right: **already
+  built** imports `dist/server.js` and gets out of the way (the common case, SDK server as
+  before); **not built** starts a **dependency-free** JSON-RPC stub that answers `initialize` and
+  `tools/list` right away, and installs+builds only on the **first real `tools/call`**. A user who
+  installed the plugin and never calls `web_read` pays no `npm install` at all.
+- **`tool.json` as the single source for the tool definition**, read by the SDK server and by the
+  stub. Duplicating it would make the stub announce a different tool than the one that answers —
+  drift invisible until someone calls it with an argument only one side knows. `src/handler.ts`
+  does the same for the logic: one pure handler, callable by both, with neither reimplementing
+  the other.
+- **Actionable error for non-fetchable input.** `file:///x`, `/local/path`, `./note.md`, and
+  exotic schemes now say **what to do next** ("read a local file with the Read tool"). Before,
+  `file://` reached the agent as `fetch failed (error): fetch failed` — handled, but silent.
+  **This is not a security control, and the code comment says so**: it does not block a private
+  IP and does not try to; destination validation stays refused (rc.2), with the bypass
+  documented.
+
+### Fixed
+
+- **The bootstrap failure was a stack trace on stderr that never reached the model.** Now it is a
+  sentence that comes back as a **tool result** — the agent reads it, knows it is not its own
+  request's fault, knows a retry is pointless, and gets the fallback (`WebFetch` + the mark in
+  `research.md`). **This goes further than the gap report proposed:** the original proposal was
+  `console.error` + `exit(1)`, which goes to the same stderr that was already inherited and just
+  as invisible — that is why rc.2 refused it. The right channel was not the message, it was its
+  **destination**.
+
+### Why rc.2 refused this and rc.9 does it
+
+rc.2 refused the `docs/.afm-version` gate in the bootstrap because the proposed form (`exit(0)`
+with no handshake) makes the client mark the server as `failed` — visible noise traded for silent
+install. The argument still holds: **this release does not implement that gate.** The stub solves
+the same problem a different way — it answers the handshake and defers the cost, so nobody sees
+anything until real use. Measured: the install `cwd` is the plugin directory, so the cost avoided
+is one install per plugin version, not per project.
+
+### Verification
+
+The stub is hand-written protocol, so it was tested **against the real client**, not only against
+asserts: with `dist/` absent, a `claude -p` session lists
+`mcp__plugin_afm_research__web_read` and **no build fires**. Package tests: 17 →
+**23**. One of them covers the drift that `tool.json` created — the default `1500` lives in the
+JSON description and in `DEFAULT_BUDGET_TOKENS`, because JSON does not interpolate, so a gate
+compares the two.
+
+### Consumer migration
+- **Consumer-noop.** `mcp/` is install-side surface, not materialized.
+  `CONSUMER_VERSION` stays at `3.5.0-rc.8`.
+
+## [3.5.0-rc.8] — 2026-08-20
+
+> **The first rule the operator does not turn off — and the honest statement of how far that goes.**
+
+### Added
+
+- **Hard rule 21 — `INALIENÁVEL`: code and tests in English.** Identifier, function name,
+  test name, and comment in English, in any language and any project. **A string facing the end
+  user follows the product language** — the rule is about the code, not about content the user reads.
+  *Verification:* `grep -rqP` over declaration lines for a non-ASCII character. The command proves
+  **half**: it catches `criarPedidoComEndereço` and `it("devolve o pedido válido")`. **It does not
+  catch** (a) Portuguese without an accent (`criarPedido`) — judgment call, § 5.1; (b) **a comment,
+  on purpose** — English prose uses an em dash, curly quotes, and an ellipsis, so non-ASCII in a
+  comment is noise, not signal. Measured: a correct English comment flagged a violation only because
+  it had a `—`. Stating what the command **does not** prove is what separates an honest partial
+  trigger from an empty promise.
+
+  The `\b` in the alternation is **load-bearing**: without it, `it` matches inside "delimitam" and
+  `type` matches inside "prototype". The first version of the trigger found real violations **for the
+  wrong reason** in this same repo — finding the right answer by accident is worse than not finding
+  it, because the next case will not have the accident.
+- **The concept of an `INALIENÁVEL` rule, with three mechanical teeth and a stated limit.**
+  The interview **does not offer it** in the Step 5 opt-out (and does not omit it silently either: it
+  lists it with a note that it is not an opt-out — offering it and then refusing would be worse). The
+  `ops/rule.md` **refuses** to remove it or mark it N/A, even under `SUPPRESS_SUBGATES`. The
+  `ops/diagnose.md` gains axis **A5b**: an inalienable rule missing from the instance is **CRITICAL**.
+
+  **The limit, stated in full:** `docs/afm.md` is a file in the operator's repo, and nothing stops
+  the operator from editing it. AFM **detects** the removal, it does not **prevent** it. Calling this
+  "impossible to change" would be exactly the empty promise that `protocol.md § 6` carried until
+  rc.2 — and the value of having fixed that disappears the moment another one like it gets written.
+
+  **Inalienable is not retroactive.** In a brownfield project it enters forward-only (§ 3.1) like any
+  other rule: requiring retroactivity would make adoption impossible in any codebase not born under it.
+
+### Fixed
+
+- **`src` was hardcoded in rule 6.** It became `{{src-path}}`, now with **two** callers (rules 6 and
+  21) — introducing a placeholder used only once would repeat the smell of the orphan `{{path}}` that
+  rc.5 fixed.
+
+### Consumer migration
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.5.0-rc.5` → `3.5.0-rc.8`.
+
+**Copy** (the rule is new; there is no From→To):
+
+| Consumer file | Action |
+| --- | --- |
+| `docs/afm.md` § 3 | add rule **21** verbatim from `core/afm.md`, filling in `{{src-path}}` |
+
+0/1 detection for an instance that does not have it yet (this is the `diagnose` axis A5b):
+
+```sh
+grep -c 'INALIENÁVEL' docs/afm.md   # 0 → needs materializing
+```
+
+> An instance whose § 3 was renumbered locally: 21 enters under the **number the plugin uses**, not
+> the next free one. Inalienable is citable by number across projects, and renumbering it would break
+> the citation.
+
+## [3.5.0-rc.7] — 2026-08-20
+
+> **The harness gets a judge, and a canary that distrusts it.** Phase 5 of the active-executor
+> plan: measure whether the improvements work, without the measurement itself turning into theater.
+
+### Added
+
+- **`llm` grader in the runner** (`test/lib/eval-run.py`), on the **official schema** and only
+  there: `criteria` (required) + `focus` (`last_message` · `trace` · `files` · `{source: file,
+  path}`), verdict by **2-of-3 majority**, model via `--judge-model` (default `haiku`). What is
+  **not** publicly documented — a numeric threshold, a model field in `case.yaml`, a return format,
+  `baseline` — was left **out on purpose**: a schema invented today is a case that does not run
+  tomorrow, and no one finds out until they try.
+- **Skipped is not passed.** Without `--judge` the `llm` grader returns `None` and drops out of the
+  **denominator** of the score. Counting it as a failure would punish someone who did not pay for the
+  API. Counting it as a pass would inflate the score with coverage that does not exist — the same
+  denominator bug that already cost this repo dearly, when `listing_total_all_plugins` summed three
+  plugins and called itself "all". The self-test now locks in exactly this distinction.
+- **Judge canary** (`test/judge-canary.sh`) — calibration in **two directions**, which
+  `guardrails/agentes/14-medicao-gameavel.md` requires before you trust a gate judged by an LLM:
+  - **impossible passed** → the judge rubber-stamps, and every `llm` score is inflated;
+  - **trivial failed** → the judge rejects everything, and every score is deflated.
+  A judge that gets both wrong is noise; one that gets **one** wrong is bias with a known direction,
+  which is worse, because it looks like it works. **It found a bug on the first run** — in the
+  harness, not the judge: the evidence was passed outside the transcript, the place
+  `_target_text` reads from, and the judge was judging a void in both canaries. One canary alone
+  (the impossible one) would have passed green with a blind judge, because a blind judge fails
+  everything.
+- **Two eval cases for the guardrail suggestion** (phase 3): `guardrail-sinal-casa` (a union of
+  literals with an incomplete `switch` — the signal fits, and the agent proposes **without claiming
+  it installed** anything) and `guardrail-negativo` (a pure-content project — no signal fits, and
+  proposing there would be the noise that makes the operator stop reading proposals).
+
+### Consumer migration
+- **Consumer-noop.** `test/` is a repo gate, not a materialized surface.
+  `CONSUMER_VERSION` stays at `3.5.0-rc.5`.
+
+## [3.5.0-rc.6] — 2026-08-20
+
+> **AFM now suggests a guardrail by signal, with no new op and no new skill.** Phase 3 of the
+> active-executor plan. The catalog grows. The mechanism that consults it does not.
+
+### Added
+
+- **Guardrail catalog** (`guardrails/*.md`) — **data, not a skill**. Each entry carries the `sinal`
+  (the 0/1 command that detects whether **this** project would benefit), the `gatilho` (the gate's
+  0/1 once installed), the `superficie`s where it can run, and the `parametros` that **the
+  operator** fills in. Three entries: executable import boundary, `never` exhaustiveness,
+  mandatory order in a fluent chain.
+- **`## What would refute this` is now a mandatory field on every entry.** An installed guardrail
+  is permanent friction, and friction with no visible rationale is the first thing someone removes
+  on a busy Friday. This section states **what evidence would overturn the recommendation** — not
+  "when not to use it", which is opinion, but the observable fact that makes the gate wrong for
+  this project. Whoever removes a guardrail should be able to cite the line that refuted it.
+- **`interview/triggers.md` gains TWO lines, not one per guardrail.** The first runs the `sinal` of
+  the catalog entries and proposes installation on a match; the second flags a hard rule whose
+  trigger rewrites in prose what a versioned script already does. The catalog grows without
+  touching the trigger — one line per guardrail would be the same sentence written N times.
+- **`ops/rule.md` gains steps 3.5 and 3.6.** Step 3.5 points the `*Verification:*` at the versioned
+  script when one exists (two sources of truth for the same check drift out of sync on their own,
+  and the one the human reads stops being the one that runs). Step 3.6 puts the **constant in the
+  operator's hands**: measure the repo and propose it with the measurement attached, never hardcode
+  a "best practice" value — a rule whose constant the owner did not choose is a rule they turn off
+  on first friction.
+
+### Fixed
+
+- **`ops/diagnose.md` A5 gains two sub-cases**, and the second is a paid lesson. **HIGH:** a trigger
+  that duplicates a versioned script in prose. **CRITICAL:** a trigger that ends in `| head`,
+  `| wc -l`, or any pipe whose last stage always exits `0` — **vacuously green**, it passes whether
+  installed or not, and measures presence instead of activation. It happened twice in this line of
+  work: once in a design the skeptic knocked down (`awk` with an empty `END{}` block), and once in
+  the signals of the catalog above (`| head -1`), caught in dogfooding minutes after it was
+  written. A trigger that never fails is worse than none: it spends the trust a real gate would
+  need.
+
+### Not done, and why
+
+- **A `guardrail` op and a new skill.** A skill costs ~550 chars of listing ≈ **~140 resident
+  tokens in every session of every project**, including ones that will never install a single
+  guardrail — on the order of the unit economics a single check brings. The surfaces that already
+  exist (passive `reconcile`, `ops/rule.md`, `ops/diagnose.md` A5) cover the case with no permanent
+  tax.
+- **Installing the gate** (CI, git hook, a target the operator names). Left for its own round: the
+  op would then write **outside `docs/`** — into a build manifest and CI config — and that strains
+  the architectural-change bright line. Suggesting is autonomous; installing is not.
+- **§ 3 becoming an installable catalog.** That would be a **regression**: today every hard rule is
+  injected on every `SessionStart` and at write time, in every AFM project, **with no installation
+  at all**. A project that skipped installation would end up with zero, not a weaker control. § 3
+  **is** the suggestion layer; installation is the optional upgrade on top of it.
+
+### Consumer migration
+- **Consumer-noop.** Nothing materialized changes: `guardrails/` is read from the plugin by
+  `reconcile`, `interview/triggers.md` is a protected surface that `update` never materializes
+  (`ops/update.md` § 2), and `ops/*` are not materialized. `CONSUMER_VERSION` stays at `3.5.0-rc.5`.
+
+## [3.5.0-rc.5] — 2026-08-20
+
+> **The framework gives the shape; the operator gives the value.** Two universal rules nailed
+> down a constant that never belonged to the framework — and one of them was the `domain_` that
+> started this whole line of work.
+
+### Fixed
+
+- **Rules 6 and 7 nailed down an operator decision inside `core/`.** Rule 6 said `≤ 300 lines`
+  and rule 7 prescribed the `domain_` prefix, both **literal** — next to `{{domain-path}}`,
+  `{{ext}}`, and `{{schema-lib}}` in the same paragraph. This proves the omission was accidental,
+  not a design choice. They became `{{limite-linhas}}` and `{{prefixo-dominio}}`, parametrized at
+  the **7 points** where they appeared (the rule, `*Verification:*`, § 1.2 doctrine, anti-patterns,
+  and the DoD checklist — parametrizing only the rule and leaving the DoD saying `300` would
+  create an internal contradiction).
+- **`{{path}}` was a name orphaned from `{{domain-path}}`.** It appeared **only once in the whole
+  template**, in rule 7's `*Verification:*`, while rules 15 and 16 use `{{domain-path}}` for the
+  same directory. The consumer would have to fill in two names for one concept — or, more likely,
+  fill in one and leave the other raw. Unified.
+
+### Added
+
+- **The interview measures before it proposes** (discover-first, #2). `bootstrap.md` gains the
+  constants step: it runs the real file-size distribution (p90) and detects by `grep` the function
+  prefix the code **already** uses, and only then proposes the value **together with the
+  measurement**. A greenfield project with no code to measure gets `300`/`domain_` **declared as
+  the template default**, not as a measurement — the difference between an assumed default and a
+  chosen one is what decides whether the rule survives first contact. An operator who does not
+  answer gets `[TBD]` and a note that the rule stays without a trigger until someone fills it in
+  (#4), never an invented number.
+- **The brownfield audit stops assuming the answer.** `refactor.md` A.5 filtered with
+  `awk '$1 > 300'` — it used the constant that the command existed to **discover**. Now it prints
+  the distribution and the constant comes from it, and a new `grep` detects the prefix convention
+  already in use.
+
+### Consumer migration
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.5.0-rc.3` → `3.5.0-rc.5`.
+
+**There is NO Replacements table, and the omission is deliberate.** A find-and-replace swapping
+`300` for `{{limite-linhas}}` in the instance would leave an **unfilled placeholder** where a
+working number used to be — worse than the problem. The materialized instance of any earlier
+release has `300` and `domain_` **literal and working**; they are not wrong, they were just never
+chosen.
+
+The migration is a **question**, not a substitution:
+
+> Does your rule 6 say `≤ 300 lines` and rule 7 use `domain_`? Were these values **your choice**
+> or did they come from the template? If they came from the template, run the measurement in
+> `bootstrap.md § As constantes das regras` and decide. If they were your choice, there is nothing
+> to do — the number is already yours.
+
+Detection (`0/1`) of an instance that still carries the inherited default with no decision on
+record:
+
+```sh
+grep -qE '≤ 300 linhas' docs/afm.md && ! grep -q 'limite-linhas' docs/afm.md && echo "herdado"
+```
+
+- **Plugin-only:** `interview/bootstrap.md`, `interview/refactor.md`.
+
+## [3.5.0-rc.4] — 2026-08-20
+
+> **The gate spent more context saying everything was fine than failing.** Phase 0 of
+> the active-runner plan: the measured token savings, and its rationale protected against
+> whoever comes to "improve" it later.
+
+### Fixed
+
+- **`afm-pre-edit.sh` told you to read a file without saying which one.** The learnings block labels
+  *"read the whole file"*, but the `grep` ran without `-H` — and with **exactly one** file in
+  `docs/learnings/` `grep` omits the name, delivering only `7:- **Trigger:** …`. The bug goes away
+  on its own from the second learning on, which explains why it never showed up: **one-learning is the
+  state of the first learning any project creates**, and it disappears right when someone
+  would look. A new fixture covers the single-file case.
+
+### Added
+
+- **Silent output on success in the mechanical gates** (`-v`/`V=1` restores it). Measured: the four
+  gates totaled **10,099 chars per run** and **8,476 of them were the scripts saying everything was
+  fine** — an `ok —` for each of the 36 skills and the 61 assertions, plus 50 section
+  headers. After: **1,627 chars (−2,119 tokens per run)**, paid on every work session.
+  The asymmetry is the whole design: **silent success, verbose failure** — a planted failure
+  still prints `FAIL —` and the summary, and the summary never disappears in either mode.
+
+### Consumer migration
+- **Plugin-only.** `hooks/afm-pre-edit.sh`, `hooks/test/run.sh`, `hooks/test/smoke-v32.sh`.
+  The repo gates (`test/*.sh`) are not materialized. `CONSUMER_VERSION` stays at
+  `3.5.0-rc.3` — **consumer-noop**.
+
+## [3.5.0-rc.3] — 2026-08-20
+
+> **Two mechanisms were ready but mute because of one character.** The `sig=` lost recurrence
+> to a path, and one whole hard rule vanished from context because of one asterisk. Neither
+> failed loudly — this release attacks that failure mode.
+
+### Fixed
+
+- **The `sig=` almost never recurred, and rule 19 never fired.** The `ERRN` was the first 40
+  chars of the raw normalized error — and in typical oracle output the **most volatile**
+  tokens lead (path, `(line,column)`, failure count), while the stable discriminator comes
+  later or gets cut off. The **same** `TS2322` in two files produced two signatures, so
+  promotion by recurrence (>=2x) never happened. Evidence: this repo has **one** `sig` in
+  three months of ledger. Now path, `line:column`, and isolated digits are dropped **before**
+  truncation; `\b[0-9]+\b` only matches a bare digit, so `TS2322` and `TS2345` stay distinct.
+  A new fixture covers both sides.
+- **A timeout counted as an oracle failure.** The only `sig` this repo recorded in three
+  months was `typecheck-exit-code-143-command-timed-out-after-2m` — a timeout, which is a
+  verdict about the **machine** (a slow suite, a stuck runner, the harness limit), not about
+  the code. Same class as the `is_interrupt` the hook already excluded. A new guard covers
+  exit 124/143 and "timed out". It deliberately does **not** cover the runner's per-test
+  timeout (`timeout of Nms exceeded`): that one is a signal about the code and stays captured.
+- **Rule 7 never reached context — because of one asterisk.** The hooks' headline extractor
+  uses `\*\*([^*]*)\*\*`, and rule 7's bold text contained `` `domain_*` ``: the `[^*]*` stops
+  at the asterisk, the match fails, and the rule gets dropped **silently**. This is exactly
+  the rule that separates pure domain from glue. The text became `` `domain_<nome>` ``, and —
+  more important — a **class gate** entered the smoke test: the count of rules with a headline
+  in § 3 has to match the count the extractor returns. Any future rule with `*` in its bold
+  text now fails the test instead of vanishing without warning. Same failure as rule 13's
+  headline (rc.2), now with a trigger.
+- **The § 3 preamble promised more than it delivered.** "Every rule below has an executable
+  trigger" was false for rules **1** and **12**, whose `*Verification:*` was prose — and the
+  preamble itself says a rule with no binary trigger is not a hard rule. Both gained the
+  mechanizable half (`git diff --staged --name-only | grep -qE '\.(test|spec)\.'` for rule 1;
+  a grep for the rerun case for rule 12) and now **state explicitly** which half the command
+  proves and which half stays judgment — including the false positive on a pure refactor,
+  rename, revert, and config commit. The preamble now acknowledges the partial trigger instead
+  of pretending full coverage. Precedent: same honesty that demoted rules 3, 8, 9, and 14 to
+  principles.
+
+### Consumer migration
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.5.0-rc.2` → `3.5.0-rc.3`.
+
+**Replacements** (apply in `<consumer>/docs/`):
+
+| File | From | To |
+| --- | --- | --- |
+| `docs/afm.md` | `` UMA função `domain_*`. `` | `` UMA função `domain_<nome>`. `` |
+| `docs/afm.md` | `*Verification:* test runner cobre o caminho novo; diff mostra` | `*Verification:* \`git diff --staged --name-only \| grep -qE '\.(test\|spec)\.'\` — o commit que traz código traz teste junto; o comando prova que existe teste, não que ele cobre o caminho novo. Antes dizia: test runner cobre o caminho novo; diff mostra` |
+
+> The rule 7 replacement is the one that matters: without it the instance keeps the rule
+> invisible to `SessionStart`. Run `awk '/^## 3\./{f=1} /^## [0-9]/&&!/^## 3\./{if(f)f=0} f' docs/afm.md
+> \| sed -nE 's/^([0-9]+)\. \*\*([^*]*)\*\*.*/\1/p' \| wc -l` and compare with
+> `grep -cE '^[0-9]+\. \*\*'` over the same slice — the two must match.
+
+- **Plugin-only:** `hooks/afm-capture-failure.sh`, `hooks/test/run.sh`.
+
+> **The `sig=` contract.** This change alters the **recurrence key** that `remediate`,
+> `reconcile`, `evolve`, rule 19, and the `failure-classification` rubric consume. Signatures
+> already recorded in an existing ledger are not rewritten (rule 18 — append-only, and `update`
+> never deletes): they simply stop matching the new ones. The practical effect is a recurrence
+> window that restarts from zero, and no lost promotion — the old one almost never matched,
+> which is the bug.
+
+## [3.5.0-rc.2] — 2026-08-20
+
+> **A rubric asserted a guarantee the compiler does not give.** Triage round on an
+> external report of 12 gaps: 6 fell on recheck, 4 survived shrunk, and the costliest
+> one was the one nobody had looked at — a false sentence copied verbatim into every instance.
+
+### Fixed
+
+- **`rubrics/error-classification.md` promised what TypeScript does not deliver.** The line said
+  *"exhaustive switch guarantees coverage at the caller"*. It does not: a union of 3 codes with a switch
+  covering 2 compiles clean under `tsc --noEmit --strict` (exit 0). The guarantee only exists if the
+  `default` assigns the rest to `never`. Both examples got closed with the assertion (the one in the
+  Procedure was an `if`-chain with no `else` — it became a `switch`, one form at both levels, because
+  that is where hard rule 15 supervises the code → transport mapping), and a new anti-pattern names the
+  case. The sentence was not an omission: it was a false claim about compiler behavior.
+- **`core/protocol.md § 6` announced enforcement that does not exist.** The "hard" line listed
+  `RETRY_CAP`, `ROUND_CAP`, `MAX_PARALLEL_SUBAGENTS`, and `permissions.deny` as imposed by the harness —
+  `grep` for those names in `hooks/`: **zero hits**, and it is architecturally impossible (the golden
+  rule forbids `decision:"block"`, and fan-out goes out in one message before the first `SubagentStart`).
+  The two-half taxonomy was what fell short: now there are **three** — **Hard** (real external
+  mechanism: cadence counters + 0/1 gates in `test/`), **Counted** (counted and observable, nothing
+  blocks: `RETRY_CAP`/`QUESTION_CAP` are self-observable within their own window — a hook there would be
+  YAGNI; `MAX_PARALLEL_SUBAGENTS` is only reportable *after the fact*; `ROUND_CAP`, whose note "it is a
+  counter, not a promise" was already the prototype of the category) and **Soft**. `permissions.deny`
+  moved down to a footnote: it is a harness mechanism class, not something AFM configures.
+- **The hard-rule-13 headline lost `docs/sessions/` on the way into context.** `afm-session-start.sh`
+  and `afm-subagent-start.sh` crop each rule's headline at the closing `**` — the directory
+  was in the body, so what arrived was *"13. Tokens and secrets never leak."*, without the target. Since
+  the versioned session narrative is exactly where a secret leaks by accident, the directory moved into
+  the headline. Zero hook touched, zero regex duplicated.
+- **`core/afm.md § 4.3` told the agent to write the missing test without saying which one.** Now it names
+  the **characterization test**: it records the **CURRENT** observed behavior, never the desired one —
+  the real failure mode is the agent cementing a bug while testing what it thinks is correct.
+- **`rubrics/when-to-create-dsl.md` chose the form by cost and never by correctness.** Four forms
+  ranked by price, four self-critique questions, none about illegal order. A 5th one came in
+  (mandatory order → refuse at compile-time via type-state, **or do not propose the builder** — a single
+  function with required arguments solves the same thing without the technique) plus a purity note in
+  item 1: a chain builds an immutable value, IO in one single terminal step. An effect mid-chain forces
+  mocking the world to test a pure rule, which is what hard rule 7 separates, and a builder outside
+  `src/<domain>/` escapes it.
+- **`ops/research.md` did not plan for the tool simply not existing.** The `WebFetch` fallback covered
+  `no_match` and a non-HTML target, but not "the MCP did not come up in this session" (build failed, no
+  Node, restricted environment) — a case where the error dies in the process's stderr and never reaches
+  the context. Now it is a named case, not an agent error, and the produced artifact carries the mark
+  `> MCP unavailable this session — WebFetch mode`.
+- **Four references taught the wrong number** (own commit, wave 0): `focus.template.md` cited hard rules
+  21 and 22, which do not exist (the real one is 20); `interview/bootstrap.md` told the agent to number
+  project rules "starting at nº 17" against `core/afm.md`, which reserves 18-29 for the maintainer and
+  tells a project to start at **30**; the `afm-capture.sh` header declared matcher `Edit|Write` while
+  `hooks.json` says `Edit|Write|Bash`; `hooks/README.md` said "6 scripts" (there are 7) and "Four events"
+  (there are 6 — it was missing `SubagentStart` and `PostToolUseFailure`).
+
+### Added
+
+- **A distrust envelope on the `research` MCP's output** (`mcp/src/server.ts`). The `web_read` return is
+  the only point where third-party content enters the context, and since `ops/research.md` demoted native
+  `WebFetch` to a last resort, it became the **default** channel. BM25 makes it worse: it ranks by match
+  against the agent's own query, so whatever the agent is looking for gets promoted to the top of the
+  distilled excerpt. The content now arrives prefixed as data, not instruction — factual, non-imperative
+  phrasing, same language as `afm-pre-edit.sh`.
+
+### Not done, and why
+
+- **Destination validation (SSRF) in `mcp/src/fetch.ts` — a deliberate non-decision.** The proposal was
+  an `isUrlAllowed` rejecting loopback, link-local, and RFC 1918. Rejected for two reasons, in this
+  order: (1) **there is no privilege boundary to protect** — the MCP runs as `node bootstrap.mjs` under
+  the same user and the same network stack as the agent, which already has Bash; (2) the guard has a
+  **verified bypass**: `http://[::ffff:127.0.0.1]/` reaches Node as hostname `[::ffff:7f00:1]` and matches
+  none of the proposed regexes (same for `[0:0:0:0:0:ffff:a00:1]`). And the realistic vector —
+  exfiltration to `https://attacker.com/?d=<secret>` — stays open by construction. A decorative mechanism
+  costs the trust of every neighboring mechanism; the strictly correct form would be `undici` with a
+  custom `connect`, which pays for a new dependency in a package that today has a single one. Recorded
+  as a choice, not an oversight.
+- **A degradation contract in `mcp/bootstrap.mjs`.** The proposed acceptance criterion (`echo $?` → 1)
+  **already passes today** (`ERR_MODULE_NOT_FOUND`), and the diagnostic channel already exists:
+  `stdio: [...,"inherit"]` inherits `npm install`/`tsc` stderr — the same place the proposed
+  `console.error` would land, and neither one reaches the model's context. What was left is the side the
+  model does see, which became the `ops/research.md` paragraph above. The proposed `docs/.afm-version`
+  gate was worse: `process.exit(0)` with no handshake makes the client show "research: failed" in every
+  non-AFM project.
+- **Materializing `.husky/pre-push` in the consumer from § 6.1.** Neither husky nor `.githooks/` creates
+  a trigger without per-clone wiring (`prepare` + `npm install`; `git config core.hooksPath`, an
+  unversioned config) — and the proposed 0/1 (`git ls-files .husky/pre-push | wc -l` → 1) stays **green
+  with the hook inert**: it measures presence, not activation. Same class as the denominator bug fixed in
+  rc.1. § 6.1 also is not left unguarded already: `PRINCIPLES.md` bright line (c) and `ops/deliver.md`
+  stop at the push boundary.
+- **A `kind` of process in the ledger to show RED before GREEN.** The premise was false:
+  `afm-capture-failure.sh` already records `failure | sig=test-…` with promotion on recurrence. The two
+  proposed `kind` values would be write-only (`afm-health.sh` counts only `deliverable`/`task`),
+  `test-modified-same-commit` fires on a **well-formed** TDD commit — the good case — and
+  `task-closed-no-red-signal` is scoped per session, not per task: one RED at any point would whitewash
+  every following commit.
+- **Marking a failure→success adjacency as `sig=flaky-`.** Failing and then passing right after is TDD's
+  happy path; the heuristic would poison hard rule 19 with signatures nobody should remediate. The
+  doctrine already covers the case (`core/afm.md § 1.2`, "a flaky test becomes tech debt").
+- **A debt ratchet for brownfield.** The floor already exists in prose (`interview/refactor.md`:
+  boy-scout — new code **and modified file**), `≤ baseline` would authorize eternal stagnation, and the
+  blocker is mechanical: every command cited under `*Verification:*` is a **global** repo count and none
+  accepts a target, so "no regression in the touched file" is unimplementable as written.
+- **Evals for `deliver`/`reflect`/`evolve`.** The selection of the 7 covered ops is **measured and
+  documented** (`test/lib/eval-verdict.py`: "ops that had usageCount 0 in the 3.1.0-rc.6 baseline";
+  `deliver` = 53 uses). The suite is a discoverability death-list, not behavior coverage — and the
+  `tool_used` grader over a 20-step op measures invocation, not conduct.
+- **A hard rule for protected branches.** It does not become a universal: many solo projects work on
+  `main` on purpose, and AFM avoids imposing topology. The finding went where a vehicle already existed —
+  the bootstrap free-text question gained the ready-made example and trigger, and refactor's A.7 now
+  reads recurring merges / `CODEOWNERS` as a PR-flow signal. The rule is born in the consumer's slot
+  **30**, by the consumer's own choice.
+
+### Consumer migration
+- **Consumer-facing.** `CONSUMER_VERSION`: `3.4.0-rc.7` → `3.5.0-rc.2`.
+
+**Re-copy** (the delta is *insertions*, which do not fit a From→To table):
+
+| Consumer file | Action |
+| --- | --- |
+| `docs/rubrics/error-classification.md` | re-copy from `rubrics/error-classification.md` |
+| `docs/rubrics/when-to-create-dsl.md` | re-copy from `rubrics/when-to-create-dsl.md` |
+
+> If the instance edited the rubric locally, `update` **proposes** the diff instead of overwriting — a
+> blind re-copy would violate rule 17 (anti-context-collapse) on a doc the consumer may have extended.
+
+**Replacements** (apply in `<consumer>/docs/`):
+
+| File | From | To |
+| --- | --- | --- |
+| `docs/afm.md` | `13. **Tokens e segredos não vazam.**` | `13. **Tokens e segredos não vazam — inclusive na narrativa de \`docs/sessions/\`.**` |
+| `docs/afm.md` | `numa área que vai mexer, escreve antes.` | `numa área que vai mexer, escreve um **characterization test**: grava o comportamento **ATUAL** observado (roda e captura a saída real), nunca o desejado.` |
+| `docs/_focus.md` | `regra dura 22` | `regra dura 20` |
+| `docs/_focus.md` | `anti-context-collapse, regra 21` | `anti-context-collapse` |
+
+- **Plugin-only** (not materialized, nothing to do in the instance): `core/protocol.md` (the consumer
+  materializes `docs/protocols/p{1,2,3}.md`, which do not repeat the taxonomy), `interview/*` (only
+  affects **new** bootstrap/refactor), `ops/research.md`, `mcp/`, `hooks/`.
+
+## [3.5.0-rc.1] — 2026-07-26
+
+> **Fan-out gets a ceiling, and approved scope gets a floor.** Two gaps that the Claude 5
+> generation widens: it delegates more spontaneously than the previous one and it tends to widen
+> scope. Both turn into a number or a rule instead of prose.
+
+### Added
+
+- **Parameter `MAX_PARALLEL_SUBAGENTS`** (`core/protocol.md § 2`; default `4`, P1 `4`, P2 `2`, P3 `6`).
+  It bites in `ops/research.md` step 4 and `ops/deliver.md` 0.C — the only two fan-out sites in AFM,
+  both **without a ceiling** until now. Above the limit the instruction is **prioritize, not slice**: run
+  the N that move the decision most and log the rest as `[NEEDS CLARIFICATION:]`, because slicing into
+  rounds pays the spawn cost twice for the same signal.
+- **`core/protocol.md § 5` gets a second dimension.** The `delegation` axis always governed *what* gets
+  delegated (`none`/`read-only`/`full`) and never *how many* — `read-only` with no ceiling could still
+  fire N parallel searches. The two dimensions are now declared as independent.
+- **Scope block in `ops/deliver.md` Phase 3.** `tasks.md` is a ceiling, not a floor: the REFACTOR step
+  applies to the code the task touched, not to code that was nearby; narrowing scope is as much a
+  violation as widening it (reporting "done" with half the work finished is the symmetric failure); a
+  change of direction becomes **one sentence, then continue with the approved task** — resizing the task
+  is the owner's decision. This is the execution-side counterpart of #6, symmetric to the gate: the gate
+  controls what enters scope, this controls that it does not grow on its own afterward.
+
+### Fixed
+
+- **`test/skills-lint.sh` measured the wrong denominator.** The baseline was named
+  `listing_total_all_plugins` but it summed only the three plugins **in this repo** — and the listing
+  budget is **one budget, shared by every installed plugin plus `~/.claude/skills`**. That is how `seo`
+  started to render **5 entries with no description** (`gaps`, `index`, `pseo`, `watch`, `write` —
+  exactly the ones with `usageCount: 0`) while the gate stayed green: the toolkit shrank, the neighbor
+  grew, and nothing measured the sum that matters. Same class as G3 — a gate that measures a proxy
+  instead of the real thing. The key became `listing_total_toolkit` (the old name was a lie) and
+  `test/lib/listing-shared.py` + `gate_listing_shared` were added, **advisory by design**: the installed
+  set is local to the machine, so failing there would fail the environment, not the commit. Measured
+  here: 25,815 total chars, of which 6,070 belong to a plugin outside the toolkit.
+
+### Not done, and why
+
+- **We did not remove the verification directives from the ops.** Opus 5 migration guidance says to
+  delete self-check scaffolding ("check your answer") because the model already verifies on its own and
+  instructing it causes over-verification. Audited: of the 29 occurrences of "verification" in the ops,
+  **25 are `*Verification:*` lines** — the executable 0/1 oracle the hard rule requires, which is
+  **external signal**, not self-judgment. A search targeted at real scaffolding (self-check, a dedicated
+  verifier sub-agent) returns **zero**. Principle #5 already covered this discipline; deleting those
+  triggers would gut rule 3 (mechanize-or-demote) with no gain. Logged here because the next audit will
+  run the same grep and deserves the ready answer.
+
+### Consumer migration
+- **`MAX_PARALLEL_SUBAGENTS` is the only row in the table whose `default` does NOT reproduce
+  pre-v4 behavior** — fan-out was unlimited before. If you depend on firing more than 4 sub-agents in a
+  single turn, declare the value in the project's protocol; otherwise no action is needed.
+- **Run `/afm:update`** to materialize the new row in your `docs/` parameter table and the scope block
+  in Phase 3.