Governance Model & Sprite Role Hierarchy

ELI5

IRIS governance is like a school club with clear roles. You have a president who makes design decisions, a treasurer who handles money (operators), a secretary who takes notes (documenters), a safety officer who can stop dangerous activities (gate authority), and members who can’t be skipped in important processes (protected). Everyone knows their job and who has the power to say “no.”

Technical Deep Dive

Sprite Role Hierarchy

mindmap
  root((Sprite Roles))
    Architect
      Design decisions
      Default chain routing
      Example: WATNEY-01
    Reviewer
      Code/content review
      Protected: true
      Cannot bypass
      Example: BECK-02
    Documenter
      Technical writing
      Documentation generation
      Example: JOHANSSEN-03
    Operator
      CI/CD
      Deployment
      Infrastructure
      Example: MARTINEZ-04
    Test-Architect
      Test strategy
      Validation
      Example: VOGEL-05
    Planner
      Planning
      Gate authority
      Example: LEWIS-06

Role Definitions

Gate Authority

flowchart TD
    A["Council created"] --> B["Exactly one sprite designated gate_authority"]
    B --> C{"Role of gate authority?"}
    C -->|planner| D["Primary gate authority<br/>(recommended)"]
    C -->|architect| E["Design gate authority"]
    C -->|reviewer| F["Safety gate authority<br/>(protected)"]
    C -->|operator| G["Deployment gate authority"]
    D --> H["Can veto any chain execution"]
    E --> H
    F --> H
    G --> H

Each council designates exactly one sprite as gate authority. This sprite:

• Has veto power at before, after, and on_error checkpoints
• Cannot be bypassed if marked protected: true
• Gate decisions are logged and fully auditable

Protected Sprites

flowchart LR
    A["Chain Execution"] --> B{"Step references protected sprite?"}
    B -->|Yes| C["Cannot skip or bypass"]
    B -->|No| D["Normal execution"]
    C --> E["Protected sprites are mandatory checkpoints"]

A sprite marked protected: true:

• Cannot be bypassed in chain execution
• Cannot be deleted without ?force=true
• Typically assigned to critical roles like reviewer
• Ensures chains cannot skip safety or review steps

Decision-Making Authority

flowchart TD
    A["Decision Required"] --> B{"Type?"}
    B -->|Schema change| C["Maintainers<br/>(locked decisions)"]
    B -->|Contract change| C
    B -->|Council config| D["Contributors<br/>(PR + maintainer review)"]
    B -->|Sprite creation| E["Any authenticated client"]
    B -->|Chain execution| F["Gate authority<br/>(automated rules + veto)"]
    C --> G["Maintainer consensus required"]
    D --> H["At least 1 maintainer review"]
    E --> I["Schema validation + fingerprint"]
    F --> J["Rules evaluated → gate decides"]

Governance File Structure

classDiagram
    class GovernanceModel {
        +Maintainer[] maintainers
        +Contributor[] contributors
        +DecisionRegister decision_register
        +SchemaChangeProcess schema_process
        +ContractChangeProcess contract_process
    }
    class DecisionRegister {
        +Decision[] decisions
        +Status locked
        +Status accepted
        +Status proposed
    }
    class Decision {
        +string id
        +string title
        +Status status
        +string rationale
        +string[] implications
    }
    GovernanceModel --> DecisionRegister : contains
    DecisionRegister --> Decision : contains

Key Terms

• Role → A predefined function within a council: architect, reviewer, documenter, operator, test-architect, planner
• Gate authority → The single sprite per council with veto power (typically a planner)
• Protected sprite → A sprite that cannot be bypassed in chains and requires force-deletion
• Maintainer → Final authority over architectural decisions; can approve/reject PRs
• Contributor → Can propose changes; requires maintainer review for merge
• Decision register → Formal record of architectural decisions with locked, accepted, or proposed status

Q&A

Q: Can any role hold gate authority? A: Technically yes, but planner is the recommended role for gate authority as it aligns with planning and oversight responsibilities. reviewer with protected: true is also common for safety-critical councils.

Q: What happens if a protected sprite is referenced in a chain but marked for deletion? A: The deletion is rejected (409) because the sprite is in an active council. You must first remove it from all councils or use ?force=true (which should be restricted to maintainers).

Q: How many maintainers does iris-hq have? A: All repositories are owned by @devarno. In practice, this means a single maintainer with final authority. Future governance may expand to a multi-maintainer model as the org grows.

Q: Can a contributor override a maintainer’s decision? A: No. Maintainers have final authority. Contributors propose changes via PR; maintainers review and approve.

Q: What is the difference between a rule and gate authority? A: Rules are governance conditions evaluated at council creation and during execution (e.g., “all code must be reviewed”). Gate authority is the specific sprite that evaluates gates and can veto execution. Rules define what should happen; gate authority decides when to stop it.

Examples

The governance model is like a hospital’s organisational chart:

• Chief of Surgery (architect) = Decides surgical techniques and operating procedures
• Nurse Supervisor (reviewer, protected) = Checks every patient chart; cannot be skipped; can stop unsafe practices
• Medical Records (documenter) = Writes and maintains all patient documentation
• Facilities Manager (operator) = Ensures power, water, and equipment function
• Quality Assurance (test-architect) = Designs infection control tests and validation procedures
• Charge Nurse (planner, gate authority) = Coordinates the day’s surgeries; can cancel any operation if conditions are unsafe

The protected reviewer is like the nurse who must sign off on every medication before it’s administered — no exceptions, no bypasses, no matter how urgent the situation.