reticle hunt

Aggregate many crawl reports into one false-green rate across already-merged changes.

reticle hunt is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by reticle_crawl) and it turns the pile into the one number the core claim needs: across N already-merged, already-green changes, how many carried a candidate false green?

npx @reticlehq/server hunt <dir-of-crawl-reports>

No control arm is needed. Those changes shipped, so the counterfactual is already established.

Arguments

Argument	Type	Default	What it does
<dir>	string, positional, required	none	Directory of *.json crawl reports. Each file is one crawl over one checkout

Each input file is read for label (falling back to the filename), anomalies[], and stepsRun.

What it prints

One reticle_hunt line with the summary:

Field	Meaning
runs	Report files read
runsWithCoverage	Runs that drove at least one control. The only honest denominator: a run that drove nothing is not evidence of cleanliness
runsWithContradictions	Runs with at least one cross-channel contradiction
contradictions	Total contradictions. The kinds are ui-advanced-request-failed, signal-contradicted, response-ignored, duplicate-request, request-never-settled, failure-misattributed
singleChannelFaults	Everything else: console errors, failed requests, dead controls. Context, not the claim
byKind	Counts per anomaly kind
flagged	The labels with contradictions, so each can be confirmed by hand
headline	A sentence phrased so it cannot overstate itself. It says “candidate”, because every flag still needs manual confirmation

Exit codes

Always 0. A read failure is logged as reticle_hunt_failed. Omitting the directory is a usage error:

{"t":"2026-08-14T19:38:47.116Z","event":"reticle_usage_error","message":"usage: reticle hunt <dir-of-crawl-reports>"}

That path exits 1.

Worked example

for sha in $(git log --format=%H -n 30 main); do
  git checkout "$sha" && npm run dev &
  # drive reticle_crawl over the app, write the JSON:
  # .../reports/$sha.json
done
npx @reticlehq/server hunt ./reports