agent-bios 0.9.5 → 0.9.6

package/config/domains.json

@@ -1,5 +1,6 @@
 {
   "version": 1,
+  "package_id": "@agent-bios/core",
   "tiers": ["core", "domain", "env-personal", "infra"],
   "domains": {
     "builder-base": "Technical-common: coding, verification menus, documentation hygiene, tooling safety, concept economy",

package/config/promotions.json

@@ -1,8 +1,10 @@
 {
-  "version": 1,
+  "version": 2,
   "promotions": [
     {
       "learning_id": "a6feee41-2aeb-4fb6-acc6-4584c5c1336c",
+      "package_id": "@agent-bios/core",
+      "anchor": "tooling-gotchas.md",
       "tier": "domain",
       "domains": [
         "builder-base"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bios",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "releaseDate": "2026-07-26",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
@@ -22,6 +22,7 @@
     "config/promotions.json",
     "shell/agent-launch.zsh",
     "scripts/agent-launch.py",
+    "scripts/pkgid.py",
     "scripts/assemble.py",
     "scripts/check-domains.py",
     "scripts/canary.sh",

package/scripts/build-promotions.py

@@ -29,12 +29,15 @@ 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 = 1
+MANIFEST_VERSION = 2
 
 
 class ManifestError(Exception):
@@ -80,7 +83,16 @@ def build_manifest(ledger, domains_manifest):
                 f"placed_anchor {anchor!r} (learning {lid}) does not resolve in "
                 "config/domains.json — the promotion has no verifiable placement")
         tier, domains = aud
-        promotions.append({"learning_id": lid.lower(), "tier": tier, "domains": domains})
+        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}
 
@@ -133,6 +145,21 @@ def _self_test():
     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:

package/scripts/check-domains.py

@@ -32,6 +32,9 @@ 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"
@@ -87,6 +90,14 @@ def run_gate(manifest, bullets, repo=REPO):
     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")
@@ -205,6 +216,9 @@ def self_test(manifest, bullets):
     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:

package/scripts/migrate-learnings.py

@@ -13,7 +13,15 @@ bundle. Per-domain opt-in means a promotion into a package the user did NOT
 install must NOT trigger removal — that would silently lose the learning. When
 unsure, KEEP (a kept duplicate is redundant; a wrong removal is data loss).
 
-Bundle membership (mirrors scripts/assemble.py `kept`): full install (original
+HOW THAT RULE IS ENFORCED (contract v2): audience metadata SELECTS candidates,
+presence in the deployed corpus AUTHORIZES the delete. Metadata is a build-time
+projection — it cannot see that this user runs a package or version whose bundle
+never received the promoted bullet — so it is never the authority for an
+irreversible act. Every uncertainty resolves to KEEP: a foreign package we
+cannot confirm, an audience miss, an anchor absent from the corpus, a v1 record
+with no anchor to verify.
+
+Candidate selection (mirrors scripts/assemble.py `kept`): full install (original
 single-zone / no selection) -> everything installed; universal tier (core/infra)
 -> always installed; a domain key -> installed iff in the user's selection;
 anything else (env-personal / unclassified / unknown) -> KEEP.
@@ -31,6 +39,9 @@ import shutil
 import sys
 import time
 
+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
 MANIFEST = REPO / "config" / "promotions.json"
 UNIVERSAL_TIERS = frozenset({"core", "infra"})  # == assemble.audience UNIVERSAL
@@ -86,6 +97,59 @@ def make_in_bundle(full, selection):
     return in_bundle
 
 
+def corpus_surfaces(home):
+    """Files and dirs that hold the DEPLOYED corpus for this host.
+
+    Deliberately excludes `personal/` — the user's own copy of a promoted
+    learning quotes the same lesson, so searching it would find the very thing
+    we are deciding whether to delete and always answer yes.
+    """
+    texts = [home / "central" / "bundle.md",   # packaged install
+             home / "CLAUDE.md", home / "AGENTS.md"]  # full install (entry is the corpus)
+    dirs = [home / "central" / d for d in ("guides", "hooks", "agents")]
+    dirs += [home / d for d in ("guides", "hooks", "agents")]
+    return texts, dirs
+
+
+def corpus_text(path, collect=None):
+    """A corpus file's text with the user's personal region removed.
+
+    On codex the personal copy lives INSIDE AGENTS.md, and a promoted bullet is
+    written FROM the user's lesson — so its anchor can legitimately appear in
+    their own bullet. Searching the region would let a personal copy authorize
+    its own deletion. Strip it before matching.
+    """
+    body = path.read_text(encoding="utf-8", errors="replace")
+    if collect is None:
+        return body
+    start, end = getattr(collect, "PERSONAL_START", None), getattr(collect, "PERSONAL_END", None)
+    if start and end and start in body:
+        pre, rest = body.split(start, 1)
+        return pre + (rest.split(end, 1)[1] if end in rest else "")
+    return body
+
+
+def placed_here(home, anchor, collect=None):
+    """Is the promoted item REALLY in this user's deployed corpus?
+
+    This is the authorization for an irreversible delete, so it asks the
+    filesystem rather than trusting build-time audience metadata, which is a
+    projection that goes stale the moment packages or versions diverge. A whole
+    guide/hook/agent placement is a deployed file; a bullet placement is its
+    anchor appearing in the deployed corpus text.
+    """
+    if not isinstance(anchor, str) or not anchor:
+        return False
+    texts, dirs = corpus_surfaces(home)
+    for d in dirs:
+        if (d / anchor).is_file():
+            return True
+    for f in texts:
+        if f.is_file() and anchor in corpus_text(f, collect):
+            return True
+    return False
+
+
 def backup(path):
     shutil.copy2(path, path.with_suffix(path.suffix + f".bak-migrate-{time.strftime('%Y%m%d-%H%M%S')}"))
 
@@ -202,15 +266,29 @@ def migrate(home, host, promotions, in_bundle, collect, dry=False, corpus_loaded
             if isinstance(lid, str):
                 local_ids.add(lid)
 
-    remove_ids, kept_not_in_bundle = set(), 0
+    # Metadata SELECTS candidates; presence in the deployed corpus AUTHORIZES the
+    # delete (contract v2 §4). Audience metadata is a build-time projection: it
+    # cannot see that this user is on a package or version whose bundle never
+    # received the promoted bullet, and acting on it alone loses the learning.
+    # Every uncertainty below resolves to KEEP.
+    remove_ids, kept_not_in_bundle, kept_not_placed, kept_foreign_pkg = set(), 0, 0, 0
     for p in promotions:
         lid = p["learning_id"]
         if lid not in local_ids:
             continue  # not held locally (never captured here, or already migrated)
-        if in_bundle(p.get("tier"), p.get("domains", [])):
-            remove_ids.add(lid)
-        else:
-            kept_not_in_bundle += 1  # promoted but not in THIS user's bundle -> keep
+        pid = pkgid.resolve(p)
+        if pid != pkgid.CORE:
+            # Stage 3 resolves a package selection; until then the only package
+            # whose composition we can confirm is core.
+            kept_foreign_pkg += 1
+            continue
+        if not in_bundle(p.get("tier"), p.get("domains", [])):
+            kept_not_in_bundle += 1  # promoted but not in THIS user's audience
+            continue
+        if not placed_here(home, p.get("anchor"), collect):
+            kept_not_placed += 1     # audience says yes, the corpus does not have it
+            continue
+        remove_ids.add(lid)
 
     # Prune PROSE first, jsonl second: the gate keys off ids still in the jsonl
     # (line ~"if lid not in local_ids: continue"), so if a prose write fails, the
@@ -223,7 +301,8 @@ def migrate(home, host, promotions, in_bundle, collect, dry=False, corpus_loaded
     jsonl_removed = prune_jsonl(jsonl, remove_ids, dry)
 
     return {"removed": len(remove_ids), "jsonl_removed": jsonl_removed,
-            "prose_removed": prose_removed, "kept_not_in_bundle": kept_not_in_bundle}
+            "prose_removed": prose_removed, "kept_not_in_bundle": kept_not_in_bundle,
+            "kept_not_placed": kept_not_placed, "kept_foreign_package": kept_foreign_pkg}
 
 
 def main():
@@ -308,13 +387,21 @@ def _self_test():
     L = {"core": "0f8c1c2a-4d1e-4abc-9def-0000000000a1",
          "bb": "0f8c1c2a-4d1e-4abc-9def-0000000000b2",
          "off": "0f8c1c2a-4d1e-4abc-9def-0000000000c3"}
-    promos = [{"learning_id": L["core"], "tier": "core", "domains": []},
-              {"learning_id": L["bb"], "tier": "domain", "domains": ["builder-base"]},
-              {"learning_id": L["off"], "tier": "domain", "domains": ["office-work"]}]
-
-    def seed_claude():
+    A = {"core": "universal corpus rule", "bb": "builder corpus rule",
+         "off": "office corpus rule"}
+    promos = [{"learning_id": L["core"], "anchor": A["core"], "tier": "core", "domains": []},
+              {"learning_id": L["bb"], "anchor": A["bb"], "tier": "domain", "domains": ["builder-base"]},
+              {"learning_id": L["off"], "anchor": A["off"], "tier": "domain", "domains": ["office-work"]}]
+
+    def seed_claude(placed=("core", "bb", "off")):
+        """`placed` = which promoted anchors this user's DEPLOYED corpus actually
+        carries. Deletion is authorized by that, not by the audience metadata, so
+        a fixture without a corpus would let a metadata-only bug pass."""
         home = pathlib.Path(tempfile.mkdtemp(prefix="migrate-selftest-"))
         (home / "personal").mkdir(parents=True)
+        (home / "central").mkdir(parents=True)
+        (home / "central" / "bundle.md").write_text(
+            "# bundle\n" + "".join(f"- {A[k]}\n" for k in placed), encoding="utf-8")
         jsonl = home / "personal" / "learnings.jsonl"
         with open(jsonl, "w", encoding="utf-8") as f:
             for k, dom in (("core", "core"), ("bb", "builder-base"), ("off", "office-work")):
@@ -350,6 +437,35 @@ def _self_test():
     s2 = migrate(home, "claude", promos, in_bundle, collect)
     checks.append(("idempotent re-run", s2["removed"] == 0))
 
+    # 1b) CONTRAST CONTROL for the v2 authorization. Same audience metadata as
+    #     above — builder-base IS selected — but this user's deployed corpus does
+    #     NOT carry the bullet (a package/version whose bundle never got it). The
+    #     metadata-only rule deletes here and loses the learning; presence keeps.
+    #     If placed_here() ever returns True unconditionally, this check fails.
+    home = seed_claude(placed=("core",))
+    s = migrate(home, "claude", promos, make_in_bundle(False, ["builder-base"]), collect)
+    checks.append(("audience says yes but corpus lacks it -> KEEP",
+                   s["removed"] == 1 and s["kept_not_placed"] == 1
+                   and L["bb"] in local_ids(home) and md_has(home, L["bb"])))
+
+    # 1c) A promotion from a package whose composition cannot be confirmed is
+    #     never acted on (stage 3 resolves package selections).
+    home = seed_claude()
+    foreign = [dict(promos[1], package_id="@acme/security")]
+    s = migrate(home, "claude", foreign, make_in_bundle(True, ()), collect)
+    checks.append(("foreign package -> KEEP",
+                   s["removed"] == 0 and s["kept_foreign_package"] == 1))
+
+    # 1d) The personal copy must not authorize its own deletion: on codex the
+    #     copy lives inside AGENTS.md, so the anchor can appear there legitimately.
+    ahome = pathlib.Path(tempfile.mkdtemp(prefix="migrate-selfauth-"))
+    (ahome / "AGENTS.md").write_text(
+        f"# AGENTS.md\n{collect.PERSONAL_START}\n- {A['bb']}\n{collect.PERSONAL_END}\n",
+        encoding="utf-8")
+    checks.append(("personal region cannot authorize its own delete",
+                   placed_here(ahome, A["bb"], collect) is False
+                   and placed_here(ahome, A["bb"], None) is True))
+
     # 2) Full (non-packaged) install: everything in bundle -> all removed.
     home = seed_claude()
     s = migrate(home, "claude", promos, make_in_bundle(True, ()), collect)
@@ -365,6 +481,7 @@ def _self_test():
     # 4) codex host: seed the AGENTS.md region, migrate prunes it there.
     chome = pathlib.Path(tempfile.mkdtemp(prefix="migrate-codex-"))
     (chome / "personal").mkdir(parents=True)
+    (chome / "AGENTS.md").write_text(f"# AGENTS.md\n- {A['bb']}\n", encoding="utf-8")
     with open(chome / "personal" / "learnings.jsonl", "w", encoding="utf-8") as f:
         r = rec(L["bb"], "builder-base")
         f.write(json.dumps(r, ensure_ascii=False) + "\n")

package/scripts/pkgid.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Canonical package identity for the domain-package ecosystem (contract v2).
+
+A package is `@scope/name` — **unversioned**, and independent of the domains it
+declares. A domain's canonical identity is the pair `(package_id, domain)`, so a
+bare domain string is only meaningful relative to a package.
+
+`CORE` is the built-in engine manifest. A manifest or record that carries no
+package id means `CORE`, permanently: that reservation is what keeps every
+artifact written before v2 — selections, promotions, ledger placements — valid
+with no migration.
+
+Spec: design/adapter-split/ECOSYSTEM-ARCHITECTURE.md, "Foundational contract v2".
+"""
+import re
+
+CORE = "@agent-bios/core"
+
+_SEG = r"[a-z0-9]+(?:-[a-z0-9]+)*"
+PATTERN = re.compile(rf"^@{_SEG}/{_SEG}$")
+
+
+def is_valid(pid):
+    """True for a well-formed package id. Callers validate before deriving paths."""
+    return isinstance(pid, str) and PATTERN.match(pid) is not None
+
+
+def resolve(obj, key="package_id"):
+    """The package id an object declares, or CORE when it declares none.
+
+    Absent means CORE — never guess from context, and never treat a present but
+    malformed id as absent: that would silently promote a typo to core's
+    authority. Validate with is_valid() where the value is first accepted.
+    """
+    if not isinstance(obj, dict):
+        return CORE
+    pid = obj.get(key)
+    return CORE if pid is None else pid
+
+
+def segments(pid):
+    """('scope', 'name') for deriving deploy paths. Only call on a valid id."""
+    if not is_valid(pid):
+        raise ValueError(f"not a package id: {pid!r}")
+    return tuple(pid[1:].split("/", 1))