# Research Findings: AI-Facing Repository Constitution

## Decision 1: Constitution is authoritative for AI
- **Decision**: AI-facing constitution overrides conflicting human docs for AI guidance; conflicts trigger updates to both with recorded resolution.
- **Rationale**: Ensures consistent automated actions and avoids drift between AI behavior and repo rules.
- **Alternatives considered**: (a) Defer to human docs and mirror later (rejected: increases drift); (b) Split authority by domain (rejected: adds ambiguity for AI tools).

## Decision 2: Documentation IA
- **Decision**: Place the living constitution in `/docs`; keep feature-specific planning/playbooks under `specs/001-ai-docs/` with index links in constitution.
- **Rationale**: Clear separation of durable source-of-truth vs feature-level artifacts; aligns with spec expectations.
- **Alternatives considered**: (a) Keep all AI docs in `/specs` (rejected: mixes planning with durable guidance); (b) Distribute docs per module directory (rejected: harder AI discoverability).

## Decision 3: Validation approach
- **Decision**: Validate docs manually against repo conventions and the specification’s success criteria (discoverability ≤2 steps, full module/host coverage, secrets map completeness).
- **Rationale**: No automated tests for markdown; checklist-based review matches spec.
- **Alternatives considered**: (a) Add automated linting now (rejected: out-of-scope for this documentation feature); (b) No validation (rejected: risks drift and omissions).

## Decision 4: Navigation and conflict logging
- **Decision**: Anchor discoverability through `docs/constitution.md` with links to `docs/reference/index.md` and `docs/playbooks/`; record any conflict resolutions in `specs/001-ai-docs/research.md` with date and source references.
- **Rationale**: Keeps navigation within two steps for AI and centralizes historical decisions for reconciliation.
- **Alternatives considered**: (a) Distribute links per playbook only (rejected: harder to enforce two-step navigation); (b) Log conflicts in ad-hoc comments (rejected: loses traceability for AI tools).

## Decision 5 (2026-02-01): MCP docs sync alignment
- **Decision**: Treat the constitution as authoritative, update MCP docs to include explicit tool anchors, and align the tool catalog anchors to actual markdown headings; scope sync checks to MCP tool headings in `docs/reference/mcp-server.md`.
- **Rationale**: Prevents false drift from unrelated docs while ensuring tool anchors remain accurate and navigable.
- **Alternatives considered**: (a) Force every doc to map to a tool (rejected: inflates catalog and adds noise); (b) Keep loose anchors without validation (rejected: undermines navigation and sync intent).

## Decision 6 (2026-02-02): secureHost gating for SOPS config
- **Decision**: Gate SOPS configuration behind `config.my.secureHost` so non-secure hosts skip secret loading.
- **Rationale**: Aligns `config/base.nix` behavior with the constitution’s secureHost rules and avoids secret dependency on non-secure hosts.
- **Alternatives considered**: (a) Leave SOPS enabled on all hosts (rejected: violates secureHost contract); (b) Duplicate SOPS logic per host (rejected: increases drift risk).

## Decision 7 (2026-02-07): Module categories and patches location; active hosts update
- **Decision**: Treat `patches/` as a root-level directory (not a module category) and update active hosts to include `vps`.
- **Rationale**: Repo structure places patches at the root and hosts include `vps`; documentation must reflect actual paths and host inventory.
- **Alternatives considered**: (a) Move `patches/` under `modules/` (rejected: would change repo layout); (b) Keep `vps` undocumented (rejected: causes host list drift).