# Autonomous Project Orchestrator

[ARCHITECTURE.md](ARCHITECTURE.md) defines the architectural principles, execution semantics, trust boundaries, and
implementation decisions. This file provides a brief overview, reading order, and link check instructions.

## Status

This document is a design baseline for a practical autonomous project-development orchestrator. It is not a claim that
arbitrary projects can presently be developed autonomously and reliably.

## Purpose

The orchestrator coordinates recursive problem decomposition, parallel execution, multi-model reasoning, deterministic
tools, integration, validation, and replanning. Its objective is to make verified progress on an initially incomplete
project description.

## Layout

| Document | Content | Normative? |
|---|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | Core principles, invariants, architectural model | Normative |
| [docs/control-plane.md](docs/control-plane.md) | Deterministic governance, reducer specification, state machines, failure handling, run termination, crash recovery | Normative |
| [docs/work-graph.md](docs/work-graph.md) | Work graph, node contracts, decomposition, actions | Normative |
| [docs/integration-and-conflicts.md](docs/integration-and-conflicts.md) | Conflicts, integration ownership, repository semantics | Normative |
| [docs/budgets.md](docs/budgets.md) | Hierarchical budgets, accounting, ledger | Normative |
| [docs/executors.md](docs/executors.md) | Executor selection, trust boundary, executor protocol, sandbox | Normative |
| [docs/validation.md](docs/validation.md) | Evidence, acceptance, binding, independent evaluation | Normative |
| [docs/experiment.md](docs/experiment.md) | Conformance gate, experiment procedure, evaluation | Normative for harness |
| [docs/roadmap.md](docs/roadmap.md) | MVP boundary, implementation sequence, deferred questions | Mixed |
| [docs/deferred.md](docs/deferred.md) | Alternatives, routing, evolving scope | Informative |
| [docs/glossary.md](docs/glossary.md) | Identifier catalogue | Normative |
| [docs/event-catalogue.md](docs/event-catalogue.md) | Event definitions and payloads | Normative |
| [docs/tables/](docs/tables/) | Canonical state-machine, policy, outcome, and limit tables | Normative |

## Reading Order

1. [README.md](README.md) — this file
2. [ARCHITECTURE.md](ARCHITECTURE.md) — core principles and invariants
3. [docs/control-plane.md](docs/control-plane.md) — reducer specification
4. [docs/work-graph.md](docs/work-graph.md) — graph structure and contracts
5. Remaining docs as needed by topic

## Documentation checks

Run the canonical documentation validation from the repository root:

```sh
scripts/check-docs
```

`docs/tables/*.yaml` is the single source of truth for the state-machine, policy-completeness, run-outcome, and experiment-limit tables. The Markdown tables and state lists between `<!-- gen:NAME -->` markers in `docs/control-plane.md` and `docs/experiment.md` are generated from those files. Edit the YAML and run `.venv/bin/python scripts/tables.py --write` to regenerate; `scripts/check-docs` fails when the committed Markdown does not match.

Create the development environment and install the Python-based documentation tools:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
```

The check requires:

* Python 3.10 or later;
* [`pymarkdownlnt`](https://github.com/jackdewinter/pymarkdown), pinned to version 0.9.40;
* [`PyYAML`](https://pyyaml.org/), pinned to version 6.0.2, used by the table verifier;
* [`lychee`](https://github.com/lycheeverse/lychee), tested with version 0.24.2.

The Markdown policy is configured in `.pymarkdown.yml`. The local `.venv` is used automatically when present and is not committed. CI runs the same script on every push and pull request.