quality-gate

Quality Gate

<!-- CANONICAL: shared/dispatch-convention.md -->

All subagent dispatches use disk-mediated dispatch. See shared/dispatch-convention.md for the full protocol.

<!-- CANONICAL: shared/return-convention.md -->

All subagent returns (red-team agents, judges, fix agents) use the Ledger Return Protocol. Every subagent returns exactly one Evidence Receipt per shared/return-convention.md; the orchestrator applies the two-tier receipt linter (see the "Receipt Linter (Ledger Return Protocol)" section below) to every Task return before acting on the declared VERDICT.

<!-- CANONICAL: shared/cairn-convention.md -->

The gate maintains an Invariant Cairn per shared/cairn-convention.md. Each gate round is a cairn phase. See ## Cairn (Layer 3) below.

Shared iterative red-teaming mechanism invoked at the end of artifact-producing skills. Provides rigorous adversarial review as the core quality mechanism.

Announce at start: "Running quality gate on [artifact type]."

Skill type: Rigid -- follow exactly, no shortcuts.

Execution model: When this skill is running, YOU are the orchestrator. You drive the loop, dispatch fix agents and reviewers as subagents, track scores, and make escalation decisions. All references to "the orchestrator" in this document refer to you.

Receipt Linter (Ledger Return Protocol)

Apply Tier 1 (structural) and Tier 2 (witness verification) lint per shared/return-convention.md to every Task return before acting on the declared VERDICT. The canonical grammar (CLAIM citations, WITNESS rules, verb-binding, byte-range limits, lint-failure handling) lives in that document. Build, siege, and audit apply the same linter.

The linter is a deterministic runtime tool: orchestrators MUST run python3 scripts/rcpt_verify.py --tier2 --strict --root <dispatch-root> --root <findings-root> --ledger <dispatch-root>/receipt-ledger.jsonl <receipt> on every received receipt before acting on its VERDICT, and apply the shared convention's in-context pseudocode ONLY as the fallback when the tool is unavailable. <receipt> is a path or -, and never a new name. Substitute either the path of the receipt file the dispatch itself already saved into the dispatch root (those basenames carry the <dispatch-id>, so pin (a) below already covers them), or the literal -, which makes the linter read the receipt text from stdin (it does so whenever the positional is absent or -). Do not materialise the receipt under a fresh unqualified name such as receipt.txt: that name is rewritten on every lint of the run — the highest-frequency write in the gate — which is exactly the collision pin (a) forbids. --root is repeatable, and this gate passes two: the dispatch root, and <findings-root>. <findings-root> is the directory whose top level holds this round's findings file: the run's scratch directory (see Scratch Directory below) for a non-chunked gate, <scratch-dir>/chunk-N for the in-progress chunk of a chunked gate. For a non-chunked gate the [FINDINGS_OUTPUT_PATH] this gate supplies puts each round's round-N-findings.md at that directory's top level; a chunked gate writes per-chunk round files into chunk-N/ subdirectories (Artifact Preparation › Code artifacts › Large implementations), which a bare-basename probe of the parent scratch directory does not reach — so on a chunked gate the directory substituted for <findings-root> is the in-progress chunk-N/ directory, not its parent. Resolution is a literal join with no search, and the findings file is cited by bare basename, so the root passed must be the directory that actually holds the round's findings file at its top level. Both must be passed explicitly. A sha256 mismatch on any resolved artifact hard-FAILs with or without --strict; --strict adds two further hard FAILs — a path-shaped name no probed base holds (probed bases being each supplied root plus that root's git toplevel; it would otherwise degrade to UNVERIFIABLE), and any cited name — bare basename or relative path-shaped alike — that two or more of the supplied roots' probes find as distinct files (ambiguous — each root contributes at most one file, its own top level first and then that root's git toplevel, so a name held at both homes of the same root resolves silently and only a collision across two roots fires; a first-hit read there would verify against a plausibly wrong file). A bare basename no probed base holds stays UNVERIFIABLE. The obligation to lint every return is unchanged — only the mechanism moves to the tool.

Create <findings-root> before the round's first lint (#486). The directory is normally created by the reviewed subagent writing its findings file into it, so "absent" is its ordinary pre-write state — and it is equally what a subagent that crashed, timed out, or wrote to the wrong path leaves behind, which is precisely the failure a Tier-2 witness exists to catch. The orchestrator therefore creates <findings-root> itself before it lints anything in that round — by writing round-N-coverage.md with empty content (Write tool, per the Tool constraint under Round History). The file is named, not left to the orchestrator's discretion, because the Write tool creates a directory only as the side effect of writing a file into it, and that file lands at the top level of a probed base, where pins (a) and (b) govern its basename. round-N-coverage.md is the one name that costs nothing: the round needs the file anyway, its first capture Read → appends onto it (Coverage-line capture › Write time, which treats empty content exactly as it treats absence), and the Round History inventory already covers it — so no unnamed placeholder (.keep, a stub round-N-findings.md) is introduced into a probed root, where an invented basename is one collision away from the cross-root ambiguity hard-FAIL pin (b) exists to prevent.

If the orchestrator does not create it, the mandated command line hits a root that does not exist: the linter runs Tier-1, refuses to run Tier-2 at all, and exits 1 with TIER2-COVERAGE: not-reached (root-absent). Three dispositions follow, and none of them is the tool-unavailable fallback. A root-absent exit 1 is structurally BLOCKED — Tier-1's verdict stands, but nothing was verified against disk, so no declared hash and no witness predicate was checked. A root that is the empty string or that names an existing file (the <findings-root> vs [FINDINGS_OUTPUT_PATH] one-token slip, or a swallowed shell substitution) is a genuine invocation error: not-reached (root-invalid) at exit 2, with nothing verified at all, Tier-1 included. The third is specific to this gate's two-root line and cannot arise for the single-root callers (build/SKILL.md, siege/SKILL.md): not-reached (root-collapse) at exit 1, emitted when two differently spelled --root tokens resolve to one directory, so the cross-root ambiguity check — one of the two safety properties #486 adds — could not fire at all. Treat all three as structurally BLOCKED; do not read any of them as "the tool is unavailable" and fall through to the in-context pseudocode, which does zero disk verification. The correct response differs by code, which is why the list must stay complete: root-absent is answered by creating the directory (the rule above), root-invalid by fixing the command line, and root-collapse by inspecting <findings-root> for a symlink before re-running — that directory is created by the reviewed subagent, so one ln -s <dispatch-root> <scratch>/chunk-N is the documented way a reviewed party collapses the two roots into one. And the rule generalises past these three: ANY TIER2-COVERAGE: not-reached (<code>) line means Tier-2 did not run and nothing was verified against disk, so treat it as structurally BLOCKED — never as the tool-unavailable fallback. The three above are the codes this gate's own mandated command line reaches through a root; the remaining exit-2 codes (root-missing-value, ledger-missing-value, two-positionals, unknown-flag, receipt-unreadable) are construction errors in the mandated command line itself — a substitution that expanded to nothing, to an extra token, or to a path that is not readable — and their remedy is to fix the command line and re-run, not to fall through to the in-context pseudocode. shared/return-convention.md › not-reached (<code>) — the closed set carries the complete nine-value enumeration with each code's exit and remedy.

The replacement signal for the crashed / wrong-path case is the census, and it has a consumer here. Creating the root removes the loud exit-1 for the very failure the paragraph above names: a subagent that crashed, timed out, or wrote to the wrong path now yields exit 0 with UNVERIFIABLE: witness <name> (no file under root) and a TIER2-COVERAGE: line whose counters carry the whole signal (#499 records that nothing consumes that census generally — this rule is its consumer in the one place its absence is load-bearing). So: on any lint whose TIER2-COVERAGE: line reports witness 0/1, or a non-zero not-reachable or unreached, the orchestrator treats that receipt as UNVERIFIED. It may still consume the declared VERDICT (Tier-1 ran and passed), but it MUST record the round as having verified nothing against disk — the captured key in round-N-coverage.md is that record — and MUST surface it in the narration log, in the same breath as the VERDICT it consumed. Without this check the trade is a loud failure for a silent one; with it, the loud channel moves from the exit code to the narration log rather than disappearing. One exemption, and it is the majority case — read the reason code, not only the counter. A VERDICT FAIL receipt carrying the Tier-1-mandated ranged grep witness renders `witness 0/1 … discarded 1 (fail-le

---

Content truncated.