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

package/plugin/agy/skills/afm-restructure/SKILL.md

@@ -10,9 +10,9 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-This is a mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/restructure.md` prints.
+> **Procedure.** Run `afm read ops/restructure.md` and follow it; read an on-demand section when its condition holds.
 
-> **Carve-out (does not overlap existing ops):** `diagnose` A1 finds a **dead reference** (the path does not exist). `restructure` staleness finds a path that **exists but changed** while the doc did not. `reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `reflect` targets **clarity**. `restructure` targets **location and freshness**. `evolve` is the **orchestrator** that composes this skill when `diagnose` flags staleness or bloat.
+> **Carve-out (does not overlap existing ops):** `afm-diagnose` A1 finds a **dead reference** (the path does not exist). `restructure` staleness finds a path that **exists but changed** while the doc did not. `afm-reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `afm-reflect` targets **clarity**. `restructure` targets **location and freshness**. `afm-evolve` is the **orchestrator** that composes this skill when `afm-diagnose` flags staleness or bloat.
 >
 > **Maturity (honest YAGNI):** the actionable core today is **staleness** (from git) plus **findability**. **Temperature tiering** (always-hot vs on-demand) is an **opt-in** ADR proposal, only for a doc that has actually outgrown its size. Small docs do not need it.
 
@@ -20,7 +20,7 @@ This is a mechanism skill of AFM. The canonical procedure is the op file that `a
 
 This is a disambiguation guide for a skill that has already activated. It does not gate activation, so it stays in the body, not in the resident listing.
 
-A path that does not exist belongs to `afm-diagnose` (A1). Staleness means the path exists but changed. Information never documented belongs to `reconcile` → `afm-gotcha` or `afm-rule`. An ambiguous doc belongs to `afm-reflect`. Merging gotchas belongs to `afm-generalize`. The full cycle belongs to `afm-evolve`.
+A path that does not exist belongs to `afm-diagnose` (A1). Staleness means the path exists but changed. Information never documented belongs to passive mode (`afm-reconcile`) → `afm-gotcha` or `afm-rule`. An ambiguous doc belongs to `afm-reflect`. Merging gotchas belongs to `afm-generalize`. The full cycle belongs to `afm-evolve`.
 
 ## Pre-check
 
@@ -30,25 +30,23 @@ A path that does not exist belongs to `afm-diagnose` (A1). Staleness means the p
 
 ## Procedure
 
-Read the op (`afm path ops/restructure.md`) end to end. Follow it literally. Use these five steps.
+Use these five steps.
 
 1. **Staleness scan.** `afm doctor --json` runs it (findings with axis `staleness` and `dead-gotcha`); read them. The git trigger fires in two cases. First case: a path cited in the doc has a later last commit than the doc. Second case: the doc has been stale for more than N commits. A hit is a candidate, not a verdict. The scan never rewrites the doc on its own.
-2. **Findability.** Relocate or cross-reference information that exists but sits buried or in the wrong doc. Cite both locations. Route information that is genuinely missing to `reconcile`.
+2. **Findability.** Relocate or cross-reference information that exists but sits buried or in the wrong doc. Cite both locations. Route information that is genuinely missing to passive mode (`afm-reconcile`).
 3. **Temperature partition.** Propose a hot/on-demand loading strategy as an opt-in ADR. Do this only when a doc has outgrown its size. Preserve 100% of the content.
-4. **Its own gate.** This gate is load-bearing and earned, one `afm ask restructure --scope <item-slug>` per finding. It follows the **shared-proposal discipline** in `evolve.md` (`afm path ops/evolve.md`), instead of a duplicate copy of that discipline. `evolve` suppresses this gate when it runs.
-5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `promote` if the finding generalizes.
+4. **Its own gate.** This gate is load-bearing and earned, one `afm ask restructure --scope <item-slug>` per finding. It follows the **shared-proposal discipline** in `evolve.md` (`afm path ops/evolve.md`), instead of a duplicate copy of that discipline. `afm-evolve` suppresses this gate when it runs.
+5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `afm-promote` if the finding generalizes.
 
 ## Invariant principles
 
-The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universal principles §1-8 apply here. Four principles matter most for this skill.
+Most relevant here:
 
 - #2: get git evidence before you propose a change.
 - #3: staleness needs an executable git trigger.
-- #4/#5: missing product content becomes `[TBD]` or goes to `reconcile`. Never invent it.
+- #4/#5: missing product content becomes `[TBD]` or goes to passive mode (`afm-reconcile`). Never invent it.
 - #6/#8: self-check the work, then pass an earned gate.
 
 **No new principle here.** `restructure` is a composed materialization. The doctrine lives in the op file.
 
-## Version
-
-Content version: `afm version` prints it.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-rule/SKILL.md

@@ -9,9 +9,10 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/rule`. The CLI owns the number, the
-rule file, the index line and the runner skeleton, and refuses a rule with no honest trigger form. This
-skill keeps only the judgment.
+> **Procedure.** Run `afm read ops/rule.md` and follow it; read an on-demand section when its condition holds.
+
+The CLI owns the number, the rule file, the index line and the runner skeleton, and refuses a rule with no
+honest trigger form. This skill keeps only the judgment.
 
 ## When NOT to activate
 
@@ -38,9 +39,11 @@ that already exist.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Note especially #3 (a hard rule needs
+Most relevant here: #3 (a hard rule needs
 a mechanical trigger, or it is a principle instead) and #6 (autonomy-first: materialize the change and
 report it).
 
 Passive mode (`afm-reconcile`) is always on and can propose `afm-rule` when it detects the signal "the user
 corrected an approach with a reusable rule".
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-specify/SKILL.md

@@ -9,11 +9,11 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/specify.md`, end to end, and follow it literally.
+> **Procedure.** Run `afm read ops/specify.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
-A trivial change (no feature folder needed) goes straight to the `afm.md § 2` loop. A full end-to-end delivery is `deliver`, which composes this op.
+A trivial change (no feature folder needed) goes straight to the `afm.md § 2` loop. A full end-to-end delivery is `afm-deliver`, which composes this op.
 
 ## Pre-check
 
@@ -25,12 +25,10 @@ The number comes from `afm next-id feature`, never by hand. What is left to you
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #2 (discover-first: compute the heuristic and the US from the scan), #5 (never invent a success criterion) and #6 (autonomy-first).
+Most relevant here: #2 (discover-first: compute the heuristic and the US from the scan), #5 (never invent a success criterion) and #6 (autonomy-first).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only the opening of the feature.
+Passive mode (`afm-reconcile`) is always on. This skill covers only the opening of the feature.
 
-## Version
-
-`afm version`. History: `afm path CHANGELOG.md`.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-tasks/SKILL.md

@@ -1,34 +1,28 @@
 ---
 name: afm-tasks
 description: |
-  Generates `tasks.md` in TDD order, and marks the parallel tasks with `[P]`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
+  Generates the `tasks:` list of `tasks.md` in TDD order with `afm task add`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
   Activates: `afm-tasks [<feature>]`, "generate the tasks", "break the feature into tasks".
 ---
 
 # AFM — Tasks
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/tasks.md`, end to end, and follow it literally.
+> **Procedure.** Run `afm read ops/tasks.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
-There is no `plan.md` yet: run `afm-plan` first. An end-to-end delivery is `deliver`, which composes this op.
+There is no `plan.md` yet: run `afm-plan` first. An end-to-end delivery is `afm-deliver`, which composes this op.
 
 ## Pre-check
 
 Run `afm preflight` (exit 3: stop and suggest `afm-init` or `afm-refactor`). Run `afm feature status <NNN> --json`: a non-empty `blockers` is an open `[NEEDS CLARIFICATION:]` in the plan. That is a hard refusal with no override, not a question.
 
-## Procedure
+## Principles
 
-Break the plan into four phases (Setup, Foundation RED/GREEN, Boundary, Reconciliation) from the generator (`afm new feature-tasks --feature NNN-slug`). Mark `[P]` only where a task does not depend on the one before it; a GREEN never is. Give every task a `US-NNN` or `RF-NN`. Then run `afm feature lint <NNN>` and fix what it reports until it exits 0. The last task closes the `status:` keys. Autonomy-first: write and report.
-
-## Invariant principles
-
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #5 (every task traces to a US or RF) and rule 1 (TDD: no GREEN without the RED before it).
+Most relevant here: #5 (every task traces to a US or RF) and rule 1 (TDD: no green task without the red task it closes).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only the task list.
-
-## Version
+Passive mode (`afm-reconcile`) is always on. This skill covers only the task list.
 
-`afm version`. History: `afm path CHANGELOG.md`.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-update/SKILL.md

@@ -9,8 +9,9 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-This is the sync skill of `afm`. The canonical procedure is the op `afm path ops/update`. The CLI runs the
-codemod registry, proves each op and moves the pin. This skill keeps the judgment.
+> **Procedure.** Run `afm read ops/update.md` and follow it; read an on-demand section when its condition holds.
+
+The CLI runs the codemod registry, proves each op and moves the pin. This skill keeps the judgment.
 
 > **Carve-out (does not overlap existing ops):** `afm-init` and `afm-refactor` **create** the instance
 > (bootstrap). `update` brings an **existing** instance forward, the path that `afm-refactor` refuses.
@@ -44,15 +45,20 @@ the run. A pin **ahead** of the binary is an anomaly: report it, never roll it b
 4. **Language migration** (when the instance is not English): read `prd.md` § 11.1 FIRST and derive the
    excluded scope from it, and only then read a file. `[TBD]` there stops the step and asks
    `afm ask update-strings`. It never picks a language. The artifacts question is
-   `afm ask update-artifacts`.
+   `afm ask update-artifacts`. On migrate, run the rewrite as one orchestrated batch through
+   parallel subagents, where the host has them, else one file at a time, with a light model per agent (the smallest model the host offers) for the rewrite and the loss
+   check. Escalate only a flagged file to a capable model. The session model keeps the excluded scope and
+   the final gate.
 5. Post-conditions: `afm index --check` returns 0 and the plugin boundary stays clean. Report in chat what
    migrated and what stayed pending. Under `afm-evolve`, feed it to `docs/evolution/`.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Follow #2 (discover-first): the proof of
+Most relevant here: #2 (discover-first): the proof of
 need is the grep that shows what is missing. Follow #4/#5: materialize only what the plugin already provides
 ready-made, and never invent missing product content. Follow #6 (autonomy-first with a gate). Bright line
 #7 applies: only **read** the plugin, and write only to the instance.
 
 **No new principle here.** `update` is composed materialization. The doctrine lives in the op file.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-verify/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/verify`.
+> **Procedure.** Run `afm read ops/verify.md` and follow it; read an on-demand section when its condition holds.
 
 ## When not to activate
 
@@ -30,4 +30,6 @@ agent actor. Report the tier that resulted and what it means.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. #5 is load-bearing here.
+Most relevant here: #5 is load-bearing.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"name": "afm",
 	"description": "Agent Flow Methodology: autonomous discovery, a strict TDD delivery loop, and documentation that evolves from measured evidence. The CLI owns state, ids, gates and lint; the skills carry the judgment.",
-	"version": "4.0.0-alpha.7",
+	"version": "4.0.0-alpha.9",
 	"author": {
 		"name": "Mapree"
 	},

package/plugin/claude-code/agents/afm-explorer.md

@@ -1,7 +1,7 @@
 ---
 name: afm-explorer
 description: Read-only investigator. Answers one question from the code, the docs or the web, cites what it read, and changes nothing; dispatched with a brief.
-tools: mcp__plugin_afm_afm__approve, mcp__plugin_afm_afm__config, mcp__plugin_afm_afm__detect, mcp__plugin_afm_afm__doctor, mcp__plugin_afm_afm__failures_promotable, mcp__plugin_afm_afm__feature_lint, mcp__plugin_afm_afm__feature_status, mcp__plugin_afm_afm__gate, mcp__plugin_afm_afm__index, mcp__plugin_afm_afm__lang, mcp__plugin_afm_afm__next_id, mcp__plugin_afm_afm__path, mcp__plugin_afm_afm__policy, mcp__plugin_afm_afm__preflight, mcp__plugin_afm_afm__version, Read, Grep, Glob, WebFetch, WebSearch
+tools: mcp__plugin_afm_afm__approve, mcp__plugin_afm_afm__config, mcp__plugin_afm_afm__detect, mcp__plugin_afm_afm__doctor, mcp__plugin_afm_afm__failures_promotable, mcp__plugin_afm_afm__feature_lint, mcp__plugin_afm_afm__feature_status, mcp__plugin_afm_afm__gate, mcp__plugin_afm_afm__index, mcp__plugin_afm_afm__lang, mcp__plugin_afm_afm__next_id, mcp__plugin_afm_afm__path, mcp__plugin_afm_afm__policy, mcp__plugin_afm_afm__preflight, mcp__plugin_afm_afm__read, mcp__plugin_afm_afm__sessions, mcp__plugin_afm_afm__sessions_signals, mcp__plugin_afm_afm__version, Read, Grep, Glob, WebFetch, WebSearch
 maxTurns: 60
 ---
 You are an explorer. The message that dispatched you is your brief: follow it.

package/plugin/claude-code/agents/afm-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: afm-reviewer
 description: Blind auditor. Checks one piece of work it did not write against its sources and rules, and returns a verdict with evidence; dispatched with a brief.
-tools: mcp__plugin_afm_afm__approve, mcp__plugin_afm_afm__config, mcp__plugin_afm_afm__detect, mcp__plugin_afm_afm__doctor, mcp__plugin_afm_afm__failures_promotable, mcp__plugin_afm_afm__feature_lint, mcp__plugin_afm_afm__feature_status, mcp__plugin_afm_afm__gate, mcp__plugin_afm_afm__index, mcp__plugin_afm_afm__lang, mcp__plugin_afm_afm__next_id, mcp__plugin_afm_afm__path, mcp__plugin_afm_afm__policy, mcp__plugin_afm_afm__preflight, mcp__plugin_afm_afm__version, Read, Grep, Glob, WebFetch, WebSearch
+tools: mcp__plugin_afm_afm__approve, mcp__plugin_afm_afm__config, mcp__plugin_afm_afm__detect, mcp__plugin_afm_afm__doctor, mcp__plugin_afm_afm__failures_promotable, mcp__plugin_afm_afm__feature_lint, mcp__plugin_afm_afm__feature_status, mcp__plugin_afm_afm__gate, mcp__plugin_afm_afm__index, mcp__plugin_afm_afm__lang, mcp__plugin_afm_afm__next_id, mcp__plugin_afm_afm__path, mcp__plugin_afm_afm__policy, mcp__plugin_afm_afm__preflight, mcp__plugin_afm_afm__read, mcp__plugin_afm_afm__sessions, mcp__plugin_afm_afm__sessions_signals, mcp__plugin_afm_afm__version, Read, Grep, Glob, WebFetch, WebSearch
 ---
 You are a reviewer. The message that dispatched you is your brief: follow it.
 

package/plugin/claude-code/skills/adr/SKILL.md

@@ -9,8 +9,10 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/adr`. The CLI owns the number, the
-template, the frontmatter, the supersede link and the index. This skill keeps only the judgment.
+> **Procedure.** Run `afm read ops/adr.md` and follow it; read an on-demand section when its condition holds.
+
+The CLI owns the number, the template, the frontmatter, the supersede link and the index. This skill keeps
+only the judgment.
 
 ## When NOT to activate
 
@@ -37,8 +39,10 @@ project (signal: `afm.md` § 3.1 forward-only exists). A greenfield project forb
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Additional #9 (a retroactive ADR is
+Additional #9 (a retroactive ADR is
 load-bearing-only) applies ONLY in a refactored project.
 
 Passive mode (`/afm:reconcile`) is always on and can propose `/afm:adr` when it detects a "novel structural
 decision" signal. This skill covers only the active creation.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/analyze/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/analyze.md`, end to end, and follow it exactly.
+> **Procedure.** Run `afm read ops/analyze.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
@@ -21,16 +21,14 @@ Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `/afm:init
 
 ## Procedure
 
-Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`). Gating mode sorts findings into buckets instead of reporting.
+Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`); a remediation that adds a task runs `afm task add`, never a hand edit of the `tasks:` list, and a task is closed only with `afm task done`. Gating mode sorts findings into buckets instead of reporting.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply, especially #2 (detection is an autonomous scan, not a question), #5 (no finding without evidence) and #6 (analyze is read-only: it reports in chat, writes no file, and remediates only on request).
+Most relevant here: #2 (detection is an autonomous scan, not a question), #5 (no finding without evidence) and #6 (analyze is read-only: it reports in chat, writes no file, and remediates only on request).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only active auditing.
+Passive mode (`/afm:reconcile`) is always on. This skill covers only active auditing.
 
-## Version
-
-`afm version`. History: `afm path CHANGELOG.md`.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/clarify/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/clarify.md`, end to end, and follow it literally.
+> **Procedure.** Run `afm read ops/clarify.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
@@ -25,12 +25,10 @@ Judgment only: a 9-category scan of the spec, a prioritized queue (at most 5 que
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. #2 is discover-first: resolve each question yourself through the scan or the docs, then ask. #4 says `[TBD]` beats invention, and a recommendation is a rejectable hypothesis, not a guess. #6 is autonomy-first: write the integration into spec § 7 and report. #8 is recommendation-first questions.
+Most relevant here: #2 is discover-first: resolve each question yourself through the scan or the docs, then ask. #4 says `[TBD]` beats invention, and a recommendation is a rejectable hypothesis, not a guess. #6 is autonomy-first: write the integration into spec § 7 and report. #8 is recommendation-first questions.
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only the active resolution of ambiguity.
+Passive mode (`/afm:reconcile`) is always on. This skill covers only the active resolution of ambiguity.
 
-## Version
-
-`afm version`. History: `afm path CHANGELOG.md`.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/deliver/SKILL.md

@@ -7,9 +7,9 @@ description: |
 
 # AFM — Deliver (orchestrated autonomous delivery)
 
-> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
+> **Procedure.** Run `afm read ops/deliver.md` and follow it; read an on-demand section when its condition holds.
 
-The **orchestrator** of the delivery loop. One request takes "build feature X" from discovery to a delivered feature. The procedure lives in the op: read it with `afm path ops/deliver.md`, end to end, and follow it literally. It does not duplicate the sub-steps: it reads and follows `specify`, `plan`, `tasks`, `clarify`, `analyze` and `reconcile` through a suppression contract.
+The **orchestrator** of the delivery loop. One request takes "build feature X" from discovery to a delivered feature. It does not duplicate the sub-steps: it reads and follows `/afm:specify`, `/afm:plan`, `/afm:tasks`, `/afm:clarify`, `/afm:analyze` and `/afm:reconcile` through a suppression contract. External unknowns go through `/nasca:research`, or `/nasca:campaign` for a deep study; ask the operator if nasca is missing.
 
 ## When NOT to activate
 
@@ -19,26 +19,12 @@ An isolated step ("just open the spec", "just generate the tasks") is the matchi
 
 Run `afm preflight`. Exit 0 continues. Exit 3 means no `docs/.afm-version`: stop and suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield). Exit 4 or 5: report the line it printed. Do not fall back silently.
 
-## Procedure
+## Most relevant here
 
-The CLI holds the state; the skill keeps only the judgment. Drive the loop with `afm feature status <NNN> --json`, which returns the phase to resume at, the next task and the blockers.
-
-- **Discovery:** scan scoped to the feature, external unknowns through the nasca research flow (`nasca-research`, or `nasca-campaign` for a deep study; ask the operator if nasca is missing), unknowns sorted into resolved-by-scan, researchable and irreducible. One batched, recommendation-first round, capped by the protocol (`/afm:protocol`).
-- **Draft:** spec, plan and tasks, verified with `afm feature lint <NNN>` plus the judgment passes of `analyze`.
-- **Gate:** the earned questions plus the `outcome` question (`afm ask deliver`), then `afm approve <NNN>`. An explicit "go" skips the questions, never the record.
-- **Execute:** each task is one `core/afm.md` § 2 cycle, checked with `afm gate --staged`, then `afm task done <NNN> <Txxx>`. Halt on a non-`[P]` failure after the capped retry.
-- **Reconcile:** § 8.5 plus a passive sweep.
-
-If artifacts already exist, resume from the correct phase, including "tasks already exist, run from the first `[ ]`".
-
-## Invariant principles
-
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. The backbone is **#2** (discover-first: resolve unknowns by scan and research, ask only the irreducible part, never guess product or criteria) and **#6** (autonomy-first: approval at checkpoint granularity, the consolidated plan IS the proposal).
+**#2** (discover-first: resolve unknowns by scan and research, ask only the irreducible part, never guess product or criteria) and **#6** (autonomy-first: approval at checkpoint granularity, the consolidated plan IS the proposal).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. It runs in parallel with `deliver` and takes the closing turn of Phase 4.
-
-## Version
+Passive mode (`/afm:reconcile`) is always on. It runs in parallel with `/afm:deliver` and takes the closing turn of Phase 4 (`core/afm.md` § 8.5 plus a passive sweep).
 
-`afm version`. History: `afm path CHANGELOG.md`.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/diagnose/SKILL.md

@@ -8,9 +8,9 @@ description: |
 
 # AFM — Diagnose (mechanical weakness-mining, read-only)
 
-This is a mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/diagnose.md` prints.
+> **Procedure.** Run `afm read ops/diagnose.md` and follow it; read an on-demand section when its condition holds.
 
-> **Carve-out (does not overlap existing ops):** `analyze` audits **one feature**. `diagnose` audits the **whole instance** of `/docs/`. `reflect` uses **behavioral** evidence, where the agent stumbled. `diagnose` is **static**, based on filesystem and git. `evolve` is the **orchestrator**. It combines `diagnose` (mechanical evidence) with `reflect` (behavioral evidence) into one proposal and one gate. `diagnose` is **read-only**. It never proposes an edit or opens a gate.
+> **Carve-out (does not overlap existing ops):** `/afm:analyze` audits **one feature**. `diagnose` audits the **whole instance** of `/docs/`. `/afm:reflect` uses **behavioral** evidence, where the agent stumbled. `diagnose` is **static**, based on filesystem and git. `/afm:evolve` is the **orchestrator**. It combines `diagnose` (mechanical evidence) with `/afm:reflect` (behavioral evidence) into one proposal and one gate. `diagnose` is **read-only**. It never proposes an edit or opens a gate.
 
 ## When NOT to activate
 
@@ -25,8 +25,6 @@ Validation of ONE feature is `/afm:analyze`. Behavioral friction, where a doc mi
 
 ## Procedure
 
-Read the op (`afm path ops/diagnose.md`) end to end. Follow it literally.
-
 The procedure has two phases. **Phase 0 — Scan** is gap-driven. Run `afm doctor --json`: it checks A1-A6, staleness and dead gotchas mechanically, and every finding carries a command plus `file:line`. You add A7 yourself. All 7 axes are checked, every time.
 
 Axis A7, cross-doc contradiction, uses a paired read. That read applies an anti-false-positive layer test. An axis that cannot be covered becomes "not-covered: <reason>".
@@ -35,16 +33,14 @@ Axis A7, cross-doc contradiction, uses a paired read. That read applies an anti-
 
 Phase 1 requires rival mechanisms, for example "agent non-compliant" versus "target legitimately removed". It applies an addressability filter and a self-sufficient severity matrix.
 
-**Output** is an evidence bundle ordered by severity. Run à la carte, the skill prints the report to chat. It does not write to disk. It opens no gate. Under `evolve`, it feeds the proposal instead.
+**Output** is an evidence bundle ordered by severity. Run à la carte, the skill prints the report to chat. It does not write to disk. It opens no gate. Under `/afm:evolve`, it feeds the proposal instead.
 
 This scan has no cooldown. It is read-only and cheap. The cycle's cooldown belongs to the orchestrator.
 
 ## Invariant principles
 
-Single canonical source: `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply. Especially relevant: #2 (discover-first — diagnose with evidence before any proposal). Also #3 (mechanize-or-demote — the checks must pass the test they audit). Also #5 (no finding without evidence external to the text).
+Most relevant here: #2 (discover-first — diagnose with evidence before any proposal). Also #3 (mechanize-or-demote — the checks must pass the test they audit). Also #5 (no finding without evidence external to the text).
 
 **No new principle here.** `diagnose` is a composed materialization. The doctrine lives in the op file.
 
-## Version
-
-Content version: `afm version` prints it.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/evolve/SKILL.md

@@ -10,11 +10,11 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
+> **Procedure.** Run `afm read ops/evolve.md` and follow it; read an on-demand section when its condition holds.
+
 This is an orchestrator skill of AFM. The canonical procedure is the op file that `afm path ops/evolve.md` prints.
 
-> **Conductor, not executor** (same pattern as `deliver`). `evolve` owns 3 things that no mechanism owns alone: (1) the evidence-collection driver for the whole instance (combines `diagnose` + `reflect`), (2) the split into buckets plus the single gate, (3) the apply driver, post-conditions, and the log/lineage record. It reads and follows everything else from the mechanisms, through a suppression contract.
->
-> **Carve-outs (it does not override existing ops):** `diagnose`/`reflect`/`generalize`/`restructure` are the **mechanisms** (each runs à la carte). `analyze` audits **one feature** (read-only). `reconcile` proposes **one single edit** at the end of a turn. `promote` **records** a finding meant for the plugin (it does not edit the plugin). `evolve` is the **cycle** that chains the mechanisms with one gate and one log — the level no other op covers.
+> **Carve-outs (it does not override existing ops):** `/afm:diagnose`, `/afm:reflect`, `/afm:generalize` and `/afm:restructure` are the **mechanisms** (each runs à la carte). `/afm:analyze` audits **one feature** (read-only). Passive mode (`/afm:reconcile`) proposes **one single edit** at the end of a turn. `/afm:promote` **records** a finding meant for the plugin (it does not edit the plugin). `evolve` is the **cycle** that chains the mechanisms with one gate and one log — the level no other op covers.
 
 ## When NOT to activate
 
@@ -22,7 +22,7 @@ This section helps someone who already activated the skill decide if it fits. It
 
 Use a single mechanism instead when the need is narrow. A report is `/afm:diagnose`. Refining a doc that misled you is `/afm:reflect`. Merging gotchas is `/afm:generalize`.
 
-A structure or staleness check is `/afm:restructure`. A version bump is `/afm:update`. `reconcile` proposes a one-off additive signal (new gotcha, rule, or ADR) directly.
+A structure or staleness check is `/afm:restructure`. A version bump is `/afm:update`. Passive mode (`/afm:reconcile`) proposes a one-off additive signal (new gotcha, rule, or ADR) directly.
 
 A feature-level check is `/afm:analyze` or `/afm:deliver`. Recording a finding for the plugin is `/afm:promote`.
 
@@ -34,36 +34,16 @@ A feature-level check is `/afm:analyze` or `/afm:deliver`. Recording a finding f
 
 ## Procedure
 
-Read the op (`afm path ops/evolve.md`) end to end and follow it exactly. The op has 5 phases.
-
-**Phase 1 — Evidence collection.** Combine two sources through the suppression contract. `diagnose` is the mechanical scan of the 7 axes (`afm doctor --json` plus the A7 reading), read-only. `reflect` is behavioral evidence of docs that misled the agent. Run `generalize`/`restructure` on demand, when their own trigger signal fires. An empty diagnosis counts as a valid result.
-
-**Phase 2 — Proposal.** This phase plays the IMPROVER role. Apply the op's **shared proposal discipline**: retrieval before create, then a dry run before the gate. Split the proposals into 3 buckets.
-
-A non-restorable change always goes through the gate. It never invents its own target. Decide here whether to downgrade, archive, or merge an artifact. Cap bucket (b) at 8 items per cycle (`afm evolve gate-check --critical <n> --high <n> --medium <n> --low <n>` computes what to ask and what to stage). Recurring failures come from `afm failures promotable`.
-
-**Phase 3 — Single gate.** Ask item by item with `afm ask evolve --scope <item-slug>`, at most 4 questions per call. This gate is never skippable — there is no "go" shortcut.
-
-**Phase 4 — Apply and post-conditions.** Re-run `afm doctor --json`, `afm index --check` and `afm detect --for <file>` over the touched docs, and confirm the content root is clean (`git status`, or a timestamp check with no git).
-
-**Phase 5 — Log.** Record the cycle in `docs/evolution/NNN-<date>.md`. Suggest `promote` when a finding generalizes beyond this instance.
+Read the op (`afm path ops/evolve.md`) end to end and follow it exactly. The op has 5 phases: evidence collection (diagnose plus reflect), proposal in 3 buckets, a single gate (`afm ask evolve`), apply with post-conditions, and the log in `docs/evolution/`.
 
 Consult the rubric `rubrics/when-to-evolve-methodology.md` (`afm path rubrics/when-to-evolve-methodology.md`) to decide between a full cycle, a single mechanism, or a one-off fix.
 
-## Invariant principles
-
-The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply. #2 (discover-first) applies: diagnose with evidence before you propose. #3 (mechanize-or-downgrade) applies too: evolve's own signals must pass the same test evolve applies to others.
-
-#8 (earned questions, recommendation-first) also applies to this skill.
+## Most relevant principles
 
-#6 (autonomy-first with self-check) follows the pattern *produce → self-check → report*. The gate is the load-bearing residue. Bright lines for #7 plugin, deletion, and push still apply.
-
-**No new principle here** — evolve is a composed materialization. The doctrine lives in the op and the rubric.
+#2 (discover-first): diagnose with evidence before you propose. #3 (mechanize-or-downgrade): evolve's own signals must pass the same test evolve applies to others. #6 (autonomy-first with self-check): the gate is the load-bearing residue, and the bright lines for #7 plugin, deletion, and push still apply. #8 (earned questions, recommendation-first).
 
 ## Continuous doctrine
 
-The `reconcile` skill owns passive mode, and it is always on. Reconcile may **suggest** `/afm:evolve` when it detects a Class B signal. That signal is a lived contradiction between docs, or perceived inflation at apply time. Only the user can invoke the full cycle.
-
-## Version
+Passive mode (`/afm:reconcile`) is always on. It may **suggest** `/afm:evolve` when it detects a Class B signal. That signal is a lived contradiction between docs, or perceived inflation at apply time. Only the user can invoke the full cycle.
 
-Content version: `afm version` prints it.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/export-template/SKILL.md

@@ -9,8 +9,9 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/export-template`. The CLI owns the plan,
-the diff and the marker. This skill keeps the judgment.
+> **Procedure.** Run `afm read ops/export-template.md` and follow it; read an on-demand section when its condition holds.
+
+The CLI owns the plan, the diff and the marker. This skill keeps the judgment.
 
 ## When NOT to activate
 
@@ -34,9 +35,9 @@ stop and suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply.
-
-Especially #5 (do not invent metadata when the operator leaves it blank: use `[TBD]` in the JSON). Also #6
+Most relevant here: #5 (do not invent metadata when the operator leaves it blank: use `[TBD]` in the JSON). Also #6
 (autonomy-first, but deleting files is a bright line): confirm the diff before you delete.
 
 Passive mode (`/afm:reconcile`) is always on. This skill focuses only on the active conversion to a template.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/generalize/SKILL.md

@@ -10,15 +10,15 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-Mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/generalize.md` prints.
+> **Procedure.** Run `afm read ops/generalize.md` and follow it; read an on-demand section when its condition holds.
 
-> **Carve-out (does not overlap existing ops):** `promote` **registers** a finding meant for the plugin. It does not write to the plugin. `generalize` merges **inside the instance** (N gotchas become 1 rule in the same `/docs/`). `reconcile` **adds** a new gotcha. `generalize` **merges** gotchas that already exist. `reflect` refines **one** doc. `generalize` consolidates **many**. `evolve` is the **orchestrator** and it composes this skill when `diagnose` flags inflation from redundant gotchas.
+> **Carve-out (does not overlap existing ops):** `/afm:promote` **registers** a finding meant for the plugin. It does not write to the plugin. `/afm:generalize` merges **inside the instance** (N gotchas become 1 rule in the same `/docs/`). `/afm:reconcile` **adds** a new gotcha. `/afm:generalize` **merges** gotchas that already exist. `/afm:reflect` refines **one** doc. `/afm:generalize` consolidates **many**. `/afm:evolve` is the **orchestrator** and it composes this skill when `/afm:diagnose` flags inflation from redundant gotchas.
 
 ## When NOT to activate
 
 This is a disambiguation criterion for someone who already activated the skill, not an activation trigger. That is why it lives in the body, not in the resident listing.
 
-Sending ONE learning to the plugin is `/afm:promote`. ADDING a new gotcha or rule is `reconcile` -> `/afm:gotcha`/`/afm:rule` (`generalize` only merges what already exists). Refining the clarity of ONE doc is `/afm:reflect`. With fewer than 2 similar candidates, there is no generalization to do.
+Sending ONE learning to the plugin is `/afm:promote`. ADDING a new gotcha or rule is `/afm:reconcile` -> `/afm:gotcha`/`/afm:rule` (`/afm:generalize` only merges what already exists). Refining the clarity of ONE doc is `/afm:reflect`. With fewer than 2 similar candidates, there is no generalization to do.
 
 ## Pre-check
 
@@ -26,24 +26,12 @@ Sending ONE learning to the plugin is `/afm:promote`. ADDING a new gotcha or rul
 2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
 3. **Is there a batch of >=2** similar gotchas/reflections? If not, report "nothing to generalize (no batch)" and stop. Generalizing from 1 case is forbidden (#5).
 
-## Procedure
+## Gate
 
-Read the op (`afm path ops/generalize.md`) end to end. Follow it literally.
+The merge is load-bearing and goes through its own earned gate, `afm ask generalize` (suppressed under `/afm:evolve`). Merged entries become tombstones; never delete.
 
-**1. Identify the batch:** cluster by shared abstract cause, >=2 cases. Ask "would one more general instruction have prevented all N?" A larger batch yields a more abstract rule.
+## Most relevant here
 
-**2. MetaReflect:** draft the generalized, non-case-specific rule. The original cases become examples. Follow the **shared proposal discipline** from `evolve.md` (`afm path ops/evolve.md`) instead of duplicating it. Reduce, do not create a parallel path.
+#1 (episodic `gotchas.md` -> semantic `afm.md`), #3 (a merged rule becomes hard only with an executable 0/1 trigger), #5 (no abstraction without a real batch), #6/#8 (self-verify before an earned gate; deletion is a bright line, so archive as tombstones). No new principle here: the doctrine lives in the op.
 
-**3. ShowsImprovement + backtracking:** check if the rule covers all N cases. A hard rule needs an executable 0/1 trigger. Otherwise it becomes a § 1.3 principle. If it cannot cover all cases without turning vague, back out and keep the cases separate.
-
--> **4. Own gate** (item (b), unavoidable and earned, through `afm ask generalize`; suppressed under `evolve`. On approval: write the rule via `rule.md` (`afm rule new <slug>`) and **archive the merged entries as tombstones**. Never delete) -> **5. Record** the result in `docs/evolution/NNN-<date>.md`. Suggest `promote` if the finding matters beyond this instance.
-
-## Invariant principles
-
-Single canonical source: `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply here, especially #1 (episodic `gotchas.md` -> semantic `afm.md`). Also #3: a merged rule becomes hard only with an executable 0/1 trigger, the ShowsImprovement step of MetaReflection. Also #5: do not invent an abstraction without a real batch.
-
-Also #6/#8: self-verify before an earned gate. Deletion is a bright line. Use tombstones instead. **No new principle here** — `generalize` is a composed materialization. The doctrine lives in the op file.
-
-## Version
-
-Content version: `afm version` prints it.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.