Policies, Exceptions and Decisions

This page explains how a policy turns findings into allow, warn or block, how an exception overrides a block for one reviewed case, and what the decision record of each run holds. Each step is shown on a real run; the file formats are documented in full in the Policy Reference.

Evaluating a policy, applying exceptions and writing decision records need no key. A policy decides on the findings the run has: without a key that is each statement as written, and the decision record says so in analysis_depth. What a Key Adds lists the findings a key adds.

How a policy decides#

A policy is a YAML file, usually kept in the repository as .lexega/policy.yml. For each finding, Lexega looks for an action in this order:

  1. An entry under policies that names the finding's rule ID and applies to this environment.
  2. Otherwise, the severity_actions entry for this run, by the finding's severity.
  3. Otherwise, default_action.

The action is allow, warn or block. A run with at least one blocked finding is blocked and exits 2; warnings are recorded but do not fail the run. The Policy Reference covers scoping entries by environment, path, repository and kind of run.

analyze, review, ci and diff take the same three options for a policy run, and all three are required together: --policy names the file, --env the environment it is evaluated for, and --decision-out where the decision record goes.

A minimal policy#

In prod, this policy blocks a write with no WHERE clause unless an exception covers it. severity_actions blocks every other critical finding, and this one outside prod. No exception can override a block from severity_actions. High findings warn:

yaml
schema_version: 1
policy_id: data-platform
policy_version: "1.0.0"

policies:
  - rule_id: DML-WRITE-UNBOUNDED
    action: block
    envs: ["prod"]
    requires_exception: true
    description: "A write with no WHERE clause needs an approved exception in prod"

severity_actions:
  - critical: block
    high: warn

default_action: allow

requires_exception: true records that an exception can lift this block, which is also what happens when the line is left out; without it, policy-lint prints a warning (P002) and still exits 0. requires_exception: false turns exceptions off for the entry: no exception lifts its block.

Save it as .lexega/policy.yml and check it. policy-lint needs no key, and exits 0 when the file is valid:

bash
lexega-sql policy-lint .lexega/policy.yml

Then analyze a migration under it. Save this as migrations/reset_orders_tmp.sql:

sql
DELETE FROM staging.orders_tmp;
bash
lexega-sql analyze migrations/reset_orders_tmp.sql \
  --policy .lexega/policy.yml --env prod \
  --decision-out .lexega/decisions/run-1/

The report on standard output is the usual one:

text
...
findings:
  [CRITICAL] Unbounded write operation detected - the statement has no WHERE clause or its WHERE clause matches every row. This affects ALL rows in the target table(s).
    ↳ Line 1 • `DML-WRITE-UNBOUNDED` • "DELETE FROM staging.orders_tmp" • migrations/reset_orders_tmp.sql:1:1

The policy blocks the finding, so the command exits 2 and writes decision.json and the full report, risk_report.<decision_id>.json, to .lexega/decisions/run-1/. With the text format, a summary of the decision is also printed on standard error. In CI, exit code 2 is what fails the job; the CLI Reference lists every exit code.

What the policy sees#

The policy decides on every finding and every context entry the analysis produces, whatever --min-severity is. The option only filters what the report shows and counts. A low-severity finding that a policy entry or severity action blocks still blocks the run, even when the report lists no findings; the risk_report.<decision_id>.json written beside the decision holds the full report, not the filtered one. Info-level rules report context, which no severity_actions key matches; to act on one, name its rule under policies.

Exceptions#

An exception is a reviewed, time-limited override for one rule. This one allows the unbounded delete above, in that one file, in prod, until the end of 2026:

yaml
schema_version: 1
exceptions:
  - exception_id: EXC-042
    policy_id: data-platform
    rule_id: DML-WRITE-UNBOUNDED
    scope:
      scoped:
        paths: ["migrations/reset_orders_tmp.sql"]
        envs: ["prod"]
        expires_at: "2026-12-31T23:59:59Z"
    reason: "Scratch table is emptied before each reload"
    approved_by: "data-platform-leads"
    approved_at: "2026-11-02T09:00:00Z"
    ticket: "DATA-1234"

Save it as .lexega/exceptions.yml, check it against the policy with lexega-sql policy-lint .lexega/policy.yml --exceptions .lexega/exceptions.yml, and pass it to the run:

bash
lexega-sql analyze migrations/reset_orders_tmp.sql \
  --policy .lexega/policy.yml --exceptions .lexega/exceptions.yml --env prod \
  --decision-out .lexega/decisions/run-2/

The finding is still reported, the run is allowed and exits 0, and the decision record names the exception that allowed it:

json
  "outcome": {
    "allowed": true,
    "blocked_reason": null,
    "exceptions_used": [
      "EXC-042"
    ]
  },

How an exception applies:

  • It must name the policy's policy_id and the rule's ID, and its scope must match the run: the paths, path patterns or prefixes, environments, repositories or roles it lists. A global scope matches every run and has to be written out as global.
  • It overrides a block from an entry under policies that names the rule. A block that comes from severity_actions cannot be excepted; give the rule its own entry under policies to make it exceptable.
  • After expires_at the exception does not apply. policy-lint and the run both warn about an expired exception, and the run blocks again.

The decision record#

Every policy run writes a decision record. For a single file, --decision-out names a folder and the record is decision.json in it, next to risk_report.<decision_id>.json, the full report the decision was made on. For a folder or a review, there is one record per file, named after the file's path, such as migrations_cleanup_orders.sql.decision.json. --decision-artifact-format yaml writes YAML instead of JSON.

This is the record of the blocked run above, cut to its key fields:

json
{
  "decision_schema_version": 2,
  "engine_version": "3.0.0",
  "decision_id": "34d417946fb8c0c4aedc73263b28f6d08f558950781ba9cd9d722b449c87ff29",
  "timestamp": "2026-11-13T12:05:40.938645161Z",
  "run_scope": {
    "kind": "snapshot"
  },
  "inputs": {
    "sql_sha256": "8deb49da1cc9d5b31f35a1c1ebce832a1d6a88e2ef3ded6bec395a8b5034302d",
    "policy_id": "data-platform",
    "policy_version": "1.0.0",
    "policy_sha256": "5d56077cee807465877fe7df6556d972060dc8acf0ebbb80fa3a1425e408636e",
    "exceptions_sha256": null,
    "env_context": {
      "env": "prod",
...
      "path": "migrations/reset_orders_tmp.sql",
      "role": null
    }
  },
  "analysis": {
...
    "matched_rules": [
      {
        "rule_id": "DML-WRITE-UNBOUNDED",
        "action": "block",
        "severity": "Critical",
...
        "policy_description": "A write with no WHERE clause needs an approved exception in prod",
        "finding_indices": [
          0
        ],
        "findings": [
          {
            "rule_id": "DML-WRITE-UNBOUNDED",
            "severity": "Critical"
          }
        ],
        "exception_used": null
      }
    ]
  },
  "outcome": {
    "allowed": false,
    "blocked_reason": "Blocked by policy rule DML-WRITE-UNBOUNDED",
    "exceptions_used": []
  },
...
}
  • inputs identifies what was decided on: the SHA-256 of the SQL file, the policy's ID, version and SHA-256, the SHA-256 of the exceptions (null when none were given), and the environment and path. --team, --repo, --commit, --change-id and --job-type fill the other env_context fields; in CI most of them are detected from the pipeline.
  • run_scope says what kind of run it was: snapshot for analyze, or change with the base and head of a review.
  • analysis.matched_rules lists each rule the policy acted on, with its action, the indexes of its findings in that report, findings (each finding's rule and its own severity) and exception_used. A finding acted on by severity_actions is listed as _severity_critical, _severity_high and so on.
  • outcome is the decision: allowed, the reason when blocked, and the exceptions used.
  • decision_id is a SHA-256 over the inputs, the analysis and the outcome. It leaves out the timestamp, so the same SQL, policy and exceptions in the same environment give the same ID on every run.

Keep decision records where your audit trail lives. --decision-out takes a cloud storage location as well as a folder; use a new folder or prefix per run, for example one named after the CI run ID, so runs do not overwrite each other.

Something missing or wrong? Open an issue on GitHub or write to [email protected].