ctrlrun scan: the command that says what is not covered

[arpanghoshal]

There was no command that answered is CTRLRun on this path at all? ctrlrun verify answers
whether the guarantee holds in a setup. The gateway covers what reaches it. The decorator covers
what somebody decorated. The call nobody decorated was invisible.

ctrlrun scan reads a Python tree and a policy document as text and reports the consequential
call sites and policy entries that are not covered.

$ ctrlrun scan --path src/ctrlrun
unprotected_call (77)
  ...
undetermined (10)
  ...
files read: 44   excluded: 0   findings: 77   suppressed: 0   undetermined: 10
vocabulary: 25 verbs   policy: not read — the two policy checks did not run

This is a finder, not a proof. It read 44 files and could not determine 10 calls;
it did not read your dependencies, your other services, or any tool server behind a gateway.
A clean scan means nothing was found where it looked.

How this was built

docs/SPEC-scan.md landed first and its tests were red before any of it existed. Five sections
of the specification now carry a paragraph beginning Found by — each a defect in the design
that writing the tests or running the command exposed, corrected in the document rather than
worked around in the code:

§	What was wrong	How it was found
§3.2	one rule could not separate stripe.refunds.create from refunds_report; both contain refunds	writing T197
§3.2	execute in the vocabulary — cursor.execute was 90 of 208 findings against this repo's own src/	running it
§3.4	a policy action whose decorator passes effect= reported as missing one; it flagged examples/double-refund, teaching a reader to add a key they already had	running it
§4.1	every unresolved receiver filed as undetermined: 216 entries, of which two were the dynamic dispatch the category exists for. Now 10	running it
§9.1	undetermined listed as a FindingKind while §4.1 said in the same document that these are not findings	writing T198 and T204

The three rules it turns on

• It never imports the tree it reads (§2.1). ast.parse and nothing else. T194 is a fixture
  whose import writes a sentinel.
• It adds no entry point (§9.2), stated as a rule and not as a fact about this
  implementation. The tempting version builds an Action per call site and asks the policy what
  would happen — a principal invented by a tool from a source file. T205 patches Control and the
  store to raise on any use and requires the scan to finish.
• A clean scan is not a verdict (§4), and the report says so on every run, including the run
  with no findings. No score, no percentage, no badge: a number that improves when the vocabulary
  is shortened is a number that will be.

Suppression is the one place this could have become a flag that relaxes a check. It does not: the
reason is mandatory, a suppressed finding stays in the report and in the totals, and the exit code
does not move.

Mutation table

Each mutant killed by the test named for it.

Guard	Mutation	Killed by
§3.3 context is not coverage	treat with as covering	T196 + 6
§3.6 a suppression needs a reason	drop and reason	T201
§7 an unparseable file is a finding	skip the file	T199, T204
§3.4 the decorator's own effect	drop the exemption	T207
§4.1 a call on an expression	file it as undetermined	T208
§4.5 the limits sentence	omit it	T203
§3.2 the plural rule	allow plurals in compounds	T197

Scope

Not a v0.6 feature. A subcommand like the operator server: no table, no column, no event type, no
error type, no policy key, no version line of its own. test_T177c holds v0.6's command list
frozen and names what came after separately, which is where scan sits — so SPEC-v0.6.md §9.4's
claim that the milestone grew no command stays literally true.

No authorization, identity, delegation or gateway code is touched, so the independent-review rule
does not apply; the reviewer's question here is the design, and the Found by paragraphs are the
record of what has already changed under it.

Green: full suite 4065 passed / 45 skipped · mypy --strict · ruff · ruff format · docs
lint 185 documents 0 findings · links 179 documents 0 broken · CLI reference regenerated.

Follow-up, deliberately not here: no docs-site guide page for scan yet — the CLI reference
and the exit-codes page carry it, and a guide wants a real tree to scan rather than a fixture.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
ctrlrun	🟢 Ready	View Preview	Sep 6, 2026, 7:31 PM

💡 Tip: Enable Automations to automatically generate PRs for you.