@groundnuty/macf 0.2.0-rc.1 → 0.2.1

package/plugin/rules/delegation-template.md

@@ -0,0 +1,250 @@
+# Delegation Template (canonical, shared)
+
+**This file is the single source of truth for how one agent delegates work to
+another.** It is copied into each agent workspace's `.claude/rules/` by
+`macf init` and refreshed by `macf update` / `macf rules refresh`. Do not edit
+workspace copies directly — edit the canonical file at
+`groundnuty/macf:packages/macf/plugin/rules/delegation-template.md` and re-run
+the distribution.
+
+Applies to any MACF agent that hands off a task to a peer — coordinators
+delegating to implementers, researchers delegating to reviewers, any agent
+splitting off scope. Works whether the peer is another bot or a human.
+
+---
+
+## When to delegate vs do the work yourself
+
+Delegation is for **asymmetric capability**, not ceremonial hand-off. Before
+filing a delegation issue, ask: is the peer agent actually better positioned
+to do this work than I am?
+
+**Delegate when:**
+
+- The peer has domain expertise the reporter lacks (framework TypeScript
+  internals → code-agent; LaTeX CV typesetting → cv-architect; historical
+  project research → cv-project-archaeologist)
+- The peer owns the repo / the canonical source (framework changes →
+  code-agent who owns `groundnuty/macf`)
+- The peer has persistent context the reporter doesn't (long-running
+  investigation, repository-specific conventions, team-facing
+  relationships)
+- The work would meaningfully benefit from review + merge discipline by a
+  non-author (even if the reporter could technically do the work, the
+  peer's second pair of eyes catches issues the author won't)
+
+**Do the work yourself (skip delegation) when:**
+
+- You have asymmetric context the peer would need to learn — delegation
+  becomes "please copy my notes into a file" rather than real work
+- You are the domain expert (rules about your own collaboration patterns,
+  a postmortem of an incident you lived, a DR for a design you drove)
+- The task is ceremonial packaging of material the reporter authored
+  anyway (the peer adds no value beyond typing)
+- The work is time-sensitive and the delegation round-trip would exceed
+  the fix window
+
+The test: if the peer's first action would be "ask the reporter for more
+context / source material", you're delegating ceremony, not real work —
+do it yourself. If the peer would immediately have everything they need
+to start, delegate.
+
+When you do the work yourself despite it being "in the peer's domain",
+note it explicitly — either in the PR body or a handoff comment:
+
+> "Authoring this directly rather than delegating to `<peer>` because the
+> content is distilled from my own collaboration-pattern observations —
+> `<peer>` would need me to write the text anyway. See
+> delegation-template.md 'When to delegate' for the principle."
+
+Transparency preserves the peer relationship: the peer sees the reasoning
+instead of feeling bypassed, and the coordinator can push back if they
+disagree with the self-authored call. Default to delegating when in
+doubt — the PR review step gives the peer their voice regardless.
+
+---
+
+## The 6-section issue template
+
+When you file a delegation issue for another agent, structure the body so the
+peer can start without coming back for clarification. Consistency matters more
+than any single section — the same headings in the same order make the body
+scannable and automation-friendly.
+
+```markdown
+## Context
+
+<What is this part of? Link to parent issue, design doc, DR. Why does this
+task exist? What problem is it solving?>
+
+## Goal
+
+<One-sentence statement of what success looks like. If you can't write it in
+one sentence, the task is too big — split first.>
+
+## Acceptance Criteria
+
+- [ ] <specific, testable, externally verifiable>
+- [ ] <specific, testable, externally verifiable>
+- [ ] <specific, testable, externally verifiable>
+
+## Dependencies
+
+- Depends on: #<N> (must be done first)
+- Blocks: #<M> (waiting on this)
+- (or "none" if truly standalone)
+
+## Pointers
+
+- Design ref: <path or link to the DR / spec / research doc>
+- Files to touch: <paths>
+- Existing patterns: <where to look in the codebase for reference>
+- Prior art: <similar work already done>
+
+## Notes
+
+<Gotchas, tradeoffs you considered, alternatives rejected. Research-refresher
+caveats — e.g., "your training data may be stale for library X; verify
+current docs before implementing.">
+
+---
+
+@<peer-agent>[bot] please take a look and ask if anything is unclear.
+```
+
+The assignee label (`code-agent`, `cv-architect`, etc.) goes on issue
+creation, not as the mention target — routing picks it up from the label.
+
+### Why a fixed template
+
+- **Predictability** — peer agents don't have to guess where the acceptance
+  criteria are
+- **Completeness check** — missing sections surface missing information at
+  write time, not implement time
+- **Parseability** — scripts, dashboards, and automation can reliably extract
+  fields
+
+Deviation from the template is allowed when the domain genuinely needs
+different structure — e.g., research-findings tasks may need "Project
+framing / Dates / Milestones / CV-angle hooks" instead of generic sections.
+Keep the *shape* (multiple level-2 or level-3 headings identifying distinct
+concerns); don't free-text a blob of requirements.
+
+---
+
+## Ask before filing
+
+Before creating the issue, confirm with the requester (usually the user, but
+it may be a coordinator peer):
+
+> **Route this now or backlog?**
+> 1. Now — peer agent picks it up immediately (applies assignee label, adds to board)
+> 2. Backlog — sits on the board for later, unassigned
+
+Getting this wrong creates noise: the assigned peer starts on something that
+isn't ready, or a backlog item sits unprocessed because no one noticed the
+label. Ask once; check the answer for each delegation.
+
+---
+
+## Labels on creation
+
+- **Assignee label** (`code-agent`, `science-agent`, `cv-architect`,
+  `writing-agent`, or whatever the target's routing label is) — the primary
+  routing signal
+- **Phase / area label** (`phase:P1`, `docs`, `research`, etc.) — optional
+  classification
+- **Type label** (`feat`, `fix`, `chore`, `docs`) — optional
+- **Priority label** (`priority:P0`, `priority:P1`, etc.) — optional
+
+Don't apply the assignee label in "Backlog" mode — routing picks up the label
+and wakes the peer. Use a separate `backlog` label if your project has one,
+or leave unassigned.
+
+---
+
+## After filing
+
+1. Post a brief comment on any related issue / PR linking the new delegation:
+   "Filed #<N> for this."
+2. Add to the project board if not auto-added.
+3. **Continue with other work — do not wait idle** for the peer to respond.
+   You will be @mentioned when it's your turn again.
+
+---
+
+## Receiving work back
+
+When the peer agent files a PR referencing your delegation issue:
+
+1. You are @mentioned — check out the PR branch, read the diff (and relevant
+   surrounding context, not just the diff lines).
+2. Review honestly. Spend enough time to be sure. A quick LGTM on substantive
+   work is worse than a thoughtful pushback.
+3. If **LGTM**: approve + @mention the peer that they can merge.
+4. If **changes needed**: list specifics (file:line references preferred),
+   @mention peer, explain *why* (not just "change X to Y" — the reasoning
+   matters for the peer to decide whether to push back or accept).
+5. **Do not merge yourself.** The implementer merges after your approval,
+   per coordination.md "merge-by-implementer" (they wrote the code; they
+   own the merge).
+
+After changes are pushed:
+
+6. Re-review the updated diff — not the whole PR again, just the delta.
+7. Either re-LGTM or list further concerns. @mention either way.
+
+---
+
+## Push-back acknowledgment
+
+If the peer pushes back on your issue body or your review:
+
+- Read their argument completely.
+- If they're right, say so, adjust the issue body / requirements / review
+  comments, and continue.
+- If you disagree, explain *why* in concrete terms — cite the relevant DR,
+  prior pattern in the codebase, or acceptance criteria. Abstract appeals
+  ("standard practice", "clean code") are not substantive; point at something
+  specific.
+- If after discussion you still disagree, escalate to the requester (usually
+  the user) rather than overriding. See `coordination.md` "Escalation".
+
+This is the peer dynamic — not "you file, I obey."
+
+---
+
+## When a PR is not needed
+
+Questions or discussions resolve in comments alone. The reporter closes the
+issue when done — no PR required. Use this for clarifications, status
+requests, or research-summary tasks where the output is the comment thread
+itself (rare; prefer a committed doc + PR for anything citeable).
+
+**Not "when you're in a hurry."** PR discipline (see `pr-discipline.md`) is
+the default for any work that produces an artifact.
+
+---
+
+## Stage-appropriate delegation
+
+| Stage | Routing mechanism | Can you delegate? |
+|---|---|---|
+| 0 | None (single agent) | No — you are the only agent; do the work yourself or defer |
+| 1 | None (bot identity but solo) | No — same as stage 0 but with bot attribution |
+| 2 | SSH + tmux routing | Yes — routing Action forwards issues / @mentions to peer |
+| 3 | MACF channels | Yes — HTTP POST to peer's channel server |
+
+Filing issues before routing is set up just piles them up unrouted. If the
+peer agent doesn't exist yet, ask whether to file anyway (for tracking) or
+defer until routing is online.
+
+---
+
+## When to modify this rule
+
+- **Read:** every session start. This rule defines how delegations look.
+- **Modify:** never directly in workspace copies. Edit the canonical file
+  and re-distribute via `macf update` in each affected workspace.
+- **Disagree with a rule?** Open an issue on `groundnuty/macf` proposing the
+  change, with rationale. Peer review applies.

package/plugin/rules/execute-on-directive.md

@@ -0,0 +1,71 @@
+# Execute on Directive
+
+**After a user directive like "go", "do X", "proceed", "approve", "ship it" — execute. Do not circle back to re-ask.**
+
+Pattern that causes friction: user gives a directive → you describe what you'd do → you ask "should I proceed?" → user repeats the directive → you execute. Three turns for what should be one turn.
+
+---
+
+## The rule
+
+When the user has clearly authorized the action — explicitly ("go", "do X", "proceed") or contextually ("here's the plan... okay, let's do it") — execute. The user's next message should be a response to the *result*, not a second authorization of the same thing.
+
+**Bad:**
+> User: run the tests
+> You: I'll run `make test` now. Should I proceed?
+> User: yes
+> You: [runs tests]
+
+**Good:**
+> User: run the tests
+> You: [runs tests] All 47 passing.
+
+**Good (when genuinely non-obvious):**
+> User: ship the observability stack
+> You: Two paths — (A) ship exactly what's in the research doc (Tier B), (B) the hybrid fallback (Langfuse-on-compose). I'd lean A. Which?
+> User: A
+> You: [ships Tier B]
+
+The second "Good" is NOT asking to proceed — it's surfacing a real branching decision. The directive is ambiguous between two paths, and picking one creates a different outcome. That's a legitimate clarifying question.
+
+---
+
+## When to ask vs. when to execute
+
+**Execute when:**
+- The directive names a specific action ("close the issue", "merge the PR", "run the spike")
+- You already laid out what you'd do and the user said a word-or-two approval ("go", "ok", "proceed", "yes", "ship it")
+- The action is reversible and bounded (local edit, `make check` run, filing one issue, reading a file)
+
+**Ask when:**
+- Genuinely multiple paths with materially different outcomes
+- Naming that matters (directory names, branch names, App names — hard to change later)
+- Destructive + irreversible operations (force-push, `rm -rf`, dropping a database, unpublishing an npm package, deleting a PR branch before merge-confirmation)
+- Scope ambiguity where wrong interpretation wastes hours (does "update the docs" mean just README, or all 15 files?)
+- Security / access-control consequences (installing a GitHub App, granting secrets access, opening a port)
+
+**The test:** if clarification would reveal a different action, ask. If clarification would return the same answer you already heard, execute.
+
+---
+
+## What slow-directive-execution looks like from the user's side
+
+The friction mode: user says "go", agent spends a turn restating the plan and asking "shall I?", user re-approves, agent finally runs. The restatement was free for the agent but costly for the user — it's another message to read, another turn to spend before seeing the result.
+
+Once the plan is agreed, the user wants the *output* of executing it, not a reminder of what the plan was.
+
+**Corollary:** after execution, lead with the result, not a recap of what you did. See `peer-dynamic.md` § "Response form" — skip restatement, skip trailing summaries.
+
+---
+
+## How this interacts with `pr-discipline.md` and `coordination.md`
+
+Those rules introduce structured decision points (ask-before-filing, reviewer-approval-before-merge, never-close-someone-else's-issue). Those are NOT "should I proceed?" moments — they're workflow-level gates that the user already endorsed by adopting MACF.
+
+This rule applies to the *micro* level: once a turn's work is approved, the micro-steps don't each need re-approval. Don't turn one directive into ten re-confirmations.
+
+---
+
+## Why this rule exists
+
+Agents that over-ask burn the user's attention on recaps they already wrote. The fix isn't being *less* careful — it's trusting the directive when it's already explicit. Save the clarifying-question budget for the cases that genuinely need it.

package/plugin/rules/gh-token-attribution-traps.md

@@ -0,0 +1,157 @@
+# gh-token attribution-trap failure modes
+
+**Six ways `gh` operations silently mis-attribute to the user account instead of the bot, and the patterns that prevent them.**
+
+When a bot agent runs `gh` commands, multiple silent failure modes cause ops to attribute to the user account instead of the bot. Because the content the agent posts is what it intended, mis-attribution is **invisible unless explicitly checked.** Past incidents:
+
+- Code-agent's merge-handoff comments posted under operator's account for an entire session — discovered only when cross-agent routing started failing
+- PR #16/#17 author mis-attribution surfaced during routine review (not by attribution itself)
+- 5+ recurring instances logged across science-agent + code-agent memory before this rule was canonicalized
+
+This is a **silent-fallback hazard class**: tool operations succeed at the API boundary, semantic-level failure (wrong identity / wrong scope / wrong target) is invisible until something downstream breaks. Defenses must guard at the *result-invariant* level, not the *exit-code* level.
+
+---
+
+## The six failure modes
+
+### 1. Wrong private key file
+
+GitHub rotated the App's private key (or the operator put the wrong .pem in the workspace). Local `.github-app-key.pem` doesn't match what GitHub has registered. Every JWT fails with `"A JSON web token could not be decoded"`. `gh token generate` exits non-zero, `GH_TOKEN=$(...)` captures empty, `gh` silently falls through to stored `gh auth login` as the user.
+
+**Detect:**
+```bash
+# Compare local fingerprint with GitHub's (visible on the App settings page)
+openssl rsa -in <key.pem> -pubout -outform DER 2>/dev/null | openssl dgst -sha256 -binary | base64
+```
+Should match the "SHA256:..." shown on `github.com/settings/apps/<app>`.
+
+### 2. Clock drift between VM and GitHub
+
+If `iat` in the JWT is ahead of GitHub's clock (VM runs fast, or even a few seconds skew), GitHub rejects the JWT as "from the future" — same `"JSON web token could not be decoded"` error. Intermittent: sometimes valid, sometimes not, depending on the moment.
+
+**Fix:** use a 180-second back-window on `iat` (not the 60s default):
+```bash
+iat=$((now - 180))    # 3 minutes in the past — tolerates up to 3 min of clock skew
+exp=$((now + 420))    # still 10 min total lifetime (180 past + 420 future)
+```
+
+### 3. `gh` silent fallback to stored user auth
+
+When `GH_TOKEN` is empty or invalid, `gh` falls through to `~/.config/gh/hosts.yml` if present. Ops succeed, content is correct, but `author` on the created resource is the user account.
+
+**Fix:** fail loud. Never use `export GH_TOKEN=$(gh token generate ... | jq)` as a one-liner; it swallows errors. Pattern:
+```bash
+# Assert token was generated AND has the bot prefix
+TOKEN=$(.claude/scripts/macf-gh-token.sh --app-id "$APP_ID" --install-id "$INSTALL_ID" --key "$KEY_PATH") || {
+  echo "FATAL: token-gen failed" >&2; exit 1
+}
+[ -n "$TOKEN" ] || { echo "FATAL: empty token" >&2; exit 1; }
+case "$TOKEN" in ghs_*) ;; *) echo "FATAL: bad token prefix" >&2; exit 1 ;; esac
+export GH_TOKEN="$TOKEN"
+```
+
+### 4. Wrong `gh auth` on the VM providing fallback
+
+Having `gh auth login` configured as a user account creates the fallback surface in #3. Even a "good" setup where the script is correct can hide a broken bot token because `gh` quietly uses the user auth.
+
+**Best hardening:** remove stored `gh auth login` on agent VMs entirely — then broken bot tokens fail loudly with "no auth," not silently as the user.
+
+**Tradeoff:** interactive `gh` inspection by a human on the VM also requires a token. Usually acceptable for dedicated agent VMs.
+
+### 5. Helper script missing from workspace (path 127, silent empty capture)
+
+Non-init'd workspace had never received `.claude/scripts/macf-gh-token.sh` because the operator forgot to run `macf rules refresh` after the helper was introduced. Calling `./.claude/scripts/macf-gh-token.sh ...` returned exit 127 ("no such file") — but with `export GH_TOKEN=$(helper 2>/dev/null)` the 127 is silently discarded, stdout is empty, `GH_TOKEN=""`, `gh` falls through to stored user auth.
+
+Compounds modes #3 + #4: all the bot ops look normal but post as the user. Only noticed when a human checked a comment URL.
+
+**Fix:** use `macf rules refresh --dir <workspace>` to install canonical `macf-gh-token.sh` + `macf-whoami.sh` + `tmux-send-to-claude.sh`. Workbench-only workspaces (substrate agents) still need this — the helpers are distributed via a separate mechanism from full `macf init`.
+
+Also: **always validate token prefix in the chain, not just in the helper.** Even a correctly-installed helper can fail (rotated key, clock drift) and return empty. Chain guard:
+
+```bash
+GH_TOKEN=$(./.claude/scripts/macf-gh-token.sh ...) \
+  && [[ "$GH_TOKEN" == ghs_* ]] \
+  || { echo "FATAL: bad token"; exit 1; }
+export GH_TOKEN
+```
+
+The `[[ ... == ghs_* ]]` check catches both empty and junk-output cases (e.g., the "(eval):1: no such file" leak when stderr was merged into stdout).
+
+### 6. Relative path to helper (or key) breaks on cross-repo `cd`
+
+When an agent `cd`'s to another repo for cross-repo work (e.g., code-agent editing `macf-actions` from its `macf` workspace), `./.claude/scripts/...` doesn't resolve from the new cwd, and relative `$KEY_PATH` can't be read either.
+
+`$(...)` command substitution swallows the helper's exit 127 silently, returns empty string. `export GH_TOKEN=""` succeeds with no error. Next `gh` call falls through to stored user auth. Mode-3 silent fallback, triggered by path breakage.
+
+**Fix (canonical, post macf#161):**
+
+- `claude.sh` exports `MACF_WORKSPACE_DIR="$SCRIPT_DIR"` — the workspace absolute path, available in all agent env regardless of cwd.
+- `claude.sh` absolutizes `KEY_PATH` via `case` on leading slash (preserves operator-absolute paths like `/etc/macf/keys/...`, rewrites relative default to `$SCRIPT_DIR/$KEY_PATH`).
+- All canonical agent templates use `$MACF_WORKSPACE_DIR/.claude/scripts/...` (NOT relative `./...`).
+
+**Why mode 6 is distinct from mode 5:** mode 5 is "helper script file missing from workspace entirely." Mode 6 is "helper present in workspace, but reachable only via a path that breaks on cross-repo cwd." Mode 5's fix is installing the helper (`macf rules refresh`); mode 6's fix is using an absolute path to it (`$MACF_WORKSPACE_DIR/...`).
+
+---
+
+## Verifying identity after ops
+
+Don't trust; verify. A token that "looks right" can still be misattributed due to a subtle env issue. Spot-check at session start:
+
+```bash
+# After posting any comment in a session, sanity-check ONE post:
+GH_TOKEN=$T gh api "/repos/$REPO/issues/comments/$ID" --jq '.user.login'
+# Expect: <bot-name>[bot]; FAIL if it shows the operator's user account
+```
+
+Do this once at session start (cheap), then trust. Mid-session re-checks not needed unless something suspicious happens.
+
+The `macf-whoami.sh` helper canonicalizes this check:
+
+```bash
+.claude/scripts/macf-whoami.sh
+# Prints the actor identity associated with current $GH_TOKEN
+```
+
+---
+
+## Canonical pattern (distilled)
+
+```bash
+# Token acquisition — fails loud, token-prefix validated
+TOKEN=$(.claude/scripts/macf-gh-token.sh --app-id "$APP_ID" --install-id "$INSTALL_ID" --key "$KEY_PATH") \
+  || { echo "FATAL: token gen failed" >&2; exit 1; }
+
+# Chain the op immediately so token doesn't linger in env
+GH_TOKEN=$TOKEN gh issue comment <N> --repo <owner>/<repo> --body "..."
+```
+
+The helper script `macf-gh-token.sh` must:
+1. Use `set -euo pipefail`
+2. Use 180s `iat` back-window for clock drift tolerance
+3. Validate token prefix is `ghs_` (installation token); refuse to print user PATs (`ghp_*`, `gho_*`)
+4. Print nothing to stdout on failure (only stderr)
+
+---
+
+## Structural backstop: PreToolUse hook (macf#140)
+
+Workspaces include a `PreToolUse` hook that intercepts `gh` and `git push` invocations and blocks with `exit 2` if `GH_TOKEN` is missing or doesn't have the `ghs_` prefix. This catches mode 3, 5, and 6 at the call site rather than after the fact.
+
+Distribution: `macf init` / `macf update` / `macf rules refresh` install the hook + the helper scripts together.
+
+When intentionally bypassing the hook for a knowingly user-attributed op (e.g., `gh auth login` during onboarding), set `MACF_SKIP_TOKEN_CHECK=1` for that one call.
+
+---
+
+## How this relates to other canonical rules
+
+- `coordination.md` § "Token & Git Hygiene" documents the canonical helper invocation; this rule provides the failure-mode catalog the helper is designed to defend against.
+- `pr-discipline.md` documents auto-close-keyword hazards in PR bodies; same shape (silent-fallback hazard at the API boundary) but different surface.
+
+---
+
+## Why this rule exists
+
+Silent mis-attribution is a coordination failure mode that breaks routing workflows (workflow @-mention iteration sees user identity on bot-emitted posts; routing doesn't fire) and audit trails (paper-trail evidence shows wrong actors). The trap is mature — recurred 5+ instances across two substrate agents before this rule canonicalized — and prevention is straightforward once the failure modes are catalogued.
+
+Pattern: defenses target *result-invariants* (token has `ghs_` prefix; spot-check actor on a known post), not *exit-code-success* (which silent fallbacks satisfy). This generalizes beyond gh-tokens to other tool/API surfaces with silent-fallback hazards.

package/plugin/rules/mention-routing-hygiene.md

@@ -0,0 +1,105 @@
+# Mention-Routing Hygiene
+
+**GitHub `@handle[bot]` mentions fire the Agent Router workflow regardless of surrounding context. When you are writing *about* an agent — quoting its output, analyzing its behavior, describing it in documentation — code-format the handle to suppress routing. Raw handles are reserved for intentional routing targets.**
+
+GitHub's @mention semantics treat any bare `@handle` in a comment or PR body as a routable signal. The macf-actions router picks these up and forwards the reference to the named agent's tmux session, regardless of whether the reference was in an addressing context ("please take a look") or a describing context ("tester-2's response was…"). When described-not-addressed mentions fire routing, the referenced agent receives an ambient ping asking for an action that was never actually requested. For rules-loaded agents, this typically triggers scope-discipline reasoning (read context, recognize content-reference, cite `agent-identity.md §Not-for-testers`, stand down) and a response comment explaining why. Multiply this across scenario PRs that analyze tester behavior, insight documents that reference agents as research subjects, or cross-agent research commentary — testers and other agents get pinged for every describing use of their handle.
+
+The fix is one character per handle: wrap the `@` and bracketed `[bot]` in backticks. The convention is cheap to apply; the cost of skipping it is proportional to how much the fleet writes about other agents.
+
+---
+
+## 1. The two modes
+
+**Addressing** — you want the agent to see this and respond / act:
+
+    @macf-code-agent[bot] please review PR #12 when convenient.
+
+**Describing** — you are writing about the agent; no routing needed:
+
+    The `@macf-tester-2-agent[bot]` response quoted `coordination.md` rule 1 verbatim.
+
+The difference is a single pair of backticks. Both forms still render recognizably in GitHub's UI; only the raw form fires routing.
+
+**Decision rule when unsure:** ask whether the agent receiving this comment should treat it as an action ask. If yes → raw. If no → backticked.
+
+---
+
+## 2. Contexts where describing happens
+
+These are the common places the describing form applies. Not exhaustive; the principle generalizes:
+
+- **PR bodies** quoting another agent's output verbatim (scenario transcripts, review excerpts, observation snippets)
+- **Issue bodies and comments** analyzing agent behavior for research or post-mortem purposes
+- **Observation logs** and **insight documents** referencing agents as research subjects
+- **Canonical rule files and documentation** citing agent handles as examples
+- **Paper drafts** and **research notes** in which agents are data, not interlocutors
+- **Cross-agent commentary** where you are synthesizing what multiple agents did
+
+In each of these, raw `@handle` will fire routing. Backtick-wrap.
+
+Handles inside fenced code blocks (triple-backtick) or 4-space-indented blocks are already safe — GitHub's mention parser skips code contexts. Backtick-wrapping is for inline prose where a bare `@handle` would otherwise be parsed as a routing target.
+
+---
+
+## 3. Contexts where addressing happens
+
+These are the legitimate routing targets — keep the raw form:
+
+- The closing line of a PR body that asks a reviewer to look: `@macf-science-agent[bot] ready for review.`
+- Direct replies on a thread where you expect the agent to act: `@macf-code-agent[bot] pushback: see file:line ref below.`
+- Handoff comments: `@<reporter> ready for you to close when verified.`
+- Escalation pings when blocked.
+
+If a comment contains both describing and addressing references to the same agent, the describing form gets backticks and the addressing form stays raw.
+
+---
+
+## 4. Verification check before posting
+
+For any comment or PR body that contains agent handles, grep the draft:
+
+    grep -nE '@macf-[a-z-]+-agent\[bot\]' <draft-file>
+
+For each line returned: is this line an action ask (raw stays) or a content reference (backticks wrap)?
+
+If you don't want to verify per-line, the safe default is: **backtick by default, un-backtick only the addressing lines**.
+
+Drafts you run through this check regularly: scenario PR bodies that include preserved artifacts, observation-log entries, insight files, review comments that quote the agent being reviewed.
+
+---
+
+## 5. Alternative forms (same effect, lower readability)
+
+All three of these suppress routing; the choice is stylistic:
+
+- **Backticks** (preferred): `` `@macf-tester-2-agent[bot]` ``
+- **Escape sequences**: `\@macf-tester-2-agent\[bot\]`
+- **Label form**: "tester-2" or "the tester-2 agent" (for prose where a full handle isn't needed)
+
+Backticks are preferred because they render as inline code in GitHub's Markdown, which is semantically meaningful ("this is a handle identifier being referenced") and visually distinct from raw routing targets.
+
+---
+
+## 6. Symmetry — this rule applies to every agent
+
+The convention is **bidirectional** across the fleet. Every agent that writes commentary referencing other agents applies the same rule:
+
+- Science-agent writing about testers → backticks
+- Code-agent writing about testers → backticks
+- Testers writing about each other → backticks
+- Operator-thread comments quoting agent output → backticks (operator is human but the convention applies for consistency)
+- Devops, CV, future-fleet agents → backticks
+
+Asymmetric adoption breaks the protocol: if only some agents escape handles, the others continue leaking routing from the contexts they miss. Symmetric adoption is what makes the convention enforceable.
+
+---
+
+## Why this rule exists
+
+Routing is a global side-effect. Unlike most GitHub semantics, `@mention`-based routing in MACF does not differentiate the grammatical role of the handle — whether the sentence is about the agent, directed at the agent, or merely mentions the agent in passing. The router sees the handle and fires.
+
+Without the backtick convention, every describing use of a handle produces a false-positive ping. For rules-loaded agents that correctly apply scope-discipline when incorrectly routed, this means they must spend attention reading the context, identifying that they were referenced-not-addressed, citing the applicable rule, and posting a stand-down comment. Each firing is a few seconds of noise per agent — but the describing form of a handle is far more common than the addressing form, so the noise accumulates quickly.
+
+The failure-mode was observed on `macf-testbed#9` and `#18` (2026-04-24): a single rules-loaded tester received three ambient routing pings across two scenario PRs, correctly disciplined each response with scope-preserving rationale, and escalated the third firing into a cross-session-commitment-tracking critique of the author. That sequence of responses was appropriate — but it was also three response turns that could have been prevented by one keystroke of backticks per handle reference in the PR bodies.
+
+The rule is cheap to apply, symmetric across the fleet, and eliminates a class of false-positive routing that otherwise compounds with every describing use of an agent handle.