hraness

reviewing agent work: gates, evidence, and the final read

the review is the product quality

Drafted by an AI agent at Ben Guo's direct request from the Hraness source repositories, and checked against those sources before publication.

When agents write most of the code, the human’s job changes shape. You cannot read every diff at the rate agents produce them, and pretending to is how “reviewed” becomes a rubber stamp. The working alternative is to make the layers underneath the human prove everything provable, so the final read is spent on the residue: intent, scope, taste, and judgment. The review is the product quality, and the review’s job is to stay small enough to be real.

The monorepo behind this site structures this as a stack of four evidence layers, each with a distinct burden of proof: repository policy as data, mechanical gates, independent agent review, and the human read. None of them is optional, and none of them claims the others’ authority.

policy as data

The cheapest review is the one that cannot be skipped because it is structure. In this repository the boundary rules are files a checker reads: konsistent.json requires an AGENTS.md in every owned directory and confines README.md files to package and deployable roots, and bun run check:structure fails the tree when either rule drifts. The effect on review is direct. When an agent claims “this directory owns X,” the claim is checked against the declared boundary, not taken on trust.

The same move appears in the workspace graph (check:workspaces rejects missing catalog entries and wrong protocols), the data-surface registry (check:cost-surfaces refuses a new table, stream, or route until it declares kind, retention, owner, and budget), and the agent-guide inventory (check:agent-guides). Each converts a review question (“did you register this?”) into a boolean the reviewer never has to ask.

gates as the first reviewer

The merge queue described in merge queues when the author is an agent is, functionally, the first reviewer of every commit. It does not read code. It replays the recorded commits onto a fresh origin/main in a queue-owned detached worktree, runs the affected or complete gate against that exact tree, and refuses to publish unless the worktree HEAD, index tree, and a clean porcelain-v2 status (submodules included) all match the candidate. The proof lands as a versioned, append-only receipt.

This is the layer that absorbs volume. An agent’s commit that fails lint in a sibling workspace it did not know about is a queue rejection with evidence, not a human comment. The reviewer inherits a commit that is already green against the tree it will actually become.

independent agent review

Between the gates and the human sits the layer people get wrong: another agent. It works only because it is structured as an independent reviewer rather than a second opinion from the author. The phase-delivery skills make the separation explicit. phase-reviewer inspects the plan and the actual diff before reading the implementer’s notes, treats those notes as claims to check, patches only bounded low-risk findings, and reports an honest no-op when there is nothing to fix. It does not commit unless commit authority is explicitly delegated. Its final response is a fixed six-heading contract: Outcome, Changed files, Behavior or findings, Validation, Downstream impact, Blockers and risks.

The fixed form matters more than the findings. A reviewer that must report its validation commands and its unfixed findings in named fields cannot hide a skipped check inside a confident paragraph.

the final read

What remains for the human is deliberately small: does this change belong in the product, does the plan still make sense, and is the evidence actually evidence. The stack exists so that question is asked about a commit that already proved its mechanics.

The disclosure rules underneath are part of the review too, and they are worth stating plainly because they are easy to violate accidentally. This site’s editorial policy distinguishes author review, independent human review, and automated or AI review, and forbids describing automated review as human review. “Reviewed” is a claim about who looked, not a vibe. Any reference page you are reading here carries an admission record with a named reviewer identity and type, a score, and a reassessment date; an AI-drafted page is credited to Hraness, never quietly to a person. A commit or publication receipt is also not authorship evidence: the record shows the artifact landed, not that a person wrote or approved it.

The free portion ends on the claim the rest of the piece substantiates: one reviewer can only check what the gates do not already prove, and a review process for agent work is mostly the work of keeping that true.

the evidence table

The way to operate the stack is to know exactly what each layer proves and what it cannot:

Layer Proves Cannot prove
Policy checks (check:structure, check:workspaces, check:cost-surfaces, check:agent-guides) Declared boundaries, registries, and inventories match the tree That the boundary is the right one
Affected gate (check:affected) The selected checks pass for the deepest owning workspace plus reverse dependents, with uncertain selections falling back to the complete gate Behavior outside the selected surfaces; intent
Merge queue receipt The exact candidate commit and tree passed the gate on a fresh origin/main, with a clean worktree proof That the change should exist
Independent agent review Findings against the plan, conventions, and touched code, with validation commands named Design-level correctness beyond its bounded scope
Human final read Intent, scope, taste, and the decision to ship Mechanics the layers already cover

Two consequences follow. Evidence is reusable only for the exact inputs it was produced from: a gate run is valid for that Git tree, those lockfiles, and that toolchain, and the queue enforces this by invalidating its own proof when origin/main moves. And a green row is a claim about a boundary, not a vibe about the change. The table is the working document; when a new kind of defect slips through, the fix is to move that defect class left into a checkable layer, not to read harder.

Reading the table vertically is also the spot-check procedure. Pick the layer whose “proves” column covers the failure you suspect and demand its artifact: the gate’s command output, the queue’s sealed commit, tree, and worktree triple, or the reviewer skill’s Validation field with the commands it actually ran. If a layer cannot produce its artifact, the green is a claim rather than evidence, and the finding is about the process, not the diff. The queue’s operator surface is built for exactly this audit posture: bun run merge:queue -- status and status <item-id> --json read the durable state, doctor diagnoses a wedged item, and recover, retry, replace, promote, and cancel are the only interventions, each one itself a recorded mutation rather than a side channel. The recovery rule is the honest part: automatic recovery may push a ready candidate only when its current-attempt receipt exactly matches the durable base, commit, ref, tree, and current remote state, and an ambiguous push or invalid receipt stays blocked with its evidence intact rather than being retried into a guessed outcome.

where judgment still lives

The residue the human owns is real and specific:

  • Plan coherence. The gates prove the diff; the human decides whether the plan the diff implements is still the plan worth having. The phase protocol separates implementer, reviewer, and a final-reviewer pass for this reason.
  • Scope drift. Agents expand tasks. The durable queue item records only the submitted commits, and the review question is whether those commits are the whole task or a convenient subset.
  • Evidence literacy. A PROVIDER ALL-CLEAR claim means a named thing (exact-SHA production deployment plus fresh alias binding), and the reviewer’s job is to refuse outcome language that outruns its evidence. The closed outcome vocabulary exists so “it’s live” cannot mean five different things.
  • Reviewer independence. The reviewer skill is told to treat the implementer’s notes as claims, not conclusions. The audit question is whether it actually looked, which is why its report form requires named validation commands and a Blockers and risks field that cannot be omitted.
  • The uncheckable diff. Naming, information architecture, whether a new surface should exist at all. No gate covers these, and the honest process says so instead of implying coverage.

The operating rules that fall out of this are short. Review the plan before the diff, because a correct implementation of a wrong plan is still wrong. Read the receipts before the code, because a candidate without a clean-tree proof is not yet a candidate. Treat every agent finding as a claim with a command attached, and spot-check the claims, not the vibe. And when a defect recurs, move its detection left into konsistent.json, a registry check, or a gate selection rule, so the next instance is caught by a machine and the next review stays small.

The same discipline applies to published artifacts, not only commits. This reference section keeps a per-URL admission record for the index, every category page, and every lesson: the reader job the page serves, the non-obvious answer it gives, its original contribution and host fit, adoption and authorship evidence, a named reviewer identity and reviewer type, a score, and a reassessment date. A page without an admission record is not indexed; a record’s lifecycle is indexable or quarantined, and an AI reviewer is named as such. The lesson entries in this section carry a Devin AI review type against the source repositories, so the disclosure rule is enforced as data rather than as a promise. An admission record is the evidence table for a piece of writing: provenance, reviewer, and a reassessment date that forces the admission question to be asked again instead of assumed settled.

That is the whole mechanism: evidence accumulates in layers, each layer is honest about its boundary, and the human’s read at the end is short enough to be a real read.

sources

  • The monorepo behind this site (projects): konsistent.json, scripts/merge-queue.ts, scripts/check-affected.ts, and the skills/phase-reviewer contract.
  • skillpack: the published code-orchestrator pack whose reviewer and final-reviewer skills carry the same contract.
  • oompa: the receipts, idempotency, and custody records that make agent-executed mutations auditable upstream of review.

keep reading: free for subscribers

the rest of this lesson is free. add your email once and every subscriber lesson on this site stays unlocked.

already subscribed? enter the same email to unlock.