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

package/plugin/agy/skills/afm-clarify/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.
 
-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/agy/skills/afm-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 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.
+> **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/agy/skills/afm-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 mis
 
 ## 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/agy/skills/afm-evolve/SKILL.md

@@ -10,11 +10,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.
 
+> **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 for
 
 ## 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/agy/skills/afm-export-template/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.
 
-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/agy/skills/afm-generalize/SKILL.md

@@ -10,15 +10,15 @@ 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.
 
-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 rule
 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`.

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

@@ -9,8 +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/gotcha`. The CLI owns the entry
-gate, the number, the frontmatter the trigger index reads and the index. This skill keeps only the judgment.
+> **Procedure.** Run `afm read ops/gotcha.md` and follow it; read an on-demand section when its condition holds.
+
+The CLI owns the entry gate, the number, the frontmatter the trigger index reads and the index. This skill
+keeps only the judgment.
 
 ## When NOT to activate
 
@@ -34,9 +36,11 @@ signal belongs to `afm-remediate`.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Two matter most here: #5 (do not
+Most relevant here: #5 (do not
 invent a gotcha without a real case; the 2x entry check is a strong gate) and #6 (autonomy-first: save the
 result and report it).
 
 Passive mode (`afm-reconcile`) is always on and can propose `afm-gotcha` when it detects the signal "the
 same runtime surprise blocked work twice." This skill covers only active registration.
+
+**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-init/SKILL.md

@@ -71,14 +71,11 @@ procedure is in `afm path interview/bootstrap` § Alternate branch. `.afm-versio
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. For this skill (greenfield), the 8 universals apply (§1-8).
-#9 (retroactive ADR, load-bearing) does NOT apply to init. Bootstrap forbids a retroactive ADR.
+For this skill (greenfield), #9 (retroactive ADR, load-bearing) does NOT apply to init. Bootstrap forbids a retroactive ADR.
 
 ## Continuous doctrine
 
-Passive mode (`afm-reconcile`) is the responsibility of the `reconcile` skill. It stays always-on in any AFM
+Passive mode (`afm-reconcile`) stays always-on in any AFM
 project session. This skill covers only the active bootstrap procedure.
 
-## Version
-
-`afm version` prints the version in use. History: `afm path CHANGELOG`.
+**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-plan/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/plan.md`, end to end, and follow it literally.
+> **Procedure.** Run `afm read ops/plan.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
-There is no `spec.md` yet: run `afm-specify` first. An end-to-end delivery is `deliver`, which composes this op.
+There is no `spec.md` yet: run `afm-specify` first. An end-to-end delivery is `afm-deliver`, which composes this op.
 
 ## Pre-check
 
@@ -25,12 +25,10 @@ Read the stack from `docs/ach.md` and never reopen it. Infer the components, dec
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #2 (discover-first: scan before you ask), #5 (do not invent contracts or a stack) and #8 (a question carries a recommendation).
+Most relevant here: #2 (discover-first: scan before you ask), #5 (do not invent contracts or a stack) and #8 (a question carries a recommendation).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only the planning.
+Passive mode (`afm-reconcile`) is always on. This skill covers only the planning.
 
-## 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-policy/SKILL.md

@@ -7,7 +7,7 @@ description: |
 
 # AFM — Policy (report the organisation layer)
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/policy`.
+> **Procedure.** Run `afm read ops/policy.md` and follow it; read an on-demand section when its condition holds.
 
 ## When not to activate
 
@@ -26,6 +26,4 @@ Run `afm policy report` and read it by family. Say plainly that a policy bundle
 nothing, and name what the reader may not edit here and who owns it. Never report a policy rule as
 enforced.
 
-## Invariant principles
-
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply.
+**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-promote/SKILL.md

@@ -7,7 +7,7 @@ description: |
 
 # AFM — Promote
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/promote`.
+> **Procedure.** Run `afm read ops/promote.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
@@ -31,7 +31,7 @@ bring the plugin INTO the instance (the opposite direction).
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. That includes #5: never record a
+Most relevant here: #5: never record a
 project-specific learning, and never one without a real case; the list grows on demand.
 
 It also includes #6/#7: the plugin boundary is **absolute**. This op records a finding and never applies a
@@ -39,3 +39,5 @@ change.
 
 Passive mode (`afm-reconcile`) is always on and can propose `afm-promote` when it detects a signal that a
 learning generalizes to any project.
+
+**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-protocol/SKILL.md

@@ -7,8 +7,9 @@ description: |
 
 # AFM — Protocol (declared autonomy posture)
 
-Skill of `afm`. The canonical procedure is the op `afm path ops/protocol`. Field and preset definitions are
-in `afm path core/protocol`.
+> **Procedure.** Run `afm read ops/protocol.md` and follow it; read an on-demand section when its condition holds.
+
+Field and preset definitions are in `afm path core/protocol`.
 
 > **A protocol is data, not a new execution path.** It parametrizes operations that already exist. A project
 > with no `protocol:` declared uses the defaults, which reproduce pre-v4 behavior.
@@ -35,8 +36,10 @@ Outside the three presets, the file must already exist: never invent one.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. See especially #4 and #5.
+Most relevant here: #4 and #5.
 
 #4: `[TBD]` beats invention. An instance with no declared posture does not receive an assumed one.
 
 #5: Do not invent a preset without a real case.
+
+**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-reconcile/SKILL.md

@@ -6,6 +6,8 @@ description: |
 
 # AFM — Reconcile (passive mode, always-on)
 
+> **Procedure.** Run `afm read ops/reconcile.md` and follow it; read an on-demand section when its condition holds.
+
 The always-on skill. It loads the continuous doctrine and the passive-mode procedure, and it is the only skill that activates by default in any AFM project session. Every other skill needs explicit invocation or specific natural language.
 
 ## When NOT to activate
@@ -24,7 +26,7 @@ One criterion decides where something belongs (universal principle #1, source in
 
 `docs/` holds rules, decisions, gotchas, architecture, persona, flows and cross-module contracts. The agent's memory holds only the user's style and durable preferences ("small PRs, not big bundles") and personal context (role, years of experience, current focus).
 
-`docs/` is a living source, **not a frozen bootstrap artifact**: it evolves through the whole session by passive reconcile. The signal table is `afm path interview/triggers.md`. The procedure is the op: read it with `afm path ops/reconcile.md`.
+`docs/` is a living source, **not a frozen bootstrap artifact**: it evolves through the whole session by passive reconcile. The signal table is `afm path interview/triggers.md`.
 
 ## Procedure (always-on)
 
@@ -42,8 +44,6 @@ Never apply an edit without proposing it first, never save a project rule in mem
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply, in particular #1 (the one criterion for memory against doc), #5 (no gotcha or rule without a case) and #6 (reconcile PROPOSES at the end of the turn).
-
-## Version
+Most relevant here: #1 (the one criterion for memory against doc), #5 (no gotcha or rule without a case) and #6 (reconcile PROPOSES at the end of the turn).
 
-`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-refactor/SKILL.md

@@ -72,15 +72,12 @@ For brownfield projects without `docs/.afm-version`:
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. For this skill (brownfield), **all** apply: the 8 universals
+For this skill (brownfield), **all** principles apply: the 8 universals
 §1-8 plus the addition §9 (a retroactive ADR is load-bearing-only). #9 separates refactor from init. Init
 forbids retroactive ADRs.
 
 ## Continuous doctrine
 
-Passive mode (`afm-reconcile`) is the responsibility of the `reconcile` skill. It is always-on in any AFM
-project session. This skill covers only the active refactor procedure.
+Passive mode (`afm-reconcile`) is always-on in any AFM project session. This skill covers only the active refactor procedure.
 
-## Version
-
-`afm version` prints the version in use. History: `afm path CHANGELOG`.
+**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-reflect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: afm-reflect
 description: |
-  Finds where the local docs failed AS A HARNESS in this session. Examples are an ambiguous rule applied wrong, a doc that misled, and a user correction against the doc. The evidence is the session trajectory, never a static scan. It proposes edits that make the docs more assertive.
+  Finds where the local docs failed AS A HARNESS in the live session and the project's sessions since the last cycle. Examples are an ambiguous rule applied wrong, a doc that misled, and a user correction against the doc. The evidence is the session trajectory, never a static scan. It proposes edits that make the docs more assertive.
   Activates: `afm-reflect`, "this rule is ambiguous", "the doc sent me the wrong way", "why do I keep getting this wrong when the doc covers it?".
 ---
 
@@ -10,46 +10,40 @@ 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.
 
-Mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/reflect.md` prints.
+> **Procedure.** Run `afm read ops/reflect.md` and follow it; read an on-demand section when its condition holds.
 
-> **Carve-out (does not overlap existing ops):** `reconcile` works **code to docs, and is additive**. It learns a new fact and proposes adding it. `reflect` works **docs to docs, and refines**. An existing doc guided the agent wrong, so `reflect` proposes a clearer version. `diagnose` runs a **static** scan. `reflect` uses **behavioral** evidence from the session trajectory. Only the agent sees its own stumble. `evolve` is the **orchestrator**. It composes `reflect` and `diagnose` into one cycle with a single gate.
+> **Carve-out (does not overlap existing ops):** `afm-reconcile` works **code to docs, and is additive**. It learns a new fact and proposes adding it. `reflect` works **docs to docs, and refines**. An existing doc guided the agent wrong, so `reflect` proposes a clearer version. `afm-diagnose` runs a **static** scan. `reflect` uses **behavioral** evidence from the session trajectory. Only the agent sees its own stumble. `afm-evolve` is the **orchestrator**. It composes `reflect` and `afm-diagnose` into one cycle with a single gate.
 
 ## When not to activate
 
 This is a disambiguation criterion for a skill already active, not an activation criterion. That is why it lives in the body, not in the resident listing.
 
-Learning a new fact, gotcha, or decision belongs to `reconcile`. Route it to `afm-gotcha`, `afm-rule`, or `afm-adr`. A static mechanical scan belongs to `afm-diagnose`. Merging N gotchas belongs to `afm-generalize`. A failure with an external signal belongs to `afm-remediate`. The full cycle belongs to `afm-evolve`.
+Learning a new fact, gotcha, or decision belongs to passive mode (`afm-reconcile`). Route it to `afm-gotcha`, `afm-rule`, or `afm-adr`. A static mechanical scan belongs to `afm-diagnose`. Merging N gotchas belongs to `afm-generalize`. A failure with an external signal belongs to `afm-remediate`. The full cycle belongs to `afm-evolve`.
 
 ## Pre-check
 
 1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm-init` (greenfield) or `afm-refactor` (brownfield) first.
 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. **Did the session hit a doc-friction event** (or an articulated symptom)? If not, report "no doc friction observed" and stop. Reflection without behavioral evidence is forbidden (#5).
+3. **Did the live session or the project's sessions since the last cycle hit a doc-friction event** (or an articulated symptom)? Read the window with `afm sessions --since reflect --json` and `afm sessions signals --since reflect --json`. If the whole window has no signal, report "no doc friction observed" and stop. Reflection without behavioral evidence is forbidden (#5).
 
 ## Procedure
 
-Read the op (`afm path ops/reflect.md`) end to end. Follow it literally.
-
 The steps are:
 
-**1. Collection.** Build the behavioral signature φ_b = `(symptom-lived, doc-causal-status, mechanism)`. Cite both the doc passage **and** the session event.
+**1. Collection.** Build the behavioral signature φ_b = `(symptom-lived, doc-causal-status, mechanism)`. Cite both the doc passage **and** the session event (`session:<id>@<ts>`). Weight: one signal in the live session suffices; a past-session signal needs 2 or more sessions, an explicit correction, or `regressed`, and `regressed` comes first. A repeated prompt is a finding: propose the artifact that stops the retyping.
 
 **2. Self-critique.** Consider a rival hypothesis: it was me, not the doc. Apply the guardrail: a violated rule is not a wrong rule. Apply an addressability filter.
 
 **3. Proposal.** Refine instructiveness: rewrite the ambiguous part, add an executable trigger, and remove ambiguity. Add suggestions for the human. This step follows the **shared proposal discipline** in `evolve.md` (`afm path ops/evolve.md`) and does not duplicate it.
 
-**4. Own gate.** Ask item by item, earned, with `afm ask reflect --scope <item-slug>`. `evolve` suppresses this gate.
+**4. Own gate.** Ask item by item, earned, with `afm ask reflect --scope <item-slug>`. `afm-evolve` suppresses this gate.
 
-**5. Record.** Write to `docs/evolution/NNN-<date>.md`. Add a `promote` suggestion when the finding generalizes. Hand off to `reconcile`.
+**5. Record.** Write to `docs/evolution/NNN-<date>.md`. Add an `afm-promote` suggestion when the finding generalizes. Hand off to passive mode (`afm-reconcile`).
 
 ## Invariant principles
 
-The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universals §1-8 apply.
-
 Rule #1 applies: refine the doc's instructiveness, not the agent's memory. Rule #5 applies: no lived event, no finding. Rule #6 applies: self-verify, then report. The gate is a load-bearing residue. Bright lines #7 for plugin, deletion, and push apply.
 
 Rule #8 applies: a suggestion or question must be earned, recommendation-first. **No new principle here.** `reflect` 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-remediate/SKILL.md

@@ -10,7 +10,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 file that `afm path ops/remediate.md` prints.
+> **Procedure.** Run `afm read ops/remediate.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
@@ -26,16 +26,14 @@ Use `afm.md § 5.1` for an in-task retry at the moment of the error. Use `afm-go
 
 ## Procedure
 
-Read the op (`afm path ops/remediate.md`) end to end and follow it literally. It includes the promotion gate (#5): 1 user correction OR at least 2 mechanical occurrences promote a failure. A transient failure does not promote. It also includes classification through the rubric `rubrics/failure-classification.md` (`afm path rubrics/failure-classification.md`). For each delta, propose the artifact (procedure or learning) and cite the source `sig=` (hard rule 19). Ask the artifact question with `afm ask remediate --scope <sig>`, materialize the result, close the signature with `afm failures close --sig <sig> --as remediated`, and report it (#6).
+The op includes the promotion gate (#5): 1 user correction OR at least 2 mechanical occurrences promote a failure. A transient failure does not promote. It also includes classification through the rubric `rubrics/failure-classification.md` (`afm path rubrics/failure-classification.md`). For each delta, propose the artifact (procedure or learning) and cite the source `sig=` (hard rule 19). Ask the artifact question with `afm ask remediate --scope <sig>`, materialize the result, close the signature with `afm failures close --sig <sig> --as remediated`, and report it (#6).
 
 ## Invariant principles
 
-The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). See in particular #3 (CRITIC corollary — recognition by tool, not self-judgment). See also #5 (do not promote a failure without recurrence or an oracle) and #6 (propose only, the human approves).
+Most relevant here: #3 (CRITIC corollary — recognition by tool, not self-judgment). See also #5 (do not promote a failure without recurrence or an oracle) and #6 (propose only, the human approves).
 
 ## Continuous doctrine
 
-The `reconcile` skill owns passive mode, and it is always on. It reads `afm failures promotable` at the end of the turn and can propose remediation with no explicit command. The `evolve` cycle uses the failure events as evidence for `reflect`, toward a final remediation. This skill is the active record of the loop.
+Passive mode (`afm-reconcile`) is always on. It reads `afm failures promotable` at the end of the turn and can propose remediation with no explicit command. The `afm-evolve` cycle uses the failure events as evidence for `afm-reflect`, toward a final remediation. This skill is the active record of the loop.
 
-## 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`.