Expand description
The shapes that cross the boundary between spar and a model, and the shapes spar keeps for itself.
Everything a model produces is parsed leniently: an LLM that answers “medium” where the schema said “med” is not a reason to abandon a run that has already spent real money. Anything genuinely unrecognisable is still an error, because silently downgrading a blocking finding is worse than stopping.
Structs§
- Adjudication
- One reviewer’s judgement of a finding the other reviewer raised.
- Adjudication
Doc - Answered
- What spar has already answered on one pull request or issue.
- Author
- Check
Doc - Checkin
Doc - Comment
Check - The second agent’s ruling on the first one’s call.
- Comment
Verdict - One agent’s judgement of one comment somebody left on a pull request.
- Contested
- An issue triage disagreed about, remembered between runs.
- Contested
Item - Converge
Doc - The last round’s answer: defences for the agent’s own challenged ideas, and its ranking of everything still standing.
- Cross
Doc - Cross
Verdict - One agent’s ruling on an idea the other agent proposed.
- Defence
- What the agent that proposed a challenged idea says to the objection.
- Disposition
- Dispute
- Finding
- FixOutcome
- What the fix pass did about one comment.
- FixReport
- Idea
- One idea from a brainstorm: existing pieces, paired in a way that has not been done.
- Ideas
Doc - Implementation
- What the implementor did, and what the pull request body is built from.
- Issue
- Issue
Comment - One top level comment on an issue, as
gh issue view --json commentsreturns it, oldest first. - Issue
Ref - Issue
Run - The outcome of working one issue, or resuming one PR.
- Judged
- A finding after both reviewers have had their say.
- Label
- Ledger
Entry - Live
Head - Where a pull request’s head stands right now, asked two ways.
- Login
- A user in a
reviewRequestsorassigneesarray. A team entry hasnameandsluginstead, which reads as an empty login and never matches the viewer. - OwnFix
- What a reviewer did about one of its own findings when it chose to fix them.
- OwnFix
Doc - Persisted
State - Everything needed to pick a review back up, including on another machine.
- Plan
- Plan
Item - PrRef
- PrRow
- An open pull request’s size, as one listing call reports it.
- PrSweep
Row - One row of
gh pr list --json PR_SWEEP_FIELDS, or ofgh pr viewwith the same fields. - PrView
- Recheck
Doc - What one reviewer answers on a second look: a ruling per earlier finding, and ordinary findings for anything new.
- Recheck
Ruling - One reviewer’s ruling on one earlier finding.
- Recorded
Finding - One finding as the review record keeps it: enough to list it again, rule on
it, and post it, and nothing a model is not asked for. The parts of a bug
report a
Findingmay carry are for an issue filed from it, which a record never does. - Response
Doc - Review
- Review
Record - What
spar reviewleaves behind, and what a second look reads and rewrites. - Screen
Response - Screen
Verdict - One agent’s ruling on one entry in the local follow-up queue.
- Skipped
Item - Split
Check - The second agent’s ruling on the first one’s decomposition.
- Split
Part - One piece of a proposed decomposition.
- Split
Proposal - One agent’s decomposition of an issue or a pull request.
- Split
Screen - One agent’s ruling on whether one open item is worth splitting at all.
- Split
Screen Doc - Triage
Response - Triage
Verdict
Enums§
- Action
- A reviewer’s point gets exactly one of these. Refutation is a first class outcome, not friction: an agent that accepts every comment to get approved produces worse code, not better.
- Ask
- What spar should do about one comment somebody left.
- Complexity
- How much work an issue is. Drives ordering: cheap unblocking work first.
- Cross
Kind - What one agent does with an idea the other proposed.
- Followup
- What one attempt to record a follow-up actually did.
- Item
Kind - Issues and pull requests share one number sequence per repository, so a number names exactly one of them and spar can work out which.
- Next
Action - Review
Verdict - What a formal pull request review says.
Verdictis what a model answers; this is what spar submits, and spar never asks a model for it. It is derived from the findings: approve when nothing blocks, request changes when something both reviewers count does. - Risk
- How likely a change here is to break something.
- Ruling
- What a second look found about one earlier finding.
- Screened
- What one screening pass decided about one recorded follow-up.
- Settled
- How a point stands, one round to the next.
- Severity
- Only
Blockinggates a merge. This is the whole defence against the nitpick spiral: a competent reviewer can always find something, so “no objections remaining” is not a stopping condition but “no blocking objections” is. - Standing
- How a finding stands after both reviewers have had their say. A word rather than a bare enum because the review record keeps it on disk.
- Status
- Terminal state of one issue or one resumed PR.
- Verdict
Constants§
- PR_
SWEEP_ FIELDS - The fields a sweep reads from
gh pr listandgh pr view: enough to notice a head that moved, a review request, an assignment, and a close. - REVIEW_
RECORD_ VERSION - STATE_
VERSION
Functions§
- de_bool
- A boolean that may arrive as
true,"true","yes", or1. - de_i64
- An integer that may arrive as a number, a float, or a quoted string, with or
without a leading
#. - de_
opt_ i64 - An optional number that may arrive as 412, “412”, “#412”, null, or “none”.
- login_
of - A login, never empty. A deleted account is null on GitHub and becomes
ghost, which no trust setting butanyonewill act on.
Type Aliases§
- Ledger
- Settled points, keyed by the review loop’s finding identity. Ordered so the settled block in a prompt is stable between rounds, which keeps prompt caches warm and diffs readable.