Skip to content

Governance precedence

Implemented

Source: doc/Governance_Overview.md · doc/governance/agent_policy.yaml · doc/governance/reviewguard_policy_draft.yaml

What overrides what when sources disagree. Multi-agent contribution + contract-first development means precedence has to be unambiguous and machine-enforceable, not aspirational prose.

Priority order

flowchart TB
    classDef high fill:#ffebee,stroke:#c62828,color:#c62828
    classDef mid fill:#fff3e0,stroke:#e65100,color:#e65100
    classDef low fill:#e3f2fd,stroke:#1565c0,color:#1565c0

    P1[1. agent_policy.yaml<br/>machine-enforced baseline]:::high
    P2[2. reviewguard_policy_draft.yaml<br/>PR-level governance]:::high
    P3[3. API contracts<br/>openapi.draft.yaml<br/>asyncapi.draft.yaml]:::high
    P4[4. openapi.spectral.yaml<br/>OpenAPI lint policy]:::mid
    P5[5. Contract_Invariant_Gates.md<br/>non-negotiable contract checks]:::mid
    P6[6. production_enforcement_policy.yaml<br/>machine-readable production controls]:::mid
    P7[7. Contract_Versioning_Policy.md<br/>evolution rules]:::mid
    P8[8. CI_Enforcement_Checklist.md<br/>pipeline gate requirements]:::mid
    P9[9. Agent_Enforcement.md<br/>agent behavior rules]:::mid
    P10[10. Coding_Standards.md<br/>code quality/security style]:::low
    P11[11. Testing_Standards.md<br/>test + acceptance requirements]:::low
    P12[12. Security_Threat_Model.md +<br/>Security_Control_Verification.md]:::low
    P13[13. Assumptions_Register.md<br/>MVP assumptions, re-validation triggers]:::low
    P14[14. Production_Platform_Baseline.md<br/>required platform controls]:::low

    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7 --> P8 --> P9 --> P10 --> P11 --> P12 --> P13 --> P14

Higher = wins more disagreements. Top three are the machine-enforced floor.

Three tiers, simplified

flowchart LR
    T1[Tier 1: Machine baseline<br/>1–3]:::t1
    T2[Tier 2: Machine policies<br/>4–9]:::t2
    T3[Tier 3: Prose docs<br/>10–14]:::t3
    T1 -->|wins ties| T2
    T2 -->|wins ties| T3

    classDef t1 fill:#ffebee,stroke:#c62828
    classDef t2 fill:#fff3e0,stroke:#e65100
    classDef t3 fill:#e3f2fd,stroke:#1565c0
  • Tier 1 is enforced by CI and reviewguard. PRs violating it are rejected automatically.
  • Tier 2 is enforced by gate scripts in scripts/ci/*.sh. PR fails the build.
  • Tier 3 is reviewer-enforced. Disagreements are reviewer judgment, but if a prose doc conflicts with a tier-1/2 policy, the higher tier wins.

Policy scope (what these rules cover)

  • Contract-first / API-first
  • Security and secret handling
  • Data integrity and idempotency
  • Compatibility / versioning
  • Testing and CI gates
  • Agent-generated PR requirements

Change-control sequence

When a rule changes, the order is machine-readable first, prose last:

sequenceDiagram
    autonumber
    participant PR as Proposer
    participant ARCH as Architecture / security owner
    participant POL as agent_policy.yaml<br/>reviewguard_policy.yaml<br/>spectral.yaml
    participant SCR as scripts/ci/*.sh
    participant DOC as Prose doc

    PR->>ARCH: change proposal
    ARCH->>ARCH: review impact
    alt approved
        PR->>POL: update machine policy
        PR->>SCR: update CI gate if needed
        PR->>SCR: add regression test
        PR->>DOC: update prose doc + rollout note
        PR->>ARCH: PR with all four
        ARCH->>PR: approve
    end
    Note over PR,DOC: Order matters: machine policy MUST<br/>change before prose, so CI is<br/>the source of truth.

Mandatory rules around change:

  • Governance changes require architecture or security owner review.
  • Breaking policy changes must include a written rollout note.
  • Machine-readable policies are updated before prose docs.
  • Assumptions affecting architecture / contracts / security tracked in Assumptions_Register.md.

Machine-readable artifacts (the floor)

flowchart LR
    AP[agent_policy.yaml] --> AAGENT[Agent task validation<br/>rejects allow-list violations]
    RG[reviewguard_policy_draft.yaml] --> RPR[Per-PR check:<br/>required reviewers,<br/>breaking-change labels,<br/>title format]
    SP[openapi.spectral.yaml] --> SLINT[Spectral lint in CI]
    PE[production_enforcement_policy.yaml] --> PGATE[Production deploy gate]

    classDef art fill:#e3f2fd,stroke:#1565c0
    classDef enf fill:#d1e7dd,stroke:#0a3622
    class AP,RG,SP,PE art
    class AAGENT,RPR,SLINT,PGATE enf

Sources:

When sources conflict

flowchart TB
    DISC[Discrepancy found<br/>between two sources] --> ASK{Which has<br/>higher precedence?}
    ASK -- machine policy wins --> A1[Update prose to match machine]
    ASK -- prose is canonical &<br/>machine is stale --> A2[Update machine policy FIRST]
    A2 --> A3[Add CI gate / reviewguard rule<br/>if not already enforced]
    A3 --> A4[Update prose]
    A1 --> NOTE[Add rollout note if breaking]
    A4 --> NOTE
    NOTE --> COMMIT[PR with all changes]
    COMMIT --> AUD[Audit row + governance owner review]

    classDef act fill:#fff3e0,stroke:#e65100
    class A1,A2,A3,A4 act

The rule "machine policy first" means: at no point is reality enforced only by prose. Either the machine catches a violation, or the violation is allowed.

Agent contribution model

This codebase is contributed to by multi-agent flows. Governance precedence is critical for them because:

  • Agents read prose docs (low precedence)
  • Agents act based on machine policy (high precedence)
  • Conflicts must be detectable before the agent ships work
flowchart LR
    AGENT[Coding agent] --> READ[Read prose<br/>understand intent]
    READ --> PLAN[Plan change]
    PLAN --> CHECK[Check against<br/>agent_policy.yaml allowlists]
    CHECK --> EDIT[Edit code]
    EDIT --> CITESTS[Run tests + lint locally]
    CITESTS --> PR[Open PR]
    PR --> RG[reviewguard checks]
    RG --> CI[scripts/ci/*.sh gates]
    CI --> REV[Human reviewer]
    REV --> MERGE[Merge]

    classDef agent fill:#fff8e1,stroke:#f57f17
    classDef machine fill:#e3f2fd,stroke:#1565c0
    classDef human fill:#d1e7dd,stroke:#0a3622
    class AGENT,READ,PLAN,EDIT agent
    class CHECK,CITESTS,RG,CI machine
    class REV,MERGE human

Sources:

Where to look next