vulnerability-validation-skill AGENTS.md

Repository Working Agreement

This repository packages one portable vulnerability-validation Agent Skill.

This skill discovers and validates vulnerabilities. Its default mode is native discovery: presented a target repository with no findings list (finding_source_type = native_discovery), it analyzes the code to find new vulnerabilities (0-days) itself, then drives every candidate through the existing validation machinery. A supplied scanner finding, researcher report, or PoC is an optional seed, not a prerequisite. Discovery is a gated precursor: it enumerates and ranks candidates but never dispositions a finding or computes severity at intake; only the existing validation gates (reachability, live PoC, negative control, threat-model fit, and fixed-build differential evidence) promote a candidate to a finding. The discovery methodology is mandated and documented in skill-core/references/discovery-intake.md; it is bounded by a declared stopping criterion, admits nothing to a maintainer without proof, and may never claim finding-space completeness. The canonical body stays a lean orchestration spine: discovery method detail lives in references, while scripts/discovery_engine.py may deterministically generate and rank candidate ledgers. The engine is a candidate source only: it cannot disposition findings, compute final severity, patch code, or produce maintainer-facing vulnerability claims.

A dev-only discovery-accuracy regression oracle (scripts/efficacy_oracle.py, fixtures under tests/eval/, methodology in docs/accuracy-eval-methodology.md) is permitted under this charter. It is a discrimination-regression measurement that runs the repository's existing deterministic gates over labeled SYNTHETIC fixtures to confirm they still block planted false positives, admit sound true positives, and protect discovery recall (no silent candidate drops, no false completeness claims); it encodes no real target or finding, and it generates and ranks no candidates itself.

A separate dev-only native candidate-generation oracle (scripts/discovery_engine_oracle.py, fixtures and baseline under tests/engine_eval/) may execute the real engine over pinned synthetic known-sink targets. It measures planted-target recall, cap survival, candidate burden, negative- control emissions, deterministic work units, and replay stability. These metrics are regression evidence for the committed heuristic corpus only, never real-world vulnerability recall, candidate validation, finding promotion, or finding-space completeness.

An autonomous discovery engine (scripts/discovery_engine.py) is also permitted under this charter. It inspects a local target repository, optionally provisions tools only into a run-local tool home, falls back to deterministic source heuristics when tools fail, and emits native discovery ledgers (discovery-plan.json, surface-inventory.json, discovery-lane-results.json, candidate-fusion.json). Its output is unvalidated candidate input for the existing gates, never a maintainer-ready report.