Adaptive Architecture

Self-remediation architecture for ownerless governance, validation, generated artifacts, and repair workflows.

Adaptive Architecture

Adaptive architecture is the repo’s self-remediation model. The repo should detect drift, explain the failing contract, point to the canonical source, provide an exact repair path, and re-check the result. Human maintainers make policy decisions; routine drift should be repairable by contributors or agents.

Control Loop

Stage	Repo implementation	Good output
Detect	validators, audits, hooks, CI workflows	A precise failure with path, rule, and severity.
Explain	policies, frameworks, generated maps, reports	The canonical source and reason for the rule.
Repair	remediators, generators, lpd repair, workflow dispatch	An exact command that changes only the owned surface.
Verify	rerun the validator or staged test suite	A clean check or a smaller next failure.
Record	generated reports, catalogs, decision registry, PR evidence	Reviewable evidence without stale report bloat.

Core Mechanisms

Mechanism	Path	Purpose
Ownerless surface manifest	operations/governance/config/ownerless-governance-surfaces.json	Machine-readable list of governed surfaces, validators, repair commands, gate layer, and rollout state.
Root governance	operations/governance/config/root-governance.json, .allowlist	Prevents root sprawl and records approved root contracts.
Generated artifact governance	operations/governance/config/generated-artifacts.json	Identifies generated files and how they should be regenerated.
Approval policy	operations/governance/config/governance-approval-policy.json	Defines PR evidence labels and approval sections for governance-sensitive changes.
Hooks	.githooks/	Local enforcement for staged safety, root allowlist, v1 frozen content, and generated artifact drift.
Repair entrypoint	lpd repair --surface <id>	Standard command surface for ownerless repairs.

Remediation Script Families

Family	Examples	Drift repaired
Component remediation	operations/scripts/remediators/components/library/*	Component metadata, component styles, AI discoverability.
Content repair	operations/scripts/remediators/content/repair/*	Links, imports, MDX-safe markdown, spelling, docs path sync.
Content style	operations/scripts/remediators/content/style/*	Em dashes, spelling variants, term capitalization, ownerless language.
SEO and metadata	operations/scripts/remediators/content/seo/generate-seo.js	SEO frontmatter drift.
Governance compliance	operations/scripts/remediators/governance/compliance/*	Governance artifacts and workflow headers.
Script governance	operations/scripts/remediators/governance/scripts/repair-script-inventory.js	Script inventory and metadata drift.

Generated Artifact Rule

Generated files are outputs, not authoring surfaces. When a generated artifact is stale:

1. Identify the generator in operations/governance/config/generated-artifacts.json or the relevant catalog.
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.

Current Adaptive Gaps

Gap	Evidence	Required implementation
Governance map drift	generate-repo-governance-status.js --check reports docs-guide/repo-ops/config/repo-governance-map.mdx is stale.	Regenerate governance map and verify the generated artifact contract.
V2 non-publishable lanes are not fully normalized	V2 folder cleanup matrix reports 307 rows: 235 _workspace targets and 72 x-deprecated targets.	Execute approved move waves, update .mintignore and file-selection helpers, then rerun matrix.
Report retention is not enforced strongly enough	Script footprint audit reports 24 findings, mostly large tracked reports.	Apply report retention policy and keep concise summaries instead of full large artifacts.
Some stale docs still describe old paths	Feature docs had TODOs and legacy path references before this update.	Add a docs-guide freshness check for feature pages that reference moved script or workflow names.
Template compliance debt	Script footprint audit cites 218 script template non-compliance findings from the baseline.	Backfill script headers and enforce compliance in a staged rollout.

Acceptance Criteria For New Adaptive Features

• The feature has a machine-readable source or manifest.
• The feature has an exact validator command.
• The feature has an exact repair command or a documented reason repair is manual.
• The feature declares one primary gate layer.
• Reports are bounded by retention policy.
• Generated outputs carry banners or are otherwise listed in generated artifact governance.
• The final check can be run by a contributor with only repo-local instructions.

Related

• docs-guide/policies/ownerless-governance.mdx
• docs-guide/policies/infrastructure-principles.mdx
• docs-guide/policies/generated-artifact-and-hook-governance.mdx
• operations/governance/config/ownerless-governance-surfaces.json
• tools/lpd