sample

package
v0.32.0 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package sample is the weekly sample of every role's acts (ADR-0046): one in ten of a week's acts per role and kind. The docs the documentalist vouched for (ADR-0014, step 4) are read whole against their sources at the commit `checked` names, by a judge standing apart from the model that vouched (ADR-0005); the other roles' acts are drawn and listed for a person. Drawing the sample takes no AI, and reads the forge without writing to it; 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 IssueTitle = "workline: the weekly sample of every role's acts"

IssueTitle is the tracking issue's: one, kept open, a comment a week, and the count (ADR-0046).

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 Act added in v0.29.0

type Act struct {
	Role string `json:"role"`
	// Kind: the product owner's act as its record names it (ready,
	// refine…); a finding the reviewer's judge kept or dropped; a commit
	// the committer rewrote.
	Kind   string `json:"kind"`
	Ref    string `json:"ref"`              // its issue or merge request as the forge names it (#205, !7), or its commit
	In     string `json:"in,omitempty"`     // the merge request a commit came in by, read on its head
	Where  string `json:"where,omitempty"`  // a finding's place: path:line
	Commit string `json:"commit,omitempty"` // the commit it was done at, when its record says
	Day    string `json:"day,omitempty"`    // the day it was done, YYYY-MM-DD, when its record says
	By     string `json:"by,omitempty"`     // the level it was done at, or the models that acted, when its record says
	Line   string `json:"line,omitempty"`   // what its record says of it
	Lens   string `json:"lens,omitempty"`   // a finding's lens
	Title  string `json:"title,omitempty"`  // a finding's title, all its judge's answer left out
	// A product owner's act: the agents and models that acted and the
	// digest of the issue's text it read, when its record says
	// (ADR-0046); what shows a person undid it since (ADR-0033).
	Acted  string `json:"acted,omitempty"`
	Body   string `json:"body,omitempty"`
	Undone string `json:"undone,omitempty"`
	// Verdict: true (it stands), false (proven wrong, with the
	// material's words), unproven (said wrong, not proven: for a person),
	// or not-read (for a person, Why says why).
	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"`
	Panel        *Panel  `json:"panel,omitempty"`  // how a false verdict was settled
	Defect       *Defect `json:"defect,omitempty"` // a true finding its judge dropped, for an issue
	// contains filtered or unexported fields
}

Act is an act of a role the sample drew.

type Autonomy added in v0.31.0

type Autonomy struct {
	Level   string `json:"level"`
	Counted int    `json:"counted"`
	Undone  int    `json:"undone"`
	Until   string `json:"until"` // the last day counted, YYYY-MM-DD
	Suggest string `json:"suggest,omitempty"`
	Why     string `json:"why,omitempty"`
}

Autonomy is what the product owner's acts done alone suggest of its level (ADR-0033): over those at the level of its last act, up to the window's end — how many, how many a person undid, the level they suggest and why.

type Count added in v0.29.0

type Count struct {
	Role  string `json:"role"`
	Kind  string `json:"kind"`
	Acts  int    `json:"acts"`
	Drawn int    `json:"drawn"`
}

Count is how many acts of a role's kind the window held, and how many were drawn.

type Defect added in v0.29.0

type Defect struct {
	Path  string `json:"path"`
	Quote string `json:"quote"` // the code that fails, as the auditor quoted it
	Lens  string `json:"lens"`
	Title string `json:"title"`
	Issue int    `json:"issue,omitempty"` // the issue it is opened as, or held by
	Said  string `json:"said,omitempty"`  // what became of it
}

Defect is a true finding the reviewer's judge dropped: opened as an issue while its cause is still on the branch (ADR-0046).

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
	// Forge is read, never written: the product owner's acts, the
	// merge requests merged and their heads, the reviewer's summaries
	// (ADR-0046). nil: those are not drawn, and the sample says so.
	Forge forge.Forge
}

Options say what to sample and who reads it.

type Panel added in v0.29.0

type Panel struct {
	For    string   `json:"for,omitempty"` // act or auditor: the majority's reading; "" when none
	Votes  []string `json:"votes"`         // each judge's: act, auditor, or "" when it did not answer
	Models []string `json:"models"`        // each judge's, as it answered
	Why    string   `json:"why,omitempty"` // why it did not settle
}

Panel is how a dispute was settled.

func (*Panel) Words added in v0.29.0

func (p *Panel) Words() string

Words say the panel's vote: "2–1 for the act (flagged)".

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"`
	Panel        *Panel  `json:"panel,omitempty"` // how a false verdict was settled
}

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"`
	// Drawn are the other roles' acts drawn, one in ten per role and
	// kind; Counts, each role's kinds of act in the window and how many
	// were drawn, the docs' too; NotDrawn, what could not be drawn, and
	// why (ADR-0046).
	Drawn    []Act    `json:"drawn,omitempty"`
	Counts   []Count  `json:"counts,omitempty"`
	NotDrawn []string `json:"not-drawn,omitempty"`
	// Older are the product owner's acts read without the record
	// ADR-0046 completes, an engine before it having kept none: on their
	// issue as it reads now. Autonomy, the level its acts suggest
	// (ADR-0033).
	Older    []string  `json:"older,omitempty"`
	Autonomy *Autonomy `json:"autonomy,omitempty"`
	// contains filtered or unexported fields
}

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: each doc of it read, the other roles' acts drawn for a person.

type Row added in v0.29.0

type Row struct {
	N            int    `json:"n"`
	Role         string `json:"role"`
	Kind         string `json:"kind"`
	Ref          string `json:"ref"`
	Where        string `json:"where,omitempty"`
	Verdict      string `json:"verdict"`
	Model        string `json:"model,omitempty"`
	Independence string `json:"independence,omitempty"`
	Panel        string `json:"panel,omitempty"`
	Issue        int    `json:"issue,omitempty"`
}

Row is one act of a week, as its comment keeps it.

Jump to

Keyboard shortcuts

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