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: 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: 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: 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).