@applesnort/crosscheck 0.2.2 → 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,7 +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 | 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
@@ -246,7 +381,80 @@ in and has to be killed to recover it.
 npm test   # 183 tests, no dependencies
 ```
 
-## Adding a lens
+## Adding your own lenses
+
+Lens sources layer, in increasing precedence:
+
+1. the lenses packaged with crosscheck
+2. `./lenses` or `./.crosscheck/lenses` in your project, if present
+3. anything named by `--lenses dir,dir` or the config's `lenses` key
+
+A later source **adds** to the earlier ones. A lens whose `name` matches an
+earlier one **overrides** it, and the override is printed — so customising the
+stock `check` costs one file rather than forking all five and losing upstream
+changes. `--no-builtin` drops the packaged set entirely.
+
+```bash
+mkdir -p .crosscheck/lenses
+$EDITOR .crosscheck/lenses/chaos.md
+npx @applesnort/crosscheck lenses     # what resolved, and from where
+```
+
+A lens is a markdown file: five frontmatter keys, then the prompt.
+
+```markdown
+---
+name: chaos
+summary: adversarial user trying to break the flow
+when: [**/*.{js,jsx,tsx,vue}]
+owns: states reachable by misuse — double-submit, back button, hostile input
+not-owns: correctness, security categories, architecture
+---
+
+# Lens: chaos
+
+You are trying to break this, not review it. ...
+
+Findings only: `file:line — SEVERITY — issue — fix`. SEVERITY is BLOCK, FIX, or
+CONSIDER. If nothing here can be broken, reply exactly `NO FINDINGS`.
+```
+
+`when` routes it — a lens whose globs match nothing in the target is skipped, with
+the reason printed. `not-owns` is required: a lens that never declines dilutes the
+signal everything else depends on. The body should end by restating the output
+contract, since that is what the parser expects back.
+
+`crosscheck lenses` prints the resolved set with each lens's origin and globs,
+which is the fastest way to see why something did or did not run.
+
+### Local lenses stay local
+
+Nothing in `./lenses` or `./.crosscheck/lenses` is packaged, uploaded, or shared
+by crosscheck. Those files are read off your disk at dispatch time and go nowhere
+else. That has two practical consequences worth knowing before you write any.
+
+**A local lens can be as specific as you like.** The packaged lenses are
+deliberately generic, which also makes them shallow: they cannot know your
+storage conventions, your framework's failure modes, the mistake your team makes
+every quarter, or the review standard one colleague applies better than anyone
+else. A lens that encodes any of that will outperform a generic one on your
+codebase, and it belongs in your repo rather than upstream. The useful ones
+usually aren't portable.
+
+**Distribution is where obligations start, and you are not distributing.** If you
+adapt a lens from a published persona set, a standards document, or a colleague's
+review checklist, keeping it local puts you in the same position as any private
+note-taking. Those materials often carry licences requiring attribution — the UK
+government's accessibility personas are published under the Open Government
+Licence, for one — and that condition attaches when you *publish* a derivative,
+not when you run one. If a local lens later becomes something you want to share,
+that is the moment to check what it derives from and credit it.
+
+The corollary: a lens holding a named individual's review preferences, or a
+description of an unreleased product, is a local lens permanently. Publishing it
+shares something about a person or a project, not just a prompt.
+
+## Writing a good lens
 
 A lens earns its place by finding what the others miss. Give it a remit narrow
 enough that it declines most changes, state what it does *not* own, and make it name