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:82

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:73

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:37

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:49

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:63

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:23

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:88

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

Functions

func BlocksCompletion(finding Finding) bool

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

BlocksCompletion reports whether a finding still blocks completion.

func CanonicalResponseSHA256(dossier Dossier) string

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

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

func DecodeDossier(text string) (Dossier, bool)

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

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:157

EncodeDossier serializes a dossier for session storage.

func NormalizeDossier(dossier Dossier) Dossier

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

NormalizeDossier fills derived defaults without hiding invalid provider shape.

func OpenBlockerCount(findings []Finding) int

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

OpenBlockerCount returns the number of findings that currently block completion.

func ParseNDJSON(text string) (Dossier, error)

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

ParseNDJSON parses newline-delimited review events into a dossier.

func ParseText(text string) (Dossier, error)

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

ParseText parses direct JSON dossiers or NDJSON review streams.

func ParseTextCalibrated(text string) (Dossier, error)

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

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.

func ResponseSHA256(packet string) string

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

ResponseSHA256 returns the digest for an already serialized review packet.

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:485

ValidAttackResult reports whether an attack-log result is supported.

func ValidCompletionProvider(provider string) bool

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

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:505

ValidConfidence reports whether confidence is supported by review dossiers.

func ValidFindingStatus(status FindingStatus) bool

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

ValidFindingStatus reports whether finding status is supported.

func ValidMode(mode Mode) bool

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

ValidMode reports whether mode is supported by the review gate.

func ValidSeverity(severity Severity) bool

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

ValidSeverity reports whether severity is supported by review dossiers.

func ValidVerdict(verdict string) bool

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

ValidVerdict reports whether verdict is supported by the review gate.

func ValidateDossier(dossier Dossier) error

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

ValidateDossier verifies dossier shape and the completion gate contract.

func ValidateFinding(finding Finding) error

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

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

func VerdictFromFindings(findings []Finding) string

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

VerdictFromFindings derives the review verdict from open completion blockers.

Types

type AttackLogEntry

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

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:69

AttackResult names the bounded result of one review attack.

type AttackResult string

type Budget

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

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:33

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

type Confidence string

type Dossier

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

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:97

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:45

FindingStatus tracks whether a previously surfaced finding still needs work.

type FindingStatus string

type Location

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

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:59

Mode describes the review pass shape.

type Mode string

type Request

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

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:19

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

type Severity string