| name | checking-drift |
| description | Use when a criv command fails or prints a diagnostic, when reading a criv error code, fix line, or next command, or when validating that documents, ADR metadata, wiki-links, source references, and generated state still match the code. |
Checking drift
Drift is the gap between what a document claims and what the code does. criv check is the whole verdict: the vault is green when the command prints
criv check: ok. Green is the completion criterion for every criv workflow.
Getting to green
- Run
criv watch --once to refresh .criv/state.json. A stale state
produces diagnostics that describe the previous code.
- Run
criv check and read every diagnostic. Each one carries a fix: line,
and the run ends with one next: command. Use criv check --filter <text>
to narrow the output while investigating one failure, and criv check --format json when an agent or a script consumes the diagnostics.
- Run the command the
next: line names. It is criv check --fix when criv
can repair the vault itself.
- Run
criv enforce --stage ci when the change touches ADR-governed source.
Repeat until a run that included your change comes back green.
Reading a diagnostic
A diagnostic names a severity, a code, a file, and a message, and it carries a
fix: line under it:
error[unresolved-governs] docs/adr/0007-example.md: governs glob `src/old.rs` matches no source files
fix: Run `criv adr reconcile-sources --base <ref>` for a rename, or add a successor ADR for a deletion.
next: apply the fixes above, then run `criv check`
Run the fix: line rather than inventing a command. The next: line at the end
names the one command to run after the repair. criv check --format json
carries the same code and fix as fields.
Correct the file the diagnostic names, or correct the code that made the claim
false. Treat a diagnostic that misreads the repository as a criv bug worth
reporting.
A governs or policy diagnostic names an ADR. Run criv check --filter ADR-NNNN
to isolate its current diagnostics. The writing-decisions skill owns the ADR
side of that fix.
Reading a failure
Some failures that are not diagnostics also carry a code and a repair. Not all
of them do: a failure with no defined recovery reports prose only. When a code
is present it looks like this:
criv: [not-a-vault] not a criv vault: no criv.toml in /work/other-repo
fix: criv init
Key recovery on the code when there is one. These are the coded failures:
| Code | Meaning |
|---|
not-a-vault | The working directory holds no criv.toml. Check the directory before running criv init. |
check-failed | criv check found errors. The diagnostics above it say which. |
policy-violation | An ADR policy pattern matched. Change the code, or supersede the ADR. |
import-policy-violation | An import broke a rule in criv.toml. |
adr-immutability-violation | An accepted ADR changed. Restore it and write a successor. |
enforcement-failed | Validation errors blocked the stage. Run criv check. |
vault-outside-git-root | The vault is not the root of the Git worktree. Run criv from the worktree root. |
adr-id-exhausted | No free four-digit ADR id remains. |
Exit codes are the fast signal: 0 succeeded, 1 the command failed, 2 the
command line was wrong.
Machine-readable runs
criv check --format json — diagnostics with code, path, line, message, and fix.criv enforce --stage ci --format json — one object with the counts, the violations, the failure code, and its fix.criv watch --once --format json — the snapshot, the counts, and the next command.criv --usage-json — the whole command tree, with every flag, choice, and default.
Never guess a flag. Read it from criv <command> --help or from
criv --usage-json.
