Skip to content
PETROVA

TASKSET 2 — completed governance audit (MR-1, MR-3, MR-5, MR-8, MR-12, MR-13)

date: 2026-05-10 slug: governance-audit-completeness status: open mr: [MR-1, MR-3, MR-4, MR-5, MR-7, MR-8, MR-10, MR-12, MR-13] outranks: finding

Section titled “date: 2026-05-10 slug: governance-audit-completeness status: open mr: [MR-1, MR-3, MR-4, MR-5, MR-7, MR-8, MR-10, MR-12, MR-13] outranks: finding”

TASKSET 2 — completed governance audit (MR-1, MR-3, MR-5, MR-8, MR-12, MR-13)

Section titled “TASKSET 2 — completed governance audit (MR-1, MR-3, MR-5, MR-8, MR-12, MR-13)”

Context

Section titled “Context”

The petrova.governance.audit MCP tool existed and already checked three meta-rules (MR-4 filename dates, MR-7 superseded-doc links, MR-10 verification-round artefacts). Six of the nine targeted meta-rules (MR-1, MR-3, MR-5, MR-8, MR-12, MR-13) had no automated check — their audit cells were always empty. The /console/repo/{slug} page made no petrova.governance.audit RPC call and rendered no MR compliance grid.

Additionally, [slug].astro used "verified" and "consistent" as keys in its outcome lookup maps, but contracts/state.schema.json only allows ok, degraded, failing, stale, not_applicable, pending — causing all integration-status pills to render with fallback styling.

Decision

Section titled “Decision”

Implement each missing check as a small, isolated async function in host/src/sources/audit.ts, consistent with the existing auditMr4 / auditMr7 / auditMr10 pattern. Wire all six into AuditSource.run() via Promise.all alongside the three existing checks. Update the dashboard repo-detail page to surface the full MR grid.

Check implementations

Section titled “Check implementations”

MR-1 — North-star outranks the backlog (auditMr1)

  • Verifies docs/north-star/ exists and contains at least one markdown doc.
  • Samples the 3 most-recent decision docs; checks each for outranks: front-matter.
  • pass: north-star present, sampled decisions carry outranks:.
  • warn: north-star absent, or north-star empty, or recent decisions missing outranks:.
  • Full DAG cycle-detection is left to the docs-invariants CI workflow (per-project).

MR-3 — Sibling files stay sibling (auditMr3)

  • Reads .petrova/contract.yaml; if it declares sibling_pairs:, verifies both files in each pair exist at the declared paths via the Contents API.
  • skip: no contract.yaml or no sibling_pairs: declared (not every project has pairs).
  • pass: all declared pairs verified.
  • fail: one or more pair members missing.

MR-5 — PR required for multi-file changes (auditMr5)

  • Calls GET /repos/{owner}/{repo}/branches/{branch}/protection.
  • pass: protection active with ≥1 required approving review.
  • warn: protection present but no required reviews, or no protection at all.
  • skip: 403 / cannot read protection (insufficient scope — common for public repos with read-only App credentials).

MR-8 — Invariants numbered and stable (auditMr8)

  • Fetches CLAUDE.md; finds all I-\d+ references via regex.
  • pass: invariants declared, no duplicate I-N number.
  • fail: duplicate invariant number detected.
  • skip: no CLAUDE.md, or CLAUDE.md contains no I-N declarations.

MR-12 — CLAUDE.md is the projection, not the source (auditMr12)

  • Verifies CLAUDE.md exists, docs/north-star/ contains at least one doc, and CLAUDE.md references docs/north-star/ or MILESTONES.md.
  • pass: all three conditions met.
  • warn: north-star absent, or CLAUDE.md does not reference canonical sources.
  • skip: no CLAUDE.md.

MR-13 — Intent and observation are separate state spaces (auditMr13)

  • Fetches .petrova/contract.yaml; checks body for observation-side field names (probe_history, current_status, last_verified_at, outcome, actual_contract_sha, contract_drift).
  • fail: any observation-side field found in the intent file.
  • pass: none found.
  • skip: no .petrova/contract.yaml.
  • Note: contract_drift delta (intent vs. observed SHA) is surfaced separately by the sweep-state signal; this check covers structural conflation only.

Infrastructure changes

Section titled “Infrastructure changes”
  • AuditSource.run() updated to fetch docs/north-star/ dir, CLAUDE.md, and .petrova/contract.yaml in a single parallel batch alongside the existing docs/decisions/ and docs/findings/ fetches.
  • ALL_MRS array added to ensure skip rows are emitted for every MR when the repo URL is unparseable.
  • host/src/mcp.ts tool description updated to list all 9 covered MRs.

Dashboard changes ([slug].astro)

Section titled “Dashboard changes ([slug].astro)”
  • petrova.governance.audit called in parallel with the 5 existing RPC calls.
  • New “Governance audit” section renders a 3-column table (MR / status pill / detail) with pass/warn/fail/skip colour coding.
  • Outcome vocab fixed: OUTCOME_LABELS, OUTCOME_CLASS, OUTCOME_GLYPH maps now use schema-valid keys (ok, degraded, failing, stale, not_applicable, pending) instead of the former "verified" / "consistent" strings that never matched.

Alternatives considered

Section titled “Alternatives considered”
  • Per-MR RPC tools (petrova.audit.mr1, etc.): rejected — adding 6 new tool registrations for reads that are already co-located in the audit scan adds surface area without benefit. The existing petrova.governance.audit tool with optional slug scoping is sufficient.
  • Persisting audit results to state/<slug>.yaml: considered for dashboard caching. Deferred — the in-process TTL cache (5 min) is adequate for current traffic; persisting adds a write path for a read-only signal, which cuts against the sweeper-first principle.
  • Full DAG validation for MR-1: rejected for this taskset — requires fetching every doc’s front-matter and building a graph, adding significant API call volume. Delegated to the per-project docs-invariants CI workflow per the playbook design.

Verification gates (MR-10)

Section titled “Verification gates (MR-10)”
  • petrova.governance.audit returns 9 rows per registered repo (MR-1 through MR-13, with skips for repos without the relevant files).
  • /console/repo/{slug} renders a “Governance audit” table with pass/warn/fail/skip badges for each MR.
  • Integration-status pills on /console/repo/{slug} correctly render using schema-valid outcome values (ok, degraded, etc.).
  • cd host && npm test → 74 passed.
  • cd cli && npm test → 185 passed (pre-existing diagnose failure unchanged).
  • cd dashboard && npx astro check → 0 errors.

References

Section titled “References”
  • TASKSET 2 scope: implementation-strategy document (2026-05-10)
  • host/src/sources/audit.ts — all check implementations
  • core/templates/META-RULES.md — canonical MR definitions (v1.1)
  • MR-7: decision docs are dated and append-only
  • MR-10: verification rounds mandatory at phase close