/protocols

user-invocable: false
install: core

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

Shared Review Protocols

This file contains the shared protocols that ALL review agents must follow. It is read alongside individual persona files during Phase 3C agent dispatch. Canonical source: `docs/spec/review-protocol.md` — sync changes there first.

Per-Agent Input Scoping

**Each domain agent receives only the diff slice relevant to its domain**, not the full PR changeset. The orchestrator (Phase 3C of `review-pr.md`) pre-computes these slices and substitutes `[DOMAIN_DIFF_SLICE]` in each agent's prompt before dispatch.

**Rationale**: Passing the full changeset to every agent inflates per-child input cost on large PRs. A billing agent reviewing auth code produces noise, not signal. Scoped inputs reduce cost and improve focus.

**Empty slice rule** (forge#4573): if a domain's file pattern matches nothing in the PR, its slice is a one-line note, never a copy of the full diff (that duplicated the whole diff across domains). Slices hold whole file blocks only: a file too large for the slice is listed as `# OMITTED` at the top and read from the head checkout. A staging brief may carry a pointer to the slice file instead of the text when the slice is large; read that file with bounded `grep`/`sed -n`.

**Security agent exception**: The General Security agent ALWAYS receives the full diff — security vulnerabilities are cross-cutting and cannot be safely scoped to a file-path filter.

Tool-Result Truncation Discipline

All tool results consumed by agents — including diff slices, file reads, and command outputs — are capped at **~100K characters**. This mirrors the runner's built-in 100K-char tool-result cap (`bin/runner.mjs`).

**Agents must NOT re-fetch `gh pr diff` in full** — use the pre-supplied `[DOMAIN_DIFF_SLICE]` instead. If an agent needs to read a specific file in full (e.g., to trace an import), cap the read at the relevant section using `head -N` or `sed -n 'X,Yp'`. Never pipe unbounded command output into context without a `| head -N` guard.

Rationale: agents receiving oversized context perform worse, not better — attention dilutes across irrelevant content, and token limits risk truncating the structured findings block that the triage phase depends on.

File-Backed GitHub Write Integrity

When staging a body for `gh issue create|edit` or `gh pr create|comment` with `--body-file`, use the session scratchpad (or a repo-relative scratch directory) rather than a generic path under shared `/tmp`; native Windows `gh` may not resolve Git Bash `/tmp` reliably. The filename must contain the issue or PR number and an agent-unique token, and `mktemp` must add a random suffix. Add exactly one caller-chosen marker to the body: `<!-- FORGE:BODY-INTEGRITY:<entity>_<role>_<agent-token> -->`.

Immediately after the write, re-read the issue, PR, or posted comment and assert that it contains that exact marker. Treat a missing marker as a hard error and stop. A unique filename reduces collision risk, but only the read-back detects another agent's plausible-looking content being posted in its place; do not rely on a visual review. The `/issue` programmatic contract performs this assertion for its `--body-file` callers.

File Resolution Discipline

Pipeline agents MUST NOT use `find` (unbounded or filesystem-wide) to locate protocol files, persona templates, or verification scripts under any circumstances. If a `Read` or `bash` invocation of an expected pipeline file fails (e.g. because `$FORGE_HOME` is unset and the path degraded to a root-anchored form), that is never a reason to search the filesystem — it means the deterministic fallback chain the orchestrator already computed (`$FORGE_HOME` → `$REPO_PATH` → documented last-resort) was exhausted. Stop and report the failure (or fall through to the orchestrator's documented FATAL/hard-stop behavior — see `commands/review-pr.md` Phase 3C `TEMPLATE_BASE` guard) instead of improvising a `find /`-style search. A filesystem-wide `find` on an unset variable is the exact failure mode that produced runaway orphaned processes in production (see forge#1984, forge#2035). <!-- Added: forge#2035 -->

---

SELF-REVIEW MODE (build-time, local diff) <!-- Added: forge#3971 -->

`work-on:build` Phase B5.6 runs the same domain personas on the builder's staged diff before any PR exists, so the builder can fix adversarial-completeness findings while the plan and code are warm. The personas, the Evidence-Based Review Protocol (sections 1-7) and the Structured Findings Protocol apply unchanged; only the transport differs. This mode is entered only when the dispatch prompt says `MODE: SELF-REVIEW`. It is never the official review and never satisfies a review gate.

**Inputs the dispatcher supplies**: `[AGENT_DOMAIN]` (the marker domain), `[ISSUE_NUMBER]`, `[GH_REPO]`, `[WORKTREE_PATH]`, `[PR_BASE]`, `[TREE_HASH]` (the staged tree, `git write-tree`), and `[DOMAIN_DIFF_SLICE]` (the slice of `git diff --cached origin/[PR_BASE]`, scoped exactly as in Per-Agent Input Scoping; the Security agent gets the full diff).

**Substitutions** (persona text that names a PR still applies, translated):

• No `gh pr *` call is ever made: there is no PR. Read the slice from `[DOMAIN_DIFF_SLICE]` (materialize `SLICE_FILE` with the same heredoc, using `[ISSUE_NUMBER]` and `[AGENT_DOMAIN]` in the path in place of `[PR_NUMBER]` and the SHA), and list changed files with `git -C "[WORKTREE_PATH]" diff --cached --name-only "origin/[PR_BASE]"` wherever a persona runs `gh pr diff [PR_NUMBER] --name-only`. Reads of other repo files happen inside `[WORKTREE_PATH]` with the usual bounded-output rules.
• No `Reviewed-SHA` staleness check. The pin is the tree: include exactly one line `Tree: [TREE_HASH]` (outside the marker) in the persisted body.
• Persist Before Post still applies, but the post is `gh issue comment [I