skills/architecture-compass/references/internal/internal-adr-index.md

# Architecture Compass Internal ADR Index

> Maintainer-only routing index for implementation mechanics shipped with the Architecture Compass skill. These records are not exposed Architecture Compass ADRs, are not adoptable target-repository decisions, and are intentionally excluded from the exposed/public `../adr-catalog.md`, provider-adoption inventory, and target-governance copies. They remain part of the installed public skill payload so Architecture Compass can load the mechanics when needed.

## Authority boundary

The accepted public Architecture Compass Long decisions remain the only portable architecture authority. Internal records may explain how the skill detects capabilities, resolves adapters, or performs bounded implementation work, but they must not add a user-visible workflow, change an artifact contract, broaden write permission, or override public policy. If an internal rule conflicts with an accepted public Long decision, follow the public decision, stop the affected route when necessary, and create a public successor or repository decision before changing behavior.

Internal records are loaded only when implementation work needs the corresponding mechanic. They are not copied into target repositories, added to the public `adr-catalog.md`, or represented as provider-to-local adoptable decisions. A change that becomes generalized, reusable, and user-visible must be promoted through a reviewed public ADR triplet and the normal catalog/lineage process rather than silently reclassifying an internal file.

## Records

| ID              | Topic                                      | Load when                                                                                                                | Public authority                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Variants                                                                                                                                                                                                                                    |
| --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AC-INTERNAL-001 | Resolve persistence surfaces before writes | A spec, ADR, index, receipt, instruction binding, or other durable artifact may be written across host surfaces.         | **Current:** [AC-ADR-051](../ac-adr-051-route-architecture-compass-through-public-and-internal-decision-namespaces.long.md), [AC-ADR-004](../ac-adr-004-report-staged-evidence-and-protect-public-outputs.long.md), [AC-ADR-036](../ac-adr-036-keep-architecture-compass-portable-through-host-adapters.long.md), [AC-ADR-038](../ac-adr-038-gate-optional-capabilities-and-tool-side-effects.long.md), [AC-ADR-064](../ac-adr-064-preserve-approved-scope-through-capability-aware-planning.long.md), [AC-ADR-052](../ac-adr-052-persist-agent-governance-through-host-neutral-repository-surfaces.long.md); **historical context only:** [AC-ADR-001](../ac-adr-001-route-architecture-compass-through-canonical-adr-triplets.long.md) (superseded by AC-ADR-051) | [Short](internal-adr-001-resolve-persistence-surfaces-before-writes.short.md) · [Long](internal-adr-001-resolve-persistence-surfaces-before-writes.long.md) · [Guide](internal-adr-001-resolve-persistence-surfaces-before-writes.guide.md) |
| AC-INTERNAL-002 | Select capability-aware receipt renderers  | A final concise receipt or progress presentation must adapt to terminal, chat, CI, redirect, or unknown-host capability. | [AC-ADR-004](../ac-adr-004-report-staged-evidence-and-protect-public-outputs.long.md), [AC-ADR-033](../ac-adr-033-choose-portable-dependency-light-skill-helpers.long.md), [AC-ADR-036](../ac-adr-036-keep-architecture-compass-portable-through-host-adapters.long.md), [AC-ADR-038](../ac-adr-038-gate-optional-capabilities-and-tool-side-effects.long.md), [AC-ADR-053](../ac-adr-053-use-capability-aware-presentation-profiles-for-portable-agent-receipts.long.md)                                                                                                                                                                                                                                                                                           | [Short](internal-adr-002-select-capability-aware-receipt-renderers.short.md) · [Long](internal-adr-002-select-capability-aware-receipt-renderers.long.md) · [Guide](internal-adr-002-select-capability-aware-receipt-renderers.guide.md)    |

## Routing rules

1. Start with the Short record to determine whether the mechanic applies.
2. Read the Long record before making a material implementation choice or resolving a failure state.
3. Use the Guide for examples, capability matrices, and focused validation; it is non-normative.
4. Keep internal profile names and surface classifications out of user-facing workflow menus unless a public decision explicitly makes them user choices.
5. Report the selected internal route and its evidence when it affects a receipt or persistence boundary, while keeping the final output compact.

## Promotion gate

Propose a public Architecture Compass or repository ADR when an internal mechanic changes any of the following:

- user-visible outcome, status, evidence stage, or final receipt contract;
- durable artifact identity, repository path, or write authority;
- mandatory dependency, machine-readable output, or host compatibility contract; or
- a target repository's adoptable architecture guardrail.

Until that decision is accepted, keep the behavior internal, preserve the plain/fallback path, and do not add the record to the public catalog.