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

package/content/tools/gate/lib/ratchet.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Ratchet — a budget of violations per rule and region, monotonically decreasing.
+#
+# It exists because turning a hard rule on in a repository that already breaks it makes the
+# gate start red, and a gate that is red on day 1 is disabled on day 2. The ratchet lets the
+# pre-existing debt through and fails the GROWTH.
+#
+# Format of the ratchet TSV (header plus rows):
+#   rule	region	count	note
+#   21	.	0	no debt — the rule was born clean
+#   34	src/legacy	4	pre-existing when the gate was turned on
+#
+# `region` is a path relative to the repository root; `.` covers the whole repository. A finding
+# counts against the MOST SPECIFIC CONFIGURED region that prefixes its path. That is what lets
+# you turn a rule on only where it is already clean, without a per-file exception list.
+#
+# Sourceable, not executable: `. "${AFM_GATE_LIB}/ratchet.sh"`.
+
+# ratchet_budget <rule> <region> -> prints the budget (0 when not registered).
+# Absence means 0 on purpose: a new rule is born with zero tolerance, and debt exists only when
+# somebody measured it and wrote it down. A permissive default would be the door to a phantom gate.
+ratchet_budget() {
+  local rule="$1" region="$2" f="${RATCHET:-}"
+  [ -n "$f" ] && [ -f "$f" ] || { printf '0'; return 0; }
+  # A value bash cannot compare is malformed, not a budget. The TSV is written by hand, and an
+  # all-digit number beyond the 64-bit range survives awk (printed back as 100000000000000000000)
+  # and then breaks `[ -le ]` itself with "integer expression expected" — which evaluates falsy,
+  # so the finding counts as over budget and stderr fills up on every run. Over 9 digits is far
+  # beyond any debt anyone measured and far below where the comparison breaks; treat it as 0,
+  # the same answer an unregistered rule gets, because a budget nobody can read is a budget
+  # nobody measured.
+  awk -F'\t' -v r="$rule" -v g="$region" '
+    NR>1 && $1==r && $2==g {
+      v = $3 + 0
+      if (v < 0 || v > 999999999) v = 0
+      printf "%d", v; found=1; exit
+    }
+    END { if (!found) print 0 }
+  ' "$f"
+}
+
+# ratchet_region <rule> <path> -> prints the most specific configured region that prefixes
+# <path>, or "." when none matches.
+ratchet_region() {
+  local rule="$1" path="$2" f="${RATCHET:-}"
+  [ -n "$f" ] && [ -f "$f" ] || { printf '.'; return 0; }
+  awk -F'\t' -v r="$rule" -v p="$path" '
+    # An `exempt` row is a SCOPE statement, not a budget. Letting it act as a region made it
+    # absorb every finding under that path into a budget of 0, so the rule failed there instead
+    # of skipping it — the exemption turned into its opposite.
+    NR>1 && $1==r && $2!="." && tolower($3)!="exempt" {
+      # `index()==1` is a literal prefix. No regex, because a path holding "." or "+" would
+      # turn into a metacharacter and match the wrong region in silence.
+      #
+      # A region is a PATH, so the prefix must end at a path boundary. Without that check,
+      # `docs/research-extra/x.md` starts with the characters of `docs/research` and spent the
+      # the neighbouring budget — a budget that absorbs a directory nobody measured stops meaning
+      # anything, and it fails toward green. A trailing slash written by hand is tolerated.
+      reg = $2
+      sub(/\/+$/, "", reg)
+      if (index(p, reg) == 1 \
+          && (length(p) == length(reg) || substr(p, length(reg) + 1, 1) == "/") \
+          && length(reg) > length(best)) best=reg
+    }
+    END { print (best == "" ? "." : best) }
+  ' "$f"
+}
+
+# ratchet_note <rule> <region> -> the recorded reason for the debt (empty when there is none).
+ratchet_note() {
+  local rule="$1" region="$2" f="${RATCHET:-}"
+  [ -n "$f" ] && [ -f "$f" ] || return 0
+  awk -F'\t' -v r="$rule" -v g="$region" 'NR>1 && $1==r && $2==g { print $4; exit }' "$f"
+}
+
+# ratchet_has_rule <rule> -> exit 0 when the rule already has any row.
+# `--baseline` uses it to refuse to touch a rule a human already decided about.
+ratchet_has_rule() {
+  local rule="$1" f="${RATCHET:-}"
+  [ -n "$f" ] && [ -f "$f" ] || return 1
+  awk -F'\t' -v r="$rule" 'NR>1 && $1==r { found=1; exit } END { exit !found }' "$f"
+}
+
+# ratchet_exempt <rule> <path> -> exit 0 when the path is OUT OF SCOPE for the rule.
+#
+# An exemption is not a budget, and conflating the two was the reason this function exists.
+# A budget says "this many violations are tolerated here, and the number may only fall". An
+# exemption says "this file is not what the rule is about at all" — the detector's own
+# dictionary, a fixture written to be wrong on purpose, an archived changelog.
+#
+# Until 3.20.0 every exemption was a `case ... continue ;;` arm inside the runner, naming a
+# path in ONE repository. That made the runner unshippable: a consumer inherited exclusions for
+# files it does not have, and had nowhere to write its own. Worse, the exclusion was invisible —
+# it lived in code nobody re-reads, while the ratchet is a versioned table a reviewer sees.
+#
+# Written as a row whose count column is the literal `exempt`:
+#
+#   rule	region	count	note
+#   38	plugins/afm/framework-template/tools/afm-lang.sh	exempt	the accented alternation IS the detector
+#   37	docs/legacy	exempt	vendored, not ours to rewrite
+#
+# `region` is a path prefix that must end at a path boundary — the same rule `ratchet_region`
+# applies, and for the same reason: `docs/research-extra` must not spend `docs/research`'s row.
+# A trailing `/*` is tolerated and means the same as the bare directory.
+ratchet_exempt() {
+  local rule="$1" path="$2" f="${RATCHET:-}"
+  [ -n "$f" ] && [ -f "$f" ] || return 1
+  awk -F'\t' -v r="$rule" -v p="$path" '
+    NR>1 && $1==r && tolower($3)=="exempt" {
+      reg = $2
+      sub(/\/\*+$/, "", reg)
+      sub(/\/+$/, "", reg)
+      if (reg == "") next
+      if (index(p, reg) == 1 \
+          && (length(p) == length(reg) || substr(p, length(reg) + 1, 1) == "/")) { hit=1; exit }
+    }
+    END { exit !hit }
+  ' "$f"
+}

package/content/tools/gate/lib/scope.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Scope of a runner: which files to look at, in each mode.
+#
+# `staged` looks at the INDEX, because the index is what becomes the commit. Failing on a
+# dirty file that is not staged is a false positive, and a gate with false positives is a
+# gate people work around.
+#
+# Declared limit: the CONTENT rules read the file on disk, not the blob in the index. In the
+# normal flow (edit, add, commit) the two are the same. Under a partial `git add -p` the gate
+# can report a line that is not staged. We prefer the rare false positive to the silent false
+# negative, but this is a known imprecision, not an oversight.
+#
+# Sourceable, not executable: `. "${AFM_GATE_LIB}/scope.sh"`.
+
+# UNTRACKED files are part of the working tree, so `worktree` must include them. Until
+# 3.9.0-rc.8 it did not: `git ls-files` lists what git tracks and `git diff HEAD` compares
+# against what git tracks, and a file created one minute ago is in neither. A brand new secret
+# (rule 13) or a brand new document in the wrong language (rule 37) therefore passed at exit 0,
+# and exit 0 from a gate reads as "I looked and it is clean", never as "I did not look". The
+# gate failed in the direction that looks like success.
+#
+# `--exclude-standard` keeps .gitignore out: an ignored file is a deliberate stance, not debt.
+# `staged` deliberately does NOT include them — a file nobody added is not entering this commit,
+# and failing on it would be the false positive that makes people work around the gate.
+
+# scope_untracked [pathspec...] -> untracked, non-ignored paths
+scope_untracked() { git ls-files --others --exclude-standard -- "$@"; }
+
+# scope_files <mode> [pathspec...] -> paths relative to the repository root
+scope_files() {
+  local mode="$1"; shift
+  case "$mode" in
+    worktree) { git ls-files -- "$@"; scope_untracked "$@"; } | sort -u ;;
+    *)        git diff --cached --name-only --diff-filter=ACMR -- "$@" ;;
+  esac
+}
+
+# scope_diff <mode> [pathspec...] -> the added content only (new lines)
+#
+# For an untracked file there is no blob to diff against, so we synthesize one with
+# `git diff --no-index /dev/null <file>`. That form is read-only. `git add -N` would give the
+# same output by writing to the index, and a gate does not write. `--no-index` exits 1 whenever
+# it finds a difference, which is always here, so its status is discarded on purpose.
+scope_diff() {
+  local mode="$1"; shift
+  case "$mode" in
+    worktree)
+      git diff HEAD -- "$@"
+      local f
+      while IFS= read -r f; do
+        [ -f "$f" ] || continue
+        git diff --no-index -- /dev/null "$f" || true
+      done < <(scope_untracked "$@")
+      ;;
+    *)        git diff --cached -- "$@" ;;
+  esac
+}
+
+# scope_all [pathspec...] -> EVERY tracked file.
+#
+# It exists because there are two classes of rule and they cannot share a scope:
+#
+#   * a DIFF rule (a plaintext secret, a version bump, a test that must run) speaks about what
+#     enters the commit. Its scope is the index. Its budget is normally 0: a new secret is
+#     never "inside the quota". A measured exception exists — a rule can hold a small budget in
+#     one region when the gate itself found pre-existing debt there.
+#
+#   * a COUNT rule (a path convention, the language of an identifier, a single source) speaks
+#     about a total of the repository, compared against the ratchet. Its scope is the whole
+#     repository, ALWAYS, even under `--staged`.
+#
+# Counting a count rule over the index is a silent FALSE NEGATIVE. With a budget of 7, a commit
+# that adds 1 new violation counts 1 <= 7 and passes clean. The ratchet means "it did not grow"
+# only when it measures the same total it recorded.
+#
+# It takes the mode from `AFM_GATE_MODE`, exported by the aggregator, because its signature has
+# to stay `scope_all [pathspec...]`: every runner in this repository and every runner a consumer
+# already wrote calls it that way. Under `--worktree` it also counts the untracked files, for the
+# same reason `scope_files` does. Default `staged` keeps a runner called directly by hand honest.
+scope_all() {
+  case "${AFM_GATE_MODE:-staged}" in
+    worktree) { git ls-files -- "$@"; scope_untracked "$@"; } | sort -u ;;
+    *)        git ls-files -- "$@" ;;
+  esac
+}

package/content/tools/gate/ratchet.seed.tsv

@@ -0,0 +1 @@
+rule	region	count	note

package/content/tools/gate/rules/README.md

@@ -0,0 +1,50 @@
+# Rule runners — the PROJECT's own
+
+This directory is **empty on purpose**, and since 3.20.0 that statement is narrower than it used
+to be. Read [`../core-rules/README.md`](../core-rules/README.md) beside it.
+
+There are **two classes of rule**, and conflating them was a real defect (ADR 0021).
+
+A **project rule** is about this project's own CODE — a line limit, a layering constraint, a
+naming convention. It belongs here, and the plugin ships none of them. The argument holds
+exactly as it always did: a consumer that inherits a rule nobody chose bypasses it first.
+
+An **artifact rule** is about the `docs/` that AFM itself materializes — English prose, no
+absolute path, the OKF frontmatter contract, a versioned runner behind every 0/1 trigger.
+Nobody "chooses" those. They are what an AFM instance IS, and they ship in `../core-rules/`
+under the `PLUGIN-` namespace. Until 3.20.0 they existed only in the plugin's own repository,
+so every consumer received an `afm.md` whose hard rules stopped at 21.
+
+## Write one
+
+Start from [`guardrail-runner.template.md`](../../../templates/guardrail-runner.template.md)
+and follow [`ops/rule.md` § Install the gate](../../../ops/rule.md).
+
+Name it `<NN>-<slug>.sh`, where `NN` is the rule number in `docs/afm.md` § 3. The aggregator
+reads that number from the filename, and `--audit` uses it to cross-check the rule and the
+runner in both directions. A runner whose number matches no rule is reported as an orphan.
+
+## Contract
+
+```
+argv[1]          : "staged" | "worktree"
+env RATCHET      : path of the ratchet TSV
+env AFM_GATE_LIB : directory holding scope.sh and ratchet.sh
+stdout           : one line per finding — "<NN>\t<path>[:<line>]\t<message>"
+exit 0 compliant · 1 violated · 2 COULD NOT decide
+```
+
+Resolve the library through `AFM_GATE_LIB`, never through a fixed path:
+
+```bash
+. "${AFM_GATE_LIB:?}/scope.sh"
+```
+
+The runner does not know where the gate lives. That is what lets the same runner work in a
+project that keeps the gate under `docs/tools/gate/` and in one that keeps it somewhere else.
+
+## Before you turn a rule on
+
+Run `guardrails.sh --baseline`. It measures HEAD and records what it finds as declared debt, so
+the gate starts green in a repository that already breaks the rule. A gate that starts red is
+disabled the next day, and it takes every other rule in the same aggregator with it.

package/package.json

@@ -1,6 +1,20 @@
 {
-  "name": "@tenkara/afm-linux-arm64",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@tenkara/afm-linux-arm64",
+	"version": "4.0.0-alpha.7",
+	"description": "The afm binary (CLI and MCP server) for linux-arm64.",
+	"license": "UNLICENSED",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"linux"
+	],
+	"cpu": [
+		"arm64"
+	],
+	"files": [
+		"bin",
+		"plugin",
+		"content"
+	]
+}

package/plugin/agy/hooks.json

@@ -0,0 +1,29 @@
+{
+  "description": "AFM hooks",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content|run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "afm hook PreToolUse",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content|run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "afm hook PostToolUse",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/agy/mcp_config.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "afm": {
+      "command": "afm-mcp"
+    }
+  }
+}

package/plugin/agy/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "afm",
+  "version": "4.0.0-alpha.7",
+  "description": "AFM (Agent Flow Methodology): hooks and an MCP server that keep a project's docs and its code in step.",
+  "license": "UNLICENSED"
+}

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

@@ -0,0 +1,44 @@
+---
+name: afm-adr
+description: |
+  Writes an Architecture Decision Record to `<consumer>/docs/adr/NNNN-slug.md`. It records context, decision, alternatives and consequence. In a refactored project, write a retroactive ADR only when it is load-bearing.
+  Activates: `afm-adr`, "create ADR", "architectural decision", "record this architecture choice".
+---
+
+# AFM — ADR
+
+> **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/adr`. 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
+
+This is a disambiguation for a skill that already activated. It does not control activation itself. A
+counterintuitive surprise belongs in `afm-gotcha`. A rule with an executable trigger belongs in `afm-rule`.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `afm-init` (greenfield) or
+`afm-refactor` (brownfield) first. Exit 4 means the shipped content does not resolve: report it, do not
+fall back silently.
+
+## Procedure (judgment only)
+
+1. Ask the status: `afm ask adr`. Collect the title, context, decision, alternatives, consequence and refs
+   as free text, because these fields carry intent.
+2. Run `afm adr new <slug> --title "<title>" --description "<one sentence>"`, with `--supersedes N` when
+   the decision replaces ADR N.
+3. Fill the sections of the printed file with what the operator said, and leave the rest `[TBD]`. Report the
+   path (#6).
+
+The "Additional step in a refactored project" in the op applies ONLY when `afm-refactor` adopted the
+project (signal: `afm.md` § 3.1 forward-only exists). A greenfield project forbids a retroactive ADR.
+
+## Invariant principles
+
+Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. 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.

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

@@ -0,0 +1,36 @@
+---
+name: afm-analyze
+description: |
+  Cross-checks one feature against the instance. It compares `docs/features/NNN-*/{spec,plan,tasks}.md` with prd, ust, ach, afm § 3 and PRINCIPLES. It reports findings by severity in chat and writes no file.
+  Activates: `afm-analyze [<feature>]`, "audit feature", "check coverage", "validate consistency before implementation".
+---
+
+# AFM — Analyze
+
+> **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/analyze.md`, end to end, and follow it exactly.
+
+## When NOT to activate
+
+Use `afm-clarify` to resolve markers interactively. Use `afm-deliver` for end-to-end delivery: it runs analyze underneath, in gating mode. Use `afm-diagnose` for the health of the whole doc set.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `afm-init` or `afm-refactor`).
+
+## 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.
+
+## 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).
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only active auditing.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

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

@@ -0,0 +1,36 @@
+---
+name: afm-clarify
+description: |
+  Scans one feature for ambiguity. It asks the irreducible questions, recommendation first, and writes the answers to `spec.md § 7 Clarifications`.
+  Activates: `afm-clarify [<feature>]`, "resolve markers", "clear up ambiguity in feature X", "clarify the spec".
+---
+
+# AFM — Clarify
+
+> **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.
+
+## When NOT to activate
+
+Use `afm-analyze` for a read-only, multi-artifact validation that does not resolve markers. Use `afm-deliver` for end-to-end delivery: it calls clarify underneath when needed.
+
+## Pre-check
+
+Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `afm-init` or `afm-refactor`). `afm feature status <NNN> --json` lists the open markers of a feature in `blockers`.
+
+## Procedure
+
+Judgment only: a 9-category scan of the spec, a prioritized queue (at most 5 questions), auto-resolution from the code and docs before any question, then one recommendation-first question per turn. The questions come from the spec, so they are dynamic; the one fixed decision (`underspecified`) is in `afm ask clarify`. Integrate each answer into `spec.md` at once, remove the marker, and finish with the coverage summary.
+
+## 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.
+
+## Continuous doctrine
+
+Passive mode is the always-on `reconcile` skill. This skill covers only the active resolution of ambiguity.
+
+## Version
+
+`afm version`. History: `afm path CHANGELOG.md`.

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

@@ -0,0 +1,44 @@
+---
+name: afm-deliver
+description: |
+  Delivers one feature from discovery to reconciliation. It takes one recorded approval (`afm approve`), writes spec, plan and tasks, then runs each task as RED, GREEN, REFACTOR, COMMIT. It resumes from the correct phase when those files exist. Orchestrator: it composes specify, plan, tasks, clarify, analyze and reconcile. External research is not an AFM op; it routes to nasca.
+  Activates: `afm-deliver [<feature>]`, "build feature X", "implement X end to end", "the tasks already exist, run them", "continue the delivery of feature N".
+---
+
+# 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.
+
+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.
+
+## When NOT to activate
+
+An isolated step ("just open the spec", "just generate the tasks") is the matching atomic skill. A trivial change goes straight to the `afm.md § 2` loop.
+
+## Pre-check
+
+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
+
+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).
+
+## 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
+
+`afm version`. History: `afm path CHANGELOG.md`.

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

@@ -0,0 +1,50 @@
+---
+name: afm-diagnose
+description: |
+  Scans the health of the local docs on 7 axes. The axes are dead reference, stale marker, instance-to-plugin drift, broken ADR chain, dead rule trigger, inflation or orphan, and cross-doc contradiction. It reads only `<consumer>/docs/` and returns evidence as `command + file:line`. It proposes no edit.
+  Activates: `afm-diagnose`, "diagnose the methodology", "what is broken in the docs?", "run the AFM health check".
+---
+
+
+# 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.
+
+> **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.
+
+## When NOT to activate
+
+This section disambiguates for a skill that already activated. It does not define activation, so it stays in the body, not in the resident listing.
+
+Validation of ONE feature is `afm-analyze`. Behavioral friction, where a doc misguided the agent at apply time, is `afm-reflect`. Proposing or applying a fix is `afm-evolve` (the full cycle, which includes diagnose).
+
+## 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.
+
+## 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>".
+
+**Phase 1 — Diagnosis** has the ANALYZER role. **It must not propose an edit.** The signature is φ = `(symptom, causal-status-of-behavior, mechanism)`.
+
+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.
+
+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).
+
+**No new principle here.** `diagnose` is a composed materialization. The doctrine lives in the op file.
+
+## Version
+
+Content version: `afm version` prints it.

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

@@ -0,0 +1,69 @@
+---
+name: afm-evolve
+description: |
+  Runs the full self-evolution cycle over `<consumer>/docs/`. It combines diagnose and reflect, adds generalize, restructure, update and remediate on demand, and delivers one package through one gate (`afm ask evolve`). It conducts the mechanisms and never touches the plugin.
+  Activates: `afm-evolve`, "audit the methodology", "the docs are a mess", "the rules no longer trigger", "clean up the docs", "reorganize the docs".
+---
+
+
+# AFM — Evolve (orchestrator for the self-evolution cycle)
+
+> **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 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.
+
+## When NOT to activate
+
+This section helps someone who already activated the skill decide if it fits. It is not an activation trigger, so it stays in the body, not in the resident listing.
+
+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 feature-level check is `afm-analyze` or `afm-deliver`. Recording a finding for the plugin is `afm-promote`.
+
+## 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. **Does `afm evolve gate-check` allow a cycle?** Pass `--symptom "<what the user said>"` when there is one. Exit 0 runs; exit 1 is the cooldown refusing (no new signal inside the window), so say so and stop; 3 and 4 mean not a project or undecided.
+
+## 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.
+
+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.
+
+#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.
+
+## 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
+
+Content version: `afm version` prints it.