# Mirror Authoring Contract

> Authoritative per-file authoring contract for the three root IDE
> mirrors (`AGENTS.md` / `CLAUDE.md` /
> `.github/copilot-instructions.md`) and the IDE-extras escape
> hatch. Extracted from `CANONICAL.md` §14 / §15 by spec-134
> sub-005 so the mirrors stay lean (§10.4 DRY — one canonical home).
> The mechanically-checkable rows are enforced by
> `tools/skill_lint/checks/md_mirror.py`.

## Strict Content Contracts (per-file authoring reference)

The three root IDE mirrors are byte-equivalent in canonical payload
(generated from `src/ai_engineering/templates/project/CANONICAL.md`).
Each mirror appends an IDE-extras fence with content unique to that
IDE. **Authoring contract** (brief §2.3 verbatim):

| File | MUST contain | MUST NOT contain |
|------|--------------|------------------|
| `<repo>/AGENTS.md` | Full canonical payload (§§0-13), no IDE-extras block. | Any `@AGENTS.md` import. Any IDE-specific runtime knobs. |
| `<repo>/CLAUDE.md` | Full canonical payload + IDE-extras with Hot-Path Discipline, Hooks Configuration, Runtime layer hooks, Token Efficiency, Engram doc pointer, Audit observability. | `@AGENTS.md` import. Cross-IDE skill list. |
| `<repo>/.github/copilot-instructions.md` | Full canonical payload + IDE-extras with Copilot Hooks Wiring table. | Any `See AGENTS.md` cross-reference (D-131-14). |
| `<repo>/.cursor/skills/ai-<name>/SKILL.md` | (ACTIVE per spec-128 Wave 4, supersedes D-133-07) Native Cursor 2.4+ on-demand skills (folder per skill). Generated by `scripts/sync_mirrors/cursor_target.py`. | Hand-edited content. Skills under `.cursor/rules/` (always-included path; framework writes nothing there). |
| `<repo>/.cursor/agents/ai-<name>.mdc` | (ACTIVE) Agent payload files for Cursor. Generated. | Hand-edited content. |
| `<repo>/.opencode/skills/ai-<name>/SKILL.md` | (ACTIVE per spec-128 Wave 4, supersedes D-133-06) Native OpenCode on-demand skills (folder per skill, agent-discovered lazy-load, NOT visible in `/` menu). Generated by `scripts/sync_mirrors/opencode_target.py`. | Hand-edited content. |
| `<repo>/.opencode/commands/ai-<name>.md` | (ACTIVE per spec-128 Wave 5) Thin saved-prompt wrappers (one per skill) that surface `/ai-<name>` in OpenCode's slash menu and lazy-load the matching skill via the `skill` tool. Generated by `scripts/sync_mirrors/opencode_target.py`. | Hand-edited content. Duplicated skill body bytes (SSOT is `.claude/skills/`). |
| `<repo>/.opencode/agents/ai-<name>.md` | (ACTIVE) Agent files for OpenCode. Generated. | Hand-edited content. |
| `<repo>/GEMINI.md` / `<repo>/.gemini/*` | (DELETED per spec-151 — Gemini CLI support retired pre-release.) | The files/directories themselves. |
| `<repo>/.codex/AGENTS.md` | (DOES NOT EXIST — Codex reads root AGENTS.md natively.) | The file itself. |
| `<repo>/.github/instructions/*` | (DELETED per spec-128 D-128-07 — copilot-instructions.md covers it.) | The directory itself. |
| `<repo>/.agent/*` | (DELETED per spec-151 — Antigravity uses `.agents/`.) | The directory itself. |
| `<repo>/.cursor/rules/*` | (NOT USED for skills — framework emits skills only under `.cursor/skills/`. Operators may add their own always-included rules here without conflict.) | Framework-generated content. |
| `<repo>/CONSTITUTION.md` | Project-identity only (10 sections: Mission / Stakeholders / Vocabulary / Prohibitions / Compliance gates / Anti-goals / Boundaries / Escalation / Language / Lifecycle phase). | Any AI-behaviour header (KISS / YAGNI / SOLID / DRY / TDD / SDD / Clean Code / Hexagonal Architecture / Simplicity First / Plan-Mode Default / Surgical Changes / Goal-Driven Execution / Subagent Strategy / Self-Improvement Loop / Demand Elegance / Autonomous Bug Fixing / Think Before Coding). |
| `<repo>/README.md` | Install, value-prop, links to AGENTS.md + CONSTITUTION.md. | Skill list. Agent list. Chain duplication. |
| `<repo>/CONTRIBUTING.md` | Dev setup, PR process, test commands, repo layout. | Duplication of canonical content. |
| `<repo>/docs/getting-started.md` | 3-minute path: install → `/ai-start` → first `/ai-brainstorm` → first PR. | Internals. Skill list. |

This table is the authoring reference. Mechanically-checkable rows
are enforced by `tools/skill_lint/checks/md_mirror.py`:

- sha256 equivalence across the three root mirrors (canonical payload
  bytes, fence stripped).
- No `@AGENTS.md` import in any mirror.
- No `GEMINI.md` or `.gemini/` orphan on disk.
- No `.codex/AGENTS.md` orphan on disk.
- No forbidden AI-behaviour header in CONSTITUTION.md.
- No extracted section headings (`## 10.` / `## 14.` / `## 15.` /
  `## 16.`) in any mirror (sub-005 guard).
- The three `docs/` targets (`principles.md`, `mirror-authoring.md`,
  `surface-axioms.md`) exist on disk (sub-005 guard).

## IDE-Extras Escape Hatch (R-1.1 / R-131-02 mitigation)

Each IDE mirror MAY append a fenced block carrying content unique to
that IDE (Hot-Path tuning for Claude Code, Hooks Wiring table for
Copilot, etc.). The fence is recognised by `md_mirror.py`
and stripped before the sha256 equivalence check.

```
<!-- ide-extras:start -->
…IDE-specific content (hot-path budgets, hooks wiring,
runtime tunables)…
<!-- ide-extras:end -->
```

The block is OPTIONAL — `AGENTS.md` carries no extras (it is the base
mirror). All other mirrors carry at most one fence block.
