# Domain 2: Adapter Infrastructure

> Last updated: 2026-04-19

**Pillars served:** governance-axis P3 (primary), P2 (supporting); content-quality-axis CQ9 Enhancability (supporting — adapter extensibility patterns).

**Scope:** All adapter support code — the base contract, canonical reader, customization pipeline, utilities, registry, content system, and archive system / drift detection. Does NOT cover per-adapter implementations (those are Domain 9).
**Sub-agents:** 7

## Sub-Agent Decomposition

| SA | Focus | Key Files |
|----|-------|-----------|
| 2.1 | Base Adapter Contract | `src/adapters/base.ts` |
| 2.2 | Canonical Reader | `src/adapters/canonical.ts` |
| 2.3 | Customization Pipeline | `src/adapters/customization.ts` |
| 2.4 | External Tool Config Utilities | `src/adapters/mcp-utils.ts`, `src/adapters/toml-utils.ts`, `src/pipeline/agentToolAllowlist.ts`, `src/pipeline/adapterToolTranslator.ts` |
| 2.5 | Adapter Index & Registry | `src/adapters/index.ts` |
| 2.6 | Content System | `src/content/index.ts` (686 LOC), `src/content/tags.ts` (91 LOC), `src/content/presets.ts` (48 LOC) |
| 2.7 | Archive System & Drift Detection | `src/archive/index.ts` + drift-detection logic in `src/cli/commands/verify.ts` / `status.ts` |

> Apply the rigor contract per [../templates/rigor-contract.md](../templates/rigor-contract.md) on every finding.

## Audit Checklists

> **Per-finding (Decision 17 / charter directive 18):** every finding declares `impact_horizon: short|medium|long` AND `progress_toward_pillar: <axis>.<pillar_id>+<delta>` (e.g., `governance.P5+0.15` or `content-quality.CQ8+0.20`); orchestrator DROPS at output time if either missing.

### 2.1 Base Adapter Contract
- [ ] Contract completeness — all required abstract methods defined
- [ ] Extensibility patterns — new adapters can be added without modifying base
- [ ] Capability declaration — adapters correctly declare supported features
- [ ] Hook support interface — base contract supports hook transformation
- [ ] Companion content emission — `BaseAdapter.emitCompanionContent` walks support subdirectories (`agents/modes/`, `agents/shared/`, `commands/board/`, `commands/revision/`, `checks/`), applies `substituteCanonicalContent`, and emits each `.md` file as a managed-block output under the per-adapter native path. Verify each adapter wires the helper; verify path references inside companion bodies remain intact for runtime Grep/Glob resolution.

### 2.2 Canonical Reader
- [ ] Correctness for ALL content types — agents, rules, commands, skills, hooks, prompts, checks, mcp, policy, learnings
- [ ] File discovery — correctly finds all canonical files via `resolveBundledContentRoot()` in the installed npm package
- [ ] Frontmatter parsing — metadata extracted accurately from all file types
- [ ] Error handling for malformed content — graceful failures with actionable messages

### 2.3 Customization Pipeline
- [ ] Override system integrity — `.hatch3r/{agents,commands,skills,rules}/{id}.customize.yaml` processed correctly
- [ ] Deny pattern enforcement — safety-critical content cannot be overridden
- [ ] Merge correctness — customizations merge with canonical content without corruption
- [ ] Override precedence — when multiple overrides apply, precedence is well-defined and documented

### 2.4 External Tool Config Utilities
- [ ] MCP config transformation correctness — `mcp.json` transformed per adapter format, per-adapter MCP schema delivered
- [ ] TOML generation — codex adapter TOML output is valid and correct
- [ ] CLI tool allowlist translation — `src/pipeline/agentToolAllowlist.ts` correctly maps canonical tool capabilities to per-agent allow/deny sets, with 0 false-allows in the per-agent vector
- [ ] Adapter tool-name translation — `src/pipeline/adapterToolTranslator.ts` maps canonical tool identifiers to each platform's native tool name with the `nativeQuestionTool` and `ASK_USER_TOOLS` invariants holding (both populated or both null per adapter)
- [ ] Utility robustness — edge cases, malformed input, missing fields across MCP, TOML, allowlist, and translator paths

### 2.5 Adapter Index & Registry
- [ ] Registry completeness — all 3 adapters (claude, cursor, copilot) registered and discoverable
- [ ] Adapter discovery — dynamic lookup works correctly
- [ ] Enable/disable logic — toggling adapters in config takes effect
- [ ] Capability querying — callers can query adapter capabilities accurately

### 2.6 Content System
- [ ] Selective init flow correctness — tag-based filtering produces correct content subsets
- [ ] Tag system (`tags.ts`) — tags accurately describe content, no misclassifications
- [ ] Preset definitions (`presets.ts`) — presets map to correct tag combinations
- [ ] Content filtering — inclusion/exclusion logic handles edge cases
- [ ] Content resolution and deduplication — no duplicate or missing artifacts
- [ ] Integration with CLI init — content system correctly feeds into the init flow

### 2.7 Archive System & Drift Detection
- [ ] Archive/backup creation and restoration — backups are complete and restorable
- [ ] Archive cleanup — old archives pruned to avoid disk bloat
- [ ] Drift detection during update — updates regenerate adapter outputs from bundled content and warn on drift before overwriting user-modified files
- [ ] Drift report accuracy — diff against on-disk copy distinguishes user edits from outdated canonical output

## Domain Boundary

> D02 audits adapter contracts and abstractions (base.ts, canonical.ts, customization.ts, content system): "Are the abstractions correct?" D09 audits per-adapter implementations: "Does each adapter correctly implement the contract for its target platform?" D11 audits end-to-end integration by tracing specific content types through the full pipeline: "When content flows from canonical source through adapter transformation to disk output, does it arrive correctly?" D11 findings must demonstrate cross-component failures that neither D02 nor D09 would catch independently.
