Structural release gates
How versioned invariants move from fixtures through shadow evaluation into release-blocking decisions without silently passing missing evidence.
Safe promotion for deterministic architecture checks
An invariant version is immutable. Changing its query, thresholds, or required ledgers creates a new version with a new content hash. That version must prove itself before it can influence a release.
Promotion path
| State | Purpose | Can block a release? |
|---|---|---|
| Draft | Author the statement, graph query, evidence requirements, and remediation contract. | No |
| Fixture validated | Pass the reference true-positive and benign cases with deterministic output. | No |
| Shadow | Evaluate on real audits and record results without changing customer state. | No |
| Review | Examine disagreements, missing-evidence rates, and customer-confirmed outcomes. | No |
| Enforced | Apply the approved gate policy using the pinned invariant version. | Yes, when policy says so |
| Retired | Preserve historical reproducibility but stop evaluating new audits. | No |
Gate outcomes
- Pass means every required ledger was present and the invariant evaluated false.
- Review means the invariant produced a hypothesis, a low-confidence path, or a policy requires human confirmation.
- Blocked means an enforced invariant produced an asserted result that matches the release policy.
- Insufficient evidence means one or more required ledgers were absent. It never renders as pass.
Before promotion
- Run every positive and benign fixture and compare stable finding IDs.
- Confirm taxonomy snapshots change labels only, not the detected set.
- Run the version in shadow on representative workspaces.
- Review false-positive, false-negative, and insufficient-evidence samples.
- Confirm the UI exposes the path, ledgers, confidence, and verification predicate.
- Record reviewer, invariant hash, decision, and rollback version.
The operator control plane enforces a minimum of 50 reviewed samples and requires observed precision to meet the invariant's target before the enforced transition succeeds. A code-owned invariant that is not blocking-eligible cannot be promoted into a blocking state.
A clean gate needs evidence
Missing cloud, CI/CD, runtime, or IaC evidence is a coverage result. It is not evidence that the structure is safe.
Every completed audit records its gate mode, outcome, reasons, enforced invariant IDs, and evaluation time. In shadow mode the result is visible but cannot block. In enforced mode a failing blocking invariant records blocks_release: true; insufficient evidence remains a distinct outcome and does not silently pass.
Consequence-proportional enforcement
The enforced gate uses the affected asset class as an input, not merely the invariant ID. Crown-jewel failures block automatically, and missing evidence for a crown-jewel-scoped invariant is itself a typed blocking result. Configured invariant failures block at critical scope or above by default; important, standard, low-confidence, and below-threshold failures remain visible for review. Every reason records its code, invariant version, asset class, effective severity, confidence, match count, and missing ledgers.
Path analysis follows the same principle while remaining bounded: standard and unknown targets use the invariant's declared hop cap, important targets may search up to six hops, critical targets up to eight, and crown jewels up to twelve. The engine still applies preconditions, per-target result limits, and path-confidence floors, so deeper assurance does not become an unbounded traversal.
Remediation tiers
R1 changes a local configuration or identity boundary. R2 changes a shared code or architecture pattern. R3 changes an organization-level dependency or control design. Generated proposals remain reviewable, and verification re-evaluates the original invariant against freshly collected evidence.
Was this guide useful?
Your response stays in this browser unless you open a GitHub issue.Reports and remediation
Canonical report JSON, approval, deterministic exports, patch proposals, static rescans, and human-controlled GitHub pull requests.
Authorized workflow actions
Create tickets, route finding ownership, and record policy exceptions through capability-specific grants and separate human approval.