Module: vvaharness/validation
Role. The inspection panel. A read-only adversarial panel grades each proposed fix against weighted gates and records a verdict; scoring is deterministic given the synthesised gates.
Size. 70 files · ~6,480 LOC.
Before any fix is trusted, this package tries to break it. It stages a patched copy of the repo, confirms the fix was applied, then runs a panel of AI personas: a security architect checks the fix addresses the root cause, a penetration tester tries to bypass it, and a cross-repo analyzer joins when a fix touches multiple repos. Their per-gate opinions are combined with a conservative rule, re-scored deterministically, and written back as a verdict.
About the AI engine behind it. Like remediation, the panel runs on DeepAgents
(see backends) because grading a fix takes several steps — read the diff,
check the surrounding code, form an opinion. Unlike remediation, this session is handed a
staged copy of the repo, not the real one, and its toolset has no Write, no Edit, and no
Bash at all — it is structurally unable to change anything, no matter what it concludes.
Explain-it-simply. An inspection panel that stress-tests each repair and stamps it Pass, Fail, or Needs-Review — and when in doubt, defaults to Needs-Review.
Data-flow (this module)
Technical details
cli/ is the vvaharness validate entry (_run.py runs the reports; _model.py
resolves/guards the backend and refuses mixed-vendor panels). ingest/ discovers validatable
DTOs (dto_loader.py), builds the agent manifest, and stages a pre-patched workspace
(workspace.py, asserting the remediation was applied). session/ builds the launch prompt
(injecting per-CWE bypass hints), injects Claude runtime config, and executes one session
(launcher.py, ~490 LOC — also writes host-synthesised gates). subagents/ loads the persona
definitions from bundled .md files. synthesis/_consensus.py computes the conservative majority;
scoring/ (_engine.py, _configs.py, _justify.py) turns gates into a typed ValidationScore;
io/_host_score.py re-scores from persisted synthesized_gates.json and fails closed. tools/
provides deterministic, read-only fact tools (diff facts, pattern scan, test inventory) the
personas call. models/, enums/, constants/, and config/ define the wire shapes, verdict
vocabularies, artifact/path registry, and the single env-reading config tree. report/augment.py
writes verdicts into the combined MD+SARIF report.
DeepAgents specifics for this stage.
tools/deep_tools.pybuilds the panel's toolset: the generic Read/Glob/Grep readers frombackends/harness/deepagents/tools.pyplus five deterministic, read-only fact tools —DiffTouched,ChangedLines,DiffImpactMap,PatternScan,TestInventory— that operate ondiff.patchand the staged workspace. There is no Write/Edit/Bash tool anywhere in this list.cli/_model.pyis what enforces one vendor per panel: every persona inherits the orchestrator'svia/providerfromdeepagents/options.py::build_model(), and a persona pinned to a different vendor's model id causes validation to refuse to start (exit 2) before any spend. Full mechanics: LLD §9.
File map (quick scan)
| File | LOC | Purpose |
|---|---|---|
validation/__init__.py |
16 | AI SAST Finding Validation Orchestrator. |
validation/cli/__init__.py |
160 | The validation CLI entry point for vvaharness validate. |
validation/cli/_model.py |
202 | Model-resolution logic for the vvaharness validate command. |
validation/cli/_parser.py |
104 | Argument parser and tunable-override helpers for vvaharness validate. |
validation/cli/_patterns.py |
22 | Compiled regex patterns for the cli package. |
validation/cli/_run.py |
311 | Core validation execution: run_validation() and _validate_one(). |
validation/config/__init__.py |
34 | Validation agent configuration (the only place environment is read). |
validation/config/settings.py |
189 | Typed configuration tree; all VVAHARNESS_* env access funnelled through _EnvScalars. |
validation/constants/__init__.py |
16 | Constant vocabularies for the validation agent (enums + path registry only). |
validation/constants/artifacts.py |
171 | Single source of truth for artifact names, DTO layout, and runtime environment keys. |
validation/constants/diff.py |
48 | Constants for deterministic diff-based fact tools. |
validation/constants/paths.py |
51 | Validation-path registry. Only the fix-validation path is supported. |
validation/constants/pattern_sets.py |
35 | Constants for deterministic pattern-scanning fact tools. |
validation/constants/policy.py |
51 | Validation-specific harness policy values (read-only tool allow-list + write gate). |
validation/constants/scoring.py |
58 | Canonical scoring weights and thresholds used directly by the scoring engine. |
validation/constants/synthesis.py |
26 | Constants for deterministic persona-report consensus synthesis. |
validation/constants/test_inventory.py |
34 | Constants for the deterministic test-inventory fact tool. |
validation/constants/tools.py |
32 | Constant tool-name vocabularies for the validation agent. |
validation/enums/__init__.py |
45 | Domain enums for vvaharness.validation. |
validation/enums/gates.py |
63 | Gate-evaluation enums for the fix-validation scoring path. |
validation/enums/paths.py |
28 | Validation-path enum. |
validation/enums/readiness.py |
30 | Merge-readiness enum derived from a ValidationScore. |
validation/enums/verdicts.py |
47 | Fix-validation verdict vocabulary emitted by the scoring engine and agent. |
validation/execution/__init__.py |
20 | Execution package: plan execution pipeline. |
validation/execution/pipeline.py |
71 | Plan execution pipeline: launch a fix-validation session and collect results. |
validation/hints/__init__.py |
19 | Per-CWE adversarial bypass hints for the validation agent. |
validation/hints/loader.py |
101 | Load per-CWE adversarial bypass hints from the operator-supplied inputs/ file. |
validation/ingest/__init__.py |
40 | DTO ingest layer: discover remediation reports and stage validation workspaces. |
validation/ingest/dto_loader.py |
138 | Discover and load remediation report DTOs from a target repository. |
validation/ingest/errors.py |
22 | Ingest-layer error type. |
validation/ingest/manifest_builder.py |
50 | Map a remediation report DTO onto the agent-facing validation manifest. |
validation/ingest/workspace.py |
96 | Stage a pre-patched copy of the target repo and gate on applied remediation. |
validation/io/__init__.py |
15 | — |
validation/io/_host_score.py |
159 | Deterministic host-side scoring from host-persisted synthesized_gates.json. |
validation/io/dto_writeback.py |
157 | Write the agentic verdict back into the remediation DTO's validation block. |
validation/io/message_logger.py |
152 | Drain a Harness streaming session to session.jsonl and return exit status. |
validation/io/persona_report_stash.py |
85 | Extract subagent persona reports from the parent graph state (DeepAgents or SDK/CLI). |
validation/io/result_collector.py |
179 | Collect fix-validation results from the agent session output. |
validation/models/__init__.py |
79 | Pydantic data contracts and value types for the validation agent. |
validation/models/dto.py |
95 | Remediation DTO (remediate_report.json) consumed by the validator; tolerant wire shape. |
validation/models/manifest.py |
73 | Per-finding workspace manifest (manifest.json); treated as a stable wire shape. |
validation/models/output.py |
90 | Strict structured-output schema for the read-only DeepAgents validation session. |
validation/models/persona_report.py |
69 | Pydantic wire shapes for native DeepAgents persona reports. |
validation/models/plans.py |
36 | Execution-plan value objects for the fix-validation path. |
validation/models/results.py |
154 | Host-side validation result models and the agent report contract. |
validation/models/scoring.py |
140 | Value types shared between the scoring engine and the rest of the package. |
validation/report/__init__.py |
19 | Combined-report augmentation: write validation results into the SARIF + MD report. |
validation/report/augment.py |
340 | Augment the combined SARIF + MD report with validation results. |
validation/scoring/__init__.py |
101 | Public scoring API: parse raw gate dicts and return typed ValidationScore results. |
validation/scoring/_configs.py |
54 | ScoringConfig instance for the fix-validation path. |
validation/scoring/_engine.py |
212 | Config-driven scoring engine; re-exports scoring dataclasses for intra-package compat. |
validation/scoring/_justify.py |
112 | Fix-path justification builder; tracker templates embed these phrasings — edit deliberately. |
validation/session/__init__.py |
32 | Validation session package — launch and error hierarchy. |
validation/session/config_inject.py |
88 | Inject Claude runtime config files into a validation workspace. |
validation/session/errors.py |
50 | Domain exception hierarchy for harness-backed validation sessions. |
validation/session/launch_prompt.py |
110 | Build the fix-validation launch prompt for a pre-staged workspace. |
validation/session/launcher.py |
488 | Execute a single fix-validation session via the harness. |
validation/session/rules.py |
60 | Read the bundled validation rules as prompt text. |
validation/session/setup.py |
73 | Assemble the validation-specific values injected into the shared harness. |
validation/subagents/__init__.py |
23 | Bundled subagent definitions loaded at import time from .md authoring files. |
validation/subagents/_frontmatter.py |
97 | Parse YAML frontmatter from subagent .md authoring files without a pyyaml dependency. |
validation/subagents/_loader.py |
126 | Load subagent definitions from bundled .md authoring files. |
validation/synthesis/__init__.py |
16 | Host-side deterministic synthesis of persona reports. |
validation/synthesis/_consensus.py |
141 | Deterministic synthesis of persona gate reports into host-owned gate verdicts. |
validation/tools/__init__.py |
16 | Deterministic read-only tools for the validation agent. |
validation/tools/_scope.py |
94 | Shared in-scope file iteration for validation fact tools. |
validation/tools/deep_tools.py |
110 | Validation's DeepAgents tool-builder: generic readers + deterministic fact tools. |
validation/tools/diff_facts.py |
160 | Deterministic, read-only diff fact tools for validation subagents. |
validation/tools/pattern_scanner.py |
69 | Deterministic pattern scanner for validation subagents. |
validation/tools/test_inventory.py |
76 | Deterministic test-inventory fact tool for validation subagents. |
Files & functions, explained
Every class and function below has a one-line plain-English note — readable whether you write code or not. _name marks an internal helper.
validation/__init__.py
16 LOC. AI SAST Finding Validation Orchestrator.
No top-level classes or functions (package init / constants).
validation/cli/__init__.py
160 LOC. The validation CLI entry point for vvaharness validate.
Functions
- _resolve_selection() — (internal helper) checks / decides the selection value.
- _resolve_config_path() — (internal helper) checks / decides the config path step.
- _is_nonempty_dir() — (internal helper) checks / decides the nonempty dir step.
- _check_path_guards() — (internal helper) checks / decides the path guards step.
- _dispatch() — (internal helper) runs the dispatch value.
- main() — Runs the main value.
validation/cli/_model.py
202 LOC. Model-resolution logic for the vvaharness validate command.
Functions
- _validate_model_spec() — (internal helper) checks / decides the model rule specification step.
- _normalize_validate_backend() — (internal helper) reads and cleans up the fix-check backend step.
- _routes_to_anthropic() — (internal helper) Provides the “routes to anthropic” logic.
- _check_persona_vendors() — (internal helper) checks / decides the AI reviewer vendors step.
- _load_validated_spec() — (internal helper) looks up / reads the validated rule specification step.
- _persona_spec_resolved() — (internal helper) Provides the “AI reviewer rule specification resolved” logic.
- _apply_model_env() — (internal helper) runs the model environment settings step.
validation/cli/_parser.py
104 LOC. Argument parser and tunable-override helpers for vvaharness validate.
Functions
- _build_parser() — (internal helper) builds / writes the parser value.
- _tunable_overrides() — (internal helper) Provides the “tunable overrides” logic.
validation/cli/_patterns.py
22 LOC. Compiled regex patterns for the cli package.
No top-level classes or functions (package init / constants).
validation/cli/_run.py
311 LOC. Core validation execution: run_validation() and _validate_one().
Classes
- Selection — Represents the “Selection” data/behaviour used in this file.
- ValidationRun — Represents the “ValidationRun” data/behaviour used in this file.
Functions
- _is_hard_failure() — (internal helper) checks / decides the hard failure step.
- _safe() — (internal helper) Provides the “safe” logic.
- _step_key() — (internal helper) Provides the “step key” logic.
- _session_log_dest() — (internal helper) Provides the “session log dest” logic.
- _persist_session_log() — (internal helper) builds / writes the session log step.
- _print_result() — (internal helper) Provides the “print result” logic.
- _validate_one() — (internal helper) checks / decides the one value.
- _resume_hit() — (internal helper) Provides the “resume hit” logic.
- _process_report() — (internal helper) runs the report value.
- _run_reports() — (internal helper) runs the reports value.
- _cleanup_workspace() — (internal helper) reads and cleans up the working folder value.
- _empty_selection_rc() — (internal helper) Provides the “empty selection report-confidence” logic.
- run_validation() — Runs the fix-check value.
validation/config/__init__.py
34 LOC. Validation agent configuration (the only place environment is read).
No top-level classes or functions (package init / constants).
validation/config/settings.py
189 LOC. Typed configuration tree; all VVAHARNESS_* env access funnelled through _EnvScalars.
Classes
- PathsConfig — Represents the “PathsConfig” data/behaviour used in this file.
- AgentConfig — Represents the “AgentConfig” data/behaviour used in this file.
- GheConfig — Represents the “GheConfig” data/behaviour used in this file.
- Config — Represents the “Config” data/behaviour used in this file.
- _EnvScalars — (internal) Represents the “EnvScalars” data/behaviour used in this file.
Functions
- _parse_tools() — (internal helper) reads and cleans up the tools value.
- _build_paths() — (internal helper) builds / writes the paths value.
- load_config() — Looks up / reads the config value.
validation/constants/__init__.py
16 LOC. Constant vocabularies for the validation agent (enums + path registry only).
No top-level classes or functions (package init / constants).
validation/constants/artifacts.py
171 LOC. Single source of truth for artifact names, DTO layout, and runtime environment keys.
No top-level classes or functions (package init / constants).
validation/constants/diff.py
48 LOC. Constants for deterministic diff-based fact tools.
No top-level classes or functions (package init / constants).
validation/constants/paths.py
51 LOC. Validation-path registry. Only the fix-validation path is supported.
Classes
- PathConfig — Represents the “PathConfig” data/behaviour used in this file.
Functions
- resolve_path() — Checks / decides the path value.
validation/constants/pattern_sets.py
35 LOC. Constants for deterministic pattern-scanning fact tools.
No top-level classes or functions (package init / constants).
validation/constants/policy.py
51 LOC. Validation-specific harness policy values (read-only tool allow-list + write gate).
No top-level classes or functions (package init / constants).
validation/constants/scoring.py
58 LOC. Canonical scoring weights and thresholds used directly by the scoring engine.
No top-level classes or functions (package init / constants).
validation/constants/synthesis.py
26 LOC. Constants for deterministic persona-report consensus synthesis.
No top-level classes or functions (package init / constants).
validation/constants/test_inventory.py
34 LOC. Constants for the deterministic test-inventory fact tool.
No top-level classes or functions (package init / constants).
validation/constants/tools.py
32 LOC. Constant tool-name vocabularies for the validation agent.
No top-level classes or functions (package init / constants).
validation/enums/__init__.py
45 LOC. Domain enums for vvaharness.validation.
No top-level classes or functions (package init / constants).
validation/enums/gates.py
63 LOC. Gate-evaluation enums for the fix-validation scoring path.
Classes
- GateStatus — Represents the “GateStatus” data/behaviour used in this file.
- parse() — Reads and cleans up the parse value.
- GateName — Represents the “GateName” data/behaviour used in this file.
validation/enums/paths.py
28 LOC. Validation-path enum.
Classes
- ValidationPath — Represents the “ValidationPath” data/behaviour used in this file.
validation/enums/readiness.py
30 LOC. Merge-readiness enum derived from a ValidationScore.
Classes
- MergeReadiness — Represents the “MergeReadiness” data/behaviour used in this file.
validation/enums/verdicts.py
47 LOC. Fix-validation verdict vocabulary emitted by the scoring engine and agent.
Classes
- FixVerdict — Represents the “FixVerdict” data/behaviour used in this file.
- parse() — Reads and cleans up the parse value.
- Answer — Represents the “Answer” data/behaviour used in this file.
validation/execution/__init__.py
20 LOC. Execution package: plan execution pipeline.
No top-level classes or functions (package init / constants).
validation/execution/pipeline.py
71 LOC. Plan execution pipeline: launch a fix-validation session and collect results.
Functions
- _unverifiable() — (internal helper) Provides the “unverifiable” logic.
- execute_plan() — Runs the plan value.
validation/hints/__init__.py
19 LOC. Per-CWE adversarial bypass hints for the validation agent.
No top-level classes or functions (package init / constants).
validation/hints/loader.py
101 LOC. Load per-CWE adversarial bypass hints from the operator-supplied inputs/ file.
Classes
- CweHints — Represents the “CweHints” data/behaviour used in this file.
- load() — Looks up / reads the load value.
Functions
- _hints_path() — (internal helper) Provides the “hints path” logic.
- _parse_hints() — (internal helper) reads and cleans up the hints value.
- _resolve_raw() — (internal helper) checks / decides the raw value.
- _registry() — (internal helper) Provides the “registry” logic.
- hints_for() — Provides the “hints for” logic.
validation/ingest/__init__.py
40 LOC. DTO ingest layer: discover remediation reports and stage validation workspaces.
No top-level classes or functions (package init / constants).
validation/ingest/dto_loader.py
138 LOC. Discover and load remediation report DTOs from a target repository.
Functions
- discover_reports() — Looks up / reads the reports value.
- load_report() — Looks up / reads the report value.
- _load_report_safe() — (internal helper) looks up / reads the report safe step.
- _all_reports() — (internal helper) Provides the “all reports” logic.
- _is_validatable() — (internal helper) checks / decides the validatable value.
- _cvss_score() — (internal helper) Provides the “severity score score” logic.
- _top_by_cvss() — (internal helper) Provides the “highest-priority by severity score” logic.
- _log_selection() — (internal helper) Provides the “log selection” logic.
- select_reports() — Checks / decides the reports value.
- _select_by_id() — (internal helper) checks / decides the by identifier step.
validation/ingest/errors.py
22 LOC. Ingest-layer error type.
Classes
- IngestError — Represents the “IngestError” data/behaviour used in this file.
validation/ingest/manifest_builder.py
50 LOC. Map a remediation report DTO onto the agent-facing validation manifest.
Functions
- build_manifest() — Builds / writes the run record value.
validation/ingest/workspace.py
96 LOC. Stage a pre-patched copy of the target repo and gate on applied remediation.
Functions
- stage_workspace() — Builds / writes the working folder value.
- _under_repo() — (internal helper) Provides the “under code repository” logic.
- _resolve_touched() — (internal helper) checks / decides the changed value.
- _any_touched_exists() — (internal helper) Provides the “any changed exists” logic.
- assert_remediation_applied() — Checks / decides the fix applied step.
validation/io/__init__.py
15 LOC. Utility / support module.
No top-level classes or functions (package init / constants).
validation/io/_host_score.py
159 LOC. Deterministic host-side scoring from host-persisted synthesized_gates.json.
Classes
- HostScore — Represents the “HostScore” data/behaviour used in this file.
Functions
- _read_gates_text() — (internal helper) looks up / reads the rule checks text step.
- _parse_gates_array() — (internal helper) reads and cleans up the rule checks array step.
- _gates_by_tracking_id() — (internal helper) checks / decides the by tracking identifier step.
- load_synthesized_gates() — Looks up / reads the synthesized rule checks step.
- effective_score() — Provides the “effective score” logic.
- _gate_scores() — (internal helper) checks / decides the scores value.
- host_score_for() — Provides the “host score for” logic.
validation/io/dto_writeback.py
157 LOC. Write the agentic verdict back into the remediation DTO's validation block.
Functions
- _load_verdict() — (internal helper) looks up / reads the pass/fail decision value.
- _validation_block() — (internal helper) Provides the “fix-check block” logic.
- _terminal_status() — (internal helper) Provides the “terminal status” logic.
- _load_raw_dto() — (internal helper) looks up / reads the raw per-finding fix record step.
- _dump_raw_dto() — (internal helper) builds / writes the raw per-finding fix record step.
- write_back_validation() — Builds / writes the back fix-check step.
validation/io/message_logger.py
152 LOC. Drain a Harness streaming session to session.jsonl and return exit status.
Functions
- _serialize() — (internal helper) Provides the “serialize” logic.
- _agent_desc() — (internal helper) Provides the “agent desc” logic.
- _log_key_event() — (internal helper) Provides the “log key event” logic.
- _format_tool_use() — (internal helper) builds / writes the tool use step.
- _format_assistant_text() — (internal helper) builds / writes the assistant text step.
- _format_terminal() — (internal helper) builds / writes the terminal value.
- _fmt_session_init() — (internal helper) Provides the “fmt session init” logic.
- _fmt_tool_use() — (internal helper) Provides the “fmt tool use” logic.
- _fmt_assistant_text() — (internal helper) Provides the “fmt assistant text” logic.
- _format_live() — (internal helper) builds / writes the live value.
- _print_live() — (internal helper) Provides the “print live” logic.
- _process_message() — (internal helper) runs the message value.
- stream_and_log() — Provides the “stream and log” logic.
validation/io/persona_report_stash.py
85 LOC. Extract subagent persona reports from the parent graph state (DeepAgents or SDK/CLI).
Functions
- _validate_candidates() — (internal helper) checks / decides the candidates value.
- extract_subagent_reports() — Reads and cleans up the helper AI reviewer reports step.
validation/io/result_collector.py
179 LOC. Collect fix-validation results from the agent session output.
Functions
- _files_needing_fixes() — (internal helper) Provides the “files needing fixes” logic.
- _build_result() — (internal helper) builds / writes the result value.
- collect_results() — Looks up / reads the results value.
- _filter_affected_files() — (internal helper) checks / decides the affected files step.
- _load_manifest() — (internal helper) looks up / reads the run record value.
- collect_and_enrich() — Looks up / reads the and enrich step.
- _enrich_tracking_id() — (internal helper) adds detail to the tracking identifier step.
- _enrich_result() — (internal helper) adds detail to the result value.
validation/models/__init__.py
79 LOC. Pydantic data contracts and value types for the validation agent.
No top-level classes or functions (package init / constants).
validation/models/dto.py
95 LOC. Remediation DTO (remediate_report.json) consumed by the validator; tolerant wire shape.
Classes
- DtoFinding — Represents the “DtoFinding” data/behaviour used in this file.
- _null_to_default() — (internal helper) Provides the “null to default” logic.
- DtoPatch — Represents the “DtoPatch” data/behaviour used in this file.
- RemediationReport — Represents the “RemediationReport” data/behaviour used in this file.
- from_file() — Provides the “from file” logic.
Functions
- _read_json() — (internal helper) looks up / reads the data file value.
validation/models/manifest.py
73 LOC. Per-finding workspace manifest (manifest.json); treated as a stable wire shape.
Classes
- ManifestFinding — Represents the “ManifestFinding” data/behaviour used in this file.
- Manifest — Represents the “run record” data/behaviour used in this file.
- to_dict() — Provides the “to dict” logic.
- write() — Builds / writes the write value.
- from_file() — Provides the “from file” logic.
validation/models/output.py
90 LOC. Strict structured-output schema for the read-only DeepAgents validation session.
Classes
- GateEntry — Represents the “GateEntry” data/behaviour used in this file.
- SynthesizedGatesEntry — Represents the “SynthesizedGatesEntry” data/behaviour used in this file.
- OutputFinding — Represents the “OutputFinding” data/behaviour used in this file.
- _coerce_csv() — (internal helper) reads and cleans up the csv value.
- ValidationOutput — Represents the “ValidationOutput” data/behaviour used in this file.
validation/models/persona_report.py
69 LOC. Pydantic wire shapes for native DeepAgents persona reports.
Classes
- EvidenceAnchor — Represents the “EvidenceAnchor” data/behaviour used in this file.
- _none_to_empty() — (internal helper) Provides the “none to empty” logic.
- PersonaGateEntry — Represents the “PersonaGateEntry” data/behaviour used in this file.
- _canonical_status() — (internal helper) Provides the “canonical status” logic.
- PersonaReport — Represents the “PersonaReport” data/behaviour used in this file.
validation/models/plans.py
36 LOC. Execution-plan value objects for the fix-validation path.
Classes
- FixValidationPlan — Represents the “FixValidationPlan” data/behaviour used in this file.
validation/models/results.py
154 LOC. Host-side validation result models and the agent report contract.
Classes
- RunMetadata — Represents the “RunMetadata” data/behaviour used in this file.
- ValidationResult — Represents the “ValidationResult” data/behaviour used in this file.
- FixFindingReport — Represents the “FixFindingReport” data/behaviour used in this file.
- _clamp_raw_score() — (internal helper) Provides the “clamp raw score” logic.
- _coerce_merge_readiness() — (internal helper) reads and cleans up the merge readiness step.
- _redact_narrative() — (internal helper) hides sensitive data in the narrative value.
- ValidationReport — Represents the “ValidationReport” data/behaviour used in this file.
- from_file() — Provides the “from file” logic.
Functions
- make_unverifiable() — Builds / writes the unverifiable value.
validation/models/scoring.py
140 LOC. Value types shared between the scoring engine and the rest of the package.
Classes
- RawEvidence — Represents the “RawEvidence” data/behaviour used in this file.
- RawCriterion — Represents the “RawCriterion” data/behaviour used in this file.
- VerdictRule — Represents the “VerdictRule” data/behaviour used in this file.
- ScoreResult — Represents the “ScoreResult” data/behaviour used in this file.
- ScoringConfig — Represents the “ScoringConfig” data/behaviour used in this file.
- ScoredGateEntry — Represents the “ScoredGateEntry” data/behaviour used in this file.
- EvidenceAnchor — Represents the “EvidenceAnchor” data/behaviour used in this file.
- GateResult — Represents the “GateResult” data/behaviour used in this file.
- ValidationScore — Represents the “ValidationScore” data/behaviour used in this file.
validation/report/__init__.py
19 LOC. Combined-report augmentation: write validation results into the SARIF + MD report.
No top-level classes or functions (package init / constants).
validation/report/augment.py
340 LOC. Augment the combined SARIF + MD report with validation results.
Functions
- augment_reports() — Adds detail to the reports value.
- _augment() — (internal helper) adds detail to the augment value.
- _locate_combined_report() — (internal helper) looks up / reads the combined report step.
- _status_label() — (internal helper) Provides the “status label” logic.
- _status_word() — (internal helper) Provides the “status word” logic.
- _parse_gates() — (internal helper) reads and cleans up the rule checks value.
- _validation_block() — (internal helper) Provides the “fix-check block” logic.
- _norm_path() — (internal helper) reads and cleans up the path value.
- _result_loc() — (internal helper) Provides the “result lines of code” logic.
- _match_by_loc() — (internal helper) checks / decides the by lines of code step.
- _match_by_title() — (internal helper) checks / decides the by title step.
- _match_sarif() — (internal helper) checks / decides the machine-readable report value.
- _augment_sarif() — (internal helper) adds detail to the machine-readable report value.
- _trim_dangling_escape() — (internal helper) Provides the “trim dangling escape” logic.
- _md_escape() — (internal helper) Provides the “Markdown report escape” logic.
- _md_cell() — (internal helper) Provides the “Markdown report cell” logic.
- _gate_rows() — (internal helper) checks / decides the rows value.
- _md_validation_section() — (internal helper) Provides the “Markdown report fix-check section” logic.
- _ftitle() — (internal helper) Provides the “ftitle” logic.
- _only() — (internal helper) Provides the “only” logic.
- _best_md_match() — (internal helper) Provides the “best Markdown report match” logic.
- _augment_md() — (internal helper) adds detail to the Markdown report value.
- _augment_segment() — (internal helper) adds detail to the segment value.
validation/scoring/__init__.py
101 LOC. Public scoring API: parse raw gate dicts and return typed ValidationScore results.
Functions
- _parse_gates() — (internal helper) reads and cleans up the rule checks value.
- _has_critical_failure() — (internal helper) checks / decides the critical failure step.
- score_fix() — Checks / decides the fix value.
- derive_merge_readiness() — Provides the “derive merge readiness” logic.
- _build_gate_results() — (internal helper) builds / writes the rule check results step.
validation/scoring/_configs.py
54 LOC. ScoringConfig instance for the fix-validation path.
No top-level classes or functions (package init / constants).
validation/scoring/_engine.py
212 LOC. Config-driven scoring engine; re-exports scoring dataclasses for intra-package compat.
Functions
- _str_from() — (internal helper) Provides the “str from” logic.
- _int_or_none() — (internal helper) Provides the “int or none” logic.
- _parse_evidence() — (internal helper) reads and cleans up the evidence value.
- parse_raw_criterion() — Reads and cleans up the raw criterion step.
- _shape_error() — (internal helper) reads and cleans up the error value.
- _renormalized_score() — (internal helper) Provides the “renormalized score” logic.
- _critical_gate_error() — (internal helper) Provides the “critical rule check error” logic.
- _cap_critical_fail() — (internal helper) checks / decides the critical fail step.
- _precheck() — (internal helper) Provides the “precheck” logic.
- score() — Checks / decides the score value.
- _apply_verdicts() — (internal helper) runs the verdicts value.
validation/scoring/_justify.py
112 LOC. Fix-path justification builder; tracker templates embed these phrasings — edit deliberately.
Functions
- _confidence() — (internal helper) Provides the “confidence” logic.
- _anchors_str() — (internal helper) Provides the “anchors str” logic.
- _fixed_text() — (internal helper) Provides the “fixed text” logic.
- _partial_text() — (internal helper) Provides the “partial text” logic.
- _not_fixed_text() — (internal helper) Provides the “not fixed text” logic.
- build_fix_justification() — Builds / writes the fix justification step.
- _collect_evidence_anchors() — (internal helper) looks up / reads the evidence anchors step.
- _files_needing_fixes() — (internal helper) Provides the “files needing fixes” logic.
- _recommended_actions() — (internal helper) Provides the “recommended actions” logic.
validation/session/__init__.py
32 LOC. Validation session package — launch and error hierarchy.
No top-level classes or functions (package init / constants).
validation/session/config_inject.py
88 LOC. Inject Claude runtime config files into a validation workspace.
Functions
- _inject_hooks() — (internal helper) builds / writes the hooks value.
- _inject_tools() — (internal helper) builds / writes the tools value.
- inject_claude_config() — Builds / writes the claude config step.
validation/session/errors.py
50 LOC. Domain exception hierarchy for harness-backed validation sessions.
Classes
- ValidationSessionError — Represents the “ValidationSessionError” data/behaviour used in this file.
- reason_string() — Provides the “reason string” logic.
validation/session/launch_prompt.py
110 LOC. Build the fix-validation launch prompt for a pre-staged workspace.
Functions
- _score_line() — (internal helper) checks / decides the line value.
- _narrative_lines() — (internal helper) Provides the “narrative lines” logic.
- _bypass_hint_lines() — (internal helper) Provides the “bypass hint lines” logic.
- _append_finding_details() — (internal helper) adds detail to the candidate issue details step.
- build_launch_prompt() — Builds / writes the launch prompt step.
validation/session/launcher.py
488 LOC. Execute a single fix-validation session via the harness.
Functions
- _build_env() — (internal helper) builds / writes the environment settings value.
- _persona_overrides() — (internal helper) Provides the “AI reviewer overrides” logic.
- _resolve_binary() — (internal helper) checks / decides the binary value.
- _write_workspace_json() — (internal helper) builds / writes the working folder data file step.
- _write_validation_outputs() — (internal helper) builds / writes the fix-check outputs step.
- _write_host_synthesized_gates() — (internal helper) builds / writes the host synthesized rule checks step.
- build_validation_options() — Builds / writes the fix-check options step.
- _injects_claude_config() — (internal helper) builds / writes the claude config step.
- _rules_section() — (internal helper) Provides the “rules section” logic.
- _synthesizes_gates_on_host() — (internal helper) builds / writes the rule checks on host step.
- _synthesis_section() — (internal helper) builds / writes the section value.
- _load_system_prompt() — (internal helper) looks up / reads the system prompt step.
- _failure_reason() — (internal helper) Provides the “failure reason” logic.
- _run_and_check() — (internal helper) runs the and check step.
- _log_stream() — (internal helper) Provides the “log stream” logic.
- launch_session() — Provides the “launch session” logic.
validation/session/rules.py
60 LOC. Read the bundled validation rules as prompt text.
Functions
- _rules_text() — (internal helper) Provides the “rules text” logic.
- orchestrator_rules_text() — Provides the “lead coordinator rules text” logic.
- persona_rules_text() — Provides the “AI reviewer rules text” logic.
validation/session/setup.py
73 LOC. Assemble the validation-specific values injected into the shared harness.
Functions
- validation_skill_root() — Provides the “fix-check skill root” logic.
- validation_write_gate() — Provides the “fix-check write rule check” logic.
validation/subagents/__init__.py
23 LOC. Bundled subagent definitions loaded at import time from .md authoring files.
No top-level classes or functions (package init / constants).
validation/subagents/_frontmatter.py
97 LOC. Parse YAML frontmatter from subagent .md authoring files without a pyyaml dependency.
Classes
- SubagentFrontmatterMeta — Represents the “SubagentFrontmatterMeta” data/behaviour used in this file.
Functions
- _append_list_item() — (internal helper) adds detail to the list item step.
- _apply_key_line() — (internal helper) runs the key line step.
- _classify_line() — (internal helper) Provides the “classify line” logic.
- parse_frontmatter() — Reads and cleans up the file-header metadata value.
validation/subagents/_loader.py
126 LOC. Load subagent definitions from bundled .md authoring files.
Functions
- _build_subagent_definition() — (internal helper) builds / writes the helper AI reviewer definition step.
- _iter_bundled_files() — (internal helper) looks up / reads the bundled files step.
- load_agents() — Looks up / reads the agents value.
- _assert_all_found() — (internal helper) checks / decides the all found step.
validation/synthesis/__init__.py
16 LOC. Host-side deterministic synthesis of persona reports.
No top-level classes or functions (package init / constants).
validation/synthesis/_consensus.py
141 LOC. Deterministic synthesis of persona gate reports into host-owned gate verdicts.
Classes
- SynthesizedGate — Represents the “SynthesizedGate” data/behaviour used in this file.
Functions
- _most_conservative_status() — (internal helper) Provides the “most conservative status” logic.
- synthesize_gates_for_finding() — Builds / writes the rule checks for candidate issue step.
validation/tools/__init__.py
16 LOC. Deterministic read-only tools for the validation agent.
No top-level classes or functions (package init / constants).
validation/tools/_scope.py
94 LOC. Shared in-scope file iteration for validation fact tools.
Functions
- _in_excluded_dir() — (internal helper) Provides the “in excluded dir” logic.
- _has_excluded_ext() — (internal helper) checks / decides the excluded ext step.
- _escapes_workspace() — (internal helper) Provides the “escapes working folder” logic.
- iter_in_scope_files() — Looks up / reads the in in-scope set files step.
validation/tools/deep_tools.py
110 LOC. Validation's DeepAgents tool-builder: generic readers + deterministic fact tools.
Functions
- _fact_tools() — (internal helper) Provides the “fact tools” logic.
- build_validation_tools() — Builds / writes the fix-check tools step.
validation/tools/diff_facts.py
160 LOC. Deterministic, read-only diff fact tools for validation subagents.
Classes
- FileChange — Represents the “FileChange” data/behaviour used in this file.
- _DiffParser — (internal) Represents the “DiffParser” data/behaviour used in this file.
- _close_added_run() — (internal helper) Provides the “close added run” logic.
- _close_file() — (internal helper) Provides the “close file” logic.
- _consume_hunk_line() — (internal helper) runs the hunk line step.
- feed() — Provides the “feed” logic.
- finish() — Provides the “finish” logic.
- DiffImpactMap — Represents the “DiffImpactMap” data/behaviour used in this file.
Functions
- _without_git_prefix() — (internal helper) Provides the “without version control prefix” logic.
- _marker_path() — (internal helper) Provides the “marker path” logic.
- parse_diff_patch() — Reads and cleans up the code change code change step.
- diff_touched() — Provides the “code change changed” logic.
- changed_lines() — Provides the “changed lines” logic.
- build_diff_impact_map() — Builds / writes the code change blast radius map step.
validation/tools/pattern_scanner.py
69 LOC. Deterministic pattern scanner for validation subagents.
Functions
- pattern_scan() — Provides the “pattern scan” logic.
validation/tools/test_inventory.py
76 LOC. Deterministic test-inventory fact tool for validation subagents.
Functions
- _is_test_file() — (internal helper) checks / decides the test file step.
- _negative_markers() — (internal helper) Provides the “negative markers” logic.
- test_inventory() — Provides the “test list” logic.
See also: HLD · LLD · Data Flow · module index.