agent-bios 0.10.0 → 0.12.0

package/compose/assemble.py

@@ -22,8 +22,10 @@ env-personal is never assembled. The domains gate must be green first.
 """
 import argparse
 import json
+import os
 import pathlib
 import re
+import shlex
 import shutil
 import subprocess
 import sys
@@ -37,6 +39,14 @@ PERSONAL_IMPORT_LINE = "@personal/learnings.md"
 CLAUDE_VAR = "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 CODEX_VAR = "${CODEX_HOME:-$HOME/.codex}"
 CODEX_ONLY_PREFIX = "- Codex-only standing authorization:"
+# Where that bullet belongs. Owned here because the payload cannot import from gates/,
+# and `gates/emit-mirrors.py` — which pins the same position in the STATIC projection —
+# imports it from this module instead, the same direction check-package.sh already takes
+# for `author_only`. The two were independent before, and they disagreed: the projection
+# put the bullet under this heading while the assembler appended it to the end of the
+# bundle, so the deployed AGENTS.md filed a multi-model rule under whatever section
+# happened to come last.
+CODEX_ONLY_ANCHOR = "## Multi-Model Workflow"
 
 ENTRY_SEED = f"""# CLAUDE.md
 
@@ -99,6 +109,30 @@ def parse_monolith(text):
     return title, sections
 
 
+def place_codex_only(bundle, bullet):
+    """Put the Codex-only bullet first under CODEX_ONLY_ANCHOR, or refuse.
+
+    Appending was the old behaviour and it is what put a multi-model rule under Session
+    Learning in every deployed AGENTS.md: the bundle's sections are whatever the selection
+    kept, so "the end" is a different heading depending on what the user installed.
+
+    Refuses rather than falling back to appending. The bullet is only added when
+    `multi-agent-orchestration` is selected, and that domain is what carries the anchor
+    heading, so a missing anchor means the bundle is not the shape this rule assumes —
+    quietly filing the rule somewhere else is how the defect looked in the first place.
+    """
+    lines = bundle.split("\n")
+    hits = [i for i, line in enumerate(lines) if line == CODEX_ONLY_ANCHOR]
+    if len(hits) != 1:
+        die(f"codex bundle must hold exactly one {CODEX_ONLY_ANCHOR!r} to place "
+            f"{CODEX_ONLY_PREFIX!r} under; found {len(hits)}")
+    index = hits[0] + 1
+    while index < len(lines) and not lines[index].strip():
+        index += 1
+    lines.insert(index, bullet)
+    return "\n".join(lines)
+
+
 def build_bundle(monolith_text, manifest, selection, tool):
     entry_of = {}
     for e in manifest["bullets"]:
@@ -226,12 +260,51 @@ def copy_filtered(src_dir, names, dest, rewrite=None, dry=False, backup=None):
         target.write_text(body, encoding="utf-8")
 
 
+def replace_atomically(path, text):
+    """Write via a temp file + os.replace, so a write that fails partway cannot truncate.
+
+    Every file this is used on is one the USER owns and edits — their settings.json, their
+    AGENTS.md — and a plain write_text truncates first and fills after. A short write (a full
+    disk, a crash) left AGENTS.md holding a fragment of our marker and none of their text,
+    with no copy in reach: the backup taken beside these calls is of the PREVIOUS content,
+    which is exactly what a half-written file destroys the value of.
+
+    learn/migrate-learnings.py has had this discipline and states the reason; it now shares
+    this one implementation rather than keeping a second. The temp file is a sibling so the
+    replace stays on one filesystem, where os.replace is atomic.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp-agent-bios")
+    try:
+        tmp.write_text(text, encoding="utf-8")
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+
+
 def hook_command_matches(command, name):
-    """A complete `/hooks/<name>` token: the command ends with it, or it is followed by an
-    argument. One matcher for the merge below AND the domain gate's settings leg — the gate
-    used a substring test, so `central/hooks/<name>.disabled` passed the gate while this
-    merge skipped it, and the install carried no hook under a green gate."""
-    return command.endswith("/hooks/" + name) or f"/hooks/{name} " in command + " "
+    """Does an argv TOKEN of this command end in `/hooks/<name>`?
+
+    One matcher for the merge below AND the domain gate's settings leg — the gate used a
+    substring test, so `central/hooks/<name>.disabled` passed the gate while this merge
+    skipped it, and the install carried no hook under a green gate.
+
+    Split as a shell would, not delimited by spaces. The registration this file writes is
+    `shlex.quote`d so a config home containing a space works, and the quoting puts a `'`
+    right after the filename — so a matcher wanting end-of-string or a following space
+    could not recognize the line it had just written, and every reinstall on a
+    `/Users/First Last` home appended another copy of the same hook. Splitting the way the
+    shell will is the only reading that survives its own quoting.
+
+    Still a PATH match and never a bare name: `wrap.py --inner <name>` passes the name as
+    an argument to somebody else's wrapper, and deleting a stranger's hook is not a right
+    this ownership rule ever claimed."""
+    try:
+        tokens = shlex.split(command)
+    except ValueError:            # unbalanced quotes: not a command we wrote
+        tokens = command.split()
+    return any(token.endswith("/hooks/" + name) for token in tokens)
 
 
 def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names=None):
@@ -250,15 +323,41 @@ def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names
     """
     owned = set(owned_names if owned_names is not None else hook_names)
     spath = claude_dir / "settings.json"
-    settings = json.loads(spath.read_text(encoding="utf-8")) if spath.exists() else {}
+    existed = spath.exists()
+    settings = json.loads(spath.read_text(encoding="utf-8")) if existed else {}
     template = json.loads(template_path.read_text(encoding="utf-8")) if template_path.exists() else {}
     hooks = settings.setdefault("hooks", {})
 
-    def ours(en):
-        return any(n in h.get("command", "") for h in en.get("hooks", []) for n in owned)
-
-    for event, entries in list(hooks.items()):  # drop every entry we own
-        hooks[event] = [en for en in entries if not ours(en)]
+    def ours(hook):
+        # The same matcher the re-add below uses, which `hook_command_matches` already
+        # describes itself as being ("one matcher for the merge below AND the domain
+        # gate"). Only the ADD half honoured that; removal asked whether the name appeared
+        # anywhere in the command, so a user's own entry was deleted for mentioning ours —
+        # `wrap.py --inner tooling-gotchas-hook.py`, a `.bak` copy, a directory named after
+        # it. Deleting a stranger's hook out of their settings is not something the
+        # ownership rule above ever claimed the right to do.
+        return any(hook_command_matches(hook.get("command", ""), n) for n in owned)
+
+    # Pruned per HOOK, not per entry. Ownership is a name on one command, and the entry is
+    # a matcher that can hold several — so `{"matcher": "Bash", "hooks": [ours, theirs]}`
+    # answered "ours" and took the stranger's hook with it. That is the same overreach the
+    # matcher above was narrowed to stop, one level up: the granularity of the removal has
+    # to match the granularity of the claim. An entry left with no hooks was only ever ours,
+    # so it still goes whole.
+    for event, entries in list(hooks.items()):
+        pruned = []
+        for en in entries:
+            children = en.get("hooks") if isinstance(en, dict) else None
+            if not isinstance(children, list):
+                pruned.append(en)          # not a shape we wrote; not ours to judge
+                continue
+            keep = [h for h in children if not (isinstance(h, dict) and ours(h))]
+            if len(keep) == len(children):
+                pruned.append(en)          # nothing of ours in it — untouched
+            elif keep:
+                en["hooks"] = keep         # ours dropped, their siblings stay where they are
+                pruned.append(en)
+        hooks[event] = pruned
     for event, entries in template.get("hooks", {}).items():  # re-add per selection
         for en in entries:
             cmds = [h.get("command", "") for h in en.get("hooks", [])]
@@ -268,16 +367,32 @@ def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names
                 continue
             clone = json.loads(json.dumps(en))
             for h in clone.get("hooks", []):
+                # Quoted, because this lands in a shell command line. A config home with a
+                # space in it — `/Users/First Last/.claude` — split into separate argv
+                # words, so the shell tried to run `/Users/First` and the deployed hook
+                # simply never fired. Nothing reported it: a hook that does not run looks
+                # exactly like a hook with nothing to say.
+                #
+                # A function replacement rather than a string one: shlex.quote emits
+                # backslashes for some paths and re.sub reads those as group references in
+                # a replacement string.
+                target = shlex.quote(str(claude_dir / "central" / "hooks" / owner))
                 h["command"] = re.sub(r"\S*/hooks/" + re.escape(owner),
-                                      str(claude_dir / "central" / "hooks" / owner),
+                                      lambda _match, value=target: value,
                                       h["command"])
             hooks.setdefault(event, []).append(clone)
     if dry:
         print(f"  [dry] merge settings.json ({len(hook_names)} central hooks)")
         return
-    if spath.exists():
+    if not existed and not any(hooks.values()):
+        # Nothing of ours to register and no file to preserve. Writing one would create a
+        # settings.json the user did not have — and this branch is reached by uninstall on a
+        # machine where the claude dir is gone, where creating the directory to hold it
+        # crashed on a missing parent instead.
+        return
+    if existed:
         shutil.copy2(spath, spath.with_suffix(f".json.bak-{time.strftime('%Y%m%d-%H%M%S')}"))
-    spath.write_text(json.dumps(settings, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    replace_atomically(spath, json.dumps(settings, indent=2, ensure_ascii=False) + "\n")
 
 
 def seed_personal_learnings(claude_dir, dry=False):
@@ -335,7 +450,21 @@ def seed_entry(claude_dir, legacy_monolith, prior_deployed=(), dry=False):
     return "needs-action"  # user content without the import line: report, never rewrite
 
 
-def merge_codex(codex_dir, central_text, dry=False):
+def merge_codex(codex_dir, central_text, prior_deployed=(), dry=False):
+    """Write the central region into AGENTS.md, and never silence a file the user wrote.
+
+    A missing marker pair used to mean "legacy whole-file deploy", so any AGENTS.md without
+    them had its active body replaced by the region plus an empty `## Personal`. Every Codex
+    user who wrote an AGENTS.md before installing has exactly that file, and their
+    instructions stopped loading on the first install — the backup made it recoverable, not
+    noticed. Absence of a marker is absence of evidence, in both directions.
+
+    So the same evidence seed_entry uses on the Claude side decides it here: `prior_deployed`
+    is the previous install's manifest, and a path in it is ours by record. Anything else is
+    theirs, and the markers are adopted ABOVE their text rather than over it — which is what
+    the marker pair is for, and it leaves nothing of theirs unloaded. Nothing is lost that
+    way, so that branch needs no backup; the by-record branch keeps the one it always had.
+    """
     agents = codex_dir / "AGENTS.md"
     region = f"{MARK_START}\n{central_text}{MARK_END}\n"
     if agents.exists():
@@ -344,17 +473,21 @@ def merge_codex(codex_dir, central_text, dry=False):
             pre, rest = body.split(MARK_START, 1)
             _, post = rest.split(MARK_END, 1)
             new = pre + region + post
-        else:  # legacy whole-file deploy: back up, adopt markers, keep nothing implicit
+        elif str(pathlib.Path(agents)) in prior_deployed:
+            # Ours by record: an earlier release deployed this file whole, so replacing it
+            # with the marked shape is the upgrade, not a loss.
             if not dry:
                 shutil.copy2(agents, agents.with_suffix(f".md.bak-legacy-{time.strftime('%Y%m%d-%H%M%S')}"))
             new = region + "\n## Personal\n"
+        else:
+            new = region + "\n" + body.lstrip("\n")
     else:
         new = region + "\n## Personal\n"
     if dry:
         print(f"  [dry] write AGENTS.md central region ({len(central_text)} bytes)")
         return
     codex_dir.mkdir(parents=True, exist_ok=True)
-    agents.write_text(new, encoding="utf-8")
+    replace_atomically(agents, new)
 
 
 def remove_owned(claude_dir, codex_dir, manifest, dry=False):
@@ -385,7 +518,7 @@ def remove_owned(claude_dir, codex_dir, manifest, dry=False):
     if dry:
         print("  [dry] strip AGENTS.md central region, keep everything outside the markers")
         return
-    agents.write_text((pre + post).lstrip("\n"), encoding="utf-8")
+    replace_atomically(agents, (pre + post).lstrip("\n"))
 
 
 def main():
@@ -402,6 +535,11 @@ def main():
                          "from it, so an earlier release's deployed CLAUDE.md is recognized as "
                          "ours instead of being reported as the user's.")
     ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--selected-skills", action="store_true",
+                    help="print the names of the shipped skills the selection delivers, one "
+                         "per line, and write nothing. install.sh deploys skills itself (a "
+                         "skill is a tree the HOST scans, not a file under central/) and asks "
+                         "here which ones, so the selection rule keeps one owner")
     args = ap.parse_args()
 
     import os
@@ -409,13 +547,28 @@ def main():
     codex_dir = pathlib.Path(args.codex_dir or os.environ.get("CODEX_HOME") or pathlib.Path.home() / ".codex")
     state_dir = pathlib.Path(args.state_dir or pathlib.Path.home() / ".local/share/agent-bios")
 
-    manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
     if args.remove_owned:
         # No domains gate: removal does not depend on the manifest being well-formed, and an
         # uninstall that refuses to run because the corpus is mid-edit would strand the user.
+        # That was the claim; the parse sat ABOVE this branch and ran first, so a malformed
+        # domains.json raised out of uninstall before the branch that does not need it. The
+        # two halves of the removal need it differently: the Codex region is bounded by our
+        # markers and needs nothing, while the settings registrations are owned BY NAME and
+        # cannot be found without it. So the region goes either way, and a manifest we cannot
+        # read makes the registration half impossible rather than skippable — the caller has
+        # to hear that, not read a clean summary over it.
+        try:
+            manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            remove_owned(claude_dir, codex_dir, {"hooks": {}}, dry=args.dry_run)
+            die(f"the AGENTS.md central region was removed, but {REPO / 'compose' / 'domains.json'} "
+                f"could not be read ({exc}) — the hook registrations it names are STILL in "
+                f"settings.json. Restore that file and re-run uninstall.")
         remove_owned(claude_dir, codex_dir, manifest, dry=args.dry_run)
         return
 
+    manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
+
     gate = subprocess.run([sys.executable, str(REPO / "compose" / "check-domains.py")],
                           capture_output=True, text=True)
     if gate.returncode != 0:
@@ -431,6 +584,16 @@ def main():
     if unknown:
         die(f"unknown domains: {sorted(unknown)} (known: {sorted(manifest['domains'])})")
 
+    if args.selected_skills:
+        # The same two rules the guides get: the manifest's audience, then the file's own
+        # `audience: author` declaration — the gate that tolerates author-side paths in a
+        # declared file assumes the assembler withholds it, and a skill deployed by
+        # install.sh from this list must keep that assumption true.
+        for name in filtered_files(manifest, "skills", selection):
+            if not author_only(REPO / "claude" / "skills" / name / "SKILL.md"):
+                print(name)
+        return
+
     monolith = (REPO / "claude" / "CLAUDE.md").read_text(encoding="utf-8")
     bundle, n_bullets = build_bundle(monolith, manifest, selection, "claude")
     codex_src = (REPO / "codex" / "AGENTS.md").read_text(encoding="utf-8")
@@ -438,7 +601,7 @@ def main():
     if "multi-agent-orchestration" in selection:
         codex_only = next((ln for ln in codex_src.splitlines() if ln.startswith(CODEX_ONLY_PREFIX)), None)
         if codex_only:
-            codex_bundle += codex_only + "\n"
+            codex_bundle = place_codex_only(codex_bundle, codex_only)
 
     guides = filtered_files(manifest, "guides", selection)
     withheld = [n for n in guides if author_only(REPO / "claude" / "guides" / n)]
@@ -492,7 +655,7 @@ def main():
                               prior.read_text(encoding="utf-8").splitlines() if ln.strip()}
     entry_state = seed_entry(claude_dir, monolith, prior_deployed, dry=dry)
 
-    merge_codex(codex_dir, codex_bundle, dry=dry)
+    merge_codex(codex_dir, codex_bundle, prior_deployed, dry=dry)
     copy_filtered(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry,
                   backup=run_backup)
 

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

@@ -114,5 +114,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"]}
   }
 }