Canonicalize the PETROVA governance model
Date: 2026-07-28 Status: accepted Supersedes: none Superseded-by: none — current
Context
Section titled “Context”A documentation audit found the governance model was real in code but
scattered across the docs with no single authoritative page: the rules
lived in core/playbook/META-RULES.md, the verbs in
spec/verbs/README.md, and the mental model across eight concepts/
pages — while three live enforcement layers (the MR audit in
host/src/sources/audit.ts, act-time phase-integrity in
host/src/tools/phase-guard.ts, and the cosign firewall opt-out in
cli/src/cosign.ts) were documented only in code and internal
docs/superpowers/specs/. The audit also surfaced a pervasive stale
count — public docs claimed “nine verbs” when spec/verbs/ holds 18
schemas (16 exposed as petrova.act.* write verbs). Understating the
write surface by half misleads operators about the governance boundary
and conflicts with MR-16 (catalogue realism).
Upholds: MR-7, MR-16.
Decision
Section titled “Decision”Establish docs/site/concepts/governance.md as the single canonical
umbrella for the governance model — naming every primitive (verbs,
registry admission, the profile / fleets_allowed / contract_committers
gates, integrations_applicability, idempotency, dry-run default,
phase-integrity, the live MR audit, and the MR-12 merge firewall) and
linking out to each mechanism page. Add two missing mechanism pages
(concepts/phase-integrity.md, concepts/governance-audit.md) and
reconcile every living reference doc to the verified counts: 18
control-plane verb schemas; 16 petrova.act.* write verbs; diagnose
read-only; daedalus_distribute CLI-only; 42 Fleet MCP tools, 17
mutating. Append-only decision history and docs/site/generated/
(machine-built) are left untouched except via regeneration. The
sync-docs.mjs verb-catalogue intro is changed to compute the count
from the schema directory so it cannot drift again.
Alternatives considered
Section titled “Alternatives considered”- Audit-and-fix in place, no canonical page — leaves the model implicit and the enforcement layers undocumented; the next drift has no home to reconcile against. Rejected.
- Put the canonical doc in
docs/decisions/— decisions are point-in-time and append-only (MR-7); a living reference belongs inconcepts/, which is explicitly framed as the load-bearing mental model. This decision doc ratifies; the concept page carries the model.
Consequences
Section titled “Consequences”For code:
scripts/sync-docs.mjsverb-catalogue heading now derives the verb count fromspec/verbs/rather than hard-coding “nine”.
For docs:
- New:
concepts/governance.md,concepts/phase-integrity.md,concepts/governance-audit.md. - Updated:
concepts/verbs.md,concepts/registry.md,concepts/index.md,docs/site/_meta/sidebar.yaml,docs/site/overview/what-is-petrova.md,docs/site/cli/install.md,docs/site/_meta/conventions.md,spec/verbs/README.md,CLAUDE.md. - Regenerated:
docs/site/generated/viasync-docs.mjs.
For in-flight phases:
- None. Documentation-only change.
For invariants:
- No MR added or changed. Reinforces MR-16 (the documented and exposed verb surfaces must agree).
References
Section titled “References”- Governance audit:
host/src/sources/audit.ts. - Phase integrity:
host/src/tools/phase-guard.ts,docs/superpowers/specs/2026-05-16-phase-integrity-design.md. - Cosign firewall:
docs/decisions/2026-07-28-cosign-automerge-firewall-optout.md. - Verb catalogue:
spec/verbs/,spec/verbs/_common.schema.json.
Sign-off
Section titled “Sign-off”- Subagent: docs-governance (session 60f31208)
- Human: Alex — confirmed 2026-07-28.