Documentation
¶
Overview ¶
Package review closes the loop around agent work: every completed agent task gets ONE review by a second agent, and a request_changes verdict can mint fix tasks. The reviewer only contributes findings — everything downstream (verdict bookkeeping, fix-task fan-out, dedup) is mechanical.
Loop safety is structural: reviews are never reviewed (the sweeper only reviews the "agent" type), each task is reviewed at most once (the review:<task-id> dedup key), and fix tasks minted from findings are bounded by the pool's budget guard, which counts every enqueue — reviews included — against the daily cap.
Index ¶
Constants ¶
const ( // ConsumerKey is the sweeper's identity in the watermarks table: the // persisted cursor shared by every sweeper over the same database, so // agent tasks completed while no sweeper was running still get their // review when the next pool starts. ConsumerKey = "review-sweeper" )
Variables ¶
This section is empty.
Functions ¶
func FixDedupKey ¶
FixDedupKey is the dedup identity of the fix task for one finding of one review: the same finding re-reported by the same review never spawns a second fix task.
func ReviewDedupKey ¶
ReviewDedupKey is the dedup identity of the review of one task: exactly one review per reviewed task, forever.
Types ¶
type SweepStats ¶
type SweepStats struct {
// Facts is the number of new facts consumed.
Facts int
// ReviewsEnqueued counts fresh review tasks this sweep created.
ReviewsEnqueued int
// ReviewsKnown counts completed agent tasks whose review task already
// existed (dedup hit — the review ran, or is pending, elsewhere).
ReviewsKnown int
// FixesEnqueued counts fresh fix tasks minted from findings.
FixesEnqueued int
// Skipped counts completions that could not yield a review and are
// checkpointed past (foreign payload shape, vanished task record, a
// completed fix-task dedup key). A refused MINT is not counted here:
// it aborts the sweep before the checkpoint so the completion
// redelivers.
Skipped int
// Merged counts approve-verdict worktree merges (branch → base + reap).
Merged int
// DocsSkipped counts completions whose derived diff is docs-only
// (2026-10-11 ceremony cut: a reviewer of prose cannot catch what the
// verify gate does not already prove; measured 52% derived-task
// overhead). No derivation available (empty file list) still reviews.
DocsSkipped int
}
SweepStats summarizes one sweep pass.
type Sweeper ¶
type Sweeper struct {
// contains filtered or unexported fields
}
Sweeper turns the journal's completion facts into review work. It is safe for concurrent use (the cursor serializes sweeps; ticks and the --once drain watcher may call it from different goroutines).
The struct shell deliberately stays per-sweeper (config fields and fact validation differ across the four sweepers); the shared pump is watermark.Cursor.Sweep.
Gate coverage ruling (2026-10-20, f13): scripts/check-mirror-clones.sh is scoped to CROSS-BACKEND clone groups (its patterns match only the sqlite/postgres backend dirs), so these intra-internal/ sweeper shells are intentionally OUTSIDE the gate — they are covered by art-dupl + the docs/dupe-type-accepted-ledger.md accepted groups, not by mirror-baseline.
art-dupl:accept mirrored sweeper shell: config fields and fact validation differ per sweeper; the shared pump already lives in watermark.Cursor.
func NewSweeper ¶
NewSweeper returns a sweeper over store. The cursor resumes from the persisted checkpoint — completions recorded while no sweeper was running are reviewed on the next start. A first run bootstraps at the journal head: completions that predate the sweeper are not replayed (same semantics as the papdashboard bridge; review the gap via `tq show`, or rewind with `tq watermarks set review-sweeper SEQ`).
func (*Sweeper) Sweep ¶
func (s *Sweeper) Sweep(ctx context.Context) (SweepStats, error)
Sweep consumes new facts since the last pass and enqueues review (and, with Autofix, fix) tasks. Idempotent by dedup: calling it twice never duplicates work, so a replayed page (crash between consumption and checkpoint) re-hits dedup keys instead of minting duplicates.
A mint refusal — a store failure while reading a completion or enqueueing the review/fix task — aborts the sweep BEFORE the checkpoint: the fact redelivers on the next pass instead of silently dropping the mint forever (dlqfix 13-15 §e pattern). Deterministic skips (foreign shapes, vanished records, done-guard dedup hits) stay checkpointed past: retrying them can never succeed and would wedge the cursor on one bad record.
type SweeperConfig ¶
type SweeperConfig struct {
// Model, when set, is written into every review payload (and fix task).
Model string
// Autofix, when true, mints an agent fix task per finding of every
// request_changes review. Off by default: verdict-only mode is the safe
// first step; autofix closes the loop autonomously.
Autofix bool
// Log receives one summary line per sweep. nil logs nothing.
Log *slog.Logger
// PageSize bounds one fact-stream page; 0 selects the default.
PageSize int
// ProjectsDir resolves relative repo names in review payloads for the
// default merge (absolute paths bypass it). "" disables merging of
// relative-repo payloads.
ProjectsDir string
// Merge overrides the branch-merge primitive (test seam). nil selects
// executor.MergeWorktreeBranch.
Merge func(repoDir, branch, base, message string) error
}
SweeperConfig controls one Sweeper.
Source Files