Every specification anchor has a stable page identifying the rule and showing its definition, context, implementation entries, and tests/evidence. The page includes Rust excerpts and access to surrounding source, and exposes each entry’s placeholder status and explanation. Multiple sites remain individually inspectable rather than being reduced to a single coverage badge.

Read in specification context

The book build includes the architecture explorer and its model and Rust source snapshots. An explorer chapter embeds the browser and offers a full-page view. The handwritten Crates landing page links to .sage subchapters that provide the searchable, interlinked presentation defined by the browser specification. Book generation and local serving share the model and renderer under its delivery rule. Published browsing, including the Rust source pane, works without a running sage-meta serve process. Local book rebuilds refresh the snapshot when the model or its Rust sources change.

Read in specification context

A specification rule can be defined in a Markdown or .sage Design chapter, with equal authority. Its definition records the rule’s text and source location; a .sage definition also identifies its containing declaration, method, or envelope clause. Either documentation form can reference a rule defined in the other without creating another definition. Every reference must resolve to an existing definition; a dangling reference is an error.

Read in specification context

An anchor’s content starts after its definition marker and includes every subsequent Markdown block until the first applicable closing boundary. Blank lines do not end the content: paragraphs, lists, tables, and code blocks within that extent belong to the same anchor.

Read in specification context

A standalone line containing exactly <!-- end anchor -->, apart from surrounding horizontal whitespace, ends the active anchor immediately before that line. The comment is excluded from the anchor’s content. Subsequent prose remains outside an anchor until a new definition begins; the explicit marker is optional when another closing boundary already ends the content.

Read in specification context

A Markdown section heading ends the active anchor’s content immediately before the heading, regardless of heading level. Both hash-prefixed and underline-style headings are boundaries. Prose following the heading remains outside an anchor until another definition begins.

Read in specification context

Boundary-looking text inside fenced or indented code blocks, inline code, or escaped text does not open or close an anchor. Raw HTML examples do not supply anchor definitions, section headings, or end markers. A standalone end comment acts as a boundary only outside these literal contexts and enclosing HTML blocks.

Read in specification context

A new anchor definition ends the preceding anchor’s content immediately before the new marker. The new definition belongs to its own anchor; content extents do not overlap.

Read in specification context

An anchor’s content ends at the end of its containing Markdown document or .sage triple-quoted prose block. A .sage anchor never captures surrounding language syntax or content from another prose block, declaration, or method.

Read in specification context

An explicit end marker with no active anchor is a validation error. Another end marker after an explicit or implicit end, without an intervening definition, is therefore also an error. An anchor ending at another definition, a heading, or its source boundary does not require an explicit end marker.

Read in specification context

Clicking an anchor badge opens its anchor page. The page’s context link returns to the defining Markdown paragraph or .sage location. Context permalinks remain available independently of the anchor-page URL, so navigating to the rule’s connections does not lose access to its original specification text.

Read in specification context

An implementation or test entry establishes a declared association, not proof that the rule is satisfied. Source inventories retain cfg conditions without claiming that a site was compiled or a test executed. Anchor pages distinguish test source, recorded run results, and other evidence such as traces. A passing structural check or a passing dummy test must not present a TODO or Not applicable entry as established behavioral evidence.

Read in specification context

The explorer’s selected Sage entity or specification anchor is reflected in the enclosing chapter’s URL. Opening that URL restores the selection, and browser back/forward navigation keeps the chapter and explorer in agreement. Sharing a selection preserves the book’s navigation as well as the selected context. Every entity is directly addressable under the entity-link rule; these links are also available to references from other documentation.

Read in specification context

Every specification anchor has at least one explicitly declared Rust implementation entry. An anchor without one is an error. A test annotation or #[sage::item(...)] correspondence alone does not supply this entry. A placeholder implementation counts as an entry with its explicit status.

Read in specification context

A Rust implementation entry is introduced by a <code>// {anchor}`meta.language.calls.declared`</code> comment, optionally followed immediately by <<. Its name must resolve to a specification definition; malformed and unknown references are errors. Only actual Rust comments create these entries: marker-like text inside string literals does not. Entries retain their source location and enclosing module, and multiple entries may reference the same rule, including across crates.

Read in specification context

Implementation references and test annotations inside a Rust module named todo record work not yet done; those inside not_applicable record that the implementation or test does not apply. Each entry retains this status and its accompanying explanation. Ordinary entries, TODO entries, and Not applicable entries are displayed separately, even when they reference the same rule. An empty special module creates no entry: it must contain an implementation reference or an annotated test to account for the respective requirement.

mod not_applicable {
    // {anchor}`example.documentation_rule`
    // This rule describes documentation organization and has no runtime implementation.
}

mod todo {
    #[test]
    #[sage::test(example.documentation_rule)]
    fn documentation_rule() {
        // TODO: Check the generated documentation against the rule.
    }
}

The example’s example.documentation_rule stands for an existing definition; it does not declare a rule. Placeholder status applies independently to the implementation and test sides. Nesting a module under both todo and not_applicable is an error.

Read in specification context

A point reference has no << suffix. Its initial excerpt contains the marker line and the next five source lines, truncated at end-of-file. A See more… action opens the surrounding source at that location; the five-line preview does not claim to delimit the implementation.

// {anchor}`meta.language.calls.declared`
check_declared_call(caller, callee)?;

Read in specification context

A region opener without a closing delimiter, or a closing delimiter without an open region, is an error. Delimiters in string literals do not open or close regions. Region boundaries are determined from source comments, independently of the five-line previews used for point references.

The existing // ANCHOR: name / // ANCHOR_END: name convention remains independent: it delimits explanatory excerpts for mdBook/ezanchor. Canonical implementation entries require only the specification comment syntax above.

Read in specification context

A reference ending in << opens an explicit region, and a standalone // >> comment closes the nearest open region in the same file. Regions may nest. The excerpt spans the opening marker line through its closing marker line, with access to the surrounding source. A point reference inside a region remains a point reference and does not close or replace that region.

// {anchor}`meta.language.calls.declared`<<
let caller = current_operation();
check_declared_call(caller, callee)?;
record_call(caller, callee);
// >>

Read in specification context

Every specification anchor must have at least one annotated Rust test. An anchor without a test is an error, independently of its implementation coverage. A placeholder test counts as an entry with its explicit status; an implementation placeholder alone cannot satisfy the test requirement.

Read in specification context

Every #[sage::test(...)] reference must resolve to an existing specification anchor and be attached to a Rust test. Dangling and misplaced references are errors.

One test can cover several rules and a rule can have several tests. Unlike sage::item, a test may reference a rule across crate boundaries. An eligible test entry is a module-level function with the built-in #[test] attribute in a Cargo target with tests and the standard test harness enabled. Targets with test = false or harness = false and unconditionally or conditionally ignored tests cannot satisfy the requirement.

Read in specification context

Every specification anchor has a well-formed full name and exactly one definition in the Design chapter inventory. Malformed markers and duplicate full names are errors. Names are derived from the defining chapter; moves between chapter namespaces rename the rule and require updating its references.

Resolved names are dot-separated ASCII identifiers and describe independently testable behavior. A Markdown definition uses a chapter-local name with the custom MyST-style inline-role syntax. For example, in design/meta/language.md:

{anchor}`calls.declared`
Every observed architectural call must be permitted by its caller's resolved
dependency envelope.

The marker and the opening prose form one paragraph: do not leave a blank line between them. Later blocks can continue the same claim under the content rules. The example resolves to meta.language.calls.declared. Use the same definition syntax inside .sage triple-quoted prose. In either format, {spec} followed by a backtick-quoted full name references an existing rule without creating another definition.

Read in specification context

Moving a rule within its chapter preserves its identity. Changing its local name or moving it into a different chapter namespace renames the rule and requires updating specification, implementation, and test references. Published links to the old location retain a redirect or context alias. A compatibility link does not create a second canonical definition or satisfy a stale code reference.

Read in specification context

The mdBook Design chapter tree is the canonical specification. Markdown and .sage are equally authoritative source formats within that tree. Every active rule definition belongs to a Design chapter with identifiable source context; its appearances in generated indexes or anchor pages refer to that definition and do not create additional definitions.

Read in specification context

Book generation, standalone export, and local serving use the same resolved model and renderer to implement these browsing rules. Invalid models produce diagnostics instead of a partially valid explorer. A generated book or standalone HTML artifact includes the data and assets needed for navigation, search, entity links, and Rust source display without a Sage server. Each view identifies itself as a snapshot. Model or Rust edits become visible when that snapshot is rebuilt, exported again, or regenerated by restarting the server.

Read in specification context

Method views render each declared envelope clause with its effect kind and target: invocations, input reads, context creation, and transitive prohibitions. They expose possible direct callees, reverse callers, and overriding implementations, using the validator’s conservative dispatch resolution. Inherited prohibitions retain their declaring method. Linked targets lead to the corresponding entities. These views label declared permissions and prohibitions as such; they do not imply that a permitted call happened or that runtime conformance has been established.

Read in specification context

Readers can reveal or hide a Rust source pane without leaving the selected Sage entity. The pane follows selection and uses indexed Rust correspondences, showing the file, line numbers, and highlighted declaration with surrounding source. Multiple mapped sites are individually selectable. Missing source is reported explicitly. Module markers, macro-input sites, and cfg conditions remain distinguishable from a confirmed active executable implementation. The pane identifies its contents as a source snapshot; navigating to code does not establish that the code executed or satisfied a specification rule.

Read in specification context

Search finds declared entities by name, qualified model path, descriptive prose, and corresponding Rust paths when available. Crate and entity-kind filters combine with the search text. Results identify each entity’s kind and owner and link directly to it, including named members. The view states when no entities match. Changing search or filters does not invalidate an entity’s direct link or prevent opening a linked entity outside the current results.

Read in specification context

The sage-meta serve <port> command validates and renders the selected model before serving its snapshot on the loopback interface. It reports the local URL and serves until stopped. The port must be an integer from 1 through 65535; an optional model path selects the input. Invalid arguments, model errors, and binding failures produce a failing exit status with a diagnostic. Opening the reported URL provides the specified browser without another serving command.

For example, cargo run -p sage-meta -- serve 3001 serves the snapshot at http://127.0.0.1:3001/. cargo run -p sage-meta -- browse writes a standalone HTML snapshot. The commands are ways to deliver the browser specified here.

Read in specification context

Readers can navigate from crates to modules, declarations, and their members, with the owning crate, module, and declaration visible at each level. Crate views show purpose and dependencies. Declaration views show kind, descriptive prose, generic parameters, and the modeled structure: struct fields, enum variants and their fields, or the description of an opaque type. Class and context views show fields, base classes, and methods, distinguishing declared, inherited, abstract, and overriding methods. Method views show query/function kind, signature, and prose. References to modeled types, bases, and methods link to their declarations.

Read in specification context

An anchor’s full name combines its chapter namespace with the local name written at its definition. The namespace is derived from the chapter source path relative to Design, removing the extension and joining path components with dots. For example, local point_excerpts in design/meta/anchors.md names meta.anchors.point_excerpts. The same derivation applies to .sage chapters. Section headings, chapter titles, and sidebar ordering do not change these names; only the source path and local name contribute. Ambiguous namespace derivations or duplicate full names are errors.

The intended Markdown source spelling is local:

{anchor}`point_excerpts`
A point reference displays its marker line and the next five source lines.

Rust references use the resolved full name, such as #[sage::test(meta.anchors.point_excerpts)] or <code>// {anchor}`meta.anchors.point_excerpts`</code>. Filename components must normalize to ASCII identifiers; different source paths that normalize to the same chapter namespace are rejected.

Read in specification context

Every .sage chapter lies beneath a directory identifying its Rust crate. The crate’s crate.sage manifest establishes the modeled crate boundary; the book loader checks that ownership against the Rust workspace. Book chapter namespaces and compiler-model item identities are distinct: moving a crate’s book directory preserves identities such as $sage_ir::symbols::Symbol when the modeled crate and declaration paths are unchanged.

Read in specification context

The Crates landing page preserves handwritten Markdown from design/crates/README.md. Its curated subsystem introductions link to rendered crate chapters and modeled entities. Generated crate and module chapters are children of this page; generation does not replace its prose with the explorer. Links written to .sage source chapters resolve to their rendered chapters.

Read in specification context

Every declared Sage entity has an unambiguous direct link, including crates, modules, types, classes, contexts, methods/queries, and named members such as fields and enum variants. Opening a link selects the declaration or member in its rendered context without a prior search or browser session. Links resolve through the entity’s identity and owning scope: equal local names in different owners remain distinct, and relocating a chapter does not break links to unchanged model entities. Markdown and .sage sources can reference these identities; rendered references link to the corresponding entity and unresolved references are errors.

Entity links and specification anchors have different purposes. For example, $sage_ir::symbols::Symbol identifies a modeled declaration, whereas meta.book.entity_links identifies a testable rule. Making a declaration linkable does not create a specification rule or require an extra named paragraph. The authoring syntax for entity references and URL spelling remain implementation-plan decisions. Selection URLs and browser history follow the navigation rule.

Read in specification context

The anchor index groups entries hierarchically by their name prefixes, such as meta and meta.book. Each group can reveal or hide all its descendants, and reports implementation and test status counts for that subtree. Grouping and counts are derived from the same active anchors displayed in the index.

Read in specification context

The generated Anchors landing page lists every active rule. Each namespace prefix has a page with the same table restricted to that prefix. A rule named meta.foo.bar has a direct page under design/anchor/meta/foo/bar; the page shows the rule and navigation within its surrounding namespace. If a rule’s name is also a prefix of other rules, one page presents both its own claim and its descendants. Generated pages do not create new specification definitions.

Read in specification context

The Design section includes an automatically generated index of every active anchor. Each anchor has a main row containing the final component of its name, with the namespace supplied by the enclosing group or page heading, and separate implementation and test statuses. The name’s tooltip shows its full identity. A disclosure control opens a second row containing its rendered specification text. Hiding the text preserves the main row. The linked name opens that anchor’s own page, independently of expanding or collapsing the text.

Read in specification context

Implementation and test status are computed independently from their declared entries: ordinary entries display Implemented, todo entries display TODO, and not_applicable entries display N/A. Mixed statuses remain visible, including outstanding TODOs when another entry is implemented. An absent implementation or test entry is a validation error, not an implicit TODO or N/A. These labels describe declared coverage; recorded run results remain separate evidence.

Read in specification context

An RFD branch contains both the design record and the proposed normative Design changes. The RFD records motivation, alternatives, goals, and a high-level overview of the required changes, with links to the affected Design pages and anchors. Its implementation plan develops that overview into stages. Acceptance merges the record and specification changes together; unfinished implementation or tests remain explicit TODO entries. Subsequent implementation replaces those entries with code and evidence. Completing an RFD does not require copying its rules into Design, because the normative changes were already expressed there.

Read in specification context

.sage sources reside within the book’s configured source directory and each is rendered as a Design chapter. Design contains a Crates chapter listing the modeled crates. Each crate has an overview chapter showing its purpose, dependencies, and modules, with its remaining .sage source chapters nested beneath it. These chapters present the design/crates/ source tree using the architecture browser specified below. Each source has one chapter in the shared inventory; rendering does not create a second canonical copy. Rendering requires no hand-maintained Markdown copies of .sage sources and the built book works without a running Sage server.

Read in specification context

The specification-book system is itself specified by anchors in Design. Its rules participate in the same naming, reference validation, implementation and test coverage, status reporting, index, and anchor-page generation as all other rules. A rule about the validator or renderer receives no exemption from those requirements; unfinished work uses explicit TODO entries.

Read in specification context

Book generation and sage-meta check consume the same resolved Design chapter inventory, rule identities, source provenance, and correspondence data. Plugins that contribute specification chapters participate in that inventory. A source chapter omitted from the intended Design inventory is diagnosed rather than silently checked but unpublished or published but unchecked. Generated copies of rule text are not re-indexed as new definitions. The CLI, CI, and workspace test apply the shared validation to the book system’s own rules too.

Read in specification context

The Design overview contains Meta, Tenets, Anchors, Crates, and RFDs. Meta specifies the specification system itself. Tenets explains design principles without defining specification anchors. Anchors is generated from all active specification rules. Crates combines a handwritten reading map and modeled crate chapters. RFDs record changes and reasoning without defining active rules. The User’s Guide provides non-normative usage instructions.

Read in specification context

Every annotated source invocation is checked, including query cache hits and same-operation recursion. A Salsa request and its execution represent one architectural invocation. Internal validation, dependency reexecution, and accumulator traversal remain distinguishable from source requests; reexecution establishes the executing operation’s context without attributing its work to the suspended caller or inventing a source call.

Verification covers cold, reused, validated, invalidated/reexecuted, recursive, cancelled, and panicking runs, calls through generated query APIs, and an unannotated query beneath an annotated caller. Hand-reviewed traversals identify the architectural operations, Rust declaration sites, parentage, and cache outcomes. A warm forbidden request must fail even when its body does not execute.

Read in specification context

Every Sage correspondence unit has one or more Rust locations declared through #[sage::item(...)]. Every such annotation resolves to a compatible Sage unit in its containing modeled crate. Crate and module headers, named declarations, and explicit methods are correspondence units. Multiple source locations are permitted; module markers provide source coverage but do not establish runtime execution coverage. Cargo package and target metadata determine Rust ownership.

Verification exercises missing locations, dangling annotations, wrong crates, incompatible operation kinds, multiple sites, abstract markers, Cargo library and binary roots, and declarations produced by supported generators. Arbitrary macro tokens do not establish a generated declaration’s existence.

Read in specification context

Incomplete observation cannot establish conformance. Unmapped requests, unsupported receiver checks, and uninstrumented effects remain explicit gaps. Strict acceptance requires complete checking of the declared scope, as well as absence of violations. Diagnostics identify the checking scenario, relevant model rule when one exists, and observed call path; an unknown mapping is not silently attributed to the caller.

Verification injects each gap into an otherwise passing scenario and requires an incomplete or failing result, including cached requests and unsupported async boundaries. A call-only report does not claim that input reads, context construction, ordinary uninstrumented helpers, or task propagation were checked.

Read in specification context

A checking session uses one immutable, validated contract model and its source correspondence index. Every event refers to that same snapshot. Enabled enforcement fails if its model is missing or invalid, or if the indexed Rust source cannot be paired with the running binary. Loading is cached for the session; source edits take effect only in a subsequent session.

Verification exercises cached loads, parallel first use, explicit model roots, missing and invalid files, source/build mismatch rejection, and a subsequent session seeing model edits. Independently configured fixture sessions can use different models without modifying an active session.

Read in specification context

Every observed architectural call must be permitted by its caller’s resolved dependency envelope. An undeclared call is an error, including recursive entry into the same operation and requests satisfied from a query cache.

Read in specification context

An observed operation must not violate a prohibition of any active ancestor, even when its immediate caller permits the call. A violation is an error and retains the prohibition and complete call path.

Read in specification context

A concrete class must implement every inherited abstract method.

Read in specification context

An overriding method must preserve the inherited method’s operation kind and resolved result type.

Read in specification context

A class or context declaration has at most one extends base.

Read in specification context

Contexts are a distinct declaration kind and may inherit only from contexts. An ordinary or abstract class cannot inherit from a context.

Read in specification context

invokes crate::module::Class::method(); permits a call on any instance of the named class or a known subclass. This permission does not require equality with the caller’s receiver.

Read in specification context

creates name: crate::module::Context; declares a fresh owned working context under the given binding name. Its target must resolve to a context declaration. This describes context creation; validation does not perform the allocation.

Read in specification context

Each invocation clause grants a direct dependency. Transitive reachability is derived from those direct edges and does not grant the caller permission to invoke an indirect dependency directly.

Read in specification context

An empty envelope describes a leaf operation with no modeled dependencies. It is distinct from an abstract method, which has no declared envelope.

Read in specification context

Declared calls are permissions: none must occur, and calls may occur in an order different from the order of their envelope clauses.

Read in specification context

reads self.field; permits reading a field declared on this receiver’s class or inherited from a base. Unknown fields and non-self field paths are errors.

Read in specification context

invokes self.method(); permits a call on the current semantic receiver. A matching method on a different receiver does not satisfy that permission.

Read in specification context

A state field is valid only in a context declaration.

Read in specification context

Fields retain their declared identity, input, or state kind, distinguishing identity from changing inputs and local working state.

Read in specification context

Methods retain their declared operation kind: query or fn. Resolving a method’s contract preserves that distinction.

Queries describe memoized semantic products; functions describe ordinary computation. These annotations document boundaries; the model has no evaluator or cache.

Read in specification context

Every method body begins with a triple-quoted description, followed by its envelope or abstract; declaration. The description is retained as prose; method-like text within it adds no dependency permissions.

Read in specification context

forbid transitive crate::module::Class::method; prohibits reaching its target over any permitted nonempty call path. A rejected path identifies the offending method sequence.

Read in specification context

An overriding implementation inherits the prohibitions of the base method.

Prohibitions record design intent even when the permitted graph already excludes the target. Adding a permitted edge must still fail validation if it creates a forbidden path.

Read in specification context

The checker resolves declared calls conservatively, including every known overriding implementation in the supplied model.

Read in specification context

Each named type application must supply exactly the declared number of type arguments. This applies to opaque types, built-in types, parameters, and nested applications; a type parameter takes zero arguments.

Read in specification context

A struct or enum can carry triple-quoted prose immediately inside its opening brace. The parsed declaration retains that text; omitting it is permitted.

Read in specification context

An enum contains named variants in source order. A variant can have no payload, an ordered tuple payload, or named, typed fields. These three shapes remain distinct, including when a tuple or named payload is empty.

Read in specification context

A named field can carry triple-quoted prose immediately before its name. The parsed field retains that text independently of the containing declaration or variant’s prose. At the start of a body, the first prose string describes the container; a description for its first field follows as a second string.

Read in specification context

Structs, enums, and opaque types can declare a nonempty comma-separated list of type parameters in angle brackets. Parameters are available throughout their own declaration and do not become names in other declarations.

Read in specification context

Adjacent named fields, enum variants, and tuple payload elements require a comma separator. A trailing comma before the closing delimiter is optional.

For example:

type Binder<T> {
    """A value under the generic parameters binding its references."""
}

struct Items {
    items: Vec<crate::symbols::Symbol>,
}

enum MethodReceiver {
    Value { mutable_binding: bool },
    Ref {
        """A borrowed receiver with the declared mutability."""
        mutability: Mutability,
    },
}

Read in specification context

An unqualified type name resolves first to a parameter of its declaration, then to a type, class, or context in the same module, then to the built-in prelude. An earlier match shadows a later one.

Read in specification context

An opaque type declares a name and any type parameters without fields or variants. It requires triple-quoted descriptive prose, either inside braces or before a terminating semicolon. A payload inside its body is an error.

Read in specification context

The built-in prelude contains Vec<T>, Option<T>, bool, u32, u64, and String. These names are available without declaring them in the model.

Read in specification context

A type outside the current module requires a crate:: or $cratename:: qualified path. Cross-crate type references require a declared dependency; unqualified lookup does not search other modules or the crate root.

Read in specification context

Semantic value types can refer directly to themselves or to each other, without Box or another storage indirection. Such recursion is not a validation error.

Read in specification context

A struct contains named, typed fields. The parsed declaration retains their names, types, and source order; an empty struct is permitted.

Read in specification context

Parentheses always denote a tuple, including () and a single element with or without a trailing comma. (T) is distinct from T when result types are compared for an override.

Read in specification context

Type expressions are named types with optional generic arguments, or tuples. Generic arguments and tuple elements are themselves type expressions, allowing arbitrary nesting. The parsed expression retains that nesting.

Read in specification context

Named fields have distinct names within a struct or a single enum variant. Different declarations and different variants may reuse field names.

Read in specification context

A value declaration cannot repeat a type parameter’s name.

Read in specification context

Variants have distinct names within an enum. Different enums may reuse a variant name.

Read in specification context

Every type name in a value field, variant payload, class or context field, or method result must resolve. An unknown name is an error even when nested in generic arguments or tuples.

Read in specification context

A variant can carry triple-quoted prose immediately inside its payload’s opening delimiter, or immediately after a unit variant’s name. The parsed variant retains that text independently of other variants.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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,
    },
}

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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.

Read in specification context

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

Read in specification context

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.

Read in specification context

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.

Read in specification context

The summary contains these fields:

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

Read in specification context

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.

Read in specification context

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.

Read in specification context

Evidence is attached to one architectural claim. A statement that a behavior is established identifies evidence exercising that particular behavior, while a negative or partial artifact may pin a known limitation. A passing aggregate suite is not evidence for an unstated local guarantee.

Verification scenarios: Documentation review checks every implemented capability against a focused test, snapshot, normalized trace, edit experiment, exact oracle result, inspector scenario, or source anchor whose asserted behavior matches the claim.

Read in specification context

Human inspection and exact conformance remain independent. Readable Sage-only views explain semantic values and incremental work; the Oracle independently decides compatibility from Sage and rustc emissions. Neither facility consumes the other’s output to repair or reinterpret a result.

Verification scenarios: Architecture and dependency tests keep inspector adapters out of oracle comparison and rustc-oracle values out of inspector rendering, while one pinned slice supplies both independently produced forms of evidence.

Read in specification context

A review packet connects result, dependency, edit, and code evidence. For one semantic target, the packet identifies the Rust input, readable result, diagnostic/completeness outcome, cold and warm dependencies, relevant or unrelated edit behavior, focused or oracle verification, and anchored implementation entry points.

Verification scenarios: Each designated review packet contains or links all seven elements, and its reproduction commands regenerate the checked-in artifacts without relying on unrecorded setup.

Read in specification context