# AGENTS.md

Conventions, normative/informative markers, and catalogue ownership for the Autonomous Project Orchestrator.

## Naming Conventions

- All normative enum values use uppercase snake case (e.g., `MODEL_TOKENS`, `VALIDATION`, `ACTIVE`).
- Human-readable identifiers, content hashes, paths, provider-defined opaque values, and externally assigned identifiers
  are not enums and need not be uppercased.
- State names, event names, and policy-outcome names occupy separate namespaces. No identifier is reused across these three dimensions (state vs event vs policy-outcome). Events use completed or requested verb forms (e.g., `REPLAN_REQUESTED`, not `REPLAN_REQUIRED`). State identifiers may be reused across different state machines (e.g., `CANCELLED` is both a node state and an attempt state); such reuse is permitted within the state dimension.

## Normative vs Informative

- **Normative**: Defines requirements that must be met. Violations cause conformance failures.
- **Informative**: Provides context, examples, or guidance. Not enforced.
- **Mixed**: Contains both normative and informative sections; each section must be explicitly marked.
- **Normative for harness**: The test harness specification is normative, but the test procedure is informative.

Each doc under `docs/` has a normative/informative marker as its first line using an HTML comment: `<!-- normative -->`,
`<!-- informative -->`, `<!-- mixed -->`, or `<!-- normative for harness -->`.

## Catalogue Ownership

The following catalogues must be maintained:

- **Event catalogue** (`docs/event-catalogue.md`): Every event, its emitter, affected machines, payload, and replay
  status. Adding a new event requires a catalogue entry, a transition table entry, and a conformance test entry.
- **Glossary** (`docs/glossary.md`): Every state, freshness value, relation type, conflict type, run outcome, and policy
  outcome catalogued exactly once. This file is the authoritative catalogue; normative documents may reference these
  values by identifier but do not redefine them.
- **Relation types**, **Conflict types**, **Executor precedence**, and **Execution modes** are catalogued in the Glossary
  and must not be redefined in other documents. Normative documents that reference these lists must link to the Glossary
  entries (e.g., `[Relation types](docs/glossary.md#relation-types)`).
- **Extracted tables** (`docs/tables/*.yaml`): Canonical machine definitions (states, terminal states, wildcards, and
  transitions), policy-completeness rows, run outcomes, and experiment limits. The Markdown tables and state lists in
  `docs/control-plane.md` and `docs/experiment.md` are generated from these files.

## Change Rules

1. A new event requires a catalogue entry, a transition in the relevant machine definition under `docs/tables/`, and a
   conformance test entry.
2. Extracted tables are generated. To change one, edit `docs/tables/*.yaml`, run `.venv/bin/python scripts/tables.py --write` to regenerate
   the Markdown, and run `scripts/check-docs`. Never hand-edit content between `<!-- gen:NAME -->` markers.
3. A renamed heading is a breaking change for links. Update all references before renaming.
4. Cross-file references use explicit relative anchors: `[text](file.md#anchor)`, never "see §X.Y".
5. Document numbering is removed from all headings. Anchors provide all navigation.