superloop

Documentation

Overview

Package superloop is the operator-intent META-LOOP: a SUPER LOOP walks a curated set of member loops/gardens/scorecards, reads their status FIRST, and selects worst-first which member to enter — the layer that sits ABOVE a normal loop.

The differentiation (super loop vs normal loop) — the conceptual crux

The fleet already runs many NORMAL loops: the dispatch loop resolves one issue, the garden tick reaps one class of stale work, a scorecard run reports one debt, `fak loop drive` settles one GOAL.md witness. Each is keyed on a TASK and a cadence; each tick DOES one unit of concrete work; each is a LEAF in the work graph — it acts on the codebase/world directly, and its health is "did it tick recently + keep-rate". A normal loop has no members, no read-first phase, and no selection step: it just runs its body.

A SUPER LOOP is keyed on an operator INTENT ("improve quality"), not a task. Its tick is a TRAVERSAL over OTHER loops, in four moves a normal loop never makes:

1. WALK — read each member's STATUS before doing anything (orient-over-loops).
2. SELECT — worst-first pick the member most in debt / dark / stale.
3. DESCEND — enter that member's loop (which may itself be a super loop: recursion).
4. FOLD — exit on the AGGREGATE clearing (folded debt <= floor), not on any single task's witness.

So a super loop is an INTERIOR node: it mutates nothing at its own altitude — its only effect is reading members and driving them; the MEMBERS mutate. That is the load-bearing line. Five properties separate the two, and Classify checks all five against a LoopFacts descriptor so "this is a super loop" is a witnessed verdict, not a label. A super loop generalizes the garden bundle (internal/gardenbundle): the garden is a FIXED bundle folded into one OK/RED gate; a super loop is an intent-named, worst-first-selecting, recursively-nestable bundle whose members are themselves loops, and whose output is a WORKLIST (what to enter next), not just a pass/fail.

The package is PURE: the registry is data, Classify and Walk are deterministic folds over inputs the impure shell (cmd/fak/superloop.go) supplies. It reads no files and no clock; the shell collects member status (scorecard baseline debt, loopfleet loop health) and hands it in — the same shell/core split loopindex and loopfleet use.

Index

• Constants
• func Names() []string
• func Render(w io.Writer, rep EvalReport)
• func ScorecardRefs() []string
• type Allocation
• type BatchDriveDecision
  • func DriveBatch(rep WalkReport, k int) BatchDriveDecision
• type BudgetRow
• type DriveDecision
  • func Drive(rep WalkReport) DriveDecision
• type EvalReport
  • func EvaluateAll(fixtures []MetaFixture, profs []ModelMetaProfile) EvalReport
  • func SimulatedReport() EvalReport
• type FrontDoor
  • func FrontDoorFor(d DriveDecision) FrontDoor
  • func (f FrontDoor) Runnable() bool
• type FrontDoorKind
• type GenerationBudget
• type Grade
  • func GradeDecision(fx MetaFixture, d ModelDecision, answered bool) Grade
• type GraphReport
  • func Graph() GraphReport
• type IntentNode
• type LoopFacts
  • func FactsFor(s Super) LoopFacts
  • func LeafFacts(name string) LoopFacts
• type Member
• type MemberKind
• type MemberStatus
  • func SubwalkStatus(m Member, rep WalkReport) MemberStatus
• type MetaAction
  • func (a MetaAction) Valid() bool
• type MetaFixture
  • func Fixtures() []MetaFixture
• type ModelDecision
• type ModelFit
  • func Evaluate(fixtures []MetaFixture, prof ModelMetaProfile) ModelFit
• type ModelMetaProfile
  • func SimulatedProfiles(fixtures []MetaFixture) []ModelMetaProfile
• type Property
• type ScorecardClash
• type Super
  • func Lookup(name string) (Super, bool)
  • func Registry() []Super
• type Verdict
  • func Classify(f LoopFacts) Verdict
• type WalkOpt
  • func WithIssueProgress(progressed int) WalkOpt
• type WalkReport
  • func Walk(s Super, statuses []MemberStatus, opts ...WalkOpt) WalkReport
• type WorkClass
• type WorkItem
• type WorkMix

Constants

const (
	FitActionMatch      = "action-match"             // chose the fixture's WantAction
	FitActionMismatch   = "action-mismatch"          // chose a different (valid) action
	FitUnknownAction    = "unknown-action"           // chose a value outside the closed set
	FitRefusalPreserved = "refusal-preserved"        // every MustPreserve reason survived the summary
	FitRefusalDropped   = "refusal-dropped"          // a MustPreserve reason was papered over
	FitNoInventedShip   = "no-invented-shipped-work" // claimed nothing shipped, and nothing was
	FitInventedShip     = "invented-shipped-work"    // claimed shipped work where none exists
	FitNoDecision       = "no-decision"              // the model returned no answer for this fixture
)

Closed-vocabulary grade reason strings. A report renders these verbatim, so a pass or a refusal is explainable without free text.

const (
	BudgetTime    = "time"    // wall-clock window spent walking/descending (max_minutes)
	BudgetTokens  = "tokens"  // model/context spend for planning, workers, reviews (token_ceiling)
	BudgetWorkers = "workers" // concurrent agent/worker seats admitted (max_workers)
	BudgetReview  = "review"  // stronger-rung review slots consumed before promotion (review_slots)
)

The four budget-dimension tokens the generation-budget contract names (docs/generation-super-loop-budgets.md §Budget Dimensions). They are the stable keys a walk's budget rows and a member's held-dimension list use.

const BatchDriveSchema = "fak.superloop-drive-batch.v1"

BatchDriveSchema is the versioned payload tag a batch drive emits.

const DefaultThroughputTargetPct = 50

DefaultThroughputTargetPct is the soft mix target a Super uses when it declares none: a balanced 50% throughput share. It only ever breaks a tie between two equally-urgent members of opposite class, so the exact number is a gentle lean, not a quota.

const DriveSchema = "fak.superloop-drive.v1"

DriveSchema is the versioned payload tag the `--json` drive emits.

const EvalSchema = "fak.superloop-modelfit.v1"

EvalSchema is the versioned tag a serialized eval report carries, so a forked or older report shape fails loud rather than silently mis-reading.

const GraphSchema = "fak.superloop-graph.v1"

GraphSchema is the versioned payload tag the `--json` graph emits.

const RootIntent = "tend"

RootIntent is the name of the ROOT super loop — the intent every other intent must be reachable from over KindSuperloop edges (the "super loop of super loops"). Depth and reachability in Graph are measured from here; the no-escape test pins that the registry actually reaches every intent from it.

const WalkSchema = "fak.superloop-walk.v1"

WalkSchema is the versioned payload tag the `--json` walk emits.

Functions

func Names

func Names() []string

Names returns the registered intent names in declaration order.

func Render

func Render(w io.Writer, rep EvalReport)

Render writes the eval report as a human-readable table: one row per model with its pass count, the work class it is CLEARED for (routine/T2, or "—" when refused), the class it is DENIED regardless of pass rate, and the cost/latency metadata. The footer restates the read-only ceiling and, when any row is simulated, that the rows are stand-ins — so a reader can never mistake the sample for a measured leaderboard.

func ScorecardRefs

func ScorecardRefs() []string

ScorecardRefs returns the distinct scorecard keys referenced across the whole registry — the set the no-drift witness checks against the control-pane cards.

Types

type Allocation

type Allocation struct {
	MaxMinutes   int      `json:"max_minutes,omitempty"`
	TokenCeiling int      `json:"token_ceiling,omitempty"`
	MaxWorkers   int      `json:"max_workers,omitempty"`
	ReviewSlots  int      `json:"review_slots,omitempty"`
	Held         []string `json:"held,omitempty"`
}

Allocation is the budget share one worklist member receives from the divide-down. Under even division each worklist member gets the same share, so a per-dimension cap is the intent's declared cap divided (floor) by the number of worklist members. Held names the dimensions the intent left UNBUDGETED (zero cap) — the contract's "no row = hold for later-horizon work" list, carried explicitly so a reader (and the future bind) can tell "0 share of a budgeted dimension" (timeshare a scarce cap) apart from "this dimension is not budgeted at all" (hold).

type BatchDriveDecision

type BatchDriveDecision struct {
	Intent         string          `json:"intent"`
	Enter          bool            `json:"enter"`
	Requested      int             `json:"requested"`
	Members        []DriveDecision `json:"members,omitempty"`
	Satisfied      bool            `json:"satisfied"`
	IssueShortfall int             `json:"issue_shortfall,omitempty"`
	Reason         string          `json:"reason"`
}

BatchDriveDecision is Drive widened from one member to a bounded worst-first fan-out: the top-K members the SELECT step offers this invocation, so throughput scales with available non-colliding work instead of one member per walk.

Members is the worst-first PREFIX of the walk's already-ranked worklist (length min(K, len(worklist))); each entry is the SAME entered DriveDecision Drive returns for the head, in worst-first (rank) order. This is a PURE SELECTION: it reads no leases and admits nothing. The impure shell passes each selected member through the SAME admission gate any single drive passes (region admission over the live lease fabric — COLLISION_RISK on lease overlap); so "trees mutually disjoint (and disjoint from live leases)" is ENFORCED by the gate, member by member, never asserted here. A member the gate refuses is simply not entered.

Enter/Satisfied/IssueShortfall carry the SAME honesty as Drive when there is nothing to enter (an empty worklist): a satisfied walk reads clean, an unsatisfied empty worklist is an unmet headline gate (#3147), never clean.

func DriveBatch

func DriveBatch(rep WalkReport, k int) BatchDriveDecision

DriveBatch reduces a completed walk's worst-first worklist to the top-K members to offer this invocation — the SELECT step widened from one member (see Drive) to a bounded fan-out. The worklist is already sorted worst-first by Walk, so the top-K are its head prefix. k <= 0 means "every worklist member" (no cap); k larger than the worklist is clamped to the worklist length. An empty worklist enters nothing with the SAME clean-vs-unmet-headline honesty as Drive (#3147).

DriveBatch is a pure fold: it reads no files, no clock, and no lease fabric, and takes no admission action. The shell gates each returned member through the shared region-admission gate and enters only those the gate admits — so the pure layer never has to know the live lease geometry to stay honest.

type BudgetRow

type BudgetRow struct {
	Dimension string `json:"dimension"`
	Unit      string `json:"unit"`
	Stream    string `json:"stream,omitempty"`
	Budgeted  bool   `json:"budgeted"`
	Total     int    `json:"total"`
	Members   int    `json:"members"`
	PerMember int    `json:"per_member"`
	Hold      string `json:"hold,omitempty"`
}

BudgetRow is one budget dimension folded for the whole walk: the intent's declared cap (Total), whether the dimension is budgeted at all, and the PerMember share the divide-down hands each worklist member. An unbudgeted dimension (Budgeted false) is a HOLD — zero total, zero share, and a Hold reason — surfaced for the operator rather than silently treated as an unlimited grant.

type DriveDecision

type DriveDecision struct {
	Intent    string `json:"intent"`
	Enter     bool   `json:"enter"`
	Member    Member `json:"member,omitempty"`
	Rank      int    `json:"rank,omitempty"`
	Action    string `json:"action,omitempty"`
	Debt      int    `json:"debt,omitempty"`
	Dark      bool   `json:"dark,omitempty"`
	Container bool   `json:"container,omitempty"`
	// Satisfied echoes the walk's satisfaction at drive time. A drive that enters
	// nothing (Enter=false) reads clean ONLY when Satisfied is true; an unsatisfied
	// empty-worklist drive is an unmet gate — a declared headline the members did not
	// carry — not a clean read (#3147). Consumers gate their exit on THIS, not on Enter.
	Satisfied bool `json:"satisfied"`
	// IssueShortfall carries the walk's unmet headline issue count (0 = none). It is the
	// magnitude behind an unsatisfied empty-worklist drive: there is no member to enter,
	// yet the declared ~headline is not met — the number the drive must not hide.
	IssueShortfall int    `json:"issue_shortfall,omitempty"`
	Reason         string `json:"reason"`
	// Allocation is the entered member's divided share of the intent's declared budget,
	// carried from the walk's [WorkItem] so the exec rung can BIND it when it runs the
	// member's front door (#2224). The walk computes it as a reservation; the drive's
	// `--execute` path turns the Time share into a real ceiling — the tighter of the
	// operator's --exec-timeout and this MaxMinutes bounds the front-door deadline, so a
	// member can never outrun its declared time budget. Empty for a non-entering decision.
	Allocation Allocation `json:"allocation,omitempty"`
}

DriveDecision is the SINGLE worst-first member a drive enters this invocation — the "one member per walk" contract as a pure selection. Enter is false when the walk is already satisfied (nothing worst-first to enter): the drive then enters nothing and the caller's re-fold is a clean exit check. When Enter is true, Member is the member to enter, Action is its front-door hint (the loop's `fak loop drive` / dispatch tick, or a scorecard's enter skill — the same text the worklist surfaces), and Rank is its 1-based worst-first position (always 1: the drive enters the head).

func Drive

func Drive(rep WalkReport) DriveDecision

Drive reduces a completed walk's worst-first worklist to the SINGLE member to enter this invocation — the SELECT step narrowed to one member per walk (the drive contract). The worklist is already sorted worst-first by Walk, so the head is the member to enter; a satisfied walk (empty worklist) enters nothing. Drive is a pure fold: it reads no files and no clock and takes no admission action; the shell gates and runs the returned member.

type EvalReport

type EvalReport struct {
	Schema   string     `json:"schema"`
	Fixtures int        `json:"fixtures"`
	Models   []ModelFit `json:"models"`
}

EvalReport is the whole eval: the fixture count graded and one ModelFit row per model, sorted by model id so the artifact is byte-stable and diff-friendly.

func EvaluateAll

func EvaluateAll(fixtures []MetaFixture, profs []ModelMetaProfile) EvalReport

EvaluateAll grades every profile against the fixture set and returns the sorted report. It is a deterministic fold over Evaluate — same inputs, same bytes out.

func SimulatedReport

func SimulatedReport() EvalReport

SimulatedReport is the convenience the witness names: grade the built-in simulated rows against the built-in fixtures and return the folded report. It is the offline eval an operator (or a test) runs when no live model is available.

type FrontDoor

type FrontDoor struct {
	Kind    FrontDoorKind `json:"kind"`
	Command string        `json:"command,omitempty"`
	Note    string        `json:"note"`
}

FrontDoor is the classification of a driven member's front door: its kind, the exact shell command to run when FrontRunnable (empty otherwise), and a one-line note the drive surfaces so a reader knows WHY a member was run or only surfaced.

func FrontDoorFor

func FrontDoorFor(d DriveDecision) FrontDoor

FrontDoorFor classifies the front door of one selected DriveDecision. The order is load-bearing: a CONTAINER is a descend pointer regardless of any Enter string (the drive never executes a subtree), so it is checked first; then a skill ("/x"), which needs an agent; then an empty Enter (nothing runnable); everything else is a concrete shell command the drive can run behind the lease. Pure and total over the decision.

func (FrontDoor) Runnable

func (f FrontDoor) Runnable() bool

Runnable reports whether the front door is a shell command a headless drive executes.

type FrontDoorKind

type FrontDoorKind string

FrontDoorKind classifies a member's front door by whether a headless drive can run it.

const (
	// FrontRunnable is a shell command a headless drive CAN execute behind the lease
	// (e.g. "go run ./cmd/fak dispatch auto --goal throughput",
	// "python tools/tooling_quality_scorecard.py --json", or a compound "a && b" line).
	// Its exit code is the member's own witness: exit 0 lands a witnessed_done.
	FrontRunnable FrontDoorKind = "runnable"
	// FrontSkill is a Claude skill front door ("/slop-score"): it needs an AGENT, not a
	// shell, so a headless drive SURFACES it and never claims to have run it. Executing
	// it is the operator's/agent's move, not the meta-loop's.
	FrontSkill FrontDoorKind = "skill"
	// FrontDescend is a container member (a sub-super-loop or the garden bundle): running
	// it would mean cascading a whole subtree, which the drive must not do implicitly. The
	// drive surfaces the descend pointer (`fak superloop walk <ref>`) instead.
	FrontDescend FrontDoorKind = "descend"
	// FrontNone is a member with no concrete Enter command declared (e.g. a plain loop
	// whose only front door is the generic "drive the loop" pointer). There is nothing a
	// headless drive can run, so it is surfaced, not executed.
	FrontNone FrontDoorKind = "none"
)

type GenerationBudget

type GenerationBudget struct {
	// Stream is the generation horizon this reservation serves (e.g. "gen/now",
	// "gen/next"), reported so a walk can say which streams received capacity and
	// which were held. Empty means the envelope is horizon-agnostic.
	Stream string `json:"stream,omitempty"`
	// MaxMinutes caps the wall-clock window (Time dimension); 0 = unbudgeted.
	MaxMinutes int `json:"max_minutes,omitempty"`
	// TokenCeiling caps model/context spend (Tokens dimension); 0 = unbudgeted.
	TokenCeiling int `json:"token_ceiling,omitempty"`
	// MaxWorkers caps concurrent worker seats (Workers dimension); 0 = unbudgeted.
	MaxWorkers int `json:"max_workers,omitempty"`
	// ReviewSlots caps stronger-rung review slots (Review dimension); 0 = unbudgeted.
	ReviewSlots int `json:"review_slots,omitempty"`
	// Expiry is the recheck date a later-horizon reservation must carry: the contract
	// requires an expiry on gen/second-next and gen/future shares so a research/design
	// budget cannot become permanent. Empty is valid only for now/near-term streams.
	Expiry string `json:"expiry,omitempty"`
}

GenerationBudget is a super loop's DECLARED reservation across the four budget dimensions. Each cap is a PLANNED operator policy (like Super.Floor), not a measured number: it says how much recurring capacity this intent reserves, so current work is not diluted and future-facing streams are not silently starved. A zero cap means UNBUDGETED for that dimension — Walk renders it as a HOLD row and lists it under each member's held dimensions.

type Grade

type Grade struct {
	Fixture string   `json:"fixture"`
	Pass    bool     `json:"pass"`
	Reasons []string `json:"reasons"`
}

Grade is the verdict for one (model, fixture) pair: pass/fail plus the closed reasons that decided it. It fails CLOSED — an unknown action, a mismatch, a dropped refusal, or an invented shipped-work claim each red the grade, and every check runs so the reasons list is complete rather than short-circuiting at the first failure.

func GradeDecision

func GradeDecision(fx MetaFixture, d ModelDecision, answered bool) Grade

GradeDecision grades one decision against its fixture. A missing decision (the model answered nothing) is a fail with FitNoDecision — silence is never a pass.

type GraphReport

type GraphReport struct {
	Schema   string       `json:"schema"`
	Root     string       `json:"root"`
	Intents  int          `json:"intents"`
	Edges    int          `json:"edges"` // KindSuperloop descend edges
	MaxDepth int          `json:"max_depth"`
	Nodes    []IntentNode `json:"nodes"` // in declaration order

	// Dangling are descend edges ("parent -> ref") whose ref resolves to no registered
	// intent — a broken module reference that would permanently red its parent's walk.
	Dangling []string `json:"dangling,omitempty"`

	// Acyclic is true when the descend edges form a DAG; Cycle carries the back-edge path
	// when they do not.
	Acyclic bool     `json:"acyclic"`
	Cycle   []string `json:"cycle,omitempty"`

	// RootReaches counts intents reachable from the root; Orphans lists those not.
	RootReaches int      `json:"root_reaches"`
	Orphans     []string `json:"orphans,omitempty"`

	// OnceOnly is true when no scorecard is double-counted; DoubleCounted lists any that
	// are.
	OnceOnly      bool             `json:"once_only"`
	DoubleCounted []ScorecardClash `json:"double_counted,omitempty"`

	// Shared lists the super loops with fan-in > 1 (reused modules), sorted.
	Shared []string `json:"shared,omitempty"`

	Verdict string `json:"verdict"`
	Finding string `json:"finding"`
	Reason  string `json:"reason"`
}

GraphReport folds the whole registry into its composition DAG plus the structural invariants that keep the nesting safe — the modular structure made observable. Verdict is OK only when the graph resolves, is acyclic, roots every intent, and counts each scorecard once; otherwise ACTION names the first failing invariant in Finding.

func Graph

func Graph() GraphReport

Graph folds the package registry into its composition DAG and the structural invariants, measuring depth and reachability from RootIntent. Pure: it reads the data-only registry and nothing else.

type IntentNode

type IntentNode struct {
	Name       string             `json:"name"`
	Title      string             `json:"title"`
	Members    int                `json:"members"`
	KindCounts map[MemberKind]int `json:"kind_counts,omitempty"`
	// Descends are the KindSuperloop member refs, in declaration order — this node's
	// out-edges in the composition DAG.
	Descends []string `json:"descends,omitempty"`
	// Parents are the intents that descend THIS node (its in-edges), sorted.
	Parents []string `json:"parents,omitempty"`
	// FanIn is len(Parents): how many parents reuse this node.
	FanIn int `json:"fan_in"`
	// Depth is the minimum descend depth from the root (root = 0); -1 if unreachable.
	Depth     int  `json:"depth"`
	Reachable bool `json:"reachable"`
	Root      bool `json:"root"`
	// LeafIntent is true when the node descends NO sub-super-loop: it drives only
	// concrete surfaces (scorecards/loops/gardens/utilization), an interior node whose
	// children are all leaves.
	LeafIntent bool `json:"leaf_intent"`
	// Shared is FanIn > 1: a module REUSED by multiple parents — the modularity payoff a
	// flat registry hides.
	Shared bool `json:"shared"`
}

IntentNode is one super loop as a node in the composition DAG: its own facts plus its place in the graph — the sub-super-loops it DESCENDS (its out-edges / module dependencies), the parents that descend IT (fan-in / in-edges), its minimum descend depth below the root, and whether the root reaches it at all.

type LoopFacts

type LoopFacts struct {
	Name string `json:"name"`
	// MemberCount is how many member loops/gardens/scorecards it walks (0 = a leaf).
	MemberCount int `json:"member_count"`
	// WalksFirst: does its tick READ member status before acting?
	WalksFirst bool `json:"walks_first"`
	// SelectsWorstFirst: does it pick which member to enter by worst-first?
	SelectsWorstFirst bool `json:"selects_worst_first"`
	// ExitsOnAggregate: does it exit on folded debt<=floor (vs a single task witness)?
	ExitsOnAggregate bool `json:"exits_on_aggregate"`
	// ActsAtOwnAltitude: does it write a domain artifact itself (a leaf), rather than
	// only driving its members (an interior node)? A super loop does NOT.
	ActsAtOwnAltitude bool `json:"acts_at_own_altitude"`
}

LoopFacts is the spawn-free descriptor Classify judges. The shell fills it: for a registered super loop via FactsFor; for a normal ledgered loop via LeafFacts. Keeping it a plain struct keeps Classify pure and the differentiation testable.

func FactsFor

func FactsFor(s Super) LoopFacts

FactsFor returns the LoopFacts of a registered super loop. By construction a registered Super satisfies all five properties (the registry only holds intents the walk treats as super loops): it has members, the walk reads them first, the fold selects worst-first, the Floor is an aggregate exit, and it drives members rather than acting itself.

func LeafFacts

func LeafFacts(name string) LoopFacts

LeafFacts returns the LoopFacts of a NORMAL leaf loop (a task loop like the dispatch tick or a scorecard run): it has no members, no read-first phase, no selection, exits on its own witness, and acts directly. Used by `explain` to show the contrast Classify draws.

type Member

type Member struct {
	Kind  MemberKind `json:"kind"`
	Ref   string     `json:"ref"`
	Why   string     `json:"why"`
	Enter string     `json:"enter,omitempty"`
}

Member is one constituent a super loop walks. Ref names the surface (scorecard key / loop id / garden name / super-loop name); Why is the one-line reason it belongs under this intent. Enter, when set, is the CONCRETE command or skill an operator runs to retire this member's debt (e.g. "/slop-score", "python tools/learning_scorecard.py --json") — it makes the worklist action directly enterable instead of the generic "its skill" pointer.

type MemberKind

type MemberKind string

MemberKind tags which existing surface a member references, so the shell knows how to read its status and a reader knows what altitude the member sits at.

const (
	// KindScorecard is a control-pane scorecard key (debt-bearing); status is read
	// from the pinned scorecard baseline / a fresh run.
	KindScorecard MemberKind = "scorecard"
	// KindLoop is a ledgered loop id; status is read from the cross-ledger loop-health
	// fold (internal/loopfleet).
	KindLoop MemberKind = "loop"
	// KindGarden is the garden bundle (itself a fold-over-folds); a member to descend.
	KindGarden MemberKind = "garden"
	// KindSuperloop is another super loop — the recursion case: a super loop whose
	// member is a super loop walks it as a sub-traversal.
	KindSuperloop MemberKind = "superloop"
	// KindSurface is a named command/control surface whose own status fold is outside
	// this generic registry. It is surfaced as a descend pointer, not weighed here.
	KindSurface MemberKind = "surface"
	// KindUtilization is a live CAPACITY-utilization signal: a resource pool whose
	// UNUSED headroom is the debt. Unlike a scorecard (a committed baseline value) or a
	// loop (a ledger liveness fold), its status is read LIVE by the shell at walk time
	// — an account pool's offerable-but-unused seats, or a lab node pool's up-but-idle
	// boxes. The debt is "capacity available but not being used": a resource sitting
	// warm while work backs up. Ref names which pool ("account-limits", "node-resources").
	KindUtilization MemberKind = "utilization"
	// KindTrajectory is a trajectory-control OBJECTIVE (internal/trajctl): a steered
	// goal whose worst-first status is its curve SIGNAL severity
	// (HEALTHY < STALL < DRIFT < DETOUR_OVERRUN). Like KindUtilization its status is
	// read LIVE by the shell — here from the trajctl ledger's folded curve, not a
	// committed baseline — and a SINGLE registry member ENUMERATES into one status per
	// OPEN objective, so "improve trajectory health" walks its objectives worst-first
	// through the same fold. Ref names the objective set on the registry member ("open"
	// = every active/paused objective; any other value selects one objective by id) and
	// the concrete objective id on each enumerated status. This joins the existing
	// controller-of-controllers walk rather than growing a rival walker (issue #2563).
	KindTrajectory MemberKind = "trajectory"
)

type MemberStatus

type MemberStatus struct {
	Member    Member `json:"member"`
	Debt      int    `json:"debt"`
	Dark      bool   `json:"dark"`
	Measured  bool   `json:"measured"`
	Container bool   `json:"container"`
	Detail    string `json:"detail"`
}

MemberStatus is the status the shell read for one member. Debt is the member's debt in its own units (scorecard debt, or a dark/stale penalty for a loop). Dark marks a member loop gone quiet or a member that errored. Measured is false when the member's status could not be read — surfaced, never silently treated as clean.

Container marks a member whose status this walk did NOT read — a descend pointer, not a leaf to weigh. A container is always surfaced in the worklist as a "descend" item, but it is NOT counted toward aggregate debt or the measured/unmeasured tally and never blocks Satisfied: this walk did not claim to have read it, so it neither inflates the debt nor is slandered as an unreadable failure. In practice only a garden or an external surface stays a container: a registered sub-super-loop is DESCENDED inline by the shell (recursion) and arrives here as a measured leaf via SubwalkStatus.

func SubwalkStatus

func SubwalkStatus(m Member, rep WalkReport) MemberStatus

SubwalkStatus folds a completed sub-walk into the member status the parent walk weighs — the DESCEND move made real for a sub-super-loop member. The mapping is conservative-honest: the member is Measured (the walk actually read it, so it is no longer a container), it carries the sub-walk's aggregate debt PLUS any unmet headline shortfall, and an UNSATISFIED sub-intent can never read as clean — when its own measured debt is zero (unmeasured or dark members inside), it still carries one unit of debt at the parent's altitude. Dark propagates when any member loop below has gone dark, so the parent's SELECT ranks a dark subtree with leaf-dark urgency.

Folding IssueShortfall into the descended debt (#3151) is what lets a large headline miss out-rank trivial member debt at the root: a run-the-night that missed its ~200-issue headline with zero member debt contributes debt 200 (not a single floored unit), so the root worst-first ranks the night's biggest gap ahead of a sibling carrying debt 2. The shortfall is 0 whenever the sub-walk declares no target or met it, so this is a no-op for shortfall-free subs and the 1-unit floor still guards the zero-shortfall unsatisfied case (dark/unmeasured members with no headline).

type MetaAction

type MetaAction string

MetaAction is the closed set of read-only super-loop decisions the eval grades. Each is a RECOMMENDATION the meta-orchestrator emits from status, never an execution: the eval is read-only, and a passing model earns the right to RECOMMEND reclaim/launch, not to carry either out (that needs a stronger tier plus a witness).

const (
	// ActionWait — live work is in flight and progressing; hold, do not double-drive.
	ActionWait MetaAction = "wait"
	// ActionReclaim — a lease/worker is stale or dark; recommend reclaiming it.
	ActionReclaim MetaAction = "reclaim"
	// ActionLaunch — capacity is idle and a ready worklist item exists; recommend launch.
	ActionLaunch MetaAction = "launch"
	// ActionNoop — the intent is satisfied (debt at/below floor, all measured & live);
	// nothing to enter.
	ActionNoop MetaAction = "no-op"
)

func (MetaAction) Valid

func (a MetaAction) Valid() bool

Valid reports whether a is one of the four defined read-only actions.

type MetaFixture

type MetaFixture struct {
	// Name is the fixture id (unique across the set).
	Name string `json:"name"`
	// Situation is the status snapshot a model reads for this scenario — the rendered
	// watchdog/super-loop readout, in the words a real prompt would show.
	Situation string `json:"situation"`
	// WantAction is the correct read-only decision for this status.
	WantAction MetaAction `json:"want_action"`
	// MustPreserve are refusal/DENY reasons present in the status that a faithful
	// summary MUST carry forward verbatim; dropping one paves over a real block and
	// reds the grade (FitRefusalDropped).
	MustPreserve []string `json:"must_preserve,omitempty"`
	// NothingShipped is the ground truth that NO work is shipped/done in this scenario.
	// When true, any ClaimsShipped entry on a decision is invented shipped work.
	NothingShipped bool `json:"nothing_shipped"`
	// Why is the one-line rationale for WantAction, surfaced in the report.
	Why string `json:"why"`
}

MetaFixture is one offline read-only super-loop decision scenario with a graded ground truth. It presents the STATUS a watchdog/meta-orchestrator reads and the decision a correct read-only orchestrator makes, plus the two honesty traps the eval scores beyond bare action-match.

func Fixtures

func Fixtures() []MetaFixture

Fixtures returns the built-in read-only meta-decision fixture set: the four actions, a refusal-preservation trap (a guard DENY that must survive the summary), and an invention trap (an OPEN issue a model must not call shipped). Every scenario is read-only and carries NothingShipped, because a meta read ships nothing.

type ModelDecision

type ModelDecision struct {
	// Fixture is the fixture Name this decision answers.
	Fixture string `json:"fixture"`
	// Action is the read-only action the model chose.
	Action MetaAction `json:"action"`
	// Summary is the model's status summary; it is scanned for preserved refusal
	// reasons (MustPreserve) — the surface where a papered-over block shows.
	Summary string `json:"summary"`
	// ClaimsShipped is the set of work items the model asserted are shipped/done. On a
	// NothingShipped fixture, a non-empty list is invented shipped work.
	ClaimsShipped []string `json:"claims_shipped,omitempty"`
	// Simulated marks this decision as a fixture stand-in, not a live model run.
	Simulated bool `json:"simulated"`
}

ModelDecision is ONE model's answer to ONE fixture — the read-only output the eval grades. Simulated marks a fixture stand-in (no live model was run) so a report can never pass an invented model result off as a measured one.

type ModelFit

type ModelFit struct {
	Model     string  `json:"model"`
	Simulated bool    `json:"simulated"`
	Passed    int     `json:"passed"`
	Total     int     `json:"total"`
	Suitable  bool    `json:"suitable"`
	Grades    []Grade `json:"grades"`
	// ClearedFor is the WorkClass a suitable model may take (routine); empty when not
	// suitable. ClearedTier is that class's required floor (T2 for routine) — the tier
	// a passing model is cleared to serve for read-only meta work.
	ClearedFor  modelroute.WorkClass `json:"cleared_for,omitempty"`
	ClearedTier string               `json:"cleared_tier,omitempty"`
	// DeniedAuthority names the work class a meta-fit pass NEVER grants, regardless of
	// pass rate — the read-only ceiling. Always populated. DeniedFloor is that class's
	// required floor (T1 — never T2), stated so a reader sees the pass did not, and
	// could not, authorize mutation.
	DeniedAuthority modelroute.WorkClass `json:"denied_authority"`
	DeniedFloor     string               `json:"denied_floor"`
	CostPerMTokOut  float64              `json:"cost_per_mtok_out,omitempty"`
	LatencyMS       int                  `json:"latency_ms,omitempty"`
	Reason          string               `json:"reason"`
}

ModelFit is the folded suitability verdict for one model over the whole fixture set: how many read-only meta decisions it graded correctly, and — only when it passed ALL of them — the WORK CLASS it is thereby cleared to handle. Suitability is READ-ONLY by construction: a model that aces the eval is cleared for the routine (T2) watchdog/meta RECOMMENDATION class and is EXPLICITLY denied the security/release/destructive class (kill/merge/push/launch), whose floor is never T2. A high pass rate NEVER buys past that ceiling — the confusion risk the issue names, made structural.

func Evaluate

func Evaluate(fixtures []MetaFixture, prof ModelMetaProfile) ModelFit

Evaluate grades one model profile against the fixture set and folds the per-fixture grades into a suitability verdict. It is PURE and offline: no model call, no clock — the decisions arrive pre-collected (live or simulated), and the grade is a deterministic fold, so the acceptance gate runs anywhere.

type ModelMetaProfile

type ModelMetaProfile struct {
	Model     string          `json:"model"`
	Simulated bool            `json:"simulated"`
	Decisions []ModelDecision `json:"decisions"`
	// CostPerMTokOut is a rough $/Mtok output price for the model (cost metadata);
	// 0 = unknown. It is metadata a routing layer weighs AFTER suitability, never a
	// lever that lifts a failing model into suitability.
	CostPerMTokOut float64 `json:"cost_per_mtok_out,omitempty"`
	// LatencyMS is a rough per-decision latency in milliseconds (latency metadata);
	// 0 = unknown.
	LatencyMS int `json:"latency_ms,omitempty"`
	// Notes is optional free text, surfaced to a human, never parsed.
	Notes string `json:"notes,omitempty"`
}

ModelMetaProfile is the eval's INPUT for one model: its decisions across the fixture set, plus the cost/latency metadata the report records. Simulated marks the whole profile as fixture stand-in data (no live model runs) — the honesty bit the witness requires when live model access is unavailable.

func SimulatedProfiles

func SimulatedProfiles(fixtures []MetaFixture) []ModelMetaProfile

SimulatedProfiles returns the built-in stand-in model rows the offline eval grades: two cheap models that answer every read-only fixture correctly (cleared for routine meta work) and one under-tuned model that papers over a guard refusal and invents shipped work (refused). Every decision is marked Simulated. The cost/latency figures are rough metadata for the report's cost-and-latency columns, not published prices.

type Property

type Property struct {
	Name   string `json:"name"`
	Want   bool   `json:"want"`
	Got    bool   `json:"got"`
	Holds  bool   `json:"holds"`
	Detail string `json:"detail"`
}

Property is one differentiation rung: the super-loop-satisfying value (Want), what this loop has (Got), and a one-line account.

type ScorecardClash

type ScorecardClash struct {
	Ref     string   `json:"ref"`
	Intents []string `json:"intents"`
}

ScorecardClash is one once-only violation: a scorecard key walked by two or more intents reachable from the root, whose debt would therefore fold into the root aggregate more than once.

type Super

type Super struct {
	// Name is the operator intent token, e.g. "improve-quality".
	Name string `json:"name"`
	// Title is the human one-liner shown in `list`.
	Title string `json:"title"`
	// About explains, in one sentence, what walking this intent does.
	About string `json:"about"`
	// Members are walked in order; SELECT reorders them worst-first.
	Members []Member `json:"members"`
	// Floor is the aggregate-debt threshold at or below which the intent is satisfied
	// (0 = the intent wants every member clear).
	Floor int `json:"floor"`
	// Budget is the DECLARED generation-budget envelope this intent reserves across
	// the four dimensions the budget contract names (Time/Tokens/Workers/Review;
	// docs/generation-super-loop-budgets.md). It is the TOP of the cascade — a
	// planned reservation, not a measured consumption — that [Walk] divides down into
	// a per-member allocation. A zero cap in any dimension is UNBUDGETED for that
	// dimension: the contract's "no row = hold for later-horizon work" case, surfaced
	// as a HOLD, never as an implicit unlimited grant. Priority stays debt-ordered; a
	// budget only reserves attention (the contract's Core Rule).
	Budget GenerationBudget `json:"budget"`
	// IssueTarget is a DECLARED operator headline number — the count of issues the
	// intent wants a run to progress (e.g. run-the-night's ~200-issue overnight
	// target). Like Floor and Budget it is a policy the operator states, NOT a
	// measured consumption: the walk always SURFACES it so the number is an explicit,
	// testable part of the intent rather than buried prose. When the impure shell hands
	// [Walk] a LIVE progress count (via [WithIssueProgress]) the walk also BINDS it: a
	// shortfall (progressed < target) is folded as a gate that keeps the intent
	// unsatisfied, so the headline stops being decorative and becomes a witnessed
	// number. With no progress handed in it stays surface-only (declared, never gating)
	// — the same declared-vs-measured posture the budget rows keep. 0 = no headline
	// issue target for this intent.
	IssueTarget int `json:"issue_target,omitempty"`
	// ThroughputTargetPct is the DECLARED soft mix target: the percentage of this
	// intent's attention the operator wants spent on throughput (issue-drain) work
	// versus gardening (quality/hygiene) work. Like Floor and IssueTarget it is a stated
	// policy, but a far GENTLER one — it never overrides worst-first urgency or debt
	// order; it only breaks a tie between two equally-urgent members of opposite class,
	// nudging a lopsided run back toward the target (#3126). 0 = unset, which takes
	// DefaultThroughputTargetPct (a balanced 50%). Values are clamped to [0,100].
	ThroughputTargetPct int `json:"throughput_target_pct,omitempty"`
}

Super is a named operator-intent super loop: an intent bound to an ordered member set plus the aggregate Floor below which the intent reads as satisfied.

func Lookup

func Lookup(name string) (Super, bool)

Lookup returns the named super loop and true, or a zero Super and false.

func Registry

func Registry() []Super

Registry returns a copy of the named super loops in declaration order.

type Verdict

type Verdict struct {
	Name       string     `json:"name"`
	IsSuper    bool       `json:"is_super"`
	Properties []Property `json:"properties"`
	Reason     string     `json:"reason"`
}

Verdict is the classification: whether the loop is a super loop, and the five properties that decided it. A super loop satisfies ALL five; a normal loop fails at least one, and Reason names the first failing rung.

func Classify

func Classify(f LoopFacts) Verdict

Classify judges a LoopFacts against the five differentiating properties. It is the executable form of "what makes a super loop a super loop":

has_members         — it walks >=1 member loop (a leaf has none)
walks_first         — its tick READS member status before acting
selects_worst_first — it picks which member to enter, worst-first
exits_on_aggregate  — it stops when the FOLD clears, not a single witness
interior_node       — it mutates nothing at its own altitude (members mutate)

All five must hold for IsSuper. The check is monotone in the obvious direction: a loop that does any of these is "more super" than one that does none.

type WalkOpt

type WalkOpt func(*walkConfig)

WalkOpt configures a Walk beyond the declared registry data — the seam the impure shell uses to fold LIVE measurements (which the pure package cannot read: it reads no ledger, disk, or clock) into the verdict. Options apply in order; a nil option is ignored. It is the same shell-measures / core-folds split the member statuses use.

func WithIssueProgress

func WithIssueProgress(progressed int) WalkOpt

WithIssueProgress hands Walk the LIVE count of issues the intent has progressed this run, as measured by the shell. When the intent declares an IssueTarget (> 0) the walk folds this against it: a shortfall (progressed < target) becomes a gate that keeps the intent unsatisfied, turning the declared headline into a witnessed number instead of decorative prose. A negative count is clamped to 0. Handing progress in for an intent with no target is harmless (surfaced, never gating). Passing it at all marks the walk as having MEASURED progress, so a real zero reads as a shortfall, not as "unmeasured".

type WalkReport

type WalkReport struct {
	Schema    string `json:"schema"`
	Name      string `json:"name"`
	Title     string `json:"title"`
	TotalDebt int    `json:"total_debt"`
	Floor     int    `json:"floor"`
	// IssueTarget echoes the intent's DECLARED headline issue count (0 = none). It is
	// always surfaced for the operator; when a live progress count is handed in (see
	// IssueProgressed) it is also the target the shortfall gate measures against.
	IssueTarget int `json:"issue_target,omitempty"`
	// IssueProgressed is the LIVE count of issues the intent has progressed this run, as
	// measured by the impure shell and handed to Walk via WithIssueProgress. It is only
	// meaningful when IssueProgressMeasured is true; the pure package reads no ledger, so
	// an unmeasured walk leaves this 0 and never fabricates progress it did not witness.
	IssueProgressed int `json:"issue_progressed,omitempty"`
	// IssueProgressMeasured records whether a live progress count was handed in at all.
	// It disambiguates a real measured zero (nothing progressed yet — a shortfall) from
	// "not measured" (surface-only, never gating), so an unread issue layer cannot make
	// the night falsely read as having hit its headline.
	IssueProgressMeasured bool `json:"issue_progress_measured,omitempty"`
	// IssueShortfall is max(0, IssueTarget - IssueProgressed) when the intent declares a
	// target AND progress was measured: the issues still owed against the headline. A
	// positive shortfall keeps Satisfied false — the declared target is a gate, not a
	// decoration. 0 when there is no target, no measurement, or the target is met.
	IssueShortfall int            `json:"issue_shortfall,omitempty"`
	Satisfied      bool           `json:"satisfied"`
	Members        int            `json:"members"`
	Walked         int            `json:"walked"`
	Unmeasured     int            `json:"unmeasured"`
	Dark           int            `json:"dark"`
	Worklist       []WorkItem     `json:"worklist"`
	Statuses       []MemberStatus `json:"statuses"`
	// Budget is the intent's declared generation-budget envelope folded into one row
	// per contract dimension (Time/Tokens/Workers/Review), each carrying the declared
	// cap and the per-worklist-member share. Always four rows: an unbudgeted dimension
	// renders as a HOLD row, which is itself the contract's operator warning.
	Budget []BudgetRow `json:"budget"`
	// Mix is the gardening-vs-throughput split of the worklist — how much of what this
	// walk says to enter is quality-tending versus backlog-draining, and which way the
	// soft target-ratio tie-break leaned (#3126). Always present; a walk with no work
	// (an empty worklist) reports all-zero counts and no favor.
	Mix        WorkMix `json:"mix"`
	Verdict    string  `json:"verdict"`
	Finding    string  `json:"finding"`
	Reason     string  `json:"reason"`
	NextAction string  `json:"next_action"`
}

WalkReport is the folded intent-level verdict + the worst-first worklist: the answer to "I asked to <intent> — what is the status of everything under it, and what should I enter first?"

func Walk

func Walk(s Super, statuses []MemberStatus, opts ...WalkOpt) WalkReport

Walk folds the member statuses the shell read into the intent-level verdict and a worst-first worklist. Ordering (the SELECT step): dark/unmeasured members first (a gone-dark loop or an unreadable member is the most urgent thing to enter), then by debt descending, ties broken by the member's declared order (stable). The intent is SATISFIED only when total debt is at-or-below Floor AND every member was measured AND none is dark AND any declared issue-target with measured progress is met — an unread or dark member, or an unmet headline, can never read as clean. Live measurements the pure package cannot read (e.g. issue progress) arrive via WalkOpts.

type WorkClass

type WorkClass string

WorkClass is the gardening-vs-throughput bucket a member's work falls into — the axis a night has to keep in balance (#3126). A fleet that spends every tick tending quality while open issues pile up is as out of balance as one that drains issues while the gardens rot; the walk classifies each member so the mix is visible and a soft tie-break can nudge a lopsided run back toward its declared target.

const (
	// WorkGardening is tend-the-house work: scorecards, the garden bundle, and named
	// control surfaces. It retires quality/hygiene debt rather than moving the backlog.
	WorkGardening WorkClass = "gardening"
	// WorkThroughput is issue-drain work: the dispatch loops and drain-* intents that
	// move open issues toward done. It is the backlog-clearing output of a run.
	WorkThroughput WorkClass = "throughput"
	// WorkNeutral is everything the gardening/throughput axis does not name — capacity
	// signals (utilization) and non-drain report loops (cadence, dojo, dogfood). It is
	// surfaced for visibility but never weighed by the mix tie-break.
	WorkNeutral WorkClass = "neutral"
)

type WorkItem

type WorkItem struct {
	Rank      int    `json:"rank"`
	Member    Member `json:"member"`
	Debt      int    `json:"debt"`
	Dark      bool   `json:"dark"`
	Container bool   `json:"container"`
	Action    string `json:"action"`
	Detail    string `json:"detail"`
	// Allocation is this member's divided share of the intent's declared budget —
	// the top-of-cascade input the drive rung binds to the member's budget.* / cap
	// env when it enters. It is a reservation, not an enforcement: no cap is applied
	// here (see [Allocation]).
	Allocation Allocation `json:"allocation"`
}

WorkItem is one worst-first entry in the walk's plan: enter this member next, and why. Rank is 1-based in worst-first order. Container carries the status's descend- pointer bit through to the renderer, so an unread container shows "→" while a descended sub-super-loop shows its real folded debt.

type WorkMix

type WorkMix struct {
	Gardening           int       `json:"gardening"`
	Throughput          int       `json:"throughput"`
	Neutral             int       `json:"neutral"`
	TargetThroughputPct int       `json:"target_throughput_pct"`
	Favor               WorkClass `json:"favor,omitempty"`
}

WorkMix is the folded gardening-vs-throughput split of a walk's worklist. The three counts tally the worklist members by WorkClass; TargetThroughputPct echoes the resolved soft target (declared or default); Favor names the class the tie-break nudged toward this walk, or "" when the mix is already on target or one side is absent (a tie-break needs BOTH classes present to have anything to trade).