internal/core/review

import "github.com/nilstate/scafld/v2/internal/core/review"

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

Constants

Source: internal/core/review/model.go:80

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"
)

Source: internal/core/review/model.go:71

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"
)

Source: internal/core/review/model.go:35

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"
)

Source: internal/core/review/model.go:47

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"
)

Source: internal/core/review/model.go:61

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"
)

Source: internal/core/review/model.go:21

const (
	// 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"
)

Variables

ErrInvalidDossier wraps malformed or semantically invalid provider output.

Source: internal/core/review/model.go:86

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

Functions

func BlocksCompletion(finding Finding) bool

Source: internal/core/review/model.go:193

BlocksCompletion reports whether a finding still blocks completion.

func DecodeDossier(text string) (Dossier, bool)

Source: internal/core/review/model.go:167

DecodeDossier parses a dossier recorded in a session review entry.

func DossierSchemaJSON() string

Source: internal/core/review/schema.go:15

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.

func EncodeDossier(dossier Dossier) string

Source: internal/core/review/model.go:155

EncodeDossier serializes a dossier for session storage.

func NormalizeDossier(dossier Dossier) Dossier

Source: internal/core/review/model.go:315

NormalizeDossier fills derived defaults without hiding invalid provider shape.

func OpenBlockerCount(findings []Finding) int

Source: internal/core/review/model.go:182

OpenBlockerCount returns the number of findings that currently block completion.

func ParseNDJSON(text string) (Dossier, error)

Source: internal/core/review/model.go:237

ParseNDJSON parses newline-delimited review events into a dossier.

func ParseText(text string) (Dossier, error)

Source: internal/core/review/model.go:219

ParseText parses direct JSON dossiers or NDJSON review streams.

func StrictDossierSchemaJSON() string

Source: internal/core/review/schema.go:28

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.

func ValidAttackResult(result AttackResult) bool

Source: internal/core/review/model.go:432

ValidAttackResult reports whether an attack-log result is supported.

func ValidCompletionProvider(provider string) bool

Source: internal/core/review/model.go:209

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

func ValidConfidence(confidence Confidence) bool

Source: internal/core/review/model.go:452

ValidConfidence reports whether confidence is supported by review dossiers.

func ValidFindingStatus(status FindingStatus) bool

Source: internal/core/review/model.go:462

ValidFindingStatus reports whether finding status is supported.

func ValidMode(mode Mode) bool

Source: internal/core/review/model.go:422

ValidMode reports whether mode is supported by the review gate.

func ValidSeverity(severity Severity) bool

Source: internal/core/review/model.go:442

ValidSeverity reports whether severity is supported by review dossiers.

func ValidVerdict(verdict string) bool

Source: internal/core/review/model.go:412

ValidVerdict reports whether verdict is supported by the review gate.

func ValidateDossier(dossier Dossier) error

Source: internal/core/review/model.go:337

ValidateDossier verifies dossier shape and the completion gate contract.

func ValidateFinding(finding Finding) error

Source: internal/core/review/model.go:371

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

func VerdictFromFindings(findings []Finding) string

Source: internal/core/review/model.go:402

VerdictFromFindings derives the review verdict from open completion blockers.

Types

type AttackLogEntry

Source: internal/core/review/model.go:114

AttackLogEntry records one bounded attack angle the reviewer attempted.

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

Fields

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

type AttackResult

Source: internal/core/review/model.go:67

AttackResult names the bounded result of one review attack.

type AttackResult string

type Budget

Source: internal/core/review/model.go:122

Budget records review depth and bounded output settings.

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"`
}

Fields

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"`

type Confidence

Source: internal/core/review/model.go:31

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

type Confidence string

type Dossier

Source: internal/core/review/model.go:131

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

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:"-"`
}

Fields

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:"-"`

type Finding

Source: internal/core/review/model.go:95

Finding is one issue surfaced by a review provider.

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"`
}

Fields

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"`

type FindingStatus

Source: internal/core/review/model.go:43

FindingStatus tracks whether a previously surfaced finding still needs work.

type FindingStatus string

type Location

Source: internal/core/review/model.go:89

Location points to the primary evidence location for a finding.

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

Fields

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

type Mode

Source: internal/core/review/model.go:57

Mode describes the review pass shape.

type Mode string

type Request

Source: internal/core/review/model.go:148

Request is the provider-facing review prompt request.

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

Fields

TaskID string
Prompt string
Context reviewcontext.Packet

type Severity

Source: internal/core/review/model.go:17

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

type Severity string