eval-toolkit 1.0.0__tar.gz → 1.0.2__tar.gz

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/CHANGELOG.md

@@ -5,6 +5,92 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] — 2026-05-26 — #76 cleanup batch closes (RC2 + RC3 + F-metrics-1/3/4)
+
+Closes the GH #76 v1.0.1 cleanup tracker. All 6 items shipped across
+v1.0.1 (RC4) and v1.0.2 (this release). All P3, all NON-BREAKING.
+
+### Changed (Tier-2 ADDITIVE: contract clarification only)
+
+- **RC2** (#76) — `SimilarityStrategy` Protocol promoted from
+  "pre-v0.7 internal interface" (prose framing only) to formal
+  10th strict Tier-2 Protocol per [ADR 0003](docs/source/adr/0003-stability-contract-and-gate3-methodology.md).
+  Aligns prose surfaces (README, extending.md, strict_tier2_protocols.md,
+  api/protocols.md, ADR 0004 §D6, roadmap.md) with the contract
+  already locked in `tests/golden/public_api/snapshot.json` +
+  `src/eval_toolkit/__init__.py:_EXPORTS` since v1.0.0. **No code
+  change — documentation-only reconciliation.** Strict-Tier-2 count
+  goes 9 → 10 (+ 1 opt-in `Versioned`).
+
+### Fixed
+
+- **RC3** (#76) — `tests/test_harness_folded.py::test_evaluate_folded_reseed_splitter_varies_partitions`
+  test hardening. Previous assertions covered count + key existence
+  only; a regression silently reusing the splitter (R8-C1 pre-fix
+  behavior) could still pass. v1.0.2 adds row-content comparison:
+  replays `reseed_splitter` against the splitter for `seed=1` vs
+  `seed=2` and asserts fold-0 test partitions differ via feature-text
+  set membership (robust to `_slice_subset`'s `reset_index(drop=True)`
+  via stable text-column identifiers).
+
+- **F-metrics-1** (#76) — `brier_score` docstring input-domain clarity.
+  Added explicit "Input domain" Notes subsection clarifying binary
+  labels in `{0, 1}` + calibrated probabilities in `[0, 1]` are
+  required; raw logits or unbounded ranking scores pass the finiteness
+  check but produce out-of-range MSE that misrepresents calibration
+  quality. Includes calibration-applying recipe pointer.
+
+- **F-metrics-3** (#76) — `expected_calibration_error` docstring
+  uniform-scores note. Added explicit Notes subsection documenting
+  that constant `y_score` returns 0.0 (per-bin formula trivially
+  satisfied) but is semantically misleading — uninformative scorers
+  look "perfectly calibrated" despite zero discriminative power.
+  Callers should filter constant inputs before ECE.
+
+- **F-metrics-4** (#76) — `brier_score` docstring single-class
+  edge-case explicit. Added Notes subsection with closed-form
+  expressions for all-zeros (`BS = mean(p²)`) and all-ones
+  (`BS = mean((1-p)²)`) cases. Explicit confirmation that
+  per-slice degenerate-class evaluation is supported (unlike
+  PR-AUC / ROC-AUC).
+
+## [1.0.1] — 2026-05-25 — audit_citation_alignment + RC4 docs polish
+
+First v1.x patch release. Ships the `audit_citation_alignment` validator
+that's been pre-staged by consumer `prompt-injection-detection-prototype`
+(see #77), plus the smallest #76 cleanup item (RC4).
+
+### Added
+
+- **`audit_citation_alignment` module** — flat-module per [ADR 0001](docs/source/adr/0001-flat-module-layout.md)
+  (stay-flat-through-v1.x; subpackage restructure deferred to v2.0).
+  Exports `validate_citations(...)`, `ADRSubject`, `CitationMisalignment`,
+  and `extract_adr_subject_category` as Tier 1 STRICT (per
+  [ADR 0003](docs/source/adr/0003-stability-contract-and-gate3-methodology.md)).
+  Validator catches the bug class where a markdown surface cites "per
+  ADR-NNN" but the cited ADR's actual subject doesn't match the
+  surrounding claim category — motivated by the V1.3.2 P1-2 finding in
+  the consumer `prompt-injection-detection-prototype` audit where
+  `docs/REPRODUCIBILITY.md:76` cited ADR-029 (test markers) for a
+  tier-lock claim that should have cited ADR-034 (reproducibility tier
+  ladder). The mis-citation went undetected by lychee (URL-resolves
+  check), consumer's `audit_numbers.py` (numeric values), and consumer's
+  `audit_adr_count_claims.py` (count claims). Closes #73.
+- **Pre-tag dogfood**: `validate_citations()` exercised against
+  eval-toolkit's own docs (95 files including README + audit_findings +
+  methodology + migration guides) — 0 misalignments found. Validator
+  proven in production use before consumers adopt.
+
+### Fixed
+
+- **RC4** (#76 cleanup) — v0.51 documentation count-tally reconciliation
+  across `docs/source/audit_findings.md`, `docs/source/migration/v0.51.md`,
+  and `CHANGELOG.md` `[0.51.0]` section. Canonical tally now consistent:
+  **13 confirmed → fixed in v0.51 / 3 refuted (R8-G2 + R8-G5 + R8-V1+V2
+  paired) / 2 deferred (R8-G3, R8-G4) = 18 total**. Prior drift was
+  "left 2 undecided" (migration/v0.51) vs "deferred" (CHANGELOG) +
+  ambiguity in the audit_findings ship-status section. Closes RC4 of #76.
+
 ## [1.0.0] — 2026-05-25 — Stability contract activates per ADR 0003
 
 v1.0 is a **stability-contract activation**, not a code delta from v0.51.

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eval-toolkit
-Version: 1.0.0
+Version: 1.0.2
 Summary: Reusable evaluation contracts for binary classification: metrics, bootstrap CIs, calibration, artifacts, and evidence gates.
 Project-URL: Homepage, https://github.com/brandon-behring/eval-toolkit
 Project-URL: Documentation, https://brandon-behring.github.io/eval-toolkit/
@@ -115,7 +115,8 @@ format changes.
 ├─ Tier 2 ─ Protocol-based orchestration ────────────────┤
 │  Scorer / SliceAwareScorer / LeakageCheck / Splitter   │
 │  ThresholdSelector / DatasetLoader / MetricSpec        │
-│  MetaLearner / Probe / TextTransform (9 strict)        │
+│  MetaLearner / Probe / TextTransform /                 │
+│  SimilarityStrategy (10 strict)                        │
 │  Versioned (opt-in: per-object versions in manifest)   │
 ├─ Tier 1 ─ Functional core ─────────────────────────────┤
 │  pr_auc / roc_auc / ECE variants / Brier / bootstrap_ci│

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/README.md

@@ -32,7 +32,8 @@ format changes.
 ├─ Tier 2 ─ Protocol-based orchestration ────────────────┤
 │  Scorer / SliceAwareScorer / LeakageCheck / Splitter   │
 │  ThresholdSelector / DatasetLoader / MetricSpec        │
-│  MetaLearner / Probe / TextTransform (9 strict)        │
+│  MetaLearner / Probe / TextTransform /                 │
+│  SimilarityStrategy (10 strict)                        │
 │  Versioned (opt-in: per-object versions in manifest)   │
 ├─ Tier 1 ─ Functional core ─────────────────────────────┤
 │  pr_auc / roc_auc / ECE variants / Brier / bootstrap_ci│

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/src/eval_toolkit/__init__.py

@@ -52,6 +52,14 @@ _EXPORTS: dict[str, str] = {
     # CharacterInjectionStrategy + character_injection SimpleNamespace
     # removed at v0.47 (Decision N + plan §4E). TextTransform Protocol +
     # the 12 concrete dataclasses are now the only public path.
+    # --- audit_citation_alignment ---
+    # Flat-module per ADR 0001 (Stay flat through v1.x; subpackage
+    # restructure deferred to v2.0). Closes #73. Motivated by consumer
+    # V1.3.2 P1-2 ADR-029 mis-citation finding.
+    "ADRSubject": "eval_toolkit.audit_citation_alignment",
+    "CitationMisalignment": "eval_toolkit.audit_citation_alignment",
+    "extract_adr_subject_category": "eval_toolkit.audit_citation_alignment",
+    "validate_citations": "eval_toolkit.audit_citation_alignment",
     # --- losses ---
     "RecallAtLowFPR": "eval_toolkit.losses",
     # --- preprocessing ---

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/src/eval_toolkit/_version.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "1.0.0"
+__version__ = "1.0.2"

eval_toolkit-1.0.2/src/eval_toolkit/audit_citation_alignment.py

@@ -0,0 +1,301 @@
+r"""ADR-citation alignment validator.
+
+Catches the bug class where a reader-facing markdown surface cites
+"per ADR-NNN" but the cited ADR's actual subject doesn't match the
+surrounding claim category.
+
+Motivating test case (from `prompt-injection-detection-prototype` v1.3.2
+audit, file `docs/REPRODUCIBILITY.md:76`)::
+
+    "Two-tier reproduction (locked at Phase 0-07 via ADR-029):"
+
+ADR-029 is the test-marker-strategy ADR (unit / smoke / integration /
+network markers). The actual reproducibility-tier-lock ADR is ADR-034.
+The citation is wrong by 5 digits, with surrounding context "Two-tier
+reproduction" clearly in the *reproducibility* category, not the
+*test_markers* category. :func:`validate_citations` flags this case.
+
+Design (per ADR 0001 contract-first; ADR 0002 metric-spec style for the
+configurable categories):
+
+- The validator is **pure**: pass in markdown text + ADR frontmatter +
+  a category-keyword map; get back a list of
+  :class:`CitationMisalignment` records. No filesystem I/O inside the
+  validator; the CLI wrapper handles globbing.
+- Categories are **consumer-supplied**: this module ships no default
+  category map. Consumers wire their project's claim taxonomy
+  (reproducibility / cost / calibration / threshold / contamination /
+  test_markers / leakage / etc.) into the validator.
+
+References
+----------
+.. [1] Nygard, M. "Documenting Architecture Decisions." 2011.
+    https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+# Default citation pattern: matches "per ADR-NNN", "via ADR-NNN", "by ADR-NNN",
+# "under ADR-NNN" — case-insensitive on the citation phrase; ADR-NNN is
+# 3-digit-zero-padded by Nygard convention.
+DEFAULT_CITATION_PATTERN: Final[str] = r"(?i)(?:per|via|by|under)\s+ADR-(\d{3})"
+
+# Sniff radius around a citation match for category-keyword matching.
+# Locked at ±2 lines so the validator catches citations whose claim
+# category is on the immediately-adjacent line (common in Markdown
+# tables / bullet lists / wrapped prose).
+DEFAULT_CONTEXT_LINES: Final[int] = 2
+
+
+@dataclass(frozen=True)
+class ADRSubject:
+    """Subject category of a single ADR.
+
+    Parameters
+    ----------
+    adr_id : str
+        3-digit-zero-padded ADR id, e.g. ``"029"``.
+    title : str
+        ADR title (from frontmatter ``title:`` field).
+    slug : str
+        ADR slug (from frontmatter ``slug:`` field). Often informative
+        about the actual subject.
+    category : str | None
+        Claim-taxonomy category the ADR belongs to (e.g.
+        ``"test_markers"``, ``"reproducibility"``, ``"cost"``). ``None``
+        if no category matched the ADR's title/slug keywords (caller
+        decides whether to treat ``None`` as a finding or skip).
+    """
+
+    adr_id: str
+    title: str
+    slug: str
+    category: str | None
+
+
+@dataclass(frozen=True)
+class CitationMisalignment:
+    """A "per ADR-NNN" citation whose category doesn't match the cited ADR's subject.
+
+    Parameters
+    ----------
+    file : Path
+        Reader-facing markdown file the citation appears in.
+    line : int
+        1-indexed line number of the citation.
+    cited_adr_id : str
+        3-digit-zero-padded ADR id from the citation.
+    surrounding_text : str
+        ≤120 chars of context around the citation (for human review).
+    claim_category : str | None
+        Category inferred from the surrounding text (None if no
+        category keyword matched).
+    adr_actual_category : str | None
+        Category inferred from the cited ADR's title+slug (None if no
+        category keyword matched).
+    """
+
+    file: Path
+    line: int
+    cited_adr_id: str
+    surrounding_text: str
+    claim_category: str | None
+    adr_actual_category: str | None
+
+
+def extract_adr_subject_category(
+    title: str,
+    slug: str,
+    category_keywords: dict[str, list[str]],
+) -> str | None:
+    """Infer an ADR's claim-taxonomy category from its title + slug.
+
+    Walks each ``(category, keywords)`` entry in ``category_keywords``
+    and returns the first category whose keywords appear in the
+    concatenated title+slug (case-insensitive).
+
+    Parameters
+    ----------
+    title : str
+        ADR title from frontmatter.
+    slug : str
+        ADR slug from frontmatter or filename.
+    category_keywords : dict[str, list[str]]
+        Map from category name to a list of keyword substrings. First
+        keyword match wins; categories are tested in dict-insertion
+        order, so the caller controls priority.
+
+    Returns
+    -------
+    str | None
+        Matching category name, or ``None`` if no keyword matched.
+
+    Examples
+    --------
+    >>> extract_adr_subject_category(
+    ...     title="Reproducibility tier - full ladder T0 + T1 + T3",
+    ...     slug="reproducibility-tier-full-ladder",
+    ...     category_keywords={
+    ...         "test_markers": ["marker", "smoke marker"],
+    ...         "reproducibility": ["reproduc", "tier"],
+    ...     },
+    ... )
+    'reproducibility'
+    """
+    haystack = f"{title} {slug}".lower()
+    for category, keywords in category_keywords.items():
+        for keyword in keywords:
+            if keyword.lower() in haystack:
+                return category
+    return None
+
+
+def _extract_context_text(
+    lines: list[str],
+    line_index: int,
+    context_lines: int,
+) -> str:
+    """Return ≤120-char snippet of context around `line_index` (1-indexed)."""
+    start = max(0, line_index - 1 - context_lines)
+    end = min(len(lines), line_index + context_lines)
+    return " ".join(line.strip() for line in lines[start:end])[:300]
+
+
+def _infer_claim_category(
+    context: str,
+    category_keywords: dict[str, list[str]],
+) -> str | None:
+    """Same first-match-wins keyword check as ADR subject extraction, on prose context."""
+    haystack = context.lower()
+    for category, keywords in category_keywords.items():
+        for keyword in keywords:
+            if keyword.lower() in haystack:
+                return category
+    return None
+
+
+def validate_citations(
+    *,
+    markdown_text: str,
+    markdown_path: Path,
+    adr_subjects: dict[str, ADRSubject],
+    category_keywords: dict[str, list[str]],
+    citation_pattern: str = DEFAULT_CITATION_PATTERN,
+    context_lines: int = DEFAULT_CONTEXT_LINES,
+    known_exempt_citations: Sequence[tuple[Path, int, str]] = (),
+) -> list[CitationMisalignment]:
+    """Find "per ADR-NNN" citations whose category doesn't match the cited ADR.
+
+    Parameters
+    ----------
+    markdown_text : str
+        Body of the reader-facing markdown file.
+    markdown_path : Path
+        Path of the markdown file (for misalignment.file annotation).
+    adr_subjects : dict[str, ADRSubject]
+        Map from 3-digit ADR id to :class:`ADRSubject` records. Caller
+        builds this by parsing each ADR's frontmatter; the
+        ``ADRSubject.category`` field is populated via
+        :func:`extract_adr_subject_category`.
+    category_keywords : dict[str, list[str]]
+        Map from category name to substring-keyword list (used both for
+        ADR subject inference and for surrounding-text category
+        inference). Same map MUST be used for both directions.
+    citation_pattern : str, optional
+        Regex finding the citation surface. Group 1 must capture the
+        3-digit ADR id. Default :data:`DEFAULT_CITATION_PATTERN`
+        matches "per/via/by/under ADR-NNN".
+    context_lines : int, optional
+        Number of lines (±) around the citation to consider when
+        inferring the claim category. Default
+        :data:`DEFAULT_CONTEXT_LINES` (=2).
+    known_exempt_citations : Sequence of (Path, int, str), optional
+        ``(file, line, cited_adr_id)`` tuples to skip. Useful for
+        consumers with known historical drift that's been accepted by
+        policy (e.g., immutable ADR bodies with frozen-in errors that
+        a superseding ADR has already addressed).
+
+    Returns
+    -------
+    list[CitationMisalignment]
+        One :class:`CitationMisalignment` per misaligned citation.
+        Empty if no misalignments OR no citations matched the pattern.
+
+    Notes
+    -----
+    A citation with ``claim_category=None`` (no category keyword
+    matched the surrounding context) is **NOT** flagged as a
+    misalignment. The validator defers to the caller's category map:
+    if the caller's vocabulary doesn't cover the claim, there's no
+    basis for saying the citation is misaligned. To force every
+    citation to be flaggable, the caller should ensure their
+    ``category_keywords`` has broad coverage.
+
+    Examples
+    --------
+    >>> adr_subjects = {
+    ...     "029": ADRSubject(
+    ...         adr_id="029",
+    ...         title="Test marker strategy",
+    ...         slug="test-marker-strategy",
+    ...         category="test_markers",
+    ...     ),
+    ... }
+    >>> result = validate_citations(
+    ...     markdown_text="Two-tier reproduction locked at Phase 0-07 via ADR-029.\\n",
+    ...     markdown_path=Path("docs/REPRODUCIBILITY.md"),
+    ...     adr_subjects=adr_subjects,
+    ...     category_keywords={
+    ...         "reproducibility": ["reproduc", "tier", "T0", "T1", "T3"],
+    ...         "test_markers": ["marker"],
+    ...     },
+    ... )
+    >>> len(result)
+    1
+    >>> result[0].cited_adr_id
+    '029'
+    >>> result[0].claim_category
+    'reproducibility'
+    >>> result[0].adr_actual_category
+    'test_markers'
+    """
+    exempt_set = {(str(p), ln, adr) for (p, ln, adr) in known_exempt_citations}
+    misalignments: list[CitationMisalignment] = []
+    lines = markdown_text.splitlines()
+    citation_re = re.compile(citation_pattern)
+
+    for line_no, line in enumerate(lines, start=1):
+        for match in citation_re.finditer(line):
+            adr_id = match.group(1)
+            if (str(markdown_path), line_no, adr_id) in exempt_set:
+                continue
+            subject = adr_subjects.get(adr_id)
+            if subject is None:
+                # Citation references an unknown ADR. Out of scope for
+                # this validator (a different validator should check
+                # "does ADR-NNN exist"). Skip.
+                continue
+            context = _extract_context_text(lines, line_no, context_lines)
+            claim_category = _infer_claim_category(context, category_keywords)
+            if claim_category is None:
+                # No category basis for comparison; skip per the deferral above.
+                continue
+            if claim_category == subject.category:
+                continue
+            misalignments.append(
+                CitationMisalignment(
+                    file=markdown_path,
+                    line=line_no,
+                    cited_adr_id=adr_id,
+                    surrounding_text=context,
+                    claim_category=claim_category,
+                    adr_actual_category=subject.category,
+                )
+            )
+    return misalignments

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/src/eval_toolkit/metrics.py

@@ -792,6 +792,20 @@ def expected_calibration_error(
     empirical positive rate in the bin, and :math:`\\mathrm{conf}` is the
     mean predicted score.
 
+    **Uniform / uninformative scores** (F-metrics-3 v1.0.2 clarity pass):
+    when ``y_score`` is constant (e.g., ``[0.5] * n`` — an uninformative
+    detector), this function returns ``0.0`` regardless of the true label
+    distribution. That's technically correct per the formula —
+    :math:`|\\mathrm{acc}(B_m) - \\mathrm{conf}(B_m)|` measures bin-level
+    calibration, and a single occupied bin with ``conf = base rate``
+    achieves perfect calibration locally. But it is semantically
+    misleading: an uninformative scorer looks "perfectly calibrated"
+    even though it has zero discriminative power. **Callers should
+    detect and filter uninformative inputs before passing to ECE** —
+    e.g., reject when ``np.unique(y_score).size == 1`` or when the
+    score variance is below a domain-specific threshold. Use
+    :func:`brier_score` or :func:`pr_auc` for resolution-aware metrics.
+
     References
     ----------
     .. [1] DeGroot, M. H. & Fienberg, S. E. "The comparison and evaluation of
@@ -1240,6 +1254,30 @@ def brier_score(
     -----
     .. math:: \mathrm{BS} = \frac{1}{n} \sum_i (p_i - y_i)^2
 
+    **Input domain** (F-metrics-1 v1.0.2 clarity pass): ``y_true`` must
+    be binary labels in ``{0, 1}`` (other label values raise
+    ``ValueError``). ``y_score`` must be calibrated probabilities in
+    ``[0, 1]`` — raw logits or unbounded ranking scores will pass the
+    finiteness check but produce an out-of-range MSE that misrepresents
+    calibration quality. If your scorer produces logits, apply
+    sigmoid / softmax / a fitted calibrator (see
+    :mod:`eval_toolkit.calibration`) before passing to ``brier_score``.
+
+    **Single-class behavior** (F-metrics-4 v1.0.2 clarity pass): unlike
+    PR-AUC / ROC-AUC, ``brier_score`` is well-defined when ``y_true``
+    is all-zeros or all-ones — it degenerates to the MSE around the
+    constant class label. Specifically:
+
+    - All-zeros: :math:`\mathrm{BS} = \frac{1}{n} \sum_i p_i^2` —
+      forecasting any positive probability incurs squared-error loss.
+    - All-ones: :math:`\mathrm{BS} = \frac{1}{n} \sum_i (1 - p_i)^2`
+      — forecasting low probability incurs squared-error loss.
+
+    This is the deliberate Brier-as-strict-proper-scoring-rule behavior
+    (Brier 1950). Per-slice degenerate-class evaluation is supported
+    via the ``empty_strategy`` parameter for ``n=0`` only; non-empty
+    single-class slices score normally.
+
     See Also
     --------
     eval_toolkit.metrics.brier_decomposition :

{eval_toolkit-1.0.0 → eval_toolkit-1.0.2}/tests/golden/public_api/snapshot.json

@@ -1,5 +1,6 @@
 {
   "__all__": [
+    "ADRSubject",
     "ADVANCED_TECHNIQUES",
     "ALL_TECHNIQUES",
     "ANCHOR_RE",
@@ -11,6 +12,7 @@
     "CISafeThresholdSelector",
     "CORE_TECHNIQUES",
     "CaseInjection",
+    "CitationMisalignment",
     "ClaimReport",
     "ClaimSpec",
     "CorrectionMethod",
@@ -156,6 +158,7 @@
     "evaluate_folded",
     "evaluate_scorer_on_slice",
     "external_diagnostic_gate",
+    "extract_adr_subject_category",
     "fdr_bh_correct",
     "figure_metadata",
     "file_sha256",
@@ -235,6 +238,7 @@
     "stratified_recall",
     "strict_artifact_gate",
     "sweep",
+    "validate_citations",
     "validate_manifest",
     "validate_payload",
     "validate_prediction_artifact_ref",
@@ -248,6 +252,14 @@
     "write_run_result"
   ],
   "entries": {
+    "ADRSubject": {
+      "bases": [
+        "object"
+      ],
+      "doc_first_line": "Subject category of a single ADR.",
+      "kind": "class",
+      "signature": "(adr_id: 'str', title: 'str', slug: 'str', category: 'str | None') -> None"
+    },
     "ADVANCED_TECHNIQUES": {
       "doc_first_line": "Built-in immutable sequence.",
       "kind": "value",
@@ -329,6 +341,14 @@
       "kind": "class",
       "signature": "(ratio: 'float' = 0.5, seed: 'int' = 42, name: 'str' = 'case_random') -> None"
     },
+    "CitationMisalignment": {
+      "bases": [
+        "object"
+      ],
+      "doc_first_line": "A \"per ADR-NNN\" citation whose category doesn't match the cited ADR's subject.",
+      "kind": "class",
+      "signature": "(file: 'Path', line: 'int', cited_adr_id: 'str', surrounding_text: 'str', claim_category: 'str | None', adr_actual_category: 'str | None') -> None"
+    },
     "ClaimReport": {
       "bases": [
         "object"
@@ -1353,7 +1373,7 @@
       "doc_first_line": "str(object='') -> str",
       "kind": "value",
       "type": "str",
-      "value": "'0.51.0'"
+      "value": "'1.0.2'"
     },
     "apply_operating_points": {
       "doc_first_line": "Apply fitted thresholds to a mixed-class or single-class target slice.",
@@ -1480,6 +1500,11 @@
       "kind": "function",
       "signature": "(path: 'str', *, op: \"Literal['<', '<=', '>', '>=', '=='] | None\" = None, threshold: 'float | None' = None, severity: 'GateSeverity' = 'error') -> 'EvidenceGate'"
     },
+    "extract_adr_subject_category": {
+      "doc_first_line": "Infer an ADR's claim-taxonomy category from its title + slug.",
+      "kind": "function",
+      "signature": "(title: 'str', slug: 'str', category_keywords: 'dict[str, list[str]]') -> 'str | None'"
+    },
     "fdr_bh_correct": {
       "doc_first_line": "Benjamini-Hochberg false-discovery-rate correction.",
       "kind": "function",
@@ -1875,6 +1900,11 @@
       "kind": "function",
       "signature": "(strategies: 'Sequence[TextTransform]', texts: 'Sequence[str]', *, scorer: 'Scorer | None' = None, attack_threshold: 'float | None' = None) -> 'pd.DataFrame'"
     },
+    "validate_citations": {
+      "doc_first_line": "Find \"per ADR-NNN\" citations whose category doesn't match the cited ADR.",
+      "kind": "function",
+      "signature": "(*, markdown_text: 'str', markdown_path: 'Path', adr_subjects: 'dict[str, ADRSubject]', category_keywords: 'dict[str, list[str]]', citation_pattern: 'str' = '(?i)(?:per|via|by|under)\\\\s+ADR-(\\\\d{3})', context_lines: 'int' = 2, known_exempt_citations: 'Sequence[tuple[Path, int, str]]' = ()) -> 'list[CitationMisalignment]'"
+    },
     "validate_manifest": {
       "doc_first_line": "Validate a serialized ``RunManifest`` payload.",
       "kind": "function",