Orchestrata Ultimate › Gates

Gates — Master Index

A gate in orchestrata-ultimate is a mechanical check with a command, a failure behavior, and no discretion. This index lists every gate in the order a change meets it, with where it runs, what it blocks, the ruling or ADR behind it, and its page. The path itself, with diagrams and a worked example, is on Workflow.

The layers:

1. Dispatch and session gates: Claude Code hooks that refuse a brief, a command or the end of a turn.
2. The worker's stop gate: the commit gate run on a temporary index before a worker may finish.
3. The commit gates: scripts/hooks/pre-commit and scripts/hooks/commit-msg.
4. The push gates: scripts/hooks/pre-push and the stages of scripts/run_tests.py it calls (freshness, affected selection, infrastructure, five safety gates, reuse, rehearsal exclusion, the capped test phase).
5. The 24 registered battery gates: the GATES registry of scripts/gates.py plus the __ast__ pre-step, cached in .cache/gates.json.
6. Ship, CI and deploy: deploy/ship.sh verify, the GitLab pipeline, the fleet-drift gates and the deploy launchers' checks.
7. The codetools gates and the process-level gates that live in workflow law.

The narrative context, where these gates sit in the design, decision and implementation lifecycle, is on Ruleset Engine — The Complete Picture (section 5, "Process-level gates").

The catalogue, in the order a change meets it

1. Dispatch and session (Claude Code hooks)

2. The worker's stop

3. Commit (scripts/hooks/pre-commit, scripts/hooks/commit-msg)

The pre-commit hook also runs three steps that never block: the stage-walls ledger (reports/precommit-walls.ndjson, ADR-0101 rule 2), ruff check --fix on the staged files, and the codebase-map refresh. They are described on Workflow — the commit gate.

4. Push (scripts/hooks/pre-push and scripts/run_tests.py)

5. Ship, CI and deploy

6. Elsewhere

Count. The catalogue has 51 entries: 27 in the tables above that are not battery gates (three of them groups with their own page: the 30 session guards, the process gates, the deploy launchers' checks) and the 24 battery gates below. Three gates run in both places (parallel-safety, test-purity, prolog-boundary) and are counted once, in the battery.

How the battery works (one command, three behaviors)

The registered gates have one entry point — enforced by the single-gate-entrypoint.sh session hook:

python scripts/gates.py                # changed gates only (the default)
python scripts/gates.py --all          # ignore the cache, run everything
python scripts/gates.py --only ruff mypy   # run only the named gate(s)
python scripts/gates.py --no-fix-ast   # skip the AST refresh (on by default)
python scripts/gates.py --no-fix       # skip the auto-format step

From scripts/gates.py's own docstring, the three behaviors that exist "because the manual alternative kept costing whole minutes and whole sessions":

1. Parallel. "The gates are independent read-only analyses over a tree nobody is mutating, so wall-clock is the slowest gate, not their sum. Measured 2026-08-07: ~50s serial -> ~25s parallel."
2. Deduplicated. "Each gate's verdict is cached against a fingerprint of the inputs it actually reads. Re-running with nothing changed is a no-op that prints the cached PASS instead of re-deriving it." The cache lives in .cache/gates.json. _fingerprint(roots) (AST toolkit, 2026-10-23) is a sha256 over the relative path and the sha256 of the bytes of every file under the gate's declared input roots, so it is insensitive to mtime; _interesting keeps only .py, .toml, .pl, .json, .md and .sh files and drops cache directories. One suffix set serves every gate. The function's docstring still says "from git's own object hashing"; the code reads the bytes itself. No gate mixes git state into its fingerprint, so a new commit or a moved master with no content change does not re-run feature-loss or wiring. Two gates (generated-artifacts, worktree-envs) opt out of caching entirely with the root !always (ALWAYS_RUN), because their subject is git or system state no content hash can see. Earlier versions of this page named GATE_MASKS and GATE_GIT_STATE; neither exists in any commit of scripts/gates.py (git log --all -S, 2026-10-23). The blind spots this leaves are listed on each gate's page; re-run one with python scripts/gates.py --only <gate> --all.
3. Self-healing. ruff --fix + black run before the gates (files written by scripts skip the editor-side autoformat hook), and a stale AST snapshot is refreshed automatically (__ast__ — see its page) because "that two-step ordering was documented and still forgotten repeatedly."

Exit code of the battery: 0 only if every gate passed.

The 24 registered gates

Where they run: by hand, python scripts/gates.py. No git hook, CI job or ship step runs the battery (grep of scripts/hooks/, .gitlab-ci.yml, .github/workflows/ and deploy/ship.sh, 2026-10-23). Ship runs its own copy of the plugin-drift check, "which this gate does not run" otherwise (see ship-verify), and the pre-push suite runs three of the gates as its safety gates. The battery exits non-zero when any gate fails.

Counts, verified against scripts/gates.py on 2026-08-29 and again with the AST toolkit on 2026-10-23: 23 GATES registry entries + the __ast__ pre-step = 24 cached gate names. python in the commands is sys.executable, the interpreter running the battery. ruff and mypy run through plain uv run, which in a checkout without UV_NO_EDITABLE=1 can re-sync the venv as an editable install; whether it does here is not measured (see source-provenance).

The three families

Reading a battery run

A real battery run prints one line per gate. SKIP lines are cached verdicts being reused ("unchanged since last PASS", with the previous evidence attached); OK/FAIL lines are fresh subprocess runs with a timing and the last lines of output:

[gates] SKIP ruff             unchanged since last PASS   0.1s | All checks passed!
[gates] OK   check-deps        25.0s | Dependency audit (59 declared deps): ✅ All third-party imports are declared in pyproject.toml.
[gates] FAIL prolog-gate       23.5s | ... stale (2): scripts/gates.py (content_changed) ...
[gates] 2 gate(s) in 25.1s wall (21 reused)
[gates] FAILED: prolog-gate

(The OK/FAIL details above are real recorded outputs from .cache/gates.json.)

Where the truth lives

• Registry and fingerprints: scripts/gates.py (GATES, ALWAYS_RUN, _fingerprint, _interesting).
• Cache: .cache/gates.json (per-gate fingerprint, ok, and where captured the last detail line).
• Battery tests: tests/scripts/test_gates.py, tests/scripts/test_gates_coverage.py.
• Single-entry-point enforcement: .claude/hooks/single-gate-entrypoint.sh (invoking gate scripts individually is denied; # gate-debug is the escape hatch for debugging one gate's own behavior).
• Git hooks: scripts/hooks/pre-commit, commit-msg, pre-push, wired by a relative core.hooksPath (scripts/install-git-hooks.sh).
• Claude Code hooks: plugins/orchestrata/hooks/hooks.json (generated from claude/), ~/.claude/settings.json and ~/.claude/settings.local.json (the three user-level hooks: dispatch_ledger.py, unshipped_guard.py, precommit_gate_subagent.sh).
• Test runner stages: scripts/run_tests.py::_main.

Known gaps (2026-10-23)

Related

• Workflow
• How we work — process, deployment, testing, coverage
• Workflow improvements, Bug fixes
• Tests, Green ledger (current entries)
• Deployment
• Claude hooks, codetools
• Decisions, Rulings