Skip to content

DevNullLtd/Yuzu / .codex/skills/governance

governance

Verified

Run Yuzu's Codex governance review pipeline on a commit range with slash-name parity to Claude `/governance`. Use when the user says `/governance <range>`, "full governance", or asks for the multi-gate security/docs/domain/ops review on commits or a PR.

FileKindSize
SKILL.mdskill md8.2 KB
---
name: governance
description: Run Yuzu's Codex governance review pipeline on a commit range with slash-name parity to Claude `/governance`. Use when the user says `/governance <range>`, "full governance", or asks for the multi-gate security/docs/domain/ops review on commits or a PR.
---

# Governance

Run Yuzu governance as a Codex-native review fanout. This skill may use Codex subagents because invoking `/governance` is an explicit request for delegated review. Keep each delegated role bounded to review only; do not let review agents edit files.

## Range

- Default range: `dev..HEAD`.
- Treat a bare commit like `HEAD` as `HEAD~1..HEAD`.
- If `dev..HEAD` is empty on branch `dev`, ask whether `origin/dev..HEAD` is intended.

## Gates

1. Change Summary: write this locally from `git log`, `git diff --stat`, and targeted diffs.
2. Mandatory review: launch `security-guardian` and `docs-writer` in parallel.
3. Domain review: select roles by changed files and launch them in parallel.
4. Correctness review: launch `happy-path`, `unhappy-path`, and `consistency-auditor` in parallel.
5. Chaos analysis: run only if Gate 4 produced unhappy-path or consistency findings.
6. Operational review: launch `compliance-officer`, `sre`, and `enterprise-readiness` in parallel.
7. Findings resolution: consolidate findings and fix blocking items.
8. Iteration and ledger: re-run affected gates, record deferrals, and make the blocking decision.

Blocking contract: **identical to the Claude runner — load it, do not restate it.** Read the "Shared preamble" severity block in `.claude/skills/governance/SKILL.md` and apply it verbatim: severity is DERIVED from TRIGGER + IMPACT + EXPOSURE + EPISTEMIC STATUS per that block's own closed lists (do not enumerate the IMPACT/EXPOSURE codes here — a second copy of the list is exactly the restatement the next line forbids), `BLOCKING` = a derived band of CRITICAL or HIGH, and the policy floors gate independently of the derivation. MEDIUM/SHOULD findings need either a fix or an explicit deferral with an issue.

This file MUST NOT carry its own copy of the severity rule. The two runners advertise parity; a second copy is how they drifted into enforcing different gates (found in #2623 re-review).

## Gate 1 Output

Include:

- commits in scope: sha, subject, branch/push state if known
- files touched: path and behavioral delta
- interfaces affected: REST, stores, proto, plugin ABI, CLI/env, CI, docs
- security surface: opened, closed, or net neutral
- Resource Ledger for C++ changes: 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 the owner type, acquisition point, release point, transfer behavior, and failure cleanup
- user-facing impact and compatibility notes
- validation already performed with exact commands and exit status
- Gate 3 roles selected and why

## Role Prompts

Use compact role prompts and include the Gate 1 summary plus prior gate findings as context.

- `security-guardian`: read every modified file; check authz, ownership, validation, audit, command execution, path handling, crypto, secret handling, sibling handler parity, and new error branches. For C++ diffs, also require an ownership proof for every raw resource boundary: fd, HANDLE, SOCKET, `FILE*`, `sqlite3_stmt*`, `sqlite3*`, OpenSSL/BCrypt object, allocated C string, thread, callback context, subprocess, mapped library, and temp path must have exactly one owner; manual cleanup must be wrapped in a small RAII/scope guard; every early return between acquire and release must be checked. Findings use CRITICAL/HIGH/MEDIUM/LOW/INFO with file:line and recommended fix. Gating is decided by the canonical derived band and policy floors, never by this prompt.
- `docs-writer`: check REST docs, user manual, CHANGELOG, upgrade notes, permission/audit/error tables, and operator workflow docs. Findings use BLOCKING/SHOULD-FIX/NICE-TO-HAVE.
- `architect`: public contracts, stores, REST boundaries, schema, lifecycle, coupling, and hard-to-reverse design.
- `cpp-expert`: C++23 correctness, idioms, standard-library use, ABI boundaries, threading primitives, and cross-compiler portability across GCC, Clang, MSVC, and Apple Clang.
- `cpp-safety`: RAII ownership, lifetime, move/copy semantics, C ABI boundaries, `std::string_view`/`std::span` validity, cast safety, thread lifetime, syscall/process boundaries, shell execution, and sanitizer coverage. Leaks, double-close risk, UAF risk, unjoined/detached thread ambiguity, unsafe shell construction and borrowed data escaping its owner are policy floors under the canonical rule — report them; the floor, not this prompt, is what gates.
- `quality-engineer`: test seams, integration coverage, fixture isolation, flaky patterns, temp DB/path hygiene, weak assertions. For C++ safety-sensitive changes, require coverage for cleanup paths, partial failure, short read/write, EINTR, failed `pclose`, failed `CloseHandle`, failed `sqlite3_prepare`, and concurrent teardown where relevant; for new RAII wrappers, require a test or compile-time assertion covering move-only/non-copyable behavior when feasible.
- `build-ci`: Meson, vcpkg, workflows, release scripts, runner assumptions, cache behavior.
- `plugin-developer`: plugin descriptors, SDK boundaries, YAML definitions, plugin execution behavior.
- `gateway-erlang`: rebar3, OTP supervision, cowboy/gun/gpb, gateway proto mirrors, EUnit/CT/Dialyzer implications.
- `dsl-engineer`: CEL, scope DSL, YAML DSL, trigger templates, validation and backward compatibility.
- `cross-platform`: Darwin, Linux, Windows/MSVC, paths, sockets, filesystem, service behavior.
- `performance`: SQLite hot paths, BFS/graph traversals, authz loops, gateway throughput, allocations.
- `release-deploy`: Docker, packages, systemd, installers, upgrade and rollback behavior.
- `happy-path`: trace normal request/store/plugin/gateway flows end to end and call out idempotency.
- `unhappy-path`: produce a risk register with ID, trigger, symptom, severity, and chaos candidate.
- `consistency-auditor`: check sibling parity, error/audit naming, schema/docs/tests drift, and CHANGELOG ordering.
- `chaos-injector`: convert Gate 4 risk registers into executable chaos test designs; do not run them.
- `compliance-officer`: SOC 2 control alignment, evidence chain, audit traceability, retention, approvals.
- `sre`: health/readiness, metrics, alerts, recovery, capacity, backpressure, runbooks.
- `enterprise-readiness`: pilot-visible rough edges, upgrade notes, breaking changes, customer assurance.

## Domain Routing

Always include `quality-engineer` for feature or bug-fix changes. Always include `architect` for public store contracts or REST API surfaces. Always include `performance` for `get_*_ids`, SQLite BFS/graph traversal, or per-authz hot paths.

Always include `cpp-expert` and `cpp-safety` when C++ files change. Also include `cpp-safety` for any diff that introduces or modifies `popen`, `system`, shell strings, `fork`/`exec`, `CreateProcess`, `dlopen`, `LoadLibrary`, `open`, `socket`, `sqlite3_prepare`, `EVP_*_new`, `BCrypt*`, `LocalAlloc`, `yuzu_ctx_*`, `raw()`, `release()`, `reinterpret_cast`, `const_cast`, or a background thread/callback that stores a pointer or reference. Run `rg` over changed C++ files for raw resource APIs and verify owning raw resource boundary hits appear in the Resource Ledger.

Use `$yuzu-proto`, `$yuzu-plugin-abi`, `$yuzu-meson`, `$yuzu-windows-msvc`, and `$yuzu-build` when the changed files touch their domains.

## Ledger

Write the per-finding JSONL fragment exactly as the canonical skill specifies — the recipe
and the field table both live in `.claude/skills/governance/SKILL.md` under Gate 8, and are
deliberately not restated here. Default location `governance.d/`, committed with the work
it reviews; `YUZU_GOV_LOG_DIR` redirects a throwaway local run outside the tree. A Codex
governance pass that produces no fragment has not finished.

Then end with a human-readable governance ledger:

- Gate status table: role, result, blocking count, deferred count
- Blocking findings with owner/fix status
- Deferred findings with issue number or explicit rationale
- Re-review scope and result
- Final decision: PASS / PASS WITH DEFERRED / BLOCKED
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall