An anchor’s review text is the complete source content selected by the
anchor-content boundaries, with surrounding
whitespace removed. For .sage prose, its enclosing common indentation is
removed first; remaining internal whitespace and Markdown markup are preserved.
The saved input covers the same content that the generated anchor views
present as the claim, including any paragraphs, lists, or examples within its
extent.
One review covers one anchor’s claim and its complete set of associated tests.
The input records every eligible test associated with that anchor in a
deterministic order. Several tests may cover different parts of a claim; each
test need not establish the whole claim independently.
An empty requested_edits list in a completed report means all aspects of the
anchor are accounted for and no edits are required. A nonempty list means work
remains and the validation cannot satisfy the gate. The reviewer must request
edits for missing implementation or test coverage unless explicit TODO/N/A
evidence adequately explains the gap.
Ordinary, todo, and not_applicable statuses are derived from the associated
implementation and test entries. The report
assesses all entries and their explanations. Accepting a justified deferral or
inapplicability does not relabel it as implemented behavior; TODO/N/A remains
visible in the evidence. An unfinished review has no completed output and
cannot satisfy the gate, even if a draft edit list is empty.
The complete association set and its metadata remain checked separately from
fragment contents. Adding, removing, or changing an association invalidates the
review even when all saved fragments still resolve to unchanged text.
Each fragment records its workspace-relative source path, selector, and exact
selected contents. Contents are stored as source lines; joining them with
newline characters recovers the selected text, including its whitespace and
line endings.
The data model is defined below in Rust notation, without prescribing a JSON
encoding:
Recording and checking resolve every fragment’s selector against current source
and compare the selected text with the saved text using exact string equality.
A missing or ambiguous selection, invalid selector, or changed selected text
makes the validation stale or invalid. No selector kind or input origin bypasses
these checks.
The shared cargo meta check fails when any current specification anchor lacks
an up-to-date validation satisfying meta.reviews.staleness, with an
output satisfying meta.reviews.output_format and no requested edits
under meta.reviews.decisions. It loads all validation directories, checks
the layout and summary metadata, and compares the saved inputs with current
source. At least one test and implementation entry are required.
A validation for an anchor ID absent from the current specification also fails
the gate, even when every current anchor has a passing validation. Diagnostics
name that directory and direct the reviewer to remove obsolete records or
reconcile renamed anchors and start fresh validation. Checking and recording
do not silently delete stale anchor IDs. Invalid record formats, unsupported
schema/policy versions, and incomplete records fail the gate. CI and
workspace Cargo tests use this same gate; checking never creates approvals.
Additional instructions supplied to the reviewer, in order.
fragments
Uniform collection of source fragments, including the claim, tests, implementation context, and additional reads.
implementations
Complete implementation association metadata.
tests
Complete associated test metadata.
The following anchors define each part. Source text belongs in the uniform
fragment collection; association metadata identifies the evidence and its
declared status. The collection contains both initial context and later reads.
Every piece of source context supplied to or consulted by a validation agent is
recorded in one uniform collection of input fragments, whether prepared
automatically, supplied by a coordinator, or declared by the reviewer. Helpers
and surrounding context used during review are additional fragments; recording
only the initial claim and tests does not excuse omitting other context used.
Automatic preparation and recorded reads use the same fragment representation
and freshness checks. Reviewers are responsible for declaring every source
dependency used in their assessment.
reviewer is a nonblank reviewer identity. report is a nonblank, complete,
claim-specific explanation accounting for every requirement, implementation
evidence, and test adequacy. It distinguishes source inspection from commands
actually executed. The report is the agent’s supplied explanation, not a
recording of internal reasoning. Each requested edit is a concrete, nonblank
change needed before revalidation.
Starting a review validates the requested anchor against the current inventory,
then clears any existing validation for that anchor and sets up
validations/<anchor>/. It writes summary.json and the initial input.json
before printing the exact captured inputs and verification prompt for the agent
to consume. The initial inputs include the complete claim, associated tests,
implementation context, and association metadata defined by
meta.reviews.input_format. Additional coordinator instructions supplied
to the reviewer are captured under meta.reviews.review_instructions.
Starting removes the previous output. After a successful start, the validation
directory must be in a state
that makes cargo meta check and the shared Cargo validation test fail for that
anchor, even if its previous validation passed and its source is unchanged.
An interrupted or abandoned review therefore cannot fall back to an
older approval. Unknown or invalid anchor IDs are rejected before clearing any
record. Other anchors’ directories are unchanged. A failed start cannot leave
an older output appearing to validate newly captured inputs.
For every anchor requiring re-evaluation, cargo meta check and the shared
Cargo validation test must fail until the assigned review subagent successfully
runs cargo meta review record for that review. Starting a review, capturing inputs,
reading additional context, or drafting a report cannot satisfy the gate.
An interrupted, abandoned, or failed review remains failing; an older report
cannot stand in for the unfinished review.
Recording is necessary but not sufficient: the recorded report must be complete,
request no edits, and still match current inputs. Recording a report that
requests edits, or changing inputs after recording, leaves the gate failing.
Every required anchor must meet these conditions independently.
The recorded-read command takes an anchor with an active review directory, a
workspace-relative source path, and a selector from
meta.reviews.fragment_format. A read without an explicit selector
selects the whole file. It appends the selected contents and selector directly
to that anchor’s input.json before returning those same contents to the
reviewer. Repeated reads are retained in order. Reads outside the workspace,
invalid selections, and reads without an active unfinished review are rejected.
These fragments participate in the same freshness checks as the initial inputs.
Reviewers declare every additional source dependency through this command and
are responsible for the completeness of those declarations.
Recording takes a completed report in the format defined by
meta.reviews.output_format and an anchor with an active unfinished review.
It checks the inputs already stored in that anchor’s directory against current
source using meta.reviews.fragment_freshness and
meta.reviews.fragment_associations, and verifies the anchor and version
metadata. Missing or stale inputs, an unknown anchor, an invalid report, or an
absent active review rejects recording. A changed input requires a new review
starting with cargo meta review start; recording never substitutes new source
text for the inputs the agent actually reviewed.
On success, recording writes output.json and updates the summary’s recording
time, preserving input.json exactly. Other anchors’ records are unchanged.
A completed report requesting edits is saved but cannot satisfy the gate under
meta.reviews.decisions. Incomplete publication cannot satisfy the gate;
readers must not accept a mixture of files from different review attempts.
The repository’s sage-review-checklist skill instructs the main agent to start
one review subagent for each anchor requiring re-evaluation. Each subagent is
given the anchor ID and an initial prompt directing it to run
cargo meta review start <anchor> and evaluate the printed inputs. The main
agent supplies any extra instructions or source context as recorded review
inputs.
The subagent uses cargo meta review read for additional source context and
cargo meta review record to save its completed report. Only one subagent owns an
anchor’s active directory at a time; reviews for different anchors may run in
parallel. The main agent reconciles requested edits, coordinates changes, and
repeats the start/read/record cycle for affected anchors after edits, then runs
cargo meta check again. TODO/N/A evidence is reviewed under the same workflow.
CLI and Cargo-test failures identify every anchor requiring re-evaluation and
explain why: missing or unfinished validation, changed inputs or associations,
unsupported versions, malformed records, or requested edits. Changed-input
diagnostics identify the affected fragment or association. Failures direct the
main agent to invoke .agents/skills/sage-review-checklist/SKILL.md; they do not
start reviews or alter saved records themselves.
Review inputs preserve the exact verification prompt and any additional
coordinator instructions supplied to the reviewer. These instructions are part
of the recorded context even when they do not originate in a source file.
One review judges both implementation completeness and test adequacy against
an anchor’s complete claim. Its saved input includes every implementation
association’s crate, target, module, file, cfg conditions, excerpt, region flag,
placeholder status, and explanation, in deterministic order. Source line
numbers and byte offsets are not association metadata. Source context used to
assess these associations is recorded under meta.reviews.input_fragments.
A point marker’s five-line preview is navigation context, not a sufficient
boundary for reviewing behavior that depends on other code.
Reviewers follow relevant helpers and dependencies and record the source
fragments they use. They add implementation associations for essential code in
other files before approval. Reviews are source judgments, not proofs; test
execution remains separate evidence.
Selector::Claim { anchor_id } selects the complete claim identified by its
full dotted anchor ID within the fragment’s source file, using the shared
anchor-content boundaries and claim-text normalization. The containing document
need not be included. The selector stores no line numbers or byte offsets;
inserting unrelated lines before an unchanged claim does not make the fragment
stale.
Selector::LineRange { start, end } selects a one-based, inclusive range of
lines within the fragment’s source file. Lines are delimited by \n; selected
text retains the original line endings, including the last selected line’s
ending if present. Zero, reversed, or out-of-bounds ranges are invalid.
The saved line numbers are used again when checking freshness, so shifting
content across those boundaries may conservatively make the fragment stale.
Selector::Test { crate_name, target, rust_path } selects the complete annotated
Rust test function within the fragment’s source file, including attributes,
signature, body, and comments. crate_name identifies the Cargo package;
target uses the correspondence target identity, including kind and name
(for example lib:sage_meta or test:review); rust_path identifies the fully
qualified function within that target. Identically named functions in different
targets are distinct. The containing file need not be included. The selector
stores no line numbers or byte offsets; inserting unrelated lines before an
unchanged test does not make the fragment stale.
Claim, implementation, and annotated test source snapshots are stored in input.json as
arrays of source lines. Joining an array with newline characters recovers the
snapshot’s text, including internal blank lines, whitespace, and markup.
A saved review applies only when its anchor, schema version, review-policy
version, complete claim, and implementation and test inputs match the current
inventory. Source context must satisfy meta.reviews.fragment_freshness
and associations must satisfy meta.reviews.fragment_associations.
Unchanged claims and tests remain reusable when unrelated edits move them, as
specified by their selectors. Changed text within a whole-file fragment,
including blank-line changes, invalidates that fragment. A reusable review must
also have a complete output under meta.reviews.output_format and no
requested edits under meta.reviews.decisions.
Each associated test’s review input contains the complete annotated Rust
function source, including its attributes, signature, body, and contained
comments. It also records the Cargo crate and target, Rust path, file path,
inherited configuration conditions, and ordinary, todo, or not_applicable
status. Source line numbers and byte offsets are excluded from the input.
summary.json identifies the review; input.json contains the context captured
for it; output.json contains the completed assessment. cargo meta review start
creates or resets the directory and writes the first two files. Until recording
completes, output.json is absent and the validation cannot satisfy the gate.
The directory name must be a valid anchor ID and match summary.json. Starting
a new review discards the previous validation; earlier validations are not
retained.