DevNullLtd/Yuzu / .claude/skills/governance
governance
UnverifiedRun the Yuzu full governance pipeline on a commit range. Produces Gate 1 Change Summary, then orchestrates Gates 2-6 as parallel agent fan-outs with pre-written prompt preambles. Use when the user says "/governance <range>" or "full governance" or asks to run the multi-gate review pipeline on a PR/commit set.
governance
Runbook for the full Yuzu governance pipeline defined in CLAUDE.md. This skill is a prompt-writing shortcut — it does not fully automate the run because Claude still has to make judgment calls (which Gate 3 domain agents are triggered, whether Gate 5 runs, how to consolidate findings, when to iterate). What it does is cut the per-run prompt-writing overhead by pre-composing the preambles and output contracts each agent needs.
Usage
/governance <commit-range>
Examples:
/governance HEAD~4..HEAD— last four commits/governance dev..HEAD— everything on this branch not yet in dev (feature branch workflow)/governance origin/dev..HEAD— commits on local dev not yet pushed (direct-to-dev workflow)/governance 82f7eb8..9c50bce— a specific PR range/governance HEAD— single-commit review (shorthand, treated asHEAD~1..HEAD)
If no range is provided, default to dev..HEAD. Yuzu's main working branch is dev (not main), so governance runs normally review "what's new on this branch relative to dev" before merging or pushing. If the current branch IS dev, dev..HEAD is empty — in that case prompt the operator with origin/dev..HEAD (commits ahead of the remote) as the likely intent, or ask them to specify.
Workflow summary
Gate 1 — Change Summary (YOU write this from git diff/log)
Gate 2 — security-guardian + docs-writer (parallel, mandatory)
Gate 3 — domain-triggered agents (parallel, decision matrix below)
Gate 4 — happy-path + unhappy-path + consistency (parallel, mandatory)
Gate 5 — chaos-injector (conditional on Gate 4)
Gate 6 — compliance + sre + enterprise-readiness (parallel, mandatory)
Gate 6b — synthesis pass (presentation only, workflow-orchestrator)
Gate 7 — address BLOCKING findings
Gate 8 — re-review gates whose DOMAIN THE FIX TOUCHED, ledger, final decision
Per CLAUDE.md standing rule 2: a finding BLOCKS when its derived band is CRITICAL or HIGH (see the shared preamble below), plus the policy floors listed there. Iterate until the team gives a clean bill. No commit until governance passes.
Step 0 — Before you launch anything
First: confirm you are running the current pipeline
This skill and all four routed-concern tables (.claude/routed-concerns.md,
.claude/routed-concerns-access-control.md, .claude/routed-concerns-security-posture.md and
.claude/routed-concerns-software-estate.md) are read from your working tree, so a branch
that predates a change to any of them silently runs the old pipeline. At the time #2604 merged,
81 of 81 local branches predated it.
git fetch origin dev -q || echo "WARNING: fetch failed - origin/dev may itself be stale"
for f in .claude/skills/governance/SKILL.md .claude/routed-concerns.md \
.claude/routed-concerns-access-control.md \
.claude/routed-concerns-security-posture.md \
.claude/routed-concerns-software-estate.md \
CLAUDE.md; do
git diff --quiet origin/dev -- "$f" \
&& echo " ok $f" \
|| echo " DIFFERS $f ($(git diff --shortstat origin/dev -- "$f" | sed 's/^ *//'))"
done
Three things about that loop are load-bearing.
It compares the WORKING TREE, because that is what gets read. The skill is loaded from
your checkout, not from a commit, so the commit is the wrong object to test. An earlier
version of this check compared HEAD...origin/dev - commit against commit - which reports
current for a tree whose branch is up to date but which has an older skill checked into
it (git checkout <old-sha> -- .claude/skills/governance/), and reports stale for a
tree like the one this paragraph was written from, whose branch is months behind but whose
files were copied across and are byte-identical to origin/dev. Both answers were wrong,
and the dangerous one was the first.
It reports per path, and shows the size of the difference, so the output is evidence rather than a verdict. A bare boolean over three aggregated paths tells you nothing you can act on.
It does not try to tell you WHY a file differs. Whether you edited it or checked out an
older copy is not knowable from git - both produce a working tree that differs from
origin/dev - so the check reports the fact and leaves the judgement to you. If you are
deliberately editing one of these files, DIFFERS on that path is expected and the diff it
names is your own. Claiming to distinguish the two would be asserting something unverifiable,
which is the failure mode a previous revision of this section shipped.
The fetch guard. A bare git fetch whose exit status is discarded fails silently
offline or on expired auth, and the comparison then runs against a stale cached
origin/dev and reports current while your tree holds the old pipeline. That is the
one direction this check exists to prevent.
CLAUDE.md is included because it is loaded into every session, so a stale summary
there outranks a correct skill in practice.
If a path you are not editing reports DIFFERS, reconcile before running: rebase or merge
origin/dev, or copy the current files across (git checkout origin/dev -- <path>), which
is enough on its own - the check passes on content, so the files do not have to be committed
to be current. Do not proceed on the assumption that your copy is current: the same failure
mode produces confident false claims about which agents a change routes to.
The same rule applies to any claim that a file, row or invariant is ABSENT. Check
git show origin/dev:<path>, never ls or a working-tree grep. Staleness inverts absence
claims, and an external reviewer pointed at your tree inherits the error rather than
catching it.
Then: size the change and pick domain agents
Run these in parallel:
git log --oneline <range>
git diff --stat <range>
git diff <range> -- '*.cpp' '*.hpp' '*.h' | wc -l
git diff <range> -- 'proto/' 'meson.build' '.github/workflows/' 'tests/' \
'gateway/' 'docs/' 'scripts/' | wc -l
Check existing memory that might apply — at minimum:
feedback_governance_run.md— prior-run learningsfeedback_test_quality.md— fixture leaks, test code standardsfeedback_claude_md_scope.md— which areas are cipher to you / still churning
Load and MATCH all four routed-concern tables — do not rely on memory
# Every changed path, against every routed-concern row.
git diff --name-only <range>
Open ALL FOUR .claude/routed-concerns.md, .claude/routed-concerns-access-control.md,
.claude/routed-concerns-security-posture.md and .claude/routed-concerns-software-estate.md
and walk them row by row against that path list. There are FOUR files — the table was split when
the first hit CLAUDE.md's 40k-character ceiling and a new catastrophic-invariant row physically
would not fit (three times: once for access-control/request-admission, again in Wave 8 for the
security-posture plugin rows (the read-only posture plugins and the mutating registry row), again for
Forensics/per-user-software-data). Walking only
the first silently skips every access-control and request-admission chokepoint, which is where the
highest-severity rows live: the authz-topology floor, dispatch confinement, dispatch targeting, the
pre-auth body cap, and the ADR-1005 spine; skipping the third silently skips every
security-posture plugin invariant; skipping the fourth silently skips the Forensics-class plugin
rows (e.g. browser_inventory's privacy contract). A row that is never opened routes nobody,
which defeats the row's only job.
Each row names the files/change-types it covers and the agents that MUST load on
them. Those agents are selected unconditionally — see the standing rule under
the Gate 3 decision matrix. Write the matched rows into your Gate 1 summary so the
selection is auditable, and repeat this match at Gate 8 against the fix diff.
Do this by reading the table, not from recall: it is amended often, and a row you
remember may have been rewritten. (The clock-guarded-retention row alone has been
rewritten twice since it landed.) Rows are also the reason a one-line change can
require sre and compliance-officer — size never gates a routed concern.
Shared preamble — inject this into EVERY agent prompt
Twelve agents asked for "BLOCKING / SHOULD / NICE" with no definition invent twelve different bars, and the operator normalises by hand. #2604 calibrated the merge THRESHOLD, which fixed the gate but left the bands undefined — CRITICAL and HIGH both mapped to the same tier with no criterion separating them, while the ledger records the native band and CLAUDE.md acts on it.
The block below closes that: the band is derived from stated facts, so a wrong band shows up as a mismatch between the facts and the label rather than as an unfalsifiable judgement. Two structural points, both learned the hard way in review (#2623):
- The facts are independent fields, not one choice. An earlier draft collapsed actor privilege, configuration, rarity and production-reachability into a single enum. A race-based authorisation escape under a non-default flag truthfully satisfied three values that derived different bands, so severity was still being chosen. List every value that applies; the strongest modifier wins.
- Contract violations are not operational severity. A missing Resource Ledger or a broken platform build has no production trigger and no wrong outcome, so an honest derivation lands it at INFO. Those are policy floors and bypass the derivation entirely.
Paste this block verbatim into every Gate 2/3/4/6 prompt, in addition to that agent's own focus.
## Severity — DERIVE it, do not choose it
Report in the severity vocabulary your own brief specifies. Do NOT switch
vocabularies — a renamed band loses information. But do NOT pick a band by feel
either. State the facts below; the band follows from them. Where your brief's own
severity criteria disagree with the derived band, **the derived band governs the
GATE**; record your brief's label as `severity_native` and say they disagreed.
Every finding MUST carry, as separate fields — they are independent, and collapsing
them into one choice is what let severity be chosen:
1. TRIGGER — the concrete input, state, or configuration that produces it. Name
it. "Under load" and "in some cases" are not triggers. If you cannot isolate
one, write `unresolved` — do NOT downgrade IMPACT to compensate.
2. IMPACT — what goes wrong if this ships. Closed list. **List EVERY value that
applies**; the strongest gives the base band. A crash that also corrupts is
`I2` AND `I5`, and it derives from `I2`. Recording only the weaker one is how
severity gets chosen.
3. EXPOSURE — what is required for it to happen. Closed list. **List EVERY value
that applies**; the strongest modifier is the one that counts.
4. EPISTEMIC STATUS — `verified` (you ran something and observed the outcome),
`likely` (reasoned from code you actually read), or `speculative` (you can
name neither the code path nor a candidate trigger — a hypothesis about code
you have not read). `likely` is the normal case and gates normally. Only
`speculative` is exempt, and it is the narrow case, not the humble one.
### IMPACT — gives the base band
I1 security-control failure — an authn, authz, confinement, crypto, or
audit control does not hold base HIGH
I2 data loss or corruption — data destroyed or wrong. A surfaced
error does not lower this; silence is not a precondition base HIGH
I3 wrong result presented as correct — the caller cannot tell base HIGH
I4 harmful operator guidance — a doc, runbook, or error message
directs an operator to a NAMED action that causes damage, or
that fails in a way which conceals the real state. Guidance
that merely fails visibly and diagnosably is I7 or I8, not I4 base HIGH
(caps at HIGH)
I5 unavailability — crash, hang, deadlock, wedge, unbounded growth base MEDIUM
I6 capability absent or unreachable — a deliverable the change
presents is not actually reachable in production (shipped-
incomplete), or a required call site is missing base MEDIUM
I7 required documentation absent for a shipped behaviour change base MEDIUM
(caps at HIGH)
I8 degraded but correct — slow, wasteful, noisy; output still right base LOW
I9 no operational impact — latent, stylistic, defence-in-depth only base INFO
I6 raises to HIGH in exactly two cases:
(a) FALSE ASSURANCE — the change advertises a security or data-integrity
control as in force which is not in fact enforced; or
(b) DORMANT AUTHORISATION CODE — a new authz or enforcement branch ships with
no production caller or author, so it goes live later without re-review.
#2202 Blocker 4 is the reference case for (b): an RBAC resolver consuming
a grant no production route could author. It is (b), NOT (a) — that
resolver fails CLOSED, so nothing was under-enforced.
I5 raises to HIGH in any of three cases:
(a) it is REPRODUCIBLE unavailability of the server or agent process reached on
an ordinary request path — a triggerable control-plane crash gates, and
does not need an unauthenticated reporter to do so;
(b) it is unbounded or persistent AND falls on a serialised path shared with a
security or data-integrity operation (revocation, enforcement, audit,
retention);
(c) it wedges a state machine. Delaying a
security operation at scale is a security outcome, not a performance one. #2580's
15s unbatched sampler on the agent-revocation thread is the reference case, and
the class also covers #2284's state-machine wedges.
I7 raises to HIGH when the omission conceals a breaking change, a security-
relevant behaviour, a data-loss risk, a migration step, or an irreversible
operation. Otherwise it stays MEDIUM. I4 and I7 never exceed HIGH: a document
is not reached by an attacker, so EXPOSURE cannot promote it to CRITICAL.
### EXPOSURE — list all that apply; strongest modifier wins
E1 unauthenticated, in the DEFAULT configuration raise one band
E2 an actor operating BEYOND the privilege it starts with
(escalation, confinement escape). Judge by the privilege
REQUIRED to begin, never the privilege gained raise one band
E0 no actor required — it fires unconditionally in production: a timer, a
background thread, a boot path, a scheduled sweep no change
E3 any authenticated actor within its own privilege, default
configuration — including the ordinary operator no change
E4 requires a non-default configuration no change
E5 requires a race or a rare environmental condition (clock skew,
disk full, concurrent writer, partial failure) no change
E6 the WRONG OUTCOME — not merely the code branch — is proven
unable to occur in production cap at LOW
E7 the artifact is documented ADVISORY (never gates CI or a merge on
its own — the skill/doc that owns it says so) AND the input is
author-controlled: hand-typed, self-authored, or fed only by the
author's own tooling, never reachable from an external actor, a
production request, or production data cap at MEDIUM
Bands, ordered: INFO < LOW < MEDIUM < HIGH < CRITICAL
Order of operations: apply the strongest RAISE first, then any CAP. `E6` and
`E7` are applied LAST, in that order — `E6`'s LOW cap dominates `E7`'s MEDIUM
cap when both apply, and both dominate every raise. The same recorded facts
must not derive CRITICAL, LOW, or MEDIUM depending on the order they are read
in.
E4 is deliberately NOT a downgrade. In Yuzu the default is frequently the LESS
hardened setting — RBAC off is the default, `--auth-mode=sso-only` is opt-in — so
"only with the flag on" often means "only for the customers who care most".
E6 is about the OUTCOME, not the branch. A branch with no production caller is
usually I6 (shipped-incomplete), not E6 — E6 requires proving the wrong outcome
cannot occur, which a missing caller does not establish. If both a security
control failed AND the actor ends up beyond its privilege, that is I1 with E2;
do not report the escalation as though it were the only fact.
E7 exists because the derivation table otherwise has no way to distinguish
"an attacker can trigger this" from "only the author, hand-authoring a test
fixture or their own input file, can trigger this" — added 2026-09-16 after
PR #4386 (an author-side, advisory-only JSONL linter) ran 11 external review
rounds, roughly half of them contrived Unicode/timestamp/precision shapes no
production caller or attacker could ever supply, each still graded HIGH/
BLOCKING because nothing in the table could discount them. E7 is narrow and
BOTH conjuncts must hold — the artifact's own doc/skill must call it advisory
(a merge-gating CI check, a production parser, or anything an external
request can reach forfeits E7 immediately, even if today's actual caller
happens to be internal), and the SPECIFIC finding's input must be one only
the author controls (a duplicate-JSON-object-member finding on a real,
already-committed governance.d fragment is NOT author-controlled in this
sense — that data source is exactly what the tool exists to check, and it
already contained real, previously-invisible instances of that exact defect
in production ledger data; a hand-typed 5000-digit fractional-second fixture
built solely to probe a regression LOCK's implementation boundary is). When
in doubt, do not apply E7 — a wrongly-withheld E7 costs one extra SHOULD
finding; a wrongly-applied E7 silently downgrades a reachable defect.
### The gate
BLOCKING = the derived band is CRITICAL or HIGH.
Vocabulary map, derived from the bands above, not asserted alongside them:
BLOCKING / SHOULD / NICE → BLOCKING = CRITICAL|HIGH, SHOULD = MEDIUM,
NICE = LOW|INFO
BLOCKING / SHOULD-FIX / NICE-TO-HAVE → the same three
low / medium / high / critical → already bands; INFO absent, use LOW
### Policy floors — gate regardless of the derived band
These are contract violations, not operational severity. They do not run through
IMPACT/EXPOSURE and they always gate:
- a Resource Ledger omission on a C++ diff
- a direct edit to `CHANGELOG.md`, or a missing mandated `changelog.d/` fragment
- a broken build or test leg on any supported platform that this change
INTRODUCED or newly exposed — not a pre-existing or environmental failure
- manual resource cleanup in NEW C++ that is not RAII-wrapped. The
"documented impossibility" exception is NOT self-granted: it must be
adjudicated by an agent other than the one proposing it and recorded in the
ledger with `adjudicated_by`. Pre-existing cleanup in a file this change
merely touches is SHOULD, not a floor — a deliberate narrowing, see the
tuning doc
- a violation of an explicit MUST / never / catastrophic-if-violated invariant.
CLOSED to three sources, so floor membership is not a judgement call: a
catastrophic-if-violated clause in a row of any of the four `.claude/routed-concerns*.md` tables; a
CLAUDE.md sentence inside a standing-rule or invariant block; an accepted
ADR's normative requirements. NARRATIVE prose does not qualify — an ADR
saying a thing "never landed" is history, not a contract. If you cannot
point at one of those three, it is not a floor — a
second copy of a single-chokepoint rule, a forked dangerous-op gate, an
approval gate outside the core primitive, a new server SQLite store with no
exception ADR. These have no wrong outcome TODAY, which is exactly why the
derivation cannot see them
- an ownership or lifetime defect of the kind `cpp-safety`'s blocking contract
enumerates: a leak, a double-close/double-free, a use-after-free or
borrowed-data escape, an unjoined or ambiguously-owned thread, unsafe shell
string construction, or a cast resting on undocumented aliasing/lifetime.
These derive `I5`/MEDIUM on an ordinary path and would otherwise stop gating
- a FALSE-GREEN test offered as closure evidence for a blocking finding — a
test that cannot observe what it asserts. Ordinary missing coverage stays
SHOULD; this is a floor because it is evidence of resolution that is not
evidence of anything (#2580 parity test)
A missing test for a behaviour that has a bounded blast radius is SHOULD, not a
floor.
### Absences — and which way each one points
- TRIGGER unresolved → keep IMPACT honest. It is `speculative` ONLY if you also
have no code path — that is the definition above. If you READ the code and
named the path but cannot yet isolate the input, it stays `likely` (so it
gates) and is flagged for adjudication. Never record a lower IMPACT than you
observed in order to express low confidence.
EPISTEMIC STATUS is an operation on the GATE, not on the band. Derive and
report the band normally; `speculative` then converts the finding into a
MANDATORY INVESTIGATION rather than a merge blocker: it is recorded at its
derived band, it must be resolved to `verified`, `likely`, or `refuted` before
the gate passes, and resolving it may confirm the band and block. `refuted` is
a resolution, not an escape: it is the disposition, it carries its evidence and
an independent refuter, and it is how a speculative claim that turns out FALSE
leaves the gate — without it, a correctly-killed finding either wedges the gate
or gets relabelled `likely`, which falsifies the record. It is a deferral of
the decision, never a dismissal of it. `verified` and `likely` gate normally.
If a finding is BOTH speculative AND has unresolved EXPOSURE, it GATES
outright: a schema failure outranks weak evidence, because the unknown may
be `E1`.
- EXPOSURE undeterminable → record `unresolved`. It does NOT default to E3, and
it GATES pending adjudication. Defaulting an unknown to "no change" is a silent
downgrade of a possible E1. Narrow exception, stated under the prose rule: `I4`
and `I7` take `E3` — a document is read by an ordinary operator, is not reached
by an attacker, and both cap at HIGH, so there is no `E1` to conceal. That is a
determination for a named IMPACT class, not a licence to default an unknown.
- Your vocabulary does not map → gate it, and say so.
Your evidence being weak points DOWN, via EPISTEMIC STATUS. The schema failing
points UP. Those are different things and they are deliberately not symmetric.
## Prose: docs-writer owns WORDING, the domain agent owns TRUTH
Two different questions, two different owners:
- Is this text WELL WRITTEN (clear, accurate to convention, not stale)? ->
`docs-writer`, including in-code comments and log/error-message text.
- Is this text TRUE? -> the domain agent. Ordinary C++ comments: `cpp-expert`.
Lifetime / ownership / thread / callback / syscall claims: `cpp-safety`.
Auth, authz, crypto, control claims: `security-guardian`. Erlang:
`gateway-erlang`. CI / build / release: `build-ci` or `release-deploy`.
Normative architecture text — ADRs, invariants documents, routed-concern rows:
`architect`, plus `security-guardian` where the text states a security posture.
So: report a comment or doc when it CONTRADICTS the code — that is a truth finding,
at your own native severity, and it is yours to raise whatever agent you are. A
WORDING-ONLY observation belongs to `docs-writer`: if you are any other agent, do
not file it at all. That is the half that makes this a consolidation rather than a
sixth opinion — routing prose to one reviewer only works if the other five stop.
`docs-writer` files wording at NICE, capped.
Exception, and it is load-bearing: a factually false comment adjacent to a security
or control-flow branch IS a contradiction, not wording. #2202 shipped a comment
asserting the opposite of what its function did, next to an authz branch.
**Absence is a third category, and it is NOT wording.** A behaviour change with no
doc at all contradicts nothing, so the cap does not reach it: a missing required doc
is a TRUTH finding, derived per standing rule 2 as `I7` (SHOULD by default, BLOCKING
where the omission conceals a breaking change, security-relevant behaviour, a
data-loss risk, a migration step, or an irreversible operation). Never file a
missing-doc finding as NICE on the grounds that it is "documentation".
**"Required" is defined, not judged.** A doc is required when it is one of these,
and nothing else:
1. the REST API reference, for a changed endpoint signature, body, error path or
permission
2. a `docs/user-manual/` section, for a changed operator workflow, CLI flag, env
var or upgrade step
3. a `changelog.d/` fragment, for an operator-visible change
4. `CLAUDE.md` or a routed-concern row, for a new architectural invariant, store,
ABI pattern or release gate
5. an audit-action, permission or error-code table the change's contract touches
6. a doc a row of any of the four `.claude/routed-concerns*.md` tables names as an **update obligation for
the changed surface** — whether operator-facing (a user-manual page for a
changed feature) or author-facing (a migration ladder, a capability registry,
a per-surface invariants doc that records each change as it lands). What it is
NOT is the row's **reading list**: `docs/cpp-conventions.md` is named for *any*
C++ change so the reviewing agent LOADS it, and reading "names the doc"
literally would make every C++ PR that does not edit it a missing-doc finding.
The test is whether the doc accrues an entry per change, not who reads it.
**In-code prose never qualifies.** An uncommented function is not a missing required
doc. Without that boundary the rule becomes a laundering route: any wording nit
restates as "the doc does not state X" and walks from NICE to SHOULD, re-creating
the noise this whole line of work exists to reduce.
An absence finding must cite which of the six it rests on. If you cannot, it is a
wording finding or nothing.
For `I4` and `I7` findings, EXPOSURE is `E3` unless you can name a specific reason
otherwise. A document that isn't there is read by an ordinary operator; it is not a
timer and not an escalation. Recording `unresolved` here instead would gate every
missing doc, contradicting the `I7`-is-SHOULD-by-default rule two paragraphs up.
(Capping wording rather than banning it is deliberate: deciding whether prose is
descriptive or normative is exactly the disputed question, so a mis-classification
should cost a line of noise, not a lost finding.)
## Verify what you can, read-only
Verify the reviewer read what you think it read. A finding derived from corrupted
input is confident and wrong, and reads exactly like a finding derived from clean
input — a shell `patsub_replacement` setting silently rewrote every `&` in a review
payload on #2622, and the corruption was invisible in the output. Echo back a
distinctive line of the source before trusting a review of it.
Where a claim can be tested cheaply — a query, a compile, a one-case test — TEST IT
and report the output. An empirically verified finding outranks a reasoned one, and
a reasoned finding about observable behaviour should say it was not verified. The
highest-value finding of the #2580 run came from an agent running a real query
against a live Postgres rather than reasoning about the SQL.
READ-ONLY, against disposable state only. Never mutate a live store, and never run a
destructive statement to raise a finding's standing.
Gate 1 — Change Summary
You write this yourself, from git show and git diff --stat. Structure:
- Commits in scope — table with sha, subject, push state
- Files touched — table with path, delta description
- Interfaces affected — public API changes, store contracts, REST behavior, proto, plugin ABI, CI gates
- Security surface — what's closed, what's opened, net-neutral explanation
- User-facing impact — behavior changes, breaking changes, new flags
- Resource Ledger — for C++ changes, list every new or modified fd,
HANDLE, SOCKET,
FILE*,sqlite3_stmt*,sqlite3*, OpenSSL object, BCrypt handle, allocated C string, mapped library, temp path, subprocess, callback context, and thread. For each, name owner type, acquisition point, release point, transfer behavior, and failure cleanup. - Prior validation performed — compile, tests, script runs with exit codes
- Governance domains triggered — which Gate 3 agents apply (see matrix below)
Write this in your own response before invoking any agents. All downstream agents reference it, so skimping here wastes the whole run.
Gate 2 — Mandatory security + docs review
Launch both agents in a single message with two tool calls so they run in parallel.
security-guardian preamble template
Full governance Gate 2 review of <N> commits on branch <branch> at
<repo-root>: <sha1>, <sha2>, ...
Use `git show <sha>` to view each commit. The working tree is clean;
what you see in <range> is the full scope.
## Your job
You are the mandatory security reviewer for Gate 2. Read every
modified file top to bottom (CLAUDE.md requires it) and assess:
<finding-specific questions — fill in based on the actual change>
## C++ safety ownership proof
For any C++ diff, verify the Resource Ledger and independently prove
ownership for every fd, HANDLE, SOCKET, `FILE*`, `sqlite3_stmt*`,
`sqlite3*`, OpenSSL object, BCrypt handle, allocated C string, thread,
callback context, subprocess, mapped library, and temp path. Each
resource must have exactly one owner, one release path, explicit
transfer behavior, and checked failure cleanup.
Manual cleanup in NEW C++ code is a policy floor (see the shared preamble)
unless it is wrapped in a small RAII owner/scope guard or the exception is
documented as impossible to express safely. Pre-existing cleanup in a file
this change merely touches is SHOULD, not a floor. Check every early return between
acquire and release.
Shell-command surfaces are high risk: new `system()`, `popen()`, shell
strings, `fork`/`exec`, or `CreateProcess` usage must prefer argv-style
execution unless a documented exception explains why a shell is required.
## Sibling-handler check (LOAD-BEARING)
This has caught 2/3 of the highest-severity findings in prior runs.
For every handler, endpoint, or store method this PR modifies, find
every OTHER handler/endpoint/store method in the codebase that
implements the same semantic (e.g. "revoke token", "update group",
"fetch inventory") and verify that:
(a) it has the same authorization check, and
(b) it has the same validation/ownership pattern.
Explicit "grep for sibling paths and compare" is the invariant — not
"trust that other paths are fine."
## New authz surface / principal class check (LOAD-BEARING)
Added after PR #2202: a rebase of already-gated engine-principal code
shipped **4 HIGH** auth findings (fleet-wide-read-when-RBAC-off,
boots-clean-on-corrupt-rbac.db, engine-audit-mislabelled, resolver
branch with no production caller) through a 14-agent `/governance` run
AND two Hermes passes. An external panel caught all four on first
contact. The gap: reviewers checked the *new routes* and the surface a
recently-added deny-belt already covered, and never traced the
capability's authority across the whole authz layer.
When a diff adds or changes a **principal class**, an `auth_source`, an
authorization **entry point**, or any capability reachable by a new kind
of actor, do ALL of the following — do not sample:
1. **Chokepoint coverage, not file coverage.** Enumerate *every*
authorization chokepoint an actor of that class can reach —
`require_permission`, `require_scoped_permission`, `require_admin`,
every inline `check_permission`/`check_scoped_permission`,
`authorize_list_read` (`AuthRoutes::require_list_read` + its MCP /
dashboard wrappers), the MCP tier gate, any service-scoped/elevation/
legacy fallback — and prove the intended posture (allow/deny/step-up)
at EACH. **List/fan-out reads of per-agent data are a DISTINCT
chokepoint from per-object permission checks**: they MUST go through
the admit-then-filter `authorize_list_read` (World A, ADR-0017 —
`docs/adr/0017-management-group-confinement-list-reads.md`), never a
bare global `require_permission` (which is inert for a confined
operator and fails *open* on a corrupt `rbac.db`). A carve-out that
gets every single-target check right but leaks a fleet-wide list is
the same failure mode as #2202. A carve-out that sits only on the new
routes, or only where a sibling guard happens to already sit, is the
#2202 gap. Grep for the chokepoint functions (incl.
`authorize_list_read`/`require_list_read`); do not reason from "the
new code looks right."
2. **Test the DEFAULT deployment config, not the hardened one.** Re-run
the authorization reasoning with the security-relevant toggle in its
**default** state (e.g. RBAC *off* — the default — not RBAC on). The
#2202 fleet-wide-read only triggered with RBAC off, which is exactly
what nobody exercised. Ask: "what does this grant/deny when the admin
has configured nothing?"
3. **Reachability of every new branch.** For each new authorization or
resolution branch (a new `principal_type` arm, a new store method, a
new grant path), grep for a **production caller**. A branch reachable
only from tests is either dead code or a shipped-incomplete
deliverable — say which. (#2202 Blocker 4: the engine RBAC resolver
had no route that could author the grant it consumed.)
4. **Fail-closed on infra failure.** For any authoritative read in the
authz/identity path — a *new* read, OR an existing resolver that this
change makes newly load-bearing for the new actor type (a resolver can
become security-critical for a new principal without a line in it
changing) — confirm a store/DB failure denies or refuses boot, never
reads as an empty/absent result that silently allows. Check the
engaged-empty-vs-`nullopt` / `std::expected` distinction.
5. **Comment-vs-code diff.** Read each comment near a new authz branch
against the code it describes. #2202 Blocker 2 shipped a comment that
asserted the *opposite* of what the function did (`nullopt` on
failure) — a lying comment is a strong signal, not decoration.
6. **Audit attribution survives to the row.** Trace the new actor through
EVERY audit helper it can reach (`make_audit_event`,
`emit_behavioral_audit`, any inline `audit_log`/`.log({...})`) and
prove the persisted row carries the stable authorization principal,
the correct `principal_class`, the correct `auth_source`, the
effective role, AND correct attribution on the *denied* path — never
the creating human, a presentation-only default, or a half-set field.
#2202 Blocker 3 stamped engine actions as `principal_class=agent`
because `make_audit_event` set the class before session resolution and
never re-stamped. "Audit events are emitted" is NOT enough — the
fields must be *correct* for the new actor.
## Design-contract & state-machine tracing (LOAD-BEARING)
Added after PR #2284: an external reviewer reading the design doc
line-by-line found real defects across THREE rounds that a 14-agent
`/governance` + Hermes ×2 had passed — because our gates reviewed the
*diff mechanics* (does the merge compile, is the carve-out present) but
never traced the PR's own *published contracts* and *state-machine
semantics* against the code. Fold that depth in here.
When a PR (a) touches a **state machine** (rotation, lifecycle CRUD,
deployment, enrollment — anything with ordered transitions or
paired/linked rows), (b) makes a **published-contract** claim (a
normative statement in docs / OpenAPI / changelog / a design doc — "a
second mint errors", "rejected outright, never truncated", "revocation
resolves the rotation state", "idempotent — does not re-emit"), or (c)
adds/changes a **classifier** (a substring allowlist, an enum switch, an
error→status map), do ALL of the following:
1. **Trace every normative claim to code.** For each "always / never /
must / rejects / idempotent" statement in the docs / OpenAPI /
changelog / design doc this PR touches, find the line that enforces it
and confirm it actually does. A claim is a CONTRACT, not a
description. #2284 shipped "a second mint errors" (no ceiling check),
"rejected outright, never truncated" (the MCP twin silently clamped),
and an OpenAPI `{id}` description that 404'd every real principal. If
doc and code disagree, ONE is a bug — say which; never assume the doc.
2. **Enumerate mutation × state for the machine.** List every mutating
operation the actor can invoke AND every state a linked/paired row can
be in, then walk the cross-product: does any combination wedge the
machine, orphan a partner, or drop to an unsafe terminal? Trace the
OUT-OF-BAND paths — a single manual revoke mid-rotation, a retry after
a lost response, a delete of a linked row — not just the happy
transitions. #2284 §7: a manual successor-revoke let the sweep
auto-revoke the principal's ONLY credential to zero; a manual
predecessor-revoke wedged the pair classifier.
3. **Prove classifier / allowlist completeness.** For a substring
allowlist or enum map: enumerate EVERY value it must handle — every
distinct `unexpected(...)` / error string the callee can emit, every
enum case — and confirm each is classified. A shared classifier must
be complete for BOTH transports (REST + MCP). A missed value defaults
silently to the wrong class: #2284 mapped a permanent "not found" to a
*retryable* error twice, on strings the allowlist missed. Require a
unit test that locks the mapping (grep the callee's error strings;
assert each maps to the intended class).
4. **Fail-visibility of a sole-enforcement path.** If a background /
periodic task is the ONLY thing enforcing an invariant (an auto-revoke
sweep, a reconcile loop), confirm its failures are observable — a
swallowed error that returns empty must still bump a counter / log, or
the invariant silently lapses with the alert at zero (#2284 M6).
## New-error-branch audit
If this PR adds any new 4xx/5xx error-response branch in a handler,
audit every response-body construction in the branch for information
disclosure. A denied/not-found fragment that echoes the caller's
permitted view is NOT safe if the rendering function itself queries
unfiltered data — this is how UP-11 shipped in the #222 hardening
round.
## Output format
Findings table with severity (CRITICAL / HIGH / MEDIUM / LOW / INFO),
file:line, description, recommended fix, and the four derivation facts.
Blocking is decided by the derived band per the shared preamble — do not
assert it from your own label. Also note any invariants the changes
*strengthen* that should
be preserved against future regression.
Report in under 800 words.
docs-writer preamble template
Full governance Gate 2 docs review of <N> commits on branch <branch>
at <repo-root>: <sha1>, <sha2>, ...
Use `git show <sha>` and `git diff <range>` to see the full scope.
## Your job
You are the mandatory docs reviewer for Gate 2. Read every modified
file and the related user-facing documentation. Per standing rule 2:
a user-facing behaviour change with no doc is `I7` — SHOULD by default,
BLOCKING when the omission conceals a breaking change, security-relevant
behaviour, data-loss risk, migration step, or an irreversible operation.
Do not assert a blanket BLOCKING.
You own WORDING everywhere prose appears, not only in documentation
FILES: in-code comments and log/error-message text are yours too
(standing rule 3), and you are the ONLY agent who files wording —
the others are told not to. The DOMAIN agent owns whether that prose
is TRUE: a comment that contradicts the code is theirs to raise, at
native severity. When you spot one, report it and say which agent owns
the truth call rather than sizing it yourself — Gate 3 and Gate 8
prompts carry your findings forward, so naming the owner is what
transfers it.
A required doc that is MISSING is a third category, not wording:
absence contradicts nothing, so it is a truth finding derived as `I7`
above, never capped at NICE (the `I7` cap at HIGH still applies).
"Required" is the six-item list in the shared preamble — checks 1–5
below correspond to items 1–5, and item 6 is a routed-concern row that
names a doc as an UPDATE OBLIGATION for the changed surface, operator-
OR author-facing (a migration ladder or per-surface invariants doc
counts), not merely as reading for the reviewer. Check 6 (in-code
prose) can never produce an absence finding.
Specifically verify:
1. REST API docs (`docs/user-manual/rest-api.md`) — endpoint signature,
request/response body, error paths, permissions
2. User manual feature sections (`docs/user-manual/*.md`) — operator
workflow changes, new CLI flags, new env vars, upgrade notes
3. Changelog — a `changelog.d/<PR#>-<slug>.<section>.md` FRAGMENT.
`CHANGELOG.md` itself is FROZEN: never edited directly, enforced by a
hook and the `Changelog fragments` CI job. Flag any direct edit to
`CHANGELOG.md` as BLOCKING. (See `changelog.d/README.md`.)
4. CLAUDE.md or a routed-concern row — new architectural invariants,
new stores, new ABI patterns, new release gates
5. Any audit action table, permission table, or error-code table
that the REST/store/plugin API contract touches
6. In-code prose the diff ADDS OR MODIFIES — comments, log lines,
error and user-facing strings: clarity, staleness, spelling, house
convention. Scoped to changed lines, NOT to every comment in a
touched file; on a large C++ diff the whole-file reading would
crowd out checks 1–5, which are the ones that produce the `I7`
findings that actually gate. Wording is capped at NICE. If the text
asserts something the code does not do, that is a contradiction:
report it and name the owning domain agent, who sizes it. Check 6
can never produce an absence finding
## Output format
Severity is DERIVED, per the shared preamble — state TRIGGER, IMPACT
(every `I` that applies), EXPOSURE (every `E`), and EPISTEMIC STATUS
for each finding, then the derived band and your own label. A missing
required doc is `I7`, sized there; do not restate the rule, apply it.
SHOULD-FIX = doc drift that would confuse an operator.
NICE-TO-HAVE = style/precision improvements, and all wording findings.
For each, quote current doc text (or "missing from X") and propose
replacement. Report in under 600 words.
Launch:
Agent (security-guardian): [above preamble + change-specific questions]
Agent (docs-writer): [above preamble + change-specific questions]
Gate 3 — Domain-triggered parallel review
Use the decision matrix below to pick agents. Launch all picked agents in a single message so they run in parallel. Always pass the Gate 2 preamble structure, plus the agent-specific focus.
Decision matrix
| Files touched | Agents to launch |
|---|---|
proto/, schema changes, plugin ABI headers | architect |
server/core/src/, cross-module refactor | architect |
Any C++ file (*.cpp, *.hpp, *.h) | cpp-expert, cpp-safety |
tests/, new fixtures, coverage gaps | quality-engineer |
meson.build, vcpkg.json, .github/workflows/, release tooling | build-ci |
agents/plugins/, plugin YAML defs | plugin-developer |
gateway/ (Erlang) | gateway-erlang |
| CEL expressions, scope DSL, trigger templates, YAML DSL spec | dsl-engineer |
| Windows-only / macOS-only code, cross-platform helpers | cross-platform |
| SQLite query paths, BFS/graph, hot authz paths | performance |
Raw resource/process/cast APIs in C++ (popen, system, fork/exec, CreateProcess, dlopen, LoadLibrary, open, socket, sqlite3_prepare, EVP_*, BCrypt*, LocalAlloc, yuzu_ctx_*, raw(), release(), reinterpret_cast, const_cast) | cpp-safety |
| Background thread or callback storing pointer/reference | cpp-safety, sre |
| Packaging, systemd units, Dockerfiles, installer scripts | release-deploy |
| New/changed REST route, MCP tool, dashboard fragment/page, or any other capability-adding operator surface | architect, security-guardian — both apply the ADR-1005 standing question (below) |
Standing rule — routed triggers are UNCONDITIONAL
Do not gate any routed-concern trigger, or any "always include" rule below, on diff
size or a materiality threshold. .claude/routed-concerns.md keys on file identity
and change type, because those files carry catastrophic-if-violated invariants
regardless of line count. Any roster trimming may only choose among agents those rules
did not already select.
A 2026-07 proposal to run a "core four" on small diffs was BLOCKed by two independent adversarial reviews, which produced these kill shapes — all "single-file, small, no public surface":
- 10 lines of
gateway/config/sys.configweakening management-listener client-cert verification.gateway-erlangdropped;cpp-safetyis useless on Erlang config; the PKI route calls a plaintext gateway a fleet-RCE edge. - A retention/prune tweak. The clock-guard row mandates
cpp-safety+sre+compliance-officer(#2360/#2361) — two of the three would have been dropped. - A one-line
.github/workflowsif:guard. The failure-path-guard invariant went silently dead for two months (#1038); that isbuild-ci's domain. - Any small C++ diff, because a "core four" contains no portability reviewer — the exact gap that shipped #2580's macOS break.
Rationale and the full review record: docs/governance-skill-tuning-2026-07.md.
Always include architect when any public store contract or REST API surface changes — the duplicate-validation and error-mapping drift patterns recur.
Always apply the ADR-1005 standing question on any capability-adding diff: is every behavior of this capability reachable by an authenticated external principal via versioned REST and MCP, or a recorded exception in ADR-1005's exception ledger; is it discoverable (A2/A3 — enumerable via /api/v1/openapi.json / MCP tools/list); does it carry the A4 error envelope; is there no in-process-only behavior; are RBAC and audit enforced at the API layer (not only in the UI)? A dashboard fragment is not an API twin. (Policy: docs/adr/1005-headless-platform-use-case-engines.md; current phase status: docs/adr-1005-execution-plan.md — both land with PRs #1918/#1926; do not merge this wiring before them.)
Always include quality-engineer when new features or fixes land — it's the only agent that flags fixture races, bad error-string substring asserts, and REST-handler-untested-through-store-tests, which are the three highest-ROI test gaps.
Always include performance for anything that touches get_*_ids, SQLite BFS, or per-authz hot paths.
Always include cpp-expert and cpp-safety when C++ files change.
The roles are separate: cpp-expert reviews language idiom and compiler
portability; cpp-safety reviews ownership, lifetime, C ABI borrowed
data, syscall/process boundaries, casts, thread teardown, and sanitizer
coverage.
For C++ safety-sensitive diffs, ask quality-engineer to require
tests for cleanup paths, partial failure, short read/write, EINTR,
failed pclose, failed CloseHandle, failed sqlite3_prepare, and
concurrent teardown where relevant. New RAII wrappers should have a
test or compile-time assertion covering move-only/non-copyable behavior
when feasible.
Gate 3 agent preamble
Each Gate 3 agent gets the same structural preamble, varying in the "Your job" stanza:
Full governance Gate 3 <agent-type> review of <N> commits on branch
<branch> at <repo-root>: <sha1>, <sha2>, ...
Read `git show <range>` for the full diff.
## Context
<paste Gate 1 Change Summary here verbatim so the agent doesn't
re-derive what's in scope>
<paste any already-completed Gate 2 findings as "for your context only,
do not duplicate">
## Your job — <agent-specific focus>
<agent-specific questions, 5-10 numbered items>
## Output format
Findings with severity (BLOCKING / SHOULD / NICE / INFO), file:line,
description, recommendation. Report in under <N> words.
Pass prior gate findings as context — the governance policy in CLAUDE.md requires this to avoid duplicated effort. Extract each prior finding ID (sec-H1, doc-B3, etc.) and summarize one line per finding.
Gate 4 — Correctness & resilience (mandatory, parallel)
Always run all three: happy-path, unhappy-path, consistency-auditor. Launch in one message.
These three are the highest-value reviewers in the Yuzu pipeline. Prior runs confirm:
- unhappy-path catches compound failure modes that no single-agent review finds (concurrent + corrupt DB, TOCTOU + I/O error).
- consistency-auditor catches cross-component drift: REST+store duplicate-validation divergence, audit field-order regression, 404-vs-403 oracle mismatch between sibling handlers, test assertion substring laxness.
- happy-path catches the "my new fix breaks the no-op PUT" and "my retry returns 404 instead of idempotent 200" kinds of mundane correctness.
happy-path preamble
Full governance Gate 4 happy-path review. <N> commits on branch <branch>
at <repo-root>: <sha1>..<shaN>.
`git show <range>` covers the full scope.
## Context — prior gate findings (for your context only, do not duplicate)
<one-line summary per Gate 2/3 finding>
## Your job — normal-path logic completeness
Trace every happy path through the changed code and verify the logic
is complete and correct:
1. For each new or modified endpoint, trace request -> auth -> perm ->
store lookup -> store write -> audit -> response. Every step.
2. For each new store method, trace the non-error path end-to-end on
representative inputs.
3. For new CLI flags / env vars, trace parse -> validate -> apply ->
log-at-startup -> effect-on-runtime.
4. Compare the new success-path to the pre-commit success-path. What
did the commit change that is visible to a normal-case caller?
Call out idempotency semantics explicitly — new error-handling that
changes a retry from 2xx-on-duplicate to 4xx-on-duplicate is a
breaking API contract even if the initial call still succeeds.
## Output format
Pass / Findings list. Severity: BLOCKING / SHOULD / NICE.
Under 600 words.
unhappy-path preamble
Full governance Gate 4 unhappy-path review. <N> commits on branch
<branch>: <sha1>..<shaN>.
`git show <range>` for the full scope.
## Context
<Gate 1 Change Summary verbatim>
<Gate 2/3 findings as "already covered, do not duplicate">
## Your job — failure-mode interrogation
You are the unhappy-path reviewer. Your mandate is to imagine every
way these changes could fail in production and produce a risk register
for Gate 5 chaos-injector. Don't propose fixes for things that are
working — propose failure scenarios and the observable symptoms.
Focus on compound failures where two or more risks interact:
- concurrent writers + partial SQLite failure
- TOCTOU between get-then-check and the write
- empty/whitespace/NUL-byte input that bypasses validation
- pre-existing corrupt DB state that the fix assumes is clean
- retry storms / idempotency under connection reset
- storage-layer failure masked as "not found"
- audit detail unescaped -> stored XSS on dashboard render
- MCP token scope confusion vs principal match
If this PR touches a STATE MACHINE (rotation, lifecycle CRUD,
deployment, enrollment — ordered transitions or paired/linked rows),
also enumerate **mutation × state**: every mutating op × every state a
linked/paired row can be in, and walk the cross-product for a
combination that wedges the machine, orphans a partner, or drops to an
unsafe terminal (e.g. zero credentials). Prioritise OUT-OF-BAND paths —
a single manual revoke/delete of one linked row mid-transition, a retry
after a lost response — over the happy transitions (see the security
preamble's "Design-contract & state-machine tracing" check; this is how
#2284's §7 auto-revoke-to-zero and pair-wedge defects shipped past an
earlier /governance run).
## Output format
Risk register with entries shaped as:
- **ID** (UP-N)
- **Risk** — one-sentence description
- **Trigger** — how it happens
- **Symptom** — what the operator/user observes
- **Severity** — BLOCKING / SHOULD / NICE
- **Chaos scenario** — suggested chaos-injector test, or "N/A"
Aim for 12-20 entries. Under 900 words.
consistency-auditor preamble
Full governance Gate 4 consistency review. <N> commits on branch
<branch>: <sha1>..<shaN>.
Read `git show <range>` for the full diff.
## Context
<Gate 1 Change Summary verbatim>
<Gate 2/3 findings as "already covered, do not duplicate">
## Your job — cross-component consistency
You are the consistency auditor. Your mandate is cross-component
state, schema, and contract consistency. Check:
1. **Sibling-handler parity** — if the PR modifies handler X, find
every OTHER handler that performs the same semantic operation and
verify they apply the same auth/validation/audit pattern.
2. **Error message string parity** — store-layer error strings vs REST
error envelope vs docs vs test assertions. Any drift = a rename
will silently break docs while tests still pass.
3. **Audit field order / naming parity** — any new `.log({...})`
emission site must match the AuditEvent struct declaration order
and the field names used elsewhere. `principal_role` must match
the session's actual role, not a hardcoded string.
4. **Auth role constant parity** — `auth::Role::admin` vs RBAC vs
`is_global_admin` — one convention across the codebase.
5. **Schema / protobuf / wire-contract untouched?** — if yes, verify
no downstream consumer breaks; if no, flag for architect.
6. **Test fixture pattern parity** — new test files should match the
existing `unique_temp_path` helper or equivalent; shared hardcoded
paths are a parallel-test race.
7. **Changelog fragment** present and well-formed — `changelog.d/<PR#>-<slug>.<section>.md`,
valid section, `CHANGELOG.md` untouched. (The old `[Unreleased]`/reverse-chronological
invariant is ABOLISHED — the file is assembled at release from fragments.)
8. **ADR-1005 headless-platform parity** — for any capability this PR
adds or changes: is every behavior reachable by an authenticated
external principal via versioned REST *and* MCP, or a recorded
exception in ADR-1005's exception ledger; is it discoverable
(A2/A3 — enumerable via `/api/v1/openapi.json` / MCP `tools/list`);
does it carry the A4 error envelope; is there no in-process-only
behavior; are RBAC and audit enforced at the API layer (not only
in the UI)? A dashboard fragment is not an API twin.
9. **A5 agentic context contract** (exec-plan Decision 16) — for any
new or materially changed MCP tool ("material" = any change to
tier, securable/operation, dispatch behavior, side-effect set, or
spec-visible `tools/list`/`initialize` output — per-se, not
arguable): standard spec annotations (`title`/`readOnlyHint`/
`destructiveHint`/`idempotentHint`/`openWorldHint`; destructive/
idempotent semantics machine-readable, never prose-only),
decision-grade description (when to use and which sibling to use
instead, workflow chaining, empty-result meaning, snapshot vs live,
terminal vs retryable errors: the five-question checklist in
`docs/agentic-first-principle.md` §A5 item 2, every claim verified
against the code; `[a5]` in `test_mcp_dispatch_coverage.cpp` is the
machine floor for registry-resident tools only), bounded documented input schema, typed
output schema for stable shapes, honest `retry_after_ms` on
retryable errors; if the PR adds a tool family or reshapes the
operating model, the `initialize.instructions` blob is updated in
the same PR. Contract text: `docs/agentic-first-principle.md` §A5.
security-guardian co-checks `readOnlyHint`/`destructiveHint`/
`idempotentHint` truthfulness against tier + dispatch behavior —
a false safe-direction hint derives `I4` (harmful operator guidance).
10. **Published-contract vs code, and classifier completeness** (see the
security preamble's "Design-contract & state-machine tracing" check).
For every normative claim this PR touches in docs / OpenAPI /
changelog / a design doc ("a second X errors", "rejected outright,
never truncated", "idempotent — does not re-emit", a `{id}`/param
format), trace the enforcing line and confirm the code actually does
it — a claim is a CONTRACT; if doc and code disagree, ONE is a bug,
name which. For any substring allowlist / enum→status map this PR adds
or changes, enumerate EVERY value the callee can emit (grep its
`unexpected(...)` strings / enum cases) and confirm each is classified
the same on BOTH transports — a missed value silently defaults to the
wrong class (#2284 mapped a permanent "not found" to a retryable error
twice). A shared classifier of this kind must have a unit test locking
the mapping.
## Output format
Findings with severity (BLOCKING / SHOULD / NICE), file:line,
description, recommended action. Under 700 words.
Gate 5 — Chaos analysis (conditional)
Skip Gate 5 if neither unhappy-path nor consistency-auditor produced findings. If either did, run chaos-injector with the full risk register as input.
Chaos is a test-design producer, not a runtime executor. It synthesizes the unhappy-path findings into prioritized chaos scenarios with success criteria and rollback procedures. Use the output to:
- File P0 scenarios as issues with "must run before release" labels
- File P1/P2 scenarios as tracked hardening backlog
- Note any scenarios that are "verify by code read" — resolve them yourself without filing
chaos-injector preamble
Gate 5 chaos analysis. <N> commits on branch <branch>: <sha1>..<shaN>.
Your input is the unhappy-path risk register and consistency-auditor
findings. Your job is to synthesize them into executable chaos
scenarios with success criteria and rollback procedures — NOT to run
the chaos yourself, but to produce the test design document that a
future chaos run would execute.
## Unhappy-path risk register
<paste all UP-N entries verbatim from Gate 4 unhappy-path output>
## Consistency-auditor findings
<paste all C-N entries verbatim>
## Superseded
<list any UP-N / C-N entries that are CLOSED in working tree fixes,
so chaos doesn't author scenarios for things already resolved>
## Your job
Produce a chaos test design with these entries. For each scenario:
1. **ID** (CH-N)
2. **Hypothesis** — invariant we want to verify under fault injection
3. **Injection** — specific fault, tool, parameters (VFS shim, sqlite
pragma, kill signal, breakpoint sleep)
4. **Setup** — pre-condition DB/fixture state
5. **Trigger** — the action(s) that expose the fault
6. **Success criteria** — observable post-conditions proving invariant
7. **Rollback** — how to restore safe state (git reset? DB restore?)
8. **Severity / phase** — P0 block-merge, P1 pre-release, P2 nightly. P0 is a
scenario-planning label, NOT a gate: a chaos scenario blocks only if the
underlying finding derives CRITICAL/HIGH or hits a policy floor.
Focus on scenarios where two or more unhappy-path risks compound —
individual fault injection in isolation often misses the real
production failure mode.
Also produce a short "scope decision" recommendation: which of P0/P1
scenarios should block the current PR's push-to-origin, vs which to
file as follow-up issues for the next release gate.
Report under 1000 words. Do not run any code — this is a planning doc.
Gate 6 — Operational review (mandatory, parallel)
Launch all three in one message: compliance-officer, sre, enterprise-readiness.
Each agent gets the same Gate 1-5 context and focuses on a different aspect:
- compliance-officer — SOC 2 control alignment, evidence chain, audit traceability
- sre — observability (metrics, alerts), recovery paths, health probes, capacity
- enterprise-readiness — customer-facing assurance, pilot-visible rough edges, upgrade notes, breaking changes doc coverage; also reviews the A5 exception ledger (
docs/agentic-first-principle.md§A5 Exceptions) — every entry must carry an issue number + revisit-by date; stale or undated entries are findings
Use the same structural preamble as Gate 4 agents, vary the "Your job" stanza to the agent's domain.
Watch for: sre routinely catches pre-existing readiness-probe gaps that become gating because the PR makes an existing store more load-bearing (they derive I5/I1 once the store is on a live path). The HC-1 pattern (store missing from /readyz) reappears — always verify the new store(s) in scope are in the probe conjunction.
Watch for: enterprise-readiness flags breaking-changes-without-upgrade-note more reliably than other agents. If the PR changes non-admin behavior, a changelog FRAGMENT carrying the Breaking entry (changelog.d/<PR#>-<slug>.changed.md or .security.md, body led with **Breaking —**) plus a docs/user-manual/server-admin.md upgrade note is almost always required. Do NOT ask for a CHANGELOG.md section — that file is frozen and edited only at release.
Gate 6b — Synthesis pass (presentation only)
A full run produces on the order of 45 non-blocking findings, each as its own block of
prose, with the same defect frequently reported by two or three agents at full length.
On #2580, four of six round-1 BLOCKINGs arrived 2–3 times over. All of the triage
landed on the operator, and workflow-orchestrator — which exists for exactly this —
was never invoked.
Run it now, over the raw reports:
Agent (workflow-orchestrator): Synthesise the attached Gate 2/3/4/6 reports into a
single severity-ordered table for the operator. Preserve EVERY source report verbatim
as an appendix — you are changing presentation, not content.
Cluster two findings ONLY when they share the same file:line AND the same defect.
Anything else stays separate. For each cluster: list its reporting agents, take the
MAXIMUM **derived** severity of its members (record the native labels alongside),
and do NOT re-adjudicate severity or dismiss a
finding. Mark every cluster PROVISIONAL.
Three rules, all load-bearing:
- Same
file:lineAND same defect. Never "same theme". On #2580, the BLOCKING for the incomplete REST classifier and the BLOCKING for the hardcoded MCP retry hint summarise almost identically and needed separate fixes and separate tests — a synthesiser merging on theme would have hidden one of them. - Max severity, never re-adjudicated. The synthesiser has not read the code.
- Clusters are provisional; the operator confirms equivalence. The synthesiser is not the authority on whether two findings are the same finding.
Convergence is the strongest confidence signal this pipeline produces — "found independently by three agents" is why a finding gets acted on without re-derivation. This pass keeps that signal and drops the re-reading; it must not launder it.
But count only INDEPENDENT reporters. This pipeline manufactures correlation on
purpose: Gate 3 is handed Gate 2's findings and Gate 4 is handed Gate 2's and Gate
3's, all "for your context only, do not duplicate". An agent that was SHOWN a
finding and agrees is an echo, not a confirmation. The test is not having been
shown it: agents in the SAME parallel wave qualify, because they could not see
one another, and so does any reporter of any source who was not shown it — a
collaborator or an external model reviewing the change cold is in no wave at all,
and counting them zero inverts the signal for the strongest evidence available.
So the attribution line reads independently: 2 of 4 (Gate 4 wave); echoed: 1 downstream, never a bare count. A finding echoed by five downstream agents and
raised independently by one is a ONE-agent finding. Record independent_reporters
in the ledger, not just reporter.
This cuts both ways and neither direction is safe to assume: correlated reviewers overstate confidence, and a reviewer that defers to a peer's partial conclusion can withdraw a finding that was correct. Both have happened here inside a month — three reviewers confirming a false claim because they shared one stale working tree (#2604), and a reviewer dropping a true finding on a peer's incomplete evidence while that peer was independently confirming it (#2622). Neither is visible from the output. When it matters, measure the claim yourself rather than counting who agreed.
Gate 7 — Findings Resolution
BLOCKING = the derived band is CRITICAL or HIGH (shared preamble), or a policy floor was hit. Resolve against the derived band, not the reporting agent's native label — record both. An agent brief that says its own CRITICAL/HIGH "blocks merge" does NOT self-certify: that text predates standing rule 2 and is superseded by the derived band. The only non-derived blocker is a policy floor or an explicit operator instruction.
Strategy:
- Fold compatible fixes into one commit. If sec flags H1, docs flags B3, QA flags B5, and they all touch related files, fix as a single "hardening round" commit rather than three small ones.
- Re-run Gate 2 security on the hardening round. Prior runs have caught HIGH regressions introduced by the fix commit itself. Always re-review.
Deciding what happens to a NON-BLOCKING finding
This step is THIRD. Establish first, in order: is the finding valid; what is its provenance; what band does it DERIVE to; does it hit a policy floor.
A gating finding is never deferred and never dropped. A derived CRITICAL/HIGH, or any policy floor, is fixed — or the change itself is withdrawn or re-cut. Nothing below is a waiver and no ledger row makes a blocker optional; Gate 8's rule is unchanged.
An INVALID finding — false, inapplicable, or disproven — is rejected with the
evidence. At a derived CRITICAL/HIGH, or on a policy floor, rejected additionally
requires an adjudicator recorded in adjudicated_by who is not the author, not the
agent that raised it, and not the party arguing the rejection. That is STRICTER than
the floor exception at the top of this file ("an agent other than the one proposing
it") and does not claim to restate it — an earlier revision asserted the two were
the same separation and they are not. Otherwise "inapplicable" is a self-granted
waiver, and the dangerous disposition ends up cheaper than the safe one.
Everything below applies ONLY to findings that are valid and non-blocking.
Test 1 — does the fix open an independently reviewable surface?
Folding keeps the fix in the SAME review pass. That is cheaper than a second pass; it is NOT a claim that corrections are cheap to get right — Gate 8 re-routes every fix diff through all touched domains precisely because they are not.
The cost is in a fix that introduces a surface a reviewer must reason about on its own:
- new authority or privilege
- new persistent state, or a new ownership lifecycle
- new external I/O, or a new protocol
- a new public contract or compatibility boundary
- a new dependency, process, thread, or deployment requirement
Completing an existing mandatory seam is not one of these, even when the edited
code is technically a probe or a gate. Adding a newly load-bearing store to the
/readyz conjunction is the reference case: it is a probe, it is a correction, and
it folds. A metric or alert riding an already-exposed endpoint folds too; a new
exporter, dashboard or alert-routing path is a new surface and splits.
If a bullet matches, it splits — arguability does not rescue it. A fix that carries a credential, makes a network call, or interprets an auth status is never seam-completion. Only a finding that matches NO bullet and is still arguable folds, and then Gate 8's routing decides the review cost.
Test 2 — can the ACCEPTED SCOPE still be satisfied without it?
Not "is the change still worthwhile" — that is a preference, answered by whoever benefits from saying yes. Anchor it to the envelope fixed BEFORE the findings arrived:
- the originating issue's or ADR's requirements
- user-facing and changelog claims
- Gate 1's declared interfaces, behaviour, and security impact
- any normative repository invariant
An anchor the change plainly implies but did not declare counts as present. Gate 1 is written by the author before findings arrive, so an under-declared Gate 1 would otherwise shrink the scope pre-emptively and make every finding outside it "not needed". Where the envelope is SILENT on something the change clearly touches, that silence is an adjudication trigger, not a licence — the same direction the Absences rule takes elsewhere in this file.
If satisfying the envelope requires withdrawing a claim or an acceptance
criterion, that is a scope change: explicit non-author adjudication and a re-cut,
not ordinary deferral. Strip the withdrawn claim from the changelog fragment, the
user docs and Gate 1's declared impact in the same change — a narrowed change still
advertising the original control is I6 false assurance.
The dispositions
Non-blocking findings only. A gating finding has no cell in this table.
| Accepted scope needs it | Accepted scope does not | |
|---|---|---|
| No independent surface | Fold | Fold if trivial — a one-line or mechanical change adding no new branch or condition — and in a file already touched; otherwise its own small change, or file it |
| Independent surface | RE-CUT (below) | Split — its own change and its own review; or file it |
The expensive mistake is the bottom-right: an independent surface folded into a
change whose scope did not need it. Measured on #2581 — a bearer-token probe folded
into a 41-line assertion fix produced six further blocking findings across two more
rounds, none of them in the original change, and the branch was re-cut anyway. Note
what the probe brought: a persisted credential, an authenticated network call, and
status-code semantics. New authority, new state, new I/O. The corrections in that
same branch ran to 287 insertions (6bf7e5d2~1..315247e3, scripts/ tests/) and
converged. Line count is not the variable; surface is.
Re-cut, concretely. The discriminator is WHICH CHANGE OWNS THE ORIGINAL ACCEPTANCE CRITERIA — the mechanism does. Without that it is a stacked split with a new name. Then:
- the remainder goes first, as a prerequisite that must have standalone value AND
standalone safety; a prerequisite that is only reachable-but-inert is a dormant
half —
I6base MEDIUM, which GATES only under the false-assurance or dormant-authorisation raises, so check which applies rather than assuming it gates. On dispute, default to landing the two together - its changelog fragment must not claim the withheld behaviour
- governance runs on the prerequisite independently, and again on the integrated range
Three further split rules, stated here for the first time — they are NOT restatements of existing practice:
- a behaviour change and its observability are two changes, behaviour first
- a behaviour change and the refactor that makes it testable are two changes, refactor FIRST
- a new REST route, MCP tool, store, proto change, schema migration or plugin ABI change gets its own review unit, WITH the wiring that makes it reachable — "alone" never means landing a dormant half
Filing, parking, and why the default matters
Filing is right for separable work with a stated definition of done. Follow
docs/agents/issue-standard.md, which is authoritative on shape and volume:
one actionable outcome per issue, split bundles, dedupe is the only inflow filter.
For valid work that is real but will not be scheduled, the existing roadmap type
is the disposition — parked on the roadmap Project, no priority, no triage state,
excluded from the active backlog, and crucially retained in the
duplicate-detection snapshot, so the next run touching that area surfaces it.
That is the resurfacing mechanism: proximity, not a calendar.
Parking is CONSTRAINED. Two constraints, stated HERE because this is where the disposition is decided. The procedure that carries them out holds the command and the check but not the rule — every previous revision put the rule in one place and an echo of it in the other, and the echo went stale every time, most recently a summary that dropped the band-independence clause in constraint 1, which is the half that does the work.
roadmapis unavailable for any finding carryingI1,I2orI3in its ledgerimpactlist, whatever its derived band. A finding lands at MEDIUM when its EXPOSURE is rare, not when its consequence is small. A rare path to a failed security control, to data loss, or to a silent wrong answer gets a priority, not a park.- Escalate on second sighting. If the mandatory dedupe probe turns up an
existing
roadmapissue for a finding a later run raises again, that recurrence is the signal it is not going away: fix it, or promote it out ofroadmapwith a priority. Never re-park. This bounds the failure at ignored-once.
Over 300 open issues already carry the label, so both matter. That is a floor rather than a share on purpose: an earlier draft said "a third of the tracker", which was last true around 2026-07-20 and was already stale when written — measured at 338 of 1281 open, the parked set had not grown at all while the open count rose by 233.
Constraint 1 is checkable against the ledger, and Gate 8 step 4 does it. Constraint 2 is not: it needs the dedupe probe's result. Neither is the label contract on the park command in that procedure, which lives on GitHub and is not a constraint here at all. Those last two stay procedural — see step 4, which states its own blind spots.
Neither the number of issues nor the number of parks is a target. What is required is that every valid finding ends somewhere recorded — fixed, filed, linked to an existing issue, or parked under the two constraints above.
Record provenance on every finding, and state the split in the run report.
introduced / newly-reachable / pre-existing is already a required ledger
field and is the only way to tell a change that introduced defects from a change
that merely touched a weak area. Without it, "this run produced forty findings" is
unattributable, and the reflex is to blame the diff. On #2581 the substantial
majority were pre-existing, which is a fact about the harness, not the fix.
This file is the canonical runbook. A separate Codex-side runner exists at
.codex/skills/governance/SKILL.md; for the blocking contract it already defers
here, which is the right shape. Its disposition rule for MEDIUM/SHOULD findings is
restated rather than deferred, so it can contradict this section — closing that is
for whoever owns that runner.
Why the pipeline is run as a pipeline
Use /governance <range>, not hand-run gates: waves 1-4 shipped 4 CRITICAL
command-injection vulnerabilities without it.
The copies, enumerated — and why the list itself matters
All four standing rules, and the ledger schema, are defined ONCE: here. These are POINTERS and lose on conflict:
CLAUDE.mdandAGENTS.md(the "Agent Team & Governance" section)governance.d/README.md- every agent brief in
.claude/agents/ - any
changelog.d/fragment describing a governance change docs/governance-skill-tuning-2026-07.md
The last two were originally omitted from this list, and they are exactly the copies that drifted — a copy-currency rule only reaches the copies it enumerates. Adding a new restatement anywhere means adding it to this list in the same change.
What the Codex runner defers, and what it does not
.codex/skills/governance/SKILL.md genuinely defers for severity and the ledger
only. It carries its own text for standing rules 1 and 4:
- Rule 1: there is no routed-concerns walk at all on that leg — its
## Domain Routingis an independently-authored heuristic list, and none of.claude/routed-concerns.md,.claude/routed-concerns-access-control.md,.claude/routed-concerns-security-posture.mdor.claude/routed-concerns-software-estate.mdis referenced anywhere in that file. Tracked as #2684. This is the only record of that gap in the tree. - Rule 4: a weaker Gate 8 phrasing ("re-run affected gates") — precisely the formulation that shipped the broken macOS leg on #2580.
A runner never told to load a rule has no conflict to lose, which is why this is a gap to close rather than a contradiction to adjudicate.
Gate 8 — Iterate And Ledger
-
Re-run every gate whose DOMAIN THE FIX DIFF TOUCHES — not only those whose findings prompted the fix. A fix that adds a language feature, a dependency, a thread, or a platform-specific call re-triggers the corresponding agent even if that agent raised nothing in round 1.
Concretely, against the fix diff (not the original):
- Gate 3 — re-run the decision matrix, including all four routed-concern
tables:
.claude/routed-concerns.md,.claude/routed-concerns-access-control.md,.claude/routed-concerns-security-posture.mdAND.claude/routed-concerns-software-estate.md. Opening only the first misses every auth, access-control and request-admission invariant; skipping the third misses every security-posture invariant; skipping the fourth misses every Forensics/per-user-software-data invariant. - Gate 2 —
security-guardianalways;docs-writerwhenever the fix touches a doc, a changelog fragment, a user-facing string, or in-code prose. - Gates 4 and 6 — re-run an agent when the fix changes behaviour in its
domain:
happy-path/unhappy-pathon any logic or error-path change,consistency-auditoron any cross-surface or contract change,sreon any metric, alert, probe or thread change,compliance-officeron any audit or evidence change,enterprise-readinesson any operator-visible behaviour or upgrade-note change. - When in doubt, re-run it. A skipped re-review is how the fix round ships its own defect.
This rule exists because the old one ("only the gates whose findings would be affected") shipped a broken macOS leg on #2580. Gate 8 ran the four agents whose findings had been fixed;
cpp-expert, the portability reviewer, had only ever seen commit 1.std::jthreadwas introduced in commit 3 as a fix for a Gate 8 finding and broke Apple Clang, whose libc++ has nostd::jthread— every other use in this codebase sits behind#ifdef __cpp_lib_jthread. No agent was ever asked whether the fix was portable. - Gate 3 — re-run the decision matrix, including all four routed-concern
tables:
-
Don't commit until governance passes. Per CLAUDE.md.
-
Record every finding in the run ledger. One JSONL object per finding, in a repo-committed fragment on the
changelog.dmodel (#2618):# Default: a fragment in the repo, committed with the work it reviews. # Override to a scratch dir for a throwaway local run you will not commit. GOV_DIR="${YUZU_GOV_LOG_DIR:-governance.d}" mkdir -p "$GOV_DIR" # O_EXCL must protect the path that is actually COMMITTED. `mktemp` on a stem # followed by `mv "$X" "$X.jsonl"` does NOT: mv overwrites silently, so a # suffix collision destroys the earlier run's findings with no error at all. # `mktemp -u` supplies only the random stem; `noclobber` does the atomic create. LEDGER="$(mktemp -u "$GOV_DIR/<PR-or-issue-number>-<short-slug>.XXXXXX").jsonl" (set -o noclobber; : > "$LEDGER") \ || { echo "ledger exists, refusing to overwrite: $LEDGER" >&2; exit 1; }Do not "simplify" this to
mktemp "$GOV_DIR/….XXXXXX.jsonl". GNUmktempacceptsXs mid-template; BSD/macOSmktemprequires them trailing, and this repo ships macOS. The two-step exists for portability — the bug was doing the second step withmvinstead of an exclusive create.The
noclobberredirect is what makes the guarantee: the committed.jsonlpath is createdO_EXCL, so a suffix collision FAILS LOUDLY instead of overwriting. Uniqueness is enforced by the filesystem rather than assumed from a timestamp. One file per RUN, not per PR: Gate 8 iterates,pass_ordinaldistinguishes rounds inside a file, and a fresh run gets a fresh fragment.Every write after the create is an APPEND. Never
>.printf '%s\n' "$ROW" >> "$LEDGER" # the ONLY way to add a rownoclobberabove is scoped to its subshell and protects the CREATE only — the same idiom reused outside it truncates silently at exit 0 (measured). Concurrent>>appends are safe on a local filesystem (measured; no network filesystem tested); it is read-modify-write that loses rows, which is why the supersede rule below forbids editing a row in place.A row is SUPERSEDED, never edited. A disposition that changes after the fact — a finding later fixed, deferred, or refuted — is a NEW row carrying the same
finding_id.The live view of a finding is FIELD-WISE last-write-wins across every row sharing its
finding_id, ordered byrecorded_at— not the latest row alone. A row with norecorded_atpredates #2619: it sorts BEFORE every timestamped row, in file order among its peers — mixed-generation fragments exist and need a total order. That distinction is load-bearing: a superseding row restates only what changed, so "the latest row is the live one" would make a floored, gating finding read as ungated and unclassified the moment afixedrow omittedseverity_mappedandpolicy_floor. Merge; do not replace. Ties, which should not occur, break on the higherpass_ordinal.List fields REPLACE wholesale, they do not union.
impactandexposureare the two. A supersession restatingimpact: ["I8"]over["I2","I5"]yields["I8"], not all three. Two conforming readers, one unioning and one replacing, would otherwise produce different live views from the same bytes; the same "an unstated convention means no reader can be right" that settled the row rule settles this one.ATTESTATION FIELDS ARE ROW-SCOPED AND EXEMPT FROM THE MERGE. The five are
adjudicated_by,adjudication_rationale,refuted_by,refuted_by_reporterandwaiver_rationale. They are NOT properties of the finding, so merging them forward is a category error: an attestation attaches to the ACT it records or justifies — this de-escalation, this refutation, this waived pass — and a reader binds each to the row that performed that act. They are never inherited by a later row and never cleared by one. (waiver_rationalewas missed when this rule first said "four": it justifies an act exactly as the others do, and leaving it in the merge let a later row null the only record of WHY a gating finding was allowed to pass — undetectably, since it carries norequired iff.)Without that exemption the guard erases itself: append a row nulling
adjudicated_by, and the live view shows a de-escalated finding with no attestation, while gate and band are unchanged — so the gate-or-band property does not fire. Measured on this change's own ledger, where the rows that withdrew two adjudications did exactly that, and the commit that wrote them called it a worked example. Every prior round of this defect was "a route that moves the band or the gate"; this one is a route that removes the control from a finding already moved, which is why naming the gate as the property did not reach it.To withdraw an attestation you supersede the ACT it approved — restate the facts or label it authorised, back to where they were. You cannot retract the signature and keep the effect. A WRONG attestation (a typo, the wrong name) is corrected the same way: supersede the act, re-perform it under the correct attestation; the signature itself is never edited. Retroactive ADDITION is closed by a different clause —
required iff the ROW de-escalatesbinds an attestation to the row performing the act, so one appended later attaches to nothing and the unattested de-escalation stays reportable.This class is closed by the schema AS IT STANDS: exactly the five fields above carry attestation semantics today. The first version of this sentence said four and called the class closed;
waiver_rationalewas found one round later. So treat any NEW rationale- or attestation-like field as joining the exemption by default — the question is settled per field, never assumed away.De-escalation — the guarded property is THE GATE, not a list of fields
READ THE MERGED VIEW AT THE STRONGER OF ITS FACTS AND ITS LABEL. The label is 3-valued and bands are 5-valued, so each label denotes a SET:
BLOCKING= {CRITICAL, HIGH},SHOULD= {MEDIUM},NICE= {LOW, INFO}.- Derived band INSIDE the label's set → they agree; the derived band governs.
- Derived band OUTSIDE it → they disagree. The finding is read at the stronger of the derived band and the label's FLOOR (HIGH / MEDIUM / LOW respectively), and the disagreement is itself reported.
Comparing against the floor alone would be wrong, not merely conservative: an
I9finding labelledNICEderives INFO, which is below LOW, so a floor comparison reports a disagreement on every correctly-recorded NICE row. Two rows in this change's own ledger did exactly that.impact: []or a null fact set derives INFO. Apolicy_floorpresent anywhere in a finding's history gates until explicitly and adjudicatedly cleared.Disagreement between facts and label is not resolved in the writer's favour — it resolves upward, and it is itself a finding about the ledger. For a CONFORMING writer the two can never disagree, because
severity_mappedis defined as the derived value; this rule exists for the non-conforming writer, and that is exactly the case round 5 measured (a label restated unchanged beside weakened facts). So: when the facts change, restate the label. A stale label is read at the stronger value and is reported.Any supersession that WEAKENS THE GATE OR THE BAND requires an
adjudicated_bywho is not the change's author, plus anadjudication_rationale. The guarded property is "would this row make the finding less likely to stop the merge" — the band is the usual mechanism but it is NOT the only one, and most of the routes below are band-NEUTRAL. (No count: two earlier counts of this list both went stale.) Known routes, non-exhaustive:severity_mappedrestated downwardimpactorexposurerestated to weaker values — noteE6caps at LOW and dominates every raise, soexposure: ["E6"]alone is a de-escalationseverity_mappedrestated UNCHANGED beside weakened facts. Band-neutral under the stronger-of rule, and still a de-escalation attempt: it is the shape round 5 shipped, and the requirement was never "restate the label"epistemic_statusflipped tospeculative— band-neutral by design (EPISTEMIC STATUS operates on the GATE, not the band) and it converts a blocker into a deferred investigation, which is the whole point of guarding itprovenanceflipped topre-existing— band-neutral, and it demotes two policy floorspolicy_floorcleared — band-neutral, and it is the floor- a sentinel released:
exposureortriggermoved fromunresolvedto a concrete value. Band-neutral, and it lifts a gate — unresolved EXPOSURE "GATES pending adjudication", so supplying the resolution IS the adjudication and needs the same independence. Defaulting an unknown toE3unattended is precisely what the absences rule forbids - a terminal
dispositionofrejectedordeferred-to-issue #Nover a live gating row commit_rangeorreviewed_at_shaset tounresolvedby the author — it voids the only verifiable half of the adjudication guard below (the self-naming check reads git authors over the range), so it weakens the gate by disarming its own precondition
A new field, or a new route, must be tested against the PROPERTY — does it weaken the gate or the band, OR remove an attestation from a finding that has already been de-escalated (structurally prevented by the exemption above; stated here so a schema change that reintroduces merged attestations is caught by the property rather than rediscovered) — and added to this list when it does. The list is openly incomplete; treating it as closed is what let round 5 ship.
What the adjudication requirement actually achieves — read this before relying on it. It is an AUDIT TRAIL, not a verified control. It makes a de-escalation attributable and reasoned in writing, and a reader with the repo can detect literal self-naming by comparing
adjudicated_byagainstgit log --format='%an'overcommit_range. It verifies nothing beyond that: the field is free text, and anadjudicated_bynaming a governance agent never matches a git author, so the self-check passes vacuously. A subagent of the authoring session is not independent — it is the same actor under another name. Independence here is ASSERTED, and the assertion is worth recording; do not describe it as enforced.Why the property and not another guarded field: eight rounds of this rule's own history — each guarded one mechanism and was beaten by the next; the property is what survived. The full sequence, the measurements, and the two lessons (name the OUTCOME, not the mechanism; then keep checking, because naming a property does not prove you have enumerated the ways to reach it) are recorded in
docs/governance-skill-tuning-2026-07.md§10 — the history lives there, not here.A supersession MAY correct
reporter— a factual correction of a mis-recorded finder, not a re-attribution.reporteris immutable as to WHOM it names, not as to whether the row got the name right. A correction that changessourcesuch thatreporter_refstops being required is a re-attribution, not a correction, and needs the de-escalation bar: it deletes the row's only third-party-retrievable reference.Precedence is
recorded_at, NOTpass_ordinal, and the difference is load-bearing: a post-run row carriespass_ordinal: 0, so under an ordinal-ordered rule it could never supersede an in-run row at round 1 — a collaborator refuting a finding the run had closed would sit in the file, visible tocat, and be silently outranked by the published read rule. That is the exact case post-run appends exist to serve.pass_ordinalrecords WHICH ROUND a row belongs to; it was never a precedence key, and using it as one inverts the feature.A superseding row states why it supersedes: a
fixedrow cites the commit orfile:linethat fixed it, adeferred-to-issue #Nrow cites the issue. A supersession torefutedorrejectedcarries the same independence requirement as the disposition itself — otherwise the cheap path (appendfixed, no evidence, no independent reporter) produces the same artefact-level read as the hardened one, and routes around it.State the read rule wherever a fragment is counted — the candidate conventions give different answers (measured), so an unstated one means no reader can be right. Rewriting also destroys the prior disposition at the artefact level, which is why the append convention is the one chosen.
Only the fields that CHANGE need restating on a superseding row, plus
schema_version,run_id,finding_id,recorded_by,recorded_at,pass_ordinal,reviewed_at_shaanddisposition. A supersession is not a re-derivation: the original row keeps the TRIGGER/IMPACT/EXPOSURE facts unless the supersession is what changed them.A supersession carries
recorded_by, NOTreporter.reporteris who FOUND the finding and never changes once written; whoever appends a later row is the recorder, and conflating the two misattributes the finding. Getting this wrong also breakssource: the first supersession ever written labelled a human appendersource: "governance-agent"with noreporter_ref, which is precisely the "small forgery" the derivation note below warns about, and it escaped thereporter_refrequirement by claiming to be a pipeline row.sourcedescribes the REPORTER. If a human appends the row,recorded_byis their handle andreporter/sourcestay as originally recorded, subject to the correction carve-out above.recorded_atis self-declared and nothing validates it, which matters more now that it is the precedence key: an author who dislikes a collaborator's post-run refutation can append a later-timestampedfixedrow and outrank it. The commit carrying the row is the corroborating witness — arecorded_atinconsistent with its commit time is suspect, and git is the substrate that makes that checkable.pass_ordinalwas no better: equally author-typed, and broken as well.Why in the repo. The record is evidence for whoever reviews the PR — which findings were raised, which fixed, which deferred and by whom. A path under
$HOMEis unreadable by the reviewer by construction, and SOC 2 CC8.1 evidence has to be retrievable by someone other than whoever produced it. The cost is accepted deliberately, and it is NOT the changelog fragment's cost: an uncommitted changelog fragment is an untracked NEW file, sogit cleanremoves it conspicuously. A row appended to an already-committed fragment is a MODIFICATION to a tracked file —git clean -xfd && git checkout -- .reverts it silently and leaves a plausible-looking ledger behind. Commit an append on the same push that makes the claim it records; a rebase, squash, or branch tidy over that commit is the loss path, and nothing detects it.There is still no database and no shared store; this is a per-run file that happens to be version-controlled. Retention — whether old fragments are pruned, assembled, or kept indefinitely as the access-review campaigns are — is a separate decision and is NOT made here. Do not describe it as more than it is.
Fields, all required unless marked — on the row that FIRST raises a finding. A superseding row carries only the minimum set above plus what changed; the live view merges them, so "required" is a property of the finding, not of every row — EXCEPT the five row-scoped attestation fields, which do not merge: their
required iffclauses bind to the ROW performing the act, and a re-performed act (a second refutation, a re-adjudication) carries its own attestation, never an inherited one:field why schema_versioninteger, currently 1. Per ROW, never per file: appends are permitted, so one fragment can legitimately hold rows written under two versions of this table. A row without it predates #2619 — and on such a row EVERY field #2619 added (source,reporter_ref,reviewed_at_sha,recorded_at,recorded_by,adjudication_rationale, therefutedpair,classification'sabsencevalue) is absent by construction: legacy, not a violation. A validator treats missing-schema_versionas the legacy discriminator, exactly as the read rule orders those rows firstrun_idwhich run. basename "${LEDGER%.jsonl}"— the fragment's filename without its extension, e.g.2619-ledger-provenance-prose-ownership.sW31cX— the FULL basename, which joins back to the filename. Stated as a command because "the mktemp stem" reads three ways: the random suffix alone, the basename, and the full path passed tomktemp -u(which varies withYUZU_GOV_LOG_DIR). A join key once rows are extracted from the file, NOT a uniqueness guarantee:noclobberproves no LIVE file in that directory shares the stem, which does not span aYUZU_GOV_LOG_DIRrun or a stem freed bygit cleancommit_rangewhich diff — per ROW, not per file, because a Gate 8 re-review reviews a different range each pass. On a row from an external reviewer who read a head rather than a range, the range they were shown, or unresolvedreporterWHO found it — a governance-agent name, a person's handle, or a model id. ONE value, never a joined list: convergence is independent_reporters, and a+-joined string is an encoding no reader parses; whereindependent_reporters> 1 it names the one whose evidence this row is derived from, and the others' identities are not currently recordable. Immutable as to WHOM it names — a supersession may correct a mis-recorded finder, but may not re-attribute the finding to someone else. Namedagentbefore #2619; renamed becausesourcebelow admits reporters that are not agents, and a required field with no honest value for two of its three cases is a schema defect, not a naming quibblerecorded_by(nullable on the row that first raises a finding, required on a supersession)WHO wrote this row, as distinct from who found the finding. Null means reporter and recorder are the same sourcegovernance-agent/collaborator/external-model— WHAT KIND of reporter, distinct fromreporter's who. Spelledgovernance-agent, notagent, per CLAUDE.md's three-meanings glossary. A Codex or Kimi run driven by.codex/skills/governanceis agovernance-agentrow —external-modelis for a model reviewing OUTSIDE this pipeline. A non-governance-agentrow MUST carryreporter_refreporter_ref(required iffsourceis notgovernance-agent)a reference that is retrievable by a third party AND not under the change author's control — a PR review URL or id, a comment permalink, a COMMITTED transcript path. Not the PR body: it is retrievable but author-editable in place with no version anchor, which is the gap the first two external-modelrows sat in. Not a bare name — a name is a string the author types freely, which is precisely the self-declared claim this field exists to replace. Where the external input genuinely has no retrievable artefact (an in-session verbal direction), recordunresolvedand say so insummary— an honestunresolvedbeats plausible prose that cannot be checked, and the first exemplar's COL-1 row shows the wrong way.sourceis otherwise an assertion of independent review recorded by the party under review, and that is the one property this artefact most needs to be checkablereviewed_at_shathe HEAD the reporter actually read, and its merge-base with origin/devwhere that is knowable (unresolvedfor the merge-base half when it is not — a GitHub review records the reviewed SHA but not what it was branched from). This is the field that closes the failuresourceis justified by: reviewer KIND does not detect three reviewers sharing one stale checkout, the merge-base doesrecorded_atISO-8601, when the ROW was written — not when the run started. Mandatory because appending after the run is permitted: without it, a row added post-merge is indistinguishable from one written at the gate, and a squash-merge collapses the git history that would otherwise carry the ordering pass_ordinalwhich round. Without it the final pass is indistinguishable from the first, and caused_bybelow presupposes a round identity the schema would otherwise lack. A row appended AFTER the run ends carries therun_idof the run it reviews andpass_ordinal: 0— round zero means "outside the run's rounds", andrecorded_atsays whenfinding_idstable across rounds — caused_byis uncomputable without a join keyseverity_nativethe REPORTER's own vocabulary, unmodified, or nullif they gave none. A collaborator writing "nit" or nothing at all is normal; do not invent a band for them, and do not treat an unmapped human word as the "vocabulary does not map → gate it" case, which is addressed to reviewing agentsseverity_mappedBLOCKING / SHOULD / NICE, derived per the severity rule — so for a conforming writer it always agrees with impact/exposure. Restate it whenever the facts change: a stale label is read at the stronger of the two and is itself reportedtriggerthe concrete input/state/config, or unresolvedimpactevery applicable I1…I9— a list; the strongest gives the bandexposureevery applicable E0…E7, orunresolved— a list, not one value.E6andE7are applied last, in that order —E6's LOW cap dominatesE7's MEDIUM cap when both apply, and both dominate every raiseepistemic_statusverified/likely/speculative. Operates on the GATE, not the band — flipping it tospeculativeconverts a blocker into a mandatory investigation without changing the derived band, which is why the de-escalation rule guards itindependent_reportershow many REPORTERS raised it WITHOUT having been shown it — downstream echoes are not confirmations. Counts reporters of every source, not agents only: a human colleague finding the same defect independently is the strongest confirmation available, and counting it zero inverts the signalpolicy_floor(nullable)the floor hit, if the finding gates as a contract violation rather than by derivation. Null on an ordinary finding, which is most of them provenanceintroduced/newly-reachable/pre-existing. Adjudicated, not inferred from prose. Default tointroducedwhen contestedfile,line,summarywhere and what. linetakesunresolvedwhen the finding is about a file as a whole or the reporter named none — the same sentineltriggerandexposureuse.filetakesunresolvedfor a run-level or process finding that is about no file.lineis relative toreviewed_at_sha, not to HEAD — it drifts, so cite the sha when the citation mattersclassification+ rationaletruth-contradiction/wording/absence, and why.absenceis the third category the prose rule names — a required doc that is missing contradicts nothing, so forcing it into the other two is what the rule exists to stop. The rationale ALSO carries the resolution when two reviewers disagreed and one was upheld — stated here so the use is declared rather than improvised. It does NOT go inadjudicated_by: that field is scoped to the departure standards below, and afixedrow involves no departure. The trade-off is accepted knowingly — no query returns "every contested finding and who upheld whom", and a dedicated field would invalidate every fragment already committeddispositionopen/fixed/deferred-to-issue #N(a NEW issue was filed) /roadmap-#N(parked) /linked-to-#N(an EXISTING issue already covers it) /split/re-cut/rejected/refuted.openis the value at the moment a finding is RAISED — the others are terminal, and a schema whose only values are terminal cannot record a finding before it is resolved. The#Nvalues are completed when the issue is filed or identified, which happens after the run: fill them in before the PR merges by SUPERSEDING ROW (samefinding_id, per the write model above) in a NEW commit — nevergit commit --amendor a rebase, which rewrites evidence a reviewer may already have read. If filing slips past the merge, amend in a follow-up PR —devis protected, so a direct commit is not a path — and say so in the run report; a fragment left holding#?makes the park unauditable, which is the failure the disposition exists to prevent.roadmap-#Nis valid work parked per Gate 7, under the two constraints stated there — and aroadmap-#Norlinked-to-#Nsupersession MUST restateimpactandseverity_mapped: the step-4 park check is ROW-wise, and a sparse park that inherits itsimpactfrom the raising row reads CLEAN to it (measured — a conforming 8-field park over an openI1row exits 4), which would false-green the one constraint the check exists to enforce.splitrecords that the work left this change as its own review unit;re-cutthat the original acceptance criteria travelled to the mechanism.rejectedmeans false, inapplicable or disproven, but WITHOUT the evidence barrefutedcarries — at CRITICAL/HIGH or on a floor it requires theadjudicated_byseparation Gate 7 states.refuted= the claim was factually WRONG andrefuted_bycarries the evidence — a different outcome with a different downstream use, so never collapse the tworefuted_by(required iffdispositionisrefuted)the evidence that killed the claim — the command run and its output, the git show origin/dev:<path>that disproved an absence, the file:line that contradicts it. Arefutedrow with no evidence is arejectedrow wearing a stronger word. The refutation must defeat the DEFECT, not merely the citation: a real finding that names the wrongfile:lineis corrected, never refuted, or the recorded kill shape suppresses a true claim on the next runrefuted_by_reporter(required iffdispositionisrefuted)who refuted it, and that they were not the change's author. adjudicated_byalready carries this requirement and the manual-cleanup floor exception states it outright — a self-authored refutation of one's own blocking finding is exactly the case both were written for, andrefutedis the disposition that most reduces downstream scrutinyadjudicated_by(nullable; required iff the row de-escalates — see the de-escalation rule)who approved a departure, that they were not the change's author, and which separation applied — this field serves several dispositions whose standards are NOT the same, so it states none of them and names the one in force: Gate 7's for rejected, Test 2's for a scope change, the floor exception's for a documented impossibility, the de-escalation rule's for a weakened gate or band. An earlier revision stated one standard here, which read as the rule for all and was the weakest of them. Free text with no*_refsibling: a reader with the repo can detect SELF-naming by comparing againstgit log --format='%an'overcommit_range, and can verify nothing beyond that. Self-naming is caught; the adjudication itself is unverified, andcommit_range: unresolvedvoids even the self-checkadjudication_rationale(required iffadjudicated_byis set)WHY the departure or de-escalation was approved. Distinct from waiver_rationale, which is specifically why an unresolved gating finding was allowed to passcaused_by(nullable)did round N's fix create this round N+1 finding waiver_rationale(nullable)why an unresolved gating finding was allowed to pass. A signature with no reasoning is content-free exception evidence caused_by,waiver_rationaleand therefuted_bypair exist so the schema is stable when the process that produces them lands. Recording anadjudicated_by,waiver_rationale, orrefuteddisposition does NOT establish that a gating finding may be released — no such merge contract is adopted here. Today's rule is unchanged: gating findings are resolved before the gate passes, and a refutation resolves one only if the refutation is itself correct and independently recorded. The columns are there so a future decision has somewhere to write, not because one has been made.Who derives the facts on a non-agent row. A collaborator does not file a TRIGGER/IMPACT/EXPOSURE derivation, and should not be asked to. Whoever RECORDS the row derives them from what the collaborator actually said, and
epistemic_statusis the recorder's confidence in their own reading of it, not the collaborator's confidence in the finding.severity_nativestays the reporter's own words ornull. Say insummarywhere the derivation is the recorder's rather than the reporter's — a row that silently attributes a derived band to a human who never stated one is a small forgery.openis not a resting place. A row recordedopenmust be superseded by a terminal row before the gate passes. That is the existing rule — gating findings are resolved before the gate passes — expressed in the schema;openexists so a finding can be recorded when it is RAISED rather than only once it is settled, not so a run can end with unresolved rows in the ledger.Nothing validates that, and nothing can: a
fixedrow is a CLAIM, not closure evidence. The ledger records; Gate 8 tests. Appendingfixedto every open row costs nothing and proves nothing — what actually closes a finding is the re-review of the fix diff, and the ledger's value is that the claim is written down next to who made it and when.Which sources a run is expected to record. A
/governancerun recordssource: "governance-agent"rows only. Rows withsource: "collaborator"or"external-model"are written when a PR review, an/adversarial-review, or an equivalent external pass actually happens — so an absentcollaboratorrow means nothing was recorded, NOT that no external review occurred, and it must never be read as evidence that none was sought. Adding those rows to an existing fragment is a normal, expected append; a run does not own its file exclusively once it has finished. An append to a fragment that has already merged goes through a pull request like any other change to the repo — never an amend over the original commit, and never a direct push that alters an evidence record without review.Why
sourceis worth a column, and what it does NOT do. Independent review is only independent if the WORKING COPIES are. On #2604 two external models independently confirmed a claim that was wrong — all three reviewers were reading one working copy whose merge-base predated the file in question by ten days, so the agreement measured the checkout, not the code. A colleague with a current checkout killed it in a single pass.sourcealone does NOT detect that: it records reviewer KIND, and all three of those reviewers would have been truthfully labelled.reviewed_at_shais the field that detects it, which is why the two land together.sourceanswers a different and narrower question — was this row produced inside the pipeline or outside it — andindependent_reporterscounts reporters who were not shown the finding.Known gap, unsolved: the absence of a finding row cannot distinguish "the reviewer passed" from "the reviewer never ran". A clean-result record needs its own design.
sourcenarrows the MISREADING risk for external review — an absentcollaboratorrow is now explicitly uninformative rather than ambiguously so — but it adds no assertive power and does not close the gap. Nor does a PRESENT row assert much on its own:reporter_refis what makes it checkable, and without one the field is a claim about the reviewer made by the reviewed.Why this exists at all: governance is the repo's largest issue-inflow source, and nothing has ever recorded what it found. CI outcomes, durations and flakes are persisted and queryable (
docs/ci-architecture.md); governance findings are not. Without a record, "governance is too noisy" and "governance caught the thing that mattered" are both unfalsifiable, and no roster change can be argued from evidence. Seedocs/governance-skill-tuning-2026-07.md. -
Check the dispositions against the ledger BEFORE the final decision. Gate 7's first park constraint is the only part of the park contract a machine can see, so see it. Whoever runs the gate does this — not "whoever writes the run report", which is a post-push artefact and would put the check back after the decision it exists to inform. Run it against
"$LEDGER"from step 3, never a hardcodedgovernance.d/path: aYUZU_GOV_LOG_DIRrun keeps its fragment elsewhere, and a check pointed at a file that is not there is the one failure this step cannot afford.jq -e 'select((.disposition | test("^(roadmap|linked-to)")) and ((.impact // empty | if type == "array" then .[] else . end) | test("^I[123]$")))' "$LEDGER"Note the prefixes carry no trailing hyphen. Requiring one let a malformed
"disposition":"roadmap"— an OFF-ENUM value truncated to the bare word — exit clean while carryingI1. Measured. To be precise about which shape this fixes: the schema's prescribed unfilled park isroadmap-#?, and the hyphenated pattern already matched that, so a park awaiting its issue number was never the gap. The gap was a value that is not in the enum at all. Dropping the hyphen costs nothing — no other disposition value begins with either word.A clean check is exit 4; a violation is exit 0.
jq -ereports 4 when no result was produced at all, so the PASS case here is a non-zero exit — measured on jq-1.8.1. Do not wire it into a bareifor&&without accounting for that inversion, and do not read every non-zero exit as a pass: a missing or unreadable file is exit 2, which is a mis-pathed check, not a clean one. Only 4 is clean.The
if type == "array"normalisation is load-bearing. A bare.impact[]?swallows the type error on a scalar, so a row recording"impact": "I1"instead of["I1"]passed the check as clean — measured.A match is a row whose finding may not be parked. Two arms, and they need different handling:
roadmap-prefixed (roadmap-#N,roadmap-#?, or the bare word) — a park barred by constraint 1. The gate does not pass and the report does not go out until that row is re-dispositioned.linked-to-prefixed — this one over-matches by construction, so treat it as a prompt, not a verdict. Linking anI1finding onto an existing parked issue reaches the same outcome as parking it, which is why the arm is here; but linking it onto an active prioritised issue is a legitimate ending that Gate 7 explicitly allows. No ledger field records the target's labels, so check them before calling it a violation. Treating everylinked-to-match as one pushes the reviewer toward filing a duplicate or thinning theimpactlist, which are both worse than the thing being prevented.
The check is ROW-wise while the artefact is supersession-based, and that cuts BOTH ways. A row parked early and re-dispositioned later still matches — before calling a match a violation, read the finding's LIVE view under the merge rules in step 3; a superseded park is history, not a live one. And a park written as a SPARSE supersession that omits
impactis invisible to this check while its live view carriesI1— measured: exit 4, the documented clean result. That gap is closed by contract, not by the check: the disposition rule requires aroadmap-#N/linked-to-#Nrow to restateimpactandseverity_mapped, so a conforming park is always visible row-wise and a park this check cannot see is non-conforming on its face. Treat "the check passed" as covering conforming rows only.What this check cannot see, and an earlier revision wrongly claimed it could: the label half of the park contract (
roadmapXOR priority + triage state) lives on GitHub, not in any ledger field; the target's labels behind alinked-to-row are equally invisible; and constraint 2 needs the dedupe probe's result. All three stay procedural. It also reads a field the author supplied — animpactlist withI1omitted passes, which is the gaming vector the severity block already names — so spot-check parked rows'impactagainst their owntriggerandsummary.Then lint the whole fragment before you push.
scripts/ci/check-governance-ledger.pyis an author-side self-check that previews the self-consistency problems a strict reviewer will flag, so a ledger stops taking multiple review rounds to converge (PR #4337 took seven rounds, every one a ledger-metadata defect while the code was byte-identical from round 1; each rule is one of those rounds' lessons):python3 scripts/ci/check-governance-ledger.py --files "$LEDGER"finding_id— the MERGE JOIN KEY ITSELF, more fundamental than any single field's value — must be an ANCHORED, whole-string match against a CLOSED ASCII token grammar: starts with an alphanumeric, then only alphanumerics plus the small punctuation set the real corpus actually uses (._+/,-). This is the fourth attempt at this check, and the first that closes the whole CLASS rather than one more reported instance: bare truthiness (bool(" ")isTrue) →.strip()(misses zero-width/format characters like ZWSP/BOM, Unicode category Cf) →isprintable() and not isspace()(still passes combining marks, variation selectors, and blank-glyph symbols like BRAILLE PATTERN BLANK or a Hangul filler — category Mn/So/Lo) → an EXISTENTIAL "contains at least one alphanumeric somewhere" allowlist (closed the BLANK-id COLLISION direction but not the SPLIT direction of the same class:"X"and"X"plus a trailing ZWSP both "contain an alphanumeric" while being two DIFFERENT dict keys, silently splitting one finding's history across two merge groups instead of colliding two unrelated ones — same root cause, opposite failure mode). "Renders blank" is a FONT property, not a fixed enumerable Unicode category, so no denylist — and no merely-existential allowlist — is ever complete. An ANCHORED full-match closes both directions at once: no leading, trailing, OR embedded invisible/non-ASCII character can hide anywhere in a value that still matches, with no separate whitespace-strip comparison needed (whitespace of any kind simply isn't in the grammar, wherever it appears). Verified: zero of 11,584 real corpusfinding_idoccurrences fail this grammar, and none starts with a non-alphanumeric character. Any of these shapes, uncaught, silently either collapses two unrelated findings that happen to share a blank-looking id into one merge group (a later row's facts overwriting an earlier BLOCKING finding's with zero warning) or splits one finding's own history into two.It builds each finding's live view as the FIELD-WISE MERGE defined above (not the last row alone), ordered by
recorded_atas a true instant — arecorded_atthat is PRESENT but does not resolve to an UNAMBIGUOUS instant is reported (bad-recorded-at) rather than silently sorted as legacy. This covers TWO tiers, not just wholly-invalid strings: a value that fails to parse at all, AND a value that parses but carries no timezone offset (a bare date, or a naive datetime) — the latter is NOT silently assumed to be UTC, because an author hand-typing a bare date is a realistic failure mode and a malformed OR ambiguous timestamp on a genuine severity ESCALATION can otherwise vanish from the merge with nothing else able to surface it. (A lowercasezUTC suffix, which RFC 3339 §5.6 also permits, is accepted likeZ— Python'sfromisoformatonly recognizes the uppercase form natively.) BELOW the merge, every line is parsed with a duplicate-object-member check: standard JSON parsers (Python'sjson.loads, jq, JavaScript'sJSON.parse) all silently keep only the LAST value for a repeated key with no diagnostic, so a row whose raw text states a merge-governing field twice can lose its real value before ANY of the checks above ever run — reported asinvalid-json: duplicate object member(s): ..., never silently resolved. On top of the merge it separately checks, PER ROW, that a row participating in the post-#2619 regime — carrying ANY field #2619 introduced (schema_version,source,reporter_ref,reviewed_at_sha,recorded_at,recorded_by,adjudication_rationale, therefutedpair, orclassification: "absence"— a genuinely legacy row carries NONE of them, per SKILL.md's own definition, so checking only two of the markers missed a row that omits BOTH while still carrying e.g.recorded_by) — restates all EIGHT mandatory fields even when sparse (schema_version,run_id,finding_id,recorded_by,recorded_at,pass_ordinal,reviewed_at_sha,disposition) — omitting one of the eight is a violation even though every OTHER field may legitimately be omitted when unchanged.pass_ordinalandrun_idare additionally validated PER ROW (not only on the merged result):pass_ordinaldetermines MERGE ORDER itself, so a bad value on a row that loses a tie because of it would otherwise vanish before anything downstream ever inspects it, and a mid-history wrongrun_ida later row incidentally restates correctly would otherwise read clean at the merged level alone. On the merged view it also requiresepistemic_status/provenance/classificationpresent and non-null on a non-legacy finding — SKILL.md's field table marks them required with no nullable annotation, unlikeimpact/exposure, which explicitly tolerate a null fact set — and checks:severity_mappednot weaker than the facts' derived floor band (over-labeling is left alone — a conditional raise can legitimately exceed the flat table — and a floor gates separately viapolicy_floor, which must itself cite a closed source or an empty-impact claim stays flagged rather than excused by a fabricated floor string);severity_nativefrozen across supersessions, compared against the finding's first row (an omission-then-later-invention is caught, not only an explicit null-then-value flip), checked per row; awordingfinding never carryingI7; single-value, non-emptyreporter; per-rowadjudicated_byandadjudication_rationale, each REQUIRED to be null or a genuine non-empty, non-whitespace string (a barebool(x)truthiness check would let a whitespace string, a bare int, orFalseitself read as "set") — pairing is then compared on those NORMALIZED presence booleans, not the raw values; single-value, non-empty, non-whitespacereporter_ref(required iffsourceis notgovernance-agent, or the literalunresolved); and enum/type hygiene forsource;disposition(must always be a non-empty string — bedrock, checked PER ROW regardless of legacy status — with its CLOSED-ENUM half, a later#2643-era convention, ALSO checked per row, gated on THAT ROW's own versioned-ness (not the finding-levellegacyflag, which is true the moment ANY row is versioned and would wrongly retro-apply the enum to a genuinely legacy first row a later versioned row happens to supersede), requiring real (non-whitespace) content after a#<id>prefix's#— a bare LENGTH comparison would accept a whitespace-only suffix ("roadmap-# ") as "non-empty" — while still tolerating a non-numeric trailing note like the corpus's own#TBD (draft: ...)shape — checking the enum per row, not just on the merged view, catches a permanently-recorded bad value a later valid row would otherwise hide, without breaking the legitimateopen→fixedevolution, since both values are individually valid);epistemic_status,provenance,classification(general content contracts, so NOT legacy-exempt — a genuinely ancient row can still carry a value worth flagging); andindependent_reporters(excluding booleans, which pass a bareisinstance(x, int)test in Python, but toleratingnull— a legitimate "not yet counted" value the corpus carries). All EIGHT per-row-mandatory fields have their VALUE (not merely their presence) checked PER ROW, not only on whatever survives into the merge — an explicitnullor a wrong-typed value on an early row is a permanently-recorded defect a later valid row would otherwise silently "correct" with no trace:schema_versionandpass_ordinalmust be non-bool integers (pass_ordinalalso non-negative);reviewed_at_shamust be a non-empty, non-whitespace string (a bare truthiness check alone misses7and" ");dispositionmust likewise be a non-empty, non-whitespace string, per row, per the closed-enum treatment described above;recorded_byis the one CONDITIONAL case — nullable only on the row that first raises the finding (SKILL.md: "nullable on the row that first raises a finding, required on a supersession"), sonullis flagged only on a later row, and on ANY row a non-null value must still be a genuine non-empty, non-whitespace string. And thepolicy_floorkey's presence. It also reproduces this step's own park probe — anI1/I2/I3finding on aroadmap-disposition, and the scalar-impact/exposureshape thejqabove catches — but does NOT replace it: the label half of the park contract (roadmapXOR priority/triage on GitHub, and alinked-to-target's labels) lives outside the ledger and stays procedural, so run BOTH. It is advisory, not a CI gate — calibration found most of the historicalgovernance.d/corpus predates these rules, so it is deliberately NOT wired as a blocking check; only its self-test runs in CI. It judges mechanical field-consistency, never whether a finding is true or a severity right. Resolve or consciously accept each finding before pushing.
Known patterns from prior runs
Pattern A: sibling IDOR. When fixing an authorization gap on endpoint X, grep for every other endpoint in the same file/semantic and verify they have the same check. #222 closed the REST path but left the HTMX dashboard path open. The governance security-guardian caught it only when explicitly told to look for siblings.
Pattern B: cycle-safe here but not there. When adding visited sets / cap checks to one traversal (get_descendant_ids), always check the sibling traversal (get_ancestor_ids) for the same class of bug. The fix pattern is symmetric; the bug pattern usually is too.
Pattern C: pre-existing bug made worse by hardening round. A latent bug that was dormant under previous call patterns can become hazardous when you add a new call site. UP-11 / C1: my #222 fix added a new denied-branch that called render_api_tokens_fragment(), which has always leaked all tokens via list_tokens()-with-no-filter — but no prior code path exercised that leak in a denied-response body sent to a non-owner. My "close the oracle" fix shipped a new info leak worse than the IDOR it closed. Watch for this pattern in every new error-branch.
Pattern D: 404 vs 403 enumeration oracle. When adding owner-check rejection to an endpoint, return the same status and same body as "not found" so non-owners cannot distinguish "doesn't exist" from "exists but not yours". Audit log server-side with the real reason.
Pattern E: readiness probe coverage regression. Gate 6 SRE reliably catches any new or newly-load-bearing store missing from /readyz. Verify server.cpp's stores_ok conjunction covers every store the PR changed or newly relies on.
Cost / ROI
One full governance run on a non-trivial commit range is ~6-9 parallel agent calls plus the consolidation writeup. On the #222/#224 hardening round (5 commits, 2 hardening rounds), it caught 3 BLOCKING items I introduced myself, 2 of which would have shipped a worse vulnerability than the one I was fixing. The run takes 30-60 min of wall clock and produces a permanent artifact trail in commit messages + CHANGELOG that satisfies SOC 2 Workstream F change-management evidence.
Skipping Gate 4 or Gate 5 to save time is rarely worth it. Do NOT skip Gate 3 domain agents on the grounds that a change is small — that guidance predates the unconditional routed-trigger floor above and contradicts it. Diff size does not gate a routed concern: .claude/routed-concerns.md keys on file identity and change type precisely because those files carry catastrophic-if-violated invariants at any line count. Use the decision matrix to decide WHICH agents, never WHETHER.
Post-run follow-ups — file or park deferred findings per the issue standard
After the run passes and the commits push, file or park whatever Gate 7's disposition step routed to either. Both branches are in step 3; the constraints on parking are Gate 7's, stated there.
There is no expected number, and the previous version of this sentence gave one. It said a run "typically produces 8-15 deferred follow-up items", which functioned as a quota: it made filing the default and made a run that filed nothing look incomplete. Git history shows that figure entered the runbook as a descriptive observation from early runs, not as a calibrated control. A run that folds every correction and splits one surface is a good run; so is a run that files nothing, PROVIDED each finding has a recorded disposition per Gate 7.
Filing follows docs/agents/issue-standard.md exactly — it is authoritative on
shape and volume, including that dedupe is the only inflow filter. The binding
procedure:
-
Draft the candidate list — one actionable outcome per candidate; split multi-finding bundles; type each honestly (
bug/task/decision/spike— a choice-to-be-made is adecision, not a code task). -
Dedupe every candidate (mandatory — dedupe is the only inflow filter):
gh issue list --repo DevNullLtd/Yuzu --state open --search "<file-or-symbol>" --json number,title gh search issues --repo DevNullLtd/Yuzu --state open "<title keywords>" --json number,title --limit 20An existing issue covers it → comment the new evidence there instead of filing. Related but a distinct outcome → file with
Relates to #Nin the body.If the duplicate target carries
roadmap, comment-and-leave is FORBIDDEN. That is a re-park, barred by Gate 7's second constraint: fix it, or promote the issue out ofroadmap— remove theroadmaplabel and add exactly one priority AND exactly one triage state. That is thegh-path rule, which is the one that binds here because governance files throughgh:docs/agents/issue-standard.md§4 requires "eitherroadmap… or exactly one priority alongside the triage state", and ADR-3001 repeats it. Do NOT weaken this to "a priority once triaged" — that is the any-path telemetry invariant attriage-labels.md, and a round of this runbook did exactly that, producing an instruction to leave the issue in a state thegh-path rule forbids. A half-promoted issue is a contract violation. Name the promotion in the run report: the ledger row recordslinked-to-#N, and no ledger field carries a free-text disposition note. -
File survivors with the four body sections (Context / Evidence with
file:lineagainst currentorigin/dev/ Acceptance criteria / Origin naming this governance run plus the dedupe probes and their results):gh issue create --repo DevNullLtd/Yuzu --title "..." \ --label <type> --label governance-deferred --label <P0|P1|P2> --label ready-for-agent \ --body-file <candidate>.mdParking instead of filing — for valid work that will not be scheduled, under the two constraints at Gate 7's "Filing, parking, and why the default matters". The rule is there; the command is here.
roadmapis XOR with (priority + triage state) perdocs/agents/issue-standard.md§4 — cite THAT, nottriage-labels.md, whose invariant list is telemetry-shaped and whose weaker "a priority once triaged" phrasing is what a previous round of this runbook mistakenly acted on — so the park branch carries NEITHER:gh issue create --repo DevNullLtd/Yuzu --title "..." \ --label <type> --label governance-deferred --label roadmap \ --body-file <candidate>.mdNo
P0/P1/P2, noready-for-agent/needs-triage.governance-deferredis an inflow counter, not a priority or a triage state, so it survives the XOR. The ledger-side check on theI1/I2/I3bar has already run by this point — it is Gate 8 step 4, before the gate passes, not after the commits push.(
<type>and<P0|P1|P2>are placeholders — pass exactly one real label each, e.g.--label task --label P2. The priority axis isP0/P1/P2perdocs/agents/issue-standard.md§4; an earlier revision wrote<P1|P2>here, which silently narrowed the authoritative set and left a governance finding that genuinely warrantedP0with no legal label.gh search issuesis rate-limited (~30/min): on a 403 mid-batch, wait 60 seconds and continue — never skip the probe.) Every governance filing carriesgovernance-deferred(that label is how agent inflow is counted). Add facet labels as they genuinely apply (tech-debt,reliabilityfor chaos findings,observability,devops,securityfor hardening — never for exploitable vulnerabilities, which go to private advisories perSECURITY.md). -
The run report enumerates BOTH lists — filed (with issue numbers) and not-filed (with the duplicate verdict and the issue each deduped against) — so inflow is auditable run over run.
Prior examples: issues #340..#353 (pre-standard; the body format is now the standard's four sections).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |