Reviewing Specification Implementations and Tests

A validation records an agent's assessment of one specification anchor against its implementation and tests. The saved context lets cargo meta check whether that assessment still applies. Running tests remains a separate obligation.

Intended workflow

The main agent discovers review work through a failing cargo meta check or the shared Cargo validation test. Diagnostics identify the affected anchors, explain why they need review, and direct the agent to the review skill. The skill delegates one subagent per anchor, supplying its ID and an initial prompt. The subagent obtains its source context through the review commands, so that the saved inputs are the same inputs it consumes.

sequenceDiagram
    participant Main as Main agent
    participant Check as Check / Cargo validation test
    participant Reviewer as Review subagent (one per anchor)
    participant CLI as cargo meta review
    participant Files as validations/anchor-id/

    Main->>Check: Check current validations
    Check-->>Main: Fail: affected anchors, reasons, review skill
    Main->>Reviewer: Follow skill, review anchor using initial prompt
    Reviewer->>CLI: start anchor
    CLI->>Files: Clear old validation, save summary and initial inputs
    Note over Check,Files: No output exists: the gate must fail
    CLI-->>Reviewer: Print the saved inputs and verification prompt
    loop Additional context needed
        Reviewer->>CLI: read anchor path selector
        CLI->>Files: Append the selected source fragment
        CLI-->>Reviewer: Return the exact saved contents
    end
    Reviewer->>CLI: record anchor report-file
    CLI->>Files: Load captured inputs
    CLI->>CLI: Verify freshness and report format
    alt Inputs changed or report invalid
        CLI-->>Reviewer: Reject recording, gate still fails
    else Valid submission
        CLI->>Files: Save output and recording time, preserve inputs
        CLI-->>Reviewer: Report recorded
    end
    Reviewer-->>Main: Report results and any requested edits
    Main->>Check: Check all validations again
    alt Every anchor has a current report with no requested edits
        Check-->>Main: Pass
    else Missing, unfinished, stale, or changes requested
        Check-->>Main: Fail with reasons
        Note over Main,Reviewer: Resolve edits and repeat review for affected anchors
    end

The subagent captures inputs and records its report in the validation directory created by start. Starting a review removes its previous output even when the source has not changed, so an interrupted review cannot reuse an old approval. Each additional read is saved before its contents are returned. Recording checks the captured inputs for freshness and preserves them exactly.

A successful record is necessary but does not by itself make the gate pass. The report must request no edits, its inputs must still be current, and every other anchor must also satisfy the gate. If edits are requested, the main agent coordinates them and starts fresh reviews for affected anchors. An accepted review of justified TODO/N/A evidence leaves that status visible; it does not claim the deferred behavior is implemented.

The contracts below define the files, selectors, and commands in detail. In particular, meta.reviews.record_required states the failing-until-recorded invariant, and meta.reviews.review_delegation defines subagent ownership.

Validation directory

specmeta.reviews.validation_layout Each anchor has one directory named by its complete dotted ID, for example:

validations/meta.reviews.gate/
    summary.json
    input.json
    output.json

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.

summary.json: identity and record metadata

specmeta.reviews.summary_format The summary contains these fields:

Freshness is determined by comparing the recorded inputs with current source, as defined by meta.reviews.fragment_freshness.

input.json: the context being reviewed

specmeta.reviews.input_format The input contains these fields:

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.

Instructions and complete context

specmeta.reviews.review_instructions 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.

specmeta.reviews.input_fragments 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.

Fragment representation

specmeta.reviews.fragment_format 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:

struct InputFragment {
    path: String,           // Workspace-relative UTF-8 source file path.
    selector: Selector,
    contents: Vec<String>, // Join with '\n' to recover the selected text.
}

enum Selector {
    WholeFile,
    LineRange { start: usize, end: usize },
    Claim { anchor_id: String },
    Test {
        crate_name: String,
        target: String,
        rust_path: String,
    },
}

specmeta.reviews.source_representation 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.

Selectors

specmeta.reviews.selector_whole_file Selector::WholeFile selects all contents of the fragment's source file, including any trailing newline. It carries no additional selector data.

specmeta.reviews.selector_line_range 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.

specmeta.reviews.selector_claim 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.

specmeta.reviews.selector_test 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 and evidence metadata

specmeta.reviews.claim_text 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.

specmeta.reviews.test_source 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.

specmeta.reviews.complete_test_set 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.

specmeta.reviews.review_scope 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.

output.json: the reviewer’s assessment

specmeta.reviews.output_format The output contains only the reviewer, report, and requested edits:

struct ValidationOutput {
    reviewer: String,
    report: String,
    requested_edits: Vec<String>,
}

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.

specmeta.reviews.decisions 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.

Freshness and acceptance

specmeta.reviews.fragment_freshness 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.

specmeta.reviews.fragment_associations 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.

specmeta.reviews.staleness 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.

Commands

cargo meta review start <anchor>

specmeta.reviews.preparation 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.

cargo meta review read <anchor> <path> [selector]

specmeta.reviews.recorded_reads 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.

cargo meta review record <anchor> <report-file>

specmeta.reviews.recording 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.

cargo meta check and Cargo tests

specmeta.reviews.gate 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.

specmeta.reviews.record_required 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.

specmeta.reviews.review_diagnostics 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.

Reviewing implementation and tests

specmeta.reviews.review_delegation 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.

Reviewers trace every requirement to implementation code, checking missing cases and contradictory behavior. They consider the complete associated test set and explain which assertions exercise which parts of the claim. They identify a plausible violation and whether those assertions would detect it.

The scenario, expected outcome, and assertion should be clear from the body of the test function itself. Parsing, fixture construction, and setup helpers are reasonable. A call such as verify_everything() that hides the meaningful assertions is insufficient evidence: request a clearer test body instead of approving it from its name or annotation. Reviewers may read helpers to understand the test, and capture additional helper fragments through the recorded-read command.

A helper edit outside the supplied files and captured reads does not invalidate a saved review. Running the tests can detect behavioral changes, but the cached review covers only the snapshotted source. Add implementation associations to include additional essential source files.

When reviewers suspect a bug, they add an anchor-associated regression test that exercises the intended behavior and run it against the implementation. A reproduced behavioral failure yields concrete requested edits, with the test, command, and observed failure in the report. Do not treat a build or environment failure as reproduction. If a test cannot reproduce the concern, or a reviewer cannot work out how to write one, consult the user with the concern and attempts; leave the affected review unresolved until the concern is resolved. New tests or associations require starting a fresh review before recording a report.

Implementation and test evidence

The generated anchor pages report implementation entries, annotated tests, explicit TODO/N/A gaps, and saved implementation/test reviews. These associations do not themselves establish that a test ran.