Skip to content

03 — OSSA Repository Governor Specification

Status: Partially Adopted — RepositoryState (Repository-State-Schema.json) is the canonical schema for config/platform-project-inventory.json (the Estate inventory, hq-pt7w). The deep git/worktree-hygiene fields (spec.*, status.health) described below remain an unimplemented design proposal; the gitlab block added to the schema is implemented and populated by a GitLab-API-only generator (agent-buildkit projects inventory) that does not require a local clone. Authority: OSSA / Bluefly Engineering Governance Stability: gitlab block: implemented. Everything else in this spec: Evolving — design proposal, not yet implemented. Governs under: 01-repository-governance-standard.md Version: 0.2.0

Purpose

This document specifies the OSSA Repository Governor — the long-term platform capability that replaces ad hoc git governance scripts with a governed, auditable, agent-consumable service.

The goal is not to automate Git. The goal is to make repository governance a first-class OSSA capability.

What the Governor Is

The Repository Governor is an OSSA service that:

  • observes repository state continuously or on demand
  • classifies state against the governance standard
  • evaluates proposed actions against Cedar policy
  • produces auditable evidence (receipts) for every action
  • exposes state as a structured contract consumable by humans, agents, CI, and dashboards

The Governor does not contain authorization logic. The Governor does not interpret policy. The Governor enforces Cedar decisions.

What the Governor Is Not

  • Not a Git automation tool
  • Not a CI/CD system
  • Not the authority (repository state is the authority)
  • Not replaceable by a shell script
  • Not responsible for deciding what is safe (Cedar decides)

Contract-First Architecture

The first artifact to build is the RepositoryState contract — not the CLI, not the dashboard.

Every other component — CLI, dashboard, Cedar policies, agent integrations — consumes or produces this contract. Shared schema eliminates re-invention at every layer.

RepositoryState Contract

kind: RepositoryState
apiVersion: ossa.bluefly.io/v1
metadata:
  name: <string>              # repository name
  namespace: blueflyio/*      # org namespace
  path: <absolute>            # local filesystem path
  remote: <url>               # origin remote
  observed_at: <iso8601>

spec:
  branches:
    authority: <string>       # e.g., main
    release: <string>         # e.g., release/v0.1.x
    integration: <string>     # e.g., develop
    current: <string>
    protected: [list]
    open_mrs: <int>

  commits:
    local_only: <int>         # ahead of remote
    behind_remote: <int>
    last_push: <iso8601>
    last_commit_sha: <string>
    last_commit_message: <string>

  worktree:
    modified: <int>
    untracked: <int>
    deleted: <int>
    stash_count: <int>
    has_index_lock: <bool>

  hooks:
    installed: [list]
    broken: [list]            # hooks that fail integrity check
    missing_commands: [list]  # referenced commands not on PATH

  artifacts:
    generated: [list]         # paths matching generated artifact patterns
    runtime: [list]           # .entire/, .ddev/.dbimage, *.log
    recovery: [list]          # emergency-backup branches, stash refs
    cache: [list]             # .qmd, .sqlite, __pycache__

status:
  classification:
    tier: <0-4>
    tier_name: <DATA_LOSS_RISK|UNPUSHED|WORKING_TREE|GENERATED|HEALTHY>
    classified_at: <iso8601>

  protection:
    verdict: CLEAN | BLOCKED | UNSCANNED | REQUIRES_OPERATOR
    scanned_at: <iso8601>
    blocked_patterns: [list]
    blocked_paths: [list]
    evidence_ref: <string>    # receipt ID

  health:
    # Derived — never stored directly
    # Computed from: local_only, secret_scan_verdict,
    #               hook_state, merge_debt, last_push_days_ago,
    #               has_index_lock, has_remote
    tier: PRISTINE | HEALTHY | STALE | AT_RISK | CRITICAL | EMERGENCY
    score: <0-100>
    computed_at: <iso8601>
    inputs:
      local_only_commits: <int>
      secret_scan_verdict: <string>
      broken_hooks: <int>
      merge_debt_days: <int>
      last_push_days_ago: <int>
      has_index_lock: <bool>
      has_remote: <bool>

  last_receipt_ref: <string>  # most recent RepositoryPreservationReceipt ID

RepositoryPreservationReceipt Contract

Every preservation action emits an immutable receipt.

kind: RepositoryPreservationReceipt
apiVersion: ossa.bluefly.io/v1
metadata:
  id: <uuid>
  repository: <name>
  session_ref: <bead_id>
  operator: <string>
  timestamp: <iso8601>

spec:
  repository_state_ref: <RepositoryState id at time of action>

  branch:
    original: <string>
    preservation: <string>
    created_new: <bool>

  classification:
    tier: <0-4>
    tier_name: <string>

  protection:
    verdict: CLEAN
    patterns_evaluated: [list]
    paths_evaluated: [list]
    scan_duration_ms: <int>

  cedar:
    policy_ref: <string>
    decision: ALLOW | DENY | REQUIRES_OPERATOR
    principal: <string>
    action: <string>
    resource: <string>

  commit:
    sha: <string>
    message: <string>
    files_staged: <int>

  push:
    sha: <string>
    remote: <string>
    verified: <bool>
    local_matches_remote: <bool>
    push_duration_ms: <int>

status:
  complete: <bool>
  error: <string | null>

Capability Architecture

Capabilities are independent services, not sequential phases. The workflow sequences them. They do not depend on each other's implementation.

┌─────────────────────────────────────────────────────────────┐
│                    OSSA Repository Governor                  │
├──────────────┬──────────────┬──────────────┬────────────────┤
│  Inventory   │Classification│  Protection  │   Planning     │
│  Capability  │  Capability  │  Capability  │  Capability    │
├──────────────┴──────────────┴──────────────┴────────────────┤
│                    Execution Capability                      │
├─────────────────────────────┬───────────────────────────────┤
│    Verification Capability  │    Evidence Capability         │
└─────────────────────────────┴───────────────────────────────┘
         │                              │
         ▼                              ▼
  RepositoryState                RepositoryPreservationReceipt
    (contracts)                        (receipts)
         │                              │
         ▼                              ▼
   Cedar Policies              ContractPlane Evidence

Cedar Integration

The Governor never contains authorization logic. It submits requests to Cedar.

Cedar request schema:

{
  "principal": { "type": "Agent", "id": "<agent-id>" },
  "action": { "id": "<action>" },
  "resource": {
    "type": "Repository",
    "id": "<repo-name>",
    "attributes": {
      "current_branch": "<string>",
      "tier": "<0-4>",
      "protection_verdict": "CLEAN",
      "has_deletions_staged": false,
      "hook_state": "BROKEN | PASSING | MISSING"
    }
  },
  "context": {
    "session_ref": "<bead_id>",
    "timestamp": "<iso8601>"
  }
}

Cedar returns:

{ "decision": "Allow" }
{ "decision": "Deny" }
{ "decision": "Allow", "conditions": ["REQUIRES_OPERATOR_ANNOTATION"] }

Policy files live in: cedar-policies/repository-governance/

Policies to define:

  • release-branch-protection.cedar — prohibit direct commits to release/*
  • deletion-guard.cedar — require operator approval for staged deletes
  • secret-scan-override.cedar — defines conditions under which blocked repos can be overridden
  • preservation-commit.cedar — allows/denies preservation commits per branch and tier

CLI Design

# Capability 1 — Inventory (read only)
ossa repo status [--repo <path>] [--all] [--format json|table|yaml]

# Capability 2 — Classification (read only)
ossa repo classify [--all] [--output <file>]

# Capability 3 — Protection scan (read only, pre-staging)
ossa repo scan [--repo <path>] [--all]

# Capability 4 — Generate preservation plan (read only)
ossa repo plan [--tier 0|1|2] [--output <file>]

# Capability 5+6 — Execute approved plan (writes — requires plan file)
ossa repo preserve --plan <file> [--repo <name>]

# Capability 7 — Verify push
ossa repo verify [--repo <path>] [--all]

# Reporting
ossa repo merge-debt [--all] [--older-than 14d]
ossa repo dashboard [--format terminal|json|html]
ossa repo receipts [--repo <name>] [--session <ref>]

All commands return structured output matching the RepositoryState or receipt schemas. All writes emit receipts.

OSSA Integration Map

governor_integrates_with:

  OSSA_Contracts:
    role: Schema authority — RepositoryState and receipt schemas live here
    repo: openstandardagents

  Cedar_Policies:
    role: Authorization decisions — all ALLOW/DENY/REQUIRES_OPERATOR
    repo: cedar-policies/repository-governance/

  ContractPlane_SDK:
    role: Evidence boundary — receipts are stored and queryable here
    repo: contractplane-sdk

  Context_CLI:
    role: Memory surface — repository state snapshots for agent sessions
    repo: context-cli

  Compliance_Engine:
    role: Audit trail — every governance action logged
    repo: compliance-engine

  QMD:
    role: Queryable index — "which repos are at tier 0?" is a QMD query
    directive: qmd query "repository_state tier=0"

  Gas_Town:
    role: Session state and convoy tracking for multi-repo operations

  BD:
    role: Task authority — remediation work items for BLOCKED repos

  Agent_Bootstrap_Authority:
    role: Drupal-side dashboard rendering of Governor state
    repo: __DRUPAL/Module/agent_bootstrap_authority

Build Sequence

Phase 1 — Contract (highest leverage, unlocks everything else)

  1. Define RepositoryState schema in openstandardagents/schemas/
  2. Define RepositoryPreservationReceipt schema
  3. Write JSON Schema validators
  4. Write example instances

Phase 2 — Cedar Policies

  1. release-branch-protection.cedar
  2. deletion-guard.cedar
  3. preservation-commit.cedar
  4. Wire Cedar evaluation into manual workflow (even before CLI exists)

Phase 3 — CLI (thin wrapper, contract-returning)

  1. ossa repo status — reads git state, emits RepositoryState JSON
  2. ossa repo classify — classifies state, emits priority queue
  3. ossa repo scan — protection scan, emits verdict
  4. ossa repo plan — preservation plan, emits plan file
  5. ossa repo preserve — executes approved plan, emits receipt
  6. ossa repo verify — SHA verification, updates receipt

Phase 4 — Evidence integration

  1. Receipts flow to ContractPlane
  2. QMD indexes RepositoryState records
  3. Context CLI surfaces state to agent sessions

Phase 5 — Dashboard

  1. ossa repo dashboard terminal view
  2. Drupal-side dashboard via agent_bootstrap_authority

Where It Lives

PROJECTS/
  openstandardagents/
    schemas/
      repository-state.schema.json
      repository-preservation-receipt.schema.json

  cedar-policies/
    repository-governance/
      release-branch-protection.cedar
      deletion-guard.cedar
      preservation-commit.cedar
      secret-scan-override.cedar

  context-cli/
    # surfaces repository state to agent sessions

  compliance-engine/
    # audit trail for all governance events

  contractplane-sdk/
    # receipt storage and evidence boundary

  # Future: Governor CLI binary
  # Could live in openstandardagents or as a new dedicated repo

Success Condition

The Repository Governor is complete when:

ossa repo status

returns a RepositoryState contract that every agent, human, dashboard, and CI system can consume without re-discovering git state from scratch.

And when:

ossa repo preserve --plan approved-plan.yaml

produces a RepositoryPreservationReceipt that Cedar authorized, ContractPlane recorded, and QMD can query — with no shell script inventing its own workflow.