Modules · Visa Vulnerability Agentic Harness (VVAH)

Module: validation

↩ architecture.html · generated 2026-08-14

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.


flowchart LR IN["Input\nRemediation DTOs"] --> ACT["Action\nRun a read-only adversarial panel against each proposed fix"] ACT --> VAL["Validation\nWeighted-gate consensus; fails closed to needs_review if unpersisted"] VAL --> OUT["Output\nVerdicts: validated / validation_failed / needs_review"]

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)

flowchart LR DTO[(remediation DTOs)] --> ING[ingest<br/>discover + stage workspace] ING --> EXE[execution/pipeline<br/>launch session] EXE --> PANEL[subagents<br/>architect + pentester + cross-repo] PANEL --> SYN[synthesis<br/>conservative consensus] SYN --> SCORE[scoring engine<br/>weighted gates] SCORE --> WB[io/dto_writeback<br/>verdict → DTO] TOOLS[tools/ deterministic facts] -.-> PANEL

Technical details

flowchart LR IN["Input\nRemediation DTOs"] --> ACT["Action\nRun a read-only adversarial panel against each proposed fix"] ACT --> VAL["Validation\nWeighted-gate consensus; fails closed to needs_review if unpersisted"] VAL --> OUT["Output\nVerdicts: validated / validation_failed / needs_review"]

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.py builds the panel's toolset: the generic Read/Glob/Grep readers from backends/harness/deepagents/tools.py plus five deterministic, read-only fact tools — DiffTouched, ChangedLines, DiffImpactMap, PatternScan, TestInventory — that operate on diff.patch and the staged workspace. There is no Write/Edit/Bash tool anywhere in this list. cli/_model.py is what enforces one vendor per panel: every persona inherits the orchestrator's via/provider from deepagents/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.