backlog

type Acts struct {
	Level string
	Did   []Did
	// contains filtered or unexported fields
}

type Announcement struct {
	Quote     Quote  `yaml:"quote"`
	Why       string `yaml:"why"`
	Commit    string `yaml:"commit"`
	Announced string `yaml:"announced"`    // the day it was announced, YYYY-MM-DD
	By        string `yaml:"by,omitempty"` // the model that proposed it
}

type Answer struct {
	Notes    []string `yaml:"notes,flow"` // the comments read, by the forge's id
	Who      string   `yaml:"who"`        // the last one's author
	Revision int      `yaml:"revision"`   // this revision's number, from 1
}

type Backlog struct {
	Next    *forge.Issue
	Waiting map[int][]int // each issue waiting on an open one, and on which
	Blocked []int         // those issues, in the backlog's order
	Cycles  [][]int
}

type Board struct {
	NextMax   int
	StuckDays int
	Next      []forge.Issue
	Stuck     []Wait
	// contains filtered or unexported fields
}

type Change struct {
	Issue int      `yaml:"issue"`               // the issue whose sections changed, or the one opened from the lines
	What  []string `yaml:"what,flow,omitempty"` // the sections a person rewrote
	Path  string   `yaml:"path,omitempty"`      // an imported file whose lines changed
	Lines string   `yaml:"lines,omitempty"`     // those lines then, and now: "7-8 → 7-9"
	Since string   `yaml:"since,omitempty"`     // the day it was found, YYYY-MM-DD
	Touch []Touch  `yaml:"touched"`             // the open issues it touches
	Was   string   `yaml:"was,omitempty"`       // the text before, for the agent (not kept in the record)
	Now   string   `yaml:"now,omitempty"`       // the text after, for the agent (not kept in the record)
}

type Child struct {
	Title        string   `yaml:"title"`
	Need         string   `yaml:"need"`
	Verification string   `yaml:"verification"`
	Validation   string   `yaml:"validation"`
	Scope        string   `yaml:"scope"`
	Sources      []string `yaml:"sources,omitempty"`
	After        []int    `yaml:"after,flow,omitempty"` // the children it waits on, by their place in the split, from 1 (ADR-0028)
}

type ClosedImport struct {
	Issue    forge.Issue
	From, To int
	Lines    string // as a skip names them: "12", or "12-14"
}

type Closing struct {
	Issue int    `yaml:"issue"`
	Act   string `yaml:"act"`
	Level string `yaml:"level,omitempty"` // the autonomy level it was done at
}

type Config struct {
	Level        string             // cautious, normal or enterprising
	Acts         map[string]Setting // each kind's mode and cap, the project's laid over the level's
	Origins      map[string]string  // each kind's: level or setting
	MovedPercent int                // the share of the open issues a run moves
	NextMax      int                // the ready issues the job's summary lists first; 0 none (ADR-0031)
	StuckDays    int                // the days an issue waits on a person before the summary says it stuck
	// UndoneMax: the acts of a kind a person undoes, across the issues,
	// before that kind is proposed everywhere; ProposalsMax, the issues
	// waiting on a person before the role reads only those answered
	// (ADR-0038).
	UndoneMax    int
	ProposalsMax int
	// ChangedNeeds: a person's change to a Need or a Scope, or to an
	// imported file's lines, flags the issues built on it (ADR-0032); off
	// unless set (ADR-0038).
	ChangedNeeds bool
	// Gone are the settings the project still sets that the role no
	// longer reads: said, never silently ignored.
	Gone []string
	// Archived are the files no longer a source, as globs: an issue
	// imported from one is not flagged when its lines change (ADR-0032).
	Archived []string
	// SpecReview: the project's line runs the reviewer after the role, so
	// ready is held while the reviewer's important findings on the spec are
	// open (#128); set by the caller, from the routing.
	SpecReview bool
}

type Coverage struct {
	File       string   `json:"file"`
	Items      []Mapped `json:"items"`
	NotCovered []Mapped `json:"not-covered"`
}

type Decision struct {
	Index  int      `yaml:"index"` // the intention's place in the run
	Mode   string   `yaml:"mode"`  // act, propose, or off (dropped)
	Act    Proposal `yaml:"act"`
	Capped bool     `yaml:"capped,omitempty"` // proposed only for the cap
}

type Did struct {
	Issue int    `yaml:"issue,omitempty"` // left out in the issue's own state
	Act   string `yaml:"act"`             // its kind, as the settings name it: close-duplicate, rename…
	Level string `yaml:"level"`           // the autonomy level it was done at
	Day   string `yaml:"day"`             // the day, YYYY-MM-DD, UTC
	Line  string `yaml:"line,omitempty"`
	Yes   string `yaml:"yes,omitempty"` // who accepted it: done on their yes, not alone
	// contains filtered or unexported fields
}

type Done struct {
	Issue int    `yaml:"issue,omitempty"` // left out in the issue's own state
	Act   string `yaml:"act"`
	Was   string `yaml:"was,omitempty"`
	Set   string `yaml:"set,omitempty"`
	Level string `yaml:"level,omitempty"` // the autonomy level it was done at
}

type Evidence struct {
	Body       string
	Parts      int
	Closed     int      // the parts closed, or gone from the forge
	Undone     []int    // the parts closed without delivering: not planned, a duplicate, gone
	Unproved   []string // the Verification items no part delivered quotes, or whose test is not in the code
	NoTest     []string // the tests a quoted item names that the code does not hold
	TestUnread []string // the tests a quoted item names that could not be looked for, with why
	Unread     []Part   // the parts whose closer the forge refused to say, with why
	AllClosed  bool
}

type Exchange struct {
	Rounds   int      // the engine's comments to the reporter
	Answered bool     // a person's comment after the last of them
	Asked    []string // each one's text, its marker left out
}

type ImportOpen struct {
	Title   string
	Quote   Quote
	Capped  bool // not opened, past the cap of open
	Dropped bool // refused by the engine, a finding saying why
	// Opening is what opening it did, as the run recorded it: the issue
	// that holds it, and whether it was opened then.
	Opening *Recorded
}

type ImportShare struct {
	From, To int // the lines it was given
	// Own is its last line to answer for: those after it are read again by
	// the next share, which answers for them.
	Own   int
	Opens []ImportOpen
	Skips []Skip
}

type Judged struct {
	Yes    *bool  `yaml:"yes"`
	Why    string `yaml:"why"`
	Model  string `yaml:"model"`
	Level  string `yaml:"level"`
	Author string `yaml:"author"`
	Error  string `yaml:"error"`
}

type KindMode struct {
	Kind   string
	Mode   string
	Max    int
	Drafts string // refine: Need and Validation proposed when "propose"
	Origin string
}

type Ledger struct {
	Report int    // an open report issue of an earlier engine: its record read once, then it is closed
	Record Record // the issues' records, as one
	Broken error  // the old report's record does not read
	States map[int]*State
	Notes  map[int][]forge.Note
	// Aside are the issues a person took workline:proposed off since the
	// last run, without accepting: "not now", that issue only, until it
	// changes.
	Aside map[int]bool
	// Undone are the role's acts a person undid since the last run, other
	// than closings; Standing, those still watched (ADR-0026).
	Undone   []Undo
	Standing []Done
	// Own are the blockers the role set on each open issue: a depend's, a
	// split's after (ADR-0028).
	Own map[int][]int
	// Signs are what a person did that a run with no agent still writes:
	// a yes, an answer, a label taken off, an act undone, the report to
	// move.
	Signs []string
}

type Mapped struct {
	Lines string `json:"lines"`
	From  int    `json:"from"`
	To    int    `json:"to"`
	Words string `json:"words"`
	State string `json:"state,omitempty"`
	Issue int    `json:"issue,omitempty"`
	Why   string `json:"why,omitempty"`
}

type Obsolete struct {
	Announcement *Announcement // nil: none waiting
	Due          bool          // its delay passed, nothing cancels it: a judge decides
	From         string        // the day it may be closed from
	Keep         string        // why it is kept open, when it is
	Say          bool          // the issue is told why it is kept: no person did it
}

type Opening struct {
	Role    string   // the role that found it, named in the issue
	Key     string   // the marker's key: issue=<subject>, or import=<a file's text>
	Also    []string // older keys the same subject was opened under
	Title   string
	Body    string
	From    string   // where it was opened from, said after "Opened": " from `ROADMAP.md`"
	Sources []string // the code it is about, for the keeper's state
	Commit  string   // the commit it was seen at
	Triage  bool     // a role's finding: labelled needs-triage, capped, said once when found after it was closed
	Wrote   []string // the sections the role wrote in its body, recorded in the keeper's state (#128)
	Quiet   bool     // where it came from hidden from a reader, kept for the engine: an import, a person's words
	// Found says where the role found it, for a person: "while reviewing
	// ccffcb2, outside that change"; the line it ends with is then "Found
	// by the … role …".
	Found string
}

type Openings struct {
	Max int // a run's findings opened as issues, at most; the rest Capped
	// contains filtered or unexported fields
}

type Part struct {
	ID      int
	Issue   forge.Issue
	Closers []forge.Closer
	Unread  error
	Gone    bool
}

type Pending struct {
	Issue int    `yaml:"issue,omitempty"` // left out in the issue's own state
	Act   string `yaml:"act"`
	Line  string `yaml:"line"`
	Key   string `yaml:"key,omitempty"` // an issue to open: the text it would be opened from (ImportKey)
	// Capped: proposed only because the run's cap was reached, not left to
	// a person by its mode: its issue is read again at the next run.
	Capped bool `yaml:"capped,omitempty"`
	// Proposal is what the engine would do, as decided: done as it says
	// when a person of the project labels the issue workline:accepted
	// (ADR-0038).
	Proposal *Proposal `yaml:"proposal,omitempty"`
	// Since is the day it was first proposed, YYYY-MM-DD: the job's summary
	// says it stuck past stuck-days (ADR-0031).
	Since string `yaml:"since,omitempty"`
}

type Plan struct {
	Decisions []Decision        `yaml:"decisions"`
	Findings  []verdict.Finding `yaml:"findings"`
	Record    Record            `yaml:"record"`
	// Report is an earlier engine's report issue, still open: its record
	// moved to the issues, and Moved, it is closed at the end of the run
	// (ADR-0038).
	Report int  `yaml:"report,omitempty"`
	Moved  bool `yaml:"moved,omitempty"`
	// Visit are the open issues with a state, written back at the end of
	// the run (Persist); SetAside, those a person took workline:proposed
	// off; Answers, a person's comments read as "revise" on each.
	Visit    []int           `yaml:"visit,flow,omitempty"`
	SetAside map[int]bool    `yaml:"set-aside,omitempty"`
	Answers  map[int]*Answer `yaml:"answers,omitempty"`
	// contains filtered or unexported fields
}

type Proposal struct {
	Do          string   `yaml:"do"` // close or sources: the intention's kind
	Issue       int      `yaml:"issue"`
	Reason      string   `yaml:"reason,omitempty"`
	DuplicateOf int      `yaml:"duplicate-of,omitempty"`
	Sources     []string `yaml:"sources,omitempty"`
	Milestone   string   `yaml:"milestone,omitempty"`
	Title       string   `yaml:"title,omitempty"`           // an issue to open, or an issue's new title (rename)
	Into        []Child  `yaml:"into,omitempty"`            // the children of a split
	BlockedBy   []int    `yaml:"blocked-by,flow,omitempty"` // depend: the issues it waits on; undepend: those taken off (ADR-0028)
	// Native, the engine's: the blockers an undepend takes off the forge's
	// own relation, the rest being in the engine's line; never the agent's.
	Native []int  `yaml:"native,flow,omitempty"`
	Quote  *Quote `yaml:"quote"`
	Why    string `yaml:"why"`
	// Refining: the sections written, Need and Validation as drafts, with
	// a real example of the need or a bug's steps to reproduce, drafts too,
	// never required; Added, the engine's, says which the body did not have
	// yet.
	Scope        string `yaml:"scope,omitempty"`
	Verification string `yaml:"verification,omitempty"`
	Need         string `yaml:"need,omitempty"`
	Example      string `yaml:"example,omitempty"`
	Steps        string `yaml:"steps,omitempty"`
	Validation   string `yaml:"validation,omitempty"`
	// Description, the text above its sections rewritten in plain words:
	// only where the role opened it and no person edited it (Rewrite).
	Description string   `yaml:"description,omitempty"`
	Added       []string `yaml:"added,omitempty"`
	// Revise, the engine's: the sections with text this refine may rewrite,
	// to answer the reviewer's findings on the spec (#128) — the role's own
	// only (Revisable); never taken from the agent.
	Revise []string `yaml:"revise,omitempty"`
	// Refused, the engine's: the sections the role wrote that a person
	// deleted (State.Deleted), never written again (ADR-0038).
	Refused   []string `yaml:"refused,omitempty"`
	Questions string   `yaml:"questions,omitempty"` // asking the reporter; for an outsider's refine, what it still needs
	// The engine's, for the conversation with the reporter: the round this
	// comment would be, and whether a refine is proposed to the reporter in
	// a comment rather than written in the body (an outsider's issue).
	Round      int  `yaml:"round,omitempty"`
	ToReporter bool `yaml:"to-reporter,omitempty"`
	// LeftOut, the engine's: the questions asked before, taken out of it;
	// said once the act is decided, never when it is dropped.
	LeftOut []string `yaml:"-"`
	// Agreed, the engine's: who agreed in a reply to the text last proposed
	// to the reporter, which this refine writes; checked again on the forge
	// (Agreement), never taken from the agent.
	Agreed string `yaml:"agreed,omitempty"`
	Spent  bool   `yaml:"spent,omitempty"` // the rounds spent: proposed to a person
	// Hearsay, the engine's: the words it quotes are only in a comment by
	// someone outside the project — proposed, never done alone (ADR-0038).
	Hearsay bool `yaml:"hearsay,omitempty"`
	// Ordering: the priority set (1 to 4); a milestone left because it is
	// released (From, the engine's); and, the engine's, the issue's
	// priority and milestone before the run, written in the report.
	Priority int    `yaml:"priority,omitempty"`
	From     string `yaml:"from,omitempty"`
	Before   string `yaml:"before,omitempty"`
	// Obsolete (ADR-0024): Announced, on the engine's closing, the day of
	// the announcement it follows; Announce and Until, the engine's, that
	// this act announces rather than closes, and the day from which it may
	// close; Judge, the engine's, the second judge's yes and its level;
	// Say, on a keep, that the issue is told why.
	Announced string `yaml:"announced,omitempty"`
	Announce  bool   `yaml:"announce,omitempty"`
	Until     string `yaml:"until,omitempty"`
	Judge     string `yaml:"judge,omitempty"`
	Say       bool   `yaml:"say,omitempty"`
	// Advice, the engine's: a closing whose kind is off (close-obsolete,
	// by default), said on the issue for a person to close, never done by
	// the role nor by a yes (ADR-0038: off, the code kept).
	Advice bool `yaml:"advice,omitempty"`
	// Ticked, the engine's: who ticked this proposal's box in the report, a
	// person of the project — checked again on the forge, the act done as
	// the record says, never as the intention does (ADR-0025).
	Ticked string `yaml:"ticked,omitempty"`
}

type Quote struct {
	Path  string `yaml:"path,omitempty"`
	Issue int    `yaml:"issue,omitempty"`
	Text  string `yaml:"text"`
}

type Record struct {
	Closed  []Closing `yaml:"closed,omitempty"`
	Wrong   []Closing `yaml:"wrong,omitempty"`        // closings found wrong: their issue open again
	Propose []string  `yaml:"propose,flow,omitempty"` // kinds of act proposed on every issue: undone too often (UndoneMax)
	// Done are the role's own acts a person may undo, other than closings:
	// a rename, a priority, a milestone, ready, a split (ADR-0026); Undone,
	// those a person undid, with what shows it.
	Done     []Done    `yaml:"done,omitempty"`
	Undone   []Undo    `yaml:"undone,omitempty"`
	Proposed []Pending `yaml:"proposed,omitempty"` // acts proposed, kept until their issue is closed, set aside or proposed again
	// Did are the acts the role did, with their day and level, for its
	// comment on each issue and the weekly sample (ADR-0033).
	Did []Did `yaml:"did,omitempty"`
}

type Recorded struct {
	Index   int    `yaml:"index"` // the intention's place in the run
	Outcome string `yaml:"outcome"`
	Issue   int    `yaml:"issue"`
}

type Setting struct {
	Mode   string
	Max    int
	Rounds int      // asking: the times an issue's reporter is written to, then a person (ask only)
	Days   *int     // close-obsolete: the days an announcement waits; ObsoleteDays when nil
	Exempt []string // close-obsolete: labels that keep an issue from it; DefaultExempt when nil
	Drafts string   // refine: propose has Need and Validation drafts proposed, Scope and Verification written (ADR-0026)
}

type Skip struct {
	Lines  any    `yaml:"lines"` // "12", or "12-14"
	Reason string `yaml:"reason"`
	Quote  *Quote `yaml:"quote,omitempty"`
	Issue  int    `yaml:"issue,omitempty"`
	Why    string `yaml:"why,omitempty"`
}

type SpecReview struct {
	Body    string   // the digest of the body it read (BodyDigest); "" when no review was whole
	Round   int      // the reviews in a row that found an important finding open, this one included
	Open    int      // the important findings open, as it read the body
	In      []string // the sections their causes lie in, by heading
	Stopped bool     // the rounds spent: put to a person, not read again
}

type State struct {
	Sources   []string `yaml:"sources"`
	Confirmed string   `yaml:"confirmed"`
	Judged    string   `yaml:"judged,omitempty"`   // the commit the role last read it at
	Comments  int      `yaml:"comments,omitempty"` // people's comments when it was last read
	Body      string   `yaml:"body,omitempty"`     // a digest of its body, when the role last read or wrote it
	Priority  int      `yaml:"priority,omitempty"` // the priority the role last set: another on the issue is a person's
	Title     string   `yaml:"title,omitempty"`    // the title the role last set: another on the issue is a person's
	Split     []int    `yaml:"split,omitempty"`    // the children the role split it into: it is not split again
	// After are the blockers the role's split set on each child, among
	// its siblings: the role's own links, taken off once a blocker closes
	// (ADR-0028).
	After map[int][]int `yaml:"after,flow,omitempty"`
	Kept  []string      `yaml:"kept,omitempty"` // the evidence an announcement as obsolete rested on, kept open: not announced again for it
	// Sections are its Need and Scope as last read or written (Basis): a
	// person's change to them touches the issues built on it (ADR-0032).
	Sections map[string]string `yaml:"sections,omitempty"`
	// Wrote are the sections the role wrote, each the digest of its text:
	// another text there is a person's (SectionDigest). Answered is the
	// review of its spec the role was last given, by the digest of the
	// body that review read (#128): a review restarting at round 1 is
	// another review, never taken for one answered.
	Wrote    map[string]string `yaml:"wrote,omitempty"`
	Answered string            `yaml:"answered,omitempty"`
	// Plain is the digest of the description the role rewrote in plain
	// words (ADR-0038, amended): another text there is a person's.
	Plain string `yaml:"plain,omitempty"`
	// Deleted are the sections the role wrote that a person took out of
	// the body: a "no" for each, never written again (ADR-0038).
	Deleted []string `yaml:"deleted,flow,omitempty"`
	// What the role holds on this issue, in place of a report (ADR-0038):
	// the acts it proposes here; those it did alone a person may undo;
	// those a person undid — proposed here from then on —; what it did,
	// each with its day; the kind of act it closed it with, should it open
	// again.
	Proposed []Pending `yaml:"proposed,omitempty"`
	Done     []Done    `yaml:"done,omitempty"`
	Undone   []Undo    `yaml:"undone,omitempty"`
	Did      []Did     `yaml:"did,omitempty"`
	Closed   string    `yaml:"closed,omitempty"`
	// Label is the label the role put on it while it waits on a person
	// (workline:proposed); Aside, the body's digest when a person took it
	// off: nothing proposed until the issue changes.
	Label string `yaml:"label,omitempty"`
	Aside string `yaml:"aside,omitempty"`
	// Heard are the comments of its reporter and the project's people the
	// role read; Revisions, the times it revised its drafts for them.
	Heard     *int `yaml:"heard,omitempty"`
	Revisions int  `yaml:"revisions,omitempty"`
	// Rules is the role's way of reading an issue when it last read it
	// (Reading): an issue it left with nothing is read again once they
	// change.
	Rules int `yaml:"rules,omitempty"`
}

type TestFinder func(name string) (string, error)

type Touch struct {
	Issue int    `yaml:"issue"`
	How   string `yaml:"how"`
	Files string `yaml:"files,omitempty"` // the code shared, for TouchSources
	Read  bool   `yaml:"read,omitempty"`  // read again by the run that found it, with the change
}

type Undo struct {
	Issue    int    `yaml:"issue,omitempty"` // left out in the issue's own state
	Act      string `yaml:"act"`
	Evidence string `yaml:"evidence"`
	Day      string `yaml:"day,omitempty"` // when a run found it, YYYY-MM-DD: the weekly sample counts it against one act
}

type Wait struct {
	Issue int    `yaml:"issue"`
	Waits string `yaml:"waits"`
	Since string `yaml:"since"`          // the day it started waiting, YYYY-MM-DD
	Act   string `yaml:"act,omitempty"`  // proposed: the kind of act
	Line  string `yaml:"line,omitempty"` // proposed with no issue (an issue to open): its line
}