Skip to content
PETROVA

Control plane vs source-of-truth

PETROVA splits two things most documentation systems conflate: methodology (how you work) and project truth (what the work governs).

The split

Section titled “The split”
Lives in PETROVA-HQ (the control plane)Lives in each consumer repo
META-RULES.md (MR-1 … MR-12)docs/north-star/intent.md
Verb schemas (spec/verbs/*.json)MILESTONES.md
Registry (registry.yaml)docs/decisions/*.md
Bootstrap prompts (core/prompts/)docs/findings/*.md
Integration contractsAGENTS.xml (consumer roster)
Skill packages (skills/*)docs/spec/ (project requirements)

The dividing line is MR-12: a CLAUDE.md projects from grounded sources; it does not introduce facts of its own. Methodology is shared because every petrova-line repo uses the same MRs, the same verbs, the same fleet identity grammar. Project truth is local because what kahn-hq is for and what smo1-io is for differ — and their decision ledgers must travel with their code.

Why the split is load-bearing

Section titled “Why the split is load-bearing”

Putting north-star content in a central database would break three things at once:

  • git blame stops working. Decision context decouples from the code it justified.
  • Branch protection bypasses become possible. A central edit surface that doesn’t go through PR review violates the every write is reviewable invariant.
  • Cross-repo intent confusion. A central north-star tempts you to homogenise project intent. Different repos serve different purposes; central storage erodes that.

Centralising methodology has the inverse effect: every consumer repo inherits the same disciplined rules without re-litigating them, and a single MR change ripples cleanly through the whole line.

What this means in practice

Section titled “What this means in practice”

When you find yourself reaching for “where should this live?”:

  • If it’s the how of working (a process rule, a verb shape, an agent-fleet boundary), it belongs in PETROVA-HQ.
  • If it’s the what of a specific project (intent, constraints, history), it belongs in that consumer repo.
  • If it’s both — say, an architectural decision that has methodology implications — open the decision in the consumer repo (per MR-7), and if it ends up changing an MR, open a follow-up decision here to record the methodology change.

See also

Section titled “See also”