maintain-governance-rubric

What problem does it solve?

host's governance rubric at gov-infra is the project's operational-trustworthiness substrate. It runs in CI on every PR, produces deterministic evidence, and is versioned in pack.json to prevent silent goalpost-shifting. When a change touches the rubric, it is a governance event — not an ordinary code change — and carries discipline that ordinary refactors don't.

The rubric architecture (memorize)

• gov-infra/README.md — the rubric's purpose and usage
• gov-infra/AGENTS.md — agent-facing governance guidance
• gov-infra/pack.json — the versioned rubric manifest. Every meaningful change bumps the version.
• gov-infra/verifiers/ — deterministic checks across categories:
  • QUA (quality) — linting, test coverage thresholds, build correctness
  • CON (contracts) — public API stability, consumer-facing shape preservation
  • SEC (security) — Slither on Solidity, secret-scanning, CSP validation, gosec / similar
  • COM (community / comms) — documentation freshness, release-notes completeness, changelog discipline
• gov-infra/evidence/ — verifier output and artifacts. Immutable history.
• gov-infra/planning/ — rubric evolution, threat model, controls matrix
• gov-infra/pack.json-versioning — anti-drift; rubric versions are named and auditable

Grades are 0 or full points, no partial credit. A verifier passes (evidence commits) or fails (PR does not merge). Loosening the threshold "a little" defeats the rubric's purpose.

When this skill runs

Invoke when:

• A change adds a new verifier
• A change modifies an existing verifier's logic, threshold, or scope
• A change removes a verifier
• A change adjusts evidence policy (retention, format, scope)
• A change bumps gov-infra/pack.json version
• A change updates the controls matrix, threat model, or other gov-infra/planning/ documents
• A failing verifier needs investigation — is the failure a legitimate rubric issue or a code issue?
• scope-need flags a change as governance-rubric-touching
• investigate-issue surfaces a root cause in the rubric

Preconditions

• The change is described concretely. "Improve SEC rubric" is too vague; "add a verifier under gov-infra/verifiers/sec/csp-header-strict that validates CloudFront response-headers config for strict CSP and emits evidence at gov-infra/evidence/sec/csp-header-strict-<commit>.json, full points if CSP matches the expected spec, zero otherwise" is concrete.
• MCP tools healthy, memory_recent first — rubric-evolution decisions accumulate over time.
• Current pack.json version and shape loaded in mind.

The five-dimension walk

Dimension 1: Verifier identity and category

For each verifier being added / modified / removed:

• Category — QUA / CON / SEC / COM / CMP. Each category has different semantics; a verifier belongs to exactly one.
• Identifier / path — under gov-infra/verifiers/<category>/<name>. Naming convention: lowercase-hyphenated.
• What it checks — a specific claim. Good verifiers make a narrow, auditable claim. Bad verifiers check broad-vague things that invite partial-credit temptation.
• Deterministic output — same input → same output. Same-commit re-runs produce identical evidence.
• Input surface — what the verifier reads (source files, deployed state, external APIs). Verifiers that read external state are more fragile; prefer in-repo reads where possible.

Dimension 2: Grade semantics

Every verifier produces 0 or full points:

• Full points — the claim holds. Evidence committed.
• Zero points — the claim does not hold. PR does not merge.
• No partial credit. A verifier that wants to produce "mostly passes" is mis-designed; split into multiple specific verifiers instead.
• Unambiguous pass/fail — a verifier whose interpretation is disputable is disputable. Refine until the pass/fail is unambiguous.

Dimension 3: Evidence policy

Every verifier emits evidence on pass:

• Format — JSON (preferred) or a structured markdown artifact. Binary formats discouraged.
• Location — gov-infra/evidence/<category>/<verifier-name>-<timestamp-or-commit>.<ext>
• Retention — evidence is immutable by convention (never rewritten). New evidence appends; old evidence stays for audit.
• Contents — the verifier's input summary, the specific claim validated, the pass result, reproducibility info (commit SHA, tool versions).
• Signed or attestable (future-looking) — evidence that can be independently verified has higher value. Consider whether this specific verifier's evidence benefits from attestation.

Dimension 4: pack.json versioning and anti-drift

For rubric-shape changes:

• pack.json version bumps — every meaningful change bumps the version. Minor for additive changes; major for semantic shifts.
• Change documentation — the bump commit explains what changed and why, in the body.
• Anti-drift check — the commit diff shows the shape-of-change clearly; reviewers can see whether this is tightening or loosening.
• Loosening requires governance-change process — ordinary code review is not sufficient. A loosening change is a governance event with explicit rationale, review by Aron, and (potentially) a Safe-multisig-style multi-reviewer approval.
• Tightening is easier but still a governance event. Documentation is part of the commit.

Dimension 5: Failure-mode analysis

For a failing verifier (before changing it):

• Is the failure real? The code is genuinely out of spec; fix the code. Don't weaken the verifier.
• Is the verifier flaky? Same input produces inconsistent output. Fix the verifier (add determinism, stabilize inputs) — not by loosening the check.
• Is the verifier out of date? The world moved; the rubric didn't. Update the rubric via governance-change process — not by skipping runs.
• Is the verifier wrong? Replace it with a better verifier — via governance-change process.
• Is this a legitimate governance-rubric issue? If yes, investigate-issue may surface findings that route here for rubric update.

The audit output

[Details of audit output and artifact storage are maintained here to support governance reviews and external audits.]

Quick Start

Review every rubric-affecting change in your PR and confirm anti-drift discipline with a complete evidence trail.