dotfiles/claude/governance/check_containment.py

#!/usr/bin/env python3
"""
Verbatim containment check for jurist packages.

The packages in this directory are written for a jurist with NO repository access,
under a contract stated in their own headers: "every clause reasoned about is quoted
verbatim". That contract is only worth what a mechanical check makes it worth. Reading
does not catch a fabricated terminal period, an elision presented as contiguous, or a
truncation that closes a sentence with a word the source does not contain — all three
have occurred in packages from this directory, and all three were caught by a check
like this one rather than by careful reading.

Every run carries POSITIVE CONTROLS: near-miss strings that must be absent. If a control
is found, the instrument is not discriminating and its passes mean nothing. An absence
is not evidence until the instrument is shown capable of detecting presence.

KNOWN LIMIT — CONTAINMENT IS NOT SUFFICIENCY.
    This tests that what you quoted is ACCURATE. It cannot test that you quoted what
    MATTERS. An omission passes every time, because nothing was misquoted.

    Demonstrated 2026-08-05, PENDING-99: the package quoted chamber §II.3 verbatim and
    passed 16/16 with 9/9 controls absent. The sentence that actually decided the
    question — "What remains genuinely open... the marker's exact syntax" — sat in the
    NEXT LINE of the same subsection, was in the executor's own read output, and was
    never surfaced. The jurist found it on first contact with the primary text and
    reframed the ruling. A containment proof is a floor against fabrication, never
    evidence of adequacy.

    The countermeasure is not a better checker. It is a different act: read the clauses
    ADJACENT to every quote, and say in the package that you did.

KNOWN LIMIT — THIS INSTRUMENT CANNOT VERIFY A NEGATION.
    It tests whether an exact string is present. It has no notion of polarity. So a
    sentence of the form "X does NOT hold" contains, as a literal substring, the
    affirmative "X holds" — and any control built from that affirmative will leak by
    construction, every time, no matter how correct the text is.

    Hit twice within five minutes on 2026-08-02 while verifying the Constraint 6
    placement: both attempts to control for "the doctrine must not claim the
    jurist-executor pair IS a check" used substrings of the very sentence that denies
    it. The instrument was right to refuse certification both times; the controls were
    malformed.

    Build controls by INVERSION, not by extraction — a string that would appear only if
    the meaning were flipped ("the jurist and the executor differ from each other in
    formation", dropping the "do not"), never a fragment lifted out of the sentence
    under test. And where polarity is what matters, this instrument does not settle it:
    read the sentence. Report that you read it, and that containment did not cover it.

USAGE
    ./check_containment.py manifest.json

MANIFEST
    {
      "sources": {"key": "/abs/path/to/source", ...},
      "claims":   [["key", "quoted text"], ...],
      "controls": [["key", "near-miss that MUST be absent"], ...]
    }

EXIT
    0  all claims contained, no control leaked
    1  a claim is not contained
    2  a control leaked — instrument not verified, result unusable
"""

from __future__ import annotations

import json
import re
import sys
import unicodedata
from pathlib import Path

# Typographic normalisation. Quotation is compared on content, not on which flavour of
# apostrophe an editor inserted — but NOT on punctuation the source does not contain.
_SUBS = [
    ("‘", "'"), ("’", "'"),
    ("“", '"'), ("”", '"'),
    ("—", "-"), ("–", "-"), ("‑", "-"),
    (" ", " "),
]


def norm(s: str) -> str:
    s = unicodedata.normalize("NFKC", s)
    for a, b in _SUBS:
        s = s.replace(a, b)
    return re.sub(r"\s+", " ", s).strip().lower()


def main() -> None:
    if len(sys.argv) != 2:
        sys.exit(__doc__)
    manifest = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))

    bodies = {}
    for key, path in manifest["sources"].items():
        p = Path(path).expanduser()
        if not p.is_file():
            sys.exit(f"FATAL: source '{key}' not found: {p}")
        bodies[key] = norm(p.read_text(encoding="utf-8"))

    def contained(key: str, quote: str) -> bool:
        if key not in bodies:
            sys.exit(f"FATAL: claim references undeclared source '{key}'")
        return norm(quote) in bodies[key]

    print("QUOTED CLAIMS")
    failures = []
    for key, quote in manifest["claims"]:
        ok = contained(key, quote)
        if not ok:
            failures.append((key, quote))
        print(f"  {'PASS' if ok else 'FAIL'}  [{key}] {quote[:70]}")
    print(f"\n  {len(manifest['claims']) - len(failures)}/{len(manifest['claims'])} contained\n")

    print("POSITIVE CONTROLS (must all be absent)")
    leaked = []
    for key, quote in manifest.get("controls", []):
        ok = contained(key, quote)
        if ok:
            leaked.append((key, quote))
        print(f"  {'LEAKED' if ok else 'absent'}  [{key}] {quote[:70]}")

    if not manifest.get("controls"):
        print("\nINSTRUMENT NOT VERIFIED — no positive controls declared.")
        sys.exit(2)

    if leaked:
        print(f"\nINSTRUMENT NOT VERIFIED — {len(leaked)} control(s) leaked. Passes above are meaningless.")
        sys.exit(2)

    print("\nINSTRUMENT VERIFIED")
    if failures:
        print(f"CONTAINMENT FAILED — {len(failures)} quoted claim(s) not found verbatim in the named source.")
        sys.exit(1)
    print("CONTAINMENT PASSED")


if __name__ == "__main__":
    main()