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

package/content/tools/gate/core-rules/PLUGIN-39-frontmatter-ops.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+# Hard rule 39 — every op carries frontmatter, and what it declares is true.
+#
+# A gate, not a preference, because the failure is SILENT in the way that matters: the
+# index reads frontmatter and nothing else, so an op with none is simply invisible to it.
+# The agent asks "who writes spec.md", gets an answer that omits the file it needed, and
+# has no signal that anything was left out. Missing metadata does not look like an error.
+# It looks like a shorter list.
+#
+# A dangling `composes:` fails the same way from the other side — it names an op that no
+# longer exists, and the reader trusts it because the frontmatter is the cheap thing it
+# read INSTEAD of the body.
+set -u
+# COUNTING rule: the scope is the whole repository, not the diff. Rule 36 declares the same, for
+# the same reason — the question "is every indexed file readable" is about the TREE. A staged-only
+# answer would report a bundle as conformant because this commit happened not to touch the broken
+# file. The argument is accepted and deliberately unused.
+MODE="${1:-worktree}"; : "$MODE"
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+
+# Resolved through $0, not $REPO (see README "Resolve a sibling tool through $0"): this file
+# sits three levels below the source root both in the plugin (framework-template/tools/gate/
+# core-rules/) and in a materialized consumer (docs/tools/gate/core-rules/), so the same
+# expression reaches framework-template/ in one and docs/ in the other. $REPO/plugins/afm/
+# framework-template only exists when this very repository is being dogfooded through ./test/ —
+# never in a project bootstrapped by afm init. There $OPS never existed either way, but the old
+# `exit 2` short-circuited the WHOLE runner on that, so passes 1c/1d below — the ones that check
+# the consumer's own docs/ instance and need no $FT at all — silently never ran in any bootstrapped
+# project. Each $FT-dependent pass already guards its own directory with `[ -d ... ] || continue`,
+# so there is nothing left here to gate on.
+FT="$(cd "$(dirname "$0")/../../.." && pwd)"
+OPS="$FT/ops"
+
+# Every directory the index reads. Keep in sync with `INDEXED` in tools/afm-index.sh: a
+# directory the index reads but the gate does not check is a directory where frontmatter
+# can silently go missing, and missing frontmatter is invisible by construction.
+# `modules` (3.31.0) is the one entry whose unit is a DIRECTORY per stack, so the loop below
+# descends one level for it. Keep this list in sync with `INDEXED` in tools/afm-index.sh: a
+# directory the index reads and the gate does not check is a directory where frontmatter can
+# silently go missing, which is exactly how these 17 files shipped unindexed until now.
+#
+# `patterns` and `code-style` (3.40.0) are the two newest entries. `code-style/<stack>/` is
+# directory-unit like `modules`, and reaches the loop below the same way — its `*/*.md` glob
+# already covers a directory one level deep, `code-style/_any/` included. `patterns` is flat.
+# Neither adds new required keys here: `smell`, `when_to_use`, `when_not_to_use`, `stack`,
+# `concern` and `detect` all stay OPTIONAL, on purpose — requiring them would fail every
+# consumer pinned below 3.40.0 the moment this release reaches it.
+INDEXED="ops core rubrics templates templates/protocols interview modules patterns code-style"
+
+RC=0
+
+# Reads one frontmatter key. Same block definition the index uses: line 1 is `---`, the
+# block ends at the next `---`.
+fmkey() {
+  awk -v k="$2" '
+    NR == 1 { next }
+    /^---[[:space:]]*$/ { exit }
+    $0 ~ "^" k ":" { print; found = 1; exit }
+    END { exit !found }
+  ' "$1" 2>/dev/null
+}
+
+# Pass 0 — the frontmatter is PARSEABLE YAML with a non-empty `type`.
+#
+# This is clause 1 and clause 2 of OKF conformance (SPEC v0.2 11), and until 3.10.1 nothing
+# checked either one. The repository declared conformance in ADR 0018 and had 59 files that no
+# YAML parser could read: a `description: Session record: name` (a colon inside a plain scalar)
+# and a `trigger_grep: "awk.*\."` (a backslash escape inside a double-quoted scalar) both parse
+# fine to a grep and not at all to YAML.
+#
+# The whole point of a shared format is that a tool nobody here wrote can read the files. A
+# grep-based reader hides exactly this class of break, because grep never parses.
+#
+# python3 is the parser. When it is absent the check SKIPS AUDIBLY, the same discipline the
+# shellcheck skip follows: a silent skip is a gate that reports coverage it does not have.
+if command -v python3 >/dev/null 2>&1; then
+  YAML_OUT="$(python3 - "$REPO" <<'PYEOF' 2>/dev/null
+import sys, os, glob
+try:
+    import yaml
+except ImportError:
+    sys.exit(3)
+repo = sys.argv[1]
+roots = ["docs/**/*.md", "plugins/afm/framework-template/**/*.md"]
+for pat in roots:
+    for p in glob.glob(os.path.join(repo, pat), recursive=True):
+        if os.path.basename(p) in ("index.md", "log.md", "README.md"):
+            continue
+        s = open(p, encoding="utf-8", errors="replace").read()
+        if not s.startswith("---\n"):
+            continue
+        end = s.find("\n---", 4)
+        if end < 0:
+            print("%s\tfrontmatter block never closes" % os.path.relpath(p, repo)); continue
+        try:
+            d = yaml.safe_load(s[4:end])
+        except Exception as e:
+            print("%s\tfrontmatter is not parseable YAML: %s" % (os.path.relpath(p, repo), str(e).split("\n")[0][:90])); continue
+        if not isinstance(d, dict):
+            print("%s\tfrontmatter is not a mapping" % os.path.relpath(p, repo)); continue
+        if not d.get("type"):
+            print("%s\tno non-empty `type:` (OKF requires exactly this one key)" % os.path.relpath(p, repo))
+PYEOF
+)"
+  RCP=$?
+  if [ "$RCP" = 3 ]; then
+    # stderr, never stdout. The runner contract says one stdout line per FINDING, and the
+    # aggregator counts them — so a skip printed there is reported as a rule 39 violation on
+    # every machine without the module. An audible skip must be audible, not a false failure.
+    printf 'note: rule 39 pass 0 SKIPPED — python3 has no yaml module, OKF clause 1 unchecked\n' >&2
+  elif [ -n "$YAML_OUT" ]; then
+    printf '%s\n' "$YAML_OUT" | while IFS="$(printf '\t')" read -r f m; do
+      printf '39\t%s\t%s\n' "$f" "$m"
+    done
+    RC=1
+  fi
+else
+  printf 'note: rule 39 pass 0 SKIPPED — no python3, OKF clause 1 unchecked\n' >&2
+fi
+
+# Pass 1 — every indexed file carries the OKF profile contract.
+#
+# `type` is the one key OKF requires (SPEC v0.2 4.1). It replaced `kind`, which said the same
+# thing under a name no other tool knows. `description` is what the generated index prints
+# INSTEAD of opening the body, so a file without one costs a full read to answer "what is this".
+# `tier` is the AFM extension that tells the index what it may skip: a `cold` file is never
+# loaded at run time, and the index must not pay to open it.
+#
+# All three fail the same silent way. The index reads frontmatter and nothing else, so the file
+# is not reported as broken. It is simply absent from the answer.
+for d in $INDEXED; do
+  [ -d "$FT/$d" ] || continue
+  for f in "$FT/$d"/*.md "$FT/$d"/*/*.md; do
+    # `templates` and `templates/protocols` are BOTH in INDEXED, so the */*.md glob re-scans
+    # what the deeper entry already scanned. Harmless while the files conform; the day one
+    # loses `load:` the gate prints the same finding twice and reads as two defects.
+    _sub="$(dirname "${f#"$FT/"}")"
+    case " $INDEXED " in *" $_sub "*) [ "$_sub" = "$d" ] || continue ;; esac
+    [ -f "$f" ] || continue
+    case "$(basename "$f")" in README.md|index.md|log.md) continue ;; esac
+    rel="${f#"$REPO"/}"
+    if [ "$(head -n1 "$f")" != "---" ]; then
+      printf '39\t%s\tno frontmatter — invisible to the index\n' "$rel"
+      RC=1
+      continue
+    fi
+    if fmkey "$f" kind >/dev/null; then
+      printf '39\t%s\t`kind:` is the retired name — OKF requires `type:`\n' "$rel"
+      RC=1
+    fi
+    fmkey "$f" type >/dev/null || {
+      printf '39\t%s\tfrontmatter has no `type:` — the one key OKF requires\n' "$rel"; RC=1; }
+    fmkey "$f" description >/dev/null || {
+      printf '39\t%s\tno `description:` — the index would have to open the body\n' "$rel"; RC=1; }
+    load="$(fmkey "$f" load | sed 's/^load:[[:space:]]*//')"
+    case "$load" in
+      hot|warm|cold) ;;
+      "") printf '39\t%s\tno `load:` — the index cannot know what to skip\n' "$rel"; RC=1 ;;
+      *)  printf '39\t%s\t`load: %s` outside the closed vocabulary (hot|warm|cold)\n' "$rel" "$load"; RC=1 ;;
+    esac
+  done
+done
+
+# Pass 1b — a rubric declares HOW it fires and WHAT it says.
+#
+# Same failure as a missing `kind:`, one family over: `afm-index.sh --triggers` and
+# `afm-detect.sh` both read frontmatter and nothing else, so a rubric without `fires_on` is
+# invisible to the index and never fires at write time. The reader gets a shorter list and no
+# signal that anything was left out. A rubric that nothing can trigger is a document nobody
+# will ever be pointed at, which is the exact condition this whole line of releases exists to
+# remove.
+RUBRICS="$FT/rubrics"
+if [ -d "$RUBRICS" ]; then
+  for f in "$RUBRICS"/*.md; do
+    [ -f "$f" ] || continue
+    case "$(basename "$f")" in README.md|index.md|log.md) continue ;; esac
+    rel="${f#"$REPO"/}"
+    [ "$(head -n1 "$f")" = "---" ] || continue   # pass 1 already reported this
+    fo="$(fmkey "$f" fires_on)"
+    if [ -z "$fo" ]; then
+      printf '39\t%s\trubric with no `fires_on:` — invisible to the index and never fires\n' "$rel"
+      RC=1
+      continue
+    fi
+    case "$fo" in
+      *file-shape|*repo-shape|*op-call|*event|*cadence) ;;
+      *) printf '39\t%s\t`fires_on:` outside the closed vocabulary (file-shape|repo-shape|op-call|event|cadence)\n' "$rel"; RC=1 ;;
+    esac
+    fmkey "$f" fires_when >/dev/null || {
+      printf '39\t%s\trubric with no `fires_when:` — nothing to name when it fires\n' "$rel"; RC=1; }
+  done
+fi
+
+# Pass 1c — a procedure and a learning declare when they start.
+#
+# Not to make them FIRE — an `event` trigger cannot fire and is not supposed to. To make them
+# DISCOVERABLE: the condition that starts a runbook used to live in a `When to run it` bullet
+# inside the body, so answering "is there a runbook for this?" meant opening every file in the
+# family. One line in the index answers it instead. This repository reached 2026-08 with 26
+# gotchas and 3 procedures, and the family that nobody creates is the family nobody can find.
+#
+# An `event` or `cadence` entry must carry NO `trigger_*` key. Fabricating a mechanical field
+# for a human judgment is the failure this vocabulary exists to prevent: it would dilute the
+# confidence that rubrics and guardrails earned by being genuinely mechanical.
+for d in docs/procedures docs/learnings; do
+  [ -d "$REPO/$d" ] || continue
+  for f in "$REPO/$d"/*.md; do
+    [ -f "$f" ] || continue
+    case "$(basename "$f")" in README.md|index.md|log.md) continue ;; esac
+    rel="${f#"$REPO"/}"
+    if [ "$(head -n1 "$f")" != "---" ]; then
+      printf '39\t%s\tno frontmatter — invisible to the trigger index\n' "$rel"; RC=1; continue
+    fi
+    fo="$(fmkey "$f" fires_on)"
+    [ -n "$fo" ] || { printf '39\t%s\tno `fires_on:` — the index cannot say how this starts\n' "$rel"; RC=1; }
+    fmkey "$f" fires_when >/dev/null || {
+      printf '39\t%s\tno `fires_when:` — nothing to show in the index\n' "$rel"; RC=1; }
+    case "$fo" in
+      *event|*cadence)
+        if grep -qE '^trigger_' "$f"; then
+          printf '39\t%s\t`%s` declares a trigger_* key — a human-recognized moment has no mechanical trigger\n' "$rel" "$fo"
+          RC=1
+        fi ;;
+    esac
+  done
+done
+
+# Pass 1d — the INSTANCE families carry the same contract as the plugin ones.
+#
+# Since 3.9.1 a gotcha, a hard rule, an ADR and a rubric are all concept files with frontmatter.
+# The generated index reads `description` from them, so a file without one costs a full read to
+# answer "what is this", which is the exact cost this whole layer exists to remove. A feature,
+# an ADR, research, a protocol and an evolution report carry this SAME base contract — the NEW
+# routing keys each family gained (`status`, `for_paths`, `trigger_path`, `fires_on`, …) are
+# checked nowhere below, and that is deliberate: they are OPTIONAL, and requiring them here would
+# fail every consumer pinned at 3.6.0 or below the moment this release reaches them.
+#
+# `check_base_contract` is shared with Pass 1e below, because a feature folder needs the exact
+# same three checks one directory level deeper than a flat family — two copies of this body
+# would let a fix land in one and rot silently in the other.
+check_base_contract() {
+  f="$1"; rel="${f#"$REPO"/}"
+  if [ "$(head -n1 "$f")" != "---" ]; then
+    printf '39\t%s\tno frontmatter — invisible to the index\n' "$rel"; RC=1; return
+  fi
+  fmkey "$f" type >/dev/null || { printf '39\t%s\tno `type:`\n' "$rel"; RC=1; }
+  fmkey "$f" description >/dev/null || { printf '39\t%s\tno `description:`\n' "$rel"; RC=1; }
+  load="$(fmkey "$f" load | sed 's/^load:[[:space:]]*//')"
+  case "$load" in hot|warm|cold) ;; *) printf '39\t%s\t`load:` absent or outside hot|warm|cold\n' "$rel"; RC=1 ;; esac
+}
+
+for d in docs docs/gotchas docs/rules docs/adr docs/rubrics docs/guardrails docs/protocols \
+         docs/sessions docs/evolution docs/research docs/measurements \
+         docs/code-style docs/patterns; do
+  [ -d "$REPO/$d" ] || continue
+  for f in "$REPO/$d"/*.md; do
+    [ -f "$f" ] || continue
+    case "$(basename "$f")" in README.md|index.md|log.md) continue ;; esac
+    check_base_contract "$f"
+  done
+done
+
+# Pass 1e — a feature folder carries the same base contract, one level deeper than every other
+# instance family. `docs/features/NNN-slug/{spec,plan,tasks}.md` is the one shape Pass 1d's flat
+# `*.md` glob cannot reach — a feature's three files sit inside their own folder. Skipping it
+# would leave every feature file invisible to the gate while `afm-index.sh --triggers` and
+# `--for` already read them, the exact silent gap this whole rule exists to close.
+if [ -d "$REPO/docs/features" ]; then
+  for f in "$REPO"/docs/features/*/*.md; do
+    [ -f "$f" ] || continue
+    case "$(basename "$f")" in README.md|index.md|log.md) continue ;; esac
+    check_base_contract "$f"
+  done
+fi
+
+# Pass 2 — an op declares more, and what it declares must be true.
+for f in "$OPS"/*.md; do
+  [ -f "$f" ] || continue
+  rel="${f#"$REPO"/}"
+  base="$(basename "$f" .md)"
+
+  [ "$(head -n1 "$f")" = "---" ] || continue
+
+  for key in writes composes; do
+    if ! fmkey "$f" "$key" >/dev/null; then
+      printf '39\t%s\tfrontmatter has no `%s:`\n' "$rel" "$key"
+      RC=1
+    fi
+  done
+
+  # A `composes:` entry naming an op that does not exist is worse than no entry: the
+  # reader trusts it precisely because it read the frontmatter instead of the body.
+  deps="$(fmkey "$f" composes | sed 's/^composes:[[:space:]]*//; s/^\[//; s/\]$//; s/"//g; s/,/ /g')"
+  for d in $deps; do
+    [ -n "$d" ] || continue
+    if [ ! -f "$OPS/$d.md" ]; then
+      printf '39\t%s\tcomposes `%s`, which is not an op\n' "$rel" "$d"
+      RC=1
+    fi
+    if [ "$d" = "$base" ]; then
+      printf '39\t%s\tcomposes itself\n' "$rel"
+      RC=1
+    fi
+  done
+done
+
+# Pass 4 — the generated indexes match the directories they describe.
+#
+# OKF endorses generating index.md (SPEC 8) and its conformance never checks an index against
+# its own directory (11 is structural only). That check is left to the producer, so it lives
+# here. A stale index is the worst kind of doc: it is the cheap thing a reader consults INSTEAD
+# of listing the directory, so when it lies the reader never finds out.
+IDX="$FT/tools/afm-index.sh"
+if [ -x "$IDX" ] && [ -d "$REPO/docs" ]; then
+  OUT="$(cd "$REPO" && "$IDX" --check-index 2>/dev/null)"
+  if [ -n "$OUT" ]; then
+    printf '%s\n' "$OUT" | while IFS= read -r l; do
+      printf '39\t%s\tgenerated index is stale — run afm-index.sh --materialize\n' "${l#stale index: }"
+    done
+    RC=1
+  fi
+fi
+
+exit $RC

package/content/tools/gate/core-rules/PLUGIN-40-dead-reference.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Hard rule PLUGIN-40 — a doc under `docs/` cites no path that does not exist.
+#
+# Why it is a GATE and not prose. The lesson "a rename is finished when the WRITERS and the
+# READERS both move" was already written down, in `_focus.md` and in a gotcha, and on 2026-08-30
+# it failed twice inside the release that exists because of it: a runner glob kept matching only
+# the old name shape, and then seven rule files kept showing a label pointing at files that had
+# just moved. `afm-health.sh` DETECTED the second one and reported it at SessionStart — where it
+# was read and passed over. Detection at the start of a session is not the same as refusal at the
+# commit, and only one of the two arrives while the change is still in the hand of whoever made it.
+#
+# The check that makes this cheap to keep honest: a cited path resolves from the REPOSITORY ROOT
+# **or** from the directory of the file that cites it. Both conventions are alive in a real
+# instance, and a checker that knows only one invents findings — which is how a gate gets
+# switched off.
+set -u
+: "${1:-staged}"   # the rule is about the CONTENT of the docs, not about the diff
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+. "${AFM_GATE_LIB:?}/ratchet.sh"
+
+[ -d "$REPO/docs" ] || exit 0
+TRACKED="$(cd "$REPO" && git ls-files 2>/dev/null || true)"
+
+# The findings are collected, not streamed. Every loop below runs inside a pipeline subshell, so
+# a counter incremented in there dies with it — a runner that prints its findings and still exits
+# 0 is a verifier that reports and never refuses, which is the exact failure this rule is about.
+FOUND="$(
+while IFS= read -r f; do
+  # NORMATIVE families only. The scope is not "every doc" and that is deliberate: a rubric
+  # teaches with an ILLUSTRATIVE path (`src/lib/stripe/checkout.ts`), a research dossier quotes a
+  # hypothetical one, and a feature's `tasks.md` is a historical plan that names paths as they
+  # were on the day it was written. Pointing the gate at those produces 44 findings that are all
+  # correct notation, and a gate that starts red is switched off the next day — which would take
+  # every other rule in the same aggregator with it.
+  case "$f" in
+    docs/afm.md|docs/ach.md|docs/prd.md|docs/ust.md|docs/_focus.md) ;;
+    docs/adr/*|docs/rules/*|docs/gotchas/*|docs/learnings/*|docs/guardrails/*|docs/procedures/*) ;;
+    *) continue ;;
+  esac
+  [ -f "$REPO/$f" ] || continue
+  ratchet_exempt PLUGIN-40 "$f" && continue
+  dir="$(dirname "$f")"
+
+  while IFS= read -r line; do
+    # A line that ANNOUNCES a removal is a historical record, not a reference. An ADR's job is
+    # to cite what stopped existing.
+    printf '%s' "$line" | grep -qiE 'remov|deprecat|legacy|no longer|used to|until [0-9]' && continue
+    printf '%s\n' "$line" | grep -oE '`[A-Za-z0-9_./-]+\.[A-Za-z]+`' | tr -d '`' | while IFS= read -r p; do
+      case "$p" in
+        */*) ;;                 # only a PATH; a bare filename in prose is not a reference
+        *) continue ;;
+      esac
+      case "$p" in
+        http*|*..*) continue ;;
+        .*/*) continue ;;       # a dot-dir path is the notation for a materialized instance
+        /docs/*|/*) continue ;; # `/docs/x.md` is AFM notation for the consumer, not an absolute path
+        *.*.*/*) continue ;;    # a domain, not a path
+        *NNN*|*NN-*|*YYYY*|*MM.md|*'{{'*) continue ;;   # a placeholder shape, not a path
+        */_shared/*) continue ;;                        # a proposed layout, not one that exists
+      esac
+      [ -e "$REPO/$p" ] && continue          # from the repository root
+      [ -e "$REPO/$dir/$p" ] && continue     # from the citing file's own directory
+      esc="$(printf '%s' "$p" | sed 's/[.[*^$\\]/\\&/g')"
+      printf '%s\n' "$TRACKED" | grep -qE "(^|/)${esc}\$" && continue
+      printf 'PLUGIN-40\t%s\t%s does not exist, from the repository root or from %s/\n' "$f" "$p" "$dir"
+    done
+  done < "$REPO/$f"
+done < <(scope_all '*.md')
+)"
+
+[ -z "$FOUND" ] && exit 0
+printf '%s\n' "$FOUND"
+exit 1

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

@@ -0,0 +1,55 @@
+# Core rule runners — the ones the plugin ships
+
+Every runner here enforces a rule about **the `docs/` instance that AFM materializes**, never
+about a consumer's own code. That is why these travel and the ones in
+[`../rules/`](../rules/README.md) do not.
+
+| Runner | Rule |
+| --- | --- |
+| `PLUGIN-13-secrets.sh` | a token or a secret never leaks, the `docs/sessions/` narrative included |
+| `PLUGIN-21-code-language.sh` | INALIENABLE — code and tests are written in English |
+| `PLUGIN-35-gate-complete.sh` | a rule with a 0/1 trigger has a versioned runner in the gate |
+| `PLUGIN-36-absolute-path.sh` | a doc under `docs/` carries no filesystem absolute path |
+| `PLUGIN-37-prose-language.sh` | the prose of an artifact is English |
+| `PLUGIN-38-parser-marker.sh` | a Portuguese literal never survives in a script or a quoted marker |
+| `PLUGIN-39-frontmatter-ops.sh` | an indexed file carries the OKF contract |
+
+## The namespace
+
+The filename is `PLUGIN-<n>-<slug>.sh`, and `<n>` matches the `PLUGIN-<n>.` entry in
+`docs/afm.md § 3`. The aggregator reads the whole `PLUGIN-<n>` as the rule ID, and `--audit`
+cross-checks rule and runner in both directions inside each namespace.
+
+A project runner with the SAME number wins over the shipped one, so a consumer overrides a core
+rule by dropping `<n>-<slug>.sh` into `../rules/` — no fork of the plugin.
+
+## Exemptions go in the ratchet, never in the runner
+
+A runner here must not carry a `case ... continue ;;` arm that names a path. A path exists in one
+repository; a shipped runner runs in all of them. Write the exemption as a ratchet row instead:
+
+```
+rule	region	count	note
+PLUGIN-38	tools/lang-detector.sh	exempt	the accented alternation IS the detector
+```
+
+`exempt` is not a budget of zero. A budget says "this many violations are tolerated and the
+number may only fall"; an exemption says "this file is not what the rule is about". The ratchet
+also makes the exemption **visible**: it sits in a versioned table a reviewer reads, instead of
+inside code nobody re-opens.
+
+A **shape** that holds in every instance — an archived `CHANGELOG`, `core/afm.md` quoting a bad
+identifier as the example of what rule PLUGIN-21 forbids — stays in the runner. It is not a path.
+
+## Contract
+
+Identical to a project runner. See [`../rules/README.md`](../rules/README.md). Two additions,
+both learned the hard way on 2026-08-30:
+
+- **Never derive the repository from `$0`.** Every runner used to run
+  `REPO="$(cd "$(dirname "$0")/../.." && pwd)"`, which is only correct while the runner sits two
+  levels below the root. The moment one shipped — five levels down — that expression pointed at
+  `tools/`, and rule PLUGIN-37 reported "cannot be decided" against a file that was right there.
+  Read `AFM_GATE_REPO`, which the aggregator exports.
+- **Resolve a sibling tool through `$0`, not through a repository path.** The aggregator ships
+  beside this directory in the plugin and in a materialized `docs/tools/gate/` alike.