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 — 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()