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

package/content/templates/guardrail-runner.template.md

@@ -0,0 +1,97 @@
+---
+type: template
+description: 'Template rendered during materialization: Template — guardrail runner.'
+load: cold
+renders_to: 'docs/tools/gate/rules/*.sh'
+---
+
+# Template — guardrail runner
+
+<!-- guidance -->
+> Skeleton of the script that a guardrail of **`hard-rule` origin** runs. The consumer repo materializes it as `docs/tools/gate/rules/<NN>-<slug>.sh` (or the path the project already uses for gates).
+> **Two forms.** `afm rule new` writes a TypeScript skeleton (`<NN>-<slug>.ts`) by default and a bash one (`<NN>-<slug>.sh`) with `--runner sh`. Use TypeScript when the check is "files in a scope, a regex per line": no shell, no execute bit, and it runs on Windows. Use bash (or any executable) for a diff, a count against the ratchet, or another tool. Both obey the contract below.
+> **The runner is the only part you write.** Since 3.7.0-rc.1 the aggregator, its two libraries, the ratchet and the hook body arrive materialized in `docs/tools/gate/`. Before that they were described here and shipped nowhere, so a runner written from this template died at its own `source` line.
+<!-- /guidance -->
+
+## Contract
+
+```
+argv[1]          : "staged" | "worktree"
+env RATCHET      : path to the budget baseline (TSV: rule region count note)
+env AFM_GATE_LIB : directory holding scope.sh and ratchet.sh, exported by the aggregator
+
+stdout      : one line per finding — "<NN>\t<path>[:<line>]\t<short message>"
+exit 0      : compliant
+exit 1      : violation found
+exit 2      : COULD NOT decide (missing dependency, mode not applicable)
+```
+
+<!-- guidance -->
+**Exit 2 is mandatory. It is not decoration.** "Could not verify" must never become "failed". The first machine without the tool would turn the gate into a permanent block. A gate like that gets disabled, together with every other gate in the same aggregator.
+<!-- /guidance -->
+
+## The two classes — choose before you write
+
+| Class | Scope | Budget | Example |
+| --- | --- | --- | --- |
+| **Diff** | the index (what becomes the commit) | always 0 | plaintext secret, version bump, test that must run |
+| **Count** | the whole repo, **even in `--staged`** | ratchet, decreases only | path convention, identifier language, single source |
+
+<!-- guidance -->
+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 "did not grow" only if it measures the same total it recorded.
+<!-- /guidance -->
+
+## Skeleton: TypeScript (the default)
+
+`afm gate` runs the file in a child process (`afm gate ts-runner`) under the same timeout and exit contract. The default export is a function of the rule builder: it imports nothing.
+
+```ts
+export default ({ rule }) =>
+  rule("{{NN}}")
+    .in("{{glob}}")              // repeat .in to add globs
+    .except("{{glob}}")          // paths left out
+    .skipping(/{{comment}}/)     // a line that matches is ignored
+    .forbid(/{{pattern}}/, "{{message}}");   // or .require(/{{pattern}}/, "{{message}}")
+```
+
+The builder reports each match at its line and exits 0, 1 or 2 for you. Check it with `afm gate --dry-run --only {{NN}}`. Full API: `docs/tools/gate/rules/README.md`. The skeleton `afm rule new` writes throws until you replace it, so an unfinished rule exits 2 and never passes.
+
+## Skeleton: bash
+
+```bash
+#!/usr/bin/env bash
+# Hard rule {{NN}} — {{short statement}}.
+# Why a gate, not a paragraph: {{the mistake is cheap to make, expensive to review, and
+# the review that would catch it does not scale — it costs context every time the code is touched}}.
+set -u
+MODE="${1:-staged}"
+REPO="$(git rev-parse --show-toplevel)"
+# Resolve the library through the variable, never through a fixed path. The runner does not
+# know where the gate lives, which is what lets the same runner work in a project that keeps
+# it under `docs/tools/gate/` and in one that keeps it somewhere else.
+. "${AFM_GATE_LIB:?}/scope.sh"
+
+# Dependency guard — exit 2, never 1.
+# command -v {{tool}} >/dev/null 2>&1 || exit 2
+
+RC=0
+while IFS= read -r f; do
+  [ -f "$REPO/$f" ] || continue
+  while IFS=: read -r n _; do
+    printf '{{NN}}\t%s:%s\t{{message}}\n' "$f" "$n"
+    RC=1
+  done < <(grep -n '{{pattern}}' "$REPO/$f")
+done < <(scope_all '{{pathspec}}')   # scope_files "$MODE" ... for a DIFF rule
+
+exit $RC
+```
+
+## Before you call it done
+
+- [ ] Did the assertion **fail on the old code**? Before you accept it, run it against the code as it was before the fix (`git show HEAD:<file>`, or the parent commit). It MUST fail there. A regression test that passes on the old code proves nothing.
+- [ ] Does the command **distinguish** the violating case from the clean case? Test both. A gate that returns green without checking buys trust it cannot back up.
+- [ ] Is there a diff that **passes the trigger but violates the intent** of the rule? If yes, the rule is reward-hackable. Rewrite it, or demote it to a principle (`core/afm.md § 1.3`).
+- [ ] Does the runner fail **legitimate work** in any real case in the repo? Test this before you turn the gate on. Failing correct work is the shortest path to `--no-verify` becoming a habit.
+- [ ] Did you run `guardrails.sh --baseline` before turning the rule on? It records what HEAD already breaks as declared debt. **A gate that starts red is disabled the next day**, and it takes every other rule in the same aggregator with it.
+- [ ] Is the constant (threshold, prefix, directory list) **the operator's own**? Measure the repo and propose it together with the measurement (`ops/rule.md` 3.6). A "best practice" value set by the agent is the first thing to get turned off.
+- [ ] Was the ratchet's `count` **measured on HEAD** before you turned the gate on? A gate that starts red gets turned off the next day.

package/content/templates/guardrail.template.md

@@ -0,0 +1,63 @@
+---
+type: template
+description: 'Template rendered during materialization: Guardrail: {{title — what this gate blocks}}.'
+load: cold
+renders_to: 'docs/guardrails/*.md'
+frontmatter_for_output: |
+  type: guardrail
+  description: '<one sentence: what this gate blocks>'
+  load: warm
+  id: '<stable kebab-case slug>'
+  origin: recurring-failure | hard-rule
+  surface: pre-commit | ci | linter | type-check | script-local   # the chosen surface
+  trigger: '<the 0/1 command>'
+  cost: low | medium | high
+  signal: '<the concrete error people kept fixing by hand: import from billing into ui, a new case in the union broke nothing>'
+  installed_on: 'YYYY-MM-DD'   # omit the key while the guardrail is still a proposal
+---
+
+# Guardrail: {{title — what this gate blocks}}
+
+<!-- guidance -->
+> This is a **mechanical** gate. A 0/1 check runs it on its own. It needs no judgment and no one to remember it.
+> Family `docs/guardrails/` (v3.5.0+). One responsibility per file.
+<!-- /guidance -->
+
+**Two origins, one artifact** (the object is the same: a 0/1 check plus the burden of proof to refute it):
+
+| `origin:` | Where it comes from | Who proposes it |
+| --- | --- | --- |
+| `recurring-failure` | `sig=` recurred in the failure records (`afm failures promotable`) | `remediate.md` (CRITIC loop, `failure-classification.md` rubric — precedence destination) |
+| `hard-rule` | a hard rule already written in `afm.md § 3`, with a 0/1 trigger no one ran | `rule.md § Install the gate` |
+
+## Origin
+
+{{The failure record (sig=`<hash>`, recurred N times), "explicit user correction on <date>", OR, for `hard-rule`, the rule number and proof its trigger never ran. If the surface is a new tool, state its cost.}}
+
+## The trigger
+
+`{{comando}}` returns {{0 or nonzero}} when {{the condition}}.
+
+<!-- guidance -->
+This is the guardrail's whole contract. If the command cannot tell the violated case from the clean case, **the guardrail does not exist**. Measure it before you trust it. A gate that returns green without checking is worse than no gate. It buys trust it cannot back up.
+<!-- /guidance -->
+
+## Why mechanical, not documented
+
+{{Why a procedure or a learning was not enough here. Usually: the error is cheap to make, costly to review, and the review that would catch it does not scale. It spends context every time the code is touched.}}
+
+## Accepted cost
+
+{{What this gate charges: build time, a known false positive, ceremony on a legitimate change. An undeclared cost breeds resentment. The next agent then disables the gate without recording why.}}
+
+## What would refute this
+
+{{Mandatory. The conditions under which this guardrail stops making sense, and who carries the burden of proof to remove it.}}
+
+- {{condition 1 — e.g., "the project has only one package, so there is no boundary to cross without a graph"}}
+- {{condition 2 — e.g., "measured it, and the command misses the violation you actually have"}}
+- {{condition 3 — e.g., "the structure is still forming, so freezing it now rejects legitimate work"}}
+
+<!-- guidance -->
+> **Burden of proof.** Changing or removing this guardrail requires **refuting one of the conditions above with evidence**, not claiming that it got in the way. Friction is the gate's intended effect. Friction alone does not prove the gate is wrong. Same discipline as "a violated rule is not a wrong rule" (`ops/reflect.md § 2`).
+<!-- /guidance -->

package/content/templates/learning.template.md

@@ -0,0 +1,40 @@
+---
+type: template
+description: 'Template rendered during materialization: Learning: {{title — the lesson in one line}}.'
+load: cold
+renders_to: 'docs/learnings/*.md'
+frontmatter_for_output: |
+  type: learning
+  description: '<one sentence: the lesson, and the area it applies to>'
+  load: warm
+  fires_on: file-shape
+  trigger_path: 'the glob whose files this lesson applies to'
+  fires_when: 'if you edit <area or path>, read this file first'
+  origin: 'the failure record (sig=<hash>) or the explicit user correction that recognized the failure'
+  recognized_by: 'the external signal: a red test, tsc, a command returning non-zero, or a user correction'
+---
+
+# Learning: {{title — the lesson in one line}}
+
+<!-- guidance -->
+> This is an instructive file for **other Claude sessions** (and developers). It holds one **conceptual** lesson from a real failure.
+> This file belongs to the `docs/learnings/` family (v3.1.0+). It comes from the CRITIC loop (`remediate.md`) when the failure is conceptual or contextual. The value sits in the *cause*, not in a mechanical sequence of steps — that case belongs in a `procedure` instead. The hook `afm-pre-edit.sh` injects this file into future sessions by path match (see `trigger_path` and `fires_when` in the frontmatter). Keep one lesson per file.
+<!-- /guidance -->
+
+## What failed
+
+{{The concrete symptom, anchored in the external signal — the command that returned ≠0, or the user's correction. Do not write "I thought I failed". CRITIC requires recognition by tool, not self-judgment.}}
+
+## The lesson
+
+{{The conceptual root cause and what to do differently. This is reusable knowledge — the "why", not only the "what". If another Claude session, without this session's context, needs this fact to avoid repeating the failure, it belongs here (#1).}}
+
+## How to apply
+
+{{What the next agent must do when it touches the trigger area. Keep this concrete and actionable.}}
+
+---
+
+<!-- guidance -->
+> This file **does not become a hard rule** (it has no executable 0/1 trigger — a rule with a trigger belongs in `afm.md § 3`). It is **not a gotcha** either (a gotcha is an SDK or runtime surprise, a learning is a lesson from one's own failure). This file is injectable conceptual instruction. If the lesson later gains a mechanical trigger, promote it to a rule (`afm rule`). If 2 or more learnings converge on the same point, consider `afm generalize`.
+<!-- /guidance -->

package/content/templates/procedure.template.md

@@ -0,0 +1,47 @@
+---
+type: template
+description: 'Template rendered during materialization: Procedure: {{title — what this runbook does}}.'
+load: cold
+renders_to: 'docs/procedures/*.md'
+frontmatter_for_output: |
+  type: procedure
+  description: '<one sentence: what this runbook does>'
+  load: cold
+  fires_on: event | cadence
+  fires_when: 'the condition that starts this runbook, in one line: before cutting a release, when the build fails with X'
+  owner: 'who maintains this (optional, omit the key when nobody does)'
+  last_run: 'YYYY-MM-DD: update on each run (optional)'
+  origin: 'the failure record (sig=<hash>, recurred N times) or: operational sequence observed N times'
+---
+
+# Procedure: {{title — what this runbook does}}
+
+<!-- guidance -->
+> Repeatable runbook. A **mechanical** sequence of steps, each with a 0/1 check.
+> Family `docs/procedures/`, since v3.1.0. It starts from a mechanical failure that
+> recurred (CRITIC loop, `remediate.md`) OR from an operational sequence repeated
+> 2+ times (release, deploy, migration). One responsibility per file, 300 lines max.
+<!-- /guidance -->
+
+## Preconditions
+
+{{What must be true before you start. Reference `afm.md § 6.1` (pre-push) and current rules. Do not duplicate them — point to them.}}
+
+## Steps
+
+1. {{action}} — `{{command}}`
+   *Check:* `{{0/1 command}}` returns {{expected result}}.
+2. {{action}} — `{{command}}`
+   *Check:* `{{0/1 command}}` returns {{expected result}}.
+
+<!-- guidance -->
+> Each step has a **command** and a **0/1 check**. A step with no executable check is not a procedure. It is prose, so it becomes a `learning` instead.
+<!-- /guidance -->
+
+## Rollback
+
+{{How to undo safely if a step fails. Flag any irreversible external effect BEFORE the DB commit (saga ordering, `afm.md § 1.3`).}}
+
+## Known gotchas
+
+{{Links to the surprises in `docs/gotchas.md` that bite during this runbook. Do not copy them here — link to them.}}

package/content/templates/protocols/p1.md

@@ -0,0 +1,29 @@
+---
+type: protocol
+description: 'Template rendered during materialization: P1 — Autonomous Delivery.'
+load: cold
+---
+
+# P1 — Autonomous Delivery
+
+> POC and MVP work. Speed and no interaction matter more than depth.
+> **Granted per session, never by the repo** (`core/protocol.md` § 6).
+
+| Field | Value |
+| --- | --- |
+| `plan` | `auto` |
+| `exec` | `auto` |
+| `RETRY_CAP` | 2 |
+| `ROUND_CAP` | **0** |
+| `MAX_DISCOVERY_ROUNDS` | 2 |
+| `HALT_PER_PHASE` | off |
+| `SUPPRESS_SUBGATES` | on |
+| `UNKNOWN_POLICY` | `[ASSUMIDO: X — porque Y]` |
+| `delegation` | full |
+| `MAX_PARALLEL_SUBAGENTS` | 4 |
+
+**What "autonomous" does NOT mean here:** a hard rule with an executable trigger still stays 0/1. Safety posture stays non-negotiable (`afm.md § 1.3`). P1 relaxes **depth**: coverage, edge-case exhaustiveness, and name refinement.
+
+**How "no questions" works mechanically:** `ROUND_CAP = 0`. With no round available, every irreducible unknown falls to `UNKNOWN_POLICY`. It becomes an assumption **recorded in the artifact** — documented, never guessed in silence (principle #4).
+
+**Cadence:** run `reflect` after each deliverable. Run `evolve` every 3-4 deliverables.

package/content/templates/protocols/p2.md

@@ -0,0 +1,28 @@
+---
+type: protocol
+description: 'Template rendered during materialization: P2 — Assisted Delivery.'
+load: cold
+---
+
+# P2 — Assisted Delivery
+
+> pair programming. The human is the senior dev. The agent escalates early instead of continuing on a wrong path.
+
+| Field | Value |
+| --- | --- |
+| `plan` | `assisted` |
+| `exec` | `assisted` |
+| `RETRY_CAP` | **1** |
+| `ROUND_CAP` | 4 |
+| `MAX_DISCOVERY_ROUNDS` | 3 |
+| `HALT_PER_PHASE` | **on** |
+| `SUPPRESS_SUBGATES` | **off** |
+| `UNKNOWN_POLICY` | ask |
+| `delegation` | none |
+| `MAX_PARALLEL_SUBAGENTS` | **2** |
+
+**P2 is compositional, not introspective.** It does not mean "ask when unsure". Self-reported confidence is not a mechanical trigger (principle #3). CRITIC shows that self-critique without an external tool degrades quality. P2 sets exactly three existing knobs: suppression off, `RETRY_CAP=1` (the first red escalates), and per-phase halt.
+
+**Floor.** Below the feature-folder heuristic (`afm.md § 2.1`), the posture degrades to "report before you commit". Asking at every step of a trivial change adds noise. Noise makes people turn the protocol off, and that is worse than not having it.
+
+**Cadence:** run `reflect` after each deliverable. Run `evolve` every 3 to 4 deliverables.

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