Governance overview

Valinor governs a repository in layers. Each layer catches a different class of problem, and the layers reinforce one another — what a fast deterministic check can prove, it proves; what needs judgment, an LLM review handles; and what only shows up over time, a standing audit surfaces. This page explains how the layers fit together and what standards they enforce.

The governance layers

1. A knowledge-architecture doctrine

A portable agent and developer doctrine — your AGENTS.md ≡ CLAUDE.md, kept byte-identical — states the methodology your contributors and coding agents follow, plus the per-project facts and gotchas that keep it current. Valinor propagates a versioned canonical doctrine into the file and verifies it hasn't drifted, so the way your team works is written down and enforced, not folklore.

2. Deterministic gates

Fast, offline, fail-closed checks that prove machine-verifiable facts about your repo:

• A claims registry (claims.yml) keeps documentation and code claims verifiable with file / grep / token / gh-api / files-identical checks.
• Branch-protection as code (branch-protection.json) is diffed against the live GitHub ruleset.
• Repo-settings as code (governance.config.yml) keeps merge options and other settings honest.
• Doc gates keep references live (no dead links, paths, or commands) and the docs corpus accounted-for (no orphans, no stubs).
• A dependency-health gate (OWASP A06) keeps your lockfile present and your dependencies free of known-critical vulnerabilities.

The file, grep, and token checks are sub-second and need no network; only the GitHub checks call the API.

3. LLM review (Greptile rubrics)

A repo-versioned .greptile/ rubric library of custom review rules handles what a deterministic gate can't — judgment calls about code and prose. The rubric suite covers silent failures, planning evidence, PII in logs, type design, test quality, comment accuracy, documentation completeness and accuracy, change narrative, README completeness, release notes, accessibility, and the OWASP top 10. Each rule reviews every pull request as the backstop behind the deterministic gates.

4. The whole-repo audit

A composable, per-concern audit-skill system applies the entire rubric suite to an existing codebase and produces a graded, verifiable Codebase Audit Report. It's backed by a baseline engine (grandfather existing debt, block only on new) and a calibration-eval regression gate, so adopting Valinor on a legacy repo doesn't drown you in day-one findings. Audit skills run on a cadence — the over-time axis, complementing the per-change gates and reviews.

5. Score and gate health over time

Privacy-safe, grade-only records make the quality score and gate health visible over time in git. The score trend (audit-trend) and gate-health trend (gate-health-trend) print deterministic Markdown tables showing how the repo's quality is moving — the meta layer that turns one-off audits into a measurable trajectory.

The enforcement triad

A governance concern in Valinor isn't considered done until it has all three legs of the enforcement triad:

• a rubric (an LLM review rule, with a dossier describing it),
• a deterministic gate (where the concern can be checked mechanically), and
• an audit skill (the standing, over-time sweep of the whole concern).

Crucially, what Valinor enforces on itself, it enforces on every consumer repo. The full triad propagates — a deterministic gate verifies that no governance surface Valinor runs on itself silently fails to reach the repos it governs.

Deterministic gates over LLM gates

Valinor's design principle for per-change enforcement is deterministic gates first, LLM review as the backstop. A deterministic check is fast, reproducible, and free of false positives, so it's always preferred when a concern can be checked mechanically. The Greptile rubric layer covers what genuinely needs judgment. The audit skills are a separate, over-time axis — the standing-repo sweep — not a per-change gate.

Standards Valinor enforces

The rubric dossiers, gate scripts, and audit skills together cover concerns including:

• Documentation — completeness, accuracy, freshness, coverage, README completeness, and curated release notes.
• Code quality — silent-failure detection, type design, comment accuracy, and the smallest-solution (YAGNI) discipline.
• Testing — test quality and end-to-end coverage per Valinor's layered testing doctrine.
• Security — the OWASP top 10, PII in logs, and dependency health.
• Process — research-before-planning, plan hygiene, change narrative, and the PR-only / strict-merge flow.
• Accessibility — WCAG 2.1 AA on user-facing surfaces.

For the full rationale and the per-rule dossiers, contributors can read the rubric library in the Valinor repository's docs/rubrics/ directory.