frontmattering 0.4.2__py3-none-any.whl

frontmattering/resources/tools/kernel_reporting.py

@@ -0,0 +1,1495 @@
+"""Actionable report helpers for the Frontmattering frontmatter kernel."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from finding_registry import guidance_for
+from frontmattering.harness_errors import ConfigurationError, HarnessError, InternalBugError, ToolingError, ValidationFailure
+from frontmattering.core import split_frontmatter
+
+
+GUIDANCE: dict[str, tuple[str, str, str]] = {
+    "FRONTMATTERING-FM-FRONTMATTER-MISSING": (
+        "Markdown frontmatter is missing or unparseable",
+        "The kernel cannot build a canonical document model without a byte-zero YAML block.",
+        "Add exactly one YAML frontmatter block at the start of the file and make it parse.",
+    ),
+    "FRONTMATTERING-FM-SCHEMA-VERSION-UNSUPPORTED": (
+        "Unsupported Frontmattering frontmatter schema version",
+        "This kernel is intentionally not backward-compatible; it validates only v0.1.5.",
+        "Rewrite or migrate this document to ai_document_contract.schema_version: frontmattering_frontmatter/v0_1_5.",
+    ),
+    "FRONTMATTERING-FM-UNKNOWN-ROOT-BLOCK": (
+        "Unknown root frontmatter block",
+        "The closed root model forbids extra semantic blocks because they can launder authority.",
+        "Remove the block or model it through an approved v0.1.5 field/surface.",
+    ),
+    "FRONTMATTERING-FM-UNKNOWN-FIELD": (
+        "Unknown frontmatter field",
+        "Every canonical field must be declared in the v0.1.5 field catalog.",
+        "Remove the field or amend the spec/kernel before using it.",
+    ),
+    "FRONTMATTERING-FM-DOCUMENT-ID-DUPLICATE": (
+        "Duplicate document_id in one docset",
+        "Document identity must be unique for routing, relationships, and provenance.",
+        "Give each document a unique ai_document_contract.document_id.",
+    ),
+    "FRONTMATTERING-FM-RELATIONSHIP-TARGET-UNRESOLVED": (
+        "Relationship target does not resolve in the same document set",
+        "A same_document_set relationship cannot be followed by agents or validators.",
+        "Add the target document to the validated docset, correct target_document_id, or change resolution_scope.",
+    ),
+    "FRONTMATTERING-FM-RELATIONSHIP-TARGET-NOT-FOUND": (
+        "Required relationship target is missing",
+        "Required relationships are preconditions for safe document use.",
+        "Add the target document or make the relationship non-required only if the spec permits it.",
+    ),
+    "FRONTMATTERING-FM-TARGET-SECTION-NOT-FOUND": (
+        "Relationship target section does not exist",
+        "Section-targeted edges must point to exact headings in the target document.",
+        "Correct target_sections or add the exact heading to the target document.",
+    ),
+    "FRONTMATTERING-FM-LOAD-ORDER-INVERSION": (
+        "load_order contradicts an ordering dependency",
+        "A source document cannot load before a required ordering dependency it depends on.",
+        "Lower the target document load_order or raise the source document load_order.",
+    ),
+    "FRONTMATTERING-FM-INTENTION-OWNER-MULTIPLE": (
+        "Multiple documents own the same intention",
+        "A deepest intention has exactly one canonical owner.",
+        "Keep one ownership: owns document and change the others to binds_to, realizes, or references.",
+    ),
+    "FRONTMATTERING-FM-BINDING-DEPENDENCY-CYCLE": (
+        "Binding dependency cycle",
+        "Binding preconditions cannot be satisfied when required dependencies form a cycle.",
+        "Break the cycle by changing or removing one binding_precondition edge.",
+    ),
+}
+
+
+FINDING_PRIORITY = [
+    "FRONTMATTERING-FM-FRONTMATTER-MISSING",
+    "FRONTMATTERING-FM-YAML-DUPLICATE-KEY",
+    "FRONTMATTERING-FM-YAML-FORBIDDEN-FEATURE",
+    "FRONTMATTERING-FM-SCHEMA-VERSION-UNSUPPORTED",
+    "FRONTMATTERING-FM-UNKNOWN-ROOT-BLOCK",
+    "FRONTMATTERING-FM-UNKNOWN-FIELD",
+    "FRONTMATTERING-FM-DOCUMENT-ID-DUPLICATE",
+    "FRONTMATTERING-FM-INTENTION-OWNER-MULTIPLE",
+    "FRONTMATTERING-FM-RELATIONSHIP-TARGET-UNRESOLVED",
+    "FRONTMATTERING-FM-RELATIONSHIP-TARGET-NOT-FOUND",
+    "FRONTMATTERING-FM-TARGET-SECTION-NOT-FOUND",
+    "FRONTMATTERING-FM-LOAD-ORDER-INVERSION",
+]
+
+SUMMARY_ITEM_LIMIT = 5
+SUMMARY_READING_LIMIT = 12
+
+BRIEF_SECTION_ALIASES = {
+    "summary": "summary",
+    "blocks": "blocks",
+    "traps": "traps",
+    "limits": "limits",
+    "do-not": "do_not",
+    "do_not": "do_not",
+    "reading-order": "reading_order",
+    "reading_order": "reading_order",
+    "defects": "defects_by_class",
+    "defects-by-class": "defects_by_class",
+    "defects_by_class": "defects_by_class",
+    "trust": "trust",
+    "claim-boundary": "claim_boundary",
+    "claim_boundary": "claim_boundary",
+}
+
+
+def _priority(error_dict: dict[str, Any]) -> tuple[int, str]:
+    eid = str(error_dict.get("error_id") or "")
+    try:
+        return (FINDING_PRIORITY.index(eid), eid)
+    except ValueError:
+        return (len(FINDING_PRIORITY), eid)
+
+
+def _default_guidance(error_id: str) -> tuple[str, str, str]:
+    return (
+        f"Frontmatter validation finding {error_id}",
+        "The document set violates a v0.1.5 kernel predicate.",
+        "Inspect the finding context, then repair the named field, relationship, evidence, or document-set invariant.",
+    )
+
+
+def _field_path_from_detail(detail: Any) -> str | None:
+    text = str(detail or "")
+    match = re.match(r"([A-Za-z0-9_.\[\]]+)(?:=| not |$)", text)
+    if match and "." in match.group(1):
+        return match.group(1)
+    return None
+
+
+def _line_hint(source_path: str | None, detail: Any) -> dict[str, Any]:
+    if not source_path:
+        return {}
+    path = Path(source_path)
+    if not path.exists():
+        return {}
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return {}
+    detail_text = str(detail or "")
+    candidates: list[str] = []
+    field_path = _field_path_from_detail(detail)
+    if field_path:
+        leaf = field_path.split(".")[-1].replace("[]", "")
+        candidates.append(f"{leaf}:")
+        containers = field_path.split(".")[:-1]
+        for container in reversed(containers):
+            key = container.replace("[]", "")
+            if key:
+                candidates.append(f"{key}:")
+    if "->" in detail_text:
+        target = detail_text.split("->", 1)[1].split("#", 1)[0].split("(", 1)[0]
+        candidates.append(f"target_document_id: {target}")
+    if "#" in detail_text:
+        candidates.append(detail_text.rsplit("#", 1)[-1])
+    candidates.append(detail_text)
+    for needle in [c for c in candidates if c]:
+        for idx, line in enumerate(lines, 1):
+            if needle in line:
+                return {
+                    "line": idx,
+                    "line_text": line.strip(),
+                    "field_path": field_path,
+                }
+    return {"field_path": field_path} if field_path else {}
+
+
+def _document_id_for_source(result: dict[str, Any], source_path: str | None) -> str | None:
+    if not source_path:
+        return None
+    per_doc = (result.get("per_document") or {}).get(source_path) or {}
+    fm = per_doc.get("fm") or {}
+    adc = fm.get("ai_document_contract", {}) if isinstance(fm, dict) else {}
+    return adc.get("document_id")
+
+
+def finding_error(
+    error_id: str,
+    detail: Any,
+    *,
+    source_path: str | None,
+    spec_path: str,
+    spec_sha256: str,
+    field_path: str | None = None,
+    line: int | None = None,
+    line_text: str | None = None,
+    document_id: str | None = None,
+) -> ValidationFailure:
+    what, why, fix = guidance_for(error_id)
+    where = source_path or "docset"
+    if detail not in (None, ""):
+        where = f"{where}: {detail}"
+    source_hint = _line_hint(source_path, detail)
+    field_path = field_path or source_hint.get("field_path")
+    line = line or source_hint.get("line")
+    line_text = line_text or source_hint.get("line_text")
+    return ValidationFailure(
+        what=what,
+        where=where,
+        why=why,
+        fix=fix,
+        context={
+            "finding_id": error_id,
+            "detail": detail,
+            "source_path": source_path,
+            "document_id": document_id,
+            "field_path": field_path,
+            "line": line,
+            "line_text": line_text,
+            "spec_path": spec_path,
+            "spec_sha256": spec_sha256,
+        },
+        error_id=error_id,
+    )
+
+
+def fixture_error(
+    *,
+    kind: str,
+    fixture_class: str,
+    status: str,
+    expected: str,
+    observed: list[str],
+) -> HarnessError:
+    where = f"fixtures/{kind}/{fixture_class}"
+    context = {
+        "kind": kind,
+        "fixture_class": fixture_class,
+        "status": status,
+        "expected_finding": expected,
+        "observed_finding_ids": observed,
+    }
+    if status == "MISSING_FIXTURE":
+        return ConfigurationError(
+            what="Spec-declared fixture class is missing",
+            where=where,
+            why="Every spec-declared fixture class must have at least one Markdown fixture.",
+            fix="Create a fixture directory with one or more .md files for this class.",
+            context=context,
+            error_id="KERNEL-MISSING-FIXTURE",
+        )
+    if status == "WRONG_FINDING":
+        return ValidationFailure(
+            what="Invalid fixture produced the wrong finding",
+            where=where,
+            why="The fixture no longer proves the expected spec predicate.",
+            fix="Adjust the fixture mutation or validator so the expected finding is emitted for the right reason.",
+            context=context,
+            error_id="KERNEL-WRONG-FINDING",
+        )
+    if status == "NOT_REJECTED":
+        return ValidationFailure(
+            what="Invalid fixture was accepted",
+            where=where,
+            why="A declared invalid class must fail closed.",
+            fix="Add or repair the validator predicate for this class.",
+            context=context,
+            error_id="KERNEL-NOT-REJECTED",
+        )
+    if status == "REJECTED":
+        return ValidationFailure(
+            what="Valid fixture was rejected",
+            where=where,
+            why="A declared valid fixture must validate without findings.",
+            fix="Repair the fixture shape or correct an over-broad validator rule.",
+            context=context,
+            error_id="KERNEL-VALID-REJECTED",
+        )
+    return ToolingError(
+        what="Unknown kernel fixture status",
+        where=where,
+        why="The verifier produced a status outside the report vocabulary.",
+        fix="Fix verify_kernel.py status aggregation before trusting the report.",
+        context=context,
+        error_id="KERNEL-UNKNOWN-FIXTURE-STATUS",
+    )
+
+
+def source_for_finding(result: dict[str, Any], finding: tuple[str, Any]) -> str | None:
+    source_path = getattr(finding, "source_path", None)
+    if source_path:
+        return source_path
+    for path, per_doc in (result.get("per_document") or {}).items():
+        if finding in (per_doc.get("findings") or []):
+            return path
+    detail = str(finding[1])
+    if "->" in detail:
+        source_id = detail.split("->", 1)[0].split("(", 1)[0]
+        for path, per_doc in (result.get("per_document") or {}).items():
+            fm = per_doc.get("fm") or {}
+            adc = fm.get("ai_document_contract", {}) if isinstance(fm, dict) else {}
+            if adc.get("document_id") == source_id:
+                return path
+    return None
+
+
+def docset_mesh(result: dict[str, Any]) -> dict[str, Any]:
+    documents = []
+    relationships = []
+    unresolved_edges = []
+    task_catalog = _task_catalog(result.get("per_document") or {})
+    for path, per_doc in sorted((result.get("per_document") or {}).items()):
+        fm = per_doc.get("fm") or {}
+        if not isinstance(fm, dict):
+            continue
+        adc = fm.get("ai_document_contract", {})
+        routing = fm.get("routing", {})
+        intention = fm.get("deepest_intention", {})
+        doc_id = adc.get("document_id")
+        documents.append({
+            "path": path,
+            "document_id": doc_id,
+            "document_role": adc.get("document_role"),
+            "document_title": adc.get("document_title"),
+            "load_order": routing.get("load_order"),
+            "task_catalog": routing.get("task_catalog") or [],
+            "read_when_tags": routing.get("read_when_tags") or [],
+            "skip_when_tags": routing.get("skip_when_tags") or [],
+            "intention_id": intention.get("intention_id"),
+            "intention_ownership": intention.get("ownership"),
+        })
+        for index, rel in enumerate(fm.get("relationships") or []):
+            if not isinstance(rel, dict):
+                continue
+            edge = {
+                "source_document_id": doc_id,
+                "source_path": path,
+                "relationship_index": index,
+                "target_document_id": rel.get("target_document_id"),
+                "relationship_type": rel.get("relationship_type"),
+                "required": rel.get("required"),
+                "authority_effect": rel.get("authority_effect"),
+                "resolution_scope": rel.get("resolution_scope"),
+                "target_sections": rel.get("target_sections") or [],
+            }
+            relationships.append(edge)
+    ids = {d["document_id"] for d in documents}
+    for edge in relationships:
+        if edge["resolution_scope"] == "same_document_set" \
+                and edge["target_document_id"] not in ids:
+            unresolved_edges.append(edge)
+    return {
+        "document_count": len(documents),
+        "relationship_count": len(relationships),
+        "task_catalog": task_catalog,
+        "unresolved_same_set_edges": unresolved_edges,
+        "documents": documents,
+        "relationships": relationships,
+    }
+
+
+def _doc_frontmatter(per_doc: dict[str, Any]) -> dict[str, Any]:
+    fm = per_doc.get("fm") or {}
+    return fm if isinstance(fm, dict) else {}
+
+
+def _doc_identity(path: str, fm: dict[str, Any]) -> dict[str, Any]:
+    adc = fm.get("ai_document_contract", {})
+    routing = fm.get("routing", {})
+    return {
+        "document_id": adc.get("document_id"),
+        "document_role": adc.get("document_role"),
+        "document_title": adc.get("document_title"),
+        "load_order": routing.get("load_order"),
+        "task_catalog": routing.get("task_catalog") or [],
+        "read_when_tags": routing.get("read_when_tags") or [],
+        "skip_when_tags": routing.get("skip_when_tags") or [],
+        "path": path,
+    }
+
+
+def _reading_edges(documents: dict[str, dict[str, Any]]) -> list[tuple[str, str]]:
+    edges: list[tuple[str, str]] = []
+    ids = set(documents)
+    for source_id, doc in documents.items():
+        for rel in doc.get("relationships") or []:
+            if not isinstance(rel, dict):
+                continue
+            target_id = rel.get("target_document_id")
+            if target_id not in ids:
+                continue
+            rel_type = rel.get("relationship_type")
+            if rel_type == "handover_to":
+                edges.append((source_id, target_id))
+            elif rel.get("required") or rel_type in {"depends_on", "validates", "projects_to"}:
+                edges.append((target_id, source_id))
+    return edges
+
+
+def _topological_reading_order(documents: dict[str, dict[str, Any]]) -> list[str]:
+    order_key = lambda did: (
+        documents[did].get("routing", {}).get("load_order") or 999999,
+        documents[did].get("ai_document_contract", {}).get("document_id") or "",
+    )
+    outgoing = {did: [] for did in documents}
+    indegree = {did: 0 for did in documents}
+    for before, after in _reading_edges(documents):
+        if after not in outgoing[before]:
+            outgoing[before].append(after)
+            indegree[after] += 1
+    ready = sorted([did for did, count in indegree.items() if count == 0], key=order_key)
+    ordered: list[str] = []
+    while ready:
+        current = ready.pop(0)
+        ordered.append(current)
+        for nxt in sorted(outgoing[current], key=order_key):
+            indegree[nxt] -= 1
+            if indegree[nxt] == 0:
+                ready.append(nxt)
+        ready.sort(key=order_key)
+    remaining = [did for did in documents if did not in ordered]
+    return ordered + sorted(remaining, key=order_key)
+
+
+def _task_fit(fm: dict[str, Any], task: str | None) -> tuple[bool, str]:
+    if not task:
+        return True, "no task filter"
+    role = fm.get("ai_document_contract", {}).get("document_role")
+    if role in {"package_router", "frontmatter_canonical_model_spec"}:
+        return True, f"foundational role {role}"
+    routing = fm.get("routing", {})
+    read_tags = set(routing.get("read_when_tags") or [])
+    if task in read_tags:
+        return True, f"read_when_tags contains {task}"
+    return False, f"read_when_tags does not contain {task}"
+
+
+def _finding_class(error_id: str) -> str:
+    if "RELATIONSHIP" in error_id or "TARGET" in error_id or "LOAD-ORDER" in error_id:
+        return "relationship_or_ordering"
+    if "SCHEMA" in error_id or "UNKNOWN" in error_id or "MISSING" in error_id:
+        return "shape_or_schema"
+    if "EVIDENCE" in error_id or "CLAIM" in error_id or "VERIF" in error_id:
+        return "claim_or_evidence"
+    if "INTENTION" in error_id:
+        return "intention"
+    return "other"
+
+
+def _defects_by_class(findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    grouped: dict[tuple[str, str], dict[str, Any]] = {}
+    for item in findings:
+        error_id = str(item.get("error_id") or item.get("finding", {}).get("id") or "UNKNOWN")
+        key = (_finding_class(error_id), error_id)
+        bucket = grouped.setdefault(key, {
+            "class": key[0],
+            "finding_id": error_id,
+            "count": 0,
+            "documents": [],
+            "examples": [],
+        })
+        bucket["count"] += 1
+        source = item.get("source_path") or item.get("context", {}).get("source_path")
+        if source and source not in bucket["documents"]:
+            bucket["documents"].append(source)
+        if len(bucket["examples"]) < 3:
+            bucket["examples"].append({
+                "detail": item.get("finding", {}).get("detail") or item.get("context", {}).get("detail"),
+                "source_path": source,
+                "line": item.get("line"),
+            })
+    return sorted(grouped.values(), key=lambda row: (row["class"], row["finding_id"]))
+
+
+def _available_tasks(per_document: dict[str, Any]) -> list[str]:
+    tasks: set[str] = set()
+    for per_doc in per_document.values():
+        fm = _doc_frontmatter(per_doc)
+        if not fm:
+            continue
+        for tag in fm.get("routing", {}).get("read_when_tags") or []:
+            if isinstance(tag, str) and tag:
+                tasks.add(tag)
+    return sorted(tasks)
+
+
+def _task_catalog(per_document: dict[str, Any]) -> list[str]:
+    catalog: set[str] = set()
+    for per_doc in per_document.values():
+        fm = _doc_frontmatter(per_doc)
+        if not fm:
+            continue
+        role = fm.get("ai_document_contract", {}).get("document_role")
+        if role != "package_router":
+            continue
+        for tag in fm.get("routing", {}).get("task_catalog") or []:
+            if isinstance(tag, str) and tag:
+                catalog.add(tag)
+    return sorted(catalog)
+
+
+def validate_brief_task(report: dict[str, Any], task: str | None) -> None:
+    if not task:
+        return
+    available_tasks = _available_tasks(report.get("_per_document") or {})
+    task_catalog = _task_catalog(report.get("_per_document") or {})
+    if task in available_tasks:
+        return
+    raise ToolingError(
+        "Unknown brief task filter",
+        f"--task {task}",
+        "The task filter must match a read_when_tags value declared by at least one target document.",
+        "Use one of the available_tasks values from the brief output, or add the task to read_when_tags in the intended document.",
+        {
+            "requested_task": task,
+            "available_tasks": available_tasks,
+            "task_catalog": task_catalog,
+        },
+        error_id="FRONTMATTERING-KERNEL-BRIEF-TASK-UNKNOWN",
+    )
+
+
+def _finding_source_path(item: dict[str, Any]) -> str | None:
+    return (
+        item.get("source_path")
+        or item.get("context", {}).get("source_path")
+        or item.get("finding", {}).get("source_path")
+    )
+
+
+def _finding_document_id(item: dict[str, Any]) -> str | None:
+    return (
+        item.get("document_id")
+        or item.get("context", {}).get("document_id")
+        or item.get("finding", {}).get("document_id")
+    )
+
+
+def _scoped_findings(findings: list[dict[str, Any]], documents: dict[str, dict[str, Any]], task: str | None) -> list[dict[str, Any]]:
+    if not task:
+        return findings
+    selected_paths = {str(doc.get("path")) for doc in documents.values()}
+    selected_ids = set(documents)
+    scoped = []
+    for item in findings:
+        source_path = _finding_source_path(item)
+        document_id = _finding_document_id(item)
+        if source_path in selected_paths or document_id in selected_ids:
+            scoped.append(item)
+    return scoped
+
+
+def _trap_census(traps: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    grouped: dict[str, dict[str, Any]] = {}
+    for item in traps:
+        category = str(item.get("category") or "uncategorized")
+        bucket = grouped.setdefault(category, {"category": category, "count": 0, "documents": []})
+        bucket["count"] += 1
+        doc_id = item.get("document_id")
+        if doc_id and doc_id not in bucket["documents"]:
+            bucket["documents"].append(doc_id)
+    return sorted(grouped.values(), key=lambda row: (-row["count"], row["category"]))
+
+
+def _block_census(blocks: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    grouped: dict[tuple[str, str], dict[str, Any]] = {}
+    for item in blocks:
+        label = str(item.get("condition") or item.get("detail") or item.get("kind") or "block")
+        kind = str(item.get("kind") or "block")
+        key = (kind, label)
+        bucket = grouped.setdefault(key, {"kind": kind, "label": label, "count": 0, "documents": [], "recovery": None})
+        bucket["count"] += 1
+        doc_id = item.get("document_id") or item.get("source_document_id")
+        if doc_id and doc_id not in bucket["documents"]:
+            bucket["documents"].append(doc_id)
+        if bucket["recovery"] is None:
+            bucket["recovery"] = item.get("recovery_action") or item.get("fix")
+    return sorted(grouped.values(), key=lambda row: (-row["count"], row["kind"], row["label"]))
+
+
+def _counter_census(items: list[dict[str, Any]], field: str, label: str) -> list[dict[str, Any]]:
+    grouped: dict[str, dict[str, Any]] = {}
+    for item in items:
+        value = str(item.get(field) or "unspecified")
+        bucket = grouped.setdefault(value, {label: value, "count": 0, "documents": []})
+        bucket["count"] += 1
+        doc_id = item.get("document_id")
+        if doc_id and doc_id not in bucket["documents"]:
+            bucket["documents"].append(doc_id)
+    return sorted(grouped.values(), key=lambda row: (-row["count"], row[label]))
+
+
+def _trust_projection(doc: dict[str, Any]) -> dict[str, Any]:
+    identity = _doc_identity(doc["path"], doc)
+    adc = doc.get("ai_document_contract", {})
+    boundary = doc.get("claim_boundary_packet", {})
+    evidence_refs = doc.get("evidence_references") or []
+    digest_bound = [
+        item for item in evidence_refs
+        if isinstance(item, dict) and item.get("digest_sha256")
+    ]
+    return {
+        **identity,
+        "lifecycle_state": adc.get("lifecycle_state"),
+        "authority": adc.get("authority"),
+        "claimed_state": boundary.get("claimed_state"),
+        "verifies_count": len(boundary.get("verifies") or []),
+        "does_not_verify_count": len(boundary.get("does_not_verify") or []),
+        "judgment_left_count": len(boundary.get("judgment_left_to_agent") or []),
+        "evidence_reference_count": len(evidence_refs),
+        "digest_bound_evidence_count": len(digest_bound),
+        "evidence_kinds": sorted({
+            str(item.get("evidence_kind"))
+            for item in evidence_refs
+            if isinstance(item, dict) and item.get("evidence_kind")
+        }),
+        "evidence_ids": [
+            item.get("evidence_id")
+            for item in evidence_refs
+            if isinstance(item, dict) and item.get("evidence_id")
+        ],
+        "body_tether_freshness": (doc.get("_body_tether") or {}).get("freshness"),
+        "summary_trust": (doc.get("_body_tether") or {}).get("summary_trust"),
+        "body_tether_reasons": (doc.get("_body_tether") or {}).get("reasons") or [],
+    }
+
+
+def _trust_census(trust_items: list[dict[str, Any]]) -> dict[str, Any]:
+    evidence_kind_counts: dict[str, int] = {}
+    for item in trust_items:
+        kinds = item.get("evidence_kinds") or []
+        if not kinds:
+            evidence_kind_counts["none"] = evidence_kind_counts.get("none", 0) + 1
+        for kind in kinds:
+            evidence_kind_counts[str(kind)] = evidence_kind_counts.get(str(kind), 0) + 1
+    return {
+        "claimed_state": _counter_census(trust_items, "claimed_state", "claimed_state"),
+        "lifecycle_state": _counter_census(trust_items, "lifecycle_state", "lifecycle_state"),
+        "authority": _counter_census(trust_items, "authority", "authority"),
+        "evidence_kind_counts": dict(sorted(evidence_kind_counts.items(), key=lambda row: (-row[1], row[0]))),
+        "documents_without_evidence_references": [
+            item.get("document_id")
+            for item in trust_items
+            if not item.get("evidence_reference_count")
+        ],
+    }
+
+
+
+
+def _freshness_census(reading_order: list[dict[str, Any]]) -> dict[str, Any]:
+    counts: dict[str, int] = {}
+    documents: dict[str, list[str]] = {}
+    for item in reading_order:
+        status = str(item.get("body_tether_freshness") or "UNTETHERED")
+        counts[status] = counts.get(status, 0) + 1
+        documents.setdefault(status, []).append(str(item.get("document_id")))
+    return {"counts": dict(sorted(counts.items())), "documents": documents}
+
+def _section_ref(section: str) -> str:
+    return f"brief --section {section}"
+
+
+def _format_more(total: int, shown: int, section: str) -> str | None:
+    remaining = total - shown
+    if remaining <= 0:
+        return None
+    return f"+{remaining} more -> {_section_ref(section)}"
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _display_path(path: str, selection: dict[str, Any]) -> str:
+    source = Path(path).resolve()
+    root_text = selection.get("project_root")
+    if root_text:
+        try:
+            return source.relative_to(Path(root_text).resolve()).as_posix()
+        except ValueError:
+            pass
+    return source.as_posix()
+
+
+def _source_binding(path: str, fm: dict[str, Any], selection: dict[str, Any]) -> dict[str, Any]:
+    source = Path(path)
+    raw = source.read_bytes() if source.exists() else b""
+    fm_text = None
+    try:
+        decoded = raw.decode("utf-8", errors="strict")
+        fm_text, _body, _findings = split_frontmatter(decoded)
+    except (UnicodeDecodeError, OSError):
+        pass
+    adc = fm.get("ai_document_contract") or {}
+    return {
+        "document_id": adc.get("document_id"),
+        "path": _display_path(path, selection),
+        "role": adc.get("document_role"),
+        "authority": adc.get("authority"),
+        "source_sha256": _sha256_bytes(raw),
+        "frontmatter_sha256": _sha256_bytes((fm_text or "").encode("utf-8")),
+    }
+
+
+def _inclusion_reason_codes(fm: dict[str, Any], task: str | None) -> list[str]:
+    role = (fm.get("ai_document_contract") or {}).get("document_role")
+    if task is None:
+        return ["FRONTMATTERING-BRIEF-WHOLE-CORPUS"]
+    if role in {"package_router", "frontmatter_canonical_model_spec"}:
+        return ["FRONTMATTERING-BRIEF-FOUNDATIONAL-ROLE"]
+    if task in set((fm.get("routing") or {}).get("read_when_tags") or []):
+        return ["FRONTMATTERING-BRIEF-TASK-TAG-MATCH"]
+    return ["FRONTMATTERING-BRIEF-INCLUDED-BY-VALIDATED-ROUTING"]
+
+
+def _orientation_projection(
+    report: dict[str, Any],
+    *,
+    task: str | None,
+    documents: dict[str, dict[str, Any]],
+    skipped: list[dict[str, Any]],
+    selected_order: list[str],
+    blocks: list[dict[str, Any]],
+    scoped_findings: list[dict[str, Any]],
+) -> dict[str, Any]:
+    selection = report.get("selection") or {
+        "selected_paths_sha256": hashlib.sha256(b"").hexdigest(),
+        "selected_path_count": len(documents),
+    }
+    records: dict[str, dict[str, Any]] = {}
+    for doc_id, doc in documents.items():
+        binding = _source_binding(doc["path"], doc, selection)
+        records[doc_id] = {**binding, "inclusion_reason_codes": _inclusion_reason_codes(doc, task)}
+
+    superseded_ids: set[str] = set()
+    for source in documents.values():
+        for rel in source.get("relationships") or []:
+            if isinstance(rel, dict) and rel.get("relationship_type") == "supersedes":
+                target = rel.get("target_document_id")
+                if target in records:
+                    superseded_ids.add(str(target))
+
+    authoritative = []
+    supporting = []
+    non_authoritative = {"advisory", "orientation_only"}
+    for doc_id in selected_order:
+        record = records[doc_id]
+        (supporting if record.get("authority") in non_authoritative else authoritative).append(record)
+
+    excluded = []
+    for item in skipped:
+        excluded.append({
+            "document_id": item.get("document_id"),
+            "path": _display_path(str(item.get("path")), selection),
+            "exclusion_reason_codes": ["FRONTMATTERING-BRIEF-TASK-TAG-NOT-MATCHED"],
+        })
+
+    ambiguities = []
+    # Authored stop_if clauses describe conditions that would block future work;
+    # their presence is not evidence that the condition is currently true.
+    # Orientation becomes incomplete only for observed structural blockers.
+    for block in blocks:
+        kind = block.get("kind")
+        if kind not in {"unresolved_required_edge", "binding_dependency_cycle"}:
+            continue
+        ambiguities.append({
+            "reason_code": "FRONTMATTERING-BRIEF-REQUIRED-RELATIONSHIP-UNRESOLVED" if kind == "unresolved_required_edge" else "FRONTMATTERING-BRIEF-BINDING-DEPENDENCY-CYCLE",
+            "document_id": block.get("document_id") or block.get("source_document_id"),
+            "detail": block.get("detail") or block.get("condition"),
+            "target_document_id": block.get("target_document_id"),
+        })
+    for finding in scoped_findings:
+        ambiguities.append({
+            "reason_code": "FRONTMATTERING-BRIEF-STRUCTURAL-FINDING",
+            "finding_id": finding.get("error_id"),
+            "document_id": finding.get("document_id"),
+            "path": finding.get("source_path"),
+        })
+    status = "READY" if report.get("terminal_state") == "GO" and not ambiguities else "CHECKPOINT_INCOMPLETE"
+    return {
+        "status": status,
+        "task": task,
+        "selection": {
+            "selected_paths_sha256": selection.get("selected_paths_sha256"),
+            "selected_path_count": selection.get("selected_path_count", len(documents)),
+        },
+        "authoritative_documents": authoritative,
+        "required_reading_order": [records[doc_id] for doc_id in selected_order],
+        "supporting_documents": supporting,
+        "superseded_documents": [records[doc_id] for doc_id in selected_order if doc_id in superseded_ids],
+        "excluded_documents": excluded,
+        "unresolved_ambiguities": ambiguities,
+        "source_bindings": [records[doc_id] for doc_id in selected_order],
+        "claim_boundary": {
+            "verifies": [
+                "Live source digests, validated metadata routing, and deterministic inclusion or exclusion reasons.",
+            ],
+            "does_not_verify": [
+                "That excluded documents are semantically irrelevant.",
+                "Semantic adequacy, factual correctness, external adoption, or release readiness.",
+            ],
+        },
+    }
+
+
+def brief_projection(report: dict[str, Any], *, task: str | None = None) -> dict[str, Any]:
+    """Project the already-validated document model into a cold-start hazard brief."""
+    per_document = report.get("_per_document") or {}
+    documents: dict[str, dict[str, Any]] = {}
+    skipped: list[dict[str, Any]] = []
+    available_tasks = _available_tasks(per_document)
+    task_catalog = _task_catalog(per_document)
+    for path, per_doc in sorted(per_document.items()):
+        fm = _doc_frontmatter(per_doc)
+        if not fm:
+            continue
+        doc_id = fm.get("ai_document_contract", {}).get("document_id")
+        if not doc_id:
+            continue
+        include, reason = _task_fit(fm, task)
+        if include:
+            documents[doc_id] = {"path": path, **fm, "_body_tether": per_doc.get("body_tether") or {}}
+        else:
+            skipped.append({**_doc_identity(path, fm), "skip_reason": reason, "body_tether": per_doc.get("body_tether") or {}})
+
+    blocks: list[dict[str, Any]] = []
+    traps: list[dict[str, Any]] = []
+    limits: list[dict[str, Any]] = []
+    do_not: list[dict[str, Any]] = []
+    trust: list[dict[str, Any]] = []
+
+    for doc_id in _topological_reading_order(documents):
+        doc = documents[doc_id]
+        path = doc["path"]
+        identity = _doc_identity(path, doc)
+        adc = doc.get("ai_document_contract", {})
+        trust.append(_trust_projection(doc))
+        for item in adc.get("stop_if") or []:
+            if isinstance(item, dict):
+                blocks.append({**identity, "kind": "stop_if", **item})
+        for item in adc.get("must_not_be_used_for") or []:
+            do_not.append({**identity, "text": item})
+
+        intention = doc.get("deepest_intention", {})
+        for item in intention.get("not_the_intention") or []:
+            if isinstance(item, dict):
+                traps.append({**identity, **item})
+            else:
+                traps.append({**identity, "statement": item})
+
+        boundary = doc.get("claim_boundary_packet", {})
+        for item in boundary.get("does_not_verify") or []:
+            limits.append({**identity, "kind": "does_not_verify", "text": item})
+        for item in boundary.get("judgment_left_to_agent") or []:
+            limits.append({**identity, "kind": "judgment_left_to_agent", "text": item})
+
+    mesh = report.get("docset_mesh") or {}
+    for edge in mesh.get("unresolved_same_set_edges") or []:
+        if not edge.get("required"):
+            continue
+        source_id = edge.get("source_document_id")
+        if source_id not in documents:
+            continue
+        blocks.append({
+            "kind": "unresolved_required_edge",
+            "document_id": source_id,
+            "source_document_id": source_id,
+            "target_document_id": edge.get("target_document_id"),
+            "detail": "required same-document-set relationship target is unresolved",
+            "recovery_action": "Add the target document, correct target_document_id, or change resolution_scope.",
+        })
+    for item in report.get("findings") or []:
+        if str(item.get("error_id") or "") != "FRONTMATTERING-FM-BINDING-DEPENDENCY-CYCLE":
+            continue
+        blocks.append({
+            "kind": "binding_dependency_cycle",
+            "detail": item.get("finding", {}).get("detail"),
+            "source_path": item.get("source_path"),
+            "line": item.get("line"),
+            "fix": item.get("fix"),
+        })
+
+    selected_order = _topological_reading_order(documents)
+    scoped_findings = _scoped_findings(report.get("findings") or [], documents, task)
+    reading_order = [
+        {
+            **_doc_identity(documents[doc_id]["path"], documents[doc_id]),
+            "agent_summary": documents[doc_id].get("routing", {}).get("agent_summary"),
+            "primary_action_expected": documents[doc_id].get("ai_document_contract", {}).get("primary_action_expected"),
+            "body_tether_freshness": (documents[doc_id].get("_body_tether") or {}).get("freshness"),
+            "summary_trust": (documents[doc_id].get("_body_tether") or {}).get("summary_trust"),
+            "body_tether_reasons": (documents[doc_id].get("_body_tether") or {}).get("reasons") or [],
+        }
+        for doc_id in selected_order
+    ]
+    orientation = _orientation_projection(
+        report, task=task, documents=documents, skipped=skipped, selected_order=selected_order,
+        blocks=blocks, scoped_findings=scoped_findings,
+    )
+
+    return {
+        "schema_version": "frontmattering_brief/v0_3",
+        "orientation": orientation,
+        "selection": report.get("selection") or {},
+        "kernel_version": report.get("kernel_version"),
+        "terminal_state": report.get("terminal_state"),
+        "task": task,
+        "task_filter": {
+            "requested_task": task,
+            "available_tasks": available_tasks,
+            "task_catalog": task_catalog,
+            "scope": "selected_read_set" if task else "whole_corpus",
+            "selected_document_ids": selected_order,
+            "skipped_document_ids": [item.get("document_id") for item in skipped if item.get("document_id")],
+            "selected_document_count": len(documents),
+            "skipped_document_count": len(skipped),
+        },
+        "document_count": len(documents),
+        "skipped_count": len(skipped),
+        "blocks": blocks,
+        "block_census": _block_census(blocks),
+        "traps": traps,
+        "trap_census": _trap_census(traps),
+        "limits": limits,
+        "do_not": do_not,
+        "trust": trust,
+        "trust_census": _trust_census(trust),
+        "freshness_census": _freshness_census(reading_order),
+        "reading_order": reading_order,
+        "skipped_documents": skipped,
+        "available_tasks": available_tasks,
+        "task_catalog": task_catalog,
+        "defect_scope": {
+            "scope": "selected_read_set" if task else "whole_corpus",
+            "scoped_finding_count": len(scoped_findings),
+            "corpus_finding_count": len(report.get("findings") or []),
+        },
+        "defects_by_class": _defects_by_class(scoped_findings),
+        "section_hints": {
+            "blocks": _section_ref("blocks"),
+            "traps": _section_ref("traps"),
+            "limits": _section_ref("limits"),
+            "do_not": _section_ref("do-not"),
+            "trust": _section_ref("trust"),
+            "reading_order": _section_ref("reading-order"),
+            "defects_by_class": _section_ref("defects"),
+        },
+        "claim_boundary": {
+            "verifies": [
+                "This is a read-only projection of validated frontmatter and findings.",
+            ],
+            "does_not_verify": [
+                "Semantic adequacy of document bodies.",
+                "That authored hazards are complete.",
+                "Implementation, adoption, release, or production readiness.",
+            ],
+        },
+    }
+
+
+def _render_brief_summary(brief: dict[str, Any]) -> list[str]:
+    orientation = brief.get("orientation") or {}
+    selection = orientation.get("selection") or {}
+    required = orientation.get("required_reading_order") or []
+    chain = " -> ".join(
+            f"{item.get('document_id')}[{item.get('body_tether_freshness') or 'UNTETHERED'}]"
+            for item in required
+        ) or "none"
+    lines = [
+        "# Frontmattering Cold-Start Brief",
+        "",
+        f"STATUS  {orientation.get('status') or 'CHECKPOINT_INCOMPLETE'}",
+        f"TASK    {orientation.get('task') or 'none'}",
+        f"SELECT  {selection.get('selected_path_count', 0)} path(s) digest={selection.get('selected_paths_sha256')}",
+        f"READ    {chain}",
+        f"BLOCKS  {len(orientation.get('unresolved_ambiguities') or [])}",
+        "CLAIM   metadata-derived orientation only; semantic adequacy is not verified",
+        "",
+        (
+            f"BRIEF - {brief.get('document_count')} docs - {brief.get('terminal_state')} - "
+            f"task: {brief.get('task') or 'none'}"
+        ),
+        "",
+    ]
+
+    block_census = brief.get("block_census") or []
+    if block_census:
+        block_total = sum(int(item.get("count") or 0) for item in block_census)
+        by_kind: dict[str, int] = {}
+        for item in block_census:
+            by_kind[str(item.get("kind") or "block")] = by_kind.get(str(item.get("kind") or "block"), 0) + int(item.get("count") or 0)
+        kind_text = " | ".join(f"{kind} x{count}" for kind, count in sorted(by_kind.items()))
+        lines.append(f"BLOCKS  {block_total} item(s): {kind_text} -> {_section_ref('blocks')}")
+        repeated = [item for item in block_census if int(item.get("count") or 0) > 1]
+        if repeated:
+            item = repeated[0]
+            lines.append(f"        top repeat: {item.get('label')} x{item.get('count')}")
+    else:
+        lines.append("BLOCKS  none")
+
+    trap_census = brief.get("trap_census") or []
+    if trap_census:
+        rendered = [
+            f"{item.get('category')} x{item.get('count')}"
+            for item in trap_census[:SUMMARY_ITEM_LIMIT]
+        ]
+        lines.append("TRAPS   " + " | ".join(rendered) + f" -> {_section_ref('traps')}")
+        more = _format_more(len(trap_census), SUMMARY_ITEM_LIMIT, "traps")
+        if more:
+            lines.append(f"        {more}")
+    else:
+        lines.append("TRAPS   none")
+
+    limit_count = len(brief.get("limits") or [])
+    if limit_count:
+        lines.append(f"LIMITS  {limit_count} item(s) across the selected READ set -> {_section_ref('limits')}")
+    else:
+        lines.append("LIMITS  none")
+
+    do_not_count = len(brief.get("do_not") or [])
+    if do_not_count:
+        lines.append(f"DO NOT  {do_not_count} item(s) across the selected READ set -> {_section_ref('do-not')}")
+    else:
+        lines.append("DO NOT  none")
+
+    trust_census = brief.get("trust_census") or {}
+    claimed = trust_census.get("claimed_state") or []
+    if claimed:
+        claimed_text = " | ".join(
+            f"{item.get('claimed_state')} x{item.get('count')}"
+            for item in claimed[:SUMMARY_ITEM_LIMIT]
+        )
+        evidence_counts = trust_census.get("evidence_kind_counts") or {}
+        evidence_text = " | ".join(
+            f"{kind} x{count}"
+            for kind, count in list(evidence_counts.items())[:SUMMARY_ITEM_LIMIT]
+        ) or "none"
+        lines.append(f"TRUST   {claimed_text}; evidence: {evidence_text} -> {_section_ref('trust')}")
+    else:
+        lines.append("TRUST   none")
+
+    freshness = brief.get("freshness_census") or {}
+    freshness_counts = freshness.get("counts") or {}
+    if freshness_counts:
+        parts = [f"{status} x{count}" for status, count in freshness_counts.items()]
+        trust_hint = "summary_trust=do_not_rely_without_reading_body" if freshness_counts.get("STALE") else "summary_trust=fresh_or_orientation"
+        lines.append(f"FRESH   {' | '.join(parts)}; {trust_hint} -> {_section_ref('reading-order')}")
+    else:
+        lines.append("FRESH   none")
+
+    defects = brief.get("defects_by_class") or []
+    if defects:
+        defect_scope = (brief.get("defect_scope") or {}).get("scope") or "unknown_scope"
+        lines.append(f"DEFECTS {len(defects)} class(es) [{defect_scope}]")
+        for item in defects[:SUMMARY_ITEM_LIMIT]:
+            lines.append(
+                f"        {item.get('class')} / {item.get('finding_id')}: "
+                f"{item.get('count')} instance(s), {len(item.get('documents') or [])} document(s)"
+            )
+        more = _format_more(len(defects), SUMMARY_ITEM_LIMIT, "defects")
+        if more:
+            lines.append(f"        {more}")
+    else:
+        lines.append("DEFECTS none")
+
+    reading_order = brief.get("reading_order") or []
+    read_chain = " -> ".join(
+        f"{doc.get('document_id')}[{doc.get('body_tether_freshness') or 'UNTETHERED'}]({doc.get('load_order')})"
+        for doc in reading_order[:SUMMARY_READING_LIMIT]
+    )
+    if read_chain:
+        lines.append(f"READ    {read_chain}")
+    more = _format_more(len(reading_order), SUMMARY_READING_LIMIT, "reading-order")
+    if more:
+        lines.append(f"        {more}")
+    if not reading_order:
+        lines.append("READ    none")
+
+    task_filter = brief.get("task_filter") or {}
+    if brief.get("task"):
+        lines.append(
+            "SCOPE   "
+            f"--task {brief.get('task')} selected {task_filter.get('selected_document_count')} "
+            f"doc(s), skipped {task_filter.get('skipped_document_count')} -> {_section_ref('reading-order')}"
+        )
+    else:
+        tasks = brief.get("available_tasks") or []
+        if tasks:
+            lines.append("SCOPE   no --task given; scope with: " + " | ".join(f"--task {task}" for task in tasks))
+        else:
+            lines.append("SCOPE   no read_when_tags found in this document set")
+
+    boundary = brief.get("claim_boundary") or {}
+    verifies = len(boundary.get("verifies") or [])
+    does_not_verify = len(boundary.get("does_not_verify") or [])
+    lines.append(f"CLAIM   verifies x{verifies}; does_not_verify x{does_not_verify} -> {_section_ref('claim-boundary')}")
+    return lines
+
+
+def _render_brief_section(brief: dict[str, Any], section: str) -> list[str]:
+    title = section.replace("_", " ").title()
+    lines = [
+        "# Frontmattering Cold-Start Brief",
+        "",
+        f"## {title}",
+        "",
+    ]
+    if section == "summary":
+        return _render_brief_summary(brief)
+    if section == "blocks":
+        for item in brief.get("blocks") or []:
+            label = item.get("condition_id") or item.get("target_document_id") or item.get("kind")
+            detail = item.get("condition") or item.get("detail") or ""
+            recovery = item.get("recovery_action") or item.get("fix")
+            lines.append(f"- {label}: {detail} [{item.get('document_id') or item.get('source_path')}]")
+            if recovery:
+                lines.append(f"  recovery: {recovery}")
+        if not brief.get("blocks"):
+            lines.append("- none")
+    elif section == "traps":
+        for item in brief.get("traps") or []:
+            category = item.get("category") or "uncategorized"
+            statement = item.get("statement") or item.get("text") or ""
+            tether = item.get("confusion_tether")
+            lines.append(f"- {category}: {statement} [{item.get('document_id')}]")
+            if tether:
+                lines.append(f"  tether: {tether}")
+        if not brief.get("traps"):
+            lines.append("- none")
+    elif section == "limits":
+        for item in brief.get("limits") or []:
+            lines.append(f"- {item.get('kind')}: {item.get('text')} [{item.get('document_id')}]")
+        if not brief.get("limits"):
+            lines.append("- none")
+    elif section == "do_not":
+        for item in brief.get("do_not") or []:
+            lines.append(f"- {item.get('text')} [{item.get('document_id')}]")
+        if not brief.get("do_not"):
+            lines.append("- none")
+    elif section == "trust":
+        trust_census = brief.get("trust_census") or {}
+        lines.append("### Claimed State")
+        for item in trust_census.get("claimed_state") or []:
+            lines.append(
+                f"- {item.get('claimed_state')}: {item.get('count')} document(s) "
+                f"{item.get('documents') or []}"
+            )
+        if not trust_census.get("claimed_state"):
+            lines.append("- none")
+        lines.append("")
+        lines.append("### Evidence References")
+        evidence_counts = trust_census.get("evidence_kind_counts") or {}
+        if evidence_counts:
+            for kind, count in evidence_counts.items():
+                lines.append(f"- {kind}: {count} document(s)")
+        else:
+            lines.append("- none")
+        missing = trust_census.get("documents_without_evidence_references") or []
+        if missing:
+            lines.append(f"- documents_without_evidence_references: {missing}")
+        lines.append("")
+        lines.append("### Documents")
+        for item in brief.get("trust") or []:
+            lines.append(
+                f"- {item.get('document_id')}: claimed_state={item.get('claimed_state')}, "
+                f"lifecycle={item.get('lifecycle_state')}, authority={item.get('authority')}, "
+                f"verifies={item.get('verifies_count')}, does_not_verify={item.get('does_not_verify_count')}, "
+                f"judgment_left={item.get('judgment_left_count')}, "
+                f"evidence_refs={item.get('evidence_reference_count')}, "
+                f"digest_bound={item.get('digest_bound_evidence_count')}"
+            )
+        if not brief.get("trust"):
+            lines.append("- none")
+    elif section == "reading_order":
+        for index, doc in enumerate(brief.get("reading_order") or [], 1):
+            lines.append(
+                f"{index}. {doc.get('document_id')} | role={doc.get('document_role')} "
+                f"| load_order={doc.get('load_order')} | path={doc.get('path')}"
+            )
+            lines.append(
+                f"   freshness={doc.get('body_tether_freshness') or 'UNTETHERED'} "
+                f"summary_trust={doc.get('summary_trust') or 'orientation_only'}"
+            )
+            if doc.get("body_tether_reasons"):
+                lines.append(f"   freshness_reasons={doc.get('body_tether_reasons')}")
+            if doc.get("agent_summary"):
+                prefix = "summary_untrusted" if doc.get("body_tether_freshness") == "STALE" else "summary"
+                lines.append(f"   {prefix}: {doc.get('agent_summary')}")
+            lines.append(
+                f"   read_when_tags={doc.get('read_when_tags') or []} "
+                f"skip_when_tags={doc.get('skip_when_tags') or []}"
+            )
+        if not brief.get("reading_order"):
+            lines.append("- none")
+    elif section == "defects_by_class":
+        for item in brief.get("defects_by_class") or []:
+            lines.append(
+                f"- {item.get('class')} / {item.get('finding_id')}: "
+                f"{item.get('count')} instance(s), {len(item.get('documents') or [])} document(s)"
+            )
+        if not brief.get("defects_by_class"):
+            lines.append("- none")
+    elif section == "claim_boundary":
+        boundary = brief.get("claim_boundary") or {}
+        for item in boundary.get("verifies") or []:
+            lines.append(f"- verifies: {item}")
+        for item in boundary.get("does_not_verify") or []:
+            lines.append(f"- does_not_verify: {item}")
+    else:
+        raise InternalBugError(
+            "Unknown brief section",
+            where="kernel_reporting._render_brief_section",
+            context={"section": section},
+        )
+    return lines
+
+
+def render_brief_markdown(brief: dict[str, Any], *, section: str = "summary") -> str:
+    section_key = BRIEF_SECTION_ALIASES.get(section)
+    if section_key is None:
+        raise InternalBugError(
+            "Unknown brief section",
+            where="kernel_reporting.render_brief_markdown",
+            context={"section": section, "allowed": sorted(BRIEF_SECTION_ALIASES)},
+        )
+    lines = _render_brief_section(brief, section_key)
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_brief_report(
+    report: dict[str, Any],
+    fmt: str,
+    *,
+    task: str | None = None,
+    section: str = "summary",
+) -> str:
+    validate_brief_task(report, task)
+    brief = brief_projection(report, task=task)
+    if fmt == "json":
+        brief["selected_section"] = BRIEF_SECTION_ALIASES.get(section, section)
+        return render_json(brief)
+    if fmt == "markdown":
+        return render_brief_markdown(brief, section=section)
+    raise InternalBugError(
+        "Unknown brief report format",
+        where="kernel_reporting.render_brief_report",
+        context={"format": fmt},
+    )
+
+
+def validation_report(
+    *,
+    target_paths: list[Path],
+    auth: Any,
+    result: dict[str, Any],
+) -> dict[str, Any]:
+    findings = list(result.get("findings") or [])
+    errors = []
+    for item in findings:
+        fid, detail = item
+        source_path = getattr(item, "source_path", None) or source_for_finding(result, item)
+        document_id = getattr(item, "document_id", None) or _document_id_for_source(result, source_path)
+        err = finding_error(
+            fid,
+            detail,
+            source_path=source_path,
+            spec_path=str(auth.spec_path),
+            spec_sha256=auth.spec_sha256,
+            field_path=getattr(item, "field_path", None),
+            line=getattr(item, "line", None),
+            line_text=getattr(item, "line_text", None),
+            document_id=document_id,
+        ).to_dict()
+        ctx = err.get("context", {})
+        err["source_path"] = ctx.get("source_path")
+        err["field_path"] = ctx.get("field_path")
+        err["line"] = ctx.get("line")
+        err["line_text"] = ctx.get("line_text")
+        err["document_id"] = document_id
+        err["finding"] = {
+            "id": fid,
+            "detail": detail,
+            "source_path": ctx.get("source_path"),
+            "field_path": ctx.get("field_path"),
+            "line": ctx.get("line"),
+            "document_id": err.get("document_id"),
+        }
+        errors.append(err)
+    affected = sorted({
+        str(e.get("context", {}).get("source_path"))
+        for e in errors
+        if e.get("context", {}).get("source_path")
+    })
+    terminal = "GO" if not errors else "VIOLATED"
+    return {
+        "kernel_version": "frontmattering_frontmatter_kernel/v0_1_5",
+        "spec_path": str(auth.spec_path),
+        "spec_sha256": auth.spec_sha256,
+        "target_paths": [str(p) for p in target_paths],
+        "terminal_state": terminal,
+        "validation_terminal_state": terminal,
+        "finding_count": len(errors),
+        "findings": errors,
+        "_per_document": result.get("per_document") or {},
+        "docset_mesh": docset_mesh(result),
+        "affected_documents": affected,
+        "verifies": [
+            "The kernel executed v0.1.5 frontmatter validation over the listed targets.",
+        ],
+        "does_not_verify": [
+            "Semantic adequacy of the document body.",
+            "Adoption by an external authority.",
+            "Production readiness.",
+            "Compatibility with any non-v0.1.5 schema.",
+        ],
+    }
+
+
+def _jsonable(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {str(key): _jsonable(inner) for key, inner in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, set):
+        converted = [_jsonable(item) for item in value]
+        return sorted(converted, key=lambda item: json.dumps(item, sort_keys=True, default=str))
+    if isinstance(value, Path):
+        return str(value)
+    if hasattr(value, "to_dict"):
+        return _jsonable(value.to_dict())
+    if hasattr(value, "_asdict"):
+        return _jsonable(value._asdict())
+    if hasattr(value, "__dict__"):
+        return _jsonable(vars(value))
+    return str(value)
+
+
+def render_json(report: dict[str, Any]) -> str:
+    return json.dumps(_jsonable(report), indent=2, sort_keys=True) + "\n"
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    lines = [
+        "# Frontmattering frontmatter validation report",
+        "",
+        "## Summary",
+        "",
+        f"- validation_terminal_state: {report.get('validation_terminal_state', report['terminal_state'])}",
+        "- claim_ceiling: validation only - not adoption, release, or production readiness",
+        f"- finding_count: {report['finding_count']}",
+        f"- spec: {report['spec_path']}",
+        f"- spec_sha256: {report['spec_sha256']}",
+        "",
+    ]
+    findings = list(report.get("findings") or [])
+    if findings:
+        lines += ["## Fix First", ""]
+        for item in sorted(findings, key=_priority)[:5]:
+            lines.append(f"- {item['error_id']}: {item['fix']}")
+        lines.append("")
+        lines += ["## Findings", ""]
+        for i, item in enumerate(sorted(findings, key=_priority), 1):
+            lines += [
+                f"### {i}. {item['error_id']}",
+                "",
+                f"- what: {item['what']}",
+                f"- where: {item['where']}",
+                f"- source: {item.get('source_path') or 'docset'}",
+                f"- line: {item.get('line') or 'unknown'}",
+                f"- why: {item['why']}",
+                f"- fix: {item['fix']}",
+                f"- context: `{json.dumps(item.get('context', {}), sort_keys=True)}`",
+                "",
+            ]
+    else:
+        lines += ["## Findings", "", "No findings.", ""]
+    lines += ["## Affected Documents", ""]
+    if report.get("affected_documents"):
+        lines += [f"- {p}" for p in report["affected_documents"]]
+    else:
+        lines.append("- none")
+    mesh = report.get("docset_mesh") or {}
+    lines += ["", "## Document Mesh", ""]
+    lines.append(f"- documents: {mesh.get('document_count', 0)}")
+    lines.append(f"- relationships: {mesh.get('relationship_count', 0)}")
+    unresolved = mesh.get("unresolved_same_set_edges") or []
+    lines.append(f"- unresolved_same_set_edges: {len(unresolved)}")
+    for edge in unresolved[:10]:
+        lines.append(
+            "- unresolved: "
+            f"{edge.get('source_document_id')} -> {edge.get('target_document_id')} "
+            f"({edge.get('relationship_type')})"
+        )
+    lines += ["", "## Raw Evidence", ""]
+    for p in report.get("target_paths") or []:
+        lines.append(f"- target: {p}")
+    lines += ["", "## Claim Boundary", ""]
+    lines += [f"- verifies: {v}" for v in report.get("verifies") or []]
+    lines += [f"- does_not_verify: {v}" for v in report.get("does_not_verify") or []]
+    lines += [
+        "",
+        "VERDICT: "
+        f"validation_terminal_state={report.get('validation_terminal_state', report['terminal_state'])} "
+        "(validation only; not adoption, release, or production readiness)",
+    ]
+    return "\n".join(lines)
+
+
+def mesh_only_report(report: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "kernel_version": report.get("kernel_version"),
+        "terminal_state": report.get("terminal_state"),
+        "validation_terminal_state": report.get("validation_terminal_state", report.get("terminal_state")),
+        "finding_count": report.get("finding_count"),
+        "spec_path": report.get("spec_path"),
+        "spec_sha256": report.get("spec_sha256"),
+        "docset_mesh": report.get("docset_mesh") or {},
+        "selection": report.get("selection") or {},
+        "does_not_verify": report.get("does_not_verify") or [],
+    }
+
+
+def render_mesh_markdown(report: dict[str, Any]) -> str:
+    mesh = report.get("docset_mesh") or {}
+    lines = [
+        "# Frontmattering frontmatter document mesh",
+        "",
+        "## Summary",
+        "",
+        f"- validation_terminal_state: {report.get('validation_terminal_state', report.get('terminal_state'))}",
+        "- claim_ceiling: validation only - not adoption, release, or production readiness",
+        f"- finding_count: {report.get('finding_count')}",
+        f"- documents: {mesh.get('document_count', 0)}",
+        f"- relationships: {mesh.get('relationship_count', 0)}",
+        f"- unresolved_same_set_edges: {len(mesh.get('unresolved_same_set_edges') or [])}",
+        "",
+        "## Documents",
+        "",
+    ]
+    for doc in mesh.get("documents") or []:
+        lines.append(
+            f"- {doc.get('document_id')} | role={doc.get('document_role')} "
+            f"| load_order={doc.get('load_order')} | path={doc.get('path')}"
+        )
+        lines.append(
+            f"  read_when_tags={doc.get('read_when_tags') or []} "
+            f"skip_when_tags={doc.get('skip_when_tags') or []}"
+        )
+    if not mesh.get("documents"):
+        lines.append("- none")
+    lines += ["", "## Relationships", ""]
+    for edge in mesh.get("relationships") or []:
+        lines.append(
+            f"- {edge.get('source_document_id')} -> {edge.get('target_document_id')} "
+            f"| type={edge.get('relationship_type')} | required={edge.get('required')} "
+            f"| scope={edge.get('resolution_scope')} | sections={edge.get('target_sections')}"
+        )
+    if not mesh.get("relationships"):
+        lines.append("- none")
+    lines += ["", "## Unresolved Same-Set Edges", ""]
+    for edge in mesh.get("unresolved_same_set_edges") or []:
+        lines.append(
+            f"- {edge.get('source_document_id')} -> {edge.get('target_document_id')} "
+            f"({edge.get('relationship_type')}) in {edge.get('source_path')}"
+        )
+    if not mesh.get("unresolved_same_set_edges"):
+        lines.append("- none")
+    lines += ["", "## Claim Boundary", ""]
+    for item in report.get("does_not_verify") or []:
+        lines.append(f"- does_not_verify: {item}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_mesh_report(report: dict[str, Any], fmt: str) -> str:
+    mesh_report = mesh_only_report(report)
+    if fmt == "json":
+        return render_json(mesh_report)
+    if fmt == "markdown":
+        return render_mesh_markdown(mesh_report)
+    raise InternalBugError(
+        "Unknown mesh report format",
+        where="kernel_reporting.render_mesh_report",
+        context={"format": fmt},
+    )
+
+
+def render_report(report: dict[str, Any], fmt: str) -> str:
+    if fmt == "json":
+        return render_json(report)
+    if fmt == "markdown":
+        return render_markdown(report)
+    raise InternalBugError(
+        "Unknown validation report format",
+        where="kernel_reporting.render_report",
+        context={"format": fmt},
+    )