agent-bios 0.11.0 → 0.12.1

package/compose/canary.sh

@@ -34,6 +34,7 @@ command -v claude >/dev/null 2>&1 || { echo "CANARY SKIP: claude CLI not found
 
 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)"
+probe_status=$?
 
 if printf '%s' "$out" | grep -qF "$expected"; then
   # Record WHICH bundle was proven to load. This is the only evidence in the system that
@@ -64,6 +65,18 @@ if [ -z "$out" ]; then
   echo "CANARY SKIP: probe produced no output — cannot tell activation from a failed dispatch"
   exit 3
 fi
+# The 1-vs-3 rule this file opens with, applied to the one signal it was not reading:
+# the probe's own exit status. An empty reply was already treated as unprobed, but a
+# FAILED dispatch that printed anything at all — a network error, an unrecognised flag,
+# a CLI upgrade changing its error text — fell through to FAIL and sent the reader off
+# to re-approve imports for a bundle that was never asked about. stderr is discarded
+# above, so the message is quoted for whatever it is worth and the status decides.
+if [ "$probe_status" -ne 0 ]; then
+  echo "CANARY SKIP: the probe command failed (exit $probe_status) — cannot tell activation"
+  echo "             from a failed dispatch"
+  echo "  probe replied:   $(printf '%s' "$out" | head -c 200)"
+  exit 3
+fi
 
 echo "CANARY FAIL: central bundle is NOT loading in live sessions."
 echo "  expected marker: $expected"

package/compose/check-domains.py

@@ -11,8 +11,10 @@ Blocking checks (any violation exits 1, all violations listed):
      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
+  3. file coverage: every file in claude/guides|hooks|agents and every skill
+     directory in claude/skills claimed exactly once; every claimed one exists
+     on disk (a skill is a directory carrying SKILL.md — a directory there
+     without one is malformed, not unclaimed)
   4. router-guide co-package, both directions: a bullet or guide referencing a
      guide must have an audience covered by that guide's audience, and the target
      must be one an install actually receives; every guide must be pointed at by
@@ -47,7 +49,29 @@ FILE_SECTIONS = {  # manifest key -> corpus dir, glob
     "guides": ("claude/guides", "*.md"),
     "hooks": ("claude/hooks", "*"),
     "agents": ("claude/agents", "*.md"),
+    # A skill's unit is its DIRECTORY (SKILL.md + free subdirectories), deployed as a
+    # tree by install.sh and asked of the assembler by name (`--selected-skills`), so the
+    # manifest classifies the directory name, not the files inside it.
+    "skills": ("claude/skills", "*"),
 }
+SKILL_MARKER = "SKILL.md"
+
+
+def units_on_disk(root, glob, key):
+    """The names the manifest section `key` must claim: files, or for skills the
+    directories that carry SKILL.md. Returns (names, malformed) — a skills subdirectory
+    without the marker is neither claimable nor ignorable."""
+    names, malformed = set(), []
+    for p in root.glob(glob):
+        if key == "skills":
+            if p.is_dir():
+                if (p / SKILL_MARKER).is_file():
+                    names.add(p.name)
+                else:
+                    malformed.append(p.name)
+        elif p.is_file():
+            names.add(p.name)
+    return names, malformed
 
 
 def load_manifest(path=MANIFEST):
@@ -173,8 +197,21 @@ def refs_from(text, guides):
 
 def run_gate(manifest, bullets, repo=REPO):
     errors = []
-    tiers = set(manifest.get("tiers", []))
-    domains_reg = set(manifest.get("domains", {}))
+
+    def name_set(value, key):
+        """The registry's names, or an error and an empty set.
+
+        This gate's contract is that shape violations exit 1 with every violation LISTED.
+        `set(None)` raises instead, so a `"domains": null` — parse-valid JSON, and exactly
+        the shape a bad hand-edit leaves — came out of the gate as a TypeError traceback
+        before it could name anything at all."""
+        if isinstance(value, (list, dict, tuple, set)):
+            return set(value)
+        errors.append(f"registry: {key} must be a list or object, got {type(value).__name__}")
+        return set()
+
+    tiers = name_set(manifest.get("tiers", []), "tiers")
+    domains_reg = name_set(manifest.get("domains", {}), "domains")
     if not tiers or not domains_reg:
         errors.append("registry: tiers/domains registry empty")
 
@@ -188,6 +225,25 @@ def run_gate(manifest, bullets, repo=REPO):
     if not pkgid.is_valid(pid):
         errors.append(f"package_id: {pid!r} is not @scope/name (lowercase, hyphen-separated)")
 
+    # A registered domain with nothing in it. The gate asserts its subject sets are
+    # non-empty so a green run cannot be vacuous, and the DOMAIN registry was the one set it
+    # never asked that of: a name could be selectable, appear in the picker, be written into
+    # selection.json — and deliver only the universal tier, which every other selection
+    # delivers too. A domain that changes nothing about what you receive is a promise the
+    # assembler cannot keep, and nothing downstream can notice.
+    claimed = set()
+    for entry in manifest.get("bullets", []):
+        if isinstance(entry, dict):
+            claimed.update(d for d in entry.get("domains", []) if isinstance(d, str))
+    for kind in FILE_SECTIONS:
+        for entry in (manifest.get(kind) or {}).values():
+            if isinstance(entry, dict):
+                claimed.update(d for d in entry.get("domains", []) if isinstance(d, str))
+    for name in sorted(domains_reg - claimed):
+        errors.append(
+            f"domain {name!r} is registered but no bullet, guide, hook, agent or skill is in "
+            f"it — selecting it would deliver exactly what selecting nothing delivers")
+
     def check_registry(entry, ctx):
         if entry.get("tier") not in tiers:
             errors.append(f"{ctx}: tier {entry.get('tier')!r} not in registry")
@@ -231,9 +287,12 @@ def run_gate(manifest, bullets, repo=REPO):
         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()}
+        on_disk, malformed = units_on_disk(repo / rel, glob, key)
         if not on_disk:
             errors.append(f"non-vacuity: no files on disk under {rel}")
+        for name in malformed:
+            errors.append(f"{key}: directory {name} in {rel} carries no {SKILL_MARKER} — "
+                          f"not a skill the hosts can load, and not a name the manifest can claim")
         for name, entry in section.items():
             check_registry(entry, f"{key}/{name}")
             if name not in on_disk:
@@ -601,25 +660,43 @@ def self_test(manifest, bullets):
     muts = []
     m1 = copy.deepcopy(manifest)
     m1["bullets"] = m1["bullets"][1:]
-    muts.append(("dropped bullet entry", m1, bullets))
+    muts.append(("dropped bullet entry", m1, bullets, "bijection"))
     m2 = copy.deepcopy(manifest)
     m2["bullets"][0]["anchor"] = "zz-no-such-phrase-zz"
-    muts.append(("anchor matches nothing (reword drift)", m2, bullets))
+    muts.append(("anchor matches nothing (reword drift)", m2, bullets, "anchor"))
     m3 = copy.deepcopy(manifest)
     m3["bullets"][1]["anchor"] = m3["bullets"][0]["anchor"]
-    muts.append(("duplicate anchor claim", m3, bullets))
+    muts.append(("duplicate anchor claim", m3, bullets, "anchor"))
     m4 = copy.deepcopy(manifest)
     first_guide = next(iter(m4["guides"]))
     del m4["guides"][first_guide]
-    muts.append((f"unclaimed guide {first_guide}", m4, bullets))
+    muts.append((f"unclaimed guide {first_guide}", m4, bullets, "unclaimed"))
     b5 = bullets + ["- a brand new bullet the manifest never heard of"]
-    muts.append(("bullet added without manifest entry", copy.deepcopy(manifest), b5))
+    muts.append(("bullet added without manifest entry", copy.deepcopy(manifest), b5, "bijection"))
     m6 = copy.deepcopy(manifest)
     m6["package_id"] = "@Acme/Builder"          # uppercase is not a legal segment
-    muts.append(("malformed package_id", m6, bullets))
+    muts.append(("malformed package_id", m6, bullets, "package_id"))
+    # A registry name with nothing in it. It is selectable, it is written into
+    # selection.json, and it delivers exactly the universal tier every other selection also
+    # delivers — so nothing downstream can tell it apart from choosing nothing at all.
+    m8 = copy.deepcopy(manifest)
+    m8["domains"]["empty-domain-control"] = "registered with no subjects"
+    muts.append(("a registered domain with no subjects", m8, bullets, "empty-domain-control"))
     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))
+    muts.append(("settings registers a hook the manifest does not declare", m7, bullets, "settings"))
+    # Skills are directory units. Both directions of coverage, and the subject asserted
+    # first: a self-test that finds no shipped skill would "catch" its own absence.
+    if not manifest.get("skills"):
+        raise SystemExit("self-test: the manifest declares no skill, so the skill-coverage "
+                         "controls have no subject and would pass vacuously")
+    m9 = copy.deepcopy(manifest)
+    first_skill = next(iter(m9["skills"]))
+    del m9["skills"][first_skill]
+    muts.append((f"unclaimed skill directory {first_skill}", m9, bullets, "not claimed"))
+    m10 = copy.deepcopy(manifest)
+    m10["skills"]["no-such-skill-control"] = {"tier": "domain", "domains": ["builder-base"]}
+    muts.append(("a claimed skill with no directory on disk", m10, bullets, "does not exist"))
 
     # A bullet that names a cross-domain guide in PROSE. This shipped for real: the reader
     # held the rule and could not hold the guide, and a path-only scan reported clean. The
@@ -638,13 +715,13 @@ def self_test(manifest, bullets):
     assert len(hits) == 1, "self-test: prose-router control could not locate its bullet"
     b8 = [b + f" (see the {gentry['handles'][0]})" if b is hits[0] else b for b in bullets]
     muts.append((f"bullet names {gname} in prose across a domain boundary",
-                 copy.deepcopy(manifest), b8))
+                 copy.deepcopy(manifest), b8, "router"))
     # The dehyphenated PLURAL of the same promise: "the concept economy guides" resolved
     # to nothing while the singular was caught — the referring pattern must own plurals.
     spoken8 = gname[:-3].replace("-", " ")
     b8p = [b + f" — read the {spoken8} guides first" if b is hits[0] else b for b in bullets]
     muts.append((f"bullet names {gname} as a dehyphenated PLURAL prose reference",
-                 copy.deepcopy(manifest), b8p))
+                 copy.deepcopy(manifest), b8p, "router"))
 
     # The orphan control removes a guide's ONLY pointer. It picks that guide by looking, not
     # from a name typed here: a typed name stops being the right subject the moment that guide
@@ -676,7 +753,7 @@ def self_test(manifest, bullets):
         raise SystemExit("self-test: the orphan control could not drop exactly one manifest "
                          "entry with its bullet, so the mutation is not the one it claims")
     muts.append((f"guide {o_name} left with no pointer at all",
-                 m_orphan, [b for b in bullets if b != o_line]))
+                 m_orphan, [b for b in bullets if b != o_line], "orphan"))
 
     # A bullet that exists but ships to NOBODY cannot root a guide: reclassify the
     # orphan guide's only router bullet as env-personal (assemble maps the tier to
@@ -696,6 +773,22 @@ def self_test(manifest, bullets):
     print(f"self-test [{'CAUGHT' if never_ok else 'MISSED'}] an env-personal (never-"
           f"delivered) router bullet leaves {o_name} an orphan")
 
+    # A registry of the wrong TYPE must be listed like any other violation. `set(None)` is
+    # not a diagnostic — it is a TypeError out of the gate before it can name anything, and
+    # `"domains": null` is exactly what a bad hand-edit of this file leaves behind. The
+    # contrast is the shape it should have: both must come back as errors, never as a raise.
+    for field, bad_value in (("domains", None), ("tiers", "core")):
+        m_shape = copy.deepcopy(manifest)
+        m_shape[field] = bad_value
+        try:
+            errs_shape, _ = run_gate(m_shape, bullets)
+            shape_ok = any(f"registry: {field} must be" in e for e in errs_shape)
+        except Exception as exc:
+            errs_shape, shape_ok = [], False
+            print(f"self-test [MISSED] {field}={bad_value!r} RAISED {type(exc).__name__}")
+        print(f"self-test [{'CAUGHT' if shape_ok else 'MISSED'}] a {field} registry of the "
+              f"wrong type is listed rather than raised")
+
     # One handle, one guide: copying a declared handle onto a second guide must fail as
     # a duplicate declaration, not silently resolve one prose router to both targets.
     m_dup = copy.deepcopy(manifest)
@@ -766,7 +859,7 @@ def self_test(manifest, bullets):
     m_cross = copy.deepcopy(manifest)
     m_cross["guides"][c_to] = {"tier": "domain", "domains": ["office-work"]}
     muts.append((f"guide {c_from} cites {c_to} after {c_to} moves to a domain it does not hold",
-                 m_cross, bullets))
+                 m_cross, bullets, "router"))
 
     # Targeted: the settings leg must use the assembler's TOKEN rule, not a substring.
     # `.disabled` appended after the hook name is the reviewer-verified shape: substring
@@ -844,6 +937,22 @@ def self_test(manifest, bullets):
     print(f"self-test [{'CAUGHT' if not false_hits else 'MISSED'}] withheld {withheld} citing "
           f"{narrow} is exempt from audience coverage")
 
+    # A directory under claude/skills that carries no SKILL.md is malformed — the hosts
+    # cannot load it and the manifest cannot claim it — and must be named, not skipped
+    # the way a stray file under guides/ is. Planted in a throwaway copy of the tree.
+    with tempfile.TemporaryDirectory() as td:
+        tmp_sk = pathlib.Path(td)
+        for sub in ("claude", "ko", "launch"):
+            if (REPO / sub).is_dir():
+                shutil.copytree(REPO / sub, tmp_sk / sub)
+        (tmp_sk / "claude" / "skills" / "half-a-skill-control" / "notes").mkdir(parents=True)
+        errs_sk, _ = run_gate(manifest, bullets, repo=tmp_sk)
+        sk_ok = any("half-a-skill-control" in e and "no SKILL.md" in e for e in errs_sk)
+    print(f"self-test [{'CAUGHT' if sk_ok else 'MISSED'}] a skills/ directory without "
+          f"SKILL.md is reported as malformed")
+    if not sk_ok:
+        return ["a skills/ directory without SKILL.md was not reported"]
+
     # Launch missions: a deployed-form reference to a non-universal or withheld guide must
     # fail; the real checkout-form reference must stay clean (it is the distill mission's
     # deliberate shape, guarded by check-package instead).
@@ -1137,11 +1246,26 @@ def self_test(manifest, bullets):
         failed.append("handle-only reference resolves")
     if not handle_bounded:
         failed.append("handle embedded in a longer word must not resolve")
-    for name, mm, bb in muts:
+    # A clean baseline first. Every row below reads "this mutation makes the gate complain",
+    # and that sentence is only true if the unmutated manifest does NOT — otherwise each row
+    # is reporting a pre-existing error as its own catch.
+    baseline, _ = run_gate(manifest, bullets)
+    if baseline:
+        failed.append("baseline: the unmutated manifest already fails, so every mutation "
+                      f"below is judged against noise ({baseline[:1]})")
+        print(f"self-test [MISSED] baseline is clean before mutating ({len(baseline)} errors)")
+
+    for name, mm, bb, expect in muts:
         errs, _ = run_gate(mm, bb)
-        if not errs:
-            failed.append(name)
-        print(f"self-test [{'CAUGHT' if errs else 'MISSED'}] {name}")
+        # The mutation's OWN diagnostic, not merely some error. Asking only whether the list
+        # is non-empty let an unrelated complaint stand in for the one the row exists to
+        # provoke — suppress the bijection checks entirely and this loop still reported
+        # CAUGHT, because a malformed package id elsewhere in the same manifest kept the
+        # list non-empty. A negative control that any failure satisfies tests nothing.
+        hit = any(expect in e for e in errs)
+        if not hit:
+            failed.append(f"{name} (wanted a diagnostic naming {expect!r}, got {errs[:2]})")
+        print(f"self-test [{'CAUGHT' if hit else 'MISSED'}] {name}")
     return failed
 
 

package/compose/domains.json

@@ -100,6 +100,7 @@
     "llm-capability-boundary-patterns.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
     "llm-capability-boundary.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
     "mock-realization-boundary.md": {"tier": "domain", "domains": ["builder-base"]},
+    "review-defect-criteria.md": {"tier": "domain", "domains": ["builder-base"]},
     "review-request.md": {"tier": "domain", "domains": ["builder-base"]},
     "session-distill-workflow.md": {"tier": "infra", "domains": []},
     "learning-flow.md": {"tier": "infra", "domains": []},
@@ -114,5 +115,8 @@
     "frontier.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
     "sweep.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
     "workhorse.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]}
+  },
+  "skills": {
+    "repo-charter": {"tier": "domain", "domains": ["builder-base"]}
   }
 }

package/compose/prune-backups.py

@@ -94,18 +94,29 @@ def prune(state_dir, homes, now=None, dry=False):
     now = time.time() if now is None else now
     removed = []
 
+    # Recorded AFTER the removal is confirmed gone. Both deleters swallow their errors on
+    # purpose — a backup that will not delete must not fail an install — but appending
+    # first made the returned list a record of what was ATTEMPTED, and the caller prints it
+    # as what was removed. A copy still on disk being reported as pruned is the reading
+    # that sends someone looking for space that was never freed.
+    def take(path, remove):
+        if dry:
+            removed.append(path)
+            return
+        remove(path)
+        if path.exists():
+            print(f"  warning: could not remove {path}", file=sys.stderr)
+            return
+        removed.append(path)
+
     backups = state_dir / "backups"
     if backups.is_dir():
         for path in to_delete(_entries([d for d in backups.iterdir() if d.is_dir()]), now):
-            removed.append(path)
-            if not dry:
-                shutil.rmtree(path, ignore_errors=True)
+            take(path, lambda p: shutil.rmtree(p, ignore_errors=True))
 
     for home in homes:
         for path in to_delete(_entries(owned_siblings(home)), now):
-            removed.append(path)
-            if not dry:
-                path.unlink(missing_ok=True)
+            take(path, lambda p: p.unlink(missing_ok=True))
     return removed
 
 
@@ -163,7 +174,46 @@ def self_test():
     if not missed and not grabbed:
         print(f"  ok   ownership: claims {len(ours)} shapes we write, "
               f"refuses {len(theirs)} we do not")
-    print(f"prune-backups self-test: {'OK' if not bad else 'FAIL'} ({len(cases) + 2} checks)")
+    # The reported list is what the caller prints as removed, so it has to be what is GONE.
+    # Both deleters swallow their errors by design — a stuck copy must not fail an install —
+    # and appending before the call made the list a record of attempts instead. Driven on a
+    # real directory, because the defect lives in the deletion and not in the pure retention
+    # rule above; the deletable run beside it is what keeps this from passing on a pruner
+    # that reports nothing at all.
+    import os as os_, tempfile as tempfile_
+
+    def reported_vs_gone(block_one):
+        root = pathlib.Path(tempfile_.mkdtemp())
+        state = root / "state"
+        (state / "backups").mkdir(parents=True)
+        made = []
+        for i in range(KEEP_RECENT + 2):
+            aged = state / "backups" / f"2020{i:04d}-000000"
+            aged.mkdir()
+            (aged / "f.txt").write_text("x")
+            stamp = now - (MAX_AGE_DAYS + 10 + i) * day
+            os_.utime(aged, (stamp, stamp))
+            made.append(aged)
+        stuck = sorted(made, key=lambda q: q.stat().st_mtime)[0]
+        if block_one:
+            stuck.chmod(0o500)
+        count = len(prune(state, [], now=now))
+        gone = len([q for q in made if not q.exists()])
+        if block_one:
+            stuck.chmod(0o700)
+        shutil.rmtree(root, ignore_errors=True)
+        return count, gone
+
+    for label, block_one in (("every aged backup deletable", False),
+                             ("one of them undeletable", True)):
+        count, gone = reported_vs_gone(block_one)
+        if count != gone or (not block_one and gone == 0):
+            print(f"  FAIL {label}: reported {count} removed, {gone} actually gone")
+            bad += 1
+        else:
+            print(f"  ok   {label}: reported {count} == gone {gone}")
+
+    print(f"prune-backups self-test: {'OK' if not bad else 'FAIL'} ({len(cases) + 4} checks)")
     return 1 if bad else 0