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

package/content/templates/protocols/p3.md

@@ -0,0 +1,47 @@
+---
+type: protocol
+description: 'Template rendered during materialization: P3 — Planned Autonomous Delivery.'
+load: cold
+---
+
+# P3 — Planned Autonomous Delivery
+
+> the middle ground — P2 quality with P1 interaction. You plan together. The agent executes alone.
+
+| Field | Phase 1 (planning) | Phase 2 (execution) |
+| --- | --- | --- |
+| posture | `assisted` | `auto` |
+| `RETRY_CAP` | 2 | 2 |
+| `ROUND_CAP` | 2 | **0** |
+| `HALT_PER_PHASE` | — | off |
+| `SUPPRESS_SUBGATES` | off | on |
+| `delegation` | read-only | full |
+| `MAX_PARALLEL_SUBAGENTS` | **6** | 4 |
+
+**Transition gate — the only gate. The criterion is mechanical.** `plan.md` and `tasks.md` have no **open** `[NEEDS CLARIFICATION:]` marker. `grep` returns 0 or 1. This is not a judgment call about plan quality.
+
+The command is:
+
+```sh
+sed 's/`[^`]*`//g' plan.md tasks.md | grep -c '\[NEEDS CLARIFICATION:'
+```
+
+The `sed` step is load-bearing. Without it, the gate is **vacuously red**. A plan that *mentions* the marker inside backticks — describing the gate itself, or citing an example — fails itself. This happened in delivery 001 of this repo, where the only "hit" was the line that documented the gate. A gate that fails because it talks about itself is as useless as a gate that passes without looking. Both teach the operator to ignore it.
+
+**Why phase 2 can be autonomous:** every unknown was already decided in phase 1, and every critical point was already resolved. Execution is predictable and known. `ROUND_CAP = 0` in phase 2 makes this concrete. If something **outside the plan** appears, there is no question budget left. That case falls to the `deliver` stop table (rule 11, bright line, failure beyond `RETRY_CAP`), which escalates on external signal, not on confidence.
+
+**Cadence (large initiative):** run `reflect` every 3-4 tasks. When you close the deliverable, run a general `reflect`, then `evolve`.
+
+## The native Plan Mode is the mechanism, not the analogy
+
+P3 **is** the shape of Claude Code's plan mode: assisted planning. Approval offers *"Yes, and use auto mode"* — a gate that transitions to autonomous execution. From v3.5.0 onward, this is not a comparison. It is the executed path.
+
+| Moment | Mechanism |
+| --- | --- |
+| Enter phase 1 | `EnterPlanMode` |
+| Transition gate | the `grep` 0/1 check above, over `plan.md`/`tasks.md` |
+| Exit to phase 2 | `afm approve <feature>` on the consolidated plan — the recorded approval (sha256 of the plan) **is** the gate |
+
+**Declared degradation.** If the harness has no native plan approval, P3 **does not stop**. It falls back to the path already described in `ops/deliver.md` Phase 1 (chat summary + one recommendation-first `afm ask deliver`). The transition criterion is the same `grep` check in both paths. The native mode changes the **approval surface**, never the criterion. A gate whose criterion depended on the mode being on would be posture, not mechanism.
+
+**What the native mode buys you.** Phase 1 becomes read-only by construction of the harness, not by a promise from the model. `delegation: read-only` in phase 1 stops being cooperative prose and becomes a floor imposed from outside — exactly the "hard vs. soft" distinction in `core/protocol.md § 6`.

package/content/templates/research.template.md

@@ -0,0 +1,50 @@
+---
+type: template
+description: 'Template rendered during materialization: Research — {{topic or area}}.'
+load: cold
+renders_to: 'docs/research/*.md'
+frontmatter_for_output: |
+  type: research
+  description: '<one sentence: the question this research answers>'
+  load: cold
+  fires_on: op-call            # a human never fires research directly — an op reads it to decide
+  fires_when: '<the question it answers, in one line — the sentence the body already states>'
+  date: 'YYYY-MM-DD'
+  context: 'free context: before bootstrap, during refactor, decide auth library'
+  status: draft | reviewed | applied
+  consumed_by: ADR-NNNN          # ONLY once an ADR or feature used it: omit the key while `status: draft`
+                                 # and add it in the same edit that moves status to `applied`
+                                 # — a consumed dossier is not re-read.
+---
+
+# Research — {{topic or area}}
+
+<!-- guidance -->
+{{Repeat the block below for each investigated topic.}}
+<!-- /guidance -->
+
+## {{topic 1 — concrete question}}
+
+**Decision (proposed):** {{X}}
+
+**Rationale:**
+- {{bullet 1 with concrete evidence}}
+- {{bullet 2}}
+- {{bullet 3}}
+
+**Alternatives considered:**
+- **{{alt A}}** — rejected because {{concrete reason}}.
+- **{{alt B}}** — rejected because {{reason}}.
+
+**Sources:**
+- {{real URL or reference}}
+- {{real URL or reference}}
+
+---
+
+<!-- guidance -->
+*Global research (not tied to a feature) feeds future PRD/ACH decisions or cross-project ADRs. To incorporate it:*
+*1. Cite this research in any project doc that decides based on it (e.g. `prd.md` § 4 RFs, `ach.md` § 1 stack, a specific ADR).*
+*2. If it becomes a load-bearing decision, turn it into an ADR via `afm adr`.*
+*3. After you incorporate it, change this file's frontmatter `status` from `draft` to `applied`.*
+<!-- /guidance -->

package/content/templates/session-handoff.template.md

@@ -0,0 +1,58 @@
+---
+type: template
+description: 'Template rendered during materialization: Session {{YYYY-MM-DD-HHMM}} — {{name}}.'
+load: cold
+renders_to: 'the session record in the state store'
+frontmatter_for_output: |
+  type: session
+  description: 'Session {{YYYY-MM-DD-HHMM}} — {{name}}.'
+  load: cold
+  tier: dual
+  state: open
+  name: '{{human label — mechanical default = dominant subtree in files_touched; reflect refines it}}'
+  date: '{{YYYY-MM-DD}}'
+  claude_session_id: '{{FULL session id — pointer to the harness transcript}}'
+  cwd: '{{absolute path of the consumer project}}'
+  created_at: '{{ISO-8601 UTC}}'
+  reflection: '{{link to docs/evolution/<date>-NNN.md — what reflect found AND fixed in the local docs}}'
+---
+
+# Session {{YYYY-MM-DD-HHMM}} — {{name}}
+
+<!-- guidance -->
+> **Two tiers in the same file** (v4/F9). The **handoff** block (`state`, `open_questions`, `next_steps`) is episodic and single-use. `state: open|consumed` governs **only this block**. The `reconcile` op consumes it. The rest is **durable telemetry**. It survives, it is versioned, and a plugin-repo agent reads it to improve AFM from real usage. It stays **outside** the `diagnose` A1–A7 axes. It is not a normative doc.
+>
+> **Two writers.** The `afm-session-end.sh` hook (`Stop`, 0-LLM) writes the skeleton and the mechanical fields for a session with work (non-empty `git diff`). `afm reflect` (§ 5.1) fills in the fields that need judgment: `name`, the two timeline sections, `afm_findings`, and `reflection:`. **A session without a `reflect` run keeps only the skeleton.** This is acceptable, not a defect.
+>
+> **File name ≠ `name:`.** The file is `<date>-<sid6>.md` (stable identity, dedup key, target of links already emitted). `name:` is a label and can be rewritten.
+>
+> ⚠️ **Hard rule 13 covers this directory.** The narrative cites commands. A command with a key inside becomes a versioned secret. Write the narrative with the secret removed.
+<!-- /guidance -->
+
+## files_touched
+
+  - {{`git diff --name-only HEAD`}}
+
+## summary (events in this session)
+
+  - {{titles of the `s=<sid>` events for this session in the event ledger (the state store)}}
+
+## what was asked
+
+  - {{reflect — what the agent UNDERSTOOD from the user's request, including where the reading changed midway. Interpretation, not transcription.}}
+
+## how it was executed
+
+  - {{reflect — how AFM was used: ops run, rules that fired, where the harness helped and where it got in the way. No other artifact holds this data.}}
+
+## afm_findings
+
+  - {{reflect/promote — what generalizes to the PLUGIN, in the format of `ops/promote.md` step 4 (title · `target:` · `evidence:` · `origin:` · why). An explicit empty result is valid.}}
+
+## open_questions
+
+  - {{what stayed open — session state, not the same as a spec `[NEEDS CLARIFICATION:]`}}
+
+## next_steps
+
+  - {{concrete next step / `T0NN` — points to tasks, does not change spec/plan/tasks}}

package/content/templates/us.template.md

@@ -0,0 +1,39 @@
+---
+type: template
+description: 'Template rendered during materialization: .'
+load: cold
+renders_to: 'docs/ust.md'
+---
+
+### US-NNN — {{objective title, "[Persona] [verb] [outcome]"}}
+
+- **Persona:** {{who, from PRD §3}}.
+- **Pain:** {{1 sentence on the current workaround}}.
+- **Story:** As {{persona}}, I want {{action}} to get {{measurable outcome}}.
+
+**Acceptance criteria:**
+
+```gherkin
+Scenario: {{happy path scenario name}}
+  Given {{precondition}}
+  And {{extra precondition, if any}}
+  When {{user action}}
+  Then {{expected observable result}}
+  And {{verifiable side effect}}
+```
+
+```gherkin
+Scenario: {{most likely error scenario}}
+  Given {{precondition}}
+  When {{user action in an invalid state}}
+  Then {{expected error, typed classification}}
+  And {{no DB side effect}}
+```
+
+**Metadata:**
+- **Priority:** P0 | P1 | P2
+- **Status:** draft | ready | in_progress | done | cancelled
+- **RF:** RF-NN
+- **RNF:** RNF-NN (if applicable)
+- **Success metric:** {{how to measure that the job was done}}
+- **Dependencies:** US-NNN, US-NNN (if any)

package/content/tools/gate/core-rules/PLUGIN-13-secrets.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Hard rule 13 — a token or a secret never leaks, the docs/sessions/ narrative included.
+# It is a gate because it is the cheapest error to make (the agent quotes the command it ran,
+# and the command carried the key) and the most expensive to undo: a committed secret is a
+# rotated secret.
+set -u
+MODE="${1:-staged}"
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+RC=0
+
+# A secret in the ADDED lines. The awk tracks the current `+++ b/<file>` because "diff:7"
+# locates no leak at all — and locating it fast is the point: a committed secret is a rotated
+# secret, and the rotation starts by knowing which file to open.
+scan() {
+  scope_diff "$MODE" | awk -v pat="$1" -v msg="$2" '
+    /^\+\+\+ b\// { f = substr($0, 7); next }
+    /^\+/ && $0 ~ pat { printf "13\t%s\t%s\n", (f == "" ? "(index)" : f), msg }
+  '
+}
+
+OUT="$(scan "(token|secret|api[_-]?key|password|bearer)[[:space:]]*[:=][[:space:]]*[\"'"'"'][^\"'"'"']+" "key/value pair with a plaintext secret")
+$(scan "(sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|AIza[A-Za-z0-9_-]{30,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{20,}[.])" "token in a recognizable format (sk-/ghp_/AIza/xox/JWT)")"
+if printf '%s' "$OUT" | grep -q .; then
+  printf '%s\n' "$OUT" | grep -v '^$'
+  RC=1
+fi
+
+# A versioned .env. `.env.example` is legitimate and stays out.
+while IFS= read -r f; do
+  case "$f" in *.env.example|*.env.sample) continue ;; esac
+  printf '13\t%s\ta .env file must not be versioned\n' "$f"
+  RC=1
+done < <(scope_files "$MODE" | grep -E '(^|/)\.env')
+
+exit $RC

package/content/tools/gate/core-rules/PLUGIN-21-code-language.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Hard rule 21 (INALIENABLE) — code and tests are written in English.
+# The trigger covers an identifier and a test name with a non-ASCII character. It does NOT
+# cover unaccented Portuguese (an identifier without a diacritic passes) and it does not cover
+# a comment — English prose uses em dashes and curly quotes, so non-ASCII inside a comment is
+# noise, not signal. Since 3.9.0-rc.1 the comment is covered from the other side, by density,
+# in `tools/afm-lang.sh`.
+set -u
+MODE="${1:-staged}"; : "$MODE"   # COUNTING rule: the scope is the whole repo (see the gate lib scope.sh)
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+
+# `grep -P` is GNU. Without it the runner does NOT decide — and an abstention never becomes a
+# failure, or the first machine without GNU grep turns the gate into a permanent block.
+echo x | grep -qP 'x' 2>/dev/null || exit 2
+
+RC=0
+PAT='\b(?:function|class|const|let|var|def|interface|type|enum|describe|it|test)\b\s*\(?\s*["\x27]?[A-Za-z_$][\w$ ]*[^\x00-\x7F]'
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  while IFS=: read -r n _; do
+    printf '21\t%s:%s\tidentifier or test name with a non-ASCII character\n' "$f" "$n"
+    RC=1
+  done < <(grep -nP "$PAT" "$REPO/$f" 2>/dev/null)
+done < <(scope_all 'plugins/*/mcp/src/*')
+
+exit $RC

package/content/tools/gate/core-rules/PLUGIN-35-gate-complete.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Hard rule 35 — a rule with a 0/1 trigger has a versioned runner and sits in the gate.
+# It is the rule that stops the gate from rotting: without it, someone adds a rule with a
+# verification written in prose and the document goes back to promising what nobody runs.
+set -u
+: "${1:-staged}"   # the rule is about the STRUCTURE of the gate, not about the diff
+# The aggregator ships BESIDE this runner, in the plugin and in a materialized `docs/tools/gate/`
+# alike, so `$0` resolves it in both. Until 3.20.0 this line read `$REPO/test/guardrails.sh` —
+# one repository's path, hardcoded in a file meant to travel.
+GATE="$(cd "$(dirname "$0")/.." && pwd)/guardrails.sh"
+[ -x "$GATE" ] || { printf 'PLUGIN-35\tdocs/afm.md\tthe aggregator is not beside this runner at %s\n' "$GATE"; exit 2; }
+
+OUT="$("$GATE" --repo "${AFM_GATE_REPO:-$PWD}" --audit 2>&1)"; RC=$?
+[ "$RC" = 0 ] && exit 0
+
+printf '%s\n' "$OUT" | grep -E '^  FAIL' | sed 's/^  FAIL — //' | while IFS= read -r l; do
+  printf 'PLUGIN-35\tdocs/afm.md\t%s\n' "$l"
+done
+exit 1

package/content/tools/gate/core-rules/PLUGIN-36-absolute-path.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Hard rule 36 — a doc under docs/ carries no absolute path.
+# A runbook holding a home directory of one user runs only on the machine of whoever wrote it,
+# and the agent that reads it in a different clone either obeys the wrong path or hallucinates
+# the correction. A relative path is what makes the markdown executable in any checkout.
+#
+# TWO exclusions, both structural and not "convenience":
+#
+# 1. `docs/sessions/` — the `cwd: <path>` line is LOAD-BEARING: afm-session-start.sh matches
+#    the pending handoff with `grep -lF "cwd: $PWD"`. Without the absolute path the
+#    cross-session handoff stops finding the right session. The directory also grows one entry
+#    per session, so a ratchet (which only decreases) would be broken by design.
+#
+# 2. The pattern requires a segment AFTER the user name. Without that, a doc that *describes*
+#    the trigger — this one — would accuse itself, and a rule that fails its own documentation
+#    is the first one to be turned off.
+set -u
+MODE="${1:-staged}"; : "$MODE"   # COUNTING rule: the scope is the whole repo (see the gate lib scope.sh)
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+RC=0
+
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  while IFS=: read -r n _; do
+    printf '36\t%s:%s\tabsolute path in a doc (use a path relative to the repo root)\n' "$f" "$n"
+    RC=1
+  done < <(grep -nE '(^|[^A-Za-z0-9_])(/home/[A-Za-z0-9._-]+/|/Users/[A-Za-z0-9._-]+/|[A-Z]:\\\\[A-Za-z0-9._-]+)' "$REPO/$f")
+# Three exclusions, and all three are the same reason: a MACHINE-WRITTEN, append-only record
+# whose content is evidence. `docs/sessions/` was excluded from the start. The other two were
+# missed, and `.afm-log-failures/` proved it on 2026-09-03: the CRITIC hook recorded a failing
+# command verbatim — which is the point of the record — and this rule then failed the tree over
+# the absolute path inside that command. Rewriting the record to satisfy the rule would destroy
+# the evidence the record exists to hold, and rules 17/18 forbid rewriting either substrate.
+done < <(scope_all 'docs/*.md' 'docs/**/*.md' \
+  | grep -vE '^docs/(sessions|\.afm-log|\.afm-log-failures)/')
+
+exit $RC

package/content/tools/gate/core-rules/PLUGIN-37-prose-language.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Hard rule 37 — the prose of an artifact is English.
+#
+# It complements rule 21, which covers only an IDENTIFIER and a TEST NAME carrying a
+# non-ASCII character. Rule 21 is blind to prose: a `.md` written entirely in Portuguese
+# passes it clean, and that is exactly how this repo reached 2026-08 with 175 Portuguese
+# doc files while the gate reported green.
+#
+# The measurement itself lives in `framework-template/tools/afm-lang.sh` and NOT here.
+# Rule 34: one canonical source. The same threshold has to decide at `PreToolUse`, where
+# the text is still a proposal, and at commit, where it is already a fact — two copies of
+# a measured threshold drift apart in silence, and the commit gate would then contradict
+# the hook that had just approved the write.
+set -u
+MODE="${1:-staged}"; : "$MODE"   # COUNTING rule: the scope is the whole repo
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+. "${AFM_GATE_LIB:?}/ratchet.sh"
+
+# Resolved through $0, not $REPO (see README "Resolve a sibling tool through $0"): the tool
+# ships beside this directory both in the plugin (framework-template/tools/, two levels up from
+# tools/gate/core-rules/) and in a materialized consumer (docs/tools/, same two levels up from
+# docs/tools/gate/core-rules/). $REPO/plugins/afm/framework-template/tools/afm-lang.sh only
+# exists when this very repository is being dogfooded through ./test/ — in a project bootstrapped
+# by afm init it never exists, so this used to report "missing" against a tool that was right
+# there at docs/tools/afm-lang.sh.
+LANG_TOOL="$(dirname "$0")/../../afm-lang.sh"
+if [ ! -x "$LANG_TOOL" ]; then
+  printf 'PLUGIN-37\t%s\tthe language tool is missing or not executable — rule 37 cannot be decided\n' \
+    "$LANG_TOOL"
+  exit 1
+fi
+
+RC=0
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  # Exemptions live in the ratchet, never in this file. A `case` arm naming a path is an
+  # exclusion that only one repository can have, invisible to any reviewer who does not read
+  # the runner. See `ratchet_exempt` in `lib/ratchet.sh`.
+  ratchet_exempt PLUGIN-37 "$f" && continue
+  # An archived CHANGELOG is a frozen historical record everywhere, not a per-project choice,
+  # so it stays in code: it is a SHAPE, not a path.
+  case "$f" in */CHANGELOG-archive.md) continue ;; esac
+  D="$("$LANG_TOOL" --density "$REPO/$f" 2>/dev/null)" || continue
+  # Exit 1 is the accusation; exit 2 is "too short to be a ratio" and has to read as a pass.
+  # Collapsing the two reported 83 extra files on the first run of this delegation — every
+  # short eval fixture — because `if ! cmd` cannot tell an accusation from an abstention.
+  "$LANG_TOOL" --verdict --path "$f" "$REPO/$f" >/dev/null 2>&1; V=$?
+  if [ "$V" -eq 1 ]; then
+    printf '37\t%s\tPortuguese prose (density %s, %s hits in %s words)\n' \
+      "$f" "$(printf '%s' "$D" | cut -f3)" "$(printf '%s' "$D" | cut -f2)" "$(printf '%s' "$D" | cut -f1)"
+    RC=1
+  fi
+done < <(scope_all '*.md')
+
+exit $RC

package/content/tools/gate/core-rules/PLUGIN-38-parser-marker.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Hard rule 38 — a Portuguese literal inside a script or inside a quoted marker.
+#
+# Why it exists: "the data was translated and the parser was not" was the MOST FREQUENT failure
+# of the english-first migration, and NONE of the occurrences was caught by a gate. Three of
+# them killed a mechanism in silence:
+#
+#   - afm-health.sh matched the Portuguese "superseded by ADR-" heading while the ADRs said
+#     something else, so vital sign A4 (broken ADR chain) found zero, always.
+#   - ops/restructure.md read the Portuguese bite and last-bite fields while the template wrote
+#     `Bites:`/`last:`, so the dead-gotcha prune never found anything.
+#   - guardrails/README.md documented the Portuguese key names while the files used `signal:`
+#     and `trigger:`, so a new guardrail would be born invisible.
+#
+# The symptom never varies: the literal stays Portuguese and the target has already changed.
+# Because the repo is english-first (rule 37), the HEURISTIC is cheap and precise — an accented
+# word inside a `.sh`, or inside backticks in a plugin `.md`, is a candidate. It does not prove
+# the drift; it points at where the drift lives. The human triages.
+#
+# It complements rule 37, which looks only at prose DENSITY in `.md` and is therefore blind both
+# to `.sh` and to an isolated literal inside an English doc.
+#
+# Since 2026-08-27 `test/` is NO LONGER exempt. It used to be, by an explicit decision that the
+# gates of this repo speak to the maintainer and are not distributed surface. Translating them
+# found three dead mechanisms this exemption had been hiding for months — rule 34's check (a),
+# the plugin-effect boundary in refs-lint, and the protocol assert in update-rehearsal — each one
+# a parser left on a spelling nothing produces any more. The exemption was protecting exactly the
+# files that most needed this rule.
+set -u
+MODE="${1:-staged}"; : "$MODE"   # COUNTING rule: the scope is the whole repo
+REPO="${AFM_GATE_REPO:-$PWD}"
+. "${AFM_GATE_LIB:?}/scope.sh"
+. "${AFM_GATE_LIB:?}/ratchet.sh"
+
+# LC_ALL=C: the [À-ÿ] range is INVALID outside a UTF-8 locale and makes grep abort.
+# The prototype of this runner swallowed that error with 2>/dev/null and reported "0 findings"
+# over a corpus with 6 known cases — a gate that swallows its own error is indistinguishable
+# from one that passed, which is exactly the bug hunted here.
+# Hence: an explicit alternation, no range, and the grep NEVER goes to /dev/null.
+export LC_ALL=C
+PT='ã|ç|õ|á|é|í|ó|ú|â|ê|ô|à|Ã|Ç|Õ|Á|É|Í|Ó|Ú|Â|Ê|Ô|À|ambos|planejada|gatilho|Gatilho'
+
+RC=0
+report() { printf '38\t%s\t%s\n' "$1" "$2"; RC=1; }
+
+# --- 1. shell: any accented word (a comment included: it is instruction) ------
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  # Exemptions live in the ratchet, never in this file. A `case` arm naming a path is an
+  # exclusion that only one repository can have, invisible to any reviewer who does not read
+  # the runner. See `ratchet_exempt` in `lib/ratchet.sh`.
+  ratchet_exempt PLUGIN-38 "$f" && continue
+  n=$(grep -cE "$PT" "$REPO/$f") || n=0
+  [ "$n" -gt 0 ] && report "$f" "${n} line(s) with a Portuguese literal in a script"
+done < <(scope_all '*.sh')
+
+# --- 2. plugin markdown: a backticked literal (marker candidate) -------------
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  # Exemptions live in the ratchet, never in this file. A `case` arm naming a path is an
+  # exclusion that only one repository can have, invisible to any reviewer who does not read
+  # the runner. See `ratchet_exempt` in `lib/ratchet.sh`.
+  ratchet_exempt PLUGIN-38 "$f" && continue
+  # These three are SHAPES that hold in any AFM instance, not paths one project happens to
+  # have, so they stay in code: a changelog is a historical record; `core/afm.md` quotes a
+  # Portuguese identifier as the example of what rule 21 forbids, and the example has to be
+  # wrong to be an example; `ops/deliver.md` lists the override phrases, which are USER SPEECH.
+  case "$f" in
+    *CHANGELOG.md|*CHANGELOG-archive.md) continue ;;
+    */core/afm.md|*/ops/deliver.md|*/ops/update.md) continue ;;
+  esac
+  # REAL backtick pairing: splitting on the backtick leaves the EVEN fields inside the code
+  # span. A naive grep for a backtick, anything, a Portuguese word, anything, a backtick also
+  # matches the SPACE BETWEEN two spans — that is how the first version reported a French loan
+  # phrase as a Portuguese marker.
+  n=$(awk -v pat="$PT" '
+        { k=split($0, S, "`"); for (i=2; i<=k; i+=2) if (S[i] ~ pat) c++ }
+        END { print c+0 }' "$REPO/$f")
+  [ "$n" -gt 0 ] && report "$f" "${n} backticked Portuguese literal(s)"
+done < <(scope_all 'plugins/*/**/*.md' 'plugins/*/*.md')
+
+exit $RC