Open_Ultra_SAST/.kiro/specs/contributor-scan/requirements.md

Requirements Document: contributor-scan

Introduction

model-grounded-detection built an arbiter and measured it: 41.3% of the corpus reaches model_entailed against the flat IR's 2.2%, and the wired pipeline scores 86.7% pair-correct at 6.7% leak against the LLM hunter's 76.7% / 12.3%, at a fifth of the model calls. All 16 of its tasks are complete.

And the model layer has zero production callers. ousast scan does not use it. Every number above came from a measurement harness, not from the tool. This feature closes that gap and answers the question the maintainer actually posed: a real world tool that helps developers when they want to contribute.

That framing changes the work. A contributor has no labelled function and no declared weakness class — they have a repository they are about to touch. Everything measured so far is function-level pairs, which exercise none of the questions a whole repository asks: which regions to look at, how to rank thousands of candidates, what to spend, and whether a CPG build on a 100k-line tree finishes at all.

Context: brief.md, .kiro/specs/model-grounded-detection/, and the committed measurements 2026-09-08-pipeline-vibe-py.json, 2026-09-08-model-entailment-ceiling-cpg.json.

Boundary Context

• In scope: wiring model/pipeline into ousast scan; region selection from entry points; ranking and budget at repository scale; the performance envelope; running against known-vulnerable checkouts; contributor-facing output; the packaging already built (image, compose, shell wrappers, pyinfra); the deferred memory-family decision; retiring evidence_level.
• Out of scope: new arbiters or families (the three forms exist); prompt optimisation of any kind; building a sandbox (Req 10 of the predecessor stands — adopt, never build); changing the gates.
• Carried forward, not re-litigated: the evidence ladder, the taxonomy, the fact tables, and the finding that the model supplies precision while the LLM supplies recall.

Requirements

Requirement 1: The model layer reaches a user

Objective: As a developer, I want ousast scan to use the model layer, so that the arbiter this project built is something I can run rather than something a harness demonstrates.

Acceptance Criteria

1. When a scan runs with a CPG engine available, the system shall arbitrate its candidate findings through model/pipeline and attach a rung to each.
2. The system shall report model findings alongside the existing pattern and overlay findings, without removing either.
3. When no CPG engine is available, the scan shall behave exactly as it does today and record cpg_unavailable — the model layer is additive, never a precondition.
4. The detection, map and local pair gates shall remain byte-identical to the committed baseline.
5. The system shall expose the model layer's per-rung counts in the scan's own output, so a user can see how much of the result the model arbitrated rather than inferring it.

Requirement 2: Regions come from the code, not from a label

Objective: As a developer scanning a repository, I want the tool to decide what to look at, because I cannot tell it which function is interesting.

Acceptance Criteria

1. The system shall select regions from entry points and reachability rather than from a declared function name.
2. If a region has no resolvable entry point, then the system shall fall back to file-level regions and record that it did.
3. The system shall route each region to the families its shape admits, rather than attempting every family on every region.
4. The system shall not require a function label anywhere on the scan path; that label belongs to pair scoring alone.

Requirement 3: Ranking and budget at repository scale

Objective: As a developer, I want the most useful findings first and a bounded cost, because a repository offers thousands of candidates and my attention and budget are finite.

Acceptance Criteria

1. The system shall order findings by rung first, so what the model established outranks what only the LLM proposed.
2. The system shall apply a total budget across a scan for model calls, not merely the per-region cap of eight the enumerator uses today.
3. When the budget is exhausted, the system shall stop asking and report how many candidates went unjudged, rather than silently truncating.
4. The system shall spend the budget on the highest-ranked candidates first.
5. The system shall report cost and elapsed time for the run.

Requirement 4: It runs on a real repository

Objective: As a maintainer, I want the performance envelope measured on real checkouts, because nothing in the corpus exercises it.

Acceptance Criteria

1. The system shall be measured against at least one known-vulnerable repository checkout at a vulnerable commit, not an excerpt.
2. The measurement shall record CPG build time, scan wall-clock, peak memory, findings by rung, and cost.
3. If a repository cannot be processed within its resource envelope, then the system shall record the reason and the stage it failed at, rather than failing opaquely.
4. The measurement shall state whether the known vulnerability was found, and at which rung.
5. The system shall not require the whole repository to fit in one CPG if that proves infeasible; the fallback shall be recorded and measured rather than assumed.

Requirement 5: Output a contributor can act on

Objective: As a developer, I want to know what is risky and why, in terms I can check.

Acceptance Criteria

1. Every finding shall carry its rung, its witness, and the file and line it concerns.
2. The system shall state plainly what a suspicion means — that the model could not confirm it — so a reader does not treat it as established.
3. The system shall write findings to the writable output location, never into the repository under analysis.
4. The system shall summarise a scan in a form readable without opening a JSON file.

Requirement 6: Packaging is part of the product

Objective: As a developer with nothing installed, I want to run this, because an analyser I cannot start is not a tool.

Acceptance Criteria

1. The system shall run from docker compose with no host dependency beyond Docker, and the image shall be built and verified, not merely defined.
2. The shell wrappers shall make the container invisible for ordinary use, and shall prefer a native install when one exists.
3. The repository under analysis shall be mounted read-only, and findings shall go to the one writable mount.
4. The network shall be off by default and required only for the optional LLM judge.
5. The engine version shall be pinned and checksum-verified in every install path.

Requirement 7: Close the two deferred decisions

Objective: As a maintainer, I want the outstanding decisions closed rather than carried, because each one silently caps what the corpus can tell us.

Acceptance Criteria

1. The system shall either reach the memory family through an adopted execution tier, or record explicitly that C memory-safety is out of scope — 173 of the 176 real-world CVE pairs currently sit idle behind a stub.
2. The system shall retire evidence_level in favour of rung, or record why both are kept.
3. Each decision shall be recorded with its reason where a later reader will find it.

Requirement 8: Honesty disciplines carry forward

Objective: As a maintainer, I want the reporting disciplines that survived the predecessor to survive this one, because each exists due to a specific past error.

Acceptance Criteria

1. The system shall report per-slice numbers with the real-world slice deciding, and refuse a bare aggregate.
2. The system shall publish the overfitting gap beside any headline number, and record it as absent rather than zero when a slice is missing.
3. The system shall pass every prompt and persisted artifact through redaction.
4. The core install shall remain zero-dependency, with the CPG engine, the LLM endpoint and any execution tier optional and degrading to a recorded reason.
5. Any new family-specific code path shall be checked for sibling paths that need the same change, before it is measured — five bugs in the predecessor shared exactly that shape.

Requirement 9: Grow the corpus where the engine can use it

Objective: As a maintainer, I want more real-world and more vibe-code bugs, so the engine is tuned against what developers actually contribute to rather than against 30 pairs of one slice.

Acceptance Criteria

1. The system shall add a PHP/WordPress slice covering plugin and core weaknesses. WordPress plugin CVEs are overwhelmingly injection, XSS and authorization bypass — the families the model layer already arbitrates well — and php2cpg works once a PHP interpreter is present, which the shipped image now provides.
2. The system shall add real-world C library CVEs beyond the existing curl and OpenSSL rows — libpng and the image libraries, OpenSSH, libpam, and vulnerable kernel modules were named. These are gated on Req 7.1: until the memory-family decision is closed they would join 173 pairs already sitting idle, so the decision comes first and the harvest follows it.
3. The system shall add further vibe-code pairs — agent-written and human-written web application bugs — because that slice is where the tool's stated audience actually works, and it is currently 35 pairs.
4. Before any slice is vendored at scale, the system shall verify on a sample that the model can read its pairs, and shall vendor only the categories that a measurement shows it can arbitrate. The OWASP harvest found 238 candidate pairs and vendored 40 for exactly this reason; the other 198 would have grown the corpus while making every number less interpretable.
5. Every vendored pair shall carry a stated licence, and no vendored excerpt or test shall contain a contiguous key-shaped literal.
6. Each new slice shall report as its own row and shall never be blended into a headline, and a synthetic slice shall say in its catalog that it measures breadth rather than real-world performance.
7. The system shall record, per slice, how many pairs the model can arbitrate — so corpus growth is measured by what it teaches rather than by how many rows it adds.

Requirement 10: Regression tuning over a large codebase

Objective: As a maintainer, I want a repeatable run over a large real codebase, so changes to the fact tables and queries can be checked for regressions that pair scoring cannot see.

Acceptance Criteria

1. The system shall support a repeatable scan over a pinned checkout of a large repository, recorded as a committed baseline.
2. When the fact tables or queries change, the system shall report the delta against that baseline — findings gained, findings lost, and rung movements.
3. The system shall treat an unexplained loss of a previously-entailed finding as a regression to be investigated, not a number to be accepted.
4. The baseline shall record the engine version, because a CPG engine change moves every verdict it produces.