agent-bios 0.9.4 → 0.9.6

package/scripts/build-promotions.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Derive the promotion manifest from the ledger (collection loop, Phase 4).
+
+`config/promotions.json` names the personal learnings that have been PROMOTED
+into the shared corpus, so the user-side migrate rule can clear the now-absorbed
+personal copy (scripts/migrate-learnings.py). The manifest is DERIVED — never
+hand-edited: a promoted user learning is a ledger entry with `status == placed`
+AND a `learning_id` (the Phase 3 dedup key kept on merge). Session-distill
+entries have no `learning_id`, so they are never in the manifest.
+
+F3 hardening (the one silent-loss path in the safety design): the audience a
+promotion belongs to (which users' bundles carry it) is derived from where the
+bullet ACTUALLY landed — the placed entry's `placed_anchor`, resolved against
+`config/domains.json` (the placement source of truth) — NOT the ledger's free
+`domain` tag. A placed+learning_id entry with a missing or unresolvable
+`placed_anchor` FAILS the build/--check, so a promotion can neither ship with a
+wrong audience nor ship without actually landing in the corpus.
+
+Manifest shape (no PII — learning_id + the derived audience):
+  { "version": 1, "promotions": [
+      { "learning_id": "<uuid>", "tier": "core|infra|domain", "domains": ["<key>", ...] } ] }
+(`domains` is empty for the universal tiers core/infra.)
+
+Release step: regenerate before a push. `--check` fails if the on-disk manifest
+is stale vs the ledger (a check-parity gate). `--self-test` runs the derivation.
+"""
+import argparse
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+import pkgid  # noqa: E402  (sibling module; scripts/ is a flat toolbox)
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+LEDGER = REPO / "design" / "session-distill" / "ledger.json"
+DOMAINS = REPO / "config" / "domains.json"
+MANIFEST = REPO / "config" / "promotions.json"
+FIXTURE = REPO / "design" / "collection-loop" / "fixtures" / "ledger-promote-sample.json"
+MANIFEST_VERSION = 2
+
+
+class ManifestError(Exception):
+    pass
+
+
+def resolve_audience(anchor, domains_manifest):
+    """(tier, [domains]) for a placed anchor, or None if it does not resolve.
+    Bullets match by their `anchor` field; a whole guide/hook/agent matches by
+    key. This is the authoritative placement audience (mirrors what assemble.py
+    reads to decide who gets the bullet)."""
+    for b in domains_manifest.get("bullets", []):
+        if b.get("anchor") == anchor:
+            return b.get("tier"), list(b.get("domains", []))
+    for kind in ("guides", "hooks", "agents"):
+        entry = domains_manifest.get(kind, {}).get(anchor)
+        if entry is not None:
+            return entry.get("tier"), list(entry.get("domains", []))
+    return None
+
+
+def build_manifest(ledger, domains_manifest):
+    """Ledger + domains manifest -> the promotion manifest. Raises ManifestError
+    on a placed+learning_id entry whose placement can't be verified (missing or
+    unresolvable placed_anchor) — the F3 silent-loss guard. Sorted by
+    learning_id for a stable, deterministic artifact."""
+    promotions = []
+    for e in ledger.get("entries", []):
+        if not isinstance(e, dict):
+            continue
+        lid = e.get("learning_id")
+        if e.get("status") != "placed" or not (isinstance(lid, str) and lid):
+            continue
+        anchor = e.get("placed_anchor")
+        if not anchor:
+            raise ManifestError(
+                f"placed learning {e.get('id')!r} ({lid}) has no `placed_anchor` — "
+                "record where the bullet landed (a config/domains.json anchor/key) "
+                "before promoting")
+        aud = resolve_audience(anchor, domains_manifest)
+        if aud is None:
+            raise ManifestError(
+                f"placed_anchor {anchor!r} (learning {lid}) does not resolve in "
+                "config/domains.json — the promotion has no verifiable placement")
+        tier, domains = aud
+        pid = pkgid.resolve(e, "placed_package_id")
+        if not pkgid.is_valid(pid):
+            raise ManifestError(
+                f"placed_package_id {pid!r} (learning {lid}) is not @scope/name")
+        # `anchor` ships alongside the derived audience because the consumer
+        # (migrate-learnings) must verify the bullet is REALLY in the user's
+        # deployed corpus before deleting their personal copy. Audience metadata
+        # alone cannot answer that — it is a build-time projection that drifts.
+        promotions.append({"learning_id": lid.lower(), "package_id": pid,
+                           "anchor": anchor, "tier": tier, "domains": domains})
+    promotions.sort(key=lambda p: p["learning_id"])
+    return {"version": MANIFEST_VERSION, "promotions": promotions}
+
+
+def render(manifest):
+    return json.dumps(manifest, ensure_ascii=False, indent=2) + "\n"
+
+
+def _self_test():
+    ledger = json.loads(FIXTURE.read_text(encoding="utf-8"))
+    # Fixture domains manifest the fixture's placed_anchors resolve against.
+    domains = {
+        "bullets": [
+            {"anchor": "universal placed rule", "tier": "core", "domains": []},
+            {"anchor": "builder placed rule", "tier": "domain", "domains": ["builder-base"]},
+        ],
+        "guides": {}, "hooks": {}, "agents": {},
+    }
+    m = build_manifest(ledger, domains)
+    by = {p["learning_id"]: p for p in m["promotions"]}
+    a1 = "0f8c1c2a-4d1e-4abc-9def-0000000000a1"
+    b2 = "0f8c1c2a-4d1e-4abc-9def-0000000000b2"
+
+    checks = [
+        ("only placed+learning_id promoted (cardinality > 0)", set(by) == {a1, b2}),
+        ("session-distill (no learning_id) excluded",
+         all(p["learning_id"] for p in m["promotions"])),
+        ("incubating excluded",
+         "0f8c1c2a-4d1e-4abc-9def-0000000000c1" not in by),
+        ("audience DERIVED from the anchor, not the ledger domain tag",
+         by[a1]["tier"] == "core" and by[a1]["domains"] == []
+         and by[b2]["tier"] == "domain" and by[b2]["domains"] == ["builder-base"]),
+        ("sorted + deterministic",
+         [p["learning_id"] for p in m["promotions"]] == sorted(by)
+         and render(build_manifest(ledger, domains)) == render(m)),
+    ]
+
+    # F3 guards: missing / unresolvable placed_anchor must FAIL.
+    def raises(mut):
+        led = json.loads(FIXTURE.read_text(encoding="utf-8"))
+        mut(led)
+        try:
+            build_manifest(led, domains)
+            return False
+        except ManifestError:
+            return True
+
+    checks.append(("missing placed_anchor fails",
+                   raises(lambda l: l["entries"][0].pop("placed_anchor", None))))
+    checks.append(("unresolvable placed_anchor fails",
+                   raises(lambda l: l["entries"][0].__setitem__("placed_anchor", "no-such-anchor"))))
+
+    # v2 identity + locator. Without these the manifest looks fine while the
+    # consumer that must verify placement has nothing to verify against.
+    checks.append(("manifest is v2", m["version"] == 2))
+    checks.append(("every promotion carries its anchor",
+                   all(p.get("anchor") for p in m["promotions"])))
+    checks.append(("absent placed_package_id resolves to core",
+                   all(p.get("package_id") == pkgid.CORE for p in m["promotions"])))
+    led2 = json.loads(FIXTURE.read_text(encoding="utf-8"))
+    led2["entries"][0]["placed_package_id"] = "@acme/security"
+    checks.append(("declared placed_package_id is carried through",
+                   any(p["package_id"] == "@acme/security"
+                       for p in build_manifest(led2, domains)["promotions"])))
+    checks.append(("malformed placed_package_id fails",
+                   raises(lambda l: l["entries"][0].__setitem__("placed_package_id", "Acme/Sec"))))
+
+    failed = [n for n, ok in checks if not ok]
+    if failed:
+        for n in failed:
+            print(f"build-promotions --self-test: FAIL: {n}", file=sys.stderr)
+        sys.exit(1)
+    print(f"build-promotions --self-test: OK ({len(checks)} manifest-derivation checks)")
+
+
+def _load_and_build():
+    ledger = json.loads(LEDGER.read_text(encoding="utf-8"))
+    domains = json.loads(DOMAINS.read_text(encoding="utf-8"))
+    try:
+        return render(build_manifest(ledger, domains))
+    except ManifestError as e:
+        print(f"build-promotions: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Derive config/promotions.json from the ledger.")
+    ap.add_argument("--check", action="store_true",
+                    help="fail if config/promotions.json is stale vs the ledger (gate)")
+    ap.add_argument("--self-test", action="store_true")
+    args = ap.parse_args()
+
+    if args.self_test:
+        _self_test()
+        return
+
+    want = _load_and_build()
+
+    if args.check:
+        have = MANIFEST.read_text(encoding="utf-8") if MANIFEST.is_file() else ""
+        if have != want:
+            print("build-promotions --check: config/promotions.json is STALE vs the "
+                  "ledger — run `python3 scripts/build-promotions.py` and commit.",
+                  file=sys.stderr)
+            sys.exit(1)
+        print("build-promotions --check: promotions.json is current with the ledger")
+        return
+
+    MANIFEST.write_text(want, encoding="utf-8")
+    n = want.count('"learning_id"')
+    print(f"build-promotions: wrote {MANIFEST} ({n} promotion(s))")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/canary.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Activation canary: proves the central bundle actually LOADS in a live
+# session — file presence cannot detect a declined @import approval or a
+# broken entry import line, so this asks a headless session to echo the
+# bundle's rev marker back.
+# Exit: 0 loaded | 1 not loading (or no bundle) | 3 cannot probe (no CLI).
+set -u
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+BUNDLE="$CLAUDE_DIR/central/bundle.md"
+
+[ -f "$BUNDLE" ] || { echo "CANARY FAIL: no bundle at $BUNDLE (run: agent-bios install --domains ...)"; exit 1; }
+expected="$(grep -m1 '^agent-bios-bundle-rev: ' "$BUNDLE")"
+[ -n "$expected" ] || { echo "CANARY FAIL: bundle has no rev marker (reassemble with a current assemble.py)"; exit 1; }
+command -v claude >/dev/null 2>&1 || { echo "CANARY SKIP: claude CLI not found — cannot probe activation"; exit 3; }
+
+probe="Somewhere in your loaded instruction context there may be a line that starts with 'agent-bios-bundle-rev:'. Reply with ONLY that line, verbatim. If no such line is in your context, reply with exactly: BUNDLE-NOT-LOADED"
+out="$(cd "$HOME" && claude -p "$probe" 2>/dev/null)"
+
+if printf '%s' "$out" | grep -qF "$expected"; then
+  echo "CANARY PASS: central bundle is loading ($expected)"
+  exit 0
+fi
+echo "CANARY FAIL: central bundle is NOT loading in live sessions."
+echo "  expected marker: $expected"
+echo "  probe replied:   $(printf '%s' "$out" | head -c 200)"
+echo "  Likely causes: the CLAUDE.md import approval was declined (open a session and re-approve imports),"
+echo "  or the entry file lost its '@central/bundle.md' line. Diagnose with: agent-bios verify"
+exit 1

package/scripts/check-domains.py

@@ -0,0 +1,256 @@
+#!/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")
+
+    # -- 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 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))
+
+    failed = []
+    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())