# internal/core/review

Package review defines review dossiers, verdicts, and provider-output parsing.

## VerdictPass

```go
const (
	// VerdictPass marks a dossier with no open completion blockers.
	VerdictPass = "pass"
	// VerdictFail marks a dossier with one or more open completion blockers.
	VerdictFail = "fail"
)
```

## VerdictFail

```go
const (
	// VerdictPass marks a dossier with no open completion blockers.
	VerdictPass = "pass"
	// VerdictFail marks a dossier with one or more open completion blockers.
	VerdictFail = "fail"
)
```

## AttackResultFinding

```go
const (
	// AttackResultFinding means the attack produced one or more findings.
	AttackResultFinding AttackResult = "finding"
	// AttackResultClean means the attack found no issue.
	AttackResultClean AttackResult = "clean"
	// AttackResultSkipped means the reviewer deliberately skipped the attack and should explain why.
	AttackResultSkipped AttackResult = "skipped"
)
```

## AttackResultClean

```go
const (
	// AttackResultFinding means the attack produced one or more findings.
	AttackResultFinding AttackResult = "finding"
	// AttackResultClean means the attack found no issue.
	AttackResultClean AttackResult = "clean"
	// AttackResultSkipped means the reviewer deliberately skipped the attack and should explain why.
	AttackResultSkipped AttackResult = "skipped"
)
```

## AttackResultSkipped

```go
const (
	// AttackResultFinding means the attack produced one or more findings.
	AttackResultFinding AttackResult = "finding"
	// AttackResultClean means the attack found no issue.
	AttackResultClean AttackResult = "clean"
	// AttackResultSkipped means the reviewer deliberately skipped the attack and should explain why.
	AttackResultSkipped AttackResult = "skipped"
)
```

## ConfidenceHigh

```go
const (
	// ConfidenceHigh means the finding is directly supported by cited evidence.
	ConfidenceHigh Confidence = "high"
	// ConfidenceMedium means the finding is plausible but may need validation.
	ConfidenceMedium Confidence = "medium"
	// ConfidenceLow means the finding is speculative and must not block completion.
	ConfidenceLow Confidence = "low"
)
```

## ConfidenceMedium

```go
const (
	// ConfidenceHigh means the finding is directly supported by cited evidence.
	ConfidenceHigh Confidence = "high"
	// ConfidenceMedium means the finding is plausible but may need validation.
	ConfidenceMedium Confidence = "medium"
	// ConfidenceLow means the finding is speculative and must not block completion.
	ConfidenceLow Confidence = "low"
)
```

## ConfidenceLow

```go
const (
	// ConfidenceHigh means the finding is directly supported by cited evidence.
	ConfidenceHigh Confidence = "high"
	// ConfidenceMedium means the finding is plausible but may need validation.
	ConfidenceMedium Confidence = "medium"
	// ConfidenceLow means the finding is speculative and must not block completion.
	ConfidenceLow Confidence = "low"
)
```

## FindingOpen

```go
const (
	// FindingOpen means the finding still needs repair.
	FindingOpen FindingStatus = "open"
	// FindingFixed means the reviewer verified the finding as repaired.
	FindingFixed FindingStatus = "fixed"
	// FindingAcceptedRisk means a human accepted the residual risk.
	FindingAcceptedRisk FindingStatus = "accepted_risk"
	// FindingSuperseded means a newer finding replaced this one.
	FindingSuperseded FindingStatus = "superseded"
)
```

## FindingFixed

```go
const (
	// FindingOpen means the finding still needs repair.
	FindingOpen FindingStatus = "open"
	// FindingFixed means the reviewer verified the finding as repaired.
	FindingFixed FindingStatus = "fixed"
	// FindingAcceptedRisk means a human accepted the residual risk.
	FindingAcceptedRisk FindingStatus = "accepted_risk"
	// FindingSuperseded means a newer finding replaced this one.
	FindingSuperseded FindingStatus = "superseded"
)
```

## FindingAcceptedRisk

```go
const (
	// FindingOpen means the finding still needs repair.
	FindingOpen FindingStatus = "open"
	// FindingFixed means the reviewer verified the finding as repaired.
	FindingFixed FindingStatus = "fixed"
	// FindingAcceptedRisk means a human accepted the residual risk.
	FindingAcceptedRisk FindingStatus = "accepted_risk"
	// FindingSuperseded means a newer finding replaced this one.
	FindingSuperseded FindingStatus = "superseded"
)
```

## FindingSuperseded

```go
const (
	// FindingOpen means the finding still needs repair.
	FindingOpen FindingStatus = "open"
	// FindingFixed means the reviewer verified the finding as repaired.
	FindingFixed FindingStatus = "fixed"
	// FindingAcceptedRisk means a human accepted the residual risk.
	FindingAcceptedRisk FindingStatus = "accepted_risk"
	// FindingSuperseded means a newer finding replaced this one.
	FindingSuperseded FindingStatus = "superseded"
)
```

## ModeDiscover

```go
const (
	// ModeDiscover searches broadly for new findings.
	ModeDiscover Mode = "discover"
	// ModeVerify checks whether known findings are fixed and whether repairs introduced regressions.
	ModeVerify Mode = "verify"
)
```

## ModeVerify

```go
const (
	// ModeDiscover searches broadly for new findings.
	ModeDiscover Mode = "discover"
	// ModeVerify checks whether known findings are fixed and whether repairs introduced regressions.
	ModeVerify Mode = "verify"
)
```

## SubmitToolName

```go
const (
	// SubmitToolName is the provider submission channel for review dossiers.
	SubmitToolName = "submit_review"

	// SeverityCritical marks correctness, security, data-loss, or release-stopping impact.
	SeverityCritical Severity = "critical"
	// SeverityHigh marks substantial product, architecture, or reliability impact.
	SeverityHigh Severity = "high"
	// SeverityMedium marks meaningful but bounded impact.
	SeverityMedium Severity = "medium"
	// SeverityLow marks polish, clarity, or minor maintainability impact.
	SeverityLow Severity = "low"
)
```

## SeverityCritical

```go
const (
	// SubmitToolName is the provider submission channel for review dossiers.
	SubmitToolName = "submit_review"

	// SeverityCritical marks correctness, security, data-loss, or release-stopping impact.
	SeverityCritical Severity = "critical"
	// SeverityHigh marks substantial product, architecture, or reliability impact.
	SeverityHigh Severity = "high"
	// SeverityMedium marks meaningful but bounded impact.
	SeverityMedium Severity = "medium"
	// SeverityLow marks polish, clarity, or minor maintainability impact.
	SeverityLow Severity = "low"
)
```

## SeverityHigh

```go
const (
	// SubmitToolName is the provider submission channel for review dossiers.
	SubmitToolName = "submit_review"

	// SeverityCritical marks correctness, security, data-loss, or release-stopping impact.
	SeverityCritical Severity = "critical"
	// SeverityHigh marks substantial product, architecture, or reliability impact.
	SeverityHigh Severity = "high"
	// SeverityMedium marks meaningful but bounded impact.
	SeverityMedium Severity = "medium"
	// SeverityLow marks polish, clarity, or minor maintainability impact.
	SeverityLow Severity = "low"
)
```

## SeverityMedium

```go
const (
	// SubmitToolName is the provider submission channel for review dossiers.
	SubmitToolName = "submit_review"

	// SeverityCritical marks correctness, security, data-loss, or release-stopping impact.
	SeverityCritical Severity = "critical"
	// SeverityHigh marks substantial product, architecture, or reliability impact.
	SeverityHigh Severity = "high"
	// SeverityMedium marks meaningful but bounded impact.
	SeverityMedium Severity = "medium"
	// SeverityLow marks polish, clarity, or minor maintainability impact.
	SeverityLow Severity = "low"
)
```

## SeverityLow

```go
const (
	// SubmitToolName is the provider submission channel for review dossiers.
	SubmitToolName = "submit_review"

	// SeverityCritical marks correctness, security, data-loss, or release-stopping impact.
	SeverityCritical Severity = "critical"
	// SeverityHigh marks substantial product, architecture, or reliability impact.
	SeverityHigh Severity = "high"
	// SeverityMedium marks meaningful but bounded impact.
	SeverityMedium Severity = "medium"
	// SeverityLow marks polish, clarity, or minor maintainability impact.
	SeverityLow Severity = "low"
)
```

## ErrInvalidDossier

```go
var ErrInvalidDossier = errors.New("invalid review dossier")
```

ErrInvalidDossier wraps malformed or semantically invalid provider output.

## BlocksCompletion

```go
func BlocksCompletion(finding Finding) bool
```

BlocksCompletion reports whether a finding still blocks completion.

## CanonicalResponseSHA256

```go
func CanonicalResponseSHA256(dossier Dossier) string
```

CanonicalResponseSHA256 returns the digest of the canonical serialized ReviewDossier packet. It is the value sealed into session review entries.

## DecodeDossier

```go
func DecodeDossier(text string) (Dossier, bool)
```

DecodeDossier parses a dossier recorded in a session review entry.

## DossierSchemaJSON

```go
func DossierSchemaJSON() string
```

DossierSchemaJSON returns the semantic ReviewDossier JSON Schema.

This schema is used for MCP tool input, managed docs, and operator-facing validation. It marks only semantically required fields as required while keeping additionalProperties false throughout the dossier tree.

## EncodeDossier

```go
func EncodeDossier(dossier Dossier) string
```

EncodeDossier serializes a dossier for session storage.

## NormalizeDossier

```go
func NormalizeDossier(dossier Dossier) Dossier
```

NormalizeDossier fills derived defaults without hiding invalid provider shape.

## OpenBlockerCount

```go
func OpenBlockerCount(findings []Finding) int
```

OpenBlockerCount returns the number of findings that currently block completion.

## ParseNDJSON

```go
func ParseNDJSON(text string) (Dossier, error)
```

ParseNDJSON parses newline-delimited review events into a dossier.

## ParseText

```go
func ParseText(text string) (Dossier, error)
```

ParseText parses direct JSON dossiers or NDJSON review streams.

## ParseTextCalibrated

```go
func ParseTextCalibrated(text string) (Dossier, error)
```

ParseTextCalibrated parses provider output for the accountability gate. It validates dossier shape but does not reject completion-blocking findings that lack location/evidence/validation, so the gate's calibration can downgrade unsubstantiated blockers to advisory instead of failing as an internal error.

## ResponseSHA256

```go
func ResponseSHA256(packet string) string
```

ResponseSHA256 returns the digest for an already serialized review packet.

## StrictDossierSchemaJSON

```go
func StrictDossierSchemaJSON() string
```

StrictDossierSchemaJSON returns the Codex/OpenAI structured-output variant.

OpenAI structured outputs require every object property to be listed in required, even when the property is semantically optional. Optional fields are therefore represented as nullable required fields.

## SubmitToolDescription

```go
func SubmitToolDescription() string
```

SubmitToolDescription is the canonical provider-facing review submission contract shared by MCP and protocol adapters.

## ValidAttackResult

```go
func ValidAttackResult(result AttackResult) bool
```

ValidAttackResult reports whether an attack-log result is supported.

## ValidCompletionProvider

```go
func ValidCompletionProvider(provider string) bool
```

ValidCompletionProvider reports whether a passing review provider can satisfy the completion gate for real work.

## ValidConfidence

```go
func ValidConfidence(confidence Confidence) bool
```

ValidConfidence reports whether confidence is supported by review dossiers.

## ValidFindingStatus

```go
func ValidFindingStatus(status FindingStatus) bool
```

ValidFindingStatus reports whether finding status is supported.

## ValidMode

```go
func ValidMode(mode Mode) bool
```

ValidMode reports whether mode is supported by the review gate.

## ValidSeverity

```go
func ValidSeverity(severity Severity) bool
```

ValidSeverity reports whether severity is supported by review dossiers.

## ValidVerdict

```go
func ValidVerdict(verdict string) bool
```

ValidVerdict reports whether verdict is supported by the review gate.

## ValidateDossier

```go
func ValidateDossier(dossier Dossier) error
```

ValidateDossier verifies dossier shape and the completion gate contract.

## ValidateFinding

```go
func ValidateFinding(finding Finding) error
```

ValidateFinding checks one finding's typed fields and repair context.

## VerdictFromFindings

```go
func VerdictFromFindings(findings []Finding) string
```

VerdictFromFindings derives the review verdict from open completion blockers.

## AttackLogEntry

```go
type AttackLogEntry struct {
	Target string       `json:"target"`
	Attack string       `json:"attack"`
	Result AttackResult `json:"result"`
	Notes  string       `json:"notes,omitempty"`
}
```

AttackLogEntry records one bounded attack angle the reviewer attempted.

- `Target: string` (json:"target"): 
- `Attack: string` (json:"attack"): 
- `Result: AttackResult` (json:"result"): 
- `Notes: string` (json:"notes,omitempty"): 

## AttackResult

```go
type AttackResult string
```

AttackResult names the bounded result of one review attack.

## Budget

```go
type Budget struct {
	MaxFindings        int    `json:"max_findings,omitempty"`
	MinAttackAngles    int    `json:"min_attack_angles,omitempty"`
	ActualFindings     int    `json:"actual_findings,omitempty"`
	ActualAttackAngles int    `json:"actual_attack_angles,omitempty"`
	Depth              string `json:"depth,omitempty"`
}
```

Budget records review depth and bounded output settings.

- `MaxFindings: int` (json:"max_findings,omitempty"): 
- `MinAttackAngles: int` (json:"min_attack_angles,omitempty"): 
- `ActualFindings: int` (json:"actual_findings,omitempty"): 
- `ActualAttackAngles: int` (json:"actual_attack_angles,omitempty"): 
- `Depth: string` (json:"depth,omitempty"): 

## Confidence

```go
type Confidence string
```

Confidence describes how strongly the reviewer believes a finding is real.

## Dossier

```go
type Dossier struct {
	Verdict        string           `json:"verdict"`
	Mode           Mode             `json:"mode"`
	Summary        string           `json:"summary"`
	Findings       []Finding        `json:"findings"`
	AttackLog      []AttackLogEntry `json:"attack_log"`
	Budget         Budget           `json:"budget"`
	Provider       string           `json:"provider,omitempty"`
	Model          string           `json:"model,omitempty"`
	SessionID      string           `json:"session_id,omitempty"`
	OutputFormat   string           `json:"output_format,omitempty"`
	Normalizations []string         `json:"normalizations,omitempty"`
	EventSummary   map[string]int   `json:"event_summary,omitempty"`
	Raw            string           `json:"-"`
}
```

Dossier is the normalized review-provider payload consumed by scafld.

- `Verdict: string` (json:"verdict"): 
- `Mode: Mode` (json:"mode"): 
- `Summary: string` (json:"summary"): 
- `Findings: []Finding` (json:"findings"): 
- `AttackLog: []AttackLogEntry` (json:"attack_log"): 
- `Budget: Budget` (json:"budget"): 
- `Provider: string` (json:"provider,omitempty"): 
- `Model: string` (json:"model,omitempty"): 
- `SessionID: string` (json:"session_id,omitempty"): 
- `OutputFormat: string` (json:"output_format,omitempty"): 
- `Normalizations: []string` (json:"normalizations,omitempty"): 
- `EventSummary: map[string]int` (json:"event_summary,omitempty"): 
- `Raw: string` (json:"-"): 

## Finding

```go
type Finding struct {
	ID               string        `json:"id"`
	Severity         Severity      `json:"severity"`
	BlocksCompletion bool          `json:"blocks_completion"`
	Category         string        `json:"category,omitempty"`
	Confidence       Confidence    `json:"confidence,omitempty"`
	Location         *Location     `json:"location,omitempty"`
	Evidence         string        `json:"evidence,omitempty"`
	Impact           string        `json:"impact,omitempty"`
	Reproducer       string        `json:"reproducer,omitempty"`
	SuggestedFix     string        `json:"suggested_fix,omitempty"`
	Validation       string        `json:"validation,omitempty"`
	RelatedSpec      string        `json:"related_spec,omitempty"`
	ReviewPass       string        `json:"review_pass,omitempty"`
	Status           FindingStatus `json:"status,omitempty"`
	Summary          string        `json:"summary,omitempty"`
}
```

Finding is one issue surfaced by a review provider.

- `ID: string` (json:"id"): 
- `Severity: Severity` (json:"severity"): 
- `BlocksCompletion: bool` (json:"blocks_completion"): 
- `Category: string` (json:"category,omitempty"): 
- `Confidence: Confidence` (json:"confidence,omitempty"): 
- `Location: *Location` (json:"location,omitempty"): 
- `Evidence: string` (json:"evidence,omitempty"): 
- `Impact: string` (json:"impact,omitempty"): 
- `Reproducer: string` (json:"reproducer,omitempty"): 
- `SuggestedFix: string` (json:"suggested_fix,omitempty"): 
- `Validation: string` (json:"validation,omitempty"): 
- `RelatedSpec: string` (json:"related_spec,omitempty"): 
- `ReviewPass: string` (json:"review_pass,omitempty"): 
- `Status: FindingStatus` (json:"status,omitempty"): 
- `Summary: string` (json:"summary,omitempty"): 

## FindingStatus

```go
type FindingStatus string
```

FindingStatus tracks whether a previously surfaced finding still needs work.

## Location

```go
type Location struct {
	Path string `json:"path"`
	Line int    `json:"line,omitempty"`
}
```

Location points to the primary evidence location for a finding.

- `Path: string` (json:"path"): 
- `Line: int` (json:"line,omitempty"): 

## Mode

```go
type Mode string
```

Mode describes the review pass shape.

## Request

```go
type Request struct {
	TaskID  string
	Prompt  string
	Context reviewcontext.Packet
}
```

Request is the provider-facing review prompt request.

- `TaskID: string`: 
- `Prompt: string`: 
- `Context: reviewcontext.Packet`: 

## Severity

```go
type Severity string
```

Severity names defect impact independent from whether the finding blocks task completion.