Skip to content

ADR-0005 — Evaluator Pattern for Repository Governance

  • Status: Accepted
  • Date: 2026-07-01
  • Related: OSSA Repository Standard, AI Context Standard (2026)

Context

Initial approaches to repository governance implemented "validators" or "engines" that actively attempted to parse unknown repository state and recommended (or executed) destructive cleanup actions. This proved dangerous and brittle when applied to highly volatile or "messy" environments (e.g. recovery scenarios, legacy infrastructure repositories, or active feature branches). We need a mechanism to enforce the OSSA Repository Standard and AI Context Standard securely across any repository without risking data loss or conflicting with higher-level orchestration decisions.

Decision

Adopt the Evaluator Pattern for repository governance in OSSA. The tool (e.g. ossa evaluate-repo) will strictly function as an evidence collector and policy evaluator, separated entirely from governance execution.

Rule

The Evaluator must strictly answer three questions: 1. What exists? (Inventory) 2. What policy applies? (Policy Resolution via YAML + Overrides) 3. Does reality satisfy policy? (Findings mapping to stable Rule IDs)

Constraints: - The Evaluator must be 100% read-only. - It must NEVER recommend, schedule, or execute data mutation (e.g. deleting files, archiving folders, popping stashes). - All findings must be assigned a stable Rule ID (e.g., REPO-001, GIT-003) to ensure they are machine-readable and actionable by higher-level governance engines or agents. - The evaluation output must be byte-for-byte deterministic when evaluating the same repository state against the same policy. - Unknown states (e.g., unclassified directories) must default to WARNING requiring human classification, not FATAL requiring deletion.

Consequences

  • Automation and CI pipelines can safely run evaluations on every commit without fear of destructive automation.
  • Agents (Claude, etc.) have stable, JSON-formatted evidence to inform orchestration decisions.
  • Governance workflows (e.g., automated cleanup, migrations) move out of the CLI evaluation layer and into explicit orchestrator workflows that consume the Evaluator's output.