Functions
list[dict]	records (Path path, str key)
	Read one registry list.

Path	resolve_page (str name)
	Resolve a page argument, accepting a number, stem, or filename.

str	source_path (str source)
	Extract a repository path from a path-or-symbol source declaration.

str	module_path (str module)
	Convert a Python module identifier to its repository path.

dict[str, str]	page_aliases ()
	Map both filenames and Doxygen page identifiers to published page stems.

str	canonical_page (str reference)
	Resolve a registry page reference to its filename stem when declared by Doxygen id.

str	git_log (list[str] paths)
	Recent history for a set of paths, for spotting what changed underneath a route.

list[dict]	contracts_for (str page_stem)
	Invariant contracts that own or depend on a page.

list[dict]	families_for (str page_stem)
	Capability families whose entries live on a page.

set[str]	record_pages (dict record)
	Collect obligation and concern pages from a subsystem record.

list[dict]	subsystems_for_pages (set[str] page_stems)
	Find subsystem records routed through any supplied page.

list[dict]	scope_records_for (str page_stem)
	Scope records that name a page as a disclosure or activation surface.

list[tuple[str, dict]]	freshness_for (str page_stem)
	Freshness surfaces that route review to a page.

list[str]	freshness_paths (dict surface)
	Return the artifact or watched paths that define a freshness surface.

str	freshness_state (dict surface)
	Whether a surface is current, suspect, or never attested.

str	_freshness_digest (list[str] paths)
	Digest matching audit_freshness.digest_of.

str	uncommitted (list[str] paths)
	Current uncommitted status for declared sources.

list[tuple[str, str, str]]	family_source_specs (dict family)
	Resolve a capability family's declared source paths and symbols.

list[str]	symbols_for (dict family)
	Named symbols a capability family depends on, rather than whole files.

list[str]	evidence_sources (dict family)
	Declared evidence sources across a family's values.

list	recorded_measurements (list[str] sources)
	Measurement records cited by declared evidence sources.

list[str]	make_targets (list[str] sources)
	Make targets named by declared evidence sources.

int	route_status (list[str] unresolved, bool unavailable=False)
	Print the fixed route state and any unresolved declarations.

int	unknown_identifier (str kind, str identifier, list[str] known)
	Report an invalid registry identifier with close matches and known ids.

None	print_freshness (list[tuple[str, dict]] surfaces, str heading)
	Print freshness routing with current attestation state.

tuple[str, dict\|None]	load_xref ()
	Load the optional cross-reference index only when its dirty-byte stamp is current.

list[str]	xref_matches (dict index, str path, str symbol)
	Match a declared path and symbol to Doxygen member identifiers.

str	format_xref_node (dict index, str refid)
	Format one indexed symbol with its definition location.

None	print_measurements (list records)
	Print the measurements already recorded against this route.

None	print_xref (list[tuple[str, str, str]] specs, list[str]\|None paths=None)
	Print bounded direct and two-hop Doxygen reference evidence for a route.

int	contract_mode (str contract_id)
	Print a review packet for one invariant contract.

int	capability_mode (str capability_id)
	Join one capability family across symbols, pages, contracts, evidence, and subsystems.

int	subsystem_mode (str subsystem_id)
	Join one subsystem across capability families, obligation pages, contracts, and evidence.

int	surface_mode (str surface_id)
	Join one freshness surface across watched paths, pages, contracts, families, and subsystems.

tuple[dict[str, set[str]], bool]	changed_paths ()
	Collect staged, unstaged, and untracked nonignored paths from Git.

str	classify_path (str path)
	Classify a changed path for routing coverage.

dict[str, list[str]]	routes_for_path (str path)
	Find declared capabilities, surfaces, contracts, and subsystems touching a path.

str	guide_fallback (str path)
	Return the nearest existing directory guide for an unrouted production path.

int	changed_mode (str value)
	Report declared routing coverage for current working-tree changes.

int	page_mode (str page_name)
	Print the original page-scoped review packet with explicit route status and xrefs.

argparse.Namespace	parse_args (list[str] argv)
	Parse the mutually exclusive review-packet route selectors.

int	main (list[str]\|None argv=None)
	Dispatch the requested bounded route and preserve differentiated exit states.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]

str	PAGES_DIR = REPO_ROOT / "docs" / "pages"

	TOOLING_DIR = Path(__file__).resolve().parent

str	CONTRACTS = TOOLING_DIR / "contract_registry.json"

str	FRESHNESS = TOOLING_DIR / "freshness_manifest.json"

str	MEASUREMENTS = TOOLING_DIR / "measurement_records.json"

str	FAMILIES = TOOLING_DIR / "capability_families.json"

str	SUBSYSTEMS = TOOLING_DIR / "subsystem_records.json"

str	SCOPE = TOOLING_DIR / "capability_scope_records.json"

str	XREF = REPO_ROOT / "docs_build" / "xref.json"

tuple	XREF_CAVEAT

str	COMPLETE = "ROUTE: complete over declared registry data (not over code behavior)"

str	INCOMPLETE = "ROUTE: incomplete — declared identifier has unresolved routing"

str	UNAVAILABLE = "ROUTE: unavailable — required environment or metadata is absent"

Detailed Description

Assemble bounded review packets from PICurv's declared routing registries.

Function Documentation

◆ records()

list[dict] review_packet.records	(	Path	path,
		str	key
	)

Read one registry list.

Parameters

[in]	path	Registry JSON path.
[in]	key	Top-level list key.

Returns: Registry records.

Definition at line 48 of file review_packet.py.

def records(path: Path, key: str) -> list[dict]:
    """!
    @brief Read one registry list.
    @param[in] path Registry JSON path.
    @param[in] key Top-level list key.
    @return Registry records.
    """
 
    return json.loads(path.read_text(encoding="utf-8"))[key]
 
 

Here is the caller graph for this function:

◆ resolve_page()

Path review_packet.resolve_page ( str name )

Resolve a page argument, accepting a number, stem, or filename.

Parameters

[in] name Page identifier supplied on the command line.

Returns: Path to the page.

Exceptions

SystemExit when no page matches.

Definition at line 59 of file review_packet.py.

def resolve_page(name: str) -> Path:
    """!
    @brief Resolve a page argument, accepting a number, stem, or filename.
    @param[in] name Page identifier supplied on the command line.
    @return Path to the page.
    @throws SystemExit when no page matches.
    """
 
    candidates = sorted(PAGES_DIR.glob("*.md"))
    for page in candidates:
        if name in (page.name, page.stem) or page.stem.startswith(f"{name}_"):
            return page
    print(f"ROUTE: invalid — no page matches '{name}'.", file=sys.stderr)
    print("Known pages:", file=sys.stderr)
    for page in candidates:
        print(f"  {page.stem}", file=sys.stderr)
    raise SystemExit(2)
 
 

Here is the caller graph for this function:

◆ source_path()

str review_packet.source_path ( str source )

Extract a repository path from a path-or-symbol source declaration.

Parameters

[in] source Declared source string.

Returns: Repository-relative path portion.

Definition at line 78 of file review_packet.py.

def source_path(source: str) -> str:
    """!
    @brief Extract a repository path from a path-or-symbol source declaration.
    @param[in] source Declared source string.
    @return Repository-relative path portion.
    """
 
    return source.split("::", 1)[0]
 
 

Here is the caller graph for this function:

◆ module_path()

str review_packet.module_path ( str module )

Convert a Python module identifier to its repository path.

A dotted name may address a package rather than a single file - the storage surface is one - in which case the package directory is the source, because that is what an importer resolves the name to.

Parameters

[in] module Dotted Python module.

Returns: Repository-relative Python path.

Definition at line 88 of file review_packet.py.

def module_path(module: str) -> str:
    """!
    @brief Convert a Python module identifier to its repository path.
 
    @details A dotted name may address a package rather than a single file - the
             storage surface is one - in which case the package directory is the
             source, because that is what an importer resolves the name to.
    @param[in] module Dotted Python module.
    @return Repository-relative Python path.
    """
 
    relative = module.replace(".", "/")
    if (REPO_ROOT / relative).is_dir():
        return relative
    return relative + ".py"
 
 
@lru_cache(maxsize=1)

Here is the caller graph for this function:

◆ page_aliases()

dict[str, str] review_packet.page_aliases ( )

Map both filenames and Doxygen page identifiers to published page stems.

Returns: Alias-to-page-stem mapping.

Definition at line 106 of file review_packet.py.

def page_aliases() -> dict[str, str]:
    """!
    @brief Map both filenames and Doxygen page identifiers to published page stems.
    @return Alias-to-page-stem mapping.
    """
 
    aliases: dict[str, str] = {}
    for page in PAGES_DIR.glob("*.md"):
        aliases[page.stem] = page.stem
        match = re.search(r"(?:^|\n)\s*@page\s+(\S+)", page.read_text(encoding="utf-8"))
        if match:
            aliases[match.group(1)] = page.stem
    return aliases
 
 

Here is the caller graph for this function:

◆ canonical_page()

str review_packet.canonical_page ( str reference )

Resolve a registry page reference to its filename stem when declared by Doxygen id.

Parameters

[in] reference Page stem or Doxygen page identifier.

Returns: Canonical filename stem, or the unresolved input.

Definition at line 121 of file review_packet.py.

def canonical_page(reference: str) -> str:
    """!
    @brief Resolve a registry page reference to its filename stem when declared by Doxygen id.
    @param[in] reference Page stem or Doxygen page identifier.
    @return Canonical filename stem, or the unresolved input.
    """
 
    return page_aliases().get(reference, reference)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ git_log()

str review_packet.git_log ( list[str] paths )

Recent history for a set of paths, for spotting what changed underneath a route.

Parameters

[in] paths Repository-relative paths.

Returns: Formatted git log output.

Definition at line 131 of file review_packet.py.

def git_log(paths: list[str]) -> str:
    """!
    @brief Recent history for a set of paths, for spotting what changed underneath a route.
    @param[in] paths Repository-relative paths.
    @return Formatted git log output.
    """
 
    if not paths:
        return "  (none declared)"
    result = subprocess.run(
        ["git", "-C", str(REPO_ROOT), "log", "--oneline", "-8", "--", *paths],
        capture_output=True,
        text=True,
        check=False,
    )
    return "\n".join(f"  {line}" for line in result.stdout.strip().splitlines()) or "  (no history)"
 
 

Here is the caller graph for this function:

◆ contracts_for()

list[dict] review_packet.contracts_for ( str page_stem )

Invariant contracts that own or depend on a page.

Parameters

[in] page_stem Page identifier without extension.

Returns: Matching contract records.

Definition at line 149 of file review_packet.py.

def contracts_for(page_stem: str) -> list[dict]:
    """!
    @brief Invariant contracts that own or depend on a page.
    @param[in] page_stem Page identifier without extension.
    @return Matching contract records.
    """
 
    return [
        contract
        for contract in records(CONTRACTS, "contracts")
        if page_stem
        in contract.get("canonical_documentation", []) + contract.get("dependent_pages", [])
    ]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ families_for()

list[dict] review_packet.families_for ( str page_stem )

Capability families whose entries live on a page.

Parameters

[in] page_stem Page identifier without extension.

Returns: Matching family records.

Definition at line 164 of file review_packet.py.

def families_for(page_stem: str) -> list[dict]:
    """!
    @brief Capability families whose entries live on a page.
    @param[in] page_stem Page identifier without extension.
    @return Matching family records.
    """
 
    return [family for family in records(FAMILIES, "families") if family["family_page"] == page_stem]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ record_pages()

set[str] review_packet.record_pages ( dict record )

Collect obligation and concern pages from a subsystem record.

Parameters

[in] record Subsystem lifecycle record.

Returns: Page stems named by the record.

Definition at line 174 of file review_packet.py.

def record_pages(record: dict) -> set[str]:
    """!
    @brief Collect obligation and concern pages from a subsystem record.
    @param[in] record Subsystem lifecycle record.
    @return Page stems named by the record.
    """
 
    pages: set[str] = set()
    for section in ("obligations", "concerns"):
        for value in record.get(section, {}).values():
            if isinstance(value, dict) and value.get("page"):
                pages.add(canonical_page(value["page"]))
    return pages
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ subsystems_for_pages()

list[dict] review_packet.subsystems_for_pages ( set[str] page_stems )

Find subsystem records routed through any supplied page.

Parameters

[in] page_stems Page stems to match.

Returns: Matching subsystem records.

Definition at line 189 of file review_packet.py.

def subsystems_for_pages(page_stems: set[str]) -> list[dict]:
    """!
    @brief Find subsystem records routed through any supplied page.
    @param[in] page_stems Page stems to match.
    @return Matching subsystem records.
    """
 
    return [record for record in records(SUBSYSTEMS, "subsystems") if record_pages(record) & page_stems]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scope_records_for()

list[dict] review_packet.scope_records_for ( str page_stem )

Scope records that name a page as a disclosure or activation surface.

Parameters

[in] page_stem Page identifier without extension.

Returns: Matching scope records.

Definition at line 199 of file review_packet.py.

def scope_records_for(page_stem: str) -> list[dict]:
    """!
    @brief Scope records that name a page as a disclosure or activation surface.
    @param[in] page_stem Page identifier without extension.
    @return Matching scope records.
    """
 
    if not SCOPE.is_file():
        return []
    matches = []
    for record in records(SCOPE, "records"):
        surfaces = record.get("disclosed_at", []) + record.get("activation_condition", {}).get("surfaces", [])
        if any(page_stem in surface for surface in surfaces):
            matches.append(record)
    return matches
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ freshness_for()

list[tuple[str, dict]] review_packet.freshness_for ( str page_stem )

Freshness surfaces that route review to a page.

Parameters

[in] page_stem Page identifier.

Returns: List of role and surface pairs.

Definition at line 216 of file review_packet.py.

def freshness_for(page_stem: str) -> list[tuple[str, dict]]:
    """!
    @brief Freshness surfaces that route review to a page.
    @param[in] page_stem Page identifier.
    @return List of role and surface pairs.
    """
 
    found: list[tuple[str, dict]] = []
    for surface in records(FRESHNESS, "surfaces"):
        if page_stem in surface.get("owning_pages", []):
            found.append(("owns", surface))
        elif page_stem in surface.get("dependent_pages", []):
            found.append(("depends on", surface))
    return found
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ freshness_paths()

list[str] review_packet.freshness_paths ( dict surface )

Return the artifact or watched paths that define a freshness surface.

Parameters

[in] surface Freshness manifest record.

Returns: Repository-relative paths.

Definition at line 232 of file review_packet.py.

def freshness_paths(surface: dict) -> list[str]:
    """!
    @brief Return the artifact or watched paths that define a freshness surface.
    @param[in] surface Freshness manifest record.
    @return Repository-relative paths.
    """
 
    return [surface["artifact"]] if surface["tier"] == "hard" else list(surface.get("watched_paths", []))
 
 

Here is the caller graph for this function:

◆ freshness_state()

str review_packet.freshness_state ( dict surface )

Whether a surface is current, suspect, or never attested.

Parameters

[in] surface One freshness manifest entry.

Returns: Human-readable state.

Definition at line 242 of file review_packet.py.

def freshness_state(surface: dict) -> str:
    """!
    @brief Whether a surface is current, suspect, or never attested.
    @param[in] surface One freshness manifest entry.
    @return Human-readable state.
    """
 
    paths = freshness_paths(surface)
    missing = [path for path in paths if not (REPO_ROOT / path).exists()]
    if missing:
        return f"INTEGRITY FAILURE - missing {', '.join(missing)}"
    attested = surface.get("attested_digest")
    if attested in (None, "unattested"):
        return "never attested"
    return "current" if attested == _freshness_digest(paths) else "SUSPECT"
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _freshness_digest()

str review_packet._freshness_digest ( list[str] paths )

protected

Digest matching audit_freshness.digest_of.

Parameters

[in] paths Repository-relative paths.

Returns: Hex digest with algorithm prefix.

Definition at line 259 of file review_packet.py.

def _freshness_digest(paths: list[str]) -> str:
    """!
    @brief Digest matching audit_freshness.digest_of.
    @param[in] paths Repository-relative paths.
    @return Hex digest with algorithm prefix.
    """
 
    accumulator = hashlib.sha256()
    for relative in sorted(paths):
        accumulator.update(relative.encode("utf-8"))
        accumulator.update(b"\0")
        accumulator.update((REPO_ROOT / relative).read_bytes())
        accumulator.update(b"\0")
    return f"sha256:{accumulator.hexdigest()}"
 
 

Here is the caller graph for this function:

◆ uncommitted()

str review_packet.uncommitted ( list[str] paths )

Current uncommitted status for declared sources.

Parameters

[in] paths Repository-relative paths.

Returns: Formatted status output.

Definition at line 275 of file review_packet.py.

def uncommitted(paths: list[str]) -> str:
    """!
    @brief Current uncommitted status for declared sources.
    @param[in] paths Repository-relative paths.
    @return Formatted status output.
    """
 
    if not paths:
        return "  (none declared)"
    result = subprocess.run(
        ["git", "-C", str(REPO_ROOT), "status", "--porcelain", "--", *paths],
        capture_output=True,
        text=True,
        check=False,
    )
    body = result.stdout.strip()
    return "\n".join(f"  {line}" for line in body.splitlines()) if body else "  (clean)"
 
 

Here is the caller graph for this function:

◆ family_source_specs()

list[tuple[str, str, str]] review_packet.family_source_specs ( dict family )

Resolve a capability family's declared source paths and symbols.

Parameters

[in] family Capability family record.

Returns: Tuples of path, symbol, and source kind.

Definition at line 294 of file review_packet.py.

def family_source_specs(family: dict) -> list[tuple[str, str, str]]:
    """!
    @brief Resolve a capability family's declared source paths and symbols.
    @param[in] family Capability family record.
    @return Tuples of path, symbol, and source kind.
    """
 
    specs: list[tuple[str, str, str]] = []
    surface = family.get("public_surface", {})
    if surface.get("module") and surface.get("symbol"):
        specs.append((module_path(surface["module"]), surface["symbol"], surface.get("kind", "public")))
    for parity in family.get("parity_sources", []):
        symbol = parity.get("function") or parity.get("symbol") or parity.get("prefix")
        if parity.get("path") and symbol:
            specs.append((parity["path"], symbol, parity.get("kind", "parity")))
    return specs
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ symbols_for()

list[str] review_packet.symbols_for ( dict family )

Named symbols a capability family depends on, rather than whole files.

Parameters

[in] family Family record.

Returns: Symbol descriptions.

Definition at line 312 of file review_packet.py.

def symbols_for(family: dict) -> list[str]:
    """!
    @brief Named symbols a capability family depends on, rather than whole files.
    @param[in] family Family record.
    @return Symbol descriptions.
    """
 
    return [f"{path}::{symbol} ({kind})" for path, symbol, kind in family_source_specs(family)]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ evidence_sources()

list[str] review_packet.evidence_sources ( dict family )

Declared evidence sources across a family's values.

Parameters

[in] family Family record.

Returns: Sorted source identifiers.

Definition at line 322 of file review_packet.py.

def evidence_sources(family: dict) -> list[str]:
    """!
    @brief Declared evidence sources across a family's values.
    @param[in] family Family record.
    @return Sorted source identifiers.
    """
 
    sources: set[str] = set()
    for metadata in family.get("value_metadata", {}).values():
        for facet_sources in (metadata.get("evidence") or {}).values():
            sources.update(facet_sources)
    return sorted(sources)
 
 

Here is the caller graph for this function:

◆ recorded_measurements()

list review_packet.recorded_measurements ( list[str] sources )

Measurement records cited by declared evidence sources.

Parameters

[in] sources Declared evidence source identifiers.

Returns: Matching measurement records, in citation order.

Definition at line 336 of file review_packet.py.

def recorded_measurements(sources: list[str]) -> list:
    """!
    @brief Measurement records cited by declared evidence sources.
    @param[in] sources Declared evidence source identifiers.
    @return Matching measurement records, in citation order.
    """
 
    wanted = [s.split(":", 1)[1] for s in sources if s.startswith("measurement:")]
    if not wanted or not MEASUREMENTS.is_file():
        return []
    by_id = {r.get("id"): r for r in
             json.loads(MEASUREMENTS.read_text(encoding="utf-8")).get("records", [])}
    return [by_id[i] for i in wanted if i in by_id]
 
 

Here is the caller graph for this function:

◆ make_targets()

list[str] review_packet.make_targets ( list[str] sources )

Make targets named by declared evidence sources.

Parameters

[in] sources Source identifiers.

Returns: Verification commands.

Definition at line 351 of file review_packet.py.

def make_targets(sources: list[str]) -> list[str]:
    """!
    @brief Make targets named by declared evidence sources.
    @param[in] sources Source identifiers.
    @return Verification commands.
    """
 
    return [f"make {source.split(':', 1)[1]}" for source in sources if source.startswith("make:")]
 
 

Here is the caller graph for this function:

◆ route_status()

int review_packet.route_status	(	list[str]	unresolved,
		bool	unavailable = `False`
	)

Print the fixed route state and any unresolved declarations.

Parameters

[in]	unresolved	Problems found while joining declared registry data.
[in]	unavailable	Whether required environmental metadata is unavailable.

Returns: Route exit status.

Definition at line 361 of file review_packet.py.

def route_status(unresolved: list[str], unavailable: bool = False) -> int:
    """!
    @brief Print the fixed route state and any unresolved declarations.
    @param[in] unresolved Problems found while joining declared registry data.
    @param[in] unavailable Whether required environmental metadata is unavailable.
    @return Route exit status.
    """
 
    if unavailable:
        print(UNAVAILABLE)
        for problem in unresolved:
            print(f"  {problem}")
        return 3
    if unresolved:
        print(INCOMPLETE)
        for problem in unresolved:
            print(f"  {problem}")
        return 3
    print(COMPLETE)
    return 0
 
 

Here is the caller graph for this function:

◆ unknown_identifier()

int review_packet.unknown_identifier	(	str	kind,
		str	identifier,
		list[str]	known
	)

Report an invalid registry identifier with close matches and known ids.

Parameters

[in]	kind	Identifier category.
[in]	identifier	Unknown value.
[in]	known	Valid values.

Returns: Invalid-argument status.

Definition at line 383 of file review_packet.py.

def unknown_identifier(kind: str, identifier: str, known: list[str]) -> int:
    """!
    @brief Report an invalid registry identifier with close matches and known ids.
    @param[in] kind Identifier category.
    @param[in] identifier Unknown value.
    @param[in] known Valid values.
    @return Invalid-argument status.
    """
 
    print(f"ROUTE: invalid — unknown {kind} '{identifier}'.", file=sys.stderr)
    close = difflib.get_close_matches(identifier, known, n=5)
    if close:
        print(f"Close matches: {', '.join(close)}", file=sys.stderr)
    print("Known ids:", file=sys.stderr)
    for value in known:
        print(f"  {value}", file=sys.stderr)
    return 2
 
 

Here is the caller graph for this function:

◆ print_freshness()

None review_packet.print_freshness	(	list[tuple[str, dict]]	surfaces,
		str	heading
	)

Print freshness routing with current attestation state.

Parameters

[in]	surfaces	Role and surface pairs.
[in]	heading	Section heading.

Returns: None.

Definition at line 402 of file review_packet.py.

def print_freshness(surfaces: list[tuple[str, dict]], heading: str) -> None:
    """!
    @brief Print freshness routing with current attestation state.
    @param[in] surfaces Role and surface pairs.
    @param[in] heading Section heading.
    @return None.
    """
 
    print(heading)
    for role, surface in surfaces:
        blocking = surface.get("enforcement") or ("blocking" if surface["tier"] == "hard" else "report")
        state = freshness_state(surface)
        print(f"  [{surface['tier']}/{blocking}] {surface['id']} ({role}) - {state}")
        for path in freshness_paths(surface):
            print(f"      {path}")
        if state != "current":
            print(f"      after review: make attest-freshness ARGS=\"{surface['id']}\"")
    if not surfaces:
        print("  (none - no declared freshness surface routes here)")
    print("")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_xref()

tuple[str, dict | None] review_packet.load_xref ( )

Load the optional cross-reference index only when its dirty-byte stamp is current.

Returns: State (current, missing, or stale) and current index when available.

Definition at line 424 of file review_packet.py.

def load_xref() -> tuple[str, dict | None]:
    """!
    @brief Load the optional cross-reference index only when its dirty-byte stamp is current.
    @return State (`current`, `missing`, or `stale`) and current index when available.
    """
 
    if not XREF.is_file():
        return "missing", None
    try:
        index = json.loads(XREF.read_text(encoding="utf-8"))
        current_sources = xref_source_files(REPO_ROOT)
        current_digest = xref_digest_files(REPO_ROOT, current_sources)
        doxyfile_digest = xref_file_digest(REPO_ROOT / "docs" / "Doxyfile")
    except (OSError, ValueError, KeyError, TypeError):
        return "stale", None
    if (
        index.get("schema_version") != XREF_SCHEMA_VERSION
        or index.get("source_digest") != current_digest
        or index.get("source_files") != [path.as_posix() for path in current_sources]
        or index.get("doxyfile_digest") != doxyfile_digest
        or not isinstance(index.get("symbols"), dict)
    ):
        return "stale", None
    return "current", index
 
 

Here is the caller graph for this function:

◆ xref_matches()

list[str] review_packet.xref_matches	(	dict	index,
		str	path,
		str	symbol
	)

Match a declared path and symbol to Doxygen member identifiers.

Parameters

[in]	index	Current cross-reference index.
[in]	path	Expected definition path, or an empty string.
[in]	symbol	Expected unqualified or qualified symbol.

Returns: Matching member ids.

Definition at line 450 of file review_packet.py.

def xref_matches(index: dict, path: str, symbol: str) -> list[str]:
    """!
    @brief Match a declared path and symbol to Doxygen member identifiers.
    @param[in] index Current cross-reference index.
    @param[in] path Expected definition path, or an empty string.
    @param[in] symbol Expected unqualified or qualified symbol.
    @return Matching member ids.
    """
 
    matches: list[str] = []
    for refid, record in index["symbols"].items():
        name_match = record.get("name") == symbol or record.get("qualified_name") == symbol
        name_match = name_match or str(record.get("qualified_name", "")).endswith(f"::{symbol}")
        name_match = name_match or str(record.get("qualified_name", "")).endswith(f".{symbol}")
        path_match = not path or record.get("definition", {}).get("path") == path
        if name_match and path_match:
            matches.append(refid)
    return sorted(matches)
 
 

Here is the caller graph for this function:

◆ format_xref_node()

str review_packet.format_xref_node	(	dict	index,
		str	refid
	)

Format one indexed symbol with its definition location.

Parameters

[in]	index	Current cross-reference index.
[in]	refid	Doxygen member id.

Returns: Compact symbol and source location.

Definition at line 470 of file review_packet.py.

def format_xref_node(index: dict, refid: str) -> str:
    """!
    @brief Format one indexed symbol with its definition location.
    @param[in] index Current cross-reference index.
    @param[in] refid Doxygen member id.
    @return Compact symbol and source location.
    """
 
    record = index["symbols"].get(refid, {})
    location = record.get("definition", {})
    line = f":{location.get('line')}" if location.get("line") else ""
    return f"{record.get('qualified_name', record.get('name', refid))} ({location.get('path', '?')}{line})"
 
 

Here is the caller graph for this function:

◆ print_measurements()

None review_packet.print_measurements ( list records )

Print the measurements already recorded against this route.

Parameters

[in] records Measurement records to render.

Returns: None.

Definition at line 484 of file review_packet.py.

def print_measurements(records: list) -> None:
    """!
    @brief Print the measurements already recorded against this route.
    @param[in] records Measurement records to render.
    @return None.
    """
 
    if not records:
        return
    print("MEASUREMENTS ALREADY RECORDED (read before running anything expensive)")
    for record in records:
        result = record.get("result") or {}
        verdict = result.get("verdict", "?") if isinstance(result, dict) else "?"
        print(f"  [{verdict}] {record.get('id')} - {record.get('question')}")
        print(f"      taken {record.get('date')} at {record.get('commit')} on {record.get('environment')}")
        print(f"      does not establish: {record.get('limitations')}")
    print("")
 
 

Here is the caller graph for this function:

◆ print_xref()

None review_packet.print_xref	(	list[tuple[str, str, str]]	specs,
		list[str] \| None	paths = `None`
	)

Print bounded direct and two-hop Doxygen reference evidence for a route.

Parameters

[in]	specs	Declared source path, symbol, and kind tuples.
[in]	paths	Optional paths whose connected definitions should seed the view.

Returns: None.

Definition at line 503 of file review_packet.py.

def print_xref(specs: list[tuple[str, str, str]], paths: list[str] | None = None) -> None:
    """!
    @brief Print bounded direct and two-hop Doxygen reference evidence for a route.
    @param[in] specs Declared source path, symbol, and kind tuples.
    @param[in] paths Optional paths whose connected definitions should seed the view.
    @return None.
    """
 
    print("OPTIONAL SOURCE CROSS-REFERENCES")
    state, index = load_xref()
    if state == "missing":
        print("XREF: not built (optional)")
        print("  Registry routing below is unaffected.")
        print("  Run `make docs-xref` to add bounded source-reference evidence.")
        print(f"  {XREF_CAVEAT}\n")
        return
    if state == "stale" or index is None:
        print("XREF: stale — run make docs-xref")
        print("  Stale edges are not displayed; registry routing remains available.")
        print(f"  {XREF_CAVEAT}\n")
        return
 
    print("XREF: current")
    print(f"  {XREF_CAVEAT}")
    selected: list[tuple[str, str]] = []
    for path, symbol, _ in specs:
        for refid in xref_matches(index, path, symbol):
            selected.append((f"{path}::{symbol}", refid))
    if paths:
        path_set = set(paths)
        connected = [
            (f"definitions in {record.get('definition', {}).get('path')}", refid)
            for refid, record in index["symbols"].items()
            if record.get("definition", {}).get("path") in path_set
            and (record.get("incoming") or record.get("outgoing"))
        ]
        selected.extend(sorted(connected, key=lambda item: format_xref_node(index, item[1]))[:8])
 
    seen: set[str] = set()
    bounded = []
    for label, refid in selected:
        if refid not in seen:
            seen.add(refid)
            bounded.append((label, refid))
    if not bounded:
        print("  (no indexed definition matched the declared symbols or paths)\n")
        return
    for label, refid in bounded[:8]:
        record = index["symbols"].get(refid, {})
        print(f"  {label}")
        print(f"    definition: {format_xref_node(index, refid)}")
        incoming = [edge for edge in record.get("incoming", []) if edge in index["symbols"]]
        outgoing = [edge for edge in record.get("outgoing", []) if edge in index["symbols"]]
        for edge in incoming[:4]:
            print(f"    direct caller: {format_xref_node(index, edge)}")
        for edge in outgoing[:4]:
            print(f"    direct reference: {format_xref_node(index, edge)}")
        second_in = sorted(
            {
                second
                for edge in incoming[:8]
                for second in index["symbols"].get(edge, {}).get("incoming", [])
                if second in index["symbols"] and second != refid
            }
        )
        second_out = sorted(
            {
                second
                for edge in outgoing[:8]
                for second in index["symbols"].get(edge, {}).get("outgoing", [])
                if second in index["symbols"] and second != refid
            }
        )
        for edge in second_in[:3]:
            print(f"    two-hop caller: {format_xref_node(index, edge)}")
        for edge in second_out[:3]:
            print(f"    two-hop reference: {format_xref_node(index, edge)}")
        if len(incoming) > 4 or len(outgoing) > 4 or len(second_in) > 3 or len(second_out) > 3:
            print("    (additional edges omitted; inspect docs_build/xref.json for this symbol)")
    print("")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ contract_mode()

int review_packet.contract_mode ( str contract_id )

Print a review packet for one invariant contract.

Parameters

[in] contract_id Contract identifier.

Returns: Process status code.

Definition at line 585 of file review_packet.py.

def contract_mode(contract_id: str) -> int:
    """!
    @brief Print a review packet for one invariant contract.
    @param[in] contract_id Contract identifier.
    @return Process status code.
    """
 
    known = {contract["id"]: contract for contract in records(CONTRACTS, "contracts")}
    contract = known.get(contract_id)
    if not contract:
        return unknown_identifier("contract", contract_id, sorted(known))
    sources = [source_path(source) for source in contract.get("authoritative_sources", [])]
    pages = [
        canonical_page(page)
        for page in contract.get("canonical_documentation", []) + contract.get("dependent_pages", [])
    ]
    unresolved = [f"missing source {path}" for path in sources if not (REPO_ROOT / path).exists()]
    unresolved.extend(
        f"missing page docs/pages/{page}.md" for page in pages if not (PAGES_DIR / f"{page}.md").is_file()
    )
 
    print(f"REVIEW PACKET: contract {contract['id']}")
    status = route_status(unresolved)
    print(f"  {contract['title']}  [{contract['status']} / {contract['enforcement']}]\n")
    if contract.get("note"):
        print("SCOPE")
        print(f"  {contract['note']}\n")
    print("AUTHORITATIVE SOURCES")
    for source in contract.get("authoritative_sources", []) or ["(none)"]:
        print(f"  {source}")
    print("\nCANONICAL DOCUMENTATION (owns the narrative)")
    for page in contract.get("canonical_documentation", []) or ["(none)"]:
        print(f"  docs/pages/{page}.md")
    print("\nDEPENDENT PAGES (review if this contract changes)")
    for page in contract.get("dependent_pages", []) or ["(none)"]:
        print(f"  docs/pages/{page}.md")
    print("")
 
    if contract["id"].startswith("run.artifact"):
        topology = json.loads((TOOLING_DIR / "artifact_topology.json").read_text(encoding="utf-8"))
        print("LOGICAL IDENTITIES")
        for artifact in topology["artifacts"]:
            print(f"  {artifact['id']:26} {artifact['path_rule']}")
        for entry in topology.get("resolved_safety_history", {}).get("entries", []):
            print(f"\n  RESOLVED SAFETY DEFECT: {entry['id']} ({entry['severity']}) - {entry['state']}")
            print(f"      residual risk: {entry['resolution']['residual_risk'][:120]}")
        print("")
 
    scoped = []
    for surface in records(FRESHNESS, "surfaces"):
        if set(surface.get("owning_pages", [])) & set(contract.get("canonical_documentation", [])):
            scoped.append(("owns", surface))
    if scoped:
        print_freshness(scoped, "FRESHNESS SURFACES ON THIS CONTRACT'S PAGES")
    print_xref([], sources)
    print("VERIFY WITH")
    checker = contract.get("checker")
    print(f"  python3 {' '.join(checker)}" if checker else "  (no automated checker - human review)")
    print("  make audit-contracts\n")
    print("UNCOMMITTED CHANGES TO DECLARED SOURCES")
    print(uncommitted(sources))
    print("\nRECENT HISTORY")
    print(git_log(sources))
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ capability_mode()

int review_packet.capability_mode ( str capability_id )

Join one capability family across symbols, pages, contracts, evidence, and subsystems.

Parameters

[in] capability_id Capability family id.

Returns: Process status code.

Definition at line 651 of file review_packet.py.

def capability_mode(capability_id: str) -> int:
    """!
    @brief Join one capability family across symbols, pages, contracts, evidence, and subsystems.
    @param[in] capability_id Capability family id.
    @return Process status code.
    """
 
    known = {family["id"]: family for family in records(FAMILIES, "families")}
    family = known.get(capability_id)
    if not family:
        return unknown_identifier("capability", capability_id, sorted(known))
    specs = family_source_specs(family)
    page = family["family_page"]
    unresolved = [
        f"missing declared source {path}" for path, _, _ in specs
        if not (REPO_ROOT / path).exists()
    ]
    if not specs:
        unresolved.append("no public or parity source symbol is declared")
    if not (PAGES_DIR / f"{page}.md").is_file():
        unresolved.append(f"missing family page docs/pages/{page}.md")
    related_contracts = contracts_for(page)
    related_subsystems = [
        subsystem
        for subsystem in records(SUBSYSTEMS, "subsystems")
        if capability_id in subsystem.get("capability_families", [])
    ]
    evidence = evidence_sources(family)
 
    print(f"REVIEW PACKET: capability {capability_id}")
    status = route_status(unresolved)
    mode = "enforced" if family.get("coverage_enforced") else "advisory"
    print(f"  {family['title']} [{mode}; {len(family.get('value_metadata', {}))} values]")
    print(f"  selector: {family.get('selector', '(not declared)')}\n")
    print("SOURCE SYMBOLS")
    for symbol in symbols_for(family) or ["(none declared)"]:
        print(f"  {symbol}")
    print("\nFAMILY DOCUMENTATION")
    print(f"  docs/pages/{page}.md")
    print("\nINVARIANT CONTRACTS ON THAT PAGE")
    for contract in related_contracts or [None]:
        print(f"  [{contract['status']}] {contract['id']}" if contract else "  (none)")
    print("\nSUBSYSTEMS USING THIS FAMILY")
    for subsystem in related_subsystems or [None]:
        print(f"  [{subsystem['status']}] {subsystem['id']}" if subsystem else "  (none declared)")
    print("")
    print_freshness(freshness_for(page), "FRESHNESS SURFACES ROUTING TO THE FAMILY PAGE")
    print("DECLARED EVIDENCE SOURCES")
    for source in evidence or ["(none declared)"]:
        print(f"  {source}")
    print("")
    print_measurements(recorded_measurements(evidence))
    print_xref(specs)
    print("VERIFY WITH")
    for command in sorted(set(make_targets(evidence))):
        print(f"  {command}")
    print("  make audit-capability")
    print(f"  make review-packet PAGE={page}")
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ subsystem_mode()

int review_packet.subsystem_mode ( str subsystem_id )

Join one subsystem across capability families, obligation pages, contracts, and evidence.

Parameters

[in] subsystem_id Subsystem lifecycle id.

Returns: Process status code.

Definition at line 712 of file review_packet.py.

def subsystem_mode(subsystem_id: str) -> int:
    """!
    @brief Join one subsystem across capability families, obligation pages, contracts, and evidence.
    @param[in] subsystem_id Subsystem lifecycle id.
    @return Process status code.
    """
 
    known = {record["id"]: record for record in records(SUBSYSTEMS, "subsystems")}
    subsystem = known.get(subsystem_id)
    if not subsystem:
        return unknown_identifier("subsystem", subsystem_id, sorted(known))
    family_map = {family["id"]: family for family in records(FAMILIES, "families")}
    family_ids = subsystem.get("capability_families", [])
    pages = record_pages(subsystem)
    unresolved = [f"unknown capability family {family_id}" for family_id in family_ids if family_id not in family_map]
    unresolved.extend(f"missing page docs/pages/{page}.md" for page in pages if not (PAGES_DIR / f"{page}.md").is_file())
    families = [family_map[family_id] for family_id in family_ids if family_id in family_map]
    specs = [spec for family in families for spec in family_source_specs(family)]
    surfaces = [
        ("routes subsystem page", surface)
        for surface in records(FRESHNESS, "surfaces")
        if set(surface.get("owning_pages", []) + surface.get("dependent_pages", [])) & pages
    ]
    related_contracts = [
        contract
        for contract in records(CONTRACTS, "contracts")
        if set(contract.get("canonical_documentation", []) + contract.get("dependent_pages", [])) & pages
    ]
    evidence = sorted({source for family in families for source in evidence_sources(family)})
 
    print(f"REVIEW PACKET: subsystem {subsystem_id}")
    status = route_status(unresolved)
    print(f"  {subsystem['title']} [{subsystem['status']} / {subsystem.get('visibility', '?')}]\n")
    print("CAPABILITY FAMILIES")
    for family in families or [None]:
        print(f"  {family['id']} -> docs/pages/{family['family_page']}.md" if family else "  (none declared)")
    print("\nOBLIGATION AND CONCERN PAGES")
    for page in sorted(pages) or ["(none declared)"]:
        print(f"  docs/pages/{page}.md")
    print("\nINVARIANT CONTRACTS ON THOSE PAGES")
    for contract in related_contracts or [None]:
        print(f"  [{contract['status']}] {contract['id']}" if contract else "  (none)")
    print("")
    print_freshness(surfaces, "FRESHNESS SURFACES ROUTING TO THOSE PAGES")
    print("DECLARED EVIDENCE AND TEST TARGETS")
    for source in evidence or ["(none declared through capability families)"]:
        print(f"  {source}")
    print("")
    print_xref(specs, [path for _, surface in surfaces for path in freshness_paths(surface)])
    print("VERIFY WITH")
    for command in sorted(set(make_targets(evidence))):
        print(f"  {command}")
    print("  make audit-subsystems")
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ surface_mode()

int review_packet.surface_mode ( str surface_id )

Join one freshness surface across watched paths, pages, contracts, families, and subsystems.

Parameters

[in] surface_id Freshness surface id.

Returns: Process status code.

Definition at line 768 of file review_packet.py.

def surface_mode(surface_id: str) -> int:
    """!
    @brief Join one freshness surface across watched paths, pages, contracts, families, and subsystems.
    @param[in] surface_id Freshness surface id.
    @return Process status code.
    """
 
    known = {surface["id"]: surface for surface in records(FRESHNESS, "surfaces")}
    surface = known.get(surface_id)
    if not surface:
        return unknown_identifier("surface", surface_id, sorted(known))
    paths = freshness_paths(surface)
    pages = {
        canonical_page(page)
        for page in surface.get("owning_pages", []) + surface.get("dependent_pages", [])
    }
    unresolved = [
        f"missing watched path {path}" for path in paths
        if not (REPO_ROOT / path).exists()
    ]
    unresolved.extend(f"missing page docs/pages/{page}.md" for page in pages if not (PAGES_DIR / f"{page}.md").is_file())
    families = [family for family in records(FAMILIES, "families") if family["family_page"] in pages]
    related_contracts = [
        contract
        for contract in records(CONTRACTS, "contracts")
        if set(contract.get("canonical_documentation", []) + contract.get("dependent_pages", [])) & pages
    ]
    subsystems = subsystems_for_pages(pages)
    specs = [spec for family in families for spec in family_source_specs(family)]
 
    print(f"REVIEW PACKET: surface {surface_id}")
    status = route_status(unresolved)
    print(f"  {surface['title']} [{surface['tier']}] - {freshness_state(surface)}\n")
    print("WATCHED PATHS")
    for path in paths or ["(none declared)"]:
        print(f"  {path}")
    print("\nOWNING AND DEPENDENT PAGES")
    for page in sorted(pages) or ["(none declared)"]:
        role = "owns" if page in surface.get("owning_pages", []) else "depends on"
        print(f"  {role}: docs/pages/{page}.md")
    print("\nINVARIANT CONTRACTS")
    for contract in related_contracts or [None]:
        print(f"  [{contract['status']}] {contract['id']}" if contract else "  (none)")
    print("\nCAPABILITY FAMILIES")
    for family in families or [None]:
        print(f"  {family['id']}" if family else "  (none routed through these pages)")
    print("\nSUBSYSTEMS")
    for subsystem in subsystems or [None]:
        print(f"  [{subsystem['status']}] {subsystem['id']}" if subsystem else "  (none routed through these pages)")
    print("")
    print_xref(specs, paths)
    print("VERIFY WITH")
    print(f"  make review-packet PAGE={next(iter(sorted(pages)), '<page>')}")
    print(f"  make attest-freshness ARGS=\"{surface_id}\"  # only after source comparison")
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ changed_paths()

tuple[dict[str, set[str]], bool] review_packet.changed_paths ( )

Collect staged, unstaged, and untracked nonignored paths from Git.

Returns: Path-to-state mapping and whether Git metadata was available.

Definition at line 825 of file review_packet.py.

def changed_paths() -> tuple[dict[str, set[str]], bool]:
    """!
    @brief Collect staged, unstaged, and untracked nonignored paths from Git.
    @return Path-to-state mapping and whether Git metadata was available.
    """
 
    probe = subprocess.run(
        ["git", "-C", str(REPO_ROOT), "rev-parse", "--is-inside-work-tree"],
        capture_output=True,
        text=True,
        check=False,
    )
    if probe.returncode != 0:
        return {}, False
    commands = {
        "staged": ["git", "-C", str(REPO_ROOT), "diff", "--cached", "--name-only", "-z"],
        "unstaged": ["git", "-C", str(REPO_ROOT), "diff", "--name-only", "-z"],
        "untracked": ["git", "-C", str(REPO_ROOT), "ls-files", "--others", "--exclude-standard", "-z"],
    }
    found: dict[str, set[str]] = {}
    for state, command in commands.items():
        completed = subprocess.run(command, capture_output=True, check=False)
        if completed.returncode != 0:
            return {}, False
        for raw in completed.stdout.split(b"\0"):
            if raw:
                found.setdefault(raw.decode("utf-8", errors="replace"), set()).add(state)
    return found, True
 
 

Here is the caller graph for this function:

◆ classify_path()

str review_packet.classify_path ( str path )

Classify a changed path for routing coverage.

Parameters

[in] path Repository-relative changed path.

Returns: Category label excluding routed versus unrouted production state.

Definition at line 855 of file review_packet.py.

def classify_path(path: str) -> str:
    """!
    @brief Classify a changed path for routing coverage.
    @param[in] path Repository-relative changed path.
    @return Category label excluding routed versus unrouted production state.
    """
 
    candidate = Path(path)
    if path.startswith("docs/generated/") or path.startswith("docs_build/"):
        return "generated"
    if (
        (candidate.parts and candidate.parts[0] == "src" and candidate.suffix in {".c", ".h"})
        or (candidate.parts and candidate.parts[0] == "include" and candidate.suffix in {".h", ".hpp"})
        or (candidate.parts and candidate.parts[0] == "picurv_cli" and candidate.suffix == ".py")
    ):
        return "production"
    routed_roots = {"docs", "config", "tests", ".github", ".agents", ".claude", "examples"}
    routed_files = {"AGENTS.md", "CLAUDE.md", "CONTRIBUTING.md", "README.md", "Makefile", ".gitignore"}
    if (candidate.parts and candidate.parts[0] in routed_roots) or path in routed_files:
        return "documentation/configuration/test/tooling"
    return "ignored/out of scope"
 
 

Here is the caller graph for this function:

◆ routes_for_path()

dict[str, list[str]] review_packet.routes_for_path ( str path )

Find declared capabilities, surfaces, contracts, and subsystems touching a path.

Parameters

[in] path Repository-relative production path.

Returns: Nonempty routing categories and sorted identifiers.

Definition at line 878 of file review_packet.py.

def routes_for_path(path: str) -> dict[str, list[str]]:
    """!
    @brief Find declared capabilities, surfaces, contracts, and subsystems touching a path.
    @param[in] path Repository-relative production path.
    @return Nonempty routing categories and sorted identifiers.
    """
 
    family_hits = [
        family["id"]
        for family in records(FAMILIES, "families")
        if path in {spec[0] for spec in family_source_specs(family)}
    ]
    surface_hits = [
        surface["id"] for surface in records(FRESHNESS, "surfaces") if path in freshness_paths(surface)
    ]
    contract_hits = [
        contract["id"]
        for contract in records(CONTRACTS, "contracts")
        if path in {source_path(source) for source in contract.get("authoritative_sources", [])}
    ]
    pages: set[str] = set()
    for family in records(FAMILIES, "families"):
        if family["id"] in family_hits:
            pages.add(family["family_page"])
    for surface in records(FRESHNESS, "surfaces"):
        if surface["id"] in surface_hits:
            pages.update(surface.get("owning_pages", []) + surface.get("dependent_pages", []))
    for contract in records(CONTRACTS, "contracts"):
        if contract["id"] in contract_hits:
            pages.update(contract.get("canonical_documentation", []) + contract.get("dependent_pages", []))
    subsystem_hits = [record["id"] for record in subsystems_for_pages(pages)]
    routes = {
        "capability": sorted(family_hits),
        "surface": sorted(surface_hits),
        "contract": sorted(contract_hits),
        "subsystem": sorted(subsystem_hits),
    }
    return {kind: values for kind, values in routes.items() if values}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ guide_fallback()

str review_packet.guide_fallback ( str path )

Return the nearest existing directory guide for an unrouted production path.

Parameters

[in] path Repository-relative path.

Returns: Guide path or root instruction fallback.

Definition at line 918 of file review_packet.py.

def guide_fallback(path: str) -> str:
    """!
    @brief Return the nearest existing directory guide for an unrouted production path.
    @param[in] path Repository-relative path.
    @return Guide path or root instruction fallback.
    """
 
    current = (REPO_ROOT / path).parent
    while current != REPO_ROOT and REPO_ROOT in current.parents:
        guide = current / "guide.md"
        if guide.is_file():
            return guide.relative_to(REPO_ROOT).as_posix()
        current = current.parent
    return "AGENTS.md"
 
 

Here is the caller graph for this function:

◆ changed_mode()

int review_packet.changed_mode ( str value )

Report declared routing coverage for current working-tree changes.

Parameters

[in] value Supported selector, currently working-tree.

Returns: Process status code.

Definition at line 934 of file review_packet.py.

def changed_mode(value: str) -> int:
    """!
    @brief Report declared routing coverage for current working-tree changes.
    @param[in] value Supported selector, currently `working-tree`.
    @return Process status code.
    """
 
    if value != "working-tree":
        return unknown_identifier("changed-set", value, ["working-tree"])
    paths, available = changed_paths()
    routed: dict[str, dict[str, list[str]]] = {}
    unrouted: list[str] = []
    categories: dict[str, str] = {}
    for path in sorted(paths):
        category = classify_path(path)
        if category == "production":
            declared = routes_for_path(path)
            if declared:
                category = "routed production"
                routed[path] = declared
            else:
                category = "unrouted production"
                unrouted.append(path)
        categories[path] = category
 
    print("REVIEW PACKET: changed working-tree")
    problems = [f"unrouted production path: {path}" for path in unrouted]
    status = route_status(problems if available else ["Git working-tree metadata is unavailable"], not available)
    print("  Coverage is advisory and covers staged, unstaged, and untracked nonignored paths.")
    print("  Ignored files are intentionally excluded by Git.\n")
    if not paths and available:
        print("CHANGED PATHS\n  (working tree clean)")
        return status
    print("CHANGED PATHS")
    for path in sorted(paths):
        states = ", ".join(sorted(paths[path]))
        print(f"  [{categories[path]}] {path} ({states})")
        for kind, identifiers in routed.get(path, {}).items():
            print(f"      {kind}: {', '.join(identifiers)}")
        if categories[path] == "unrouted production":
            guide = guide_fallback(path)
            root = Path(path).parts[0]
            print(f"      fallback guide: {guide}")
            print(f"      targeted search: rg -n \"<responsibility-or-symbol>\" {root}")
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ page_mode()

int review_packet.page_mode ( str page_name )

Print the original page-scoped review packet with explicit route status and xrefs.

Parameters

[in] page_name Page number, stem, or filename.

Returns: Process status code.

Definition at line 981 of file review_packet.py.

def page_mode(page_name: str) -> int:
    """!
    @brief Print the original page-scoped review packet with explicit route status and xrefs.
    @param[in] page_name Page number, stem, or filename.
    @return Process status code.
    """
 
    page = resolve_page(page_name)
    stem = page.stem
    page_contracts = contracts_for(stem)
    families = families_for(stem)
    scope_records = scope_records_for(stem)
    sources: list[str] = []
    specs: list[tuple[str, str, str]] = []
    evidence: list[str] = []
    for contract in page_contracts:
        sources.extend(source_path(source) for source in contract.get("authoritative_sources", []))
    for family in families:
        family_specs = family_source_specs(family)
        specs.extend(family_specs)
        sources.extend(path for path, _, _ in family_specs)
        evidence.extend(evidence_sources(family))
    sources = sorted(set(sources))
    evidence = sorted(set(evidence))
    unresolved = [f"missing declared source {source}" for source in sources if not (REPO_ROOT / source).exists()]
 
    print(f"REVIEW PACKET: {page.relative_to(REPO_ROOT)}")
    status = route_status(unresolved)
    print(f"  {len(page.read_text(encoding='utf-8').splitlines())} lines\n")
    print("SOURCE SYMBOLS (read these, not whole files)")
    for symbol in [f"{path}::{symbol} ({kind})" for path, symbol, kind in specs] or ["(none declared)"]:
        print(f"  {symbol}")
    print("\nAUTHORITATIVE FILES")
    for source in sources or ["(none declared)"]:
        print(f"  {source}")
    print("")
    if stem == "71_Invariant_Contracts":
        print("THIS PAGE DOCUMENTS THE WHOLE REGISTRY")
        for contract in sorted(records(CONTRACTS, "contracts"), key=lambda item: (item["status"], item["id"])):
            print(f"  [{contract['status']:8}] {contract['id']}")
        print("")
    print("INVARIANT CONTRACTS")
    for contract in page_contracts:
        role = "owns" if stem in contract.get("canonical_documentation", []) else "depends on"
        print(f"  [{contract['status']}] {contract['id']} ({role} this page)")
        print(f"      inspect: make review-packet CONTRACT={contract['id']}")
    if not page_contracts:
        print("  (none)")
    print("\nCAPABILITY FAMILIES ON THIS PAGE")
    for family in families:
        mode = "enforced" if family.get("coverage_enforced") else "advisory"
        print(f"  {family['id']} ({mode}) - {len(family.get('value_metadata', {}))} declared values")
    if not families:
        print("  (none)")
    print("")
    if evidence:
        print("DECLARED EVIDENCE SOURCES")
        for source in evidence:
            print(f"  {source}")
        print("")
    if scope_records:
        print("SCOPE RECORDS NAMING THIS PAGE")
        for record in scope_records:
            print(f"  [{record.get('status')}] {record['id']} ({record.get('publication_policy')})")
        print("")
    print_freshness(freshness_for(stem), "FRESHNESS SURFACES ROUTING REVIEW HERE")
    print_xref(specs, sources)
    print("UNCOMMITTED CHANGES TO DECLARED SOURCES")
    print(uncommitted(sources))
    print("\nRECENT HISTORY")
    print(git_log(sources))
    print("\nVERIFY WITH")
    for command in sorted(set(make_targets(evidence))):
        print(f"  {command}")
    print("  make audit-capability")
    print("  make audit-contracts")
    print("  make preview-docs")
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parse_args()

argparse.Namespace review_packet.parse_args ( list[str] argv )

Parse the mutually exclusive review-packet route selectors.

Parameters

[in] argv Arguments excluding the executable name.

Returns: Parsed command-line namespace.

Definition at line 1061 of file review_packet.py.

def parse_args(argv: list[str]) -> argparse.Namespace:
    """!
    @brief Parse the mutually exclusive review-packet route selectors.
    @param[in] argv Arguments excluding the executable name.
    @return Parsed command-line namespace.
    """
 
    parser = argparse.ArgumentParser(
        description="Assemble everything a reviewer needs for one declared PICurv route."
    )
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument("page", nargs="?", help="Page number, stem, or filename (for example 44).")
    group.add_argument("--contract", help="Invariant contract id.")
    group.add_argument("--capability", help="Capability family id.")
    group.add_argument("--subsystem", help="Subsystem lifecycle id.")
    group.add_argument("--surface", help="Freshness surface id.")
    group.add_argument("--changed", help="Changed-set selector; currently working-tree.")
    return parser.parse_args(argv)
 
 

Here is the caller graph for this function:

◆ main()

int review_packet.main ( list[str] | None argv = None )

Dispatch the requested bounded route and preserve differentiated exit states.

Parameters

[in] argv Optional arguments excluding the executable name.

Returns: Zero for complete, two for invalid, and three for incomplete or unavailable.

Definition at line 1081 of file review_packet.py.

def main(argv: list[str] | None = None) -> int:
    """!
    @brief Dispatch the requested bounded route and preserve differentiated exit states.
    @param[in] argv Optional arguments excluding the executable name.
    @return Zero for complete, two for invalid, and three for incomplete or unavailable.
    """
 
    args = parse_args(sys.argv[1:] if argv is None else argv)
    if args.contract:
        return contract_mode(args.contract)
    if args.capability:
        return capability_mode(args.capability)
    if args.subsystem:
        return subsystem_mode(args.subsystem)
    if args.surface:
        return surface_mode(args.surface)
    if args.changed:
        return changed_mode(args.changed)
    return page_mode(args.page)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ REPO_ROOT

review_packet.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 17 of file review_packet.py.

◆ PAGES_DIR

str review_packet.PAGES_DIR = REPO_ROOT / "docs" / "pages"

Definition at line 18 of file review_packet.py.

◆ TOOLING_DIR

review_packet.TOOLING_DIR = Path(__file__).resolve().parent

Definition at line 19 of file review_packet.py.

◆ CONTRACTS

str review_packet.CONTRACTS = TOOLING_DIR / "contract_registry.json"

Definition at line 31 of file review_packet.py.

◆ FRESHNESS

str review_packet.FRESHNESS = TOOLING_DIR / "freshness_manifest.json"

Definition at line 32 of file review_packet.py.

◆ MEASUREMENTS

str review_packet.MEASUREMENTS = TOOLING_DIR / "measurement_records.json"

Definition at line 33 of file review_packet.py.

◆ FAMILIES

str review_packet.FAMILIES = TOOLING_DIR / "capability_families.json"

Definition at line 34 of file review_packet.py.

◆ SUBSYSTEMS

str review_packet.SUBSYSTEMS = TOOLING_DIR / "subsystem_records.json"

Definition at line 35 of file review_packet.py.

◆ SCOPE

str review_packet.SCOPE = TOOLING_DIR / "capability_scope_records.json"

Definition at line 36 of file review_packet.py.

◆ XREF

str review_packet.XREF = REPO_ROOT / "docs_build" / "xref.json"

Definition at line 37 of file review_packet.py.

◆ XREF_CAVEAT

tuple review_packet.XREF_CAVEAT

Initial value:

=  (
    "Doxygen provides source-reference edges, not a semantic call graph. Registry tables, "
    "callbacks, function pointers, macros, PETSc dispatch, and runtime-selected paths may "
    "require following intermediate symbols. No direct edge does not prove that a symbol is unused."
)

Definition at line 38 of file review_packet.py.

◆ COMPLETE

str review_packet.COMPLETE = "ROUTE: complete over declared registry data (not over code behavior)"

Definition at line 43 of file review_packet.py.

◆ INCOMPLETE

str review_packet.INCOMPLETE = "ROUTE: incomplete — declared identifier has unresolved routing"

Definition at line 44 of file review_packet.py.

◆ UNAVAILABLE

str review_packet.UNAVAILABLE = "ROUTE: unavailable — required environment or metadata is absent"

Definition at line 45 of file review_packet.py.

Functions

Variables

Detailed Description

Function Documentation

◆ records()

◆ resolve_page()

◆ source_path()

◆ module_path()

◆ page_aliases()

◆ canonical_page()

◆ git_log()

◆ contracts_for()

◆ families_for()

◆ record_pages()

◆ subsystems_for_pages()

◆ scope_records_for()

◆ freshness_for()

◆ freshness_paths()

◆ freshness_state()

◆ _freshness_digest()

◆ uncommitted()

◆ family_source_specs()

◆ symbols_for()

◆ evidence_sources()

◆ recorded_measurements()

◆ make_targets()

◆ route_status()

◆ unknown_identifier()

◆ print_freshness()

◆ load_xref()

◆ xref_matches()

◆ format_xref_node()

◆ print_measurements()

◆ print_xref()

◆ contract_mode()

◆ capability_mode()

◆ subsystem_mode()

◆ surface_mode()

◆ changed_paths()

◆ classify_path()

◆ routes_for_path()

◆ guide_fallback()

◆ changed_mode()

◆ page_mode()

◆ parse_args()

◆ main()

Variable Documentation

◆ REPO_ROOT

◆ PAGES_DIR

◆ TOOLING_DIR

◆ CONTRACTS

◆ FRESHNESS

◆ MEASUREMENTS

◆ FAMILIES

◆ SUBSYSTEMS

◆ SCOPE

◆ XREF

◆ XREF_CAVEAT

◆ COMPLETE

◆ INCOMPLETE

◆ UNAVAILABLE