# internal/core/reviewgate

Package reviewgate projects review-attempt and review evidence into the single gate state used by review, status, handoff, and completion commands.

## EntryReviewAttempt

```go
const (
	// EntryReviewAttempt records a leased provider review lifecycle attempt.
	EntryReviewAttempt = "review_attempt"

	AttemptStatusRunning   = "running"
	AttemptStatusAccepted  = "accepted"
	AttemptStatusFailed    = "failed"
	AttemptStatusAbandoned = "abandoned"

	DefaultAttemptLease = 2 * time.Hour
)
```

## AttemptStatusRunning

```go
const (
	// EntryReviewAttempt records a leased provider review lifecycle attempt.
	EntryReviewAttempt = "review_attempt"

	AttemptStatusRunning   = "running"
	AttemptStatusAccepted  = "accepted"
	AttemptStatusFailed    = "failed"
	AttemptStatusAbandoned = "abandoned"

	DefaultAttemptLease = 2 * time.Hour
)
```

## AttemptStatusAccepted

```go
const (
	// EntryReviewAttempt records a leased provider review lifecycle attempt.
	EntryReviewAttempt = "review_attempt"

	AttemptStatusRunning   = "running"
	AttemptStatusAccepted  = "accepted"
	AttemptStatusFailed    = "failed"
	AttemptStatusAbandoned = "abandoned"

	DefaultAttemptLease = 2 * time.Hour
)
```

## AttemptStatusFailed

```go
const (
	// EntryReviewAttempt records a leased provider review lifecycle attempt.
	EntryReviewAttempt = "review_attempt"

	AttemptStatusRunning   = "running"
	AttemptStatusAccepted  = "accepted"
	AttemptStatusFailed    = "failed"
	AttemptStatusAbandoned = "abandoned"

	DefaultAttemptLease = 2 * time.Hour
)
```

## AttemptStatusAbandoned

```go
const (
	// EntryReviewAttempt records a leased provider review lifecycle attempt.
	EntryReviewAttempt = "review_attempt"

	AttemptStatusRunning   = "running"
	AttemptStatusAccepted  = "accepted"
	AttemptStatusFailed    = "failed"
	AttemptStatusAbandoned = "abandoned"

	DefaultAttemptLease = 2 * time.Hour
)
```

## DefaultAttemptLease

```go
const (
	// EntryReviewAttempt records a leased provider review lifecycle attempt.
	EntryReviewAttempt = "review_attempt"

	AttemptStatusRunning   = "running"
	AttemptStatusAccepted  = "accepted"
	AttemptStatusFailed    = "failed"
	AttemptStatusAbandoned = "abandoned"

	DefaultAttemptLease = 2 * time.Hour
)
```

## KindReadyForReview

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindAttemptRunning

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindAttemptStale

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindAttemptFailed

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindReviewFailed

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindReviewNeedsOperatorDecision

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindReviewPassed

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindReviewStaleAfterBuild

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindReviewStaleAfterSpec

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindReviewStaleAfterWorkspace

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindCompletedAuthorized

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## KindInvalid

```go
const (
	KindReadyForReview              Kind = "ready_for_review"
	KindAttemptRunning              Kind = "attempt_running"
	KindAttemptStale                Kind = "attempt_stale"
	KindAttemptFailed               Kind = "attempt_failed"
	KindReviewFailed                Kind = "review_failed"
	KindReviewNeedsOperatorDecision Kind = "review_needs_operator_decision"
	KindReviewPassed                Kind = "review_passed"
	KindReviewStaleAfterBuild       Kind = "review_stale_after_build"
	KindReviewStaleAfterSpec        Kind = "review_stale_after_spec"
	KindReviewStaleAfterWorkspace   Kind = "review_stale_after_workspace"
	KindCompletedAuthorized         Kind = "completed_authorized"
	KindInvalid                     Kind = "invalid"
)
```

## AbandonedAttemptEntry

```go
func AbandonedAttemptEntry(attempt Attempt, reason string) session.Entry
```

AbandonedAttemptEntry closes a stale running attempt before a new attempt starts.

## AcceptedAttemptEntry

```go
func AcceptedAttemptEntry(attempt Attempt, reason string) session.Entry
```

AcceptedAttemptEntry explicitly closes a provider attempt that produced an accepted ReviewDossier. The following review entry carries the authority.

## CurrentReviewGate

```go
func CurrentReviewGate(ledger session.Session) Authority
```

CurrentReviewGate validates the latest review gate that can currently authorize completion. Later build, criterion, phase, approval, fail, cancel, baseline, or review-attempt evidence invalidates older reviews.

## DecodeAttempt

```go
func DecodeAttempt(entry session.Entry, opts Options) Attempt
```

DecodeAttempt normalizes attempt metadata from a session entry.

## EntryReference

```go
func EntryReference(entry session.Entry) string
```

EntryReference returns a stable human-readable evidence reference.

## FailedAttemptEntry

```go
func FailedAttemptEntry(attempt Attempt, reason string, diagnosticPath string) session.Entry
```

FailedAttemptEntry closes a provider attempt that did not produce an accepted dossier.

## LatestAttempt

```go
func LatestAttempt(ledger session.Session, opts Options) (Attempt, bool)
```

LatestAttempt returns the newest review attempt in the current review window.

## NewAttemptID

```go
func NewAttemptID(taskID string, now time.Time) string
```

NewAttemptID returns a deterministic attempt identifier for the task and start time.

## Project

```go
func Project(ledger session.Session, model spec.Model, opts Options) State
```

Project reduces a session ledger plus current task state into the review gate state. Readers should treat this as read-only; mutating commands append recovery entries based on the projected state.

## RepairPacketCommand

```go
func RepairPacketCommand(taskID string, path string) string
```

RepairPacketCommand records a locally repaired ReviewDossier without spending another external review call.

## ReviewRerunMaterialScope

```go
func ReviewRerunMaterialScope(ledger session.Session) []string
```

ReviewRerunMaterialScope returns the scope needed to decide whether a post-build review rerun is meaningful after a failed review. An empty result means no current failed-review repair window needs material comparison.

## RunningAttemptEntry

```go
func RunningAttemptEntry(input AttemptEntryInput) session.Entry
```

RunningAttemptEntry builds the opening review\_attempt entry.

## TerminalAuthority

```go
func TerminalAuthority(ledger session.Session) Authority
```

TerminalAuthority validates the review gate that authorized the latest complete event in an archived task ledger.

## Attempt

```go
type Attempt struct {
	Entry                  session.Entry
	AttemptID              string
	Status                 string
	Running                bool
	Stale                  bool
	LeaseExpiresAt         time.Time
	HasLease               bool
	Provider               string
	Model                  string
	Mode                   corereview.Mode
	PassCount              int
	Reason                 string
	DiagnosticPath         string
	ReviewedHead           string
	ReviewedDirty          string
	ReviewedDiff           string
	ReviewedSpec           string
	ReviewedScope          []string
	ReviewedMaterialDigest string
}
```

Attempt is normalized metadata for the latest current review attempt.

- `Entry: session.Entry`: 
- `AttemptID: string`: 
- `Status: string`: 
- `Running: bool`: 
- `Stale: bool`: 
- `LeaseExpiresAt: time.Time`: 
- `HasLease: bool`: 
- `Provider: string`: 
- `Model: string`: 
- `Mode: corereview.Mode`: 
- `PassCount: int`: 
- `Reason: string`: 
- `DiagnosticPath: string`: 
- `ReviewedHead: string`: 
- `ReviewedDirty: string`: 
- `ReviewedDiff: string`: 
- `ReviewedSpec: string`: 
- `ReviewedScope: []string`: 
- `ReviewedMaterialDigest: string`: 

## AttemptEntryInput

```go
type AttemptEntryInput struct {
	AttemptID              string
	LeaseExpiresAt         time.Time
	Mode                   corereview.Mode
	Provider               string
	Model                  string
	PassCount              int
	Reason                 string
	Output                 string
	ReviewedHead           string
	ReviewedDirty          string
	ReviewedDiff           string
	ReviewedSpec           string
	ReviewedScope          []string
	ReviewedMaterialDigest string
}
```

AttemptEntryInput contains the typed metadata stamped onto review\_attempt entries.

- `AttemptID: string`: 
- `LeaseExpiresAt: time.Time`: 
- `Mode: corereview.Mode`: 
- `Provider: string`: 
- `Model: string`: 
- `PassCount: int`: 
- `Reason: string`: 
- `Output: string`: 
- `ReviewedHead: string`: 
- `ReviewedDirty: string`: 
- `ReviewedDiff: string`: 
- `ReviewedSpec: string`: 
- `ReviewedScope: []string`: 
- `ReviewedMaterialDigest: string`: 

## Authority

```go
type Authority struct {
	Found          bool
	Completed      bool
	Valid          bool
	OverrideReason string
	HumanReviewed  bool
	Reason         string
	Actual         string
	Evidence       []string
	ReviewEntry    session.Entry
	ReceiptEntry   session.Entry
	CompleteEntry  session.Entry
	Dossier        corereview.Dossier
	HasDossier     bool
	Receipt        receipt.Envelope
	HasReceipt     bool
}
```

Authority describes the review evidence that authorizes completion.

- `Found: bool`: 
- `Completed: bool`: 
- `Valid: bool`: 
- `OverrideReason: string`: 
- `HumanReviewed: bool`: 
- `Reason: string`: 
- `Actual: string`: 
- `Evidence: []string`: 
- `ReviewEntry: session.Entry`: 
- `ReceiptEntry: session.Entry`: 
- `CompleteEntry: session.Entry`: 
- `Dossier: corereview.Dossier`: 
- `HasDossier: bool`: 
- `Receipt: receipt.Envelope`: 
- `HasReceipt: bool`: 

## Kind

```go
func (a Authority) Kind() string
```

Kind returns a stable label for the completion authority.

## Provider

```go
func (a Authority) Provider() string
```

Provider returns the provider that produced the authorizing review.

## RefusalSuffix

```go
func (a Authority) RefusalSuffix() string
```

RefusalSuffix summarizes terminal authority for commands that cannot operate on archived work.

## Status

```go
func (a Authority) Status() string
```

Status returns valid or invalid for display surfaces.

## Summary

```go
func (a Authority) Summary() string
```

Summary returns the best available human-readable authority summary.

## Verdict

```go
func (a Authority) Verdict() string
```

Verdict returns the authorizing review verdict.

## Kind

```go
type Kind string
```

Kind is the stable review gate projection state.

## Options

```go
type Options struct {
	Now              time.Time
	AttemptLease     time.Duration
	WorkspaceSeal    WorkspaceSeal
	HasWorkspaceSeal bool
	MaterialSeal     reviewevidence.MaterialSeal
	HasMaterialSeal  bool
}
```

Options configures review gate projection.

- `Now: time.Time`: 
- `AttemptLease: time.Duration`: 
- `WorkspaceSeal: WorkspaceSeal`: 
- `HasWorkspaceSeal: bool`: 
- `MaterialSeal: reviewevidence.MaterialSeal`: 
- `HasMaterialSeal: bool`: 

## State

```go
type State struct {
	Kind                     Kind
	TaskID                   string
	Reason                   string
	Actual                   string
	Next                     string
	Evidence                 []string
	Blockers                 []string
	CanStartReview           bool
	ShouldAbandonAttempt     bool
	ReviewBlockedUntilBuild  bool
	ReviewRerunBlocked       bool
	OperatorDecisionRequired bool
	Authority                Authority
	LatestAttempt            Attempt
	HasAttempt               bool
	LatestReview             session.Entry
	HasReview                bool
	Dossier                  corereview.Dossier
	HasDossier               bool
	PriorFailedReview        session.Entry
	HasPriorFailedReview     bool
	PriorFailedDossier       corereview.Dossier
	HasPriorFailedDossier    bool
	BlockerFingerprints      []string
}
```

State is the single read model for review gate lifecycle decisions.

- `Kind: Kind`: 
- `TaskID: string`: 
- `Reason: string`: 
- `Actual: string`: 
- `Next: string`: 
- `Evidence: []string`: 
- `Blockers: []string`: 
- `CanStartReview: bool`: 
- `ShouldAbandonAttempt: bool`: 
- `ReviewBlockedUntilBuild: bool`: 
- `ReviewRerunBlocked: bool`: 
- `OperatorDecisionRequired: bool`: 
- `Authority: Authority`: 
- `LatestAttempt: Attempt`: 
- `HasAttempt: bool`: 
- `LatestReview: session.Entry`: 
- `HasReview: bool`: 
- `Dossier: corereview.Dossier`: 
- `HasDossier: bool`: 
- `PriorFailedReview: session.Entry`: 
- `HasPriorFailedReview: bool`: 
- `PriorFailedDossier: corereview.Dossier`: 
- `HasPriorFailedDossier: bool`: 
- `BlockerFingerprints: []string`: 

## WorkspaceSeal

```go
type WorkspaceSeal struct {
	Head  string
	Dirty string
	Diff  string
}
```

WorkspaceSeal is the current workspace seal used to decide whether a passing review still covers the files being completed.

- `Head: string`: 
- `Dirty: string`: 
- `Diff: string`: