programreport

Documentation

Overview

Package programreport folds the project's ONGOING PROGRAMS — the work classes internal/worktype marks as never-"done" frontiers (kernel-optimization cache-optimization, and human-operator-effectiveness) — into one read-only report envelope with a durable JSONL trend ledger. It is the ongoing-program sibling of internal/milestonereport.

The distinction the two reports draw together (see internal/worktype for the law):

• milestonereport's ROADMAP measures DISCRETE epics by child-completion % — the right lens for a deliverable that converges on 100% and closes.
• programreport measures the ONGOING programs by a FRONTIER + a TREND — the right lens for a process that is never done. There is no completion % here on purpose; a "60% complete" line on kernel-opt, cache-opt, or human-steerability is a category error.

The program frontier signals (WITNESSED, never self-reported):

• KERNEL OPTIMIZATION — the trailing-window count of ships stamped on a perf/kernel leaf (the decode/prefill/quant/parity lanes), read from git through the SAME hooks.StampOf grammar the pre-commit lint binds to. It is an activity proxy, honestly labeled: it asserts the program is being worked, not a tok/s number (the throughput claim lives in the benchmark authority rows). A quiet window is HOLDING, not regressed.
• CACHE OPTIMIZATION — the realized KV-reuse ratio over the dogfood cache-value ledger, read through cachevalueledger's #1066-fenced trend gate (the same gate `fak cachevalue` enforces, so the two never disagree). The honesty fence (the marginal-over-tuned-warm-KV value family) is carried onto the signal.
• HUMAN OPERATOR EFFECTIVENESS — the operator-heaviness lightness proxy, read from the source-reading scorecard: max(0, 100 - heaviness_pressure), forced to zero when hard heaviness_debt exists. It is a first deterministic proxy for "can a human still steer this system without drowning in the surface?".

The report is a REPORT CONTRACT, not a second quality gate (the milestonereport posture): --check fails ONLY when the programs dimension could not be MEASURED. A regressed frontier is a MEASURED fact surfaced as an advisory line; the per-program ratchet (the cache-value trend gate, the perf-parity RSI loop) owns the real gate.

The pure surface (the interpreter, the fold, the ledger parse/trend, render, gate) lives in programreport.go and is unit-testable with no process and no repo. The impure runners (the cache-value ledger read, the perf-lane git window, and the operator-heaviness source read) live in collect.go.

Index

• Constants
• Variables
• func AppendLedgerLine(row LedgerRow) (string, error)
• func CheckDogfoodGate(r DogfoodCorpusResult) (code int, summary string)
• func CheckGate(r Report) (int, string)
• func CheckGateTriaged(r Report, enforce bool) (int, string)
• func CheckJudgeGate(v JudgeVerdict) (code int, summary string)
• func CheckReviewGate(v ReviewVerdict) (code int, summary string)
• func DogfoodCorpusDigest(c DogfoodCorpus) string
• func HeadCommit(root string) string
• func InterRaterAgreement(cases []ReviewCase) (fraction float64, pairs int, ok bool)
• func JudgeCorpusCalibrated(cases []JudgeCase) (ok bool, reason string)
• func MarshalDogfoodCorpus(c DogfoodCorpus) ([]byte, error)
• func MarshalJudgeCase(c JudgeCase) ([]byte, error)
• func MarshalReviewCase(c ReviewCase) ([]byte, error)
• func Render(r Report) string
• func SeedSetCalibrated(cases []ReviewCase) (ok bool, fraction float64, reason string)
• func SummaryOf(r Report) string
• func TriageSelfcheck() error
• type DogfoodCase
• type DogfoodCaseResult
• type DogfoodCorpus
  • func SeedDogfoodCorpus() DogfoodCorpus
  • func UnmarshalDogfoodCorpus(b []byte) (DogfoodCorpus, error)
  • func (c DogfoodCorpus) Validate() error
• type DogfoodCorpusResult
  • func GradeDogfoodCorpus(c DogfoodCorpus) DogfoodCorpusResult
• type FoldOpts
• type HeldOutRating
• type JudgeAxis
• type JudgeCase
  • func UnmarshalJudgeCase(b []byte) (JudgeCase, error)
  • func (c JudgeCase) ValidateJudge() error
• type JudgeMetrics
• type JudgeReplay
• type JudgeVerdict
  • func ReviewJudge(c JudgeCase) JudgeVerdict
• type LedgerRow
  • func ParseLedger(content string) []LedgerRow
  • func RowFromReport(r Report) LedgerRow
• type PairProbe
• type ParaphraseProbe
• type Programs
  • func Collect(root, cacheLedgerPath string, windowDays int) Programs
  • func InterpretPrograms(signals []Signal) Programs
• type RaterScores
• type ReplayArtifact
• type Report
  • func Fold(p Programs, opts FoldOpts) Report
  • func (r Report) WithGate(code int, message string) Report
  • func (r Report) WithTrend(t Trend) Report
• type ReviewCase
  • func UnmarshalReviewCase(b []byte) (ReviewCase, error)
  • func (c ReviewCase) Validate() error
• type ReviewDimension
• type ReviewProvenance
• type ReviewTier
• type ReviewVerdict
  • func Review(c ReviewCase) ReviewVerdict
• type Signal
• type StateCapture
• type Trend
  • func TrendVsLast(row LedgerRow, prior []LedgerRow) Trend
• type VerbosityProbe

Constants

const (
	ExpectPass = "pass"
	ExpectFail = "fail"
)

Expectation values a dogfood case may declare. ExpectFail marks a currently suspected report defect (a failing-before-fix case); ExpectPass marks a summary the raters judged adequate.

const AgreementTolerance = 1

AgreementTolerance is the largest absolute gap two raters may show on a 1-5 axis and still count as agreeing. A five-point anchored scale tolerates ±1 (adjacent anchors); a gap of 2+ is a genuine disagreement to escalate, not a difference to average away.

const DeclaredAgreementFloor = 0.80

DeclaredAgreementFloor is the minimum pooled within-tolerance inter-rater agreement a blinded seed set must reach to be admissible as a calibrated review corpus (the issue's "blinded seed set reaches declared inter-rater agreement"). It is a property of the CORPUS, checked once at admission.

const DefaultBiasTolerance = 0.75

DefaultBiasTolerance is the largest absolute mean signed (judge − expert) error a judge may carry on the held-out set. It is below 1.0 on purpose: a full-point systematic skew is a bias to fix, not to average away, even if per-item agreement is otherwise within the ±1 band.

const DefaultCorrelationFloor = 0.80

DefaultCorrelationFloor is the minimum within-tolerance agreement a judge must reach against the held-out expert ratings to be admissible. It mirrors reviewrubric.go's DeclaredAgreementFloor: a judge that agrees with the experts on fewer than 80% of held-out items is not a calibrated stand-in.

const DefaultLedgerRel = "docs/programs/history.jsonl"

DefaultLedgerRel is the committed, append-only history ledger (one JSONL row per program tick). It lives under docs/ so it is durable trunk evidence, not a regenerable build artifact.

const DefaultReviewPassFloor = 4

DefaultReviewPassFloor is the consensus rating an axis must reach for a case to pass when the case does not set its own PassFloor. 4 is the "adequate" anchor across every axis (grounded / covers every program / leads with the decision / runnable / clear / verdict matches); 3 and below are partial.

const DefaultWindowDays = 7

DefaultWindowDays is the trailing window the kernel-opt activity signal counts over.

const DogfoodCorpusSchema = "fak-program-report-dogfood-corpus/1"

DogfoodCorpusSchema is the versioned envelope tag of the dogfood corpus. A reader handed a different schema refuses it rather than guessing.

const JudgeReplaySchema = "fak-program-report-judge-replay/1"

JudgeReplaySchema tags the scrubbed replay artifact a failing judge case emits.

const JudgeSchema = "fak-program-report-judge/1"

JudgeSchema is the versioned envelope tag of a judge-validation case; a reader handed a different schema refuses it rather than grading an unversioned corpus.

const LedgerSchema = "fak-program-ledger/1"

LedgerSchema tags each durable history row so a reader can validate the line.

const ReplaySchema = "fak-program-report-replay/1"

ReplaySchema tags the scrubbed replay artifact a failing case emits.

const ReviewSchema = "fak-program-report-review/1"

ReviewSchema is the versioned envelope tag of a review case. A reader that is handed a different schema refuses it rather than guessing — an unversioned or wrong-versioned corpus is not silently graded.

const Schema = "fak-program-report/1"

Schema is the stable control-pane schema identifier for the report envelope.

Variables

var JudgeAxes = []JudgeAxis{Position, Repeatability, Verbosity, Bias, Correlation, Escalation}

JudgeAxes is the fixed, ordered axis set. Canonical order is the first-divergence order: a failing case is attributed to the earliest axis here that diverges, so attribution is deterministic.

var ReviewDimensions = []ReviewDimension{
	Grounding, Completeness, Salience, Actionability, Clarity, Calibration,
}

ReviewDimensions is the fixed, ordered axis set (#4562 scope). Canonical order is also the first-divergence order: a failing case is attributed to the earliest axis in this slice that diverges, so attribution is deterministic.

Functions

func AppendLedgerLine

func AppendLedgerLine(row LedgerRow) (string, error)

AppendLedgerLine renders the JSONL line for a row (no trailing newline).

func CheckDogfoodGate

func CheckDogfoodGate(r DogfoodCorpusResult) (code int, summary string)

CheckDogfoodGate maps a corpus result to a process exit and a one-line summary, the shape the report family's CheckGate uses: 0 on pass, 1 on any non-pass. A non-pass always names the first diverging case (or the admission failure), so a CI caller can route on the reason without re-deriving it.

func CheckGate

func CheckGate(r Report) (int, string)

CheckGate is the advisory CI gate over a folded report. It fails ONLY when the programs dimension could not be measured — the report is a mirror, not a second quality gate (a regressed frontier is a measured fact, not an incomplete report).

0  programs recorded (clear or advisory)
1  the programs dimension failed to measure

func CheckGateTriaged

func CheckGateTriaged(r Report, enforce bool) (int, string)

CheckGateTriaged is CheckGate with the decenter-the-human fold applied at the source: an INCOMPLETE report whose NextAction is a runnable rerun routes to the fleet instead of paging. Soaks behind enforce (the CLI reads FAK_PROGRAM_TRIAGE_GATE); enforce=false is byte-for-byte CheckGate.

func CheckJudgeGate

func CheckJudgeGate(v JudgeVerdict) (code int, summary string)

CheckJudgeGate maps a verdict to a process exit and a one-line summary — the report family's CheckGate shape: 0 on pass, 1 on any non-pass. A non-pass always carries a first divergence (or the "invalid" kind).

func CheckReviewGate

func CheckReviewGate(v ReviewVerdict) (code int, summary string)

CheckReviewGate maps a verdict to a process exit and a one-line summary, the shape the report family's CheckGate uses: 0 on pass, 1 on any non-pass. A non-pass ALWAYS carries a first divergence (or the "invalid" kind), so a CI caller can route on the reason without re-deriving it.

func DogfoodCorpusDigest

func DogfoodCorpusDigest(c DogfoodCorpus) string

DogfoodCorpusDigest computes the canonical content digest of a corpus (the Digest field itself excluded). Case order is significant — it is the first-divergence order — so it is hashed as-is, not sorted.

func HeadCommit

func HeadCommit(root string) string

HeadCommit returns the short HEAD commit of root, or "unknown" — inlined git plumbing so this tier-1 leaf imports no sibling composer (the milestonereport pattern).

func InterRaterAgreement

func InterRaterAgreement(cases []ReviewCase) (fraction float64, pairs int, ok bool)

InterRaterAgreement is the corpus-level calibration statistic: the pooled fraction of rater pairs, across every axis of every case, that agree within tolerance. ok is false when the set carries no comparable pairs (fewer than two raters everywhere) — an empty set cannot "reach" an agreement floor, so it fails closed rather than reporting a vacuous 1.0.

func JudgeCorpusCalibrated

func JudgeCorpusCalibrated(cases []JudgeCase) (ok bool, reason string)

JudgeCorpusCalibrated reports whether a set of judge cases is admissible as a validated judge corpus: every case validates AND passes. It fails closed — an empty set, an invalid case, or any non-pass case is not calibrated.

func MarshalDogfoodCorpus

func MarshalDogfoodCorpus(c DogfoodCorpus) ([]byte, error)

MarshalDogfoodCorpus / UnmarshalDogfoodCorpus round-trip the corpus through its versioned envelope; the unmarshaler refuses an unknown schema so a mis-versioned corpus is rejected rather than graded.

func MarshalJudgeCase

func MarshalJudgeCase(c JudgeCase) ([]byte, error)

MarshalJudgeCase / UnmarshalJudgeCase round-trip a case through its versioned envelope; the unmarshaler refuses an unknown schema so a mis-versioned corpus is rejected rather than graded.

func MarshalReviewCase

func MarshalReviewCase(c ReviewCase) ([]byte, error)

MarshalReviewCase / UnmarshalReviewCase round-trip a case through its versioned envelope; the unmarshaler refuses an unknown schema so a mis-versioned corpus is rejected rather than graded.

func Render

func Render(r Report) string

Render produces the human snapshot.

func SeedSetCalibrated

func SeedSetCalibrated(cases []ReviewCase) (ok bool, fraction float64, reason string)

SeedSetCalibrated reports whether a blinded seed set is admissible as a calibrated review corpus: every case validates AND the pooled inter-rater agreement reaches DeclaredAgreementFloor. It fails closed — an empty set, an invalid case, or too few pairs is not calibrated.

func SummaryOf

func SummaryOf(r Report) string

SummaryOf renders the decision-support narrative a folded program report puts in front of an operator — the Reason + NextAction prose this rubric grades. It is the in-package subject the #4562 review contract is calibrated on.

func TriageSelfcheck

func TriageSelfcheck() error

TriageSelfcheck proves the program report's source-level page-vs-act fold with no I/O, delegating to the shared trendreport proof.

Types

type DogfoodCase

type DogfoodCase struct {
	Review ReviewCase   `json:"review"`
	State  StateCapture `json:"state"`
	// Expect is ExpectPass or ExpectFail. An ExpectFail case is a currently
	// suspected defect: it MUST fail with ExpectDivergence as its first
	// actionable divergence until the underlying report defect is fixed and the
	// case is re-captured at a new corpus revision.
	Expect string `json:"expect"`
	// ExpectDivergence names the suspected defect's axis (required iff
	// Expect == ExpectFail).
	ExpectDivergence ReviewDimension `json:"expect_divergence,omitempty"`
	// DefectRef names the suspected defect an ExpectFail case tracks — the
	// failure mode observed on the report surface, so the case stays actionable
	// after the person who captured it moves on.
	DefectRef string `json:"defect_ref,omitempty"`
}

DogfoodCase is one corpus entry: a review case (summary + provenance + tier + cost + blind ratings, the #4562 contract) plus the captured project state it summarizes and the property the corpus expects of it.

type DogfoodCaseResult

type DogfoodCaseResult struct {
	CaseID   string        `json:"case_id"`
	Expect   string        `json:"expect"`
	Verdict  ReviewVerdict `json:"verdict"`
	Holding  bool          `json:"holding"`
	Diverged bool          `json:"diverged"`
	Reason   string        `json:"reason"`
}

DogfoodCaseResult is one graded corpus entry: the rubric verdict plus whether the case matched its declared expectation. Holding means an expected-fail case still fails on its suspected axis — the defect reproduces, which is the healthy before-fix state.

type DogfoodCorpus

type DogfoodCorpus struct {
	Schema   string        `json:"schema"`
	Revision string        `json:"revision"` // corpus content revision, bumped on any case change
	Cases    []DogfoodCase `json:"cases"`
	Digest   string        `json:"digest"`
}

DogfoodCorpus is the versioned corpus envelope: schema, revision, the cases, and a content digest so a serialized corpus mutated after capture is refused rather than graded.

func SeedDogfoodCorpus

func SeedDogfoodCorpus() DogfoodCorpus

SeedDogfoodCorpus is corpus revision 2026-07-13.1: five representative cases captured from this repo's executive-report surfaces (the programreport / milestonereport rollup narratives graded by #4562). The three ExpectFail cases are the currently-suspected defect classes observed on those surfaces — unsupported claims, omitted regressions, buried priorities (the exact failure modes #4550 names as what exact-string correctness misses) — captured as failing-before-fix cases. The two ExpectPass cases pin the adequate shape, including one whose state carries genuine ambiguity the summary must hedge. Tiers span pr / nightly / release; every case documents its rating cost.

func UnmarshalDogfoodCorpus

func UnmarshalDogfoodCorpus(b []byte) (DogfoodCorpus, error)

func (DogfoodCorpus) Validate

func (c DogfoodCorpus) Validate() error

Validate is the corpus admission gate; it fails closed at every boundary so an ill-formed corpus can never be graded: wrong schema, missing revision, stale or tampered digest, no cases, duplicate case ids, an invalid case (schema/provenance/tier/cost/raters — the #4562 boundaries), an ill-formed expectation, or a blinded rater set below the declared inter-rater agreement floor (an uncalibrated corpus is not evidence).

type DogfoodCorpusResult

type DogfoodCorpusResult struct {
	Schema          string              `json:"schema"`
	Revision        string              `json:"revision"`
	Pass            bool                `json:"pass"`
	Cases           []DogfoodCaseResult `json:"cases"`
	FirstDivergence string              `json:"first_divergence,omitempty"` // case id
	Reason          string              `json:"reason"`
	Replay          *ReplayArtifact     `json:"replay,omitempty"` // present iff Pass is false
}

DogfoodCorpusResult is the corpus-level grade. Pass means every case matched its expectation: passing cases pass, and every suspected defect still reproduces on its declared axis. The first case (corpus order) that diverges from its expectation sets FirstDivergence and carries a scrubbed replay.

func GradeDogfoodCorpus

func GradeDogfoodCorpus(c DogfoodCorpus) DogfoodCorpusResult

GradeDogfoodCorpus grades every case with the #4562 Review contract and adjudicates each against its expectation. It fails closed: an invalid corpus never passes, an expected-fail case that PASSES is a corpus failure (a silently-green before-fix case), and an expected-fail case whose first actionable divergence moved off the suspected axis is a corpus failure (attribution drifted — the case no longer tracks its defect).

type FoldOpts

type FoldOpts struct {
	Workspace   string
	Commit      string
	GeneratedAt string
	Date        string
}

FoldOpts carries the ambient context the fold stamps onto the envelope.

type HeldOutRating

type HeldOutRating struct {
	ItemID      string `json:"item_id"`
	JudgeScore  int    `json:"judge_score"`
	ExpertScore int    `json:"expert_score"`
	Confidence  string `json:"confidence"` // "high" | "low"
	Escalated   bool   `json:"escalated"`
}

HeldOutRating pairs a judge's score with the expert consensus on a held-out summary the judge did not calibrate on, plus the judge's self-reported confidence and whether the case escalated to human review.

type JudgeAxis

type JudgeAxis string

JudgeAxis is one validation axis of the judge contract.

const (
	Position      JudgeAxis = "position"      // order-swap stability
	Repeatability JudgeAxis = "repeatability" // paraphrase stability
	Verbosity     JudgeAxis = "verbosity"     // no length premium
	Bias          JudgeAxis = "bias"          // signed error vs expert
	Correlation   JudgeAxis = "correlation"   // held-out agreement vs expert
	Escalation    JudgeAxis = "escalation"    // low confidence escalates
)

type JudgeCase

type JudgeCase struct {
	Schema           string            `json:"schema"`
	ID               string            `json:"id"`
	Judge            string            `json:"judge"` // identifier of the LLM judge under validation
	Provenance       ReviewProvenance  `json:"provenance"`
	Tier             ReviewTier        `json:"tier"`
	CostNote         string            `json:"cost_note"`
	Positions        []PairProbe       `json:"positions"`
	Paraphrases      []ParaphraseProbe `json:"paraphrases"`
	Verbosities      []VerbosityProbe  `json:"verbosities"`
	HeldOut          []HeldOutRating   `json:"held_out"`
	Tolerance        int               `json:"tolerance,omitempty"`         // 0 => AgreementTolerance
	CorrelationFloor float64           `json:"correlation_floor,omitempty"` // 0 => DefaultCorrelationFloor
	BiasTolerance    float64           `json:"bias_tolerance,omitempty"`    // 0 => DefaultBiasTolerance
}

JudgeCase is one judge-validation case: the judge under validation, its replay-complete provenance, tier and documented cost, and the recorded probe evidence on each axis.

func UnmarshalJudgeCase

func UnmarshalJudgeCase(b []byte) (JudgeCase, error)

func (JudgeCase) ValidateJudge

func (c JudgeCase) ValidateJudge() error

ValidateJudge is the structural admission gate. It fails closed at every boundary: wrong schema, empty id/judge, incomplete provenance, an unassigned tier, an undocumented cost, an out-of-range probe score, a malformed pair winner, or a held-out row with an unknown confidence label. Axis EMPTINESS is NOT rejected here — it is adjudicated as an inconclusive divergence by ReviewJudge, so a failing case still names the missing axis.

type JudgeMetrics

type JudgeMetrics struct {
	PositionPairs       int     `json:"position_pairs"`
	PositionUnstable    int     `json:"position_unstable"`
	ParaphraseMaxGap    int     `json:"paraphrase_max_gap"`
	VerbosityMaxPremium int     `json:"verbosity_max_premium"`
	HeldOutPairs        int     `json:"held_out_pairs"`
	MeanSignedError     float64 `json:"mean_signed_error"`
	HeldOutAgreement    float64 `json:"held_out_agreement"`
	LowConfidence       int     `json:"low_confidence"`
	Escalated           int     `json:"escalated"`
}

JudgeMetrics is the measured fact set for a case — the report-contract posture: an operator reads the numbers behind the verdict without re-deriving them.

type JudgeReplay

type JudgeReplay struct {
	Schema     string           `json:"schema"`
	CaseID     string           `json:"case_id"`
	JudgeID    string           `json:"judge_id"`
	Tier       ReviewTier       `json:"tier"`
	Provenance ReviewProvenance `json:"provenance"` // scrubbed
	Axis       JudgeAxis        `json:"axis"`
	Kind       string           `json:"kind"`
	Metrics    JudgeMetrics     `json:"metrics"`
	Reason     string           `json:"reason"`
}

JudgeReplay is the scrubbed, self-contained record a failing case emits so the first divergence can be independently re-checked. Provenance values and the free-text reason pass through the same secret scrubber reviewrubric.go uses.

type JudgeVerdict

type JudgeVerdict struct {
	CaseID          string       `json:"case_id"`
	JudgeID         string       `json:"judge_id"`
	Pass            bool         `json:"pass"`
	FirstDivergence JudgeAxis    `json:"first_divergence,omitempty"`
	DivergenceKind  string       `json:"divergence_kind,omitempty"`
	Reason          string       `json:"reason"`
	Metrics         JudgeMetrics `json:"metrics"`
	Replay          *JudgeReplay `json:"replay,omitempty"` // present iff Pass is false
}

JudgeVerdict is the adjudicated result of validating one judge case.

func ReviewJudge

func ReviewJudge(c JudgeCase) JudgeVerdict

ReviewJudge validates one judge case and fails closed. Adjudication order: (1) structural validation — a malformed case is kind "invalid" and never passes; (2) each axis in canonical order — an axis with no evidence is "inconclusive", otherwise the axis-specific divergence. The first axis that diverges is reported. A case with no divergence passes.

type LedgerRow

type LedgerRow struct {
	Schema       string  `json:"schema"`
	Date         string  `json:"date"`
	Commit       string  `json:"commit"`
	GeneratedAt  string  `json:"generated_at"`
	Verdict      string  `json:"verdict"`
	Tracked      int     `json:"tracked"`
	Measured     int     `json:"measured"`
	Advancing    int     `json:"advancing"`
	Regressed    int     `json:"regressed"`
	KernelMetric float64 `json:"kernel_metric"`
	KernelDir    string  `json:"kernel_dir,omitempty"`
	CacheMetric  float64 `json:"cache_metric"`
	CacheDir     string  `json:"cache_dir,omitempty"`
	HumanMetric  float64 `json:"human_metric"`
	HumanDir     string  `json:"human_dir,omitempty"`
}

LedgerRow is one durable, append-only history line (a flattened per-class projection so the ledger is a self-describing time series).

func ParseLedger

func ParseLedger(content string) []LedgerRow

ParseLedger parses an append-only JSONL ledger, tolerating blank + garbled lines.

func RowFromReport

func RowFromReport(r Report) LedgerRow

RowFromReport projects a folded report into one durable ledger row.

type PairProbe

type PairProbe struct {
	ItemA         string `json:"item_a"`
	ItemB         string `json:"item_b"`
	WinnerForward string `json:"winner_forward"` // winner when shown (A, B)
	WinnerSwapped string `json:"winner_swapped"` // winner when shown (B, A)
}

PairProbe records a judge's pairwise preference under an order swap. The judge is shown the same two summaries twice, forward (A, B) and swapped (B, A); a position-free judge names the same winner both times. Each winner must be "" (a declared tie), ItemA, or ItemB.

type ParaphraseProbe

type ParaphraseProbe struct {
	ItemID          string `json:"item_id"`
	ScoreOriginal   int    `json:"score_original"`
	ScoreParaphrase int    `json:"score_paraphrase"`
}

ParaphraseProbe records a judge's score on a summary and on a meaning-preserving paraphrase of it. A repeatable judge scores the two within tolerance.

type Programs

type Programs struct {
	Signals     []Signal `json:"signals"`
	Tracked     int      `json:"tracked"`
	Measured    int      `json:"measured"`
	Advancing   int      `json:"advancing"`
	Regressed   int      `json:"regressed"`
	PartialNote string   `json:"partial_note,omitempty"`
	Err         string   `json:"err,omitempty"`
	OK          bool     `json:"ok"`
}

Programs is the PROGRAMS dimension: the per-program signals folded for a tick. Err is set only when EVERY program failed to measure (a true unmeasured dimension that gates); a partial failure records a non-gating PartialNote and leaves Err == "" so one flaky ledger read never reds the whole report.

func Collect

func Collect(root, cacheLedgerPath string, windowDays int) Programs

Collect measures both ongoing programs' frontier signals: kernel-opt from the perf-lane git ship window, cache-opt from the cache-value reuse trend gate. A signal that cannot be read carries Err (never a silent zero), and the pure InterpretPrograms folds the partial/whole-failure verdict.

func InterpretPrograms

func InterpretPrograms(signals []Signal) Programs

InterpretPrograms folds the per-program signals into the PROGRAMS dimension. The signals arrive already measured (collect.go does the impure reads); this is the pure tally so the verdict logic and the JSON shape are unit-testable with no disk.

type RaterScores

type RaterScores struct {
	Rater  string                  `json:"rater"`
	Scores map[ReviewDimension]int `json:"scores"`
	Note   string                  `json:"note,omitempty"`
}

RaterScores is one rater's independent 1-5 score on each axis. Raters rate blind (they do not see each other's scores); the disagreement process below reconciles them. A score outside 1..5, or a missing axis, is invalid.

type ReplayArtifact

type ReplayArtifact struct {
	Schema         string           `json:"schema"`
	CaseID         string           `json:"case_id"`
	Tier           ReviewTier       `json:"tier"`
	Provenance     ReviewProvenance `json:"provenance"` // scrubbed
	Dimension      ReviewDimension  `json:"dimension"`  // the first actionable divergence
	Kind           string           `json:"kind"`
	Anchor         string           `json:"anchor,omitempty"` // published anchor at the observed level
	RaterScores    map[string]int   `json:"rater_scores"`     // per-rater score on the divergent axis
	SubjectExcerpt string           `json:"subject_excerpt"`  // scrubbed
	Reason         string           `json:"reason"`
}

ReplayArtifact is the scrubbed, self-contained record a failing case emits so the first divergence can be independently re-rated. Free-text spans (subject excerpt, rater notes) and provenance values are passed through the secret scrubber, so a credential pasted into a summary is redacted before replay.

type Report

type Report struct {
	Schema      string   `json:"schema"`
	OK          bool     `json:"ok"`
	Verdict     string   `json:"verdict"`
	Finding     string   `json:"finding"`
	Reason      string   `json:"reason"`
	NextAction  string   `json:"next_action"`
	Workspace   string   `json:"workspace"`
	Commit      string   `json:"commit"`
	GeneratedAt string   `json:"generated_at"`
	Date        string   `json:"date"`
	Programs    Programs `json:"programs"`
	Trend       *Trend   `json:"trend,omitempty"`
	GateExit    *int     `json:"gate_exit,omitempty"`
	GateMessage string   `json:"gate_message,omitempty"`
}

Report is one folded ongoing-program control-pane envelope.

func Fold

func Fold(p Programs, opts FoldOpts) Report

Fold folds the programs dimension into one report envelope. The verdict ladder mirrors milestonereport's REPORT contract, not a second quality gate: it is ACTION only when the dimension could not be MEASURED (every program's frontier signal failed), and OK otherwise — a regressed program frontier is surfaced as an advisory line, never a gate (a frontier can dip for honest reasons; the per-program ratchet, e.g. the cache-value trend gate, owns the real regression gate).

func (Report) WithGate

func (r Report) WithGate(code int, message string) Report

WithGate returns a copy reconciled to a CheckGate decision, for --check --json.

func (Report) WithTrend

func (r Report) WithTrend(t Trend) Report

WithTrend attaches a per-tick trend and applies the advisory rewrite.

type ReviewCase

type ReviewCase struct {
	Schema     string           `json:"schema"`
	ID         string           `json:"id"`
	Subject    string           `json:"subject"` // the executive-summary narrative under review
	Provenance ReviewProvenance `json:"provenance"`
	Tier       ReviewTier       `json:"tier"`
	CostNote   string           `json:"cost_note"`            // documented runtime/resource cost
	Raters     []RaterScores    `json:"raters"`               // >= 2, for inter-rater agreement
	PassFloor  int              `json:"pass_floor,omitempty"` // per-axis consensus floor; 0 => DefaultReviewPassFloor
}

ReviewCase is one executive-summary review: the summary text under review, its provenance, tier and documented cost, and the blind ratings of two or more raters.

func UnmarshalReviewCase

func UnmarshalReviewCase(b []byte) (ReviewCase, error)

func (ReviewCase) Validate

func (c ReviewCase) Validate() error

Validate is the admission gate. It fails closed at every boundary so an ill-formed case can never reach a pass verdict: wrong schema, empty id or subject, incomplete provenance, an unassigned tier, an undocumented cost, fewer than two raters, or any out-of-range / missing axis score.

type ReviewDimension

type ReviewDimension string

ReviewDimension is one anchored axis of the expert-review rubric.

const (
	Grounding     ReviewDimension = "grounding"
	Completeness  ReviewDimension = "completeness"
	Salience      ReviewDimension = "salience"
	Actionability ReviewDimension = "actionability"
	Clarity       ReviewDimension = "clarity"
	Calibration   ReviewDimension = "calibration"
)

type ReviewProvenance

type ReviewProvenance struct {
	Model     string `json:"model"`     // model that generated the summary under review
	Tokenizer string `json:"tokenizer"` // tokenizer id
	Engine    string `json:"engine"`    // engine/backend (e.g. "fak-gateway", "reference")
	Seed      string `json:"seed"`      // RNG seed — required unless Oracle is set
	Oracle    string `json:"oracle"`    // deterministic oracle id — required unless Seed is set
	Revision  string `json:"revision"`  // code/module revision the summary was produced at
	Baseline  string `json:"baseline"`  // tolerance/baseline provenance the ratings anchor to
}

ReviewProvenance records the replay-complete origin of a review case — the shared #4509 provenance contract: what produced the summary under review and against what baseline the ratings are anchored. Every field except the seed/oracle pair is required; a case missing any of them is refused (an unprovenanced case is never a pass).

type ReviewTier

type ReviewTier string

ReviewTier is the explicit run tier a case is assigned to. A case with no tier is refused — the issue requires an explicit PR / nightly / release assignment.

const (
	TierPR      ReviewTier = "pr"
	TierNightly ReviewTier = "nightly"
	TierRelease ReviewTier = "release"
)

type ReviewVerdict

type ReviewVerdict struct {
	CaseID          string                  `json:"case_id"`
	Pass            bool                    `json:"pass"`
	Consensus       map[ReviewDimension]int `json:"consensus"` // 0 => inconclusive (raters disagreed)
	FirstDivergence ReviewDimension         `json:"first_divergence,omitempty"`
	DivergenceKind  string                  `json:"divergence_kind,omitempty"` // invalid | inconclusive | below_floor
	Reason          string                  `json:"reason"`
	Replay          *ReplayArtifact         `json:"replay,omitempty"` // present iff Pass is false
}

ReviewVerdict is the adjudicated result of grading one case.

func Review

func Review(c ReviewCase) ReviewVerdict

Review grades one case and fails closed. Order of adjudication: (1) validation — a malformed case is DivergenceKind "invalid" and never passes; (2) the first axis (canonical order) on which raters disagree beyond tolerance is "inconclusive"; (3) otherwise the first axis whose consensus is below the pass floor is "below_floor". A case with no divergence passes.

type Signal

type Signal struct {
	Class     worktype.Class `json:"class"`
	Label     string         `json:"label"`
	Doc       string         `json:"doc,omitempty"`    // the program's operating-plan doc
	Frontier  string         `json:"frontier"`         // the best-witnessed frontier reading (human string)
	Metric    float64        `json:"metric"`           // the numeric frontier reading the trend is computed on
	Direction string         `json:"direction"`        // advancing | holding | regressed | unknown
	Activity  int            `json:"activity"`         // recent shipped frontier-moves over the window
	Window    string         `json:"window,omitempty"` // the window the activity is counted over (e.g. "7d")
	Note      string         `json:"note,omitempty"`   // an honesty fence / caveat (e.g. the #1066 reuse-family label)
	Err       string         `json:"err,omitempty"`
	OK        bool           `json:"ok"`
}

Signal is one ongoing program's measured frontier-activity for a tick. It is deliberately NOT a completion %: Frontier is the best-witnessed number/state (e.g. the realized reuse ratio, or the trailing perf-ship count), Direction is whether the frontier is advancing, and Activity is the recent shipped work that moved it. A program whose signal could not be measured sets Err — never a silent zero, the same honesty seam the milestone roadmap carries for an unreadable epic.

type StateCapture

type StateCapture struct {
	Programs     []string `json:"programs"`                // tracked programs in scope of the summary
	Evidence     []string `json:"evidence"`                // measured signals available when the summary was written (>= 1 required)
	Decisions    []string `json:"decisions"`               // the operator decision(s) the summary must support (>= 1 required)
	Ambiguity    []string `json:"ambiguity,omitempty"`     // genuinely unresolved facts an honest summary hedges rather than resolves
	KnownDefects []string `json:"known_defects,omitempty"` // known state defects a complete summary must surface
}

StateCapture is the representative project state a case's summary was written against — the #4550 scope's "project states, evidence, decisions, ambiguity, and known defects". It is the context a re-rater needs to judge grounding, completeness, and calibration without re-deriving the repo state; it never constrains the summary's wording.

type Trend

type Trend struct {
	PrevDate          string  `json:"prev_date"`
	PrevCommit        string  `json:"prev_commit"`
	Direction         string  `json:"direction"` // improved | regressed | flat | new
	KernelMetricFrom  float64 `json:"kernel_metric_from"`
	KernelMetricTo    float64 `json:"kernel_metric_to"`
	KernelMetricDelta float64 `json:"kernel_metric_delta"`
	CacheMetricFrom   float64 `json:"cache_metric_from"`
	CacheMetricTo     float64 `json:"cache_metric_to"`
	CacheMetricDelta  float64 `json:"cache_metric_delta"`
	HumanMetricFrom   float64 `json:"human_metric_from"`
	HumanMetricTo     float64 `json:"human_metric_to"`
	HumanMetricDelta  float64 `json:"human_metric_delta"`
	AdvancingFrom     int     `json:"advancing_from"`
	AdvancingTo       int     `json:"advancing_to"`
	Summary           string  `json:"summary"`
}

Trend is the per-tick delta vs the previous ledger row.

func TrendVsLast

func TrendVsLast(row LedgerRow, prior []LedgerRow) Trend

TrendVsLast computes the per-tick trend vs the most recent prior row. The direction is driven by the two program metrics: a rise in either frontier metric is "improved", a fall in either (with no rise) is "regressed". With no prior row it is "new".

type VerbosityProbe

type VerbosityProbe struct {
	ItemID            string `json:"item_id"`
	JudgeScoreConcise int    `json:"judge_score_concise"`
	JudgeScoreVerbose int    `json:"judge_score_verbose"`
}

VerbosityProbe records a judge's score on a concise summary and on a longer summary of EQUAL expert quality. A judge free of verbosity preference gives the verbose form no premium beyond tolerance.