psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/_claim_audit_constants.py

@@ -0,0 +1,268 @@
+"""Shared constants for v3.8 claim-faithfulness audit.
+
+Single source of truth for the literals + regexes that appear in BOTH the
+lint (`check_claim_audit_consistency.py`) and the pipeline runtime
+(`claim_audit_pipeline.py`). Re-declaring these in both places opens a
+drift hole — a spec bump that updates the lint without updating the
+runtime would change one side silently. Tests cover both call sites; the
+shared import binds them.
+
+See docs/design/2026-05-15-issue-103-claim-alignment-audit-spec.md §3.1
+(matrix + INV catalogue) and §4 step 3 (sampling) for canonical
+definitions.
+"""
+from __future__ import annotations
+
+import re
+
+# Canonical sentinel for the MANIFEST-MISSING fallback path (spec §3.1 INV-15).
+SENTINEL_MANIFEST_ID = "M-0000-00-00T00:00:00Z-0000"
+
+# INV-6 canonical rationale prefix (v3.7.3 R-L3-1-A firm rule).
+INV6_RATIONALE_PREFIX = "v3.7.3 R-L3-1-A violation"
+
+# INV-14 audit-tool-failure rationale fault-class tags.
+INV14_FAULT_CLASS_TAGS: tuple[str, ...] = (
+    "judge_timeout",
+    "judge_api_error",
+    "judge_parse_error",
+    "cache_corruption",
+    "retrieval_api_error",
+    "retrieval_timeout",
+    "retrieval_network_error",
+)
+
+# Sampling strategy literal (S-INV schema constant).
+SAMPLING_STRATEGY = "stratified_buckets_v1"
+
+# Sub-claim breakdown sub_verdict enum (claim_audit_result.schema.json #213).
+# The "non-SUPPORTED" set is the valid OPPOSING verdicts only — a missing or
+# out-of-enum sub_verdict must NOT count as non-SUPPORTED, or a degenerate
+# breakdown `[SUPPORTED, <missing>]` would masquerade as true-partial.
+SUBCLAIM_VERDICTS: frozenset[str] = frozenset({"SUPPORTED", "UNSUPPORTED", "AMBIGUOUS"})
+SUBCLAIM_NON_SUPPORTED: frozenset[str] = frozenset({"UNSUPPORTED", "AMBIGUOUS"})
+
+
+def is_true_partial_breakdown(breakdown: object) -> bool:
+    """True iff `breakdown` is a well-formed true-partial decomposition (#213).
+
+    Single source of truth for the INV-19 true-partial test, shared by the lint
+    (`check_claim_audit_consistency.py`), the runtime
+    (`claim_audit_pipeline.py` PARTIAL normalization + judge-output validation),
+    and the calibration subset metric (`claim_audit_calibration.py`). A list of
+    >=2 dict items whose sub_verdicts include >=1 SUPPORTED AND >=1 valid
+    non-SUPPORTED ({UNSUPPORTED, AMBIGUOUS}). A missing / out-of-enum sub_verdict
+    is NOT counted as non-SUPPORTED.
+
+    NOTE: this is the *content-shape* gate only. The lint additionally pins the
+    enclosing row's judgment/defect_stage (INV-19) and the calibration subset
+    metric additionally matches the breakdown against each fixture's expected
+    sub-claims — neither of those belongs here.
+    """
+    if not isinstance(breakdown, list) or len(breakdown) < 2:
+        return False
+    verdicts = [item.get("sub_verdict") for item in breakdown if isinstance(item, dict)]
+    has_supported = any(v == "SUPPORTED" for v in verdicts)
+    has_non_supported = any(v in SUBCLAIM_NON_SUPPORTED for v in verdicts)
+    return has_supported and has_non_supported
+
+
+def _is_schema_shaped_item(item: object) -> bool:
+    """True iff a breakdown item satisfies the schema item shape (#213).
+
+    Each item MUST be a dict with a non-empty-string `sub_claim_text` and a
+    `sub_verdict` in the closed enum. The runtime needs this BEFORE it copies an
+    item onto an emitted row — `is_true_partial_breakdown` only checks the verdict
+    *mix*, so a degenerate item like `{"sub_verdict": "UNSUPPORTED"}` (no text)
+    passes the mix gate but would emit `sub_claim_text: None`, a schema-invalid
+    completed row (ship-gate round-2 finding).
+
+    Validates the fields the runtime COPIES onto the row against the
+    claim_audit_result.schema.json item shape: non-empty string sub_claim_text
+    (<=1000), sub_verdict in the enum, and evidence_pointer — if present — a
+    string (<=1000) or null. Extra keys are not rejected here because the runtime
+    copy keeps only these three; but the copied fields' TYPES must be valid or a
+    wrong-typed evidence_pointer (e.g. a number) would reach a completed row and
+    violate the schema (ship-gate round-3 finding).
+    """
+    if not isinstance(item, dict):
+        return False
+    text = item.get("sub_claim_text")
+    if not isinstance(text, str) or not text.strip() or len(text) > 1000:
+        return False
+    if item.get("sub_verdict") not in SUBCLAIM_VERDICTS:
+        return False
+    if "evidence_pointer" in item:
+        ep = item["evidence_pointer"]
+        if ep is not None and (not isinstance(ep, str) or len(ep) > 1000):
+            return False
+    return True
+
+
+def is_emittable_partial_breakdown(breakdown: object) -> bool:
+    """True iff `breakdown` is true-partial AND every item is schema-shaped (#213).
+
+    The runtime validation gate before a PARTIAL is normalized onto a *completed*
+    row: it must be a genuine partial (`is_true_partial_breakdown`) AND every item
+    must carry a non-empty sub_claim_text + valid sub_verdict, so the copied row
+    satisfies the item schema. A breakdown that is true-partial by mix but has a
+    malformed item is a judge parse failure, NOT a completed row.
+    """
+    if not is_true_partial_breakdown(breakdown):
+        return False
+    return all(_is_schema_shaped_item(item) for item in breakdown)
+
+# rule_version literals for v3.8.0 release. Future revisions bump the literal
+# and require re-lint per spec §3.3 / §3.4 / §3.5.
+UNCITED_RULE_VERSION = "D4-c-v1"
+DRIFT_RULE_VERSION = "D4-a-v1"
+# v3.8.2 / #118 — uncited_audit_failure rule_version literal (§3.6).
+# Distinct prefix from D4-c-v1 (uncited_assertion D4-c detector) and
+# D4-a-v1 (constraint_violation) so the lint can route by literal.
+UAF_RULE_VERSION = "D4-c-v1-uaf-v1"
+
+# #361 — judge-prompt version, a HUMAN-READABLE LABEL ONLY. The judge prompt
+# text lives in academic-pipeline/agents/claim_ref_alignment_audit_agent.md
+# (### Step 5 — Judge invocation) and is supplied to the pipeline via an injected
+# judge_fn, so the pipeline cannot hash the prompt text itself. This literal is a
+# friendly name for the current prompt revision (e.g. the #213 Step-0
+# sub-claim-decomposition prompt); BUMP IT whenever the judge prompt changes so
+# logs/diffs read clearly. It is NO LONGER the judge-cache-key source of truth —
+# the cache key tracks JUDGE_PROMPT_SHA256 below (the prompt fingerprint), which
+# the lint keeps in lockstep with the prompt text. Decoupling the two means a
+# forgotten label bump can never leave stale cache entries valid.
+JUDGE_PROMPT_VERSION = "step0-decomp-v1"
+
+# #361 backstop: SHA-256 of the canonical judge-prompt section (the text between
+# the JUDGE-PROMPT-CANONICAL-START/END markers in
+# academic-pipeline/agents/claim_ref_alignment_audit_agent.md, stripped).
+# scripts/check_judge_prompt_version.py recomputes this hash and fails CI if it
+# drifts — forcing a human to update this hash whenever the prompt text changes.
+# This hash DOUBLES AS the judge-cache-key prompt component (the single source of
+# truth for cache invalidation): claim_audit_pipeline.py defaults
+# prompt_version to this value, so because the lint pins the hash to the prompt
+# text, any prompt edit automatically changes the cache key and invalidates stale
+# entries — no reliance on a separate human-readable label bump.
+JUDGE_PROMPT_SHA256 = "cdd5ba2d681ea6d6422a017fb122f36a9d62edb32f9d27bd98dbaad1f807b058"
+
+# Constraint id parse rules (spec §3.2 + INV-17 canonical form).
+RE_NC_CONSTRAINT = re.compile(r"^NC-C([0-9]{3,})-([0-9]+)$")
+RE_MNC_CONSTRAINT = re.compile(r"^MNC-([0-9]+)$")
+RE_CLAIM_ID = re.compile(r"^C-([0-9]{3,})$")
+
+# Schema rejects this pattern, but for malformed-on-purpose fixtures the lint
+# surfaces INV-17 explicitly before schema validation runs.
+RE_NC_INNER_HYPHEN = re.compile(r"^NC-C-[0-9]+-[0-9]+$")
+
+# ---------------------------------------------------------------------------
+# D4-c uncited-assertion detector constants (spec §"Uncited-assertion
+# detector (D4-c)" in claim_ref_alignment_audit_agent.md).
+#
+# Centralised here so pipeline runtime, lint, and detector share one source
+# of truth — a spec bump touches one literal, not three.
+# ---------------------------------------------------------------------------
+
+# Condition 1: empirical-claim verbs (case-insensitive whole-word match).
+# Spec list: showed, demonstrated, observed, proved, confirmed.
+UNCITED_EMPIRICAL_VERBS: frozenset[str] = frozenset(
+    {"showed", "demonstrated", "observed", "proved", "confirmed"}
+)
+
+# Condition 1: fuzzy English quantifier words (case-insensitive whole-word).
+# Spec list: most, several, two-thirds. Kept literal; numerical / percent
+# quantifiers are caught by RE_NUMERIC_QUANTIFIER below.
+UNCITED_FUZZY_QUANTIFIERS: frozenset[str] = frozenset(
+    {"most", "several", "two-thirds"}
+)
+
+# Condition 1: numerical quantifier regex. Spec line 250 lists three numeric
+# classes — `numbers / percentages / explicit quantifiers (50%, 67 of 100)`.
+# All three fire D4-c condition 1; the detector then applies a guard pass
+# (RE_NUMERIC_QUANTIFIER_GUARD below) that rejects matches whose surrounding
+# context proves them to be years, version triples, or section numbers
+# instead of quantifiers. Splitting into match-broadly + guard-narrowly is
+# easier to read and to test than stuffing every exclusion into a single
+# regex's negative lookaheads. The detector concatenates the matched
+# substring into trigger_tokens verbatim so the schema's minItems=1
+# invariant holds.
+RE_NUMERIC_QUANTIFIER = re.compile(
+    # Order matters: longest-prefix-first so percent and "N of M" bind
+    # before the bare-number branch swallows the leading digits.
+    r"\b\d+(?:\.\d+)?%"                  # percent quantifier
+    r"|\b\d+(?:\.\d+)?\s+of\s+\d+\b"     # "N of M" quantifier idiom
+    r"|\b\d+(?:\.\d+)*\b"                # bare number, possibly dotted
+                                          # (3+ segments routed to guard
+                                          # as version/section)
+)
+
+# Condition 1 guard: rejects bare-number matches whose surrounding context
+# identifies them as years, version triples, or section numbers — none of
+# those are quantitative claims, and treating them as such produced
+# false-positive LOW-WARN advisories before the guard landed (see codex
+# R1 P1-3). Applied AFTER RE_NUMERIC_QUANTIFIER to the matched substring +
+# its character offsets in the sentence; bare-number matches that satisfy
+# any guard branch are dropped, percent and `N of M` matches always pass
+# through.
+#
+# Guard branches:
+#   1. Standalone 4-digit year in plausible academic range (1900-2099).
+#   2. Version triple `X.Y.Z` (dotted form with 3+ segments — the broad
+#      regex captures only the first two segments, so we re-scan).
+#   3. Dotted section number `X.Y[.Z…]` (treated as section ref, not
+#      quantifier). Distinguished from version by `section` / `§` /
+#      `chapter` / `figure` / `table` cue word within a 24-char left
+#      window, OR by `v` immediately preceding (version literal).
+RE_BARE_NUMERIC_YEAR = re.compile(r"^(19|20)\d{2}$")
+RE_DOTTED_TRIPLE_OR_MORE = re.compile(r"^\d+(?:\.\d+){2,}$")
+RE_DOTTED_PAIR = re.compile(r"^\d+\.\d+$")
+RE_SECTION_CUE = re.compile(
+    r"(?:section|chapter|figure|table|fig\.|tbl\.|step|appendix|§)\s*$",
+    re.IGNORECASE,
+)
+RE_VERSION_PREFIX = re.compile(r"v\s*$", re.IGNORECASE)
+# Catches the case where Python's `\b` fails between a letter and a digit
+# (both are \w characters) — e.g. `v3.7.3` has no \b between `v` and `3`,
+# so RE_NUMERIC_QUANTIFIER starts matching from the SECOND segment (`7.3`)
+# and the guard never sees the version-triple shape. This pattern detects
+# a digit-then-dot prefix immediately attached to the left of the match.
+# Requires exactly one digit-run + `.` ending the window — combined with
+# the surrounding match (also dotted or bare number), this signals a
+# multi-segment dotted form that should be treated as a version/section
+# reference rather than a quantifier.
+RE_NUMERIC_LEFT_ATTACHED = re.compile(r"\d+\.$")
+
+# Condition 2: three-layer-citation ref-marker probe. Presence probe
+# WITHIN the v3.7.3 ref-marker namespace — accepts any `<!--ref:...-->`
+# shape where the slug payload begins with a non-whitespace character,
+# rejects HTML comments that happen to start with `ref:` but use it as
+# a label rather than a citation marker (e.g.
+# `<!-- ref: $internal.notebook.cell -->`).
+#
+# Iteration history:
+#   R0 `[^-]+`                                — rejected hyphenated slugs.
+#   R1 `[A-Za-z][A-Za-z0-9_:-]* + 0-2 tokens` — rejected digit-leading
+#                                                 slugs, plus-sign slugs,
+#                                                 and 3+ status tokens.
+#   R2 `[^>]*?`                                — too broad; matched
+#                                                 `<!-- ref: $analysis -->`
+#                                                 and similar code/internal
+#                                                 ref comments (codex
+#                                                 R3 P2-NEW-A).
+#   R3 `[^\s>][^>]*?`                          — current. Slug must begin
+#                                                 with a non-whitespace
+#                                                 non-`>` character; the
+#                                                 v3.7.3 strict validator
+#                                                 in
+#                                                 scripts/check_v3_7_3_three_layer_citation.py
+#                                                 catches any remaining
+#                                                 shape errors.
+RE_REF_MARKER = re.compile(r"<!--\s*ref:[^\s>][^>]*?-->")
+
+# Condition 3: definitional-phrase substrings (case-insensitive). Spec list:
+# `refers to`, `is defined as`, `we define`, `for the purposes of`.
+UNCITED_DEFINITION_PHRASES: tuple[str, ...] = (
+    "refers to",
+    "is defined as",
+    "we define",
+    "for the purposes of",
+)

package/vendor/ars/scripts/_e4_evidence.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Shared filesystem primitives for the E4 evidence boundary (#616)."""
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from pathlib import Path
+
+
+class EvidencePathError(ValueError):
+    """An evidence path is missing, redirected, or not a plain file/tree."""
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def lexical_path(path: Path) -> Path:
+    """Absolute lexical normalization without following symlinks."""
+    return Path(os.path.abspath(os.path.normpath(os.fspath(path))))
+
+
+def within(path: Path, root: Path) -> bool:
+    try:
+        lexical_path(path).relative_to(lexical_path(root))
+    except ValueError:
+        return False
+    return True
+
+
+def assert_no_symlink_components(path: Path, root: Path) -> None:
+    """Reject every symlink from ``root`` down to ``path`` inclusive."""
+    root = lexical_path(root)
+    path = lexical_path(path)
+    try:
+        relative = path.relative_to(root)
+    except ValueError as failure:
+        raise EvidencePathError(f"{path} escapes evidence root {root}") \
+            from failure
+    current = root
+    if current.is_symlink():
+        raise EvidencePathError(f"symlink evidence root is forbidden: {root}")
+    for part in relative.parts:
+        current = current / part
+        try:
+            mode = current.lstat().st_mode
+        except FileNotFoundError as failure:
+            raise EvidencePathError(f"evidence path does not resolve: {path}") \
+                from failure
+        if stat.S_ISLNK(mode):
+            raise EvidencePathError(
+                f"symlink evidence path is forbidden: {current}")
+
+
+def assert_plain_file(path: Path, root: Path) -> None:
+    assert_no_symlink_components(path, root)
+    try:
+        mode = lexical_path(path).lstat().st_mode
+    except FileNotFoundError as failure:
+        raise EvidencePathError(f"evidence file does not resolve: {path}") \
+            from failure
+    if not stat.S_ISREG(mode):
+        raise EvidencePathError(f"evidence path is not a regular file: {path}")
+
+
+def assert_plain_directory(path: Path, root: Path) -> None:
+    assert_no_symlink_components(path, root)
+    try:
+        mode = lexical_path(path).lstat().st_mode
+    except FileNotFoundError as failure:
+        raise EvidencePathError(
+            f"evidence directory does not resolve: {path}") from failure
+    if not stat.S_ISDIR(mode):
+        raise EvidencePathError(
+            f"evidence path is not a directory: {path}")
+
+
+def tree_manifest(root: Path, *, exclude: set[str] | None = None) -> list[dict]:
+    """Return a stable path/type/hash manifest without following links."""
+    root = lexical_path(root)
+    assert_plain_directory(root, root)
+    excluded = exclude or set()
+    entries: list[dict] = []
+    for path in sorted(root.rglob("*"), key=lambda item: item.as_posix()):
+        relative = path.relative_to(root).as_posix()
+        if relative in excluded:
+            continue
+        mode = path.lstat().st_mode
+        if stat.S_ISREG(mode):
+            entries.append({
+                "path": relative,
+                "type": "file",
+                "sha256": sha256_file(path),
+            })
+        elif stat.S_ISDIR(mode):
+            entries.append({"path": relative, "type": "directory"})
+        elif stat.S_ISLNK(mode):
+            entries.append({
+                "path": relative,
+                "type": "symlink",
+                "target": os.readlink(path),
+            })
+        else:
+            entries.append({"path": relative, "type": "other"})
+    return entries

package/vendor/ars/scripts/_eval_threshold_gate.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Absolute-threshold verdict for the eval harness (#184 Delta 3 / Fix 1).
+
+Phase 1b has no ``main`` baseline, so the CI gate is an ABSOLUTE-threshold check,
+not a lift comparison. This module reads a ``run_evals`` report and returns the
+list of measured tasks whose aggregate metric failed its declared threshold.
+
+Kept out of the workflow YAML (no inline heredoc) so the gate's only load-bearing
+logic is unit-testable rather than asserted via brittle YAML string matching.
+
+CLI::
+
+    python -m scripts._eval_threshold_gate <report.json>
+
+prints a comma-separated list of failed threshold keys —
+``<task>.aggregate.<metric>`` and ``<task>.<class>.<metric>`` (empty line if
+none) — to stdout.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def failed_tasks(report: dict[str, Any]) -> list[str]:
+    """Return one key per measured threshold that failed — aggregate AND per-class.
+
+    Only tasks with ``status == "measured"`` that declare a threshold (so the
+    measurer set ``.passed``) are gated. ``passed is False`` is the failure signal
+    — a metric without a threshold (``passed`` absent) is not gated, and a
+    pending/skipped task is never gated.
+
+    Both axes are binding: manifests declare aggregate AND per-class thresholds
+    (e.g. citation_extraction: aggregate ``accuracy >= 0.90`` plus per_class
+    ``accuracy >= 0.85``; rq_framing_patterns: ``balanced_accuracy >= 0.75`` plus
+    ``fnr <= 0.30`` / ``fpr <= 0.20`` as per_class rows). run_evals stamps
+    ``per_class[].passed`` against the per-class threshold, so the gate must honour
+    it too — else a PR that regresses only a per-class metric passes the gate when
+    it should block (#328). Aggregate failures use ``<task>.aggregate.<metric>``;
+    per-class failures use ``<task>.<class_name>.<metric>`` (matching the lift
+    gate's per-class key shape).
+    """
+    failures: list[str] = []
+    for task in report.get("per_task", []):
+        # Skip-unless-measured (symmetric with check_ranking_lift._flatten_report).
+        if task.get("status", "measured") != "measured":
+            continue
+        agg = task.get("aggregate_metric") or {}
+        if agg.get("passed") is False:
+            failures.append(f"{task['task_name']}.aggregate.{agg.get('metric', '?')}")
+        for pc in task.get("per_class", []):
+            if pc.get("passed") is False:
+                failures.append(
+                    f"{task['task_name']}.{pc.get('class_name', '?')}."
+                    f"{pc.get('metric', '?')}"
+                )
+    return failures
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1:
+        print("usage: python -m scripts._eval_threshold_gate <report.json>",
+              file=sys.stderr)
+        return 2
+    report = json.loads(open(args[0], encoding="utf-8").read())
+    print(",".join(failed_tasks(report)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/vendor/ars/scripts/_markdown_lint_util.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Shared markdown rendering semantics for the defrift lints (#771).
+
+Single authority for one question: what does GitHub render from this
+markdown? Inline code spans render literally (a link inside backticks is
+not a link) and an image `![alt](target)` renders no anchor, so both are
+excluded from the rendered link grammar. Grammar hardened under the #757 /
+#758 review rounds; consumers are check_control_availability.py,
+check_data_flows.py, check_risk_register.py, check_spec_consistency.py, and
+run_indirect_prompt_injection_probe.py.
+
+No helper writes to the filesystem or assumes a particular repository layout.
+Consumers supply every path and own their invariant-specific error wording.
+
+Modeling boundary: deeper CommonMark laminations — blocks terminated by the
+enclosing quote or list, comments opened inside list items, … — are
+deliberately not modeled. The surfaces the lints read do not use them, and a
+full markdown parser is out of proportion for a maintainer-slip guard.
+"""
+from __future__ import annotations
+
+import re
+from enum import Enum
+from pathlib import Path
+
+# [text](target) and [text](target "title") — the target is captured before
+# an optional quoted title; a titled link must not silently fall out of the
+# link-resolution invariants. (?<!\!) — an image renders no anchor.
+_LINK_RE = re.compile(r"(?<!\!)\[[^\]]*\]\(\s*([^)\s]+)(?:\s+\"[^\"]*\")?\s*\)")
+
+# Inline code spans render literally. Stripped AFTER the block-level passes
+# (a fence's contents are gone by then, so a lone backtick inside a fence
+# cannot open a phantom span).
+_CODE_SPAN_RE = re.compile(r"`([^`\n]+)`")
+
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_QUOTE_PREFIX_RE = re.compile(r"^(\s{0,3}>\s?)+")
+_HEADING_RE = re.compile(r"^#{1,6}\s+(.*)$", re.MULTILINE)
+_FENCE_OPEN_RE = re.compile(r"`{3,}|~{3,}")
+
+# Link targets that are not repo-relative paths: absolute schemes plus
+# intra-document anchors.
+NON_RELATIVE_LINK_PREFIXES = ("http://", "https://", "mailto:", "#")
+
+
+class RelativeLinkFailure(str, Enum):
+    """Closed failure vocabulary for a rendered repo-relative link."""
+
+    ESCAPES_REPOSITORY = "escapes_repository"
+    DOES_NOT_EXIST = "does_not_exist"
+    ANCHOR_ON_NON_MARKDOWN = "anchor_on_non_markdown"
+    ANCHOR_NOT_FOUND = "anchor_not_found"
+
+
+def _strip_fenced_code(md_text: str) -> str:
+    """Fenced code blocks render literally: a link or heading inside a
+    ``` / ~~~ fence counts for nothing. Runs BEFORE the comment pass, so a
+    `<!--` inside a fence stays literal text and cannot open a comment
+    block."""
+    kept: list[str] = []
+    fence: str | None = None  # the opening run, e.g. "```" or "~~~~"
+    for line in md_text.split("\n"):
+        content = _QUOTE_PREFIX_RE.sub("", line).lstrip(" ")
+        if fence is None:
+            opener = _FENCE_OPEN_RE.match(content)
+            if opener:
+                fence = opener.group(0)
+                continue
+        else:
+            # CommonMark: the closer is a run of the SAME character at least
+            # as long as the opener, with nothing but whitespace after it —
+            # so a ```` fence is not closed by a literal ``` example line.
+            if re.match(rf"{re.escape(fence[0])}{{{len(fence)},}}\s*$", content):
+                fence = None
+            continue
+        kept.append(line)
+    return "\n".join(kept)
+
+
+def _strip_html_comments(md_text: str) -> str:
+    """Non-rendering markdown counts for nothing (neither satisfying a
+    coverage invariant nor firing a resolution one).
+
+    Two GFM behaviors matter here:
+    - A line beginning with `<!--` (up to 3 leading spaces) opens a type-2
+      HTML block that runs through the line containing `-->` — or to EOF if
+      unclosed — and NOTHING on those lines renders as markdown, including
+      text after the terminator on the closing line.
+    - Elsewhere, an inline `<!-- ... -->` span is raw HTML; the surrounding
+      text still renders.
+
+    The line-start test looks through leading block-quote markers (`> `),
+    since the same type-2 rule applies to block-quote content.
+    """
+    kept: list[str] = []
+    lines = md_text.split("\n")
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        content = _QUOTE_PREFIX_RE.sub("", line)
+        stripped = content.lstrip(" ")
+        indent = len(content) - len(stripped)
+        if indent <= 3 and stripped.startswith("<!--"):
+            while i < len(lines) and "-->" not in lines[i]:
+                i += 1
+            i += 1  # skip the closing line entirely (or run off EOF)
+            continue
+        kept.append(line)
+        i += 1
+    return _HTML_COMMENT_RE.sub("", "\n".join(kept))
+
+
+def strip_non_rendering(md_text: str) -> str:
+    """Fenced code first (its contents are literal), then HTML comments.
+    Inline code spans are NOT stripped here: heading-slug extraction needs a
+    heading's backticked words (GitHub slugs keep them), so span stripping is
+    applied only where links are extracted (`extract_link_targets`)."""
+    return _strip_html_comments(_strip_fenced_code(md_text))
+
+
+def github_slug(heading: str) -> str:
+    """GitHub's markdown heading -> anchor slug, for ASCII headings:
+    lowercase, drop punctuation, spaces become hyphens (consecutive spaces
+    produce consecutive hyphens, e.g. "CLI / IDE" -> "cli--ide")."""
+    text = heading.strip().lower()
+    # Strip markdown emphasis/backticks before slugging.
+    text = re.sub(r"[*_`]", "", text)
+    text = re.sub(r"[^\w\- ]", "", text)
+    return text.replace(" ", "-")
+
+
+def heading_slugs(md_text: str) -> set[str]:
+    """GitHub anchor slugs of every rendered heading in `md_text`."""
+    return {
+        github_slug(match.group(1))
+        for match in _HEADING_RE.finditer(strip_non_rendering(md_text))
+    }
+
+
+def anchor_resolves(md_text: str, fragment: str) -> bool:
+    """Whether ``fragment`` exactly names a rendered heading id.
+
+    The fragment is already an id reference, not heading prose to slugify.
+    """
+    return fragment in heading_slugs(md_text)
+
+
+def link_targets(text: str) -> list[str]:
+    """Link targets in `text` AS GIVEN — no stripping passes are applied;
+    callers choose which passes have already run."""
+    return _LINK_RE.findall(text)
+
+
+def code_spans(text: str) -> list[str]:
+    """Inline code-span contents in `text` AS GIVEN."""
+    return _CODE_SPAN_RE.findall(text)
+
+
+def extract_link_targets(md_text: str) -> list[str]:
+    """Targets of the RENDERED markdown links in `md_text`: block-level
+    non-rendering stripped, then inline code spans, then the image-excluding
+    link grammar."""
+    return link_targets(_CODE_SPAN_RE.sub("", strip_non_rendering(md_text)))
+
+
+def links_to(md_text: str, surface_dir: Path, target_abs: Path) -> bool:
+    """True when `md_text` carries a rendered link whose destination,
+    resolved relative to `surface_dir`, is exactly `target_abs`. The check
+    is on the link DESTINATION — a link whose visible label keeps the
+    filename but whose target points elsewhere must not pass."""
+    for target in extract_link_targets(md_text):
+        if target.startswith(NON_RELATIVE_LINK_PREFIXES):
+            continue
+        path_part = target.partition("#")[0]
+        if path_part and (surface_dir / path_part).resolve() == target_abs:
+            return True
+    return False
+
+
+def relative_link_failure(
+    repo_root: Path,
+    source_path: Path,
+    target: str,
+) -> RelativeLinkFailure | None:
+    """Return why a repo-relative rendered link fails, or ``None``.
+
+    This is the shared file/anchor-resolution ladder for consumers that need
+    more than :func:`links_to`: a target must stay inside ``repo_root``, exist,
+    and, when it has a fragment, point to a Markdown heading with that exact
+    generated id.
+
+    The fragment is deliberately compared *as authored* with the generated
+    heading ids.  It is not run through :func:`github_slug`: browsers resolve
+    a fragment against an existing id, and slugifying the fragment itself
+    would make broken variants such as ``#Mixed-Case`` falsely satisfy the
+    real ``mixed-case`` id.
+
+    Absolute/web targets are outside this helper's contract; callers retain
+    their existing policy for skipping them.
+    """
+    root_abs = repo_root.resolve()
+    path_part, separator, fragment = target.partition("#")
+    resolved = (
+        source_path.resolve()
+        if not path_part
+        else (source_path.parent / path_part).resolve()
+    )
+
+    if not resolved.is_relative_to(root_abs):
+        return RelativeLinkFailure.ESCAPES_REPOSITORY
+    if not resolved.exists():
+        return RelativeLinkFailure.DOES_NOT_EXIST
+
+    # Preserve the existing intra-document `#` behavior: it names an empty
+    # fragment and therefore has no matching heading.  A trailing `file.md#`
+    # has historically remained a plain file link in these lints.
+    checks_anchor = bool(fragment) or (bool(separator) and not path_part)
+    if not checks_anchor:
+        return None
+    if resolved.suffix.lower() != ".md":
+        return RelativeLinkFailure.ANCHOR_ON_NON_MARKDOWN
+    if not anchor_resolves(resolved.read_text(encoding="utf-8"), fragment):
+        return RelativeLinkFailure.ANCHOR_NOT_FOUND
+    return None