sample

package
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package sample is the weekly sample of the docs the documentalist vouched for (ADR-0014, step 4): one in ten of the docs whose `checked` it moved in a week, read whole against their sources at the commit `checked` names, by a judge standing apart from the model that vouched (ADR-0005). Drawing the sample takes no AI; the read is the only call, and the engine checks every quote the judge gives. What it found goes to the forge, in a job holding the forge's token and no AI key (Apply): one tracking issue, a comment per week, and a merge request putting back a `checked` found false.

Index

Constants

View Source
const ActsIssueTitle = "workline: the weekly sample of the product owner's acts"

ActsIssueTitle is the tracking issue of the product owner's acts.

View Source
const IssueTitle = "workline: the weekly sample of the docs vouched for"

IssueTitle is the tracking issue's: one, kept open, a comment a week.

View Source
const OneIn = 10

OneIn is the share of the docs vouched for that is read: one in ten, rounded up, so a week with any reads at least one.

View Source
const StepZeroLabel = "documentalist-step-0"

StepZeroLabel marks the tracking issue once a `checked` is found false: the documentalist is set back to step 0 (ADR-0014), until a person takes the label off.

Variables

This section is empty.

Functions

func Pick

func Pick(week string, cands []candidate) []candidate

Pick draws one in OneIn of the candidates, rounded up, the same each time for the same week: each is ranked by a digest of the week, the doc and the commit, and the first are taken.

func Week

func Week(week string, now time.Time) (string, time.Time, time.Time, error)

Week reads an ISO week (2026-W40) and the instants it starts and ends, in UTC; with none, the last whole week before now.

Types

type ActsRead added in v0.16.0

type ActsRead struct {
	Issue  int     `json:"issue"`  // the tracking issue written
	Report int     `json:"report"` // the product owner's report the record was read from
	Level  string  `json:"level"`  // the level in force at its last run
	Week   int     `json:"week"`   // the acts done alone in the week
	Drawn  []Drawn `json:"drawn"`
	// Counted are the acts done alone at Level that the record keeps, up to
	// the week's end; Undone, those a person undid.
	Counted int    `json:"counted"`
	Undone  int    `json:"undone"`
	Suggest string `json:"suggest,omitempty"`
	Why     string `json:"why,omitempty"`
}

ActsRead is what the sample drew of the product owner's acts.

type Drawn added in v0.16.0

type Drawn struct {
	backlog.Did
	Undone string `json:"undone,omitempty"` // what shows it undone
}

Drawn is one act drawn, and whether a person undid it.

type Options

type Options struct {
	Repo     string
	RolesDir string
	Week     string    // the ISO week sampled, 2026-W40; default the last whole week
	Since    string    // read what was vouched for after this commit, up to HEAD, instead of a week
	Judge    string    // an --ai value; default WORKLINE_JUDGE, then the `sample.judge` setting
	Now      time.Time // when the run is, for the default week
}

Options say what to sample and who reads it.

type Proof

type Proof struct {
	Passage string `json:"passage"`
	Path    string `json:"path,omitempty"`
	Line    int    `json:"line,omitempty"`
	Quote   string `json:"quote,omitempty"`
	Name    string `json:"name,omitempty"`
	Why     string `json:"why,omitempty"`
}

Proof is a passage said false, and the source's words saying otherwise.

func (Proof) String

func (p Proof) String() string

String is a proof as the findings and the issue say it.

type Read

type Read struct {
	Doc      string            `json:"doc"`
	Commit   string            `json:"commit"`             // the commit that moved its `checked`
	Checked  map[string]string `json:"checked"`            // what it moved it to
	Previous map[string]string `json:"previous,omitempty"` // what it was before
	By       []string          `json:"vouched-by,omitempty"`
	// Verdict: true, false (a passage proven false), unproven (passages
	// said false, none proven), unearned (its sources do not fit whole), or
	// not-read.
	Verdict      string  `json:"verdict"`
	Why          string  `json:"why,omitempty"`
	Judge        string  `json:"judge,omitempty"`
	Model        string  `json:"model,omitempty"`
	Independence string  `json:"independence,omitempty"`
	Proofs       []Proof `json:"proofs,omitempty"`
	Unproven     []Proof `json:"unproven,omitempty"`
}

Read is one doc of the sample, and what its reading found.

type Result

type Result struct {
	Status     string            `json:"status"`
	Summary    string            `json:"summary,omitempty"`
	Findings   []verdict.Finding `json:"findings,omitempty"`
	AgentCalls int               `json:"agent-calls"`
	Calls      []agent.Call      `json:"calls,omitempty"`
	Applied    []string          `json:"applied"`
	Refused    []string          `json:"refused"`
	Week       string            `json:"week"`
	From       string            `json:"from,omitempty"` // the window: commits after From, up to To
	To         string            `json:"to,omitempty"`
	Window     string            `json:"window"` // the window, in words
	Vouched    int               `json:"vouched"`
	Reads      []Read            `json:"reads"`
	Acts       *ActsRead         `json:"acts,omitempty"` // the product owner's acts drawn, written with --apply (ADR-0033)
}

Result is what a sample found, and what applying it wrote.

func Apply

func Apply(file, repo string, f forge.Forge) *Result

Apply writes what a sample found to the forge: the week's comment on the tracking issue, the step-0 label when a `checked` is false, and a merge request putting back each false `checked` still standing.

func Draw

func Draw(o Options) *Result

Draw picks the week's sample and has each doc of it read.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL