# Work with the ratchet

Record improvements, approve new exceptions, and keep coding agents from gaming the limits.

Commands on this page run `sprawl-guard` as installed with Cargo or Homebrew. If you installed Sprawl Guard with pnpm, npm, or uv, replace `sprawl-guard` with `pnpm exec sprawl-guard`, `npm exec -- @kpozin/sprawl-guard`, or `uv run sprawl-guard`.

The ratchet file, `sprawl-guard.ratchet.toml`, records each violation you accepted. The size it had
when you recorded it is its ceiling. `sprawl-guard check` fails when a recorded violation grows past
its ceiling, and also when it shrinks below it, so that the file always matches the repository.
Commit ratchet changes together with the source changes that caused them.

This ratchet file records a 640-line parser and a directory with 14 source files, both over the
default limits, and a 2 MB image over a configured
[byte limit](/sprawl-guard/reference/configuration.md#limits):

```toml title="sprawl-guard.ratchet.toml"
#:schema https://kpozin.github.io/sprawl-guard/schemas/v1/sprawl-guard.ratchet.schema.json
schema_version = 1

[[files]]
path = "src/parser.rs"
role = "production"
max_lines = 640

[[directories]]
path = "src/handlers"
role = "production"
group = "source"
max_direct_files = 14

[file_sizes]
"assets/hero.png" = 2000000
"models/weights.bin" = { max_bytes = 50000000, storage = "lfs" }
```

Each entry's `role` says whether the production or the test limit applies. A directory entry's
`group` names the [language group](/sprawl-guard/reference/configuration.md#language_groupsname) whose
files it counts. Languages outside custom groups use `source`, except literate languages such as
Markdown, which use `documentation`. Each `file_sizes` entry maps a path to the size in bytes of any
file, source or not, under the limit from `max_bytes_per_file`. A file in Git LFS has a table with
`storage = "lfs"` instead, under the limit from `max_bytes_per_lfs_object`. It records the content
size, so the entry doesn't change when Git LFS downloads the file. When a file moves into or out of
Git LFS, its old entry becomes stale. Sprawl Guard versions without byte limits reject a ratchet
file that has `file_sizes` entries. The commands below write the file. Edit it by hand only to
resolve a merge conflict.

## Record an improvement

After you shorten a file or move files out of a crowded directory, the check reports the ratchet
entry as stale. Preview the change, then write it:

```sh
sprawl-guard tighten
sprawl-guard tighten --write
```

`tighten` lowers each ceiling to the new size, or removes the entry when the file or directory is
back within its limit. It never raises a ceiling or adds an entry.

## Approve a new violation

When a file or directory has to exceed its limit for now, preview and write an entry for it. Pass
the file or directory that is over its limit:

```sh
sprawl-guard update src/parser.rs
sprawl-guard update src/parser.rs --write
```

`update` adds entries for new violations but leaves existing ceilings alone. To let a recorded
violation grow, add `--allow-increases` to both commands. The preview marks each raised ceiling
with `! raise`.

For a permanent exception, such as a vendored file, set a higher limit with an
[override](/sprawl-guard/configure-checks.md#make-exceptions) instead. An override states its reason
in the configuration.

## Resolve a merge conflict in the ratchet file

Keep the entries from both sides, and where they disagree, keep the higher ceiling. Then run
`sprawl-guard tighten --write` to lower each ceiling to the size of the merged code, and run
`sprawl-guard check`. If both branches grew the same file or directory, approve the combined size
with `sprawl-guard update PATH --allow-increases --write`.

## Guide coding agents

Coding agents tend to satisfy a size limit by moving code into catch-all files or by raising the
limit. Sprawl Guard comes with an [agent skill](https://agentskills.io) that tells an agent how to
run the check and how to fix each kind of failure. The npm package includes it at
`node_modules/@kpozin/sprawl-guard/skills/sprawl-guard/`, and the
[GitHub repository](https://github.com/kpozin/sprawl-guard/tree/main/skills/sprawl-guard) has it
too. Copy the `sprawl-guard` directory to where your agent loads skills, such as `.claude/skills/`
for Claude Code.

If your agent does not support skills, copy the directory to `skills/sprawl-guard/` in the
repository instead, and add a line like this to the repository's agent instructions file:

```md
Before declaring work complete, follow skills/sprawl-guard/SKILL.md.
```
