# Check reference

```sh
.repo-standards/runtime/node_modules/.bin/repo-standards check --json
```

This page is the contract for `check`: what runs, its report, how it detects
checks that write, and its failures. [Run the adopted checks](https://repo-standards.com/docs/guides/run-checks/)
covers using it.

`check` runs every check of the last complete adoption against the current
working tree and reports each result. Use it between runs, for example to
check finished work against the adopted standards before delivering it. It
runs no fix and asks for no confirmation: the adoption disclosed and ran
these checks. It records nothing, so a passing `check` does not change the
adoption's evidence or claim continuing compliance. `--project <directory>`
selects another Git working tree.

## What runs

`check` reads the committed product state and retained inputs, verified
against the integrity lock, and nothing else: no standards source, registry or
network connection is needed. It runs the checks of the retained resolved
selection exactly as a run does, as the [script protocol](https://repo-standards.com/docs/reference/script-protocol/)
describes:

* It first probes the prerequisites of every check. Any missing executable or
  incompatible version fails `check` with `PREREQUISITES_BLOCKED` before any
  check runs, listing every probe in the diagnostic's `details`.
* Each check receives the same `repo-standards/operation/v2` input as in a run,
  with the selection's standards, profile and platform, every active resolved
  declaration,
  its declaration's allowed targets, and `overwriteAllowed: false`, except that
  it carries `invocation: "check"` where a run's carries `"run"`. A source may
  use that field to skip rules that only hold within a run. It uses the same
  arguments, working directory, timeout and output limits.
* Declarations run by ID and checks in their listed order.

Unlike a run, `check` runs every check whatever earlier checks returned, so one
invocation reports them all. The working tree need not be clean; uncommitted
work is what it checks.

## Report

With `--json`, `check` prints one `repo-standards/check/v3` object:

```json
{
  "format": "repo-standards/check/v3",
  "outcome": "failed",
  "selection": {
    "cli": { "package": "@lutzseverino/repo-standards", "version": "10.0.0" },
    "standards": {
      "repository": "https://github.com/alice/standards",
      "version": "v1.0.0",
      "commit": "40-character-resolved-commit-sha"
    },
    "profile": "work",
    "platform": "github"
  },
  "checks": [
    {
      "declaration": "project-readme",
      "id": "headings",
      "status": "failed",
      "message": "README.md has no Usage heading.",
      "error": null,
      "rules": ".repo-standards/rules/project-readme.md",
      "stdout": ".repo-standards/local/checks/0.stdout",
      "stderr": ".repo-standards/local/checks/0.stderr"
    }
  ]
}
```

Each entry of `checks` names its declaration and check `id`, in execution
order. `status` is the check's result status, `passed`, `failed` or `blocked`,
with its `message`, or `error` when the check did not return a valid result: a
nonzero exit, signal, timeout, spawn failure, excess output or invalid protocol
output. `error` is then the execution error code, such as `PROTOCOL_ERROR` or
`NONZERO_EXIT`, and `message` says so; otherwise `error` is null. The `rules`
of a check that did not pass name its declaration's
[installed rules](https://repo-standards.com/docs/reference/rules/); they are null for a passed check or a declaration
without rules. `stdout` and
`stderr` name the check's captured output streams, which the next `check`
replaces. `outcome` is `passed` only when every check passed, including when
there are none.

Without `--json`, `check` prints a readable summary: the selection, with its
profile and platform, and the count
of each status, then one line per check with its status, declaration, ID and
message, then its installed rules and the paths of its output logs when it did
not pass. Line breaks in
a message or the profile become spaces in the summary, so each check and the
header keep one line; the JSON report keeps both values as they are.

`check` exits 0 when every check passed and 1 when any check failed, was
blocked, or did not return a valid result. A failure to run the checks at all
also exits 1, with `valid: false` and the diagnostic in `errors` under `--json`,
or the diagnostic on stderr without it; invalid usage exits 2.

## Checks that write

The script protocol requires checks to leave project content unchanged, and
`check` cannot stop a trusted script from writing. Its guarantee is bounded by
what a run observes during its check interval. Before the prerequisite probes,
and after the probes and each check, it makes that observation:

* tracked and non-ignored untracked content, the declarations' named targets,
  their ancestors and explicit directory trees, and the ignore inputs and
  observation settings, as described under
  [observed adoption scope](https://repo-standards.com/docs/reference/script-protocol/#observed-adoption-scope), with
  the same limits;
* the inventory of the durable product state and retained inputs, other than
  the ignored `local`, `cache` and `runtime/node_modules` directories;
* the commit HEAD resolves to;
* the index's staged entries and the paths it marks skip-worktree or
  assume-unchanged.

Any difference from the first observation stops `check` with `CHECK_MUTATION`,
naming the probe or check and each changed path in the message and in
`details.paths`. Changes to HEAD and the index are named `@git/HEAD` and
`@git/index`, and changes to ignore inputs and settings are named as in a run.

`check` fails closed when the observation cannot be made. An observation after
a probe or check that cannot be made, or finds the project unsafe, is a change
that probe or check made. Examples are an unreadable index, a target replaced
by a symbolic link, nested Git metadata, or unsafe product state. It stops
`check` with `CHECK_MUTATION`: `details.cause` holds the underlying failure's
code, when it has one, such as `PROJECT_READ` or `EACCES`, and its message, and
`details.paths` holds the paths a product diagnostic names, `@git/index` for an
unreadable index. The same failure in the first observation, before any probe
or check, fails `check` with that diagnostic itself.

No later check runs after a change, and the changes are preserved for review:
`check` restores nothing. Changes outside that observation are not detected.

A probe or check that leaves its process group running stops `check` with
`AUTHOR_PROCESS_ACTIVE`. `check` does not stop or record the group; stop it
before running any command again. When group inspection fails, `PROCESS_STATE`
blocks further checks and identifies the cause, rather than confirming a live
group. The system `ps` utility must be on `PATH`; if it is missing, provide it
(`procps` on Debian/Ubuntu, including minimal containers) and retry. A failing
`ps -axo pgid=,stat=` reports its available spawn error, exit status or signal,
and diagnostic stderr. JSON diagnostics retain those details alongside the
actor, group and original probe or check process outcome. Successful check
reports are unchanged.

`check` itself writes only two things: its output logs, under the ignored
`.repo-standards/local/checks/`, and, while it runs, a worker registration in
Git's directory. Its logs replace the previous invocation's. It keeps a check's
logs after observing the project. When the check changed the project, it
still keeps them where it can. It never changes committed content, HEAD or the
index.

## Failures before any check runs

`check` fails with the diagnostics other commands use:

* `CLI_PIN_MISMATCH` under a CLI other than the pinned one, as for
  [`status`](https://repo-standards.com/docs/reference/adoption-run/#fresh-checkout-and-source-disappearance), before
  reading any record. Only the pin is read for it.
* `GIT_VERSION_UNSUPPORTED` under Git older than 2.32, as for
  [`inspect`](https://repo-standards.com/docs/reference/inspection/), after the pin and before reading records or
  observing the project, so Git never follows a symbolic `.gitignore` whose
  referent the observation does not bind. Before it, Git only locates the
  project root and the run record.
* `RETIRED_FORMAT` for older committed records or archived reports other than
  `repo-standards/run/v6` ones,
  `RETIRED_RUN` for an older active run record, or `NEWER_FORMAT` for a higher
  version of a known record format. Malformed format identities in committed
  records `check` reads fail integrity validation, including a same-prefix
  version that is not `vN`.
* `ACTIVE_RUN` while an adoption run is active or incomplete, or another
  adoption command is executing. Complete or abandon the run first.
* `NO_SELECTION` when no complete adoption is recorded.
* `STATE_INTEGRITY` when the committed product state or retained inputs do not
  match the integrity lock.

Any other failure, such as a filesystem error while registering in Git's
directory, is reported as `CHECK_FAILED` with its message: under `--json` as a
`valid: false` diagnostic, and otherwise on stderr.
