> ## Documentation Index
> Fetch the complete documentation index at: https://na-36-handover-docs-v2-into-docs-v2-dev-20260518.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`