@applesnort/crosscheck 0.3.0 → 0.6.0

package/README.md

@@ -19,7 +19,42 @@ or your own wrapper. crosscheck owns prompt construction, routing, fan-out, dedu
 and output; you own the model. `--dry-run` prints the roster and prompts without
 spawning anything.
 
-No dependencies, no install step, 183 tests.
+No dependencies, no install step, 267 tests.
+
+## Getting set up
+
+```bash
+npx @applesnort/crosscheck init
+```
+
+Scaffolds `.crosscheckrc.json`, a `.crosscheck/lenses/` directory with a note on
+writing lenses, and a `.github/workflows/crosscheck.yml` that reviews each pull
+request, uploads SARIF to code scanning, and posts a summary comment. Existing
+files are left alone unless you pass `--force`.
+
+Set `exec` to whatever runs your model, then:
+
+```bash
+crosscheck run --diff --dry-run
+```
+
+## In CI
+
+The scaffolded workflow reviews the diff against the base branch, and does two
+things with the result:
+
+- **SARIF to code scanning** — per-line annotations in the Files changed view,
+  which is where a reviewer is already looking.
+- **A summary comment** via `--comment-file`, carrying what per-line annotations
+  cannot: which lenses were skipped and why, which died, what the baseline
+  suppressed, and how many findings verification refuted.
+
+The comment embeds a marker so later runs **edit** it rather than stacking. A pull
+request with eleven bot comments gets muted, and a muted reviewer finds nothing.
+
+The workflow checks out with `fetch-depth: 0`, because reviewing a diff needs the
+base commit. crosscheck itself never talks to a model — supply whatever your
+`exec` command needs via the workflow's `env`.
 
 ## Configuration
 
@@ -50,7 +85,9 @@ and an unrecognised key is an error rather than a silent no-op, because a
 misspelled `exec` that quietly does nothing is worse than a crash.
 
 Accepted keys: `exec`, `lenses`, `concurrency`, `only`, `skip`, `mixed`, `out`,
-`sarif`, `baseline`, `overlap`. Keys beginning `//` are treated as comments.
+`sarif`, `baseline`, `overlap`, `preflight`, `context`, `verify`, `since`,
+`max-dispatches`, `no-cache`, `cache-dir`, `comment-file`. `exec` accepts a string
+or a per-lens map. Keys beginning `//` are treated as comments.
 
 > **v0.x — the API is unstable.** The CLI commands and the `lib/` exports may
 > change shape before 1.0. Pin an exact version if you depend on it.
@@ -59,6 +96,100 @@ Accepted keys: `exec`, `lenses`, `concurrency`, `only`, `skip`, `mixed`, `out`,
 > similar to the (abandoned) `cross-check`. Installed, the command is
 > `crosscheck`.
 
+## Reviewing a change, not a directory
+
+Nobody reviews a whole tree — they review a diff. Auditing paths makes cost scale
+with repository size instead of change size, and re-reads code nobody touched.
+
+```bash
+crosscheck run --diff             # everything uncommitted
+crosscheck run --staged           # what you are about to commit
+crosscheck run --since origin/main   # the branch, for a PR
+```
+
+Each lens is told which lines moved:
+
+```
+- src/a.js  (changed lines: 5-27, 61-84)
+```
+
+Ranges are widened by `--context` lines (20 by default) so a lens sees the code
+around a change, and the prompt is explicit that changed lines are the *priority*
+rather than the boundary — a defect elsewhere that the change causes or depends on
+is still worth reporting, while a pre-existing one it never touches is not what the
+review is for. An empty diff exits cleanly rather than falling back to reviewing
+everything.
+
+## Verification is on by default
+
+`BLOCK` findings are refuted before they are reported. Each one gets a skeptic that
+is handed **the file** rather than the finding's account of it, told to default to
+refuted when it cannot name a concrete trigger. Refuted findings are removed and
+**the count is always printed, including zero** — a finding that vanished without a
+number is indistinguishable from one that was never found.
+
+```
+crosscheck: verifying 3 finding(s)
+  ✓ confirmed src/session.js:44
+  ✗ refuted   src/cache.js:12
+Refuted in verification: 1.
+```
+
+False positives cost more than misses: a panel that cries wolf twice stops being
+read, and its true findings go unread with the rest. `--verify` extends the pass to
+every severity; `--no-verify` skips it, at that cost.
+
+A verifier that fails to run is **not** treated as agreement — the finding stands
+and the failure is reported.
+
+## Your own gate, before anything is dispatched
+
+```json
+{ "preflight": "scripts/check-clean-worktree.sh" }
+```
+
+A non-zero exit aborts before a single model call. That lets a project enforce a
+rule crosscheck knows nothing about — data classification, branch policy, a clean
+worktree — without the rule having to exist upstream.
+
+## Cost control
+
+A tool that costs real money per run gets switched off, and a switched-off tool
+finds nothing.
+
+**A cheap lens should not pay for an expensive model.** `exec` may be a map:
+
+```json
+{
+  "exec": {
+    "default": "claude -p",
+    "conventions": "llm -m claude-haiku-4-5"
+  }
+}
+```
+
+Precedence is the lens's own `exec` in its frontmatter, then the map entry, then
+`default`. A rostered lens with no command anywhere fails loudly and names itself
+— it is never quietly skipped.
+
+**Unchanged files are not re-reviewed.** Results are cached under
+`.crosscheck/cache`, keyed on the lens definition, the files, and their contents.
+The definition is part of the key deliberately: editing a lens must invalidate its
+results, or you would be served answers from the previous prompt with no way to
+tell. `--no-cache` disables it, `--cache-dir` relocates it. A failed lens is never
+cached, so it is retried rather than permanently wrong.
+
+**`--max-dispatches N` caps the run, and says what it dropped:**
+
+```
+crosscheck: BUDGET REACHED — 3 lens(es) not run: check, security-check, taint
+```
+
+The unit is dispatches, not dollars. crosscheck cannot see tokens or cost —
+`--exec` is an arbitrary command — so a monetary budget would be a number invented
+from nothing. Truncation is always named, because a run that quietly stopped early
+looks exactly like a run that found nothing.
+
 ## SARIF output
 
 Findings are emitted as [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html),
@@ -200,8 +331,11 @@ lib/
   prompt.mjs            lens prompt construction
   run.mjs               roster planning and bounded fan-out
   config.mjs            .crosscheckrc.json discovery and validation
-bin/crosscheck.mjs      CLI: run | lenses | report | sarif | baseline |
-                             overlap | calibrate
+  target.mjs            diff parsing, changed line ranges
+  cache.mjs             content-addressed result cache
+  comment.mjs           pull-request summary comment
+bin/crosscheck.mjs      CLI: init | run | lenses | report | sarif |
+                             baseline | overlap | calibrate
 fixtures/calibration/   planted defects, ground truth, and the calibration record
 fixtures/deception/     20 modules that look safe and are not, or the reverse
 PROVENANCE.md           where all of this came from