Orchestrata Ultimate › Gates › uncovered-policies

Gate: uncovered-policies

At a glance

What it refuses

Strictly speaking, nothing — by design. It refuses to let unmechanized policy go unseen: every battery run prints each policy requirement that has no enabled mechanism behind it. A genuinely RED battery entry for this gate means the query machinery itself broke, not that a policy is uncovered.

Why it exists

From the scripts/gates.py registry comment:

"uncovered-policies is REQ-GATE-011's own drift detector (plans/prolog-gates-implementation-plan.md), wired ADVISORY per the user's 'severity tier in ONE channel' ruling (2026-08-19, gate_rules.pl policy_requirement/1): uncovered(Policy) names a policy requirement with no enabled mechanism behind it, and that is DRIFT — no file:line, nothing broken, must stay visible without ever blocking until someone promotes it."

And from scripts/gate.py's docstring: "uncovered prints every policy requirement with no enabled mechanism behind it (REQ-GATE-011) — RUL-014 as a query, never a gate: it reports, it does not change whether run passes."

How it runs

• Command: python scripts/gate.py uncovered
• When it fires: the scripts/gates.py battery (registered as uncovered-policies), on every run whose inputs changed.
• The advisory mechanism, precisely (registry comment): "gate uncovered (scripts/gate.py cmd_uncovered) already returns EXIT_OK on every successful query regardless of what it finds, by design — the SAME shape gate facts --stats already has (a report, not a verdict). The ordinary ok/fail wiring … therefore already reports this gate OK while the tail-captured stdout still prints the count and every policy name, so the '1' becomes visible on every battery run instead of needing to be asked for."
• Inputs: fingerprint roots ("src", "tests", "scripts", ".claude/banned-libraries.txt", "pyproject.toml") — "Same input set as prolog-gate, because it queries the identical extracted fact base (policy_mechanism/3, tool_rule_status/3) plus gate_rules.pl's own violation/4 heads."
• Caching: the verdict is cached in .cache/gates.json against _fingerprint(roots): a sha256 over the relative path and bytes of every file under the directory roots whose suffix is .py, .toml, .pl, .json, .md or .sh (_interesting() in scripts/gates.py), plus the two file roots. There is no per-gate suffix mask: this page previously quoted one, and git log --all -S GATE_MASKS -- scripts/gates.py finds no commit that ever contained a GATE_MASKS table (checked 2026-10-23).
• What counts as a policy requirement (gate_rules.pl): a native rule in gate_rules.pl, a configured formatter, or a ruff rule whose status in this project's config is enabled or ignored. Ruff rules with status unknown are excluded, so uncovered/1 does not report on "the ~700 ruff rules nobody asked about". The predicate's comment also separates it from rulings_lint.py: this one reasons over ruff/native mechanisms, the lint over hook/gate/banned-deps/ constitution directives, "and neither replaces the other here."

Typical failures and how to fix them

• Exit codes: EXIT_OK (0) on every successful query, whatever it finds. A non-zero exit "would mean gate uncovered itself broke (a bad snapshot, a Prolog consult failure), not that a policy is unmechanized." cmd_uncovered returns EXIT_ERROR (2) on SnapshotMissingError (read through the AST toolkit on 2026-10-23).
• A red uncovered-policies entry. Treat it as a broken query, not a policy finding: check that plans/ast-ultimate.json exists and that the .pl files consult, then re-run the battery.
• What its output looks like (representative): a count plus every uncovered policy requirement by name — the standing "1" (or 0, or N) that stays visible in the battery tail on every run.
• Un-blocking / acting on it: promoting an uncovered policy means giving it a real mechanism (a hook, a gate, a banned-deps line, a constitution article) and recording it — at which point the count drops. There is no waiver because there is nothing to waive.

Wiring

• Invokers: scripts/gates.py (battery).
• Rulebase: gate_rules.pl (policy_requirement/1, uncovered/1) under src/orchestrata_ultimate/prolog/.
• Tests: tests/scripts/test_gate_cli.py (the uncovered subcommand), plus the engine suite under tests/gates/.

Related

• Gates master index
• Development workflow
• RUL-014 — A ruling that exists only in prose is incomplete work
• prolog-gate — the blocking sibling over the same fact base
• rulings-lint — the same "prose is not a mechanism" doctrine applied to the rulings canon (also on the suite-preflight family page)