Agent context files

php artisan sqlens:agent-rules

A linter tells an agent it was wrong after it wrote the migration. sqlens:agent-rules tells it the rule beforehand, by writing the project's active rule set into the context files the coding agents in the repository already read.

That "active" is the whole point. The artifact describes the rules this project actually runs — its level, its categories, its stability tiers, its engine — not the full catalog. An agent handed every rule SQLens can express would be told about checks that will never fire here.

Targets

php artisan sqlens:agent-rules --target=claude
php artisan sqlens:agent-rules --target=cursor
php artisan sqlens:agent-rules --target=copilot
php artisan sqlens:agent-rules --target=all      # the default

Each target writes to the context file that agent reads, at the path that agent expects.

--target=all means all agent targets — it iterates that family and nothing else. Other artifact families exist on the same registry and write elsewhere; all picking them up would put this package's artifacts into a file that belongs to something else.

--output= redirects a single target's artifact to a path of your choosing. It is refused with more than one target, because one path cannot hold two files.

It writes into a marked block

The command does not own your context file. It writes a marked block into it and leaves everything around that block alone, so a file you also maintain by hand keeps every line you put there.

Each marker line carries the generator version and a hash of the rule catalog. Those are two fields answering two different questions — did the artifact shape change and did the rules move — which is why the generator version is bumped when the format changes and not when a rule does.

--check is for CI, and the case it exists for is the missing file

php artisan sqlens:agent-rules --check

Non-zero when any artifact is out of date. Writes nothing.

Two states count as a deviation, and the second is the one worth stating: a file whose marked block is stale, and a file that does not exist at all. The missing file is the commonest state in a consuming project's pipeline — a fresh clone, or a target nobody ever generated — and it is the easiest to answer wrongly, because the write path would simply create it. A --check that quietly created what it was asked to verify would make the promise worthless exactly where it is supposed to hold.

--dry-run prints what would be written without touching a file.

Check and write are one code path. The exporter is handed no filesystem and the writer returns content instead of writing it, so the only difference between the two modes is whether the bytes reach the disk. Two paths would agree until they did not, and the disagreement would be found by somebody whose green --check was wrong.

No database, ever

This command opens no connection. It works from rule metadata and configuration, so it runs in a fresh clone, in a CI image, and offline.

That has a consequence worth naming: a missing connection is not a reason for an undetermined result here. There was never a question left open — the artifact describes which rules are active, and that is a fact about your configuration rather than about your database.

--connection= is still accepted, and it selects which engine to describe. A project on PostgreSQL should not hand its agent the MySQL rule set.

Determinism

The artifacts are byte-for-byte reproducible: the same configuration produces the same file, on any machine and under any locale.

That is a survival condition rather than an academic one. A generator that leaked a timestamp, an absolute path or a locale-dependent sort would produce a diff on every run; the committed artifacts would then read as noise, and a team would switch the command off. At that point nothing regenerates, and every other guarantee in the chain is worth nothing.

Wiring it in

Generate once, commit the result, and hold it with --check in the same job that runs the linter:

php artisan sqlens:agent-rules --check

When a rule set changes — a level raised, a category added, a preview rule adopted — that check goes red and the fix is to regenerate and commit.