Concepts and glossary
Audit structure
| Term | Meaning |
|---|---|
| Project | One repo in one org. Both Security and Bugs live here, and so do the findings. |
| Audit profile | security or bugs. Owns methodology versions and campaigns. |
| Methodology | An immutable config version: buckets, passes, scopes, prompt sections. |
| Campaign | One audit of a branch and commit, pinned to one profile and one methodology version. |
| Slice | The smallest job: one pass × one bucket × one model. Pending, running, completed, or failed. failed is retryable: invalid runner output does not count as coverage. |
| Lease | A time-boxed claim on a slice. If it expires, the slice goes back on the queue. First valid accepted result wins. |
| Report | One observation parsed out of a model's stdout. |
Finding identity
| Term | Meaning |
|---|---|
| Finding | The de-duplicated issue the team triages. Project-wide, not per campaign or branch. |
| Fingerprint | A stable hash of the scrubbed report. Used to recognize the same issue again. |
| Alias | Another fingerprint that was judged to be the same finding (wording drifted, files renamed). |
| Sighting | "We saw this finding in this campaign, on this branch, at this commit." Comparisons use sightings. |
| Keeper | The finding that stays after a merge. |
| Soft merge | The losing finding is pointed at the keeper, not deleted. |
A finding can show up in both profiles and on several branches. It still has one triage status. bucket_id is first-discovery provenance, not a merge boundary. Equivalent reports from different models or buckets can merge. A compound report that covers two or more existing findings (same files, broader root-cause text) is attached to those findings instead of creating a combined one, and those parts are recorded as distinct so a later pass does not fold them back together. Related pairs that do not auto-merge appear on GET /v1/projects/:id/findings/merge-suggestions.
Identity is decided on arrival and re-checked afterwards. Two models can describe one root cause differently enough that neither report matches the other when it lands; once both findings hold their reports, the pair can become an obvious duplicate, and the later of the two is merged into the keeper then. Triage follows the keeper, and the merged-away fingerprint keeps resolving to it.
Campaign comparison
| Term | Meaning |
|---|---|
| Baseline | The "before" campaign. Named explicitly, or the previous one. |
| New | Sighted now, not in the baseline. |
| Resolved | Sighted in the baseline, not now. Do not trust this while slices are still running. |
| Carried forward | Open in both. |
| Gate | A cheap pass / fail / pending read for CI. CI does not run models. |
Fixes and retests
| Term | Meaning |
|---|---|
| Fix record | Description, PR, ticket, and one or more commits. |
| False-positive record | Reason, who decided, optional commit it applies through. |
| Retest campaign | Runs the finding's bucket and the passes that match its files. |
| Fix verification | confirmed (covered retest did not reproduce it) or regressed (it came back). |
Who does what
| Term | Meaning |
|---|---|
| Server | Prompts, parsing, fingerprints, de-duplication, triage, storage. |
| Agent | Local process: git metadata, claim, run a command, upload stdout. |
| Runner | The command bound to a model code. Reads a prompt file, writes marker-delimited JSON. |
| Artifact | Stored prompt, output, or stderr, for provenance. |
See campaigns, the runner contract, or the API.