Skip to main content

​
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: Until all four are declared, the surface stays in rollout_state: advisory (reports but does not block). After all four are declared and exercised:
  • autofix – the remediator runs deterministically and writes
  • migrating – transitional state during rollout
  • blocking – full enforcement; PR cannot merge on failure

​
The five-stage control loop

​
The loop in practice – concrete walkthrough

A contributor edits snippets/components/elements/Badge/Badge.jsx and forgets to update the @usedIn JSDoc tag.
  1. Detect. Pre-commit runs the component metadata validator (operations/scripts/validators/components/library/...). It reports: file path; missing tag; severity P2; exact validator command.
  2. 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.
  3. 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.
  4. 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.
  5. 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:
The system reliably flags itself. Nothing yet auto-runs the repair. That gap is named below.

​
Surface inventory (live, 2026-05-25)

​
Core mechanisms

​
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.

​
Remediator families

Mode standardisation: every remediator supports --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:
  1. Identify the generator in operations/governance/config/generated-artifacts.json (each entry names path + generator + sources + class).
  2. Run the generator in --check mode if available.
  3. Run the generator in --write mode.
  4. Re-run the check.
  5. Include both source and output changes in the same review unit.

​
The 3 artefact classes

Hook policies + commit policies + CI policies per class are defined in 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 model
  • docs-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: Bypass policy in .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.
Last modified on June 2, 2026