agent-bios 0.9.8 → 0.10.0

package/scripts/check-domains.py

@@ -1,296 +0,0 @@
-#!/usr/bin/env python3
-"""Bijection/coverage gate: config/domains.json vs the canonical corpus.
-
-The manifest is the sole classification authority (tagged-monolith layout);
-claude/CLAUDE.md stays the sole text authority. This gate closes the
-silent-drop window: a bullet reworded without a manifest update, or a
-manifest entry whose anchor no longer matches, fails HERE, before landing.
-
-Blocking checks (any violation exits 1, all violations listed):
-  1. schema shape + registry legality (tiers/domains from the manifest's own
-     registry; domains list non-empty iff tier == "domain")
-  2. bullet bijection: every manifest anchor matches exactly ONE `- ` bullet
-     in claude/CLAUDE.md, and every bullet is claimed by exactly ONE entry
-  3. file coverage: every file in claude/guides|hooks|agents claimed exactly
-     once; every claimed file exists on disk
-  4. router-guide co-package: a bullet referencing guides/<g>.md must have an
-     audience covered by that guide's audience (universal bullet -> universal
-     guide; domain bullet -> guide covering all its domains)
-  5. hook source_guide: a hook naming its source guide must carry the same
-     tier + domain set as that guide
-  6. non-vacuity: every subject set this gate judges is non-empty, so a green
-     run cannot be vacuous
-
-Informational (non-blocking until budgets are set in the manifest): estimated
-token size per package.
-
---self-test: runs negative controls (mutated manifests that MUST fail) and
-exits 0 only if every mutation is caught. Proves the gate can fail.
-"""
-import json
-import pathlib
-import re
-import sys
-
-sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
-import pkgid  # noqa: E402  (sibling module; scripts/ is a flat toolbox, not a package)
-
-REPO = pathlib.Path(__file__).resolve().parent.parent
-MANIFEST = REPO / "config" / "domains.json"
-MONOLITH = REPO / "claude" / "CLAUDE.md"
-FILE_SECTIONS = {  # manifest key -> corpus dir, glob
-    "guides": ("claude/guides", "*.md"),
-    "hooks": ("claude/hooks", "*"),
-    "agents": ("claude/agents", "*.md"),
-}
-
-
-def load_manifest(path=MANIFEST):
-    with open(path, encoding="utf-8") as f:
-        return json.load(f)
-
-
-def corpus_bullets(path=MONOLITH):
-    text = path.read_text(encoding="utf-8")
-    return [ln for ln in text.splitlines() if ln.startswith("- ")]
-
-
-def audience(entry, errors, ctx):
-    """Universal set marker, or the frozen domain set; records legality errors."""
-    tier = entry.get("tier")
-    domains = entry.get("domains", [])
-    if tier in ("core", "infra"):
-        if domains:
-            errors.append(f"{ctx}: tier {tier} must not list domains, got {domains}")
-        return "UNIVERSAL"
-    if tier == "env-personal":
-        if domains:
-            errors.append(f"{ctx}: env-personal must not list domains")
-        return "NEVER"
-    if tier == "domain":
-        if not domains:
-            errors.append(f"{ctx}: tier domain requires >=1 domain")
-        return frozenset(domains)
-    errors.append(f"{ctx}: illegal tier {tier!r}")
-    return "NEVER"
-
-
-def covers(guide_aud, bullet_aud):
-    if guide_aud == "UNIVERSAL":
-        return True
-    if bullet_aud in ("UNIVERSAL", "NEVER"):
-        return False  # universal bullet needs universal guide; NEVER refs nothing
-    return isinstance(guide_aud, frozenset) and guide_aud >= bullet_aud
-
-
-def run_gate(manifest, bullets, repo=REPO):
-    errors = []
-    tiers = set(manifest.get("tiers", []))
-    domains_reg = set(manifest.get("domains", {}))
-    if not tiers or not domains_reg:
-        errors.append("registry: tiers/domains registry empty")
-
-    errors += check_settings_template(manifest, repo)
-
-    # -- 0. package identity ------------------------------------------------
-    # Absent means core (the reservation that keeps pre-v2 artifacts valid), but
-    # a PRESENT malformed id must fail rather than fall back — silently treating
-    # a typo as core would hand it the engine's unconditional-injection audience.
-    pid = pkgid.resolve(manifest)
-    if not pkgid.is_valid(pid):
-        errors.append(f"package_id: {pid!r} is not @scope/name (lowercase, hyphen-separated)")
-
-    def check_registry(entry, ctx):
-        if entry.get("tier") not in tiers:
-            errors.append(f"{ctx}: tier {entry.get('tier')!r} not in registry")
-        for d in entry.get("domains", []):
-            if d not in domains_reg:
-                errors.append(f"{ctx}: domain {d!r} not in registry")
-
-    # -- 2. bullet bijection ------------------------------------------------
-    mb = manifest.get("bullets", [])
-    if not bullets:
-        errors.append("non-vacuity: no bullets found in monolith")
-    if not mb:
-        errors.append("non-vacuity: manifest has no bullet entries")
-    if len(mb) != len(bullets):
-        errors.append(f"bijection: manifest has {len(mb)} bullet entries, monolith has {len(bullets)} bullets")
-    claimed = [0] * len(bullets)
-    seen_anchors = set()
-    for i, entry in enumerate(mb):
-        ctx = f"bullets[{i}] anchor={entry.get('anchor', '')!r:.60}"
-        check_registry(entry, ctx)
-        anchor = entry.get("anchor", "")
-        if not anchor:
-            errors.append(f"{ctx}: empty anchor")
-            continue
-        if anchor in seen_anchors:
-            errors.append(f"{ctx}: duplicate anchor")
-        seen_anchors.add(anchor)
-        hits = [j for j, b in enumerate(bullets) if anchor in b]
-        if len(hits) != 1:
-            errors.append(f"{ctx}: anchor matches {len(hits)} bullets (need exactly 1)")
-        for j in hits:
-            claimed[j] += 1
-    for j, n in enumerate(claimed):
-        if n != 1:
-            errors.append(f"bijection: bullet line {bullets[j][:70]!r} claimed {n} times (need exactly 1)")
-
-    # -- 3. file coverage ---------------------------------------------------
-    entries = {}
-    for key, (rel, glob) in FILE_SECTIONS.items():
-        section = manifest.get(key, {})
-        entries[key] = section
-        if not section:
-            errors.append(f"non-vacuity: manifest section {key!r} empty")
-        on_disk = {p.name for p in (repo / rel).glob(glob) if p.is_file()}
-        if not on_disk:
-            errors.append(f"non-vacuity: no files on disk under {rel}")
-        for name, entry in section.items():
-            check_registry(entry, f"{key}/{name}")
-            if name not in on_disk:
-                errors.append(f"{key}: claimed file {name} does not exist in {rel}")
-        for name in sorted(on_disk - set(section)):
-            errors.append(f"{key}: file {name} in {rel} not claimed by the manifest")
-
-    # -- 4. router-guide co-package ----------------------------------------
-    guide_aud = {n: audience(e, errors, f"guides/{n}") for n, e in entries["guides"].items()}
-    anchor_of = {id(e): e.get("anchor", "?") for e in mb}
-    ref_checks = 0
-    for entry in mb:
-        hits = [b for b in bullets if entry.get("anchor", "\0") in b]
-        if len(hits) != 1:
-            continue  # already reported by bijection
-        b_aud = audience(entry, errors, f"bullet {entry.get('anchor', '')!r:.40}")
-        for g in re.findall(r"guides/([a-z0-9-]+\.md)", hits[0]):
-            ref_checks += 1
-            if g not in guide_aud:
-                errors.append(f"router: bullet {entry['anchor']!r:.40} references unclaimed guide {g}")
-            elif not covers(guide_aud[g], b_aud):
-                errors.append(
-                    f"router: bullet {entry['anchor']!r:.40} (audience {b_aud}) references guide {g} "
-                    f"(audience {guide_aud[g]}) — user can hold the router without the guide"
-                )
-    if ref_checks == 0:
-        errors.append("non-vacuity: no router->guide references were checked")
-
-    # -- 5. hook source_guide -----------------------------------------------
-    for name, entry in entries["hooks"].items():
-        src = entry.get("source_guide")
-        if src:
-            g = entries["guides"].get(src)
-            if g is None:
-                errors.append(f"hooks/{name}: source_guide {src} not in manifest guides")
-            elif (entry.get("tier"), sorted(entry.get("domains", []))) != (g.get("tier"), sorted(g.get("domains", []))):
-                errors.append(f"hooks/{name}: tier/domains differ from source guide {src}")
-
-    # -- informational token report ------------------------------------------
-    sizes = {}
-    for entry in mb:
-        key = entry.get("tier") if entry.get("tier") != "domain" else ",".join(entry.get("domains", ["?"])[:1])
-        hit = next((b for b in bullets if entry.get("anchor", "\0") in b), "")
-        sizes[key] = sizes.get(key, 0) + len(hit) // 4
-    for name, entry in entries["guides"].items():
-        key = entry.get("tier") if entry.get("tier") != "domain" else ",".join(entry.get("domains", ["?"])[:1])
-        p = repo / FILE_SECTIONS["guides"][0] / name
-        if p.is_file():
-            sizes[key] = sizes.get(key, 0) + len(p.read_text(encoding="utf-8")) // 4
-    return errors, sizes
-
-
-def check_settings_template(manifest, repo=REPO):
-    """Every hook registered in the shipped settings template must be a hook the
-    manifest declares.
-
-    `merge_settings` only re-adds template entries whose command names a
-    manifest-declared hook (assemble.py:167-169), so an entry for anything else
-    is silently inert — it looks registered, ships to every user, and never runs.
-    That is how a machine-local registration ends up committed in a
-    deploy-managed file. Make it invalid instead of asking people to remember.
-    """
-    errors = []
-    spath = repo / "claude" / "settings.template.json"
-    if not spath.is_file():
-        return ["settings: claude/settings.template.json missing"]
-    names = set(manifest.get("hooks", {}))
-    entries = [(ev, h.get("command", ""))
-               for ev, evs in json.loads(spath.read_text(encoding="utf-8")).get("hooks", {}).items()
-               for en in evs for h in en.get("hooks", [])]
-    if not entries:
-        errors.append("non-vacuity: settings template registers no hooks")
-    for ev, cmd in entries:
-        if not any(("/hooks/" + n) in cmd for n in names):
-            errors.append(f"settings: {ev} hook {cmd!r} names no manifest hook "
-                          f"(known: {sorted(names)}) — it would never deploy")
-    return errors
-
-
-def self_test(manifest, bullets):
-    """Negative controls: each mutation MUST make the gate fail."""
-    import copy
-
-    muts = []
-    m1 = copy.deepcopy(manifest)
-    m1["bullets"] = m1["bullets"][1:]
-    muts.append(("dropped bullet entry", m1, bullets))
-    m2 = copy.deepcopy(manifest)
-    m2["bullets"][0]["anchor"] = "zz-no-such-phrase-zz"
-    muts.append(("anchor matches nothing (reword drift)", m2, bullets))
-    m3 = copy.deepcopy(manifest)
-    m3["bullets"][1]["anchor"] = m3["bullets"][0]["anchor"]
-    muts.append(("duplicate anchor claim", m3, bullets))
-    m4 = copy.deepcopy(manifest)
-    first_guide = next(iter(m4["guides"]))
-    del m4["guides"][first_guide]
-    muts.append((f"unclaimed guide {first_guide}", m4, bullets))
-    b5 = bullets + ["- a brand new bullet the manifest never heard of"]
-    muts.append(("bullet added without manifest entry", copy.deepcopy(manifest), b5))
-    m6 = copy.deepcopy(manifest)
-    m6["package_id"] = "@Acme/Builder"          # uppercase is not a legal segment
-    muts.append(("malformed package_id", m6, bullets))
-    m7 = copy.deepcopy(manifest)
-    m7["hooks"] = {"renamed-hook.py": {"tier": "core", "domains": []}}
-    muts.append(("settings registers a hook the manifest does not declare", m7, bullets))
-
-    # Targeted: the settings rule itself must speak, not just some neighbouring
-    # check tripping on the same mutation.
-    import copy as _c
-    m_off = _c.deepcopy(manifest)
-    m_off["hooks"] = {"renamed-hook.py": {"tier": "core", "domains": []}}
-    settings_errs = [e for e in check_settings_template(m_off) if e.startswith("settings:")]
-    print(f"self-test [{'CAUGHT' if settings_errs else 'MISSED'}] settings rule fires on its own")
-
-    failed = [] if settings_errs else ["settings rule fires on its own"]
-    for name, mm, bb in muts:
-        errs, _ = run_gate(mm, bb)
-        if not errs:
-            failed.append(name)
-        print(f"self-test [{'CAUGHT' if errs else 'MISSED'}] {name}")
-    return failed
-
-
-def main():
-    manifest = load_manifest()
-    bullets = corpus_bullets()
-    if "--self-test" in sys.argv:
-        missed = self_test(manifest, bullets)
-        if missed:
-            print(f"SELF-TEST FAIL: gate missed: {missed}")
-            return 1
-        print("SELF-TEST OK: every negative control was caught")
-        return 0
-    errors, sizes = run_gate(manifest, bullets)
-    for e in errors:
-        print(f"FAIL: {e}")
-    print("-- package token estimate (informational) --")
-    for k in sorted(sizes):
-        print(f"  {k}: ~{sizes[k]} tokens")
-    if errors:
-        print(f"DOMAINS GATE FAIL: {len(errors)} violation(s)")
-        return 1
-    print(f"DOMAINS GATE OK: {len(bullets)} bullets bijective, all files claimed, routers co-packaged")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())