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

package/content/CHANGELOG-archive.md

@@ -0,0 +1,806 @@
+# Changelog (archive) — framework-template
+
+> **Historical archive. Nothing here was rewritten or compressed.**
+>
+> These are the releases from `3.0.0-rc.1` (2026-05-28) through `3.4.0-rc.7`, moved out of
+> `CHANGELOG.md` on 2026-08-23 so the working file stays readable. The active file keeps
+> `3.5.0` onward.
+>
+> **Why moved and not merged.** Two compression passes were run and both were rejected by
+> an adversarial check. This file is dense: 1832 lines held 322 file paths, 96 measured
+> numbers, 50 table rows, 32 consumer-migration blocks and 10 arXiv citations. Almost
+> nothing here is ornament, so compressing it degrades a record instead of shortening one.
+>
+> **`ops/update.md` reads this file too.** The `### Consumer migration` blocks are
+> parsed to decide what a consumer project must materialize. A version range that reaches
+> back before `3.5.0` must read this archive, not only `CHANGELOG.md`.
+
+## [3.4.0-rc.7] — 2026-07-26
+
+> **The plugin boundary becomes absolute, and the session becomes usage telemetry.** Two halves coupled by
+> one point: the finding that `promote` now records lives in `afm_findings` of the session file.
+> Executes Concept #5 of v4 (F9).
+
+### BREAKING (pre-release) — `promote` no longer writes to the plugin
+
+- **`ops/promote.md` becomes a pure recorder.** Steps 3-6 (edit `framework-template/`, bump
+  `VERSION`, write `CHANGELOG`, "do not push") **are gone**. What stays: the reproducible mechanical
+  evidence gate and the walk classification, which now decides the finding's `target:` field instead of a
+  write destination. **Tracks A/B collapsed into one** — without a write to the plugin, the distinction no
+  longer discriminated anything.
+- **Why, with the measurement:** the write steps resolved
+  `${CLAUDE_SKILL_DIR}/../../framework-template/...`, which points to the **versioned install cache**
+  (`~/.claude/plugins/cache/<mkt>/<plugin>/<version>/`) — **even in a session running inside the
+  plugin's own repo**, because since ADR-0005 the install is a copy, not a symlink. Measured 2026-07-26: 6
+  copies, 93 MB. Every `promote` edit would die on the next `plugin update`, with no error and no signal.
+  **The op never worked anywhere**; the owner invariant and the defect pointed to the same edit.
+- **`PRINCIPLES.md` #6 bright line (b) hardens:** from "stops and asks" to **"no path exists"**.
+  No AFM op writes to the plugin. #7 gains the corollary of who edits (the maintainer, with the plugin
+  repo open) and why it is not just discipline. **Invariant principle reframe — hard rule 11.**
+- **The boundary post-condition (`evolve.md § Phase 4.3`, two branches) becomes a universal assertion**
+  of the ops, not a guard for one cycle. The 4 mirrors already pointed there.
+- **New mechanical gate in `test/refs-lint.sh`:** no op may declare an effect on the plugin on the
+  **Forma** line. Uses the structure that already existed instead of hunting a write verb — RED only on
+  `promote`, zero false positive.
+
+### Added — `docs/sessions/` stops being an audit log and becomes usage telemetry
+
+- **What was missing was not a record of what changed** (git already does that, and the directory was not
+  even versioned) — it was a record **of what was asked and of how AFM was used to serve it**. It is the
+  only telemetry that neither git nor the substrate has, and the one an agent in the plugin repo needs
+  to improve AFM from real usage.
+- **Three layers with no duplication:** `sessions/<date>-<sid6>.md` (rich frontmatter + timeline in 2 parts +
+  inline `afm_findings`) · `docs/evolution/NNN` (what `reflect` found **and fixed** — already canonical) ·
+  the transcript (via `claude_session_id`). **`docs_findings` is not a field** — it collapses into a
+  `reflection:` link; keeping the finding *and* the fix in two places would be the inflation `reflect`
+  itself forbids.
+- **`afm-session-end.sh` (`Stop`, 0-LLM):** frontmatter gains the **full** `claude_session_id` (the id was
+  truncated with `cut -c1-6` and only became a filename suffix — that made the pointer to the transcript
+  useless), `name` (mechanical slug of the dominant subtree), `date`, `reflection:`. The body gains
+  `## what was asked`, `## how it was executed`, and `## afm_findings`.
+- **`ops/reflect.md § 5.1` — session closing.** The hook writes the mechanical part; `reflect` fills in the
+  judgment part. **A session with no `reflect` keeps only the skeleton**, and that is acceptable —
+  rejected: intercepting `Stop` (blocks every turn end) and a per-turn timeline from `reconcile` (one write
+  per turn in every adopted project). No new template: partial fill of the
+  `evolution-report.template.md` (rule 34).
+- **`sessions/` is dual-tier** (`rubrics/episodic-vs-semantic-boundary.md`): the handoff block decays,
+  the telemetry does not. **`state: consumed` marks the handoff as read, never the file as dead.** The
+  exclusion in rule 17 still runs on a closed path — the file is append-per-session, never rewritten.
+- **Hard rule 13 now covers `docs/sessions/`** — the mandatory counterpart of versioning the narrative: the
+  agent cites the command it ran, and the command held the key. New verification by known credential
+  prefix (`sk-`, `ghp_`, `AIza`, `xox*-`, JWT), tested against a good **and** a bad case in the smoke test.
+- **`hooks/test/run.sh` 54 → 57 asserts:** full id, 7 frontmatter fields, `afm_findings` reserved,
+  dedup preserved, and the rule 13 pattern against 5 prefixes + 1 negative.
+
+### Fixed
+
+- **`afm-capture-failure.sh` had two dead patterns** (SC2221/SC2222): `*"npm test"*` already matches
+  `pnpm test` and `*"go test"*` already matches `cargo test` — the dedicated entries were never reached. No
+  behavior effect (all assigned the same oracle), but it left `shellcheck --severity=warning`
+  red. **It only surfaced because shellcheck ran through a container:** it is not installed on this machine and
+  the smoke test skips it silently (`shellcheck ausente — pulado`), so hard rule 33 had been
+  verified only halfway.
+
+### Consumer migration
+
+- **Take `docs/sessions/` out of `.gitignore`** and start versioning the directory. That is what makes the
+  telemetry useful (it survives the machine and travels).
+- **Extend hard rule 13** in your `docs/afm.md § 3` with the credential-prefix check over
+  `docs/sessions/` — without it, versioning the narrative is the new leak path.
+- **Old session files stay readable** (`kind: handoff`): the hook does not rewrite what already exists.
+  The new fields appear starting with the next session that has work.
+- **`/afm:promote` changed contract.** If any of your flows expected it to edit the plugin, it no longer
+  does — and it did not actually do so before either, it wrote to a disposable cache.
+
+## [3.4.0-rc.6] — 2026-07-26
+
+> **The gates passed because they measured the wrong thing.** Four defects from the same family: a linter
+> blind to a whole class of reference, a hook that counted noise as signal, an axis that never ran, and the
+> instance/plugin boundary guard passing in silence exactly where it needed to block.
+
+### Fixed
+
+- **`refs-lint.sh` gains class 5 — a backtick path.** Classes 1-2 covered a command and a markdown link.
+  The reference that escaped in rc.5 had a third nature (`MAINTAINERS.md` cited in prose inside a
+  SKILL.md, after the file left the plugin). Gate green, dead reference **installed in the consumer**.
+  It covers a canonical root doc cited by name plus a path anchored in the plugin. It ignores consumer
+  notation (`/docs/`, an instance dot-dir) and prose with an ellipsis. **`skills/promote/SKILL.md` fixed.**
+- **Instance/plugin boundary — the guard was inert in production.** `git -C <not-a-repo> status
+  --porcelain` exits with **code 128 and empty stdout**, so the "empty output" check **passed** in a
+  directory that is not a git repo — which is exactly the plugin-root of a consumer (a versioned
+  marketplace cache). The postcondition now has **two branches** (`rev-parse` decides), and the no-git
+  branch compares against a `T0` captured in Phase 1. Canonical in `ops/evolve.md § Phase 4.3`; the 4
+  mirrors now link to it.
+- **`afm-health.sh` — vital signs with ~90% noise.** Measured on this repo: 23 dead refs, of which 21
+  were a subproject path resolved against the root (including the check for rule 30 itself), and 5 of
+  5 § 3 triggers the same way. Resolution now tries the path as a **versioned-file suffix** before
+  declaring it dead; a line announcing removal and an instance dot-dir path stop counting. **23 → 0.**
+- **`afm-health.sh` A1 never ran without `docs/adr/`.** The guard was `ls ./docs/*.md ./docs/adr/*.md`,
+  and `ls` exits non-zero if **any** argument is missing — so every instance still without an ADR had the
+  axis silently turned off (it did not report "0 dead refs": it did not run). Caught by an assert that
+  passed for the wrong reason.
+- **`afm-health.sh` A2 counted a mention as a gap.** A backtick marker is the doc **teaching the
+  convention**, not leaving a gap; `docs/research/` is episodic evidence that cites other docs. 20 → 4.
+- **`afm-health.sh` A7 routed to the opposite of the right call.** In a monorepo where one subtree holds
+  >80% of the counted code, the global ratio is not interpretable: here it gave 2% ("under-documented" →
+  document more) when, once you exclude the engine that § 3.1 scopes out, it is 93% ("bloated" → the
+  opposite). It now reports the composition and **does not route to an action**.
+
+### Tests
+
+- `hooks/test/run.sh`: **46 → 51 asserts.** Two new fixtures that *are* git repos (the old ones were not,
+  so the suffix-match was never exercised) — one proves a subproject path is not a dead ref, the other
+  that a reference with no anchor at all **still** gets flagged. The gate must not be blind while proving
+  it is not noisy.
+- `refs-lint.sh --self-test`: 7 → 11 asserts (missing root doc, a sibling of the citer, both prose forms).
+
+### Consumer migration
+
+- **Consumer-noop.** Nothing materialized changes. `CONSUMER_VERSION` stays at `3.3.0-rc.1`.
+
+## [3.4.0-rc.5] — 2026-07-25
+
+> **`MAINTAINERS.md` leaves the plugin.** It gave instructions on how to **edit AFM** — and the person who edits AFM edits it **in this repo**, whose `/docs/` is the instance that already governs this work. The distributed plugin carried 140 lines of prose useful to only one repository. This was the duplication rule 34 forbids, in the most visible place possible.
+
+### Removed
+
+- **`framework-template/MAINTAINERS.md`** (140 lines). Its content went to two places, by nature:
+
+| Content | Went to | Why |
+| --- | --- | --- |
+| Shared hooks contract | **`plugins/afm/hooks/README.md`** | 6 scripts referenced it; the contract lives next to what it governs, and **travels with the plugin** |
+| Versioning, watermark, how to add a component, degree of freedom, NEVER do | **`docs/procedures/manter-o-plugin-afm.md`** (this repo's instance) | it is a maintenance runbook, and maintenance happens here — `procedures/` is the exact family for this |
+
+Content that **was already a hard rule** (`docs/afm.md` § 3: 11, 30, 31, 33, 34) was not copied: the runbook points to those rules. Duplicating the rule next to the procedure would repeat the error this removal fixes.
+
+### Changed
+
+- **`skills/init` and `skills/refactor`: the "How to modify the methodology" section is removed.** This was prose in a thin wrapper that explained how to **edit the plugin** — not what the skill does. This cuts the 80% where it is obvious.
+- **`ops/promote.md`**: the 3 bump criteria became inline (one line). `promote` **edits** the plugin and travels to the consumer — pointing it to a doc in the maintainer's repo would be a reference that does not resolve from where it runs.
+- **`ops/evolve.md`**: "never renumber a rule" became inline with the reason (renumbering breaks every external reference and every trigger that cites the number), instead of a link.
+- **`ops/diagnose.md`, `README-light.md`, `hooks/test/README.md`, 6 hook scripts, `CLAUDE.md`, `docs/afm.md`, `docs/gotchas.md`, `docs/adr/0002`**: repointed.
+
+### Consumer migration
+
+- **Consumer-noop.** `MAINTAINERS.md` was never materialized in the instance (it was plugin-only, and its own header said "not runtime"). `CONSUMER_VERSION` stays at `3.3.0-rc.1`.
+
+## [3.4.0-rc.4] — 2026-07-25
+
+> **F4 (forma e grau de liberdade) — what was convention becomes a verifiable contract.** The 21 ops now declare, in one line, what they do and how much freedom they have. Merge and removal stay out of scope (ADR-0012 + organic data).
+
+### Added
+
+- **Line `> **Forma** —` in all 21 ops**: effect · trigger · precondition · composed-of · **grau de liberdade**. It exists so the agent can decide if the op fits **without opening the whole file**, and so the protocol can compose without duplicating procedure.
+- **`test/refs-lint.sh`: form rule** — an op with no line, or with a grau outside the closed vocabulary (`alto|médio|baixo`), fails. Without a gate, a new op is born with no declaration, and the form stays a convention only the author remembers.
+- **`MAINTAINERS.md` § Adicionar sub-flow ops novo** gains step 0, with the consequence table: grau **alto** means the op file carries the **contract** (input, output, invariants) and little else — prescribing the path where the decision depends on context is *over-specification*, a named anti-pattern.
+
+### Measured
+
+Distribution: **alto 2 · médio 8 · baixo 11**. And the expected correlation (high grau ⇒ heavy prose) **does not exist**:
+
+| grau | ops | average lines |
+| --- | --- | --- |
+| alto | 2 | 72 |
+| **médio** | 8 | **117** |
+| baixo | 11 | 62 |
+
+The **médio** grau carries the most prescription, dominated by the two orchestrators (`deliver` and `evolve`, 184 lines each) — which arguably need procedure because they compose other ops. Among the `alto` ops, `reconcile` has **24 lines** and is the example of the grau applied well; `research` (120) is the outlier, and part of the weight came from this line's own rc.1 (the two modes). This stays on record as the first candidate for a future prune — which remains **not** approved.
+
+### Consumer migration
+
+- **Consumer-noop.** The form line lives in the plugin's `ops/`, which are not materialized. `CONSUMER_VERSION` stays at `3.3.0-rc.1`.
+
+## [3.4.0-rc.3] — 2026-07-25
+
+> **F8 — `update` learns to replace.** Until now it could only **copy new content**. Rename and removal existed only as prose in the migration block, with a single precedent (the `kenpachi`→`evolve` rename: one marker and one skill name). A framework that renames an already materialized term needs mechanics. Otherwise the instance keeps the old vocabulary, the plugin has the new one, and `diagnose A7` flags the contradiction later.
+
+### Added
+
+- **`**Replacements**` block in the CHANGELOG** — a `File | From | To` table that `update` executes. Six 0/1 application rules: proof of need through `grep` before touching anything; **literal** replacement, never regex (regex on a hand-edited instance rewrites what nobody asked for); proof of application afterward with **both** counts (the first count alone cannot distinguish "replaced" from "deleted"); a missing file is skipped instead of created; **`[TBD]` stops the sync** (#4 — the owner's stance wins); and a replacement never creates a section.
+- **`test/update-rehearsal.sh`** — a rehearsal on a disposable consumer, 13 asserts. Replacement fails in a way copy does not — it rewrites a doc the owner edited by hand. Rehearsing before touching the real instance is what separates "the migration works" from "it worked on the two I tested."
+
+### Decided
+
+- **Removal stays out of mechanical scope, and this is deliberate.** Deleting content from the instance is a destructive operation, and destructive is a bright line in **every** protocol (#6). A release that removes something states in prose what became obsolete. The owner deletes it if they want. **`update` never deletes.**
+
+### Consumer migration
+
+- **Consumer-noop.** The mechanics belong to the op. Nothing new to materialize. `CONSUMER_VERSION` stays at `3.3.0-rc.1`.
+
+## [3.4.0-rc.2] — 2026-07-25
+
+> **F4 (mechanical part) — a partial read stops being silent.** The part of the consolidation that does **not** depend on organic data. Merge and removal stay blocked: ADR-0012 proved that no operation should be removed, and the license to merge depends on the cadence counter building up real use.
+
+### Added
+
+- **Scope indicator in 16 reference files** (`> **Neste arquivo:** …`) — one line that lists the sections, right below the title.
+- **`test/refs-lint.sh`: scope rule** — a reference file with more than 100 lines and 3+ sections declares the scope at the top, or it fails. More recorded debt, under the same discipline as `skills-lint`.
+
+### Measurement corrections
+
+The plan dossier recorded **reference depth 3-5 and 2 cycles**. Measured with a graph resolver over the real links:
+
+- **Max depth is 3** (`SKILL → op → core → rubric`), reaching 8-11 files. Not 5.
+- **Zero link cycles.** The "2 cycles" (`deliver`↔`specify`, `evolve`↔`update`) are references in **prose** — one op mentions the phase of another op in the text. Prose is not a link that anyone follows, and the navigation graph has no cycle at all.
+
+**Why the target stopped being "depth ≤1".** The official recommendation is to reference one level down from the SKILL.md. Here that would need the op to link nothing — impossible without duplicating `core/`, which breaks rule 34 (procedure in `ops/`, principle in `PRINCIPLES.md`, each in one place only). Chasing the number would break the rule that gives the number its meaning.
+
+What the recommendation **protects** is named in the doc itself: a silent partial read (`head -100` leaves the agent with incomplete information without knowing it is incomplete). And the remedy also comes from the official doc — a reference file with more than 100 lines declares the scope at the top. That is the target now: mechanical, verifiable, and it attacks the risk instead of the proxy.
+
+### Consumer migration
+
+- **Consumer-noop.** The scope indicator goes into `core/*.md`, which `/afm:update` materializes; an existing instance gets it on the next sync, with no behavior change. `CONSUMER_VERSION` stays at `3.3.0-rc.1`.
+
+## [3.4.0-rc.1] — 2026-07-25
+
+> **F7 of v4 — own research MCP.** `plugins/afm/mcp/`, TypeScript, self-contained. It reads the page and returns **only the excerpts that match the query**, ranked by BM25, inside a token budget. `WebFetch` native becomes the last resort.
+
+### Added
+
+- **`@afm-mcp/research`** — one tool (`web_read`). Pipeline: fetch → content extraction → chunking ~200 tokens at block boundary → BM25 (`k1=1.5`, `b=0.75`) → budget-based selection. Parameters come from published measurement: recall stays almost flat between 200 and 800 tokens, but IoU drops ~4.6x at 800, and overlap makes IoU worse. BM25, not embeddings, because the regime is zero-shot on a disposable page — embedding N chunks of a page that will not be re-queried does not pay off.
+- **`research` in two modes** — `normal` (MCP only, inline) and `deep` (`Agent(Explore)` using `web_read` instead of `WebFetch`). What promotes to `deep`: a user flag or the active protocol (phase 1 of P3).
+- **Eval with a frozen corpus** (`mcp/evals/`) — 4 real pages, target facts verified by `grep`, zero API calls. Arm A = the whole page extracted. Arm B = the distilled version.
+
+### Design notes
+
+- **One tool, not a set.** The official guidance is explicit: *"more tools don't always lead to better outcomes"*, and a bloated set with ambiguous decision points is a named failure. A new tool enters only with a real case.
+- **Headless stays OUTSIDE the minimum cut, but the signal is measured.** ~36% of sites return <80% of their content without JS, and the median time to network-idle with headless is ~21x longer. Paying 21x on 100% of fetches to cover 36% is the wrong trade-off as a default — so `fetch.ts` **detects** (`jsLikely`) and reports it, so the decision to raise the step comes from measured frequency.
+- **`no_match` is a response, not an empty result.** A query that does not match returns an explicit status instead of the first chunks. Irrelevant content that looks like an answer is worse than nothing, because the model has no way to tell.
+- **The pipeline is extractive by construction** — every returned line came literally from the page. Hallucination is not measured by sampling; the eval verifies the construction.
+
+### Record correction — the acceptance criterion was falsified and replaced
+
+The plan declared `tokens(B) ≤ 0.3 × tokens(A)`. **It was falsified on the first run**, and the reason is structural, not a tuning issue: `tokens(B) ≥ relevant content` is an identity. On a page with relevance density above 30%, **no** correct distiller reaches 0.3×A — reaching it would require dropping relevant content, which is the quality loss the first inequality forbids. The two were unsatisfiable together in this regime. Measured on the corpus: density of 61%, 70%, 98%, and 105%.
+
+Replaced by `tokens(B) ≤ budget` (always) **and** `tokens(A) > budget ⟹ tokens(B) < tokens(A)`. The 0.3x was a proxy for "saves a lot on a large page"; what matters for the context is the ceiling. The observed saving keeps being reported on every run, so the claim stays auditable.
+
+**Known corpus bias:** the 4 pages are technical reference, high density. A blog or marketing page would show a much bigger saving. The extreme case (`hooks-events`, 4 MB) is the regime the pipeline exists for: **36,708 → 1,472 tokens (−96%)**, with fact-recall intact.
+
+### Fixed
+
+- **The budget counted the raw chunk but returned chunk + breadcrumb** — it silently overran the ceiling (1688 returned against 1500). `render()` became the single source of shape and cost. Caught by the eval, with a regression guard in the unit test.
+- **`&ecirc;` and the accented Latin-1 block passed through raw** into the extracted text. In a PT-BR corpus this breaks the term in the BM25 index, and the right chunk stops being retrievable. Caught by the unit test.
+
+### Consumer migration
+
+- **Consumer-noop.** The MCP is an install-side surface; the plugin's `.mcp.json` declares the server, and `bootstrap.mjs` installs/builds it in the cached copy on first use. `CONSUMER_VERSION` stays at `3.3.0-rc.1`.
+
+## [3.3.0-rc.1] — 2026-07-25
+
+> **F6 of v4 — the `protocol` layer.** The autonomy posture stops being global and implicit. It becomes **declared per work item**. Protocol is **data**, not a new execution path: it parametrizes operations that already exist. A project with no `protocol:` declared runs the defaults, which reproduce pre-v4 behavior.
+
+### Added
+
+- **`core/protocol.md`** — canonical definition: 5 fields, 8 parameters with a default, the 3 presets, what the protocol does NOT govern, and the sub-agent delegation ceiling.
+- **`ops/protocol.md` + skill `/afm:protocol`** — declares/reports the active protocol. With no argument it only reports. With an argument it materializes the preset and writes `protocol:` to `docs/_focus.md`.
+- **`templates/protocols/{p1,p2,p3}.md`** — the presets as versionable data.
+- **`SessionStart` injects the active protocol** (+ up to 700 chars of the file). Letting the model *discover* a file that nothing references would measure discovery by chance, not the layer.
+
+### Changed
+
+- **`AUTONOMY=high|normal` → `plan` field of the protocol** (11 sites in `ops/deliver.md`, `core/afm.md`, `ops/evolve.md`). `"go"` survives as an **ephemeral gate override** — it forces `plan=auto` for this delivery without changing the project's contract. A gate override is not a contract change. Otherwise the contract stops being a contract.
+- **The 3 bolts of the loose loop** (`core/afm.md § 2`): the READ step resolves the protocol. `PLAN_THRESHOLD` shifts the threshold of step 3. `RETRY_CAP` parametrizes the cap in § 5.1. § 8.5 closes the task and feeds the cadence. **The loop was not rewritten** — it only gained a name for the literals that were already there.
+- **À-la-carte back-pointers now conditioned** (`specify`/`plan`/`tasks`): *"running this op IS ALREADY the approval"* stops being unconditional. It was the side door through which any assisted posture leaked — these ops were **more autonomous than the orchestrated path**, and not even `"go"` governed them. `research` stays invariant by purpose. It is input, not a definer of the work inventory.
+- **`PRINCIPLES.md` #6 reframed** — the **degree** of autonomy becomes a parameter. The **form** (materialize-and-report), the 4 bright lines, and the load-bearing test stay invariant.
+- **`ops/evolve.md`** stops denying a flag that no longer exists. A mandatory gate in every protocol is a first-class exception, next to the bright lines.
+
+### Design correction
+
+- **`disallowed-tools: AskUserQuestion` is NOT the hard mechanism of P1.** The plan expected this, but the field is **per-skill** frontmatter, static, and the chosen architecture is protocol-as-data over a **shared** runner (`deliver` serves all three presets). A skill just for P1 would multiply the listing — the problem v4 exists to solve. The real mechanism is **`ROUND_CAP = 0`**: with no round available, every irreducible item falls to `UNKNOWN_POLICY` and becomes `[ASSUMED:]`. A counter, not a promise.
+- **The predicted conflict with `gate_listing_budget` did not happen.** `/afm:protocol` is the 23rd skill and should have burst the one-directional gate. The rc.9 pruning left ~5k of slack and it fit (26,541 of 31,524). The allowlist entry stays the same either way — what stops silent growth is the recorded intent, not the slack.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.3.0-rc.1).** `/afm:update` materializes `docs/protocols/` with the 3 presets and writes `protocol: [TBD]` to `docs/_focus.md`. **Nothing changes in behavior until the owner declares it** — assuming the posture the owner wants would be invention (principle #4). P1 needs explicit invocation in the session. It is not granted by a file in the repo.
+
+**Replacements** (apply in `<consumer>/docs/`):
+
+| File | From | To |
+| --- | --- | --- |
+| `docs/afm.md` | `AUTONOMY=high` | `plan=auto` |
+| `docs/afm.md` | `AUTONOMY=normal` | `plan=assisted` |
+
+## [3.2.0-rc.1] — 2026-07-25
+
+> **F1 of v4 — the hard half.** Everything here is a mechanism the harness **enforces**, with no dependence on any assumption that the model cooperates. It closes three measured gaps: sub-agent with no rule, cadence with no counter, and a failure substrate that never existed.
+
+### Added
+
+- **`afm-subagent-start.sh` (`SubagentStart`).** `SessionStart` does **not** fire for a sub-agent — measured in a 12-agent fanout: zero hook attachment in the transcripts, against 5 in the parent session. `CLAUDE.md` reaches the agent through the harness (except in `Explore`/`Plan`, which skip it by design and with no override), but the instance's **materialized** hard rules reached it through no channel. It injects the `§ 3` headlines, ~340 chars. No-op for `Explore`/`Plan`: they have Write/Edit denied, and a code rule is a **write trigger** — an agent that does not write cannot violate it. The exclusion lives in the script, not the matcher, so it stays testable.
+- **`afm-capture-failure.sh` (`PostToolUseFailure` Bash).** `remediate` read `docs/.afm-log-failures/` — which **nothing populated**: only the agent, in the `§ 5.1` terminal, and `afm-capture.sh` excludes the directory. A 0/1 trigger over a structurally empty set is a dead trigger, and it was the second cause (independent of the listing truncation) of `remediate` never having run. Two levels: every **oracle** failure (closed allowlist) appends an event; only **recurrence** of the same `sig` promotes it to an artifact — which respects `§ 5.1`, because a failure resolved on retry is transient.
+- **Derived cadence.** `task` events (a `git commit`) and `deliverable` events (a `tasks.md` with no `- [ ]` and with `[X]`), read by `afm-health.sh` in `SessionStart`. The counter is **never stored** — keeping mutable state in `.afm-log/` would violate **rule 18**, and in `_focus.md` it would collide with **rule 20** and create a race with the agent. Deriving it amends no universal rule. Two signals because they are two granularities: `deliverable` feeds the `evolve` threshold; `task` feeds the `reflect` threshold and is the **only** one that sees a small change, which by `§ 2.1` does not even open a feature folder — which is where most of the real work happens.
+
+### Fixed
+
+- **`afm-pre-edit.sh`: `agent_id` in the cache key.** The sub-agent **shares the parent's `session_id`** (verified in the harness's real payload), and only calls from inside it carry `agent_id`. Without this in the key, a file already remembered in the parent had its reminder **suppressed silently** inside the sub-agent — exactly where context is scarcest.
+- **The smoke test covered by name.** The `shellcheck` script list was written by hand, so any new hook was **skipped silently** and the gate looked green without covering it. It now derives from the directory.
+
+### Changed
+
+- **Factual phrasing in the hooks.** `additionalContext` in command form triggers the model's defenses (official anti-prompt-injection guidance). "Before touching code, consult /docs" became "The normative source of this project is /docs"; the `PreToolUse` warning lost the `⚠` and the imperative.
+- **`SessionStart`: 6,008 → 2,631 chars (−56%).** It injected 4,000 chars of `§ 3` in prose every session; now it sends only each rule's headline. Nothing is lost: `PreToolUse` delivers the **full** rule at write time, by path-match — real progressive disclosure instead of precautionary front-load.
+
+### Consumer migration
+
+- **Consumer-noop.** The instance gains `docs/.afm-log/events/` with new `kind` values and, on recurrence, `docs/.afm-log-failures/` — both on-demand, append-only. `CONSUMER_VERSION` stays at `3.1.0-rc.7`.
+
+## [3.1.0-rc.9] — 2026-07-25
+
+> **A description routes. The body explains.** The rc.8 took the skills rendering with no description from 7 to 3. The 3 remaining (`generalize`, `remediate`, `restructure`) sat at the edge of the shared budget — they needed ~1.6k more chars.
+
+### Changed
+
+- **7 descriptions trimmed of internal mechanics** (`evolve`, `reconcile`, `update`, `reflect`, `remediate`, `restructure`, `generalize`): −1,387 chars. What left was procedure (the `evolve` 3 buckets, the `reconcile` memory-vs-doc criterion, the `generalize` backtrack, …) — information the model does not use to **route**, and that already lives, verifiably, in the matching canonical op. This is rule 34 at work: procedure in `ops/`, routing in the `description`.
+- **`afm` listing: 10,033 → 8,646 chars.** Cumulative since rc.6: **26,683 → 8,646 (−68%)**. Total for installed plugins: 31,524 → 25,988.
+
+### Consumer migration
+
+- **Consumer-noop.** `CONSUMER_VERSION` stays at `3.1.0-rc.7`.
+
+## [3.1.0-rc.8] — 2026-07-25
+
+> **`when_to_use` leaves the frontmatter — negative routing moves down into the body.** The rc.7 shrank the listing and **it was not enough**: the 7 skills with zero usage still rendered with no description. The measurement showed why — the budget is **shared** across all plugins and built-ins, and loading only `afm` renders all 22 in full (`SEM_DESC=0`). Shrinking `afm` was necessary, not sufficient.
+
+### Changed
+
+- **Frontmatter of the 22 skills: `when_to_use` removed.** The `ATIVA` half (trigger words) was **merged into `description`** — the field the official spec requires to contain *"what it does **and** when to use it"*, and the only documented one. The `NÃO ATIVA` half became the **`## Quando NÃO ativar`** section in the `SKILL.md` body.
+  **Why the body:** disambiguation is a criterion for **who already activated**, not for activation. Keeping 4,061 chars of negative routing always-resident charged context to describe *when to do nothing* — and the body loads on demand, with no penalty until it is read.
+  **Spec note:** `when_to_use` **does not exist** in the official Agent Skills spec (only `name` and `description`), but the Claude Code binary **injects it** — it builds the entry as `description + " - " + when_to_use`. AFM was paying 2x for a surface the doc treats as a single field.
+- **`afm` listing: 14,182 → 10,033 chars** (−29%). Summed across installed plugins: 31,524 → 27,375.
+
+### Consumer migration
+
+- **Consumer-noop.** Skills are install-side surface; nothing materialized in `<consumer>/docs/` changes. `CONSUMER_VERSION` stays at `3.1.0-rc.7`.
+
+## [3.1.0-rc.7] — 2026-07-25
+
+> **F0 of v4 — listing unblocking and the gates it was missing.** The skill listing has a budget (`contextWindow × 4 × 1%`); when it overflows, the binary prioritizes by `usageCount × decay` and renders the losing entries **with no description**. The 7 `afm` skills with zero use (`analyze`, `clarify`, `diagnose`, `export-template`, `generalize`, `remediate`, `restructure`) were exactly in that state — invisible to the model, which blocked use, which lowered the score. A ratchet. This release installs the instrumentation that measures it and fixes the rule that let the problem start.
+
+### Fixed
+
+- **13 dead links in `core/ach.md`** (§ rubrics): `../framework-template/rubrics/*.md` → `rubrics/*.md`. The old path did not resolve **from any root** — not in the plugin, not in the materialized instance. The new form resolves in both (`rubrics/` here, `docs/rubrics/` there).
+
+### Added
+
+- **`test/lib/skill-entry.py`** — measures the resident cost of each `SKILL.md` in the listing, mirroring the binary's formula (`2 + len(name) + 2 + min(len(desc + " - " + wtu), 1536) + 1`). Its own frontmatter parser: multi-line YAML does not come out clean in shell, and this data is the base for all the new gates.
+- **`test/baseline/`** — a baseline measured **before** any v4 edit: per-skill, aggregates, `usageCount` snapshot, pre-existing debt, and justified reference exceptions.
+- **`test/skills-lint.sh`: 2 rules + 1 aggregate gate.** `rule_desc_len` (≤1024, the documented limit), `rule_name_spec` (≤64, `[a-z0-9-]`, no reserved term, `name` == directory) and `gate_listing_budget` — **one-directional**: shrinking passes, growing fails; a new skill enters through `test/baseline/allowlist.tsv`, never through a silent rebaseline. A pre-existing violation becomes registered `debt`, not a silent exemption.
+- **`test/refs-lint.sh`** — a dead reference in two classes: a `/<plugin>:<skill>` command that does not exist, and a markdown link that does not resolve **relative to the citing file** (resolving from the root produces a false positive). This is the gate that makes it safe to consolidate operations in slices.
+
+### Changed
+
+- **Hard rule 30 (this repo's instance) — surface widened from `framework-template/` to `{framework-template,skills,hooks}/`.** The old trigger did not cover `skills/`: commit `39c8a7b` trimmed the 22 `SKILL.md` files with no bump — legitimately, by the letter of the rule — and the installed cache kept serving **26,639** listing chars against the HEAD's **14,182**, under the same tag `3.1.0-rc.6`. A version that does not bump leaves the marketplace unaware it needs to recopy.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.1.0-rc.7).** Nothing else changes in the instance — the new gates are repo-level, not materialized.
+
+**Replacements** (apply in `<consumer>/docs/`):
+
+| File | From | To |
+| --- | --- | --- |
+| `docs/ach.md` | `../framework-template/rubrics/` | `rubrics/` |
+
+## [3.1.0-rc.6] — 2026-06-16
+
+> **Fix for the rc.5 design — after a large delivery, `deliver` calls `/afm:reflect`, not `/afm:evolve`.** The automatic pass at the end of a **large** delivery under `AUTONOMY=high` (step 4.D) is **session behavioral self-reflection** (`reflect` — where the docs guided the delivery poorly), not the full instance health cycle (`evolve`, heavier / signal-driven / with a cooldown). `reflect` is session-scoped, **auto-gated by evidence** (no friction experienced → it stops, no cooldown) and keeps its own gate. This fits better: the delivery's *new* knowledge is already covered by `reconcile` (4.B). `reflect` covers the complementary axis — the doc that **failed as a harness**.
+
+### Changed
+
+- **`deliver` step 4.D + stop table + suppression contract + `core/afm.md § 2.2` step 6:** `/afm:evolve` → **`/afm:reflect`**. `reflect` keeps its own gate (it does not auto-apply — #6; the human approves the instructivity refinements). Removed the mention of cooldown/unlock (`reflect` has no cooldown — it is auto-gated by session evidence). Under `AUTONOMY=normal` it stays only **suggested**. The `/afm:evolve` skill still exists and can be invoked à la carte — it only stops being the automatic post-`deliver` trigger.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.1.0-rc.6).** `/afm:update` materializes the fixed step 6 in `afm.md § 2.2` (`reflect` instead of `evolve`). Nothing else changes.
+
+## [3.1.0-rc.5] — 2026-06-16
+
+> **BREAKING (pre-release) — rename `kenpachi` → `evolve`.** The orchestrator of the local documentation self-evolution cycle drops the codename `kenpachi` (the doc itself admitted it was not descriptive) and becomes **`evolve`** — aligned with `docs/evolution/` (the lineage it writes) and with the rubric `when-to-evolve-methodology`. By MAINTAINERS, a file rename in `framework-template/` is **major**. Because the whole 3.x line is still pre-release (3.0.0 never shipped), the rename is absorbed into the 3.1.0 line, with the breaking change documented here (the final numbering is decided at release). Tests: harness 26/26 + smoke 17/17. **Also (feature):** `deliver` now runs `/afm:evolve` at the end of a **large** delivery under `AUTONOMY=high` (gated doc hygiene).
+
+### Added
+
+- **`deliver` runs `/afm:evolve` at the end of a large delivery under `AUTONOMY=high`** (new step **4.D** + a row in the stop table + `core/afm.md § 2.2` step 6). When the delivery hits the feature-folder heuristic (**large**) **AND** the user said "go" (skipped the Phase 2 review gate), `deliver` **starts** the local doc hygiene cycle. Rationale: under "go" the human reviewed **less inline** → a **gated** pass catches the drift/inflation that a large delivery accumulates. `evolve` **keeps its own gate** (it does not auto-apply — #6). The large-delivery-under-"go" condition is the **signal** that unlocks the `evolve` cooldown. Under `AUTONOMY=normal` it stays only a **suggestion**. This is the only line in the `deliver` suppression contract where the composed op's gate is **NOT** suppressed — that is the whole point (hygiene reviewed by the human).
+
+### Changed (BREAKING)
+
+- **Skill renamed: `/afm:kenpachi` → `/afm:evolve`.** Anyone invoking `/afm:kenpachi` now uses `/afm:evolve`. **Natural-language activation is unchanged** (lives in `when_to_use`: "audit the methodology", "the docs are a mess", etc.).
+- **Files moved:** `framework-template/ops/kenpachi.md` → `ops/evolve.md`; `skills/kenpachi/SKILL.md` → `skills/evolve/SKILL.md` (dir `skills/kenpachi/` → `skills/evolve/`).
+- **Override marker renamed:** `<!-- kenpachi: marker-age-days=… inflation-lines=… cooldown-days=… -->` → `<!-- evolve: … -->` in `docs/.afm-version` (read by `diagnose`/`afm-health.sh`).
+- **~110 cross-refs across ~28 files** updated `kenpachi`→`evolve`: ops/* (deliver/diagnose/reflect/generalize/restructure/update/promote/reconcile/remediate), every SKILL.md, README/README-light, MAINTAINERS, the rubric `when-to-evolve-methodology`, ach, bootstrap, refactor, triggers, evolution-report template, plugin.json, hooks (`afm-health.sh`/`afm-session-start.sh`), and the test fixtures. **Historical CHANGELOG entries (rc.10–rc.4) keep the period name `kenpachi`** (non-revisionist).
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.1.0-rc.5).** (1) Use **`/afm:evolve`** instead of `/afm:kenpachi` (natural language stays the same). (2) If you had the cooldown override in `docs/.afm-version`, **rename the marker** `<!-- kenpachi: … -->` → `<!-- evolve: … -->` — otherwise the parser cannot find it and falls back to defaults. `/afm:update` applies this rename. If you had no marker: nothing changes beyond the skill's new name.
+
+## [3.1.0-rc.4] — 2026-06-16
+
+> **Phase 4 of the v3.2 initiative (essential Tier 2) — promotion gating + self-reflection on failures.** Closes the highest-value, lowest-risk Tier 2 items. **Negative filters** (what NOT to promote — a false constraint is poison), **cardinality fan-out** (a redefinition covers all pages), and **`kenpachi` composes `remediate` over recurring failures** — the "self-reflection that resolves the error for good" (procedure/learning). **Deferred to rc.5 (focused):** the `docs/index.md` catalog + diagnose axis A8 (high churn in the "7 axes" refs) and **usage-based decay** (`access_count`) — this last one depends on an open design decision about the access-tracking mechanism (frontmatter vs `.afm-access.jsonl`), and without it the metric is inert.
+
+### Added
+
+- **Rubric `rubrics/negative-filters.md`** — a **rejection** checklist at the `gotcha`/`reconcile`/`remediate` gate: a negative tool claim (a fossil refusal), a transient failure (a dead constraint), a one-off narrative, user-visible status, a vibe rule with no trigger. 4 promotion tests (durable antidote? survives the cause's fix? #1? >=2x/user/SDK?). Referenced in `ach.md § 6`. Field evidence (ai-memory: ~28% of pages are low-signal).
+- **Principle `afm.md § 1.3` — ingest is cardinality fan-out** (Karpathy LLM-wiki): redefining a term that lives across several docs touches **all** of them (`grep -rl`), not just the obvious one. Orthogonal to rule 17 (granularity=delta vs cardinality=fan-out). A principle, not a hard rule (no clean 0/1 trigger for "this is a redefinition" — #3).
+- **Principle `afm.md § 1.3` — promotion goes through the negative filter** (the negative face of #5).
+
+### Changed
+
+- **`kenpachi` Phase 1 composes `remediate` over recurring failures** (`sig=` >=2x in `docs/.afm-log-failures/`): `diagnose`/rule 19 **flag** the orphan failure, and the cycle **resolves it for good** (procedure/learning) in a single gate. This is the requested self-reflection on failures. The `kenpachi` suppression table gains the `remediate.md` row. (Note: `reflect` remains docs-to-docs — an instructiveness refinement; a task failure belongs to `remediate`, not to `reflect`.)
+- **`ops/reconcile.md` gains step 2.5 (negative filter at the entry gate)** + the cardinality-fan-out discipline before promotion.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` -> 3.1.0-rc.4).** `/afm:update` materializes: the 2 new principles in `afm.md § 1.3` (fan-out + negative-filter) and the references to the `negative-filters`/`episodic-vs-semantic-boundary` rubrics in `ach.md § 6`. The rubrics live in the plugin (consulted through the skill); nothing new is hand-created in `/docs`. No hook change -> harness unchanged (**26 ok**).
+
+## [3.1.0-rc.3] — 2026-06-16
+
+> **Phase 3 of the v3.2 initiative — cross-session continuity.** On top of the substrate (rc.1) and the CRITIC loop (rc.2), this closes the 3rd gap of half-memory: AFM now **honors work state between sessions/agents** without promoting it to a normative doc. At the end of a session with work, it writes an **episodic handoff**; on the next one, it injects "where we stopped" + the **current focus**. **Main risk addressed:** the exception to rule 17 for the `_focus.md`/`sessions/` slots is a **closed path** (not a loosened threshold), preserving anti-context-collapse in the normative docs. **Hard rule 20 + 4th `Stop` hook + 2 episodic families, consumer-facing.**
+
+### Added
+
+- **Hook `afm-session-end.sh` (`Stop`, fallback `SessionEnd`) — cross-session handoff.** In a session with work (`git diff` not empty), it synthesizes `docs/sessions/<ts>-<sid>.md` (`state: open`, `tier: episodic`): `files_touched` via git, `summary` via this session's `s=<sid>` events in the substrate. Rule-based, 0-LLM, dedup per session; a session with no work is a no-op (negative-filter).
+- **Episodic family `docs/sessions/`** (handoffs) + `templates/session-handoff.template.md`.
+- **`docs/_focus.md`** (slot-state, mutable current focus) + `templates/focus.template.md`. Read in `afm.md § 2 READ` and injected at SessionStart.
+- **Hard rule 20 — `_focus.md` is small, overwritable slot-state** (OVERWRITE, does not grow by append). *Verification:* `wc -l docs/_focus.md > 40 → BLOATED` empty.
+- **Rubric `rubrics/episodic-vs-semantic-boundary.md`** — what decays (episodic: `sessions/`, `_focus.md`) vs what is permanent (semantic). Referenced in `ach.md § 6`. CoALA ancestor.
+
+### Changed
+
+- **Hard rule 17 (ACE) extends the path exclusion to `docs/_focus.md` and `docs/sessions/`** (slots that overwrite by design). **Closed-path exclusion, NOT a loosened threshold** — never through a flag a normative doc could set (otherwise it reopens context-collapse). This is the mitigation for the plan's main risk.
+- **`hooks/afm-session-start.sh` injects the cwd's `state: open` handoff + `docs/_focus.md`** into `additionalContext` (continuity at open).
+- **`hooks/hooks.json` gains the `Stop` event** → `afm-session-end.sh` (4th hook).
+- **`ops/reconcile.md` gains the 4th destination `docs/_focus.md` (OVERWRITE) + consumes the handoff** (`state: open` → `consumed`). Handoff/`_focus` sit **below** the promotion-to-doc gate (#1).
+- **`afm.md § 2 READ`** now reads `docs/_focus.md`. `MAINTAINERS.md § Hooks` documents the 4th hook. Harness `run.sh` +4 asserts → **26 ok, 0 fail**.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.1.0-rc.3).** `/afm:update` materializes: **hard rule 20**, the extended exclusion of rule 17, the `_focus.md` bullet in `§ 2 READ`, and the reference to the `episodic-vs-semantic-boundary` rubric in `ach.md § 6`. The `docs/sessions/` and `docs/_focus.md` families are born on-demand (on the 1st `Stop` with work / 1st focus update) — nothing to materialize by hand. Both committed (continuity through git).
+
+## [3.1.0-rc.2] — 2026-06-16
+
+> **Phase 2 of the v3.2 initiative — CRITIC loop recognize-failure→remediate.** On top of the rc.1 substrate, this closes the 2nd gap of half-memory: the agent now **recognizes failure by EXTERNAL SIGNAL** (CRITIC — never self-judgment), **records it** durably, and **remediates it for good** — **procedure** (mechanical) or **learning** (conceptual, that instructs other Claude sessions by path-match). Gated by #5: 1 user correction OR a recurring `sig=` ≥2x promotes; a single/transient failure stays only evidence. **22nd skill `remediate` + 2 new families (`procedures/`, `learnings/`) + hard rule 19 (consumer-facing).** The deep scan of `.afm-log-failures/` by `reflect`/`kenpachi` (cross-session self-reflection) arrives in Phase 4.
+
+### Added
+
+- **Skill `remediate` (`/afm:remediate`) + `ops/remediate.md` — CRITIC loop (22nd skill).** Reads `status: open` failures in `docs/.afm-log-failures/`, classifies them via the rubric, and **proposes** (a delta, citing `sig=`) the durable artifact: **procedure** (mechanical) or **learning** (conceptual). It complements — it does not duplicate — the short in-task loop of `§ 5.1` (it is the **long loop**, cross-session). Composed of `reconcile` (passive) and `kenpachi` through the suppression contract.
+- **Family `docs/procedures/`** (repeatable runbooks: release/deploy/migration) + `templates/procedure.template.md` — steps with `Verification: 0/1`, a precondition (references `§ 6.1`, does not duplicate it), rollback, `Origin: sig=`.
+- **Family `docs/learnings/`** (MD that instructs other Claude sessions) + `templates/learning.template.md`. **Injected by path-match** through `afm-pre-edit.sh` via the `**Trigger:**` field (the same mechanism as gotchas) → the next Claude session that touches the area gets the lesson.
+- **Rubric `rubrics/failure-classification.md`** — mechanical→procedure | conceptual→learning | transient→nothing; an **executable** discriminator; referenced in `ach.md § 6`.
+- **Hard rule 19 — a recurring anchored failure becomes a remediation** (`afm.md § 3`). Every `sig=` that appears ≥2x in `.afm-log-failures/` has an artifact that cites it. **Explicit anti-Goodhart caveat** (STOP, arXiv:2310.02304): the trigger measures **traceability**, not the quality of the remedy (human gate) — it guarantees that no recurring failure stays orphaned. *Verification:* grep of duplicated `sig=` values with no remediation → empty.
+
+### Changed
+
+- **`afm.md § 5.1` (reflect-retry terminal) records `kind=failure` BEFORE it halts** — `docs/.afm-log-failures/YYYY-MM-DD-<slug>.md` (`status: open`, external signal + command + output, a stable `sig=`). A failure resolved on retry is **transient** (it is not recorded — negative filter); an explicit user correction is also recorded (the user is the oracle). Recognition by **tool** (CRITIC, #3), never self-judgment.
+- **`ops/reconcile.md` step 2 routes an `open` failure to the CRITIC loop** (`remediate.md`) — gated, proposes-does-not-apply (#6).
+- **`hooks/afm-pre-edit.sh` injects `docs/learnings/` by path-match** (mirrors the gotchas block). Harness `hooks/test/run.sh` +1 assert (learning injection) → **22 ok, 0 fail**.
+- **`interview/triggers.md`** gains 3 signals: a failure crossed the §5.1 terminal, a `sig=` recurred ≥2x, a repeatable operational sequence ≥2x → procedure.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.1.0-rc.2).** `/afm:update` materializes: **hard rule 19**, the extension of `afm.md § 5.1` (failure record on the terminal), and the reference to the `failure-classification` rubric in `ach.md § 6`. The `docs/procedures/`/`docs/learnings/` families and the `docs/.afm-log-failures/` dir are **born on-demand** (on the 1st use of `remediate`/the §5.1 terminal) — nothing to materialize by hand. `docs/learnings/` is **committed** (it instructs future sessions through injection). The `remediate` skill is install-side (it does not materialize into `/docs`).
+
+## [3.1.0-rc.1] — 2026-06-16
+
+> **This opens the 3.1.0 line (initiative codename: "v3.2") — auditable memory/continuity.** First phase of a multi-phase initiative (capture substrate → recognize-failure→remediate CRITIC loop → cross-session continuity) that closes the AFM's three **half-memory** gaps: volatile learning signal (`reconcile` only observed session memory, which dies at compaction/crash), no failure recognition/remediation, and no continuity between sessions/agents. This rc delivers **Phase 1 — auditable capture substrate**, the base that unlocks the rest. Research dossier and ROI prioritization: `relatorio-afm-3.2.md` + `plano-afm-3.2.md`. Opens the rc cycle for 3.1.0 (one rc per phase, as with 3.0.0-rc.1..13). **Adds universal hard rule 18 (consumer-facing → bumps `CONSUMER_VERSION`).**
+
+### Added
+
+- **Hook `afm-capture.sh` (`PostToolUse` Edit|Write) — auditable capture substrate.** It records **one line per completed edit of a normative doc** in an append-only ledger `docs/.afm-log/events/YYYY-MM.md` — format `- [ISO-8601 UTC] <kind> | s=<sid6> | <título>`, `kind` inferred **mechanically from the path** (closed vocabulary). It is the "funnel entry": `reconcile` now **reads** this ledger instead of relying on session memory. **0-LLM, fire-and-forget, always exit 0**, writes stay inside the dotdir; product code and the substrate/`_focus`/`sessions` themselves do **not** become an event (anti-transcript, #6 — capture ≠ promotion). Idempotent bootstrap of `docs/.afm-log/HEAD` (the `reconcile` cursor, epoch 0).
+- **Hard rule 18 — the substrate is append-only** (`core/afm.md § 3`). Events are never rewritten or deleted; audit = `git log -p`; `HEAD` is the only exception (1-line overwrite). *Verification:* `git log -p -- docs/.afm-log/events/ | grep -c '^-- \['` → `0`. **§ 3 reserves 18–29 for universal template rules** (the consumer project-rule placeholder moves from "starting at 18" to "starting at 30").
+
+### Changed
+
+- **`ops/reconcile.md` step 1 reads the substrate delta since the `HEAD` cursor** (safety net against a volatile signal), **adding** it to what it observed in-context; it writes `HEAD` at the end of the turn (a 1-line overwrite, exempt from rule 17 by path). Steps 2–4 (propose-don't-apply / delta-not-rewrite / never-auto-apply) are unchanged.
+- **Hard rule 17 (ACE anti-context-collapse) gains a path exclusion for the `docs/.afm-log*` dotdir** — an append-only slot, **not** a relaxation of the threshold (the 1-line `HEAD` overwrite is already below the 20-line floor). Rule 21 (Phase 3) will extend the exclusion to `docs/_focus.md`/`docs/sessions/`.
+- **`hooks/hooks.json` gains `PostToolUse` Edit|Write → `afm-capture.sh`** (3rd hook). `MAINTAINERS.md § Hooks` documents the hook + the ledger's **parseable format contract** (a change in the script changes `reconcile.md` step 1 AND the fixture too). The `hooks/test/run.sh` harness covers capture (**+6 asserts**: append per kind, kind from path, product code does not get captured, the substrate does not capture itself, no-op outside AFM, `HEAD` bootstrap) — **21 ok, 0 fail**.
+
+### Consumer migration
+
+- **Consumer-facing (bumps `CONSUMER_VERSION` → 3.1.0-rc.1).** `/afm:update` materializes **hard rule 18** in the consumer's `afm.md § 3`, plus the path exclusion for rule 17, plus the renumbered project-rule placeholder ("starting at 30"). **Note for anyone who already added project rules at 18/19:** renumber **your** rules to 30+ (never-renumber protects the universal/canonical numbers; renumbering your own project rules on a version bump is an expected migration step).
+- **The `docs/.afm-log/` substrate comes up on its own at runtime** (the first doc edit with `PostToolUse` active) — nothing to materialize by hand. **Decision: the substrate IS COMMITTED** (git audit — `git blame`/`git log -p` — is the "auditable" goal; it accepts a dirty working-tree state per edit). Anyone pinned to `docs/.afm-version` upgrades via `/afm:update`.
+
+## [3.0.0-rc.13] — 2026-06-14
+
+> **Closes 4 functional issues logged by a beta round of self-evolution** (`sdk.mapree.dev/docs/evolution/002` — the loop found the gaps during the rc.5→rc.11 update). PF-1 (HIGH) is a new capability (new skill); PF-2 (MEDIUM)/PF-3/PF-4 (LOW) are refinements to existing surfaces. **No new principle, no renumber → zero migration of `#N` refs.**
+
+### Added
+
+- **21st skill `update` — plugin→instance sync (`ops/update.md` + `skills/update/SKILL.md`).** Resolves the **A3 version drift**: it reads the consumer-facing deltas from `CHANGELOG.md` between the version pinned in `docs/.afm-version` and the current `VERSION`, materializes only what is missing (discover-first by grep; skips a consumer-noop release), and bumps `.afm-version` at the end. **This was the missing path** for an already bootstrapped instance to move to a new version — `refactor` **refuses** a project with `.afm-version` (PF-1: the CHANGELOGs said "re-run `/afm:refactor`", the skill that denies that audience). It only **reads** the plugin; it writes only to the instance (#7). It runs à-la-carte (own gate) or under `kenpachi` (gate suppressed).
+- **`framework-template/CONSUMER_VERSION` — watermark for materializable content** (PF-3). Marks the last version with a consumer-facing delta; consumer-noop releases do not bump it. The A3 vital sign compares against it, not against `VERSION`.
+
+### Changed
+
+- **`kenpachi` composes `update` on the A3 axis (was Phase 2.2 own-procedure).** The drift migration, which used to "live" in the orchestrator, became the op `update`; `kenpachi` now **reads and follows** it through the suppression contract (mirrors the rc.7 split of the mechanisms — DRY). The suppression table gains the `update.md` row; Phase 1.3 composes `update` when `diagnose` flags A3.
+- **Upgrade instructions corrected (PF-1).** The 5 "Consumer migration" blocks (rc.5–rc.9) that said "re-run `/afm:refactor`" now point to `/afm:update`; the `refactor` pre-check gains a redirect ("want to move to a new version? → `/afm:update`"); the `CLAUDE.md` disambiguation table + README/README-light/plugin.json are updated (20→21 skills).
+- **`promote.md § 1.5` gains Track B (plugin meta-fix) (PF-2).** The anti-rot gate assumed "promotion = a learning from code that ran green" (a clean consumer working tree). A fix to the **plugin itself** found by `reflect`/`diagnose` (a cross-ref typo proved by `grep`) does not fit — its validation is the **mechanical trigger of the finding** (the command that proves the defect returns 1 before / 0 after), not consumer git-clean. This is the most common case in self-evolution, and the single track used to block it behind an unrelated commit.
+- **The `afm-health.sh` A3 axis compares against the watermark + routes to an action (PF-3).** It fires only when the instance is **behind** the `CONSUMER_VERSION` (`sort -V`), not on every internal tag bump; the message now prescribes `/afm:update`.
+
+### Fixed
+
+- **`afm-pre-edit.sh` injects only under the consumer root (PF-4).** Editing another repo from a consumer session (for example, the plugin itself) no longer pulls in that consumer's irrelevant gotchas/rules — guard `case "$FILE" in "$PWD"/*)`.
+
+### Consumer migration
+
+- **None (consumer-noop).** The `update` skill + the op + `CONSUMER_VERSION` are install-side / plugin-side; nothing materializes in `/docs`. The `promote`/hooks fixes belong to the plugin. `CONSUMER_VERSION` stays at `rc.9` (rc.10–rc.13 are all consumer-noop). `.afm-version` does not need to move.
+
+## [3.0.0-rc.12] — 2026-06-14
+
+> **Framing fix (patch — "comprehension bug fix").** The self-evolution family (`kenpachi` + `diagnose`/`reflect`/`generalize`/`restructure`) **describes** its target correctly in the details (all cite `<consumer>/docs/`, have bright line #7 and the post-condition that the plugin's `git status` is empty), but the **headline framing** — "self-evolution **of the methodology**", "health **of the methodology**" — reads as *"evolve the AFM plugin"*. At activation, the model formed the wrong mental model (wanting to edit `framework-template/`) because the real target — the *instance materialized in the local docs* — stayed buried in a secondary clause. The defenses were **post-condition** (they catch the error afterward), not **priming** (they do not prevent the wrong model at entry). This rc fixes the priming. **No change to procedure/buckets/gates/principles — clarity only.** No consumer migration.
+
+### Changed
+
+- **New canonical block at the top of `ops/kenpachi.md`** (`## ⚠ O alvo da evolução: os docs locais, NUNCA o plugin`): states unambiguously that "evolve the methodology" = refine the instance materialized in `<consumer>/docs/`; the plugin (`framework-template/`) is never touched (#7), it only receives a **suggestion** through `/afm:promote`. The 4 mechanisms link this block.
+- **Target banner in the opening blockquote of the 4 mechanisms** (`diagnose`/`reflect`/`generalize`/`restructure`): one line "target = this project's local docs, never the plugin" pointing to the `kenpachi` canonical block.
+- **`description` of the 5 SKILL.md** (kenpachi/diagnose/reflect/generalize/restructure): the opening framing changed from "…of the AFM **methodology**" to "…of the project's **local documentation** (the materialized instance of the methodology in `<consumer>/docs/`) — NOT the plugin itself". This is the text that primes the model at activation.
+- **Reframe of the secondary points** that primed the wrong model: `plugin.json` description, `README-light.md`, `MAINTAINERS.md § Manter o op kenpachi` (+ banner), rubric `when-to-evolve-methodology.md` (+ banner at the top), `core/ach.md`, `interview/bootstrap.md`, `templates/evolution-report.template.md` → "self-evolution of the **local documentation** (materialized instance of the methodology)".
+
+### Consumer migration
+
+- **Nothing.** The change is only framing/priming in the plugin docs + skill descriptions. No procedure, bucket, gate, or principle changed; materialized instances do not need to rematerialize. `.afm-version` can mark `rc.12` (consumer-noop).
+
+## [3.0.0-rc.11] — 2026-06-13
+
+> **Reference fix (patch — "bug fix in a link/path").** The rc.9 in-task reflect-retry loop lives in `core/afm.md` under the literal heading **`### 5.1`** (a sub-step of "5. GREEN"), but **every** operational reference cited it as `§ 2.5.1` — a number that does not exist in the file. An agent that fails a task under `deliver` and greps `2.5.1` in `core/afm.md` finds nothing. Drift across 12 refs in a load-bearing feature (the Reflexion/Autogenesis integration). Found by the `/afm:reflect` self-reflection itself (sdk.mapree.dev instance) during the rc.5→rc.10 update. No behavior change, no consumer migration (the materialized section in the instances is already `§ 5.1`).
+
+### Fixed
+
+- **`§ 2.5.1` → `§ 5.1` in all refs** (`ops/deliver.md` ×6 — Phase 3.B, the stop table, the bright line, anti-patterns; `ops/reflect.md` § 5; `PRINCIPLES.md` #6; and the 4 rc.9 entries in this CHANGELOG). They now match the real heading `core/afm.md § 5.1`.
+
+### Consumer migration
+
+- **Nothing.** Internal plugin refs; the instances already materialized the section as `§ 5.1`. `.afm-version` can mark `rc.11` (consumer-noop — no new content to materialize).
+
+## [3.0.0-rc.10] — 2026-06-13
+
+> **Closes ROI #1 of a 4-axis audit** (Axis 4: "signals exist but do not route to action"). The vital sign **A7** (`afm-health.sh`, ratio context:code — Codified-Context arXiv:2602.20478) **reported** the out-of-band number but, unlike A6 (per-file inflation, which already suggested `/afm:generalize`/`/afm:restructure`), **did not prescribe an action**. Additive, patch — refinement of an existing nudge. No hard rule, no principle, no renumber.
+
+### Changed
+
+- **A7 routes to action (`afm/hooks/afm-health.sh`).** The single `if` that covered both sides of the band in one string becomes `if/elif` per branch, each with the **correct** action: `>60%` inflated → `/afm:restructure` (partitions) or `/afm:generalize` (merges redundancy) + `do NOT prune by size (ACE)` (mirrors the A6 wording); `<5%` under-documented → `/afm:reconcile` or `/afm:refactor` (covers what is missing — `restructure` here would be **wrong**: there is nothing to re-partition when documentation is missing).
+
+### Safety
+
+- **Only #1 of the audit was applied.** #3 literal ("avoided errors" counter) **rejected** — avoidance is counterfactual/unfalsifiable/*reward-hackable*, and it contradicts the STOP guard from rc.8 (`PRINCIPLES.md` #3); the falsifiable intent already shipped (rc.9's last bite). #2 (commit-counter docs/week) rejected (a metric with no coupled action is the exact gap it claims to fight). #5 (F4.1 null-retrieval), #4 (AGENTS re-sync), #6 (online template induction) **deferred**, gated on evidence/ADR.
+
+### Consumer migration
+
+- **Nothing.** The change is only in the plugin's hook (install-side); consumers do not materialize `afm-health.sh`. Refs `#N` unchanged.
+
+## [3.0.0-rc.9] — 2026-06-13
+
+> **Closes the remaining Reflexion gap (arXiv:2303.11366)** — the 3 items in the "still improvable" section of the summary. rc.8 already had the backbone (gotcha = long-term memory; `≥2×` = mechanical "when to reflect"; `reflect` = self-reflection anchored on the trajectory). This rc applies **point 1** (there was no retry-with-reflection loop *inside* the task), **honestly defers point 2** (the tight loop already is point 1; the rest = F4.1, gated on evidence), and **reframes point 3** (usefulness counter) in a falsifiable way. Direction: **more robust** (bounded self-correction before it escalates) AND **leaner** (dead-gotcha pruning). **Additive — no new hard rule § 3 (it is a loop, not a binary gate), no new principle, no renumber** → zero `#N` ref migration.
+
+### Added
+
+- **Retry-with-reflection loop in-task — `core/afm.md § 5.1` (Reflexion 2303.11366 + Self-Refine 2303.17651 + CRITIC 2305.11738).** When GREEN fails (red test / broken `tsc`), **before it halts**: (1) it verbalizes the failure *grounded* in the real test/`tsc` output (CRITIC — self-critique with no tool degrades), (2) it retries GREEN against the same RED (TDD intact), (3) **cap of 2 retries** (Reflexion window Ω 1-3), (4) **anti-oscillation** (same failure 2x → stop and escalate, Self-Refine), (5) cap or oscillation exhausted → it halts to the human gate (the paper's "Commit"). In-task reflection = **ephemeral** short-term memory (a retry does not become a gotcha; it crosses into the doc only through the `≥2×` gate). Zero cost on the happy path.
+
+### Changed
+
+- **`ops/deliver.md` Phase 3.B — the capped reflect-retry precedes the halt.** Step 1 (GREEN points to § 5.1), step 3 (a non-`[P]` failure runs the retry before it halts), stop table (failure row + oscillation row), bright line and anti-patterns updated. `deliver` reuses § 5.1, it does not duplicate it.
+- **`ops/reflect.md` § 5 — closes the honest admission of the old § 82** ("re-execution is only observed future behavior"): **in-task** re-execution now exists (literal, immediate) for the test-of-its-own-task case. Boundary note: in-task reflection (Reflexion short-term, signal = test/`tsc`) ≠ `reflect` docs→docs (long-term, signal = a doc that misled). The two ends of Reflexion; one does not replace the other.
+- **`PRINCIPLES.md` #6 (verification corollary) — 1 clause added to bucket (a):** self-correction now extends to **bounded re-execution** when a cheap re-runnable signal exists (test/`tsc`), capped + anti-oscillation. Corollary under the existing number — **no renumber** (same as rc.8 did with CRITIC/STOP).
+- **Last-bite signal in the gotcha + pruning in `restructure` (reframe of point 3).** `gotcha.template.md`: the `Bites:` line gains `(last: YYYY-MM)` — zero new ritual (the agent already touches the line when it increments; `ops/gotcha.md` step 4 stamps the date). `ops/restructure.md § 1.1`: a gotcha with an old last-bite date (> N months, default 12) **AND** `N` stalled → pruning candidate → **tombstone** (rule 17, never a hard delete). Reuses the existing staleness machinery.
+
+### Safety
+
+- **Point 2 (tight feedback loop) NOT reopened** — the tight loop that matters IS point 1 (reflection in the same agent's context, no hook). The cross-session gap (F4.1, null-retrieval nudge in `afm-pre-edit.sh`) stays **deferred, gated on evidence** that the case really bites (rc.8 decision preserved).
+- **Point 3 did NOT become an avoidance counter** ("Avoided: N"): avoidance is counterfactual, **unfalsifiable**, and *reward-hackable* — it would contradict the STOP guard from rc.8 (`PRINCIPLES.md` #3). Pruning is by **observable incidence** (last-bite + stalled `N`), which Reflexion approximates without violating the hardening.
+- **Cap + anti-oscillation are the token guard** of § 5.1 — worst case 3x the cost of 1 attempt, only on a failing task; happy path unchanged.
+
+### Consumer migration
+
+- **Nothing mandatory.** § 5.1, corollary #6, and the `last:` field activate additively. Pre-rc.9 instances have neither § 5.1 materialized nor the date in `Bites:` — copy it from `core/` or run `/afm:update` (version sync — materializes the consumer-facing deltas automatically). `#N` refs **do not** change (no renumber). Old gotchas with no `last:` are treated as "date unknown" by `restructure` (no pruning until the next bite stamps it).
+
+## [3.0.0-rc.8] — 2026-06-13
+
+> **Applies what was still missing from the "training-free improvement" lineage** (the papers in `[references]/kenpachi`). Line 3.0.0 already embodied most of it — CRITIC/Self-Refine → executable-trigger doctrine + `analyze` gating; Reflexion/MetaReflection → gotcha + `generalize`; Self-Harness/Autogenesis → `diagnose`/`kenpachi`; Codified-Context → `restructure` + hooks. This rc closes the narrow gap that remained, where the **"leaner AND more robust"** gain lives: **ACE** (anti-context-collapse, #1 in the report, previously ~0% applied), **Voyager/AWM** (retrieval-before-generate + induced templates + offline↔online precedence), and explicit hardening of **CRITIC/STOP** (self-critique with no tool degrades; a non-gameable trigger). **Additive rc iteration — no new principle, no renumber** (materialization composes #1/#3/#5/#6/#8) → zero `#N` ref migration in consumers.
+
+### Added
+
+- **Hard rule 17 (universal) — anti-context-collapse (ACE, arXiv:2510.04618).** `core/afm.md § 3`: a rewrite of a `/docs/` doc that deletes >50% of the lines in one edit (floor 20 lines) **stops and needs review**. Trigger `git diff --numstat -- docs/ | awk '$2>20 && $2/($1+$2+1)>0.5'`. Delete-only → `generalize` consolidation (tombstone = *adds* lines) does **not** fire. The non-mechanizable half becomes a principle in § 1.3 ("a doc evolves by delta, not monolithic rewrite"; failure modes *context collapse* + *brevity bias*).
+- **`rubrics/template-vs-streaming-precedence.md` (9th rubric) — AWM non-additivity (arXiv:2409.07429).** A frozen template (offline, `export-template`) and streaming learning (online, `reconcile`) are **non-additive — combining them hurts**. Rule: **precedence + tombstone, never sum**. Recorded in `ach.md § 6`.
+- **`templates/feature-tasks.induced.template.md` — induced tasks template (AWM/Voyager).** A parametrized variant (`{product-name}`/`{domain}`/`{entity}`/`{boundary-procedure}`); `export-template` induces it from the most recent 100% `[X]` feature (gate `L_eval=1`) and writes it into the frozen template so the next consumer **composes** instead of regenerating.
+- **`Mordidas:` field in `gotcha.template.md`** — an itemized counter à la ACE (helpful/harmful bullets), fed by the "≥2×" that `ops/gotcha.md` already collects; ≥2 in the same area routes to `generalize`.
+
+### Changed
+
+- **`ops/reconcile.md` — explicit delta policy (ACE).** New step: every proposal is a structured append OR an in-place update of a named item, never a rewrite (>50% violates rule 17); an anti-inflation nudge, signal-gated (grep ≥2 similar gotchas → suggests `/afm:generalize`); a template↔streaming precedence clause for a template-origin project.
+- **`ops/deliver.md` + `ops/specify.md` — retrieval-before-generate (Voyager/AWM).** New `deliver` Phase 0.A0 (grep similar features/ADRs/gotchas before synthesizing → composes, does not regenerate) + `specify` step 2.5; reuses the `retrieval-before-create` discipline from `kenpachi.md § Disciplina` (bidirectional link, zero duplication).
+- **`ops/promote.md` + `ops/export-template.md` — anti-rot gate (Voyager/AWM).** Promotes/freezes only work that is green and committed (`git diff --quiet` + `test -e`); export suggests `/afm:generalize` pre-freeze (consolidates streaming into the template). The export green-check is doubled onto the existing destructive confirmation (not a second prompt).
+- **`PRINCIPLES.md` #3 — CRITIC + STOP corollaries.** Self-critique with no external tool degrades (the *why* of the executable trigger; #6's self-verification only holds anchored to a command) + an anti-Goodhart guard (a non-gameable trigger). A corollary under the existing number — **no renumber** (not a reframe).
+- **`ops/rule.md` — anti-Goodhart guard (STOP, arXiv:2310.02304):** "does a diff exist that passes the trigger but violates the spirit?" → rewrite it or demote it to § 1.3.
+- **`ops/analyze.md` (gating) + `ops/deliver.md` Phase 1.D — anti-oscillation history (Self-Refine, arXiv:2303.17651):** each auto-fix round carries `finding → fix`; a finding that reappears after "fixed" = oscillation → escalates to the (b) bucket, does not re-auto-fix.
+- **`hooks/afm-health.sh` — A6 two tiers + new A7.** A6: 800 (inflated) / 500 (norm Configuring → consolidation, never pruning by size — ACE). A7: context:code ratio (~24% calibration, `git ls-files`, band 5–60%; **sum via `awk`, robust to `xargs` batching** — `tail -1` would undercount in a large monorepo where the args overflow ARG_MAX, inflating the PCT). Recorded in `MAINTAINERS.md § Hooks` (+ fixes the `v3.1.0`→`rc.6` forward-ref in afm-health).
+- **Containerized test harness** (`afm/hooks/test/container/`): runs the 3 hooks against synthetic consumers in an Alpine **GNU + busybox** setup (macOS-BSD portability/proxy) with **shellcheck** (missing on the local machine) — catches shell bugs and **token bloat** (measures the injection size: § 3 at 16KB → 5KB injected, the cap works; pre-edit ≤5 gotchas out of 300). 20 green checks across both toolsets. This is what caught the A7 bug above.
+- **`when-to-evolve-methodology.md`** — note "size is a signal of consolidation, never of pruning" (resolves the ACE × Configuring tension).
+- **`README.md`** — `AGENTS.md` block (a tool-agnostic facade, Configuring arXiv:2602.14690 — only points, never duplicates a rule; creates it if absent) in the "How to use in a NEW project" § + a pointer in `bootstrap.md`/`refactor.md`. Structure tree realigned (pre-existing drift: 9 rubrics, 10 templates, evolution ops, 17 rules).
+- **`CHANGELOG.md`** — pre-3.0.0 entries collapsed into milestones (grow-and-refine applied to the framework itself; full history in git).
+
+### Safety
+
+- **Rule 17 is delete-only** — does not conflict with `generalize`'s tombstone (which adds lines). Verified.
+- **Offline↔online precedence is precedence + tombstone, never merge** (AWM measured: combining lands *between* the two and matches neither). Preserves the "never delete, tombstone" invariant.
+- **Anti-rot gate and nudges are a materialization of #5/#6** — no new principle, no renumber.
+- **F4.1 (null-retrieval → nudge in `afm-pre-edit.sh`) DEFERRED** — noise risk > gain; not included (explicit decision).
+- **`README-light.md` kept** — audited and it is **not** a stale subset (a deliberate quickstart, in sync); removing it would lose value (#5).
+
+### Consumer migration
+
+- **Nothing required.** Rule 17 + the precedence rubric + the induced template + A7/A6-soft activate additively. Pre-rc.8 instances have neither rule 17 nor the 9th rubric materialized — copy them from `core/` or run `/afm:update` (version sync). `#N` refs **do not** change (no renumber).
+
+## [3.0.0-rc.7] — 2026-06-13
+
+> **Splits the monolithic `kenpachi` into an orchestrator + 4 mechanism skills.** The rc.6 delivered the third loop (methodology→methodology) as **one** skill that did everything. But self-evolution and self-reflection are **distinct mechanisms** — and AFM skills should be the *mechanisms*, not just the goal. Each of the 4 reference papers describes a mechanism that the monolithic kenpachi only partly materialized: mechanical weakness-mining (Self-Harness), behavioral self-reflection (MetaReflection + Autogenesis *Reflect*), semantic consolidation (MetaReflection *MetaReflect*), and context-architecture health (Codified-Context). The rc.7 decomposes: `kenpachi` becomes **conductor-not-executor** (mirrors `deliver`) and **composes** the mechanisms through a suppression contract; each mechanism also runs à-la-carte. **BREAKING inside the rc (layout): moves procedure inside `framework-template/`** (kenpachi Phase 0/1 → `diagnose.md`) + changes the `kenpachi.md` op contract (executor→orchestrator). **No new principle, no renumber** (composed materialization of #1/#2/#3/#6/#8) — zero `#N` ref migration in consumers.
+
+### Added
+
+- **`ops/reflect.md` + `skills/reflect/SKILL.md` — behavioral self-reflection (docs→docs).** Reflects on where the docs **underperformed as a harness** in the session (an ambiguous rule applied wrong, a doc that misled, a section that gave no guidance, a lived contradiction, a user correcting against the doc) and proposes **making the doc more assertive/clear** (refines the instructivity of what exists — it does not add knowledge) plus suggestions for the human. Evidence = the session trajectory (φ_b = `(sintoma-vivido, status-causal-do-doc, mecanismo)`), not a static scan. **Mandatory self-critique "a violated rule is not a wrong rule"** (rival hypothesis "it was me, not the doc") before proposing. Ancestors: MetaReflection (self-reflection = episodic memory; distill into one assertive instruction) + Autogenesis *Reflect*. **Hybrid** activation: an in-session behavioral accumulator (`triggers.md`) suggests `/afm:reflect` when a threshold is crossed (>=2 events) + a static proxy in `afm-health.sh` (§3 with content but no `*Verification:*` = "no ShowsImprovement").
+- **`ops/diagnose.md` + `skills/diagnose/SKILL.md` — mechanical read-only weakness-mining.** Extracts Phase 0 (scan of the 7 axes A1-A7) + Phase 1 (φ, addressability, severity, ANALYZER role) from the monolithic kenpachi into its own skill. Returns an **evidence bundle** ordered by severity — **zero edit proposals, no gate, no cooldown** (read-only and cheap). Ancestor: Self-Harness *Weakness Mining*. À-la-carte = health report; under `kenpachi` it feeds the cycle.
+- **`ops/generalize.md` + `skills/generalize/SKILL.md` — semantic consolidation of gotchas.** Merges a **batch of >=2 similar gotchas** (AFM's "bit twice" = the paper's batch) into one **abstract, non-case-specific rule** (episodic `gotchas.md` → semantic `afm.md`). **ShowsImprovement** validation: a merged rule becomes a hard rule in §3 only if it has an executable 0/1 trigger (else §1.3 principle — #3); **backtracking** if the abstraction does not cover the cases. Merged gotchas become a **tombstone** (provenance preserved, never deleted). Ancestor: MetaReflection *MetaReflect*. Anti-inflation at the root — where `diagnose` (A6) only detects.
+- **`ops/restructure.md` + `skills/restructure/SKILL.md` — context-architecture health.** (1) **staleness** (git trigger: a cited path has a later commit than the doc — the paper's only confirmed failure mode); (2) **findability** (info that exists but sits in the wrong place → relocate; missing info routes to `reconcile`); (3) **temperature partition** (hot-always vs on-demand, **opt-in** ADR proposal — YAGNI for small docs). Ancestor: Codified-Context.
+- **`ops/kenpachi.md` rewritten as ORCHESTRATOR** (modeled on `deliver.md`): keeps only the conductor's 3 pieces — (1) evidence-collection driver (composes `diagnose` + `reflect`; `generalize`/`restructure` on demand), (2) partition into buckets + a single gate, (3) apply + postconditions + record/lineage. **`§ Disciplina de proposta (compartilhada)`** (retrieval-before-create, minimal change, 4-field audit record, inventory-to-preserve, attempt memory + flip-flop, dry-run before the gate, partition into 3 buckets) becomes a **single canonical section** the mechanisms link to (not duplicate — auditable DRY). **Suppression contract** expanded with rows for `diagnose`/`reflect`/`generalize`/`restructure`.
+
+### Changed
+
+- **`rubrics/when-to-evolve-methodology.md` → 3-way decision:** cycle (`kenpachi`, multi-modality sweep with a consolidated gate) vs **single mechanism** (`diagnose`/`reflect`/`generalize`/`restructure` à-la-carte, scoped) vs point fix (`reconcile`→`gotcha`/`rule`/`adr`, additive-local). Decreasing cost; scope decides the path.
+- **`interview/triggers.md`** — new row for the `reflect` behavioral accumulator (a doc guided wrong, single-doc; >=2 events/session); the "lived contradiction" row narrowed to **cross-doc** (single-doc routes to reflect); a `generalize` row (>=2 similar gotchas) and a `restructure` row (staleness / misplaced info, with a note "missing info → gotcha").
+- **`hooks/afm-health.sh`** — emits a `reflect` nudge when `afm.md § 3` has content but **no** `*Verification:*` at all (secondary static proxy; reflect's strong trigger is behavioral). Smoke test `hooks/test/run.sh` stays 15/15; shellcheck `--severity=warning` clean.
+- **kenpachi `whitelist`** — the protected surface generalized from "the kenpachi rubric + triggers" to "the evolution rubric + the `triggers.md` entries that fire **any** evolution mechanism skill" (anti-self-reference).
+
+### Safety
+
+- **Shared discipline, DRY (auditable):** the `retrieval-before-create`/`dry-run` anchors live **only** in `ops/kenpachi.md § Disciplina de proposta (compartilhada)`; the mechanisms link and follow (never copy) — grep proves zero duplication.
+- **`reflect` cannot soften a rule that only got in the way** — the "a violated rule is not a wrong rule" guardrail (same as kenpachi's) is mandatory before any refinement, else the agent ends up rewriting its own constraints.
+- **`generalize` never deletes** — merged gotchas become a tombstone (`*(consolidado na regra N — ver ciclo NNN)*`); deletion is a bright line (#6), its own gate item.
+- **`restructure` never invents missing content** — info that does not exist becomes `reconcile`/`gotcha` or `[TBD]` (#4/#5); staleness is a signal, not a verdict (it does not rewrite on its own).
+- **Editing a hook trigger/path always follows bucket (b)** in every mechanism (narrowing one's own oversight); the postcondition `git -C <plugin-root> status --porcelain` empty is kept.
+- **`test/skills-lint.sh` suite (repo-level)** covers the 4 new SKILL.md files automatically (500-line cap; thin wrappers at ~30-40 lines pass with room to spare).
+
+### Consumer migration
+
+- **Nothing required.** Mechanism skills activate only by invocation (or a reconcile/hook suggestion); `kenpachi` stays invocable and now composes the mechanisms. Pre-rc.7 instances do not have the updated 3-way rubric or the new `triggers.md` rows — copy from `core/`/`interview/` or run `/afm:update` (version sync). `docs/evolution/` still appears on the 1st cycle. `#N` refs in consumers **do not** change (no renumber).
+
+## [3.0.0-rc.6] — 2026-06-12
+
+> **This closes the third loop: methodology→methodology (codename `kenpachi`).** The 3.0.0 line already closed code→docs (reconcile) and docs→code (hooks). This repo still needed an owner for the **health of the AFM materialized instance itself**: a rule whose trigger stopped running, dead refs, `[TBD]` markers that age, instance↔plugin drift, a broken ADR chain, inflated or contradictory docs — symptoms that neither `reconcile` (single signal→edit), nor `analyze` (cross-artifact for ONE feature), nor `promote` (consumer→plugin) covers. `kenpachi` is the self-reflection cycle that diagnoses this with **evidence external to the text** (git/FS/command), partitions the findings into buckets, and delivers **one evolution package** approved at one gate. Ancestors: Self-Harness (arXiv 2606.09498) and Autogenesis (arXiv 2604.15034) — their loop's *Commit* becomes the human gate (AFM has no held-out re-runnable set; high-risk needs a gate stronger than pass-rate, and that gate is the human). **Additive rc iteration — no new principle** (kenpachi is a composed materialization of #2/#3/#6/#8); no consumer migration.
+
+### Added
+
+- **`skills/kenpachi/SKILL.md` (16th skill) + `ops/kenpachi.md` (orchestrator op).** A 5-phase cycle: **Scan** (Class A + directed greps, evidence = command + `file:line`) → **Diagnosis** (ANALYZER role, signature φ = `(symptom, behavior-causal-status, mechanism)` + addressability filter — a finding with no editable surface becomes an observation, not a patch) → **Proposal** (IMPROVER role, retrieval-before-create, minimal change, 4-field audit record, inventory-to-preserve, attempt memory + per-surface lineage with a flip-flop flag, **validation dry-run before the gate**) → **Single gate** (`AskUserQuestion` `multiSelect` item-by-item, **never skippable — no "go" path**) → **Apply + post-conditions** (re-extracting the hooks keeps the format or reports a rollback; `git -C <plugin-root> status --porcelain` empty) → **Record** in `docs/evolution/NNN-<date>.md` + suggests `promote` if it generalizes. Resumable (state = report on disk). Reuses `analyze`/`rule`/`gotcha`/`adr`/`reconcile`/`promote` through an honest suppression contract (the logic to downgrade/archive/merge **lives in the op** — there is no canonical op for it).
+- **A 3-bucket partition (verification corollary of #6), bucket (a) NARROW:** (a) self-applicable only for **non-semantic** restorative fixes proven by git/FS (a dead path ref, a broken ADR link) — **an edit to a `*Verification:*` command in § 3, or to a path the hooks parse, is ALWAYS (b)** (these are enforcement guardrails; fixing one can narrow what it catches); (b) load-bearing → gate; (c) cosmetic → diff. The gate always runs, even for an (a)-only package.
+- **`rubrics/when-to-evolve-methodology.md` (8th rubric).** Binary decision cycle-vs-point-fix (both signals: instance problem **and** observable evidence); self-critique = the jiuwenswarm "dreaming" 3 questions ("an empty diagnosis is a valid result — do not fabricate an illness"); counterexamples ("❌ run it as ritual"). Materialized in the consumer alongside the other rubrics (bootstrap/refactor); referenced in `ach.md § 6`.
+- **`templates/evolution-report.template.md`.** Materializes `<consumer>/docs/evolution/NNN-<date>.md` (φ findings, buckets, audit records, both rejected AND approved-then-reverted, vital signs before/after, cooldown). The `docs/evolution/` directory is born on demand at the 1st cycle (like `docs/research/` in 1.2.0).
+- **`afm/hooks/afm-health.sh` — Class A vital signs at SessionStart.** Called by `afm-session-start.sh`; static/cheap checks only (`test -e`/`grep`/`wc`, **does not run § 3**); cached once a day in `$TMPDIR` (does not pollute the consumer's git); silent when the instance is healthy; anti-Goodhart doctrine inline ("age/count is not bad on its own"). This is what makes the "sensing that things are not at 100%" real — the same mechanism that made reconcile always-on real. **It informs, never decides or blocks.**
+- **2 passive triggers (Class B) in `triggers.md`:** a contradiction lived between docs (>=2x in the session) and perceived inflation at apply-time → reconcile **suggests** `/afm:kenpachi` (suggests, does not run it — only the user invokes the cycle).
+
+### Safety (designed against an adversarial 3-lens audit — fidelity to sources / fit with invariants / self-modification risk)
+
+- **No `AUTONOMY=high` path in kenpachi** — the valve that makes "go" safe in `deliver` (halt at the 1st dependent task) does not exist here (the edit to the doc *is* the effect); so the gate is inescapable.
+- **The instance/plugin boundary becomes MECHANICAL** — post-condition: the plugin-root `git status --porcelain` is empty (before, "never edit the plugin" was doctrine with no trigger — it failed its own test #3).
+- **Anti-oscillation** — per-surface lineage + a flip-flop flag; the memory covers both rejected **and** approved-then-reverted; re-proposing needs new evidence.
+- **A "rule violated" signal does not downgrade a rule on its own** — "agent non-compliant" is a mandatory rival mechanism in the φ; downgrading needs proof the rule is *wrong*, not just *violated*.
+- **`multiSelect` gate item-by-item** (not one monolithic plan-approve — the edits are independent); downgrading/removing a rule and deletion are item-by-item and inescapable; never renumbers (tombstone `*(removed — lives in §X)*`); ADRs are itemized at the gate, zero post-gate materialization.
+
+### Consumer migration
+
+- **Nothing mandatory.** `kenpachi` activates only on explicit invocation; the `afm-health.sh` hook is opt-in per install (needs `jq`, degrades to a no-op). Pre-rc.6 instances' `docs/rubrics/` do not have the 8th rubric — copy `rubrics/when-to-evolve-methodology.md` by hand, or run `/afm:update` (version sync). `docs/evolution/` is born at the 1st cycle.
+
+## [3.0.0-rc.5] — 2026-05-30
+
+> **Release candidate (iterates on rc.4).** This closes the structural gap a 5-lens audit found: the methodology kept the docs alive well (the **code→docs** loop through `reconcile`), but it barely applied the docs to the code (the **docs→code** loop) — that loop rested on one passive sentence in the consumer `CLAUDE.md`, with no mechanism. rc.5 gives this loop executable wiring (hooks), makes § 3 consistent with its own contract (a rule with no executable trigger becomes a principle), and gives the autonomy "load-bearing" pivot a structural test (a deterministic gate). **The plugin stops being pure Markdown** — it gains `afm/hooks/` (shell + smoke test).
+
+### Added
+
+- **`afm/hooks/` — closes the docs→code loop (the central fix).** `hooks/hooks.json` declares two events; the scripts' cwd is the consumer root; they degrade to a silent no-op outside an AFM project or without `jq` (they never break the session or block Edit).
+  - **`afm-session-start.sh`** (`SessionStart`): injects a digest (§ 2 situation→doc map + § 3 hard rules + reconcile doctrine) through `hookSpecificOutput.additionalContext`. **This is what makes reconcile truly "always-on"** — before this it was aspirational (a skill frontmatter has no way to be injected every session without a hook).
+  - **`afm-pre-edit.sh`** (`PreToolUse` matcher `Edit|Write`): injects the rules (§ 3) and gotchas whose path-prefix/`Gatilho` matches a segment of the edited file's path. Cached per session+file. It delivers "the right rule at the moment of writing".
+  - **`afm/hooks/test/run.sh`**: smoke test (shellcheck if present + functional asserts with fixtures). The plugin gained shell, so it gained a test.
+- **Rubrics materialized in the consumer.** The decision rubrics (`rubrics/`) were orphans — not copied to the consumer `/docs/` nor listed in the `CLAUDE.md` index. Now `bootstrap.md` (Step 7) and `refactor.md` (B.7) copy `rubrics/` → `<consumer>/docs/rubrics/`; `export-template` keeps `rubrics/` in the "keep" set; from-template copies it if missing.
+- **DSL-first — new rubric + principle + trigger.** New rubric `rubrics/when-to-create-dsl.md` (7th, in the "when-to-create-X" family): the agent **suggests** a DSL (fluent builder / combinators / declarative object / mini-language) when boilerplate over primitives scales up. **Trigger = two combined signals:** (1) 3 or more call sites repeating the same primitive *sequence* in fixed order (Rule-of-Three over a sequence), AND (2) wiring dominates intent at those sites — plus the condition that separates a DSL from a helper: a **reusable grammar** exists. This complements the Rule of Three, and is not the opposite of KISS (it picks the lightest form that captures the grammar; a parser is the last resort). **It suggests, it does not build:** proposing a DSL is an architectural change → hard rule 11 (stop and ask; bring an API sketch plus a candidate ADR). Principle in `core/afm.md § 1.3`, passive trigger in `triggers.md` (reconcile proposes it), reference in `ach.md § 6`. Materialized in the consumer alongside the other rubrics.
+
+### Changed
+
+- **§ 3 becomes consistent with its own contract (mechanize-or-demote).** The contract (`core/afm.md` § 3 + `PRINCIPLES.md` #3) now requires an **executable trigger the agent runs at the keyboard** (`grep`/`wc`/`git diff`/`tsc`); "code review"/"PR template"/"manual review" no longer count (and "binary checklist" is dropped from the list). Disposition: **rule 3** (types at boundaries) and **8** (Rule of Three) and **14** (saga ordering) are demoted to § 1.3 (they were already principles; 3 and 8 already lived there — this collapses the duplication; saga ordering gets its own dedicated bullet); **rule 13** (secrets) is mechanized with `git diff --staged | grep`; **rule 11** (architectural change) gets a **mid-flight** trigger on the working tree (`git status --porcelain`), not a "PR checklist" (`deliver` fires it before a PR even exists). Modules (`modules/*/rules.patch.md`) are restructured: "Hard rules (executable trigger)" vs. "Principles (review → § 1.3)" — rules that were only "code review" (stripe 1/3/5, prisma 3, trpc 5, trigger 2, vireya 6) become principles.
+- **Broken trigger commands fixed.** Brace-glob in `find`/`grep` paths (`*.{css,module.css}`, `*.{{ext}}`) → `--include`/`-o`; `grep "a\|b"` → `grep -E "a|b"`; PCRE lookahead `:focus(?!-visible)` under `-E` → the portable `:focus([^-]|$)`; `wc -l **/route.ts` (globstar) → `find ... | xargs wc -l`. All validated by running them in a POSIX shell.
+- **`PRINCIPLES.md` #6/#8 — a structural "load-bearing" discriminator (a deterministic gate).** The circular pivot "it breaks something if it goes wrong" becomes a mechanical test: a finding is bucket (b) (escalates to the gate) **if and only if the wrong choice changes which components/boundaries/tasks get created** (the structural inventory), not just the content. CRITICAL = it changes the inventory of the whole plan; HIGH = of one feature/task. `#6` and `#2` are rewritten as scannable sub-bullets (bright lines — push, rule-11, destructive, plugin — stop being clauses buried in a 30-line paragraph). Bright line (a), destructive, now explicitly covers a destructive operation that arrives as a task from an approved `tasks.md`.
+- **`ops/deliver.md` Phase 2 — "go" no longer lets a load-bearing guess steer things silently.** On the `AUTONOMY=high` path with a HIGH bucket (b) finding: the agent adopts the recommendation and marks `[NEEDS CLARIFICATION:]`, **but** the tasks that depend on the assumption are born marked, and the Phase 3.B driver **halts at the first one of them** (resumable) — the drift surfaces at the dependent task's boundary, not 8 tasks later. The question cap is clarified as **per feature lifetime** (resumability does not reset the counter; rounds spent are noted in the spec). A 5th stop bright line is added to the table.
+- **`ops/analyze.md` (verification engine) aligned:** bucket (b) uses the structural test; CRITICAL/HIGH locks to (b) (gate), never (c), after 3 auto-fix rounds; the severity matrix is adjusted (HIGH no longer cites "hard rule with no trigger" — it does not exist; § 1.3 includes the demoted rules).
+- **Activation disambiguation:** reciprocal carve-outs between `analyze`↔`clarify` (read-only validation vs. resolving markers), `analyze`→`deliver`, and `research` tightened (it over-captured "investigate this bug" — now it is only an external technical unknown to decide; diagnostic debugging is explicitly excluded).
+- **`deliver`'s attention cost:** a note at the top of the suppression contract — the only universal suppression is `AskUserQuestion`/diff per artifact (it escalates to the gate); do not re-read the 7 ops re-subtracting steps.
+
+### Fixed
+
+- **Principle-numbering drift after the rc.1 renumber.** `skills/reconcile/SKILL.md` cited `#5` for propose-not-apply (it is `#6`) and `#4` for do-not-invent (it is `#5`) — and it contradicted itself internally (line 53 already had the fix). `skills/research/SKILL.md` cited `#4` for do-not-invent (it is `#5`). Fixed. A sweep confirmed the other ops/interview files were already correct; `#N` refs in the CHANGELOG are historical and are not rewritten.
+
+### Consumer migration
+
+- **Hooks are opt-in through the plugin install** — an existing consumer starts receiving them on the next plugin update; no manual action needed. `jq` must be on the PATH to activate them (without `jq`, a silent no-op).
+- **`/docs/rubrics/` is not retroactive** — consumers bootstrapped before rc.5 do not have the folder; run `/afm:update` (version sync) OR copy `rubrics/` manually to `docs/rubrics/` (they are stack-agnostic, with no placeholders).
+- **Demoted rules (3/8/14):** if a consumer materialized `afm.md` before rc.5, the rules stay in § 3 there — no automatic migration (the template changed, the instance did not). Optional: move them to § 1.3 on the next reconcile pass.
+
+## [3.0.0-rc.4] — 2026-05-30
+
+> **Release candidate (iterates on rc.3).** Closes the efficiency gap of autonomy: rc.1–rc.3 gave autonomy to **production** (materializes, infers, cuts gates), but not to **verification**. Without self-verification, drift only showed up late (in `git diff` or in a test failing 8 tasks later) — and the "fewer questions" gain came back as expensive rework. rc.4 brings **some questions back, but earned**: the gate stops being ceremony and becomes the load-bearing residue of self-critique.
+
+### Changed
+
+- **`PRINCIPLES.md` #6 gains a verification corollary.** Autonomy-first is *produce → **self-verify** → report*, not *produce → report*. Before it delivers an artifact (discovery/spec/plan/tasks), the agent runs adversarial self-critique and **partitions** each finding into 3 buckets: (a) resolvable by evidence → self-corrects; (b) load-bearing + not resolvable → becomes the gate question; (c) cosmetic/deferrable → `[TBD]`/`[NEEDS CLARIFICATION:]` for reconcile. The **delivery gate = bucket (b)**, not a process question. With no (b) and no CRITICAL → there is no gate ("go").
+- **`PRINCIPLES.md` #8 gains an "earned question" corollary.** Only what survives discover-first (#2) + self-critique (#6) + load-bearing reaches `AskUserQuestion`. Every gate question carries evidence + a recommendation (`(Recomendado)`) + "what breaks if wrong". The anti-interrogation cap (≤4/call, ≤2 rounds) is holistic: discovery and verification share the same budget.
+- **`ops/analyze.md` gains two modes.** *Advisory* (default, à-la-carte — read-only in chat, unchanged) and *gating* (in-loop, called by `deliver`): same detection (steps 2-5), but it partitions into the 3 buckets, self-corrects bucket (a), and **re-runs until CRITICAL/HIGH clears** (cap 3 rounds), returns bucket (b) as earned questions; no report-in-chat. `analyze` becomes the **verification engine** of AFM.
+- **`ops/deliver.md` Phase 1.D + Phase 2 rewritten.** 1.D stops being "silent self-check (only CRITICAL escalates)" and becomes the mandatory verification that produces the partition (self-corrects (a) + loop-until-clear + (b) for the gate). Phase 2 stops being "approve the plan?" and instead **carries the earned questions from bucket (b)** (≤4, recommendation-first, evidence + "what breaks" built in) — answering IS approving. `AUTONOMY=high` with non-CRITICAL (b): adopts its own recommendation as default + records `[NEEDS CLARIFICATION:]` (documents, does not guess); CRITICAL (b) asks even with "go". Suppression table and anti-patterns updated.
+- **`core/afm.md` § 2.2** steps 2-3 reframed: synthesis gains self-verification; the single gate = residue of verification.
+
+### Notes
+
+- Iterates within the same rc (rc.1–rc.3 not pushed). Doctrine anchored as a corollary, **with no principle renumbering** (operator's choice) — zero consumer migration. Conceptual ancestor: the "adversarial verify / completeness critic" patterns from multi-agent orchestration, applied to the methodology's own artifacts (not only to code, which already had an oracle via TDD).
+
+## [3.0.0-rc.3] — 2026-05-29
+
+> **Release candidate (iterates on rc.2).** Makes the `refactor` interview embody #6 (autonomy-first) — fewer gates, fewer questions about the discoverable, same captured information.
+
+### Changed
+
+- **`interview/refactor.md` — a more autonomous interview.** It applies #6 (autonomy-first) and #2 (discover-first) to the retroactive adoption flow, without losing information:
+  - **Ceremony gates removed:** the pre-check no longer asks "start?" (invoking `/afm:refactor` already approves — it announces the plan in 1 line and continues); B.8 no longer asks "want to review?" (it materializes + reports paths, review via `git diff`); D.10 forward-only materializes the default (from-today + boy-scout) with a non-blocking note instead of an `AskUserQuestion` about granularity.
+  - **New A.7 — CI/hooks scan:** it discovers what **already gates** merge/push (`.github/workflows`, `.husky`, `.pre-commit-config`, `package.json` scripts/`lint-staged`, `Makefile`). C.9.6 (DoD/pre-push) now enters **pre-marked** with what it discovered, recommendation-first — a confirmation instead of a blank multi-select. Empty result → falls back to the current behavior.
+  - **Closing:** the remaining `[TBD]` markers are **reported** (a summary + commit note) and handed to the always-on `reconcile`, instead of the `multiSelect` gate "which to fill in now?".
+  - **Kept** (the operator's decision): the block for **product intent** (C.9.1–C.9.5 — pain/persona/summary/ADR/gotcha) stays **one per turn** with validation by rephrasing. Only the human knows this. The careful cadence stays on purpose.
+- Anti-patterns and success criteria of `refactor.md` updated: "only genuine intent consumes a turn; zero ceremony gates; nothing discoverable gets asked".
+- **`init`/`refactor` become explicit-activation-only.** The `when_to_use` of both skills loses the **auto-activation by project state** branches (detected greenfield/brownfield/from-template): now they ACTIVATE only by explicit invocation — `/afm:init`÷`/afm:refactor` or an explicit natural-language request ("build the AFM doc", "adopt AFM here"). The **pre-checks** stay intact and use state **after** invocation to redirect (`init`↔`refactor`, from-template branch) or refuse (already bootstrapped). The disambiguation table in the root `CLAUDE.md` and `README.md` was rewritten to reflect "explicit activation, state only describes when it fits". `reconcile` remains the only always-on skill.
+- **`interview/bootstrap.md` — stack inferred from evidence (#2 + #8), always with confirmation.** Step 1 gains **1.0 — Stack scan**: when a manifest exists in the repo (or the user named the stack in Step 0), it infers each layer (web/API/DB+ORM/tasks) and takes it to the `AskUserQuestion` **pre-marked as `(Recommended)`** citing the evidence — the question becomes a confirmation of a suggestion, not a blank choice. No signal → the current blank flow. Step 6 (DoD/pre-push) works the same way: it pre-marks whatever `.github/workflows`/`.husky`/scripts/`Makefile` reveal. Guiding rule #1 rewritten ("pre-filled suggestion > blank question, where a signal exists") + anti-pattern "asking for the stack blank when a manifest exists". **The user's confirmation is kept** — the stack is their decision, no ceremony gate was removed here (unlike `refactor`, which materializes directly). `bootstrap` stays conversational, since it is almost all product intent.
+
+### Notes
+
+- Refinement inside the same rc (rc.1/rc.2 were not pushed/merged). No change to principle, numbering, or consumer contract — it is `refactor` and `bootstrap` embodying the #6/#2 the doctrine already declared. It operationalizes what `PRINCIPLES.md` #2 already mandated for greenfield ("where a manifest exists, infer the stack as a recommendation BEFORE offering options").
+
+## [3.0.0-rc.2] — 2026-05-29
+
+> **Release candidate (iterates on rc.1).** Refines headline principle #2 — discovery stops being a mandatory sweep and becomes **gap-triggered**.
+
+### Changed
+
+- **#2 discover-first reframed as a gap-triggered decision procedure** (`PRINCIPLES.md`). Before, it read as "exhaust the discoverable before ANY question" (it sounded like an always-on sweep). Now: the agent works and, on hitting **missing information**, routes **in this order** — (1) code/`docs/` can answer → local discovery (`grep`/glob/`Read`/Explore); (2) the web can answer (lib/tech) → research; (3) no path resolves it OR it is product intent → `AskUserQuestion` (#8). **Discovery is conditional:** with no discoverable gap, there is no discovery — it does not scan what it already knows or research what it does not need; asking is the fallback after (1) and (2).
+- **`core/afm.md` § 2.2** step 1 and **`ops/deliver.md` Phase 0** reframed as gap-driven: it identifies the gaps first, and scans/researches only those; a trivial/already-specified feature passes almost straight through. The `deliver` convergent loop only digs deeper where a gap still exists.
+
+### Notes
+
+- Refinement within the same rc (rc.1 was not pushed/merged). Bright lines of #6, mechanical-refusal gates, and intent questions: unchanged. #8 already filtered to "only the irreducible left over from #2" — this stays consistent.
+
+## [3.0.0-rc.1] — 2026-05-28
+
+> **Release candidate.** This locks in the philosophy shift (BREAKING) and opens a test window before the final `3.0.0`.
+
+### Philosophy — autonomy-first
+
+The v2.1.0 introduced discover-first (#9) and `deliver`, but treated autonomy as "a mode of `deliver`". The 3.0.0 locks it in as **law of the whole methodology**: the agent discovers everything discoverable and goes to the human only with **product intent**. No more `"where is X"`, `"what is the current state of X"`, `"which components"`, `"which stack"` — the agent looks and answers itself.
+
+### Changed (BREAKING)
+
+- **Principles renumbered and reframed** in `PRINCIPLES.md`. Old→new map: `#2→#3, #3→#4, #4→#5, #5→#6, #6→#7, #7→#8, #8→#9, #9→#2`. Result: **8 universals (§1-8) + #9 refactor-only**.
+  - **#2 — discover-first** (was #9, mis-numbered after the refactor-only): **raised** to an early foundational principle, default law for EVERY op (not only `deliver`). Active side of #1.
+  - **#6 — autonomy-first** (reframe of the old #5 "propose the edit, do not apply"): inside an approved scope (an op invoked, or a feature approved at the `deliver` gate), the agent **materializes and reports** — writes and shows a summary + paths for review through `git diff`, with no blocking per-write `AskUserQuestion`. The invocation itself IS the consent. **Bright lines that still confirm first:** a destructive operation (`export-template` deletes files), an edit to the plugin (`promote`), a push (`§ 6.1`), an architectural surprise (rule 11). Absorbs the checkpoint corollary of `deliver`.
+  - **#9 — retroactive load-bearing ADR** (was #8): the only refactor-only entry, moved to the end.
+- **Standalone ops become autonomous by default.** Running `/afm:plan` (etc.) alone now infers everything from the scan (discover-first), materializes, and reports — with no interrogation of discoverable state and no blocking diff per edit. This affects `gotcha/adr/rule/specify/plan/tasks/clarify/research`. Feature disambiguation in `plan/tasks/clarify/research` now auto-detects (branch/recency), and asks only when 2+ candidates are ambiguous. Kept: **mechanical refusal** gates (`gotcha` 2×, `tasks` HARD-block, `rule` trigger) and **intent** questions (ADR status, rule scope, product clarify).
+- **Sweep of `#N` references** across every op, SKILL.md, `core/afm.md`, interviews, READMEs, and `CLAUDE.md` for the new numbering. `analyze.md` constitution set moves from `§1-7` to `§1-8` (fixes a drift that omitted discover-first); detection of "applied without a diff" becomes "crossed a bright line without confirming" (#6).
+
+### Removed
+
+- **The interrogative bias of the doctrine.** The default was "ask what is needed" and is now "discover what you can, ask only what is irreducible".
+- **Legacy triggers `/afm:init <op>` / `/afm:refactor <op>`** across the 11 op files + README — a residue of the pre-v2.0.0 router; each op now declares only `/afm:<op>`.
+- **`spec-kit/`** leaves the repo (`.gitignore`) — it was an external reference clone (GitHub spec-kit), with no code dependency (only cited as an ancestor in historical notes).
+
+### Notes
+
+- **This is rc.1.** Consumer migration: consumer projects' `CLAUDE.md` that cites a principle `#N` may need the map above. Bright-line behavior is preserved — autonomy is not recklessness.
+- **The `[2.1.0]`/`[2.0.0]`/earlier entries stay frozen** (they describe the numbering state of their own time); only this entry uses the new numbering.
+
+## Pre-3.0.0 — milestones (collapsed)
+
+> The detailed entries from 0.1.0 → 2.1.0 were collapsed into milestones (grow-and-refine in the framework itself — ACE: prune redundancy, not load-bearing detail). **Full history is preserved in git** (`git log -- framework-template/CHANGELOG.md` or the commits for each version). The principle numbering `#N` cited in pre-rc.1 entries reflects the numbering **of that time** (the v3.0.0-rc.1 reframe remapped `#2↔#9` — see that entry).
+
+- **[2.1.0] — 2026-05-28** — Skill `deliver` (autonomous end-to-end delivery orchestrator: discovery → 1 gate → runs to the end, resumable, DRY suppression contract). The discover-first principle introduced (then `#9`). Hard rule `nextjs-app-router` `<html lang>` on the `[lang]` segment.
+- **[2.0.0] — 2026-05-28 (BREAKING)** — refactors from "2 skills + op router" to **14 atomic skills** (`/afm:clarify`, `/afm:gotcha`, etc. invoked directly); `/afm:reconcile` always-on centralizes the continuous doctrine formerly duplicated in init/refactor; the legacy bridge `commands/afm.md` removed. Hard cut, no shim.
+- **[1.3.0] — 2026-05-09** — a third project state: greenfield with an architectural template (`docs/.template`). Op `export-template` + from-template branch in `init`.
+- **[1.2.0] — 2026-05-09** — delivery loop auxiliaries: `clarify` / `analyze` / `research` + research templates. Inspired by spec-kit (Phase 0), preserving AFM invariants.
+- **[1.1.0] — 2026-05-09** — per-feature delivery loop: `specify` / `plan` / `tasks` + `feature-{spec,plan,tasks}` templates + `core/afm.md § 2.1` (folder heuristic) + `[NEEDS CLARIFICATION:]` marker.
+- **[1.0.0–1.0.4] — 2026-05-01→03** — splits the monolithic `afm` skill into a plugin with `init`+`refactor` sharing `framework-template/`; `${CLAUDE_SKILL_DIR}` paths; ops extracted to `framework-template/ops/` (single canonical source); `MAINTAINERS.md`; SKILL.md trim.
+- **[0.1.0–0.3.0] — 2026-04-29** — genesis: initial PRINCIPLES/templates/rubrics, first interviews (bootstrap/refactor), first stack modules.