rag-wright 0.1.0__py3-none-any.whl

rag_wright/ontology/template_introspect.py

@@ -0,0 +1,100 @@
+"""ADR-0066 P1b-1: introspect the hand-maintained clause extraction template (`clause_template.py`) into a
+structured field spec -- the SHARED source used by both the bootstrap emitter (writes the specs into the ttl) and
+the drift test (asserts the ttl captured them faithfully). One introspection, so emitter and test cannot diverge.
+
+Keyed by TEMPLATE FIELD (`<Model>.<field>`), because the template is not a flat dimension->field map: it has
+nested constraint models (CapConstraint/TemporalConstraint/Jurisdiction) and non-dimension fields (clause_type,
+document_reference), and field names do not uniformly match dimension values (excepts<->carve_out).
+"""
+
+from __future__ import annotations
+
+import enum
+import typing
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel
+from pydantic_core import PydanticUndefined
+
+from rag_wright.ontology import clause_template as ct
+
+# The models whose fields make up the extraction template (root + nested constraint models).
+_MODELS: tuple[tuple[str, type[BaseModel]], ...] = (
+    ("Clause", ct.Clause),
+    ("CapConstraint", ct.CapConstraint),
+    ("TemporalConstraint", ct.TemporalConstraint),
+    ("Jurisdiction", ct.Jurisdiction),
+)
+
+
+@dataclass(frozen=True)
+class TemplateFieldSpec:
+    """One field of the extraction template -- everything needed to regenerate it (P1b-2) + its knowledge."""
+
+    model: str
+    name: str
+    kind: str                       # scalar_enum | list_enum | list_str | optional_str | str | model_ref
+    default_token: str              # required | none | list | enum:<value> | model_none
+    definition: str = ""            # the field's LOOK-FOR description (verbatim; "" for the TODO gaps)
+    enum_class: str | None = None   # the Enum class name (scalar_enum / list_enum)
+    model_ref: str | None = None    # the nested model name (model_ref)
+    edge_label: str | None = None   # the docling-graph edge label (nested refs)
+    max_length: int | None = None
+    examples: tuple[str, ...] = field(default_factory=tuple)
+
+
+def _enum_class(ann: typing.Any) -> type[enum.Enum] | None:
+    for a in [ann, *typing.get_args(ann)]:
+        for b in [a, *typing.get_args(a)]:
+            if isinstance(b, type) and issubclass(b, enum.Enum):
+                return b
+    return None
+
+
+def _model_class(ann: typing.Any) -> type[BaseModel] | None:
+    for a in [ann, *typing.get_args(ann)]:
+        if isinstance(a, type) and issubclass(a, BaseModel):
+            return a
+    return None
+
+
+def _spec(model_name: str, name: str, f: typing.Any) -> TemplateFieldSpec:
+    ann = f.annotation
+    enum_cls = _enum_class(ann)
+    model_cls = _model_class(ann)
+    is_list = typing.get_origin(ann) is list
+    js = f.json_schema_extra if isinstance(f.json_schema_extra, dict) else {}
+    max_length = next((getattr(m, "max_length", None) for m in (f.metadata or [])
+                       if getattr(m, "max_length", None) is not None), None)
+
+    if model_cls is not None:
+        kind, default_token = "model_ref", "model_none"
+    elif is_list and enum_cls is not None:
+        kind, default_token = "list_enum", "list"
+    elif is_list:  # issue 0037: List[str] -- an OPEN descriptive list dim (verbatim capture, canonicalized at KG)
+        kind, default_token = "list_str", "list"
+    elif enum_cls is not None:
+        kind = "scalar_enum"
+        default_token = f"enum:{f.default.value}" if isinstance(f.default, enum.Enum) else "required"
+    else:  # str / Optional[str]
+        kind = "optional_str" if typing.get_origin(ann) is typing.Union else "str"
+        default_token = "required" if f.default is PydanticUndefined else "none"
+
+    return TemplateFieldSpec(
+        model=model_name, name=name, kind=kind, default_token=default_token,
+        definition=f.description or "",
+        enum_class=enum_cls.__name__ if enum_cls is not None else None,
+        model_ref=model_cls.__name__ if model_cls is not None else None,
+        edge_label=js.get("edge_label"),
+        max_length=max_length,
+        examples=tuple(f.examples or ()),
+    )
+
+
+def introspect_template_fields() -> list[TemplateFieldSpec]:
+    """The template's fields as structured specs (stable order: model order, then field-declaration order)."""
+    specs: list[TemplateFieldSpec] = []
+    for model_name, model in _MODELS:
+        for name, f in model.model_fields.items():
+            specs.append(_spec(model_name, name, f))
+    return specs

rag_wright/reference/__init__.py

@@ -0,0 +1,2 @@
+"""Reference-pack facades (EP-REF): thin, worked-example wrappers over the engine API for the engine's reference
+CONTRACT/COMPLIANCE domain. They show a product the exact call shape; a product owns its own seam + guardrails."""

rag_wright/reference/compliance.py

@@ -0,0 +1,41 @@
+"""EP-REF-1c: thin REFERENCE invoker wrappers for the GENERIC compliance leg -- worked examples showing a product
+the exact call shape: open a workspace, then invoke the capability BY NAME via `ainvoke_subgraph`. Each is a
+one-liner over the engine API -- no store/embedder/model-id/id-parsing. Reference-ONLY: a product owns the
+FTC-routing / ad-compliance variants (`run_ad_compliance_check`) and its guardrails/human-gate policy.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from rag_wright.api import ainvoke_subgraph
+
+
+async def invoke_compliance_check(ws: Any, *, subject_text: str, source_doc: str, k: int = 8,
+                                  sources: Optional[list[str]] = None):
+    """Check a subject TEXT against the Requirement KG -> a `ComplianceReport` (cited findings + gap matrix).
+    `sources` scopes to named policies (None = store-wide)."""
+    return await ainvoke_subgraph(
+        "compliance_check",
+        {"subject_text": subject_text, "source_doc": source_doc, "k": k, "sources": sources},
+        resources=ws)
+
+
+async def invoke_document_check(ws: Any, *, doc_name: str, data: bytes, k: int = 8,
+                                sources: Optional[list[str]] = None):
+    """Check a subject DOCUMENT (raw bytes: PDF/DOCX/HTML/TXT) against the Requirement KG -> a `ComplianceReport`."""
+    return await ainvoke_subgraph(
+        "compliance_check",
+        {"doc_name": doc_name, "data": data, "k": k, "sources": sources},
+        resources=ws)
+
+
+async def invoke_policy_ingest(ws: Any, *, source: str, sections_path: Any = None,
+                               doc_name: Optional[str] = None, data: Optional[bytes] = None):
+    """Ingest a policy into the Requirement KG -> an `IngestionReport`. Give EITHER `sections_path` (a pre-sectioned
+    eCFR-style `sections.json`) OR `doc_name` + `data` (a policy DOCUMENT's raw bytes, split at its headings)."""
+    inputs: dict = {"source": source}
+    if data is not None:
+        inputs |= {"doc_name": doc_name, "data": data}
+    else:
+        inputs["sections_path"] = sections_path
+    return await ainvoke_subgraph("compliance_ingestion", inputs, resources=ws)

rag_wright/reference/contract_seam.py

@@ -0,0 +1,123 @@
+"""EP-REF-1d: a REFERENCE product seam for the engine's CONTRACT/COMPLIANCE reference domain -- a worked example
+of what a product seam looks like AFTER the domain-agnostic separation. It is the shape EP-SEAM-3 refactors
+RuleWright's real `engine/seam.py` toward.
+
+Every method is a thin composition over the engine: `open_workspace` (tenancy = one call), the invokers
+(`ainvoke_subgraph`), the generic API reads (`entities_by_name`), and the reference-pack store extensions
+(`ContractKGStore` / `ComplianceStore`) + the compliance invoker wrappers. It holds NO `ArcadeDBStore`, embedder,
+model id, or id-string parsing -- those are engine calls.
+
+This is a worked EXAMPLE, deliberately thin. A real product adds, around these calls, the concerns marked
+`# PRODUCT OWNS:` below -- tenancy policy, scoping (`ScopeViolation`), the FTC/ad-compliance variants, the
+unknown-policy guard, presentation/citation types, caching, and routing the engine's usage/progress to its own
+telemetry. Those stay product-side; see `docs/product/seam-adaptation-guide.md`.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from rag_wright.api import (
+    EngineConfig,
+    ainvoke_subgraph,
+    aparse_document,
+    entities_by_name,
+    open_workspace,
+    source_document,
+)
+from rag_wright.capabilities.compliance_store import ComplianceStore
+from rag_wright.capabilities.contract_kg_store import ContractKGStore
+from rag_wright.reference.compliance import invoke_compliance_check, invoke_policy_ingest
+
+
+class ContractComplianceSeam:
+    """A thin reference seam over the engine for the contract/compliance reference domain."""
+
+    def __init__(self, config: EngineConfig) -> None:
+        self._config = config
+
+    # --- tenancy -------------------------------------------------------------------------------------
+    def open(self, corpus: str, *, reset: bool = False):
+        """Open a workspace for a corpus (one engine call). PRODUCT OWNS: per-tenant corpus selection + auth policy."""
+        return open_workspace(self._config, corpus=corpus, reset=reset)
+
+    # --- ingestion + query (compose the invokers) ----------------------------------------------------
+    async def ingest_contract(self, ws, doc_id: str, *, cache_dir: str, text: Optional[str] = None,
+                              path: Any = None, metadata: Optional[dict] = None):
+        """Ingest one contract: build a `SourceDocument` (docling-parse a file PATH, or wrap TEXT) then run the
+        ingestion capability. Returns the engine's `IngestionReport`. PRODUCT OWNS: the document source + progress UI
+        (the engine emits progress/usage; route it to your telemetry)."""
+        sd = (await aparse_document(doc_id, path, cache_dir=cache_dir, metadata=metadata) if path is not None
+              else source_document(doc_id, text=text or ""))
+        return await ainvoke_subgraph("contract_ingestion_pipeline",
+                                      {"document": sd, "cache_dir": cache_dir}, resources=ws)
+
+    async def ask_contract(self, ws, contract_id: str, question: str):
+        """Single-document Q&A over one contract. Returns the engine's cited answer (raw -- PRODUCT OWNS: what
+        counts as 'answered' / how to render the citations)."""
+        return await ainvoke_subgraph("intra_document_qa",
+                                      {"contract_id": contract_id, "question": question}, resources=ws)
+
+    async def search_corpus(self, ws, query: str, *, k: int = 8, documents: Optional[list[str]] = None):
+        """Corpus-wide typed/similarity retrieval (Leg B). The leg extracts the query's typed constraints itself;
+        pass `documents` to scope to a workspace's docs. PRODUCT OWNS: ranking/selection presentation."""
+        return await ainvoke_subgraph("typed_property_retrieval",
+                                      {"query": query, "k": k, "documents": documents}, resources=ws)
+
+    # --- relational / terms / citations (reference-pack store extensions over the workspace store) ----
+    def find_party(self, ws, name: str) -> list[tuple[str, str]]:
+        """A party NAME -> every `(entity_id, stored_name)` it resolves to (engine-normalized; one name can match
+        several nodes -- all are returned, never the first only)."""
+        return sorted((str(e["entity_id"]), str(e.get("name") or "")) for e in entities_by_name(ws, name))
+
+    def counterparties(self, ws, entity_id: str, *, max_hops: int = 1, documents: Optional[list[str]] = None):
+        """The parties this one has a CONTRACTS_WITH edge to (one hop by default)."""
+        return ContractKGStore(ws._store).party_counterparties(entity_id, max_hops=max_hops, documents=documents)
+
+    def affiliates(self, ws, entity_id: str, *, documents: Optional[list[str]] = None):
+        """The parties this one has an AFFILIATE_OF edge to (same corporate group -- a separate traversal)."""
+        return ContractKGStore(ws._store).party_affiliates(entity_id, documents=documents)
+
+    def contract_terms(self, ws, contract_id: str) -> list:
+        """The typed clauses of one contract (the full view -- keeps AMBIGUOUS out-of-vocab values)."""
+        return ContractKGStore(ws._store).contract_terms(contract_id)
+
+    def span_locations(self, ws, contract_id: str) -> list:
+        """Every span's position (pages/bbox/offsets) + the clause ids on it -- for a citation preview."""
+        return ContractKGStore(ws._store).span_locations(contract_id)
+
+    @staticmethod
+    def canonical_clause_type(label: str) -> Optional[str]:
+        """Map a user's clause label onto the taxonomy (alias-resolving), or None -- to validate a correction."""
+        return ContractKGStore.canonical_clause_type(label)
+
+    @staticmethod
+    def clause_type_vocabulary() -> tuple[str, ...]:
+        """Every clause type a sweep/correction UI can be scoped to."""
+        return ContractKGStore.clause_type_vocabulary()
+
+    # --- compliance (reference invoker wrappers + the read facade) -----------------------------------
+    async def ingest_policy(self, ws, *, source: str, sections_path: Any = None,
+                            doc_name: Optional[str] = None, data: Optional[bytes] = None):
+        """Ingest a policy into the Requirement KG (sections.json OR a document's bytes). Returns an
+        `IngestionReport`. PRODUCT OWNS: the unknown-policy guard / curation workflow."""
+        return await invoke_policy_ingest(ws, source=source, sections_path=sections_path,
+                                          doc_name=doc_name, data=data)
+
+    async def check(self, ws, *, subject_text: str, source_doc: str, k: int = 8,
+                    sources: Optional[list[str]] = None):
+        """Check a subject against the Requirement KG -> a `ComplianceReport` (the GENERIC verdict). PRODUCT OWNS:
+        the FTC/ad-compliance tuned variant (`run_ad_compliance_check`), the unknown-policy guard, the human gate."""
+        return await invoke_compliance_check(ws, subject_text=subject_text, source_doc=source_doc,
+                                             k=k, sources=sources)
+
+    def requirements_for(self, ws, source: str) -> list[dict]:
+        """The curated requirement rows under one policy (the proof an ingest landed)."""
+        return ComplianceStore(ws._store).requirements_for(source)
+
+    def requirement_locations(self, ws, source: str) -> list:
+        """Where each requirement of one policy sits in its document (pages + bbox) -- for a citation preview."""
+        return ComplianceStore(ws._store).requirement_locations(source)
+
+    def curated_requirement_count(self, ws, sources: Optional[list[str]] = None) -> int:
+        """How many requirements are in scope -- the denominator of an honest coverage statement."""
+        return ComplianceStore(ws._store).curated_requirement_count(sources)

rag_wright/skills/__init__.py

@@ -0,0 +1,7 @@
+"""Authored skill content built as ordinary software.
+
+Holds the RLM skill (FR-C.10): an authored SKILL.md teaching the divide-and-conquer method
+(load a working set into an interpreter, slice and dispatch the work in code, synthesize the
+results). Used by the RLM chunking capability (ingestion) and the RLM synthesis capability
+(query). It is not provided by any build tool and is not a compiler feature in this repo.
+"""

rag_wright/skills/claim_extraction/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: claim_extraction
+description: >
+  The subject-document claim-extraction method: read an advertisement and pull out its distinct CHECKABLE
+  claims (the assertions a regulator could test), each with its kind, the disclosures present near it, and
+  whether the ad references evidence. Applied by the compliance_check subgraph (subject side). The schema is
+  the co-located asset `template.py` (ExtractedAd / ExtractedClaim); the deterministic mapping to the closed
+  Claim vocab is the claim_adaptation FUNCTION's job, not this skill's.
+---
+
+# Claim extraction: what checkable claims does this ad make?
+
+This skill teaches a **method**, not a behavior. It turns a subject advertisement into the checkable claims the
+compliance check will judge. It is authored software (an Agent Skill), with its extraction **schema** as the
+co-located asset **`template.py`** (`ExtractedAd` → `ExtractedClaim[]`), referenced here and filled by the model.
+
+## What to extract (the schema — `template.py`)
+
+Per ad, produce an `ExtractedAd` whose `claims` are the distinct **checkable** assertions. For each claim:
+
+- **assertion_text** — the claim itself, quoted or closely paraphrased; one claim per entry.
+- **claim_type** — the kind, from the closed vocab: `efficacy, comparative, pricing, health, environmental,
+  endorsement, performance, guarantee`.
+- **disclosures_present** — any disclaimers/qualifiers near the claim: `#ad`, `paid partnership`, `results vary`.
+- **evidence_referenced** — whether the ad points to a study/data for the claim.
+- **actor / subject_product / quantitative_value / medium** — when present.
+
+Extract the **checkable** assertions (a regulator could test them), not pure subjective flourish — but when in
+doubt, extract it; the judgment step decides puffery vs objective claim.
+
+## The reliability method (docling-graph, from GP-1B)
+
+The extractor runs through docling-graph in API mode. Three settings are load-bearing and must not drift:
+
+1. **source must be a file path**, not a raw string — docling-graph `stat()`s it (write the text to a temp file).
+2. **`structured_output=False`** (json_object) — the strict nested json_schema returns nothing on some models;
+   json_object is reliable across DeepSeek / Gemma / Granite.
+3. **a `max_tokens` cap** — an unknown provider else gets a generic 8192 context window and SKIPS the LLM.
+
+Ads are short, so `extraction_contract="direct"` (one call) is correct here.
+
+## What this skill does NOT own (the applying capability's job)
+
+- mapping `claim_type` to the closed `ClaimType` vocab and coercing an off-vocab value (kept-but-AMBIGUOUS, a
+  checkable assertion is never dropped) — the `claim_adaptation` FUNCTION;
+- the `claim_id` content-hash identity and the span provenance — the FUNCTION;
+- concurrency, timeouts, and the compliance judgment that follows — the subgraph.

rag_wright/skills/claim_extraction/__init__.py

@@ -0,0 +1 @@
+"""claim_extraction agent-skill folder: SKILL.md + the template.py schema asset."""

rag_wright/skills/claim_extraction/template.py

@@ -0,0 +1,50 @@
+"""Schema ASSET for the `claim_extraction` agent skill (referenced by this folder's SKILL.md).
+
+The docling-graph extraction template the skill fills: `ExtractedAd` (the subject ad) with its checkable
+`ExtractedClaim`s. Loose strings by design (robust to model output); the deterministic `claim_adaptation`
+FUNCTION maps them to the closed CC-1 `Claim` vocab. Co-located with the skill because the schema IS part of
+the authored extraction method (an Agent-Skill asset), not a hidden implementation detail.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rag_wright.capabilities.dg_extraction import edge
+
+
+class ExtractedClaim(BaseModel):
+    """One checkable assertion the LLM reads out of a subject ad (a docling-graph child entity)."""
+
+    model_config = ConfigDict(graph_id_fields=["assertion_text"], extra="ignore", populate_by_name=True)
+
+    assertion_text: str = Field(
+        description="One checkable factual claim the ad makes, quoted or closely paraphrased (one claim per entry)")
+    claim_type: str = Field(
+        default="",
+        description=("The kind of claim, chosen from: efficacy, comparative, pricing, health, environmental, "
+                     "endorsement, performance, guarantee"))
+    actor: str = Field(default="", description=(
+        "DEON-8: the ROLE of the party this claim involves -- a role word, NOT a person's or company's name. "
+        "Choose the general role: advertiser, endorser, expert, manufacturer, seller. (E.g. 'Dr. Miller "
+        "recommends ...' -> endorser, not 'Dr. Miller'.) Empty if no clear actor."))
+    subject_product: str = Field(default="", description="The product or brand the claim is about")
+    quantitative_value: str = Field(
+        default="", description="Any specific number/quantity claimed, e.g. '30 pounds in one month', '2x faster'")
+    disclosures_present: list[str] = Field(
+        default_factory=list,
+        description="Disclaimers/qualifiers present near the claim, e.g. '#ad', 'paid partnership', 'results vary'")
+    evidence_referenced: bool = Field(
+        default=False, description="Whether the ad references evidence/substantiation for the claim (a study, data)")
+    medium: str = Field(default="", description="The medium, e.g. social, tv, print, podcast, web")
+
+
+class ExtractedAd(BaseModel):
+    """The subject document and the distinct checkable claims it makes (the docling-graph root entity)."""
+
+    model_config = ConfigDict(graph_id_fields=["subject"], extra="ignore", populate_by_name=True)
+
+    subject: str = Field(description="A short label for the subject ad (the brand/product or a headline phrase)")
+    claims: list[ExtractedClaim] = edge(
+        "MAKES_CLAIM", default_factory=list,
+        description="The distinct checkable claims the ad makes (one entry per claim)")

rag_wright/skills/compliance_judgment/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: compliance_judgment
+description: >
+  The advertising-compliance judgment method: given ONE advertising claim and ONE applicable regulatory
+  requirement, and seeing only the ad text (never the advertiser's evidence files), decide whether the claim
+  clearly violates the requirement, clearly satisfies it, or cannot be judged from the text and must be
+  escalated for human review. Applied by the compliance_check subgraph (query side). The applying capability
+  owns the deterministic guarantees (verdict vocab, conservative default, both-sided citation) -- this skill
+  teaches only the reading.
+---
+
+# Compliance judgment: does this claim satisfy or violate this requirement?
+
+This skill teaches a **method**, not a behavior. It extends the grounding-judge idea (ADR-0028) from
+"is X supported by cue Y?" to "does claim X satisfy or violate requirement Y?". A capability applies it with
+its own contract (`ComplianceFinding`) and its own guarantees; those guarantees are the **applying
+capability's** job, not the method's (see "What this skill does NOT own").
+
+## The one hard constraint: you see only the ad text
+
+You are given the requirement and the claim. You **cannot** see the advertiser's studies, substantiation
+files, or evidence. So you can only judge what the *text itself* shows. This constraint is the whole reason the
+verdict is three-way, not two-way.
+
+## The three verdicts
+
+- **violation** — reserve this for what is **clearly wrong from the text itself**:
+  1. the claim **overclaims proof** — it asserts it is "clinically proven", "scientifically proven", "science
+     backed", "doctor proven", or "guaranteed" **without pointing to an actual study or data** (the
+     proof-language *is* the unsubstantiated claim, not evidence for it);
+  2. an endorsement is **missing a required disclosure** — no "#ad" / "paid partnership" is present when a
+     material connection would need disclosing;
+  3. a review or testimonial is **fake or deceptive**.
+
+- **needs_review** — an **objective** efficacy / health / performance / factual claim that may well be true, but
+  the ad shows **no evidence** and makes **no overclaim**. You cannot verify its substantiation from the text
+  alone, so **escalate** it: a human will check the advertiser's substantiation file. Do **not** call this a
+  violation (you don't have the evidence), and do **not** clear it as compliant (you can't confirm it either).
+
+- **compliant** — the requirement does not bite, because one of:
+  - the claim is mere **subjective opinion or taste/experience puffery** ("smooth flavor", "relaxing", "I like
+    it") — there is nothing objective to substantiate;
+  - the required **disclosure is present** (see the claim's `disclosures_present`, e.g. "#ad");
+  - the ad **actually points to real evidence** (a specific study / data / citation) for the objective claim;
+  - there is **no objective claim** to substantiate.
+
+## The discipline
+
+Only say **violation** when the text clearly shows the breach; only say **compliant** when the text clearly
+clears it; **otherwise `needs_review`**. Uncertainty is escalation, never a silent pass. Give a one-sentence
+rationale and a confidence in [0,1].
+
+## What this skill does NOT own (the applying capability's job)
+
+- the verdict **vocabulary** and the **conservative default** — an unreadable or missing verdict maps to
+  `needs_review` deterministically, in the capability, not here;
+- the **both-sided citation** — the exact claim span and the exact requirement clause are attached from the
+  INPUTS by the capability, never authored by this skill (the model rules; it never fabricates a citation);
+- the **ad-level rollup** (how many findings make an ad a violation) and the **human gate**.

rag_wright/skills/corpus_ingest/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: corpus_ingest
+description: >
+  The repeatable method for ingesting ANY new corpus of contracts into the one contract KG and
+  auto-connecting it (parties <-> clauses). Point the GENERIC ingestion pipeline
+  (contract_ingestion_pipeline) at the corpus through a single thin CorpusAdapter -- never a
+  re-implemented ingest_xyz(). Write the adapter (parse + canonical source_doc_id + optional metadata),
+  point the entity registry at the corpus's parties, and run run_corpus_ingestion; the pipeline chunks,
+  segments, function-classifies, extracts clauses + the party graph, resolves entities, and writes both. Applied over src/rag_wright/subgraphs/contract_ingestion_pipeline.py.
+---
+
+# Ingesting a new corpus into the contract KG
+
+This skill teaches a **method**, not a behavior. The design that makes it cheap: ONE generic, corpus-agnostic
+ingestion pipeline (LG-3d, `contract_ingestion_pipeline`) plus a thin per-corpus **`CorpusAdapter`**. Adding a
+corpus is one adapter — **never** a re-implemented `ingest_xyz()` that duplicates the flow. See ADR-0033
+(unified KG), HYG-1 (canonical identity), ADR-0037 (the clause template is authoritative code), and
+`docs/corpus_ingest_recipe.md` (the prose recipe this skill formalizes).
+
+## The method: one generic pipeline + one thin adapter
+
+The pipeline is fixed and shared. Everything corpus-specific lives behind one seam,
+`CorpusAdapter.documents() -> Iterable[SourceDocument]`. `SourceDocument` is `{source_doc_id, text, metadata}`.
+The pipeline, per document, runs: **chunk (semantic_chunking) → segment → LegalBERT function-classify →
+clause-extract ∥ graph-extract → entity_resolution → write (clause KG + entity graph)**. (The KG-7
+`party_clause_linking`/PartyTo post-step was retired — issue 0028 / ADR-0091 — since party→clause is reached
+via CONTRACTS_WITH provenance + the contract-scoped clause KG.)
+
+## A new *contract* corpus — 3 steps
+
+### 1. Write one `CorpusAdapter` — the ONLY new code
+`documents()` owns everything corpus-specific:
+- enumerate the corpus's files/records;
+- **parse each to text** (PDF → docling; JSON → read; …) — parsing lives here, so the pipeline is parse-agnostic;
+- assign the id via `canonical_source_doc_id(...)` (HYG-1) — this is **load-bearing**: it is what lets the new
+  corpus's clauses, spans, entities, and contracts share ONE id scheme and auto-connect. A slug that disagrees
+  with the rest (e.g. `-` for spaces instead of `_`) silently breaks the cross-graph join;
+- optionally attach corpus quirks on `SourceDocument.metadata` (annotated parties, pre-segmented spans, …).
+
+`CuadAdapter` (in `contract_ingestion_pipeline.py`) is the reference implementation.
+
+### 2. Point the entity registry at the corpus's parties
+Extend the EDGAR verified registry (`build_verified_registry`) for the corpus's public companies, or accept
+`UNLINKED` / `PRIVATE` for parties not in the registry (the honest closed-world gap).
+
+### 3. Run it (monitored)
+
+```python
+from rag_wright.subgraphs.contract_ingestion_pipeline import (
+    arun_corpus_ingestion, aproduction_document_ingest,
+)
+
+report = await arun_corpus_ingestion(
+    YourAdapter(path, limit=N),                 # test on a FEW docs first; never a full re-ingest without intent
+    aproduction_document_ingest(store, cache_dir=..., registry=...),
+)
+# report: documents_ingested, dead_lettered (per-doc), per_document
+```
+
+The ingest **extraction models are caller-configurable** (like the query/compliance entrypoints; env vars stay
+the fallback): `aproduction_document_ingest(store, cache_dir=..., registry=..., extract_model=..., list_model=...,
+samples=...)`. `extract_model` is the primary clause-property model (an `ExtractionModel` or a bare model-id
+string; default = the `RAG_SERVING` backend model, granite). `list_model` is the SECOND model for the cross-model
+UNION on the LIST-bearing dims only (carve_out / covered_subject / damage_type) — granite and gemma
+under-enumerate different list items, so their union is more complete; `"off"` disables it, default = gemma. If
+you override `extract_model` (e.g. to qwen), set `list_model` deliberately — the union only helps if the two
+models are complementary. `graph_extract_model` sets the party+affiliation extraction model (they share one),
+`judge_model` the ingest semantic-judge model, and `chunk_model` the chunker's boundary-refinement model (used
+only for over-cap sections). All accept a bare id or an `ExtractionModel` and default to their backend/env value,
+so every ingest LLM surface (clause extract + list union, party/affiliation, judge, chunk boundary, and the
+pre-existing `classify_fn`) is now a call-site argument.
+
+`run_corpus_ingestion` streams `X/N` progress; a bad document dead-letters and is skipped (one bad doc never
+kills the corpus). Write to a SCRATCH database first (`from_env(database=..., reset=True)`) to keep it
+non-destructive while proving it out.
+
+## Rules (not optional)
+
+1. **Never write an `ingest_xyz()` that re-implements the flow.** A new corpus = one `CorpusAdapter`, then
+   `run_corpus_ingestion(adapter, ...)`. If you find yourself copying the pipeline, stop.
+2. **The canonical `source_doc_id` is load-bearing.** Always derive it via `canonical_source_doc_id`; a
+   divergent slug breaks the cross-graph join (HYG-1). Every graph must share one id scheme.
+3. **Extraction is concurrent, per-item tolerant, and cached.** Clause/graph extraction runs under
+   `map_concurrent` (granite is ~10s/single call); a truncated/failed span is SKIPPED, not fatal to the
+   document; and each successful extraction is cached by clause-id + template-schema-version, so a re-run or a
+   template change re-extracts only what it must.
+4. **Long-running runs stream `X/N` and are actively monitored** (CLAUDE.md) — never launch-and-forget.
+5. **The clause template is authoritative code, not regenerated** (ADR-0037); tune extraction by editing
+   `clause_template.py`, never by chasing a regeneration from the `.ttl`/spec.
+
+## A new *domain* (non-contract)
+The pipeline *structure* stays; the capabilities it binds change: a **new extraction template** (bootstrap a
+fresh `.py` from a new ontology, then hand-maintain it — ADR-0037), a **retrained/replaced function classifier**
+(new taxonomy), and possibly a different entity registry.
+
+## What this skill does NOT own (deferred to the pipeline / capabilities)
+- **The pipeline internals** (`build_document_ingest` graph, dead-letter, the extraction seams) — LG-3d.
+- **The extraction capabilities** — semantic_chunking, the function classifier, clause extraction (docling-graph
+  + granite, ADR-0037 template), GP-1B graph_extraction (ADR-0035), entity_resolution.
+- **The span/embedding retrieval index** — wired into the pipeline as a parallel `index_spans` branch off the
+  shared `segment` node (INGEST-REFACTOR phase 2a); a corpus now gets the typed KG + entity graph + the
+  dense/sparse retrieval index in one pass. Indexing is best-effort (a failed index degrades to 0 spans, never
+  dead-letters the document's KG).
+
+The method is: parse behind the adapter, one canonical id, run the generic pipeline, connect once. Keep this
+file about that shape; the pipeline supplies the flow, the capabilities, and the tests.

rag_wright/skills/extraction_semantic_judge/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: extraction_semantic_judge
+description: >
+  The clause-property faithfulness method: given ONE extracted property (a dimension = a value) and the clause
+  text it was extracted from, decide whether a careful reading of THIS clause genuinely SUPPORTS that property.
+  For the closed SEMANTIC dimensions (mutuality, favorability, party_asymmetry, cap_basis, the consent regimes)
+  whose value is a reading with no surface token, this is what the lexical and symbolic gates cannot reach.
+  Layer 3 of the neuro-symbolic extraction-fidelity cascade (ADR-0040). The applying capability owns the
+  deterministic guarantees (which dimensions are semantic, the AMBIGUOUS downgrade, concurrency) -- this skill
+  teaches only the reading.
+---
+
+# Extraction semantic judge: does this clause support this property?
+
+This skill teaches a **method**, not a behavior. It extends the grounding-judge idea (ADR-0028) from
+"is X supported by cue Y in the text?" to the harder **semantic** case: "does a faithful reading of THIS clause
+support the property (dimension = value) that was extracted from it?" A capability applies it with its own
+contract (`ClausePropertyRecord`) and its own guarantees; those guarantees are the **applying capability's**
+job, not the method's (see "What this skill does NOT own").
+
+## What you are judging
+
+You are given one extracted **property** as `dimension = value` (with a short plain-language meaning of what
+that property claims about the clause) and the **clause text**. These are the closed SEMANTIC dimensions:
+`mutuality` (obligation runs both ways vs one), `favorability` (which side a term favors), `party_asymmetry`,
+`cap_basis` (fixed_fee vs multiple_of_fees), the governing-law multiplicity, IP ownership, the non-solicit
+target, the renewal mechanism, the change-of-control / assignment consent regimes, the MFN scope, the
+termination right. Their value is a **reading** of the clause, not a token you can grep for -- which is exactly
+why a model is spent here and nowhere else in the cascade.
+
+## The one hard rule: strictness
+
+Decide **supported=true** only if the clause **genuinely** supports the property. Decide **supported=false**
+if the clause does not support it or contradicts it. Be strict:
+
+- **mere plausibility is not support** -- that a mutual reading is *possible* is not enough; the clause must
+  actually bear it;
+- **absence of support in this clause means supported=false** -- if the text is silent on what the property
+  asserts, it is not supported. Do not import world knowledge or the "usual" drafting; judge only THIS clause.
+
+A `false` verdict means the reading is unsupported by the text; the applying capability will downgrade that
+assertion to AMBIGUOUS (kept but flagged), never delete it. Give a one-sentence reason.
+
+## What this skill does NOT own (the applying capability's job)
+
+- **which dimensions are semantic** -- the set of dimensions this judge runs on (closed vocabulary, no lexical
+  cue) is selected deterministically by the capability, not decided here;
+- the **AMBIGUOUS downgrade** and the "leave untouched on a judge error / no ruling" conservative rule --
+  applied by the capability, not by this method;
+- the **per-assertion dispatch and concurrency** -- the capability runs this reading over each surviving
+  (non-AMBIGUOUS) semantic assertion; the method judges exactly one at a time.

rag_wright/skills/extraction_semantic_judge/__init__.py

@@ -0,0 +1 @@
+"""extraction_semantic_judge agent-skill folder: SKILL.md (the clause-property faithfulness method)."""