Skip to content
PETROVA

Defer governance enforcement of contract_committers + integrations_applicability to sub-project G

date: 2026-05-01 status: accepted title: Defer governance enforcement of contract_committers + integrations_applicability to sub-project G supersedes: []

Section titled “date: 2026-05-01 status: accepted title: Defer governance enforcement of contract_committers + integrations_applicability to sub-project G supersedes: []”

Defer governance enforcement of contract_committers + integrations_applicability to sub-project G

Section titled “Defer governance enforcement of contract_committers + integrations_applicability to sub-project G”

Date: 2026-05-01 Status: accepted Supersedes: none Superseded-by: none — current

Context

Section titled “Context”

Reviewer flagged a P1 critical “honesty” finding against sub-project A’s spec (docs/superpowers/specs/2026-04-30-petrova-integration-spine-design.md) §12 “Failure modes and what defends each”. Two rows of that table advertise governance fields as active defenses:

| Agent fleet writes a lying contract | contract_committers: ["humans"] default + git-blame attestation in CI | | not_applicable becomes a green-washing escape hatch | not_applicable_reason + review_by required by schema; integrations_applicability in registry overrides |

The reviewer’s verbatim finding (paraphrased from the round-1 verification notes): the spec describes contract_committers and integrations_applicability as active defenses, but no code in cli/src/ actually reads either field. Schema captures them; the CLI does not enforce them. Shipping the spec as written is dishonest — it implies controls that do not exist.

This is correct. As of the merges of sub-projects A + B + C, both fields are declared but not enforced: registry.yaml carries the values and the JSON schema validates their shape, but no petrova verb verifies contract authors against contract_committers, and no check surfaces a governance-vs-consumer applicability conflict as a failing dashboard row.

Decision

Section titled “Decision”

We are taking path (c) — hybrid:

  1. Sub-project A’s spec wording is downgraded now to match reality. A status note prepended to §12 marks the two relevant rows as aspirational design intent rather than active controls, while preserving the original wording so the target state stays legible.
  2. The actual enforcement work is deferred to a future sub-project G, with a clearly scoped charter (see Consequences for sub-project G’s scope below). Sub-projects C, D, E, F are not blocked by this decision.

No code changes ship under this decision. No schema changes. No CI workflows. The only artefacts produced are the spec edit and this decision doc.

Alternatives considered

Section titled “Alternatives considered”
  • (a) Ship enforcement now, alongside sub-project C. Rejected: governance enforcement is a meaningfully scoped problem (git-blame walks across every consumer’s contract history, fleet-wide CI orchestration, false-positive handling for legitimate machine commits). Bolting it onto C would slow C / D / E / F unnecessarily and would muddle C’s own acceptance gates. Enforcement deserves its own sub-project with its own gates.
  • (b) Silently leave the docs as-is. Rejected: dishonest. The reviewer caught it once; future reviewers (including subagents running 03-verification-round) will refloat the same finding every time they read §12. Honesty in the spec is an MR-7 / MR-12 obligation — CLAUDE.md is a projection of grounded source, and the source must not lie.
  • (c) Hybrid — downgrade the docs now, defer enforcement to a tracked future sub-project. Selected. Restores honesty immediately, preserves design intent, and keeps the enforcement work scoped and trackable.

Consequences for sub-project G’s scope

Section titled “Consequences for sub-project G’s scope”

Sub-project G’s job is to convert the two aspirational rows of spec §12 into active controls. Two checks are in scope:

  • (i) contract_committers attestation. For every consumer slug $slug in registry.yaml, walk the git-blame of that consumer’s .petrova/contract.yaml commit history and verify each author against registry.yaml::repos[$slug].contract_committers. Default ["humans"] rejects machine-authored contract edits unless the repo has explicitly opted in (with a notes: justification, per spec §4).
  • (ii) Applicability conflict detection. Cross-reference each consumer’s not_applicable declarations against registry.yaml::repos[$slug].integrations_applicability. A governance required paired with a consumer not_applicable surfaces as a failing dashboard row with detail: "applicability conflict" (matching the language already in spec §9).

Likely shape: a new CLI verb petrova governance-check that runs both checks locally, plus a fleet-wide GitHub Actions workflow that invokes it across all consumer repos using state/*.yaml as the slug index. Acceptance gates, exact CLI ergonomics, false-positive handling for legitimate bot commits, and the rollout runbook are all left to sub-project G’s own brainstorm + spec phases.

Consequences

Section titled “Consequences”

For code:

  • None under this decision. Sub-project G will add the petrova governance-check verb when it runs.

For docs:

  • docs/superpowers/specs/2026-04-30-petrova-integration-spine-design.md §12 gets a prominent status note prepended (the only edit; original table wording preserved).
  • This decision doc is the tracked landing pad for sub-project G’s future charter.

For in-flight phases:

  • Sub-projects C, D, E, F are unblocked — they do not depend on these governance defenses being live, and the spec now says so honestly.
  • Sub-project G is added to the backlog (charter to be drafted when C/D/E/F have settled).

For invariants:

  • No MR additions or repeals. This decision is consistent with MR-7 (decision docs are dated and append-only — this is a new doc, not a silent edit) and MR-12 (CLAUDE.md and projected docs must not claim what their grounded source doesn’t support).

References

Section titled “References”

Sign-off

Section titled “Sign-off”
  • Subagent: spec-fix-pass (sub-project A P1 follow-up, 2026-05-01)
  • Operator approval: [x] alex@devarno.com — approved 2026-05-01 (path c chosen during sub-project C brainstorm).