meta.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.

Read in specification context · design/meta/reviews.md

Implementation

Implemented crates/sage-meta/src/review.rs:517–522

sage_meta::review · lib:sage_meta

#![allow(unused)]
fn main() {
// {anchor}`meta.reviews.preparation`
// {anchor}`meta.reviews.review_instructions`
pub fn start(
    workspace: &Path,
    anchor: &str,
    instructions: Vec<String>,

}

See more source ↗

Implemented crates/sage-meta/src/main.rs:100–105

sage_meta · bin:sage-meta

#![allow(unused)]
fn main() {
// {anchor}`meta.reviews.preparation`
// {anchor}`meta.reviews.recorded_reads`
// {anchor}`meta.reviews.recording`
// {anchor}`meta.reviews.review_instructions`
fn review(args: &[std::ffi::OsString]) -> Result<(), Box<dyn std::error::Error>> {
    use sage_meta::review::{self, Selector, ValidationOutput};

}

See more source ↗

Tests and review

Indexed tests and the implementation-completeness and test-adequacy review; no test run is implied.

Implemented sage_meta::cli_start_and_record_roundtrip_exact_saved_input

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.recording)]
#[sage::test(meta.reviews.review_instructions)]
fn cli_start_and_record_roundtrip_exact_saved_input() {
    let fixture = Fixture::new();
    fixture.write(
        "instructions.txt",
        "Inspect the edge cases.\nPreserve these instructions.",
    );
    let output = fixture.run(&[
        "review",
        "start",
        "demo.rule",
        "--instructions",
        "instructions.txt",
    ]);
    assert!(
        output.status.success(),
        "{}",
        String::from_utf8_lossy(&output.stderr)
    );
    let input: ReviewInput = serde_json::from_slice(&output.stdout).unwrap();
    assert_eq!(input, fixture.input());
    assert_eq!(
        input.coordinator_instructions,
        ["Inspect the edge cases.\nPreserve these instructions."]
    );
    fixture.write(
        "report.json",
        &serde_json::to_string(&Fixture::report()).unwrap(),
    );
    let output = fixture.run(&["review", "record", "demo.rule", "report.json"]);
    assert!(
        output.status.success(),
        "{}",
        String::from_utf8_lossy(&output.stderr)
    );
    assert!(fixture.run(&["check"]).status.success());
    assert!(
        !fixture
            .run(&["review", "record", "demo.rule"])
            .status
            .success()
    );
}
}

See more source ↗

Implemented sage_meta::initial_context_preserves_instructions_and_exact_uniform_fragments

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.input_format)]
#[sage::test(meta.reviews.input_fragments)]
#[sage::test(meta.reviews.fragment_format)]
#[sage::test(meta.reviews.review_instructions)]
#[sage::test(meta.reviews.review_scope)]
#[sage::test(meta.reviews.source_representation)]
#[sage::test(meta.reviews.preparation)]
fn initial_context_preserves_instructions_and_exact_uniform_fragments() {
    let fixture = Fixture::new();
    let instructions = vec![
        "Check all scenarios.\nKeep this newline.".into(),
        "Account for TODO rationale.".into(),
    ];
    let input = review::start(&fixture.0, "demo.rule", instructions.clone()).unwrap();
    assert_eq!(input.coordinator_instructions, instructions);
    assert_eq!(input.prompt, review::PROMPT);
    assert_eq!(input, fixture.input());
    let claim = input
        .fragments
        .iter()
        .find(|f| matches!(&f.selector, Selector::Claim { anchor_id } if anchor_id == "demo.rule"))
        .unwrap();
    assert_eq!(claim.path, "md/design/README.md");
    assert_eq!(claim.contents.join("\n"), "The result is four.");
    let implementation = input
        .fragments
        .iter()
        .find(|f| f.path == "src/behavior.rs" && matches!(f.selector, Selector::WholeFile))
        .unwrap();
    assert_eq!(
        implementation.contents.join("\n"),
        std::fs::read_to_string(fixture.0.join("src/behavior.rs")).unwrap()
    );
    let test = input
        .fragments
        .iter()
        .find(|f| matches!(f.selector, Selector::Test { .. }))
        .unwrap();
    assert_eq!(test.path, "src/tests.rs");
    assert_eq!(test.contents.join("\n"), TEST);
    assert!(
        !input
            .fragments
            .iter()
            .any(|f| f.path == "src/tests.rs" && matches!(f.selector, Selector::WholeFile))
    );
    assert_eq!(input.implementations.len(), 1);
    assert_eq!(input.implementations[0].file, "src/behavior.rs");
    assert_eq!(input.implementations[0].status, TestStatus::Ordinary);
    assert_eq!(input.tests.len(), 1);
}
}

See more source ↗

Implemented sage_meta::input_keeps_complete_association_metadata_and_appends_context_in_one_collection

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.input_format)]
#[sage::test(meta.reviews.review_scope)]
#[sage::test(meta.reviews.input_fragments)]
#[sage::test(meta.reviews.preparation)]
fn input_keeps_complete_association_metadata_and_appends_context_in_one_collection() {
    let fixture = Fixture::new();
    fixture.write(
        "src/lib.rs",
        "#[sage::item(crate)] mod model {}\n#[cfg(unix)] mod behavior;\n#[cfg(test)] mod tests;\n",
    );
    let initial = fixture.start();
    let implementation = &initial.implementations[0];
    assert_eq!(implementation.crate_name, "demo");
    assert_eq!(implementation.target, "lib:demo");
    assert_eq!(implementation.module, "demo::behavior");
    assert_eq!(implementation.file, "src/behavior.rs");
    assert!(implementation.cfg.iter().any(|cfg| cfg.contains("unix")));
    assert!(
        implementation
            .excerpt
            .join("\n")
            .contains("pub fn result() -> u32 { 4 }")
    );
    assert!(!implementation.region);
    assert_eq!(implementation.status, TestStatus::Ordinary);
    assert_eq!(implementation.explanation, None);
    let test = &initial.tests[0];
    assert_eq!(test.crate_name, "demo");
    assert_eq!(test.target, "lib:demo");
    assert_eq!(test.rust_path, "demo::tests::verifies_result");
    assert_eq!(test.file, "src/tests.rs");
    assert!(test.cfg.iter().any(|cfg| cfg.contains("test")));
    assert_eq!(test.status, TestStatus::Ordinary);
    fixture.write("helper.txt", "extra context\n");
    assert_eq!(
        review::capture_read(&fixture.0, "demo.rule", "helper.txt", Selector::WholeFile).unwrap(),
        "extra context\n"
    );
    let captured = fixture.input();
    assert_eq!(captured.implementations, initial.implementations);
    assert_eq!(captured.tests, initial.tests);
    assert_eq!(
        &captured.fragments[..initial.fragments.len()],
        initial.fragments
    );
    assert_eq!(captured.fragments.len(), initial.fragments.len() + 1);
    assert_eq!(
        captured.fragments.last().unwrap().contents.join("\n"),
        "extra context\n"
    );
    let json = serde_json::to_value(&captured).unwrap();
    let mut keys: Vec<_> = json
        .as_object()
        .unwrap()
        .keys()
        .map(String::as_str)
        .collect();
    keys.sort();
    assert_eq!(
        keys,
        [
            "coordinator_instructions",
            "fragments",
            "implementations",
            "prompt",
            "tests"
        ]
    );
}
}

See more source ↗

Implemented sage_meta::interrupted_start_publication_states_cannot_reuse_an_old_approval

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.record_required)]
fn interrupted_start_publication_states_cannot_reuse_an_old_approval() {
    let fixture = Fixture::new();
    fixture.approve();
    let directory = fixture.0.join("validations/demo.rule");
    let input = fixture.input();
    // Start removes the old directory before creating any part of the new record.
    std::fs::remove_dir_all(&directory).unwrap();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    assert!(!fixture.run(&["check"]).status.success());
    std::fs::create_dir(&directory).unwrap();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    assert!(!fixture.run(&["check"]).status.success());
    std::fs::write(
        directory.join("input.json"),
        serde_json::to_vec(&input).unwrap(),
    )
    .unwrap();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    assert!(!fixture.run(&["check"]).status.success());
    assert!(!directory.join("output.json").exists());
    // A successful restart also stays failing until a fresh report is recorded.
    fixture.start();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    assert!(!fixture.run(&["check"]).status.success());
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    assert!(sage_meta::check(&fixture.0).is_valid());
}
}

See more source ↗

Implemented sage_meta::invalid_ids_and_paths_are_rejected_without_destroying_existing_reports

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.recorded_reads)]
#[sage::test(meta.reviews.gate)]
#[sage::test(meta.reviews.validation_layout)]
fn invalid_ids_and_paths_are_rejected_without_destroying_existing_reports() {
    let fixture = Fixture::new();
    fixture.approve();
    let output = std::fs::read(fixture.0.join("validations/demo.rule/output.json")).unwrap();
    for anchor in [
        "../escape",
        "/absolute",
        "demo/rule",
        "demo..rule",
        "demo.missing",
    ] {
        assert!(review::start(&fixture.0, anchor, vec![]).is_err());
        assert_eq!(
            output,
            std::fs::read(fixture.0.join("validations/demo.rule/output.json")).unwrap()
        );
    }
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.missing",
            "src/tests.rs",
            Selector::WholeFile
        )
        .is_err()
    );
    fixture.start();
    let before = fixture.input();
    for path in ["../outside", "/etc/passwd", "missing.txt"] {
        assert!(review::capture_read(&fixture.0, "demo.rule", path, Selector::WholeFile).is_err());
        assert_eq!(fixture.input(), before);
    }
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "src/tests.rs",
            Selector::Claim {
                anchor_id: "demo.rule".into()
            }
        )
        .is_err()
    );
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "src/tests.rs",
            Selector::Test {
                crate_name: "demo".into(),
                target: "test:missing".into(),
                rust_path: "demo::tests::verifies_result".into()
            }
        )
        .is_err()
    );
    assert_eq!(fixture.input(), before);
}
}

See more source ↗

Implemented sage_meta::restarting_one_anchor_leaves_other_anchor_record_unchanged

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.recording)]
#[sage::test(meta.reviews.record_required)]
fn restarting_one_anchor_leaves_other_anchor_record_unchanged() {
    let fixture = Fixture::new();
    fixture.write(
        "md/design/README.md",
        &format!("{CLAIM}\n{{anchor}}`demo.other`\nAnother claim.\n"),
    );
    fixture.write("src/behavior.rs", "// {anchor}`demo.rule`\npub fn result() -> u32 { 4 }\n// {anchor}`demo.other`\npub fn other() -> u32 { 4 }\n");
    fixture.write(
        "src/tests.rs",
        &format!("{TEST}\n#[test] #[sage::test(demo.other)] fn other() {{ assert_eq!(4, 4); }}"),
    );
    fixture.approve();
    review::start(&fixture.0, "demo.other", vec![]).unwrap();
    review::record(&fixture.0, "demo.other", &Fixture::report()).unwrap();
    assert!(sage_meta::check(&fixture.0).is_valid());
    let before: Vec<_> = ["summary.json", "input.json", "output.json"]
        .map(|file| std::fs::read(fixture.0.join("validations/demo.other").join(file)).unwrap())
        .into();
    fixture.start();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    for (file, bytes) in ["summary.json", "input.json", "output.json"]
        .into_iter()
        .zip(before)
    {
        assert_eq!(
            bytes,
            std::fs::read(fixture.0.join("validations/demo.other").join(file)).unwrap()
        );
    }
    assert!(sage_meta::check(&fixture.0).is_valid());
}
}

See more source ↗

Implemented sage_meta::start_invalidates_previous_success_and_record_is_required

crates/sage-meta/tests/review.rs · test:review

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.validation_layout)]
#[sage::test(meta.reviews.summary_format)]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.record_required)]
#[sage::test(meta.reviews.recorded_reads)]
#[sage::test(meta.reviews.recording)]
#[sage::test(meta.reviews.decisions)]
fn start_invalidates_previous_success_and_record_is_required() {
    let fixture = Fixture::new();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    fixture.approve();
    assert!(sage_meta::check(&fixture.0).is_valid());
    let input = fixture.start();
    assert_eq!(fixture.input(), input);
    let summary = fixture.summary();
    assert_eq!(summary["anchor"], "demo.rule");
    assert!(summary["started_at_unix_seconds"].as_u64().unwrap() > 0);
    assert!(summary["recorded_at_unix_seconds"].is_null());
    assert_eq!(summary["schema_version"], review::SCHEMA_VERSION);
    assert_eq!(summary["policy_version"], review::POLICY_VERSION);
    assert!(summary.get("input_sha256").is_none());
    assert!(!fixture.0.join("validations/demo.rule/output.json").exists());
    assert!(!sage_meta::check(&fixture.0).is_valid());
    let saved = review::load_saved(&fixture.0.join("validations")).unwrap();
    assert_eq!(saved.reviews.len(), 1);
    assert!(saved.reviews[0].output.is_none());
    fixture.write("helper.txt", "context\n");
    review::capture_read(&fixture.0, "demo.rule", "helper.txt", Selector::WholeFile).unwrap();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    let bytes = std::fs::read(fixture.0.join("validations/demo.rule/input.json")).unwrap();
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    assert_eq!(
        bytes,
        std::fs::read(fixture.0.join("validations/demo.rule/input.json")).unwrap()
    );
    assert!(
        fixture.summary()["recorded_at_unix_seconds"]
            .as_u64()
            .unwrap()
            >= summary["started_at_unix_seconds"].as_u64().unwrap()
    );
    assert!(sage_meta::check(&fixture.0).is_valid());
    assert!(review::record(&fixture.0, "demo.rule", &Fixture::report()).is_err());
    assert!(
        review::capture_read(&fixture.0, "demo.rule", "helper.txt", Selector::WholeFile).is_err()
    );
}
}

See more source ↗

Review: Accepted · final_quality.

Fresh final marker followup of meta.reviews.preparation. Preserved prior input/output, started fresh, assessed the complete claim, both ordinary implementation entries and all seven ordinary test bodies, and recaptured every prior dependency: review Fixture lines 1–106, shared check/workspace test, specification and correspondence inventories. Compared all fragments by path/selector and both metadata collections. The only change is an implementation_references association comment in supplementary spec.rs. All preparation behavior, claim, assertions, helpers and metadata are unchanged; no captures were removed. This isolated marker was assessed against the complete prior findings below.

review.rs start validates anchor syntax and current inventory and finds the requested anchor before changing records. It locks the validation parent, removes that anchor's old directory before publishing new input, creates the directory, writes captured input and unfinished summary, then returns that exact input. Other directories are untouched. Atomic per-file writes cannot restore an old output after removal; intermediate failure leaves missing/incomplete/unrecorded state, not approval of new inputs. main.rs reads optional instructions and prints returned serialized input after successful start. Inventory includes complete claim, implementation context, associated test functions and metadata. Shared check and workspace validation reject missing/unfinished review records. These mechanisms establish validation-before-clearing, persisted capture-before-printing, fresh-record requirement and isolation.

All seven tests supply concrete assertions. cli_start_and_record_roundtrip_exact_saved_input checks actual CLI stdout equals saved input and exact multiline instructions, then records and checks. initial_context_preserves_instructions_and_exact_uniform_fragments verifies prompt/instructions, saved equality and exact claim/file/test fragments. input_keeps_complete_association_metadata_and_appends_context_in_one_collection verifies metadata and unchanged initial prefix after reads. start_invalidates_previous_success_and_record_is_required proves restarting an unchanged approved fixture removes output and yields unfinished/failing state, reads cannot approve it, and fresh recording restores validity without changing input bytes. interrupted_start_publication_states_cannot_reuse_an_old_approval checks removed-directory, empty-directory and input-only states through both library and CLI gates, then requires recording after restart. This is intermediate-state testing, not filesystem fault injection. invalid_ids_and_paths_are_rejected_without_destroying_existing_reports checks malformed/unknown IDs preserve existing output and invalid reads preserve input. restarting_one_anchor_leaves_other_anchor_record_unchanged creates two approvals, restarts one and compares the other's summary/input/output bytes while restoring overall validity. Captured helpers build real Cargo/Design inputs and run actual CLI where asserted.

All preparation requirements are accounted for and no TODO/N/A entries exist. The supplementary comment changes none of these conclusions. No source edits, formatting, tests or workspace build were performed in this followup; executed review start/read, capture comparison and record only. No requested edits.

Browse meta anchors

116 anchors

Specification anchors and declared coverage
AnchorImplementationTests
meta (116)102 Implemented24 TODO103 Implemented36 TODO
meta.anchors (22)22 Implemented21 Implemented12 TODO
anchor_pagesImplementedImplementedTODO
book_explorerImplementedImplementedTODO
canonical_sourcesImplementedImplementedTODO
meta.anchors.content (7)7 Implemented7 Implemented
blocksImplementedImplemented
explicit_endImplementedImplemented
headingImplementedImplemented
literal_syntaxImplementedImplemented
next_anchorImplementedImplemented
source_endImplementedImplemented
unmatched_endImplementedImplemented
context_navigationImplementedImplementedTODO
evidence_statusImplementedImplementedTODO
explorer_navigationImplementedTODO
implementation_coverageImplementedImplementedTODO
implementation_referencesImplementedImplementedTODO
placeholder_statusImplementedImplementedTODO
point_excerptsImplementedImplementedTODO
region_balanceImplementedImplemented
region_excerptsImplementedImplementedTODO
test_coverageImplementedImplemented
test_referencesImplementedImplemented
unique_namesImplementedImplementedTODO
meta.book (21)10 Implemented18 TODO12 Implemented18 TODO
anchor_movesImplementedTODOImplementedTODO
authorityImplementedTODOImplementedTODO
browser_deliveryTODOImplementedTODO
browser_dependenciesTODOTODO
browser_rust_sourceTODOTODO
browser_searchTODOTODO
browser_serveTODOTODO
browser_structureTODOTODO
chapter_namesImplementedTODOImplementedTODO
crate_ownershipImplementedImplemented
crates_landingImplementedImplemented
entity_linksTODOTODO
index_groupsImplementedTODOImplementedTODO
index_namespace_pagesImplementedImplemented
index_rowsImplementedTODOImplementedTODO
index_statusImplementedTODOImplementedTODO
rfd_changesTODOTODO
sage_chaptersTODOImplementedTODO
self_descriptionTODOTODO
shared_modelImplementedTODOImplementedTODO
source_rolesTODOTODO
meta.contracts (4)4 Implemented3 TODO4 Implemented3 TODO
cache_invocationsImplementedTODOImplementedTODO
correspondenceImplementedImplemented
observation_coverageImplementedTODOImplementedTODO
validated_sessionImplementedTODOImplementedTODO
meta.language (39)39 Implemented39 Implemented
meta.language.calls (2)2 Implemented2 Implemented
declaredImplementedImplemented
forbiddenImplementedImplemented
meta.language.classes (3)3 Implemented3 Implemented
abstract_completeImplementedImplemented
override_signatureImplementedImplemented
single_inheritanceImplementedImplemented
meta.language.contexts (1)1 Implemented1 Implemented
inheritanceImplementedImplemented
meta.language.envelopes (7)7 Implemented7 Implemented
class_callsImplementedImplemented
createsImplementedImplemented
direct_callsImplementedImplemented
leafImplementedImplemented
permissionsImplementedImplemented
readsImplementedImplemented
receiver_callsImplementedImplemented
meta.language.fields (2)2 Implemented2 Implemented
context_stateImplementedImplemented
kindsImplementedImplemented
meta.language.methods (2)2 Implemented2 Implemented
kindsImplementedImplemented
proseImplementedImplemented
meta.language.model (3)3 Implemented3 Implemented
forbidden_pathsImplementedImplemented
inherited_prohibitionsImplementedImplemented
virtual_dispatchImplementedImplemented
meta.language.types (19)19 Implemented19 Implemented
argument_arityImplementedImplemented
declaration_proseImplementedImplemented
enum_variantsImplementedImplemented
field_proseImplementedImplemented
generic_parametersImplementedImplemented
member_commasImplementedImplemented
name_resolutionImplementedImplemented
opaque_representationImplementedImplemented
preludeImplementedImplemented
qualified_namesImplementedImplemented
recursive_valuesImplementedImplemented
struct_fieldsImplementedImplemented
tuplesImplementedImplemented
type_expressionsImplementedImplemented
unique_fieldsImplementedImplemented
unique_parametersImplementedImplemented
unique_variantsImplementedImplemented
unknown_namesImplementedImplemented
variant_proseImplementedImplemented
meta.reviews (27)27 Implemented27 Implemented
claim_textImplementedImplemented
complete_test_setImplementedImplemented
decisionsImplementedImplemented
fragment_associationsImplementedImplemented
fragment_formatImplementedImplemented
fragment_freshnessImplementedImplemented
gateImplementedImplemented
input_formatImplementedImplemented
input_fragmentsImplementedImplemented
output_formatImplementedImplemented
preparationImplementedImplemented
record_requiredImplementedImplemented
recorded_readsImplementedImplemented
recordingImplementedImplemented
review_delegationImplementedImplemented
review_diagnosticsImplementedImplemented
review_instructionsImplementedImplemented
review_scopeImplementedImplemented
selector_claimImplementedImplemented
selector_line_rangeImplementedImplemented
selector_testImplementedImplemented
selector_whole_fileImplementedImplemented
source_representationImplementedImplemented
stalenessImplementedImplemented
summary_formatImplementedImplemented
test_sourceImplementedImplemented
validation_layoutImplementedImplemented
meta.validation (3)3 TODO3 TODO
claim_specific_evidenceTODOTODO
independent_inspectionTODOTODO
review_packetsTODOTODO