# What did the agent's branch actually reach?
nool try impact api-rate-limit
nool try diff api-rate-limit
# Structural invariants and the AST-aware gate stack, before merge
nool verify --all
nool propose --path src/middleware/rateLimit.ts --intent "Add rate limiting to the public API"
# The judgment call: a cross-vendor quorum, tightening with blast radius
nool fleet start --builder <builder-spec> --reviewer <reviewer-a> --reviewer <reviewer-b> \
--intent "Add rate limiting to the public API" --blast 14
# The verdict lives on the knot, as a signed ref
nool attest record --target <knot-id> --checker human --assertion human-approval --verdict pass
nool attest show <knot-id>Impact and invariants are computed from the architecture model. The quorum fraction rises with the blast radius you pass or the one Nool computes.
Line-by-line review does not scale to agents
A diff is the wrong unit for reviewing agent-generated code. Agents produce large, correct-looking changes that cross module boundaries, and the defects that matter are rarely visible in the lines that changed. A renamed field is fine until you know three callers depend on the old name; a simplified guard is fine until you know it was the only thing enforcing an invariant. Reviewers reading diffs at agent volume either skim or stall. Semantic review changes the unit: what did this change reach, which boundaries did it cross, which invariants does it touch, and is that consistent with what it said it would do?
What Nool reviews, and when
Nool reviews a change at proposal time, before it reaches Git. Blast radius closes over the entities touched and their dependents across the architecture model; nool try impact reports it for a try branch and nool try diff shows the unified diff beside it. The envelope check compares that impact with the declared intent, and --full validation checks the result against the AST and the repository's structural invariants; nool verify runs those invariants on demand. Findings attached to the affected scope surface in the reviewer's context, so a reviewer, human or agent, sees the corrections that were made last time. The output is not a list of comments; it is a verdict with evidence attached to the knot.
Deterministic gates first, judgment second
The cheapest review is one nobody has to perform. Rules that can be stated precisely, such as which paths may call the payment provider or which packages may import identity, become policies that gate every proposal deterministically, with the same verdict for the same change every time. In the coordination benchmark an authored policy blocked all ten violations in 36 of 40 seed-runs with zero false alarms, and let five through across the other four. What remains after the gates is the part that needs judgment: whether the design is right, whether the intent was the right intent. That is where a human approval or a cross-vendor reviewer quorum spends its attention, on a change whose mechanical properties are already established.
Review as evidence on the change
Every review outcome in Nool is attached to the knot it judged. Gate results are recorded at proposal time. nool attest record mints a signed verdict from a checker, whether that is a CI job, a scanner or a person, and nool attest obligations shows which assertions a knot's paths require and which are satisfied. nool approve records a human decision with a comment. When a reviewer corrects a change, the correction can be recorded as a finding that future proposals are checked against. The pull request still exists if you want it; the difference is that by the time it opens, the change already carries its impact analysis, its gate results and its verdicts.
Impact-scoped tests as part of the review
A semantic review should also decide which tests to run, because running everything on every agent change is what makes CI the bottleneck. nool test select resolves the knot's touched paths and applies the same dependents-closure selection the proposal used, so CI runs the tests the change can actually affect and nothing else. Selection is deterministic for a given knot and semantic index. When a checkout lacks the index, because it restored plain Git history without running discover, selection says so and falls back to the full suite with an explicit reason rather than quietly under-testing. The result is attested back onto the knot with nool attest record, where the reviewer sees it next to the blast radius.
Frequently asked questions
- Is this an AI review bot?
- No. Nool's gates are deterministic and run on the architecture model, not on a language model's reading of the diff. Language models can participate as reviewers in a quorum; their verdicts are recorded as evidence, and their accepted corrections become findings the next change is checked against.
- What does semantic mean here?
- That review operates on entities, dependencies, boundaries and invariants rather than on text. Two changes can merge cleanly as text and still be semantically incompatible; that is the case Nool is built to catch.
- Can I keep my pull request workflow?
- Yes. Solidified knots mirror to Git and can open pull requests as before, and nool merge can ingest an incoming branch through the gate stack. The review evidence arrives with the change instead of being produced after it.
- How does this help a human reviewer?
- They open a change that already carries its blast radius, its gate results, its attestations and the findings relevant to its scope, so their attention goes to design and intent rather than to spotting a missed caller.
- Does semantic review include running tests?
- It includes choosing them. nool test select prints the tests affected by a knot's changes for a CI step, in text, JSON, cargo or go format, and the run's verdict is recorded as a signed attestation on the knot so the review and the test evidence live together.