v2.1.0 to v2.1.0

---

name: ironlint-config

description: Authors, modifies, or removes checks in an IronLint .ironlint.yml policy.

license: MIT

metadata:

author: dynamik-dev

version: 2.1.0

---

# IronLint policy authoring

IronLint runs project-owned shell commands after a change or before work is

accepted. A policy is `.ironlint.yml` with a required `version: 1` and a

nonempty `checks` mapping:

```yaml

version: 1

execution:

timeout_secs: 30

total_timeout_secs: 300

checks:

format:

files: ["*.rs", "Cargo.toml"]

on: [change, accept]

timeout_secs: 10

run: cargo fmt --all --check

tests:

timeout_secs: 180

run: cargo test --locked

```

Every check has one nonempty `run` command. `files` is an optional glob or list

of globs. Bare filename globs such as `*.rs` match at any depth. `on` defaults

to `[accept]`; the other valid form is `[change, accept]` (either order).

Acceptance is required for every check.

`accept` runs every check once in check-ID order. `change` runs only checks that

opt into change feedback. Known `--file` paths filter those checks through

`files`; without known paths, every change-enabled check runs. A check owns any

iteration over files. `files` selects a check; it does not restrict what the

command can read or modify.

The optional `execution` block accepts positive integer `timeout_secs` and

`total_timeout_secs`. Their defaults are 30 and 300 seconds. A check's optional

positive integer `timeout_secs` overrides the command default for both events;

it may be shorter or longer, but the remaining total budget always caps it.

Timeout values cannot be null, zero, negative, fractional, or strings.

Check overrides require evaluator 1.1.0 or newer. Update the evaluator before

adding the field; older binaries reject it. Remove it before downgrading and

review/renew consent after either edit. Verdict schema 7 is unchanged.

`show-resolved-config` and `explain` expose the override and resolved command

budget before the total cap.

The total deadline covers selection, policy/script verification, commands,

output handling, and final verification. Initial capture and consent lookup

precede it. Expired final verification denies pass even when commands passed;

filesystem deadline checks are cooperative and cleanup has a bounded grace.

Put command sequences in a reviewed script under `.ironlint/scripts/` and

invoke that script from `run`.

## Command contract

IronLint executes `run` as `sh -c` from the selected root, with stdin closed.

The reserved variables are:

- `IRONLINT_ROOT`: canonical evaluated root.

- `IRONLINT_EVENT`: `change` or `accept`.

- `IRONLINT_BIN`: current IronLint executable.

Commands inspect the evaluated tree on disk. Never splice an untrusted path

into `run`; read paths from environment variables or quote fixed paths in the

command. Exit 0 passes. Exit 1–125 reports a policy violation. Exit 126/127,

signals, timeouts, or launch failures are execution errors.

## Workflow

Validate and review before granting local execution consent:

```sh

ironlint validate

ironlint trust

ironlint check --event change --file src/lib.rs

ironlint check --event accept

```

Use `ironlint explain PATH` to inspect change selection,

`ironlint show-resolved-config` to inspect the loaded policy, and

`ironlint check --format json` for schema-7 machine output.

When editing a policy, preserve existing check IDs unless the requested change

requires renaming one. Prefer the smallest command that enforces the stated

rule. Re-run `ironlint validate`, review the final command, re-run

`ironlint trust`, then exercise both a passing and a violating example.