AGENTS.md · diff

git:20260909.e45146c to git:20260911.75c7edc

1 added, 47 removed. Audit A to A.

- # Repository guidance

- The canonical `orchflows` source: a four-tier library for orchestrator >

- subagent work. `ARCHITECTURE.md` maps boundaries, ownership, dependency

- direction; `docs/vocabulary.md` owns every library term and each

- standard its own domain's; `rules/` owns cross-cutting law, under

- `rules/visibility.md` §3.

- Routing, the state sink and the friction law are the host block's —

- `templates/host-block.md`, installed at `~/.orchflows/host-block.md`.

- From this checkout the friction command is `python scripts/friction.py

- "<what happened>" "<what was expected or missing>"`, same sink, same

- flags.

- ## Required checks

- [Prerequisites](tools/check-prerequisites.md).

- Through this host's verified interpreter (`uv run --no-project python`;

- bare `python` is a Windows Store stub; Python 3.9 or newer,

- `install.py`'s floor):

- python tools/validate.py

- python tools/run_tests.py # one process per module

- python tools/run_serial_compat.py # selected same-process lane

- python install.py --dry-run

- git diff --check

- `python tools/run_required.py` runs the five, cached by tree; a gate

- passes `--no-cache`. While working,

- `python tools/run_tests.py --scope <changed-paths>` runs only the

- affected shards. Parallel units preview with

- `python tools/affected_tests.py --format json <changed-paths>` (space-separated).

- If shared infrastructure selects the repository, units run exact owner controls;

- the joined gate runs all five. Adding or removing tests

- regenerates the manifest with

- `python tools/run_serial_compat.py --write-manifest`.

- Selected routinely checks cross-module coupling; exhaustive

- `python -m unittest discover -s tests -v` stays scheduled/manual and

- pre-release; green here is provisional until the

- `.github/workflows/checks.yml` matrix agrees — `python tools/preflight.py`

- replays it, docstrings own the rest.

- ## Serial compatibility

- `tools/serial-compat-policy.md` defines the routine lane and fallback.

+ `docs/architecture.md`: how orchflows fits together, where anything belongs. `docs/home.md`: paths, setup, update. `docs/hosts.md`: isolation, plugin registration. `docs/history.md`: agent transcripts.