Infrastructure First Principles - Livepeer Docs

Purpose

This is the canonical architecture contract for repository infrastructure. It defines what each layer owns, what each layer must never do, and where enforcement belongs.

Design Tenets

Single responsibility per layer. Each gate owns one class of risk.
Fast local feedback. Pre-commit is local, offline, and bounded.
Governance at branch and CI boundaries. Contract, issue-readiness, and policy checks run at pre-push/CI.
One canonical policy source. Operational docs link here instead of copying rule text.
Measurable SLOs. Runtime budgets are enforced, not aspirational.

Severity Model

P0: merge/deploy safety failure (broken routes, broken rendering, blocked docs delivery)
P1: correctness/governance failure (scope violations, invalid contract/issue readiness)
P2: quality drift (style, docs hygiene, generated index drift)
P3: advisory debt (non-blocking cleanup, optimization backlog)

Stack Architecture (End-to-End)

Layer	First Principle	Primary Risks	Enforcement Point	Max Severity Owned
Repository topology	Folder boundaries are explicit and immutable.	Root sprawl, misplaced files, v1 mutation	`.githooks/pre-commit`, CI structure checks	`P1`
Content contract	Docs pages, navigation, and imports must stay structurally valid.	Broken docs routes/imports/frontmatter	`tests/run-all.js`, `tests/run-pr-checks.js`	`P1`
Generated artifacts	Generated files are rebuilt from source scripts, never hand-maintained.	index drift, stale docs-index, script catalog drift	pre-commit staged generators + CI checks	`P2`
Local commit gate	Pre-commit runs only fast staged local checks.	slow commits, dependency coupling, local flakiness	`.githooks/pre-commit`	`P2`
Branch governance	Codex branch contract and issue readiness are validated before push.	out-of-scope changes, missing readiness, unsafe force-push	`.githooks/pre-push`	`P1`
PR changed-scope CI	CI blocks regressions in changed scope only.	silent regressions entering `docs-v2`	`.github/workflows/test-suite.yml` + `tests/run-pr-checks.js`	`P0`
Full sweep CI	Browser/link/page sweeps catch system-level regressions.	route-level runtime failures, broad link failures	`test-v2-pages.yml`, browser and audit workflows	`P0`
Scheduled ingestion	External data syncs are isolated and idempotent.	stale snippets data, secret drift, workflow collisions	dedicated update workflows + fetch scripts	`P2`
Policy system	Rules are authored once, referenced everywhere else.	contradictory docs, operator confusion, policy drift	this file + `source-of-truth-policy.mdx`	`P1`

Runtime and Scope Budgets

pre-commit: must complete in <= 60s by default. No browser sweep, no WCAG crawl, no external link/network dependency.
pre-push (codex/*): owns contract, lock, stash, issue-readiness, and push safety checks.
CI changed-scope: owns blocking quality checks for changed files in PR context.
CI heavy sweeps: owns browser/page/link/domain/WCAG full or broad scans.

Ownership Contracts

Pre-commit must not implement codex governance policy.
Pre-push must not duplicate style/authoring checks already in pre-commit and PR CI.
CI must be source of truth for heavyweight, potentially flaky, or network-dependent checks.
Any new rule must declare its primary gate layer before implementation.
Any duplicated policy text outside this file is documentation debt and should be replaced by a link.

Migration Rules for New Changes

Define risk class (P0..P3) before adding a new check.
Place the check in exactly one primary layer.
Add runtime budget impact if the check runs locally.
Add CI mirror only when local feedback is insufficient.
Update this document in the same PR when gate boundaries change.

Last modified on May 31, 2026

⌘I