Diagnostics and exits

Finding anatomy

Diagnostic commands reuse a small Finding shape. That keeps machine consumers stable without turning the terminal report into a JSON dump.

One finding object

{
  "id": "environment.runtime.selected",
  "category": "environment",
  "state": "passed",
  "severity": "info",
  "policy": "observe",
  "title": "Resolved Lean environment",
  "detail": "lev selected the local project environment.",
  "evidence": {
    "selector": "local"
  },
  "remediation": null,
  "elapsed_ms": 0.24
}

Field	Meaning
`id`	A stable machine-readable identifier such as `environment.runtime.selected`.
`category`	The part of the system that owns the finding, such as environment, project, dependency, cache, or workspace.
`state`	Whether the check `passed`, was `raised`, or was `not_applicable`.
`severity`	How the observed condition is classified: `info`, `warning`, or `error`.
`policy`	What a policy command does with the finding: `observe`, `pass`, or `fail`.
`title`, `detail`	A short label and the human-readable explanation.
`evidence`	Optional structured facts behind the finding.
`remediation`	An optional concrete next step.
`elapsed_ms`	Optional timing for the check, in milliseconds.

Severity describes the evidence lev found. Policy determines whether that evidence fails a gate. An error can remain observational, and a policy failure is counted from policy: "fail", not inferred from severity.

Exit behavior

Exit behavior follows the job. Observational commands report findings and return 0. Gate commands return nonzero when the gate fails. Delegated and workspace commands preserve the child process status when that is the most useful result.

Observational commands

Bare lev inspect, lev inspect environment, and lev inspect dependencies return 0 after writing their report, even when it contains warnings or errors. These commands collect evidence; they do not enforce project policy.

Policy and drift commands

lev inspect graph returns 1 when it finds an import cycle.
lev deps outdated --check returns 1 when a compatible update exists.
lev inspect imports --check returns nonzero when imports can be minimized or validation fails.
lev inspect trust returns 1 for policy violations or an incomplete declaration scan.
lev check returns 1 for a provably stale selected revision and for other configured gate failures.

Delegated and workspace commands

lev inspect performance stops on the first failed warmup or sample and returns that command's code.
Delegated process failures preserve the child's exit code where applicable.
Workspace operations stop at the first failure unless --keep-going is set; the first failure code is retained.

Shell pattern

When a command can fail while still emitting useful JSON, capture stdout and exit status separately. That way the report is still available for triage.

Keep the report and the status code

status=0
lev check --json > check.json || status=$?
printf 'exit=%s\n' "$status"
jq -r '.schema' check.json

Example result

exit=1
lev.cli.check/v1

Troubleshooting

Read the table left to right: symptom, likely cause, then the narrowest useful next command. That order usually settles the problem faster than bouncing between sync, build, and cache commands.

Symptom	Likely cause	First command
"No Lake project found"	The current directory is outside any Lake root.	`lev --project PATH ...` or `cd` into the project.
Lock drift reported in CI	A Lakefile, toolchain, or manifest change was committed without `lev lock`.	`lev lock --check` locally, then `lev lock` if the change was intended.
A transitive revision looks surprising	Different parents may have recorded different requests, or the selected manifest may be stale.	`lev inspect dependencies`
Offline run fails	A required toolchain or dependency object is not local yet.	`lev sync` once with network access, then retry `--offline`.
Toolchain cannot be resolved	A channel or alias needs resolution and no elan fallback is available.	`lev inspect environment`, then `lev toolchain install SELECTOR`.
Builds slow on shared storage	Project and `.lake` writes are landing on a networked filesystem.	`LEV_CACHE_DIR=.../scratch lev --local build`
Unexpected cache size	Old artifacts accumulated across toolchains and projects.	`lev cache status`, then `lev cache gc --max-age-days N` before `--apply`.
Suspected cache corruption	Interrupted writes or external modification of store contents.	`lev cache verify` reports integrity problems but does not repair them. Remove and repopulate the affected cache data before retrying.

When a delegated Lake or Lean error is the problem, re-run with -v to separate lev's orchestration decisions from the child command's own output before filing an issue against either tool.

Use lev with a coding agent

The repository includes a project skill covering environment reproduction, dependency changes, import minimization, Lean source quality, and worktree safety.

Agent instruction

Read .agents/skills/lev/SKILL.md before working on this Lean project.

Agents that support skill discovery can load it directly. For other tools it remains ordinary, reviewable project documentation that tells the next tool how this project expects to be handled.