Automations

Map of GitHub Actions, CI gates, scheduled jobs, dispatchers, remediators, and automation governance in the Livepeer Docs repo.

Automations

The automation layer is the repo’s operating system. The repo is ownerless and self-governed – there is no single human responsible for keeping content fresh, links unbroken, navigation in sync, or generated artefacts aligned with their sources. The automation layer fills that role. It validates new contributions before they land, regenerates derived artefacts the moment a source changes, ingests live data from external services, repairs deterministic drift, and surfaces what it cannot fix as backlog.

This page documents what’s live as of 2026-05-23. The canonical published framework is at docs-guide/frameworks/github-actions.mdx (with the internal working spec at .github/workspace/framework-canonical.md).

The 4-tier composable architecture (D-GOV-08, 2026-05-22)

A major refactor on 2026-05-22 consolidated 53 standalone workflows → 11 active workflows under a 4-tier composable model. Workflow YAML files are dispatchers only; the typed work lives in scripts. The type classification comes from what the script does, not the workflow filename. Smoke test passing 66/66 dispatchers per framework-canonical.md Status line.

Tier	Layer	What lives here	Count (2026-05-23)
1	.github/workflows/*.yml	Pure dispatchers (trigger + permissions + orchestration only)	11 active (6 dispatch-{concern} + 5 interface-governance-*)
2	operations/scripts/dispatch/{concern}/	Meta-dispatchers (per-mode entry: check / generate / scan / update / repair / sync)	102 dispatcher scripts
3	operations/scripts/{type}/{concern}/{niche}/	Atomic scripts (validator / generator / integrator / remediator / audit / interface)	219 atomic scripts
4	tools/lib/	Shared libraries imported by atomics (governance, copy-governance, docs, docs-usefulness, ai, bootstrap)	6 lib subtrees

The refactor locked 18 decisions (D-ACT-01..10 + D-GOV-01..08) in .github/workspace/decisions-log.mdx.

The 11 active workflows

6 concern dispatchers (dispatch-{concern}.yml)

Each follows an identical 4-mode shape per D-ACT-08 + D-GOV-08:

1. PR check (pull_request) – dispatch-{concern}-check.js --staged
2. Post-merge (push to docs-v2) – dispatch-{concern}-generate.js --write (or -sync.js)
3. Scheduled (cron) – dispatch-{concern}-update.js or -scan.js with FLAGS pattern (⚠️ see §The cron-is-dry-run bug)
4. Manual repair (workflow_dispatch with mode=manual) – dispatch-{concern}-repair.js with FLAGS pattern

File	Concern	Cron	Path filters (PR/push)
dispatch-brand.yml	brand	Mon 06:30 UTC	v2/**/*.mdx, snippets/**/*.mdx, snippets/components/**
dispatch-copy.yml	copy	daily 03:00 UTC	v2/**/*.mdx, snippets/data/**
dispatch-discoverability.yml	discoverability	daily 04:00 UTC	v2/**, snippets/**, docs.json
dispatch-governance.yml	governance	daily 07:00 UTC	.github/**, operations/scripts/**, docs-guide/**, tools/config/**, snippets/**
dispatch-health.yml	health	daily 06:00 UTC	v2/**, snippets/**, content/scripts paths
dispatch-maintenance.yml	maintenance	daily 05:00 UTC	snippets/components/**, snippets/data/**, docs.json

dispatch-governance.yml has an additional fifth job: pipeline-tests runs operations/tests/integration/pipeline-smoke-test.js (66/66 dispatcher smoke test) + pipeline-functional-tests.js (synthetic violation cycles per D-GOV-03). dispatch-health.yml and dispatch-brand.yml open a PR on manual repair via peter-evans/create-pull-request@v7.

5 governance interfaces (interface-governance-*.yml)

File	Trigger	What it does
assign-reviewers.yml	pull_request (opened/reopened/ready/edited/labeled)	Codex PR eligibility gate; request Copilot reviewer; fallback assign via gh CLI
close-linked-issues.yml	push to docs-v2	Close issues linked to merged PRs
index-issues.yml	issues events + cron every 6h	Rolling docs-v2 issue index (marker-based discovery, single canonical index issue)
intake-discord-issues.yml	repository_dispatch (type: discord-issue-intake)	Discord webhook → GitHub issue conversion
label-issues.yml	issues events	Auto-label new issues by parsed body headings (area:* + priority:*)

All 5 interfaces are tagged # pipeline: P7 in their header comment – distinct from the P2-P6 dispatcher taxonomy.

Pipeline patterns (A–G)

Every pipeline follows one of these shapes. Source: .github/workspace/framework-canonical.md.

Pattern	Trigger	Flow	Example
A – Integrate	cron / dispatch / manual	Fetch external API → transform → diff → commit + push → on failure create issue	contracts addresses; exchanges data; social feeds
B – Generate	push to deploy branch / manual	Read repo data → generate output → diff → commit + push	catalogs; component registry; docs-index; llms files; AI sitemap
C – Check	pull_request / push	Run validator(s) → report pass/fail → P2 block or P3 advise	docs-quality; OpenAPI reference audit; link health
D – Scan, Report, Act	cron / manual	Scan → report → route findings (auto-remediate / create issue / re-dispatch). “No headless scans – every finding gets a response.”	content-quality scheduled scan + manual repair pair
E – Repair	cron / manual	Scan for drift → fix → commit or PR	brand sweep; styles sweep
F, G	–	reserved; see framework canonical for full spec	–

The gold standard implementation is the contracts pipeline (Pattern A with shadow verification) – daily cron + verification-only shadow + bytecode auth against Arbitrum + Ethereum + health-check artefacts + incident issue creation + publish gate requiring --check rerun.

Operations scripts taxonomy

321 active scripts under operations/scripts/, 38 in archive. Every script declares @type / @concern / @niche via an 11-tag JSDoc header.

Type	Live count	Purpose
dispatch	102	Meta-dispatchers + per-concern entries (-check, -update, -scan, -generate, -repair, -sync) per D-ACT-08
integrators	58	Pull/transform external + internal data into repo
validators	55	Exit-code checks for hooks, CI, manual validation
remediators	37	Deterministic repairs to existing files
generators	31	Produce derived files from canonical sources
audits	25	Read-only scans and reports
interfaces	8	Issue/PR/Discord event handlers
archive + x-archive	38	Deprecated or legacy scripts retained for review/compatibility

JSDoc compliance (sampled 2026-05-23):

• 327 of 321 active scripts have @purpose (canonical) – basically 100%
• 81% have @type, 81% have @concern (sampled 100)
• 45 scripts repo-wide still use retired @category
• 4 scripts use retired @domain
• The retired tags (@category, @domain, @needs, @purpose-statement, @owner) are explicitly banned per docs-guide/policies/script-governance.mdx lines 195-205

The previously documented “218 non-compliant scripts” figure (from gap-analysis.mdx as of 2026-05-14) is stale. Actual non-compliance as of 2026-05-23 is ~45-50 scripts with retired tags – a 4× improvement from the documented baseline.

Hook pipeline (.githooks/)

5 active hooks + 4 docs + 4 utility files in .githooks/. Hard gates run on every commit, scoped to a 60-second runtime budget.

Hook	What it enforces
pre-commit	MDX syntax; docs.json redirect integrity; no-deletion guard; .allowlist + v1/ protection; Codex branch isolation. 22.8 KB; the entry-point.
pre-push	Codex codex/* branch contract; lock overlap; AI-stash policy; non-fast-forward push guard
pre-commit-no-deletions	Deletion guard (alternative variant – wiring status unclear; flagged in SLICE-03 as dead code)
install.sh	Wires .git/hooks/pre-commit → .githooks/pre-commit
verify.sh	One-shot verification runner (7 internal checks: MDX, JSON, JS, shell, mintlify, snippets-import, browser); orphan in pre-commit per SLICE-03 – defined but not invoked

Bypass policy in .githooks/BYPASS.md. Pre-commit has an undocumented carve-out: allows deletion without --trailer "allow-deletions=true" if the blob hash matches a v2/x-archived/ follow-up.

Gate layers

Layer	Belongs here	Does not belong here
Pre-commit	Fast staged checks; generated artefact drift checks; root structure guardrails; v1 frozen-file guard	Browser sweeps; network calls; long full-site audits
Pre-push	Codex branch contract; lock checks; issue readiness; branch safety	Style checks already handled by pre-commit or PR CI
PR CI	Changed-file quality; docs-index; OpenAPI references; component + governance checks	Local-only setup checks
Scheduled CI	Broad freshness; links; page integrity; data refresh; advisory scans	Mutating source files without deterministic PR or repair path
Manual dispatch	One-off migrations; approvals; repair waves; large data updates	Routine drift that should be covered by a gate

Ownerless automation contract

Each production automation must declare (per docs-guide/policies/ownerless-governance.mdx):

Requirement	Implementation target
Canonical source	Policy, config, source data, docs tree, or workflow definition that owns truth
Validator	Local or CI command that fails deterministically when drift exists
Repair command	Exact command or workflow that restores derived state
Primary gate	One layer only (pre-commit / PR / scheduled / manual)
Output contract	Where reports, generated files, or PR comments are written
Retention policy	Whether outputs are committed, archived, summarised, or purged

Post-D-ACT-10 (2026-04-05): the canonical registry is operations/governance/config/repo-governance-surfaces.json with 5 unified surfaces, 4 ownerless-ready, 1 advisory (github-workspace-governance). The file’s bridge_mode is "retired" and legacy_bridge_inventory is empty – migration complete. The legacy 8-entry ownerless-governance-surfaces.json remains on disk for reference but is superseded.

Locked decisions (18)

10 D-ACT decisions + 8 D-GOV decisions, split across two logs by date:

• D-ACT-01..10 + D-GOV-07..08 in .github/workspace/decisions-log.mdx (workflow architecture, taxonomy, dispatcher model; locked 2026-03-31 through 2026-05-22)
• D-GOV-01..06 in .github/workspace/design/governance/design-overview.md (governance principles; locked 2026-04-04)

ID	What it locks
D-ACT-01	interface is a 7th type (issue/PR event handlers – not a subtype of automation)
D-ACT-02	P5-auto is a distinct pipeline tag from P5 (scheduled writes vs scheduled read-only)
D-ACT-03	7 social-data workflows consolidate into 1 matrix update-social-feeds.yml
D-ACT-04	Workflow naming type-concern-function-name.yml with closed-enum 11 function verbs
D-ACT-05	Concern taxonomy expanded from 4 to 7 (integrations, copy, maintenance, health, discoverability, governance, brand)
D-ACT-06	Migrate .github/scripts/ into operations/scripts/ governance – .github/scripts/ is intentionally empty as a result
D-ACT-07	Rename automation type to integrator (script + workflow side)
D-ACT-08	Workflows are dispatchers; type reflects the script. No inline logic in YAML
D-ACT-09	Pipeline output locations (per type/concern)
D-ACT-10	Unified governance registry replaces ownerless-governance-surfaces.json (single source of truth)
D-GOV-01	Governance is enforcement infrastructure, not content rules
D-GOV-02	Categories are enforcement layers, not surfaces (pre-commit, PR, post-merge, scheduled, self-heal, hooks, lifecycle)
D-GOV-03	Every detection must self-repair or escalate (auto-fix > PR > issue > block)
D-GOV-04	Tooling makes correct the default (templates, scaffolding, IDE snippets)
D-GOV-05	Advisory before hard gate (P3 first, promote to P2 after baseline clean)
D-GOV-06	Align script framework to actions framework (7 types, 7 concerns)
D-GOV-07	Every workflow dispatcher must have a local CLI equivalent
D-GOV-08	Every folder is governed. No commit of files that do not belong

Pipeline tag taxonomy (8 tags): P2 (PR required), P3 (PR advisory), P4 (post-merge), P5 (scheduled read-only), P5-auto (scheduled writes), P6 (self-heal), manual, event-driven.

Concern taxonomy (7): integrations, copy, maintenance, health, discoverability, governance, brand.

Type taxonomy (7): integrator, generator, validator, audit, remediator, dispatch, interface.

Recently shipped (May 2026)

Veracity dispatcher tranche

Three new dispatchers under operations/scripts/dispatch/content/veracity/ (type dispatch, concern health, niche veracity) close the long-standing “veracity-pass DRAFT blocks Phase 6” gap noted in the Checks Framework:

Script	Pipeline	Purpose
docs-research-packet.js	manual packet generator	Generic engine: derives nav/manifest/path scope, runs the research stack tranche-by-tranche, writes reusable packet reports + master rollup
orchestrator-guides-research-review.js	manual wrapper	Delegates to docs-research-packet.js with live Orchestrators Guides nav scope and legacy output root
docs-page-research-pr-report.js	manual, experimental advisory PR integration, non-blocking	Runs fact-check research runner on changed docs pages; emits PR artefact summarising claim families, contradictions, unresolved factual risk, propagation follow-up

These are manual-pipeline (not yet on cron); inputs/outputs registered under workspace/research/claims/ + workspace/reports/. Unit-tested under operations/tests/unit/.

Local social-feed dispatcher

operations/scripts/dispatch/content/data/run-solutions-social-fetch.js (type dispatch, concern integrations, niche social-feeds) mirrors dispatch-social-feeds.yml for local workstation use: loads .env, supports --mode forum,youtube, --dry-run, --skip discord. Iterates the 7 fetchers under operations/scripts/integrators/copy/social-feeds/. Local-only, not in any GitHub Actions workflow (a deliberate contributor tool, not a duplicate CI surface). Closes the gap where contributors couldn’t fetch live forum/discord/blog/YouTube/GitHub data on their workstation before pushing snippets that depended on freshly-generated outputs.

Known gaps

Cron-is-dry-run-by-default bug – FIXED 2026-05-25

Status: Fixed in commit e42946cdf on docs-v2-dev-draft. Pending merge to docs-v2.

Every dispatch-{concern}.yml scheduled job previously had this pattern:

- name: {concern} scheduled meta
  run: |
    FLAGS=""
    if [[ "${{ inputs.dry_run }}" == "false" ]]; then FLAGS="--write --verify"; fi
    node operations/scripts/dispatch/.../dispatch-{concern}-update.js $FLAGS

The schedule event did not pass inputs.dry_run – it was empty, never the literal string "false". So FLAGS stayed empty and the script ran with no --write --verify. Cron physically could not trigger the write mode. Only workflow_dispatch with explicit dry_run: false actually wrote.

Net effect (pre-fix): the entire daily cron schedule was check-only theatre. Root cause of:

• Contract addresses last written 2026-05-04 (19 days stale on 2026-05-23) despite _health-checks.json confirming the pipeline ran daily
• llms.txt + sitemap-ai.xml 47 days stale (no manual dispatch with dry_run: false)
• generate-og-images.js + generate-seo.js classified “manual-only” in 2026-03-30 P0 flag – they’re CI-wired but cron defaulted to dry-run

Fix shipped: inverted FLAGS default in all 6 dispatch-{concern}.yml (FLAGS="--write --verify"; if ... == "true" then FLAGS=""). Manual-repair jobs deliberately unchanged (safe-by-default for human-triggered repairs). Post-merge jobs unaffected (already hardcode --write).

Archive sprawl

Three archive lanes in .github/:

1. .github/workflows/deprecated/ (1 file: update-blog-data.yml)
2. .github/workflows/x-archive/ (61 files: 56 .archived + 5 non-.archived)
3. .github/x-archive/ (separate at .github root, contents not enumerated)

The script-framework declares one lane (x-archive/). Plus operations/scripts/archive/ and operations/scripts/x-archive/ – two more for scripts.

Path drift from pre-refactor docs

.github/scripts/ is intentionally empty per D-ACT-06 (migration locked 2026-04-04). Stale references in older docs need updating:

• Contracts pipeline doc references .github/scripts/fetch-contract-addresses.js. Current path: operations/scripts/integrators/maintenance/contracts/fetch-contract-addresses.js.
• agent-governance-framework.mdx lines 137 + 228 reference validators/governance/check-agent-docs-freshness.js; actual path is validators/governance/compliance/check-agent-docs-freshness.js (missing /compliance/ subfolder). AGENTS.md line 98 has the right path.

Published framework lags the 2026-05-22 refactor

.github/workspace/framework-canonical.md says: “Canonical published framework: docs-guide/frameworks/github-actions.mdx – read that first.” But the published framework likely predates the 2026-05-22 refactor. Sync state undocumented.

Stale governance map

node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --check reports docs-guide/repo-ops/config/repo-governance-map.mdx is stale. Self-detection works; auto-repair doesn’t run.

.githooks orphan + dead code

• verify.sh is defined with 7 internal checks but not invoked by active pre-commit – dead enforcement (per SLICE-03)
• pre-commit-no-deletions is unwired dead code per its own JSDoc (@pipeline manual – not yet in pipeline)
• .githooks/post-commit.disabled has NO JSDoc header at all
• .githooks/script-index.md only catalogues 3 of 7 hook scripts (generator filter broken)

actions-library/ per-action MDX catalogue not enumerated

.github/workspace/actions-library/{type}/{concern}/{niche}/*.mdx – one MDX file per atomic action. Mostly auto-generated from script JSDoc headers. Full enumeration not done; freshness vs source not verified.

Phase 4 workflow consolidation pending

framework-canonical.md Status line says “Phase 4 consolidation shipped” but Phase 6 (renames, inline-script extraction, consolidation) is explicitly noted as pending per the 2026-04-08 component-governance row in CLAUDE.md.

Related

• GitHub Actions Framework – canonical published framework (v2.2, synced 2026-05-25 with the 2026-05-22 refactor + D-ACT-09/10 + D-GOV-07/08)
• Script Framework – 11-tag JSDoc spec + type/concern/niche taxonomy
• Script Governance Policy – what retired tags look like + repair commands (lines 195-205)
• Ownerless Governance Policy – the 4-part contract every governed surface must declare
• Infrastructure Principles – gate-layer rule ownership
• Generated-Artifact & Hook Governance – 3 classes + commit/hook/CI policies + delta strategies for every generated output
• Quality Gates Policy – full gate-layer map with named tools per tier
• Workflows Catalog – generated catalogue of all workflows (auto-regenerated by dispatch-maintenance)
• Scripts Catalog – generated catalogue of all scripts
• .github/workspace/framework-canonical.md – internal working spec (the 2026-05-22 Status line is the most current document)
• .github/workspace/decisions-log.mdx – 18 locked decisions (D-ACT-01..10 + D-GOV-01..08)