# The Estate Agent specification

**Version 0.1.0.** Anchors on this page are permanent. Later versions add
sections; they do not renumber or rename existing ones, so a link or a citation
to any heading here keeps working.

## 1. The deed

Each repository has exactly one source of truth at `.agent/estate.yaml`. All
assistant-specific context files are generated from it and are never edited
directly. A conforming implementation MUST fail a check when a generated file
differs from what the deed would produce.

## 2. Generated context files

From one deed, an implementation generates `CLAUDE.md`, `AGENTS.md`,
`GEMINI.md`, `.github/copilot-instructions.md`, and `.cursor/rules/00-estate.mdc`.
Each carries a stamp recording the hash of the content generated, which allows a
hand edit to be distinguished from a stale file.

## 3. Tiers

A repository declares one of three tiers.

| Tier | Name | The agent may | The agent may not |
|---|---|---|---|
| 1 | Restricted | read, explain, propose | write, open pull requests, mutate state |
| 2 | Reviewed | edit, open pull requests | merge |
| 3 | Autonomous | edit, open pull requests, merge on green CI | bypass CI, edit another repo's deed |

Legacy systems default to tier 1. An implementation MUST NOT raise a tier
automatically.

## 4. The resolution ladder

A connection between two repositories is established by exactly one method, and
the method is recorded on the connection.

| Rank | Method | Basis | Confidence |
|---|---|---|---|
| 1 | `declared` | the source names the service outright | 0.95 |
| 2 | `dependency` | a generated client for the service is a dependency | 0.90 |
| 3 | `env` | a configured variable names the service | 0.75 |
| 4 | `host` | a URL hostname matches the service | 0.70 |
| 5 | `path` | the called path matches exactly one service's endpoint | 0.60 |

## 5. Evidence

Every connection MUST cite a file path and line number. A connection without
evidence MUST NOT appear on the map.

## 6. Ambiguity

Where a signal matches more than one service equally well, an implementation
MUST NOT choose. The signal is recorded for human confirmation, with its
candidates listed.

## 7. External dependencies

A signal that matches no service in the estate is external, not ambiguous. It
MUST be recorded separately from items awaiting confirmation.

## 8. Ship cost and landing order

Repositories are classified by how reversibly they deploy. Client applications
(mobile, TV, installed desktop) cannot be rolled forward, so where the affected
set contains one, an implementation MUST produce an expand-and-contract landing
order: add the new shape, migrate services, ship clients, and only then remove
the old shape.

## 9. Self-healing

An implementation repairs staleness automatically, subject to four constraints:

1. It MUST NOT overwrite a file that has been edited by hand.
2. It MUST NOT relax a safety rule without human action.
3. It MUST NOT modify source code.
4. It MUST migrate deeds written by earlier versions.

## 10. The correction protocol

Generated context files instruct the agent that when reality contradicts them,
the agent corrects the deed — not the generated file — within the same unit of
work, and notes the correction in the pull request.

## 11. Data flow

Levels 1 and 2 of a conforming implementation MUST NOT make network calls of
any kind, including telemetry.