Documentation Index
Fetch the complete documentation index at: https://na-36-merge-docs-v2-dev-draft-into-docs-v2-clean-20260525.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Adaptive Architecture
The repo’s self-remediation model. Every governed surface declares a four-part contract – canonical source · deterministic validator · exact repair command · single gate layer. When any of those four is missing, the surface stays in advisory state until the contract is complete. Once complete, an OSS contributor (or an AI agent acting on their behalf) can correct routine drift without privileged context or staff approval.
The novelty is not validators or hooks individually – most large repos have those. The novelty is the manifest-driven five-stage control loop and the explicit retirement of “human-only context” as a dependency. Post-D-ACT-10: 4 of 5 unified surfaces are formally ownerless-ready in the canonical repo-governance-surfaces.json (bridge_mode "retired"); 1 advisory (github-workspace-governance). Legacy 8-entry ownerless-governance-surfaces.json superseded but kept on disk for reference.
Honest framing: the model is “ownerless for routine drift” – not “ownerless for policy authorship or destructive operations.” Policy decisions stay human. Routine drift becomes contract.
The four-part contract
Every governed surface must declare:
| Part | What it is | Where it lives |
|---|
| Canonical source | The single file or files the repo treats as authoritative for this surface | surface_globs + canonical_sources fields in ownerless-governance-surfaces.json |
| Deterministic validator | A script that exits non-zero on drift, with path + rule + severity in the failure output | validators field; usually a script under operations/scripts/validators/ |
| Exact repair command | A single command that fixes the deterministic part of the drift, touching only the owned surface | repair_commands field; usually lpd repair --surface <id> |
| Single gate layer | One of pre-commit, pr-changed, scheduled, manual – never multiple | gate_layer field |
rollout_state: advisory (reports but does not block). After all four are declared and exercised:
autofix – the remediator runs deterministically and writesmigrating – transitional state during rolloutblocking – full enforcement; PR cannot merge on failure
The five-stage control loop
| Stage | Repo implementation | Good output |
|---|
| Detect | Validators, audits, hooks, CI workflows | Precise failure with path, rule, severity, and re-check command |
| Explain | Policies, frameworks, generated maps, reports, printed remediation messages | Canonical source named + reason for the rule + link to the framework |
| Repair | Remediators, generators, lpd repair, workflow dispatch | Exact command that touches only the owned surface |
| Verify | Rerun the validator (--verify mode) or staged test suite | Clean check OR a smaller next failure |
| Record | Generated reports, catalogs, decision registry, PR evidence labels | Reviewable evidence without stale report bloat |
The loop in practice – concrete walkthrough
A contributor edits snippets/components/elements/Badge/Badge.jsx and forgets to update the @usedIn JSDoc tag.
- Detect. Pre-commit runs the component metadata validator (
operations/scripts/validators/components/library/...). It reports: file path; missing tag; severity P2; exact validator command.
- Explain. The hook prints a link to
docs-guide/frameworks/component-framework-canonical.mdx (canonical source for the 7-tag JSDoc contract) + notes the surface is declared in ownerless-governance-surfaces.json under id component-governance, gate layer pr-changed, rollout state autofix.
- Repair. The hook prints:
lpd repair --surface component-governance --write --staged. That command runs operations/scripts/remediators/components/library/repair-component-metadata.js against only the staged file set. The remediator derives the missing @usedIn field from tools/lib/governance/component-governance-utils.js::buildComponentUsageSummary() – a live scan of MDX imports.
- Verify. The remediator’s
--verify mode re-runs the validator after writing. If the validator still fails, the loop hands back control instead of escalating.
- Record. The repaired file is staged for commit alongside the source change. The catalog at
docs-guide/catalog/components-catalog.mdx is regenerated because generated-artifacts.json lists it as a committed_derived_scoped artefact whose source set includes snippets/components/**. The PR body picks up the change set. The governance approval policy decides whether the approval:governance-schema label is required based on the surface touched.
A live example of the loop self-detecting
Running node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --check on 2026-05-23 prints:
docs-guide/repo-ops/config/repo-governance-map.mdx is stale.
Surface inventory (live, 2026-05-25)
| Manifest | Path | Entries | Purpose |
|---|
| Repo governance surfaces (canonical post-D-ACT-10) | operations/governance/config/repo-governance-surfaces.json | 5 unified surfaces (4 ownerless-ready + 1 advisory: github-workspace-governance) | Single canonical registry; bridge_mode: "retired", legacy_bridge_inventory empty (migration complete) |
| Ownerless surfaces (legacy / superseded) | operations/governance/config/ownerless-governance-surfaces.json | 8 | Pre-D-ACT-10 inventory; kept on disk for reference. Authoritative reads should use repo-governance-surfaces.json |
| Generated artefacts | operations/governance/config/generated-artifacts.json | 29 | Every committed-derived file with class + commit-policy + hook-policy + ci-policy + delta-strategy |
| Root governance | operations/governance/config/root-governance.json | 35 root entries | Prevents root sprawl; generates .allowlist |
| Approval policy | operations/governance/config/governance-approval-policy.json | per-surface label rules | Defines PR evidence labels + approval sections for governance-sensitive changes |
| Agent-write governance | operations/governance/config/agent-write-governance.json | per-path rules | What agents may write where; currently bridge_mode: "staged" (transition incomplete – see Known gaps) |
Core mechanisms
| Mechanism | Path | Purpose |
|---|
| Unified governance registry (canonical post-D-ACT-10) | operations/governance/config/repo-governance-surfaces.json | Machine-readable contract per surface: validators, repair commands, gate layer, rollout state. Legacy ownerless-governance-surfaces.json superseded |
| Root governance | operations/governance/config/root-governance.json + .allowlist (generated) | Prevents root sprawl; pre-commit reads .allowlist to refuse new root entries |
| Generated artefact governance | operations/governance/config/generated-artifacts.json | Three classes (committed_authoritative, committed_derived_scoped, ephemeral_local), three commit policies, three hook policies, three CI policies, four delta strategies |
| Approval policy | operations/governance/config/governance-approval-policy.json | PR evidence labels (approval:governance-schema, approval:cleanup, etc.) |
| Hooks | .githooks/ | Local enforcement: pre-commit (staged safety, MDX syntax, docs.json integrity, root allowlist, v1 frozen, no-deletion, Codex branch isolation); pre-push (Codex task contract, lock overlap, stash policy) |
| Repair entrypoint | lpd repair --surface <id> | Standard command surface for ownerless repairs |
| Pipeline tests | operations/tests/integration/pipeline-smoke-test.js + pipeline-functional-tests.js | 66/66 dispatcher smoke test + synthetic violation cycles per D-GOV-03 |
Script corpus (live counts, 2026-05-23)
The remediation backbone. All 321 active scripts follow the 11-tag JSDoc contract per docs-guide/frameworks/script-framework.mdx.
| Type | Count | Where | What each does |
|---|
| Validators | 55 | operations/scripts/validators/ | Detect drift; exit-code 0/1/2 with precise failure output |
| Remediators | 37 | operations/scripts/remediators/ | Repair detected drift; support --write / --verify / --staged / --files modes |
| Generators | 31 | operations/scripts/generators/ | Rebuild derived artefacts from canonical sources; every output declared in generated-artifacts.json |
| Audits | 25 | operations/scripts/audits/ | Read-only scans; emit JSON + MD reports under workspace/reports/repo-ops/ |
| Dispatchers | 102 | operations/scripts/dispatch/ | Per-concern meta-dispatchers (-check, -update, -scan, -generate, -repair, -sync) called by the 6 dispatch-{concern}.yml workflows |
| Integrators | 58 | operations/scripts/integrators/ | Pull/transform external + internal data into repo |
| Interfaces | 8 | operations/scripts/interfaces/ | Issue/PR/Discord event handlers |
| Family | Path | Drift repaired |
|---|
| Component remediation | operations/scripts/remediators/components/library/* | Component metadata, styles, AI discoverability, registry parity |
| Content repair | operations/scripts/remediators/content/repair/* | Links, imports, MDX-safe markdown, docs-path sync |
| Content style | operations/scripts/remediators/content/style/* | Em-dashes (zone-aware frontmatter handling), US→UK spelling, term capitalisation, ownerless language |
| Content classification | operations/scripts/remediators/content/classification/* | Page taxonomy + frontmatter classification |
| Content copy | operations/scripts/remediators/content/copy/* | Banned-word + banned-phrase replacement |
| SEO + metadata | operations/scripts/remediators/content/seo/generate-seo.js | SEO frontmatter drift |
| Governance compliance | operations/scripts/remediators/governance/compliance/* | Governance artefacts, workflow headers, JSDoc compliance |
| Script governance | operations/scripts/remediators/governance/scripts/repair-script-inventory.js | Script inventory + metadata drift |
| Governance scaffold | operations/scripts/remediators/governance/scaffold/* | New-surface scaffolding |
--dry-run / --write / --verify / --staged / --files. The --verify mode is partially adopted – some remediators only repair without re-running the validator after writing. The contract says repair-then-recheck.
Generated artefact governance
Generated files are outputs, not authoring surfaces. When a generated artefact is stale:
- Identify the generator in
operations/governance/config/generated-artifacts.json (each entry names path + generator + sources + class).
- Run the generator in
--check mode if available.
- Run the generator in
--write mode.
- Re-run the check.
- Include both source and output changes in the same review unit.
The 3 artefact classes
| Class | What it is | Example |
|---|
committed_authoritative | Hand-authored canonical files | docs-guide/policies/ownerless-governance.mdx |
committed_derived_scoped | Generated from canonical sources; committed because consumers depend on them | docs-guide/catalog/components-catalog.mdx, snippets/data/contract-addresses/contractAddressesData.jsx, docs-index.json |
ephemeral_local | Generated for local use only; gitignored or never committed | workspace/reports/_local/**, test fixtures |
generated-artifact-and-hook-governance.mdx.
Locked decisions
Three registries cover this surface:
docs-guide/decisions/registry.md – unified cross-reference index.github/workspace/decisions-log.mdx – 18 locked decisions (D-ACT-01..10 + D-GOV-01..08) covering workflow architecture, taxonomy, pipeline tags, dispatcher modeldocs-guide/decisions/docs-guide-structure.md – D-DG-01..13 covering docs-guide IA migration
The 18 D-ACT + D-GOV decisions establish the 4-tier composable architecture (workflow YAML = dispatcher only; typed work in scripts; D-GOV-08), the 7-prefix workflow naming convention (D-ACT-04), the 7-type × 7-concern taxonomy (D-ACT-05), the 8-tag pipeline taxonomy (D-ACT-02), the issue/PR interface as a 7th type (D-ACT-01).
Pre-commit hooks (the local enforcement layer)
5 hard gates run on every commit, scoped to 60-second runtime budget:
| Gate | What it enforces |
|---|
| MDX syntax | Pages parse cleanly; frontmatter valid |
docs.json integrity | Redirect block valid; no broken nav routes |
| No-deletion | Tracked file deletion requires allow-deletions=true trailer |
.allowlist + v1/ protection | Root sprawl blocked; v1 frozen content unchanged |
| Codex branch isolation | codex/* branches comply with task contract |
.githooks/BYPASS.md. Pre-commit has an undocumented carve-out allowing deletion without the trailer if the blob hash matches a v2/x-archived/ follow-up.
Acceptance criteria for new adaptive features
A new surface graduates from advisory to autofix (or blocking) when:
- The surface has a machine-readable manifest entry in
ownerless-governance-surfaces.json or repo-governance-surfaces.json
- The surface has an exact validator command (exits non-zero on drift)
- The surface has an exact repair command (or a documented reason repair is manual)
- The surface declares one primary gate layer (not multiple)
- Reports are bounded by retention policy
- Generated outputs carry banners or are listed in
generated-artifacts.json
- The final check can be run by a contributor with only repo-local instructions
- The remediator supports
--verify mode (re-runs the validator after writing)
- The validator failure output prints the
lpd repair command (the Error Reporting and Issue-Creation Hooks contract below)
Error reporting and issue-creation hooks
The standardised failure-output contract: every blocking failure prints (a) why it failed, (b) the re-check command, (c) the repair command. Repair commands are repo-backed commands an OSS contributor or AI agent can run directly.
Adoption is uneven. Most newer scripts comply. Older validators (especially under governance/pr/) sometimes print failure reasons without the explicit lpd repair command. Cleanup queue.
Known gaps
”Ownerless” is currently 4 of 5 unified surfaces (P1, honest framing)
The four-part contract is real and enforced for the 8 surfaces in ownerless-governance-surfaces.json. The wider repo-governance-surfaces.json lists 28 surfaces, of which 20 are still advisory. Manifests still use owner: docs everywhere in root-governance.json. The agent-governance taxonomy references @livepeer/docs-team. Several policies say “human review” or “review owner”. The model is “ownerless for routine drift” – not “ownerless for policy authorship or destructive operations.” This is consistent with the design intent but should be surfaced in product narrative (and on docs-guide/index.mdx).
The stale governance map is self-detected but not auto-repaired (P1)
generate-repo-governance-status.js --check on 2026-05-23 prints docs-guide/repo-ops/config/repo-governance-map.mdx is stale. The map last regenerated 2026-04-07T13:18:37.118Z – about 6 weeks behind. The system flags itself; nothing auto-runs the repair. The check runs at the right cadence; the publish gate doesn’t. Same root cause as the contracts pipeline 19-day staleness – the cron-is-dry-run bug (fix shipped 2026-05-25 in commit e42946cdf on docs-v2-dev-draft; pending merge to docs-v2 after which the next scheduled run should regenerate the map).
307-row v2 cleanup matrix is recommendation-only (P1)
The v2 folder governance audit reports 307 rows (235 _workspace candidates + 72 x-deprecated candidates). 41 internal-scope rows. Largest section (gateways) carries 199 of the 307 rows alone.
The pipeline is mature (policy, lane definitions, matrix generator). Execution is the gap. No automated move-waves have run. Humans approve each batch. Per Workspace Lifecycle Policy, 30/90-day TTL is documented; tasks-retention.yml is a stub (not implemented).
Script JSDoc compliance is much better than the documented gap (live data, 2026-05-23)
Documented in docs-guide/features/gap-analysis.mdx (last verified 2026-05-14): “218 scripts marked template non-compliant.”
Live data 2026-05-23:
- 327 of 321 active scripts have canonical
@purpose (essentially 100%)
- 81% have
@type (sampled 100)
- 81% have
@concern (sampled)
- Only 45 scripts repo-wide use retired
@category
- Only 4 use retired
@domain
The “218 non-compliant” figure is 9 days stale. Actual compliance gap is ~45-50 scripts max – a 4× improvement.
Backfill these 45–50 scripts with repair-script-inventory.js to close the gap entirely.
--verify mode adoption is partial
Not every remediator implements --verify (the re-check after write). The contract says repair-then-recheck. Audit the corpus, add --verify to the ones missing it.
Hook scripts violate their own JSDoc spec (P2)
Per SLICE-03: .githooks/pre-commit and pre-push use retired JSDoc tags (@category, @domain, @needs, @purpose-statement) that docs-guide/policies/script-governance.mdx lines 195-205 explicitly bans. The hooks that enforce JSDoc compliance violate the JSDoc spec.
.githooks/verify.sh is dead enforcement (P2)
Per SLICE-03: verify.sh defines 7 internal checks (MDX, JSON, JS, shell, mintlify, snippets-import, browser) but is not invoked by the active pre-commit hook. Dead enforcement code. Either wire it back in OR retire.
.githooks/pre-commit-no-deletions is unwired (P2)
Per SLICE-03: declares @pipeline manual – not yet in pipeline in its own header. Not referenced by install.sh, not invoked by pre-commit, no test. Pure safety-net cruft.
.githooks/script-index.md only catalogues 3 of 7 hook scripts
Generator filter is broken – only catches pre-commit* and pre-push. Misses install.sh, verify.sh, verify-browser.js, server-manager.js.
agent-write-governance.json bridge_mode: "staged" migration incomplete
Per SLICE-03: repo-governance-surfaces.json already flipped to "retired" for the corresponding surface but agent-write-governance.json is still in transitional staged mode. Complete the migration.
No automated decision-registry enforcement
docs-guide/decisions/registry.md says “decisions made in chat that aren’t written here don’t exist” – enforced by convention only. No script checks PRs for chat-decisions that should be in the registry but aren’t. Three separate registries (D-NAV, D-ACT+D-GOV, D-DG) + per-plan registries with no automated cross-index check.
Audit→issue automation is partial (Pattern D “Act” stage)
The Pattern D framework doctrine says “every finding gets a response – no headless scans.” Health-scheduled-scan and brand-scheduled-scan open PRs on manual repair. But the daily scheduled runs write findings nowhere except workflow step-summary output (the cron-is-dry-run bug). The “Act” stage of the scan-report-act pattern is mostly missing for cron-driven scans.
Surfaces without canonical claim yet (gaps from the gap analysis)
Surfaces that exist in the repo but have not been promoted into the ownerless model:
- ~50 scripts with retired JSDoc tags (above)
- 24 archived JSX components with no removal schedule
- Duplicate developer trees (
v2/developers/, v2/developers1/, v2/developers2/)
- Large historical reports under
workspace/reports/**/files/
.vscode/livepeer-legacy.code-snippets.bak (35 KB tracked backup)
Inventoried in docs-guide/features/gap-analysis.mdx but not yet under contract.
