diff --git a/scripts/README.md b/scripts/README.md index 6b54bfeb..b3fa46b0 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -6,7 +6,7 @@ The fleet's checks and review tooling, run by hand, with the deterministic ones Python only, and standard library only, with markdown-it-py the one exception. `build_dist.py`, `canonical_review.py`, `carry.py`, `pr_review.py`, `pr_review_copilot.py`, and `pr_cleanup.py` declare it in their inline script metadata. `build_dist.py` and `carry.py` import it only on the path that reads a region, since `skills_install.py` and `handoff.py` import them under a plain `python3`. Every check script is read-only and exits non-zero on a finding. `build_dist.py`, `local_review.py`, `canonical_review.py`, `handoff.py`, and `skills_install.py` below are the exceptions, since a generator, two recorders, an installer, and the handoff chain all exist to write. `build_dist.py --check` and `skills_install.py --report` are read-only modes for CI and for asking without changing anything. `local_review.py status` and `check` answer without recording anything, but they are not read-only in that same sense: reading the working tree stages it, which writes inside `.git` and runs any `filter.*.clean` the repository configures, and only the receipt is left untouched. `canonical_review.py` reads files rather than staging them, so its `list`, `status`, `sweep`, and `report` are read-only outright, and `record` alone writes. -The directory separates its kinds by name and by tree. A gate checks and exits non-zero on a finding, and its name carries a `_lint` or `_gate` suffix saying what it gates. The `prose_lint.py` and `repo_gate.py` entry points delegate to the action-owned implementations that gate this tree in CI, and `host_gate.py` gates the machine it runs on. A utility does work rather than gating and carries no suffix: `backlog_metrics.py`, `build_dist.py`, `canonical_review.py`, `handoff.py`, `local_review.py`, `pr_cleanup.py`, `pr_review.py`, `pr_review_copilot.py`, `skills_install.py`. `gh_graphql.py` is a library with no command line, the GraphQL transport and cursor walker that `backlog_metrics.py`, `handoff.py`, `pr_cleanup.py`, and `pr_review.py` import from beside them. `pr_review_checks.py` and `pr_review_rounds.py` are libraries with no command line as well. They are the pure readers `pr_review.py` imports for the head's checks and its review rounds. The unit tests live apart at the repository root under [`tests/`][tests], one `test_