rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/rlm_synthesis.py

@@ -0,0 +1,316 @@
+"""RLM synthesis (FR-Q.5, T28): apply the recursive RLM method to the retrieved candidate chunks.
+
+The query-side RLM. The rebuild (ADR-0015/0016) makes synthesis genuinely recursive dynamic sub-agents,
+in two halves:
+
+  - DESCENT (new, recursive): a `SliceExtractor` decomposes the candidate set through the T15 machinery
+    (`build_rlm_agent`) — the interpreter holds the candidate chunks, a fresh `rlm_decomposer` splits an
+    over-large group, and an `rlm_slice_worker` extracts the query-relevant facts from each leaf slice
+    (per-slice tool use and per-slice skills live in the worker). A model is only ever called on a focused
+    slice, never over the full candidate volume.
+  - ASCENT (kept, ADR-0016): the Python `_reduce` fan-in combines the per-slice extracts into the final
+    synthesis, recursively (each combine sees at most `fanout` notes), so a model is never called over the
+    whole set of extracts either.
+
+Unlike chunking, recursion IS gated for synthesis (ADR-0019): the ADR-0016 fail-if-absent recursion
+discipline applies. The extractor and the combine both sit behind seams so the ascent is tested
+hermetically with stubs and the descent machinery is driven by scripted fake models; the live extract +
+synthesize is opt-in. No claim leaves without a citation: every `SliceOutput` carries its `chunk_id`
+(FR-Q.6).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Optional, Protocol, runtime_checkable
+
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+from langchain_core.tools import tool
+from pydantic import BaseModel
+
+from rag_wright.capabilities.registry import CapabilityRegistry
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.seam import build_model
+from rag_wright.skills.rlm.agent import (
+    RLM_DECOMPOSER,
+    RLM_SLICE_WORKER,
+    build_rlm_agent,
+    rlm_interpreter_session,
+)
+
+__all__ = [
+    "RLM_DECOMPOSER",
+    "RLM_SLICE_WORKER",
+    "SynthesisChunk",
+    "SliceOutput",
+    "SynthesisResult",
+    "Synthesizer",
+    "SeamSynthesizer",
+    "SliceExtractor",
+    "SeamSliceExtractor",
+    "rlm_synthesize",
+    "register_rlm_synthesis",
+]
+
+DEFAULT_REDUCE_CONCURRENCY = 8  # in-flight combine calls (backpressure); network-bound
+DEFAULT_FANOUT = 8  # code-side reduce fan-in: a combine call sees at most this many notes at once
+
+_EXTRACT_WORKER_PROMPT = (
+    "You handle ONE slice of retrieved candidate passages. Extract only the facts in this slice that help "
+    "answer the question, with any figures and named entities, faithfully and concisely, and keep each "
+    "fact tied to the chunk_id it came from. If the slice is irrelevant, say so briefly. You never see the "
+    "whole candidate set."
+)
+_COMBINE_PROMPT = (
+    "Combine these notes into a single faithful synthesis that answers the question, keeping figures and "
+    "named entities. Do not add facts not present in the notes."
+)
+
+
+class SynthesisChunk(BaseModel):
+    """A candidate chunk to synthesize over: its id and full text (rehydrated by `chunk_read`, T38,
+    from the chunk-text sidecar the ingest write leg persisted, `store/chunk_text.py`, T40)."""
+
+    chunk_id: str
+    text: str
+
+
+class SliceOutput(BaseModel):
+    """One slice's focused extract (the divide step), tied to its chunk_id (no claim without a citation)."""
+
+    chunk_id: str
+    extract: str
+
+
+class SynthesisResult(BaseModel):
+    """The RLM synthesis output: per-slice extracts, the combined synthesis, and the cited chunk_ids."""
+
+    query: str
+    slice_outputs: list[SliceOutput]
+    synthesis: str
+    chunk_ids: list[str]
+
+
+# --- the ascent: the kept Python `_reduce` fan-in (ADR-0016) --------------------------------------
+
+
+@runtime_checkable
+class Synthesizer(Protocol):
+    """The combine seam: fold a small group of already-reduced notes (<= fanout) into one synthesis."""
+
+    def combine(self, query: str, extracts: list[str]) -> str: ...
+
+
+class SeamSynthesizer:
+    """The real combine: a free-text call through the model-profile seam (DeepSeek V4 Pro, ADR-0006)."""
+
+    def __init__(self, model_id: str | None = None) -> None:
+        self._model_id = model_id or model_for(ModelRole.STRUCTURED_REASONING)
+
+    def combine(self, query: str, extracts: list[str]) -> str:
+        notes = "\n\n---\n\n".join(extracts)
+        message = build_model(self._model_id).invoke(f"{_COMBINE_PROMPT}\nQuestion: {query}\n\nNotes:\n{notes}")
+        return message.content if hasattr(message, "content") else str(message)
+
+
+async def _reduce(
+    query: str, extracts: list[str], synthesizer: Synthesizer, semaphore: asyncio.Semaphore, fanout: int
+) -> str:
+    """Fan-in reduce in code: combine at most `fanout` notes per call, recursing on the results so a
+    model is never called over the whole set. Groups at one level are combined concurrently. Kept from
+    the pre-rebuild implementation as the synthesis combine step (the ascent complements the descent)."""
+    if not extracts:
+        return ""
+    if len(extracts) <= fanout:
+        async with semaphore:
+            return await asyncio.to_thread(synthesizer.combine, query, extracts)
+    groups = [extracts[i : i + fanout] for i in range(0, len(extracts), fanout)]
+
+    async def _combine(group: list[str]) -> str:
+        async with semaphore:
+            return await asyncio.to_thread(synthesizer.combine, query, group)
+
+    partials = list(await asyncio.gather(*(_combine(group) for group in groups)))
+    return await _reduce(query, partials, synthesizer, semaphore, fanout)
+
+
+# --- the descent: the recursive RLM extractor (the T15 machinery) ---------------------------------
+
+
+@runtime_checkable
+class SliceExtractor(Protocol):
+    """The recursive-descent seam: decompose the candidate set and extract query-relevant facts per leaf."""
+
+    def extract(self, query: str, chunks: list[SynthesisChunk]) -> list[SliceOutput]: ...
+
+
+def _final_text(messages) -> str:
+    for message in reversed(messages):
+        if isinstance(message, AIMessage) and (message.text or "").strip():
+            return message.text
+    for message in reversed(messages):
+        if isinstance(message, ToolMessage) and message.name == "eval":
+            return str(message.content)
+    return ""
+
+
+def _parse_slice_outputs(text: str) -> list[SliceOutput]:
+    """Parse the JSON array of {chunk_id, extract} objects from the model's final output.
+
+    Scans every ``[`` and JSON-`raw_decode`s from it, keeping the LONGEST array whose elements are all
+    ``{chunk_id, extract}`` objects. Bracket-matching from the end (rfind) is wrong: real legal clauses put
+    ``[`` inside the extract text (e.g. "as set out in [Section 5]"), so the last ``[`` before the closing
+    ``]`` lands inside a string and the slice is invalid JSON — throwing a valid answer away. A ``[`` inside
+    a string cannot itself decode into a citation array, so scanning-and-validating cannot be fooled by it.
+    Returns ``[]`` when no valid citation array is present (never raises).
+    """
+    decoder = json.JSONDecoder()
+    best: list[SliceOutput] = []
+    for i, ch in enumerate(text):
+        if ch != "[":
+            continue
+        try:
+            value, _ = decoder.raw_decode(text, i)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(value, list) or not value:
+            continue
+        if not all(isinstance(o, dict) and "chunk_id" in o and "extract" in o for o in value):
+            continue
+        if len(value) > len(best):
+            best = [SliceOutput(chunk_id=str(o["chunk_id"]), extract=str(o["extract"])) for o in value]
+    return best
+
+
+class SeamSliceExtractor:
+    """The real extractor: the candidate set is decomposed recursively via `build_rlm_agent` and each leaf
+    slice is extracted by an `rlm_slice_worker`. Per-role models resolve through the profile seam
+    (STRUCTURED_REASONING / DeepSeek V4 Pro) or are injected as instances (tests). `working_set` overrides
+    the candidate view handed to the orchestrator (tests use an opaque handle to force recursion)."""
+
+    def __init__(
+        self,
+        model: object = None,
+        *,
+        decomposer_model: object = None,
+        worker_model: object = None,
+        worker_tools=(),
+        worker_skills=(),
+        working_set: object = None,
+    ) -> None:
+        self._model = model
+        self._decomposer_model = decomposer_model
+        self._worker_model = worker_model
+        self._worker_tools = worker_tools
+        self._worker_skills = worker_skills
+        self._working_set = working_set
+
+    def _build_agent(self, chunks: list[SynthesisChunk], query: str, *, interpreter=None):
+        model = self._model if self._model is not None else model_for(ModelRole.STRUCTURED_REASONING)
+        # Enforce the query reaching every worker: bake it into the worker's system prompt (T42). The leaf
+        # dispatch delivers the SLICE (the workflow threads `items`); the capability delivers the QUERY here,
+        # so query-relevant extraction no longer depends on the orchestrator choosing to thread it.
+        worker_prompt = (
+            f"{_EXTRACT_WORKER_PROMPT}\n\n"
+            f"The question to answer (extract facts relevant to THIS, verbatim):\n{query}"
+        )
+        return build_rlm_agent(
+            reasoning_model=model,
+            decomposer_model=self._decomposer_model if self._decomposer_model is not None else model,
+            worker_model=self._worker_model if self._worker_model is not None else model,
+            worker_system_prompt=worker_prompt,
+            worker_tools=self._worker_tools,
+            worker_skills=self._worker_skills,
+            interpreter=interpreter,
+        )
+
+    def _working_set_ptc(self, chunks: list[SynthesisChunk]):
+        value = self._working_set if self._working_set is not None else [
+            {"id": c.chunk_id, "chunk_id": c.chunk_id, "text": c.text} for c in chunks
+        ]
+        delivered = len(value)
+
+        @tool
+        def working_set() -> object:
+            """Return the working set: the retrieved candidate chunks (id, chunk_id, text)."""
+            return value
+
+        @tool
+        def working_set_size() -> int:
+            """Return the number of items in the delivered working set (a truthful count the workflow's
+            load-completeness assertion checks against, so an under-read fails loud, not silent)."""
+            return delivered
+
+        return [working_set, working_set_size]
+
+    def _request(self, query: str) -> str:
+        return (
+            "Run this as a workflow. Call `const workingSet = await tools.workingSet();` to get the "
+            "retrieved candidate set (a list of {id, chunk_id, text}); it is a JavaScript value in the "
+            "interpreter, never in your context. Decompose it (dispatch rlm_decomposer with `cuts` for an "
+            "over-large group and recurse), hand each leaf slice to an rlm_slice_worker that extracts the "
+            "facts relevant to the question, keeping each fact tied to its chunk_id. Apply the coverage "
+            "tail from your instructions: before returning, cover any candidate the recursion missed. Then "
+            "return ONLY a JSON array [{\"chunk_id\": ..., \"extract\": ...}], one entry per candidate.\n\n"
+            f"Question: {query}"
+        )
+
+    def extract(self, query: str, chunks: list[SynthesisChunk]) -> list[SliceOutput]:
+        if not chunks:
+            return []
+        request = self._request(query)
+        # The candidate set is delivered as a PTC value (`tools.workingSet()`, T36): it stays in the
+        # interpreter and never enters the model's context. The interpreter session is serialized
+        # process-wide (KI-1, ADR-0020): build + run + teardown inside the lock.
+        with rlm_interpreter_session(ptc=self._working_set_ptc(chunks)) as interpreter:
+            agent = self._build_agent(chunks, query, interpreter=interpreter)
+            messages = agent.invoke({"messages": [HumanMessage(content=request)]})["messages"]
+        return _parse_slice_outputs(_final_text(messages))
+
+
+# --- the capability: descent then ascent ---------------------------------------------------------
+
+
+def rlm_synthesize(
+    query: str,
+    chunks: list[SynthesisChunk],
+    *,
+    extractor: Optional[SliceExtractor] = None,
+    synthesizer: Optional[Synthesizer] = None,
+    max_concurrency: int = DEFAULT_REDUCE_CONCURRENCY,
+    fanout: int = DEFAULT_FANOUT,
+) -> SynthesisResult:
+    """Synthesize an answer over the candidate chunks: recursive extract (descent) then reduce (ascent).
+
+    `extractor` decomposes the candidate set and extracts per leaf, with the coverage guarantee **in the
+    interpreter workflow** (the skill's coverage tail covers any candidate the recursion missed, so it runs
+    in every consumer including GraphWright's node, not just here — T37); `_reduce` combines the extracts
+    via `synthesizer` (defaults to `SeamSynthesizer`). Every extract keeps its `chunk_id`, cited (FR-Q.6).
+    """
+    if not chunks:
+        return SynthesisResult(query=query, slice_outputs=[], synthesis="", chunk_ids=[])
+    extractor = extractor if extractor is not None else SeamSliceExtractor()
+    synthesizer = synthesizer if synthesizer is not None else SeamSynthesizer()
+
+    slice_outputs = extractor.extract(query, chunks)
+    semaphore = asyncio.Semaphore(max_concurrency)
+    synthesis = asyncio.run(
+        _reduce(query, [o.extract for o in slice_outputs], synthesizer, semaphore, fanout)
+    )
+    return SynthesisResult(
+        query=query,
+        slice_outputs=slice_outputs,
+        synthesis=synthesis,
+        chunk_ids=[chunk.chunk_id for chunk in chunks],
+    )
+
+
+def register_rlm_synthesis(registry: CapabilityRegistry) -> None:
+    """Register RLM synthesis under FR-Q.5 (`rlm_synthesis`, an `agent_skill` applying the RLM method)."""
+    registry.register(
+        "rlm_synthesis",
+        contract=SynthesisResult,
+        kind="agent_skill",
+        display_name="RLM synthesis",
+    )

rag_wright/capabilities/scan_quality.py

@@ -0,0 +1,136 @@
+"""Issue 0009-GATE: the scan-quality gate.
+
+Decide whether a scanned page's OCR is trustworthy, so the tiered OCR path can react: a DEGRADED page is
+escalated to a VLM (which reads blurred/faded text by language context), and a genuinely UNREADABLE page is
+flagged PARTIAL / needs-rescan rather than ingested as gibberish (the 0006-C / ENG-1 lossless principle applied
+to OCR).
+
+Signals (any subset; the strongest DEGRADED/UNREADABLE verdict wins):
+  - `text_readability`  -- common-word hit rate of the OCR text. Garbage OCR ("upareaia aes jo sa ...") almost
+    never hits common English words; real prose is dense with them. The strongest post-OCR signal, no dep.
+  - `image_quality`     -- Laplacian variance (blur) + dark_frac (faint ink), pre-OCR, via OpenCV. Predicts an
+    unreadable page before OCR is even run.
+  - docling `confidence` -- the parser's own per-page `PageConfidenceScores` (0..1), when available.
+
+Thresholds are the ones separated in the OCR benchmark (docs/eval/ocr_benchmark.md): clean/moderate scans read
+at word-hit ~0.2-0.4, Laplacian 2440/549, dark_frac 0.03/0.028; the heavy scan that defeats all OCR sits at
+word-hit ~0, Laplacian 54, dark_frac 0.003.
+"""
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+from pydantic import BaseModel
+
+# validated thresholds (see docs/eval/ocr_benchmark.md)
+_WORD_HIT_DEGRADED = 0.08       # readable text >> this; garbage OCR ~ 0
+_LAPLACIAN_DEGRADED = 150.0     # heavy 54 (blur) vs moderate 549 / clean 2440
+_DARK_FRAC_FAINT = 0.008        # heavy 0.003 (almost no ink) vs ~0.03 readable
+_CONFIDENCE_DEGRADED = 0.5      # docling PageConfidenceScores below this -> distrust
+
+# a small, dependency-free set of the most common English words -- their hit rate in OCR text cleanly separates
+# real prose (dense with these) from OCR garbage (almost none). Deliberately generic, not domain-specific.
+_COMMON_WORDS = frozenset((
+    "the of and to a in that is was he for it with as his on be at by i this had not are but from or have an "
+    "they which one you were her all she there would their we him been has when who will more no if out so said "
+    "what up its about into than them can only other new some could time these two may then do first any my now "
+    "such like our over me after also did many shall not any such under upon herein hereof any all each party "
+    "parties agreement pursuant provided further including without between whether"
+).split())
+
+
+class ScanQuality(str, Enum):
+    READABLE = "readable"        # trust the OCR text
+    DEGRADED = "degraded"        # low-quality -> escalate to a VLM
+    UNREADABLE = "unreadable"    # nothing recovered -> flag PARTIAL / needs-rescan
+
+
+class ScanAssessment(BaseModel):
+    quality: ScanQuality
+    reason: str
+    word_hit_rate: float | None = None
+    laplacian_var: float | None = None
+    dark_frac: float | None = None
+    confidence: float | None = None
+
+
+def text_readability(text: str) -> float:
+    """Fraction of alphabetic OCR tokens that are common English words (0..1). ~0 for OCR garbage."""
+    toks = re.findall(r"[A-Za-z]{2,}", (text or "").lower())
+    if not toks:
+        return 0.0
+    return sum(t in _COMMON_WORDS for t in toks) / len(toks)
+
+
+def image_quality(gray) -> dict:
+    """Pre-OCR page metrics from a grayscale image (numpy 2-D uint8): Laplacian variance (blur; higher = sharper)
+    and dark_frac (fraction of ink-dark pixels; a faint/washed-out scan is near zero)."""
+    import cv2
+    import numpy as np
+
+    g = np.asarray(gray)
+    return {"laplacian_var": float(cv2.Laplacian(g, cv2.CV_64F).var()), "dark_frac": float((g < 128).mean())}
+
+
+def assess_scan(text: str | None, *, laplacian_var: float | None = None, dark_frac: float | None = None,
+                confidence: float | None = None) -> ScanAssessment:
+    """Classify a page from whatever signals are available. The strongest negative verdict wins; if nothing at
+    all is recognised and no other signal is present, the page is UNREADABLE (a blank / failed scan)."""
+    whr = text_readability(text) if text is not None else None
+
+    def _a(q: ScanQuality, reason: str) -> ScanAssessment:
+        return ScanAssessment(quality=q, reason=reason, word_hit_rate=whr, laplacian_var=laplacian_var,
+                              dark_frac=dark_frac, confidence=confidence)
+
+    # UNREADABLE: an empty/near-empty result with no positive evidence anywhere
+    if text is not None and not (text or "").strip() and laplacian_var is None and confidence is None:
+        return _a(ScanQuality.UNREADABLE, "no text recognised")
+
+    # DEGRADED signals (escalate to a VLM)
+    if whr is not None and (text or "").strip() and whr < _WORD_HIT_DEGRADED:
+        return _a(ScanQuality.DEGRADED, f"low word-hit-rate {whr:.3f} (likely garbage OCR)")
+    if laplacian_var is not None and laplacian_var < _LAPLACIAN_DEGRADED:
+        return _a(ScanQuality.DEGRADED, f"blurry image (laplacian_var {laplacian_var:.0f})")
+    if dark_frac is not None and dark_frac < _DARK_FRAC_FAINT:
+        return _a(ScanQuality.DEGRADED, f"faint image (dark_frac {dark_frac:.3f})")
+    if confidence is not None and confidence < _CONFIDENCE_DEGRADED:
+        return _a(ScanQuality.DEGRADED, f"low OCR confidence {confidence:.2f}")
+
+    return _a(ScanQuality.READABLE, "ok")
+
+
+def _page_texts(doc) -> dict[int, str]:
+    """Group a parsed document's text by page number (from each item's `prov[0].page_no`). Duck-typed on
+    `iterate_items()` so it works on a real DoclingDocument or a hermetic fake."""
+    pages: dict[int, list[str]] = {}
+    for item, _level in doc.iterate_items():
+        text = (getattr(item, "text", "") or "").strip()
+        if not text:
+            continue
+        prov = getattr(item, "prov", None) or []
+        pg = prov[0].page_no if prov else 1
+        pages.setdefault(pg, []).append(text)
+    return {pg: "\n".join(v) for pg, v in pages.items()}
+
+
+def assess_document(doc, *, page_images: dict | None = None) -> dict[int, ScanAssessment]:
+    """Assess each page of a parsed document -> {page_no: ScanAssessment}. When `page_images` (a {page_no:
+    grayscale numpy image} map) is given, the IMAGE metrics (blur/faintness) are folded in alongside the OCR
+    text -- the strong signal that separates a degraded scan whose OCR is garbled-but-common-word (which a
+    text-only gate misses) from a readable one. A page present only in the image map (no OCR text) is still
+    assessed. Pass NO images to re-check VLM output (the image stays blurry after the VLM recovers the text)."""
+    page_images = page_images or {}
+    texts = _page_texts(doc)
+    out: dict[int, ScanAssessment] = {}
+    for pg in sorted(set(texts) | set(page_images)):
+        img = page_images.get(pg)
+        metrics = image_quality(img) if img is not None else {}
+        out[pg] = assess_scan(texts.get(pg, ""), **metrics)
+    return out
+
+
+def register_scan_quality(registry) -> None:
+    """0009-GATE: register `scan_quality` (function; page signals -> a readable/degraded/unreadable verdict)."""
+    registry.register("scan_quality", contract=ScanAssessment, kind="function",
+                      display_name="Scan-quality gate (route degraded scans to VLM; flag unreadable PARTIAL)")

rag_wright/capabilities/span_relevance_judgment.py

@@ -0,0 +1,191 @@
+"""Engine issue 0023: a per-span RELEVANCE VERDICT on the corpus retrieval path.
+
+`typed_property_retrieval` always returns the top-k nearest spans, so `not_found` was unreachable and a nonsense
+query still returned a full page of clauses. No SCORE fixes this: RRF is a relabeling of the row number, cosine's
+distribution moves with model/domain/chunking, and a cross-encoder is a better number but still a number to
+threshold -- every threshold is a corpus-specific magic knob that fails silently. The generic answer is a VERDICT
+(the shape the compliance judge and answer-abstention already use): the engine decides "does this span address
+this condition?" and returns the FACT; the product keeps the matched/possible/not_found grouping (POLICY).
+
+SKILL-SPLIT (mirrors `compliance_judgment`):
+- **`span_relevance_judgment` (agent_skill)** -- the LLM relevance METHOD, authored as
+  `skills/span_relevance_judgment/SKILL.md`, applied through the model seam. Given one span's text + the
+  structured `Condition` (+ the typed properties detected on the span, as CONTEXT not proof), returns a raw
+  `RelevanceVerdict`. `build_arelevance_judge_fn` is its runtime; `structured_factory` is injected for tests.
+- The applying capability owns the guarantees the skill does not: the closed verdict vocab and the CONSERVATIVE
+  DEFAULT -- an unreadable/failed judgement maps to `uncertain` (recall-safe: a judge failure never fabricates a
+  `not_found`; the span stays visible), exactly as the compliance judge defaults to `needs_review`.
+
+`ajudge_spans` runs the judge over a retrieved set concurrently (async + semaphore + a wall-clock bound per span),
+so a sweep's wall-clock is concurrency-bound, not count-bound (the parallel-LLM rule).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Awaitable, Callable, Optional
+
+from pydantic import BaseModel
+
+from rag_wright.models.seam import build_structured
+
+_SKILL_PATH = Path(__file__).parents[1] / "skills" / "span_relevance_judgment" / "SKILL.md"
+
+
+class Relevance(str, Enum):
+    """The closed relevance vocab. `uncertain` is both a real judgement (ambiguous text) AND the conservative
+    default when the judge could not be read (recall-safe: never a fabricated not_found)."""
+
+    RELEVANT = "relevant"
+    NOT_RELEVANT = "not_relevant"
+    UNCERTAIN = "uncertain"
+
+
+_VERDICTS = {v.value for v in Relevance}
+
+
+class Condition(BaseModel):
+    """The structured test a retrieved span is judged against (issue 0023). `clause_type` is primary (a category
+    to test membership of); `value_condition` is a narrower test within it (often absent or shared across a
+    multi-condition sweep); `question` is CONTEXT ONLY -- in a multi-condition sweep it belongs to all conditions
+    at once, so it must not by itself make a span relevant. (Per-condition question decomposition is a separate
+    engine gap, not owned here.)"""
+
+    clause_type: str
+    value_condition: Optional[str] = None
+    question: Optional[str] = None
+
+
+class RelevanceVerdict(BaseModel):
+    """The raw structured output of one relevance judgement (the `span_relevance_judgment` SKILL's typed output).
+    `verdict` is a loose string mapped to the closed `Relevance` vocab by the applying capability (unreadable ->
+    uncertain, the conservative default)."""
+
+    verdict: str
+    rationale: str = ""
+    confidence: float = 0.0
+
+
+# ajudge_fn: (span_text, matched_constraints, condition) -> RelevanceVerdict. Primitives (not RankedSpan) so this
+# capability stays independent of the retrieval contract -- the subgraph adapts its spans to these inputs.
+AJudgeFn = Callable[[str, list[tuple[str, str]], Condition], Awaitable[RelevanceVerdict]]
+
+
+def _skill_body(path: Path) -> str:
+    text = path.read_text(encoding="utf-8")
+    if text.startswith("---"):
+        marker = text.find("\n---", 3)
+        if marker != -1:
+            text = text[marker + 4 :]
+    return text.strip()
+
+
+def relevance_method() -> str:
+    """The authored relevance-judgment method (skills/span_relevance_judgment/SKILL.md)."""
+    return _skill_body(_SKILL_PATH)
+
+
+_PROMPT_TAIL = (
+    "\n\nCONDITION being searched for:\n"
+    "- clause type: {clause_type}\n"
+    "- specific condition: {value_condition}\n"
+    "- user's question (CONTEXT ONLY -- may be shared across several conditions): {question}\n\n"
+    "TYPED PROPERTIES already detected on this span (CONTEXT -- extracted from the question and reused across "
+    "conditions, so evidence, NOT proof of relevance; judge the span TEXT):\n{matched}\n\n"
+    "RETRIEVED SPAN (the only text you may judge):\n{span}"
+)
+
+
+def _tail(span_text: str, matched: list[tuple[str, str]], condition: Condition) -> str:
+    matched_str = ", ".join(f"{d} = {v}" for d, v in matched) if matched else "(none)"
+    return _PROMPT_TAIL.format(
+        clause_type=condition.clause_type,
+        value_condition=condition.value_condition or "(none -- judge against the clause type)",
+        question=condition.question or "(none)",
+        matched=matched_str,
+        span=span_text,
+    )
+
+
+def build_arelevance_judge_fn(model_id: str, *, structured_factory=build_structured) -> AJudgeFn:
+    """The `span_relevance_judgment` SKILL runtime: an async relevance judge through the model seam. Given a span's
+    text + the typed properties detected on it (context) + the structured condition, returns a raw
+    `RelevanceVerdict`. `structured_factory` is injected for hermetic tests."""
+    method = relevance_method()
+
+    async def judge(span_text: str, matched: list[tuple[str, str]], condition: Condition) -> RelevanceVerdict:
+        # label names the generation (ADR-0058 / issue 0025) so a reader tells `span-relevance` from
+        # `query-constraints` in the cost report; ignored by the hermetic stub factory.
+        return await structured_factory(model_id, RelevanceVerdict, label="span-relevance").ainvoke(
+            method + _tail(span_text, matched, condition))
+
+    return judge
+
+
+def to_relevance(raw: str) -> Relevance:
+    """Map the LLM's loose verdict string to the closed vocab; unreadable -> uncertain (conservative default:
+    recall-safe, so a mis-read never fabricates a not_found)."""
+    value = (raw or "").strip().lower().replace("-", "_").replace(" ", "_")
+    return Relevance(value) if value in _VERDICTS else Relevance.UNCERTAIN
+
+
+def finalize_verdict(raw: Optional[RelevanceVerdict]) -> RelevanceVerdict:
+    """The deterministic guarantees the SKILL does not own (the applying-capability step): map the raw verdict to
+    the closed vocab (unreadable/None -> `uncertain`, the conservative recall-safe default) and clamp confidence to
+    [0, 1]. Mirrors `compliance_judgment.assemble_finding`'s conservative mapping."""
+    if raw is None:
+        return RelevanceVerdict(verdict=Relevance.UNCERTAIN.value, rationale="relevance judge did not rule",
+                                confidence=0.0)
+    return RelevanceVerdict(verdict=to_relevance(raw.verdict).value, rationale=raw.rationale,
+                            confidence=min(1.0, max(0.0, raw.confidence)))
+
+
+_JUDGE_TIMEOUT_S = float(os.environ.get("RAG_RELEVANCE_TIMEOUT_S", "90"))  # per-span wall-clock bound
+
+
+async def ajudge_spans(
+    spans: list[tuple[str, list[tuple[str, str]]]], condition: Condition, *, ajudge_fn: AJudgeFn,
+    max_concurrency: int = 8, timeout_s: float | None = _JUDGE_TIMEOUT_S, timeout_retries: int = 1,
+) -> list[RelevanceVerdict]:
+    """Judge many retrieved spans against one condition CONCURRENTLY (asyncio.gather + Semaphore, the parallel-LLM
+    rule), order preserved. Each `spans` item is `(span_text, matched)`. Each judgement is bounded by `timeout_s`
+    (a hard wall-clock deadline); on the deadline it is retried up to `timeout_retries` times, then falls back to a
+    conservative `uncertain` verdict -- a stalled provider never hangs the sweep. A NON-timeout judge error
+    propagates (a genuine bug is never masked). Every returned span gets a verdict: the list is 1:1 with `spans`."""
+    semaphore = asyncio.Semaphore(max_concurrency)
+
+    async def _rule(span_text: str, matched: list[tuple[str, str]]) -> RelevanceVerdict:
+        if timeout_s is None:
+            return await ajudge_fn(span_text, matched, condition)
+        for attempt in range(timeout_retries + 1):
+            try:
+                async with asyncio.timeout(timeout_s):
+                    return await ajudge_fn(span_text, matched, condition)
+            except (asyncio.TimeoutError, TimeoutError):
+                if attempt >= timeout_retries:
+                    return RelevanceVerdict(verdict=Relevance.UNCERTAIN.value,
+                                            rationale="relevance judge timed out", confidence=0.0)
+        return RelevanceVerdict(verdict=Relevance.UNCERTAIN.value, rationale="relevance judge timed out")
+
+    async def _one(item: tuple[str, list[tuple[str, str]]]) -> RelevanceVerdict:
+        span_text, matched = item
+        async with semaphore:
+            return await _rule(span_text, matched)
+
+    return list(await asyncio.gather(*(_one(item) for item in spans)))
+
+
+def register_span_relevance_judgment(registry) -> None:
+    """Register `span_relevance_judgment` as an AGENT_SKILL (issue 0023, ADR-0088): a single grounded LLM relevance
+    judgement, authored as `skills/span_relevance_judgment/SKILL.md` and applied via the seam. Output =
+    `RelevanceVerdict`. Promoted to a canonical FR-C slug (`CANONICAL_CAPABILITY_SLUGS`), the same way every
+    post-v0.1 capability (compliance module, KG-primary retrieval core) was added -- registry mirror + ADR."""
+    registry.register(
+        "span_relevance_judgment",
+        contract=RelevanceVerdict,
+        kind="agent_skill",
+        display_name="Span relevance judgment (span x condition -> verdict; authored skill)",
+    )