Governance model

Implemented

Source: doc/Governance_Overview.md · doc/governance/agent_policy.yaml · doc/governance/reviewguard_policy_draft.yaml · doc/governance/Contract_Invariant_Gates.md · doc/governance/production_enforcement_policy.yaml · doc/governance/Coding_Standards.md · doc/governance/Testing_Standards.md

The full stack of rules that govern change in this codebase — from machine-enforced policy to reviewer prose — and which wins when they disagree.

Precedence stack (high → low)

flowchart TB
    classDef tier1 fill:#ffebee,stroke:#c62828,color:#c62828
    classDef tier2 fill:#fff3e0,stroke:#e65100,color:#e65100
    classDef tier3 fill:#e3f2fd,stroke:#1565c0,color:#1565c0

    T1[Tier 1 — Machine baseline]:::tier1
    T1 --> P1[1. agent_policy.yaml<br/>agent execution rules]
    T1 --> P2[2. reviewguard_policy_draft.yaml<br/>PR-level gates]
    T1 --> P3[3. API contracts<br/>openapi.draft.yaml<br/>asyncapi.draft.yaml]

    T2[Tier 2 — Machine policies]:::tier2
    T2 --> P4[4. openapi.spectral.yaml<br/>lint policy]
    T2 --> P5[5. Contract_Invariant_Gates.md<br/>non-negotiable checks]
    T2 --> P6[6. production_enforcement_policy.yaml<br/>production controls]
    T2 --> P7[7. Contract_Versioning_Policy.md<br/>evolution rules]
    T2 --> P8[8. CI_Enforcement_Checklist.md<br/>pipeline gate requirements]
    T2 --> P9[9. Agent_Enforcement.md<br/>agent behavior rules]

    T3[Tier 3 — Prose docs]:::tier3
    T3 --> P10[10. Coding_Standards.md]
    T3 --> P11[11. Testing_Standards.md]
    T3 --> P12[12. Security governance:<br/>Threat_Model + Control_Verification]
    T3 --> P13[13. Assumptions_Register.md]
    T3 --> P14[14. Production_Platform_Baseline.md]

    T1 -->|wins ties| T2
    T2 -->|wins ties| T3

Higher tier = wins more disagreements. The top three are the machine-enforced floor.

Why three tiers

flowchart LR
    classDef bad fill:#ffebee,stroke:#c62828
    classDef ok fill:#d1e7dd,stroke:#0a3622

    DRIFT[Prose doc says X<br/>Code does Y] -.tier-3 only.-> NOENF[Nobody catches it<br/>until a customer does]:::bad
    DRIFT2[Machine policy says X<br/>Code does Y] -.tier-1 enforcement.-> BLOCK[CI rejects the PR<br/>at the boundary]:::ok

    note[Reality: prose drifts.<br/>The platform routes around drift<br/>by encoding load-bearing rules<br/>as machine policy.]

Tier 1/2 artifacts are executable:

• agent_policy.yaml — read by the agent orchestrator + CI gates
• reviewguard_policy_draft.yaml — read per PR
• openapi.spectral.yaml — runs in lint
• scripts/ci/*.sh — runs in pipeline

Tier 3 artifacts are reviewer-enforced. They guide judgement but don't block on their own.

Policy scope (what the rules cover)

mindmap
  root((Policy scope))
    Contract-first / API-first
      Every API change starts in spec
      No UI feature bypasses API
      Generated types only at HTTP boundary
    Security & secret handling
      No secrets in code or repo
      Sanitize-first logging
      Signed task params for fleet
      mTLS internal
    Data integrity & idempotency
      Immutable ledger
      Immutable audit
      Idempotency keys on mutations
      Outbox pattern for events
    Compatibility & versioning
      Breaking changes get rollout note
      Spec backward-compat by default
      OpenAPI breaking-change diff gate
    Testing & CI gates
      Evidence-first verification
      Acceptance matrix per PR
      Integration against real infra
      Schemathesis contract tests
    Agent-generated PR requirements
      Contract-first read before write
      Sanitize before log
      Audit row in same tx
      No symptom-only fixes

Change-control sequence

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

sequenceDiagram
    autonumber
    participant PR as Proposer (human or agent)
    participant OWN as Architecture / security owner
    participant POL as Machine policy<br/>(agent_policy / reviewguard / spectral)
    participant CI as scripts/ci/*.sh
    participant DOC as Prose doc

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

Why this matters for multi-agent execution

flowchart TB
    AGENT[Coding agent] --> READ[Read prose docs<br/>understand intent]
    READ --> PLAN[Plan change]
    PLAN --> CHK[Check against<br/>agent_policy.yaml allowlists]
    CHK --> EDIT[Edit code]
    EDIT --> LOC[Run local tests + lint]
    LOC --> PR[Open PR]
    PR --> RG[reviewguard]
    RG --> CIG[scripts/ci/*.sh gates]
    CIG --> 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 CHK,LOC,RG,CIG machine
    class REV,MERGE human

The agent reads prose (intent) but acts based on machine policy (constraint). When the two disagree, the agent's PR will fail CI — that's the system telling someone to align the prose with the machine policy, not vice versa.

Standards stack — what each prose doc owns

mindmap
  root((Standards docs<br/>tier 3))
    Code quality
      Coding_Standards.md
        Handler shape
        Service shape
        14 mandatory rules
        Patterns + naming
      Pre_MVP_Simplification_Policy
        Avoid premature abstraction
    Testing
      Testing_Standards.md
        Pyramid
        Acceptance matrix AT-001 to AT-083
        Evidence-first
        Coverage targets
      Test_Ownership_Matrix.md
      Test_Data_Strategy.md
      Frontend_E2E_Validation_Model_v1.md
    Security
      Security_Threat_Model
      Security_Control_Verification
      Abuse_Case_Catalog
      Pen_Test_Scope
    Observability
      Observability_Standards.md
      Error_Traceability_DNA_Standard
    Process
      Evidence_First_Change_Protocol
      Task_Authoring_Standard
      Design_Baseline_Gate
      Agent_Startup_Prompts
    Release
      Platform_Control_Release_Promotion_Policy
      CI_Pipeline_Implementation
      Pipeline_Blueprint

When sources conflict

flowchart TB
    DISC[Discrepancy found<br/>between two sources] --> ASK{Which tier wins?}
    ASK -- machine policy --> A1[Update prose to match machine]
    ASK -- prose canonical &<br/>machine stale --> A2[Update machine policy FIRST]
    A2 --> A3[Add CI gate 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]
    AUD --> DONE[Reconciled]

    classDef act fill:#fff3e0,stroke:#e65100
    classDef done fill:#d1e7dd,stroke:#0a3622
    class A1,A2,A3,A4,NOTE act
    class DONE done

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

Cross-references

If you want	Go to
The machine policy file itself	Policy & enforcement
How agents read this stack	Multi-agent orchestration
Per-PR check sequence	CI gates (Developers section)
Security-policy view	Governance precedence (Security section)
Standards for code	Coding patterns (Developers section)
Standards for tests	Testing patterns (Developers section)
Source-of-truth doc	Governance_Overview.md