lane

type DefaultBoard struct {
	Lanes    []string
	Options  []string
	Path     string
	Warnings []string
	// Body is the prose below the frontmatter, preserved across a save so
	// SaveDefaultBoard never erases a note the user left themselves.
	Body string
}

type DriftEntry struct {
	ID            string
	ProjectPath   string
	CataloguePath string
}

type Lane struct {
	ID          string
	Name        string
	Description string

	// After anchors ordering to another lane's ID. Anchoring is used instead of
	// a numeric position because two independently written lane files would
	// otherwise both claim the same slot.
	After string

	// Precedence orders lanes by how far along the work is, and is what a merge
	// consults so concurrent edits never revert forward progress. It is
	// deliberately separate from display order: Blocked appears last on the
	// board but must not outrank active work in a merge.
	Precedence int

	// Agentic marks a lane whose work is performed by a subagent.
	Agentic   bool
	Terminal  bool
	ModelTier string

	// Context says whether the agent working this lane may be the one that
	// worked the lanes before it. "fresh" means it may not: the lane is handed
	// to a new agent that has seen nothing of the ticket's work, because a
	// judge who wrote what it judges is not a judge. "shared" says the
	// opposite out loud, and empty means the file does not say. A single
	// agent carries a ticket through every other agentic lane itself.
	//
	// Load resolves the empty case for the whole board: when no lane declares
	// a context at all, the last agentic lane before the first lane a person
	// owns is fresh, with ContextImplied set — so a board written before the
	// field existed keeps a fresh review without a migration. See
	// impliedFresh.
	Context        string
	ContextImplied bool
	// ContextInvalid holds a context: value that is neither fresh nor shared —
	// a typo like "Fresh". Such a lane still loads and runs fresh, but it does
	// not count as having declared a context: the board's default still
	// applies when no lane carries a valid value, so a typo can add a fresh
	// lane and never take one away. Load warns about it and 'jaira validate'
	// fails on it.
	ContextInvalid string

	// Holds caps how many tickets the lane keeps. After a move lands a ticket
	// here, the oldest beyond the newest Holds leave for the logbook — reported,
	// never silent. 0 or absent means unlimited. Declared in the lane file so the
	// one rule that moves files can be read, changed or switched off there.
	Holds int

	// LogbookOnEntry files a ticket straight into the logbook the moment a
	// move lands it here — commits stamped first, reported, never silent. The
	// lane is a doorway, not a shelf: the logbook is the record of finished
	// work, so it gets everything immediately. Terminal lanes only.
	LogbookOnEntry bool

	// InputRequires names the ticket fields assembled into a subagent's bounded
	// input. OutputProduces names the fields it must return.
	InputRequires  []string
	OutputProduces []string

	RequiresQuestion       bool
	RequiresOutcome        bool
	RequiresNonModelSignal bool

	// RequiresBlockedReason means a ticket may not be parked here without saying
	// what it is waiting on. Parking is cheap and forgetting is silent, so this
	// is the one place the board charges for it.
	RequiresBlockedReason bool

	// RequiresCommits means a ticket cannot enter this lane without naming the
	// commits that carry its change. It sits on the done lane rather than on
	// the implementing lane's output contract, so work can move through review
	// uncommitted — but nothing is accepted that cannot be checked.
	RequiresCommits bool

	// RequiresHumanExit means no agent may move a ticket on out of this lane —
	// back to an earlier lane is allowed, since that accepts nothing. It is
	// the difference between a review step that is conventionally respected and
	// one that actually stops: an agent that decides its own work passed review
	// would make the step decorative.
	RequiresHumanExit bool

	// RequiresOption names an entry in a ticket's Options checklist. When set,
	// this lane is only part of a ticket's path if that option is ticked — which
	// is how one ticket is planned and reviewed while another goes straight to
	// implementation, without either lane being uninstalled.
	RequiresOption string

	// RejectsTo names the lanes a ticket goes back to when this lane finds the
	// work wanting: the loop's back edges, written down. Moving backwards has
	// always been allowed — the gate only checks a move that advances (see
	// core/gate) — but nothing declared where back was, so the route lived in
	// the prompt's prose and an agent reading the board could not see it.
	//
	// More than one is allowed because a rejection is not one kind of thing: a
	// critique that found a flaw sends the work back to be implemented, while a
	// critique that found a decision to make hands it to a person instead. Both
	// are the same lane's back edge and a reader has to be able to see both.
	//
	// It is documentation the tool validates, not a rail: nothing forces a
	// rejection to go here, exactly as nothing forces a lane's prompt to be
	// followed.
	RejectsTo []string

	// RequiresSpecified marks the first lane, in precedence order, that sets
	// this: the boundary between thinking about a ticket and working on it.
	// Everything before it is a place a half-formed ticket may sit; nothing at
	// or after it may hold a ticket that is missing its promotion fields.
	RequiresSpecified bool

	// Prompt is the markdown body: the instruction given to the subagent.
	Prompt string

	// Creator names who wrote this lane, for provenance once a lane has been
	// adopted or copied between machines. A built-in with no creator: field
	// defaults to "jaira" rather than having the field written into all nine
	// shipped files; a custom lane with no creator: field is left empty, since
	// "shipped by the tool" and "author unknown" are different facts.
	Creator string

	// Builtin distinguishes shipped lanes from user-installed ones: it says
	// the lane travels inside the binary, nothing more.
	Builtin bool
	// Default says the lane belongs to a fresh board's selection. It is the
	// second half of what Builtin used to carry alone: a shipped lane that is
	// installable without the network but must not be forced on every board —
	// critique, optimize, testing — ships with "default-board: false" and is
	// built-in without being default.
	Default bool
	// Source is the path a custom lane came from, for error messages.
	Source string
	// Overrides names the built-in this lane displaced, empty if it does not
	// override anything. Set by Load, not by parse: overriding is a fact about
	// resolution, not about the file itself.
	Overrides string
	// Unknown marks a synthetic passthrough lane created for a ticket whose
	// status names a lane this installation does not have.
	Unknown bool
}

type Set struct {
	Lanes []*Lane

	// Warnings records non-fatal problems (a custom lane anchored to a lane that
	// is not installed, for instance) so the caller can surface them without
	// failing to draw a board.
	Warnings []string
	// contains filtered or unexported fields
}

type SharedLane struct {
	Lane   *Lane
	Folder string
	Path   string
}