agent-bios 0.9.4 → 0.9.6

package/scripts/ingest-learnings-export.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Curation intake — map a dashboard learnings export to ledger candidates.
+
+Phase 3 of the collection loop (design/collection-loop/PHASE3-CURATION-DESIGN.md).
+The curator exports RECEIVED learnings from the dashboard as ledger-compatible
+JSON (GET /api/exports/learnings — verbatim payloads + provenance); THIS script
+does the DETERMINISTIC half of intake:
+
+  * validates each exported record against config/learning.schema.json — the
+    single validation source, reused from scripts/check-learning.py (no second
+    schema), so an invalid/verbatim-but-nonconforming payload is caught here;
+  * buckets each row: VALID → a ledger-candidate entry; REJECTED → schema or
+    domain-membership failure (with the reasons); DEFERRED → schema_version != 1
+    (Phase 2 stores v2+ verbatim for forward-compat; the v1 intake cannot map it
+    yet — it is NOT a reject, it is re-exportable once a v2-aware intake lands);
+  * flags candidates whose learning_id already appears in ledger.json (a
+    deterministic dedup warning — string membership, not a semantic judgment);
+  * emits a curation WORKLIST the curator then works through by hand.
+
+It does NOT do the SEMANTIC half — triage the domain, classify type/layer/
+mechanism, or judge novelty vs the full canon. Those stay with the curator
+(capability boundary); see design/collection-loop/CURATION-INTAKE.md.
+
+PII boundary: the worklist carries `_provenance.user_email` (D3.3 — visibility
+into who contributes what). The worklist is a LOCAL artifact — never commit it;
+when merging a candidate into the git-tracked ledger.json, keep `learning_id`
+(non-PII dedup key) and DROP `_provenance` (see the procedure doc).
+
+Input:  a learnings-export JSON file (positional arg; '-' or omitted = stdin).
+Output: the worklist JSON to stdout, or to --out FILE.
+"""
+import argparse
+import importlib.util
+import json
+import pathlib
+import sys
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+LEDGER = REPO / "design" / "session-distill" / "ledger.json"
+FIXTURE = REPO / "design" / "collection-loop" / "fixtures" / "export-sample.json"
+SUPPORTED_SCHEMA_VERSION = 1
+
+
+def die(msg, code=1):
+    print(f"ingest-learnings-export: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def load_checker():
+    """Reuse scripts/check-learning.py as the single validation source."""
+    path = REPO / "scripts" / "check-learning.py"
+    spec = importlib.util.spec_from_file_location("check_learning", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_ledger_learning_ids(path=LEDGER):
+    """learning_ids already present in the ledger (dedup key). Entries sourced
+    from earlier learnings carry a top-level `learning_id`; the historical
+    session-distill entries do not, so they simply contribute nothing here.
+    A missing/unreadable ledger is not fatal — dedup just finds nothing."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return set()
+    out = set()
+    for e in data.get("entries", []):
+        lid = e.get("learning_id") if isinstance(e, dict) else None
+        if isinstance(lid, str) and lid:
+            out.add(lid.lower())
+    return out
+
+
+def map_candidate(payload, row):
+    """A validated export row -> a ledger-candidate entry (ledger.json shape).
+    Deterministic fields the record carries are copied; curator-only fields are
+    null for the curator to fill. `_provenance` is worklist-only (strip before
+    the ledger merge)."""
+    cls = payload.get("classification") or {}
+    return {
+        "id": None,                                   # curator assigns (e.g. S4-02)
+        "learning_id": payload.get("learning_id"),    # kept in ledger = dedup key
+        "lesson": payload.get("lesson"),
+        "strength": None,                             # curator: recurrence
+        "verdict": None,                              # curator: novel|partial|principle
+        "criteria": payload.get("criteria", []),
+        "supporting_sessions": payload.get("supporting_sessions", []),
+        "domain": payload.get("domain"),
+        "proposed_domain": payload.get("proposed_domain"),
+        "context": payload.get("context"),            # curator-facing evidence note
+        "classification": {
+            "type": cls.get("type"),
+            "underlying_value": None,
+            "reformulation": None,
+            "meets_promotion_bar": cls.get("meets_bar"),
+            "layer": cls.get("layer"),
+            "mechanism": None,
+            "token_est": None,
+            "consumer_note": None,
+            "split": None,
+            "verification": None,
+            "proposed": False,                        # ledger convention: boolean
+        },
+        "status": "candidate",
+        "_provenance": {
+            "user_email": row.get("user_email"),      # PII — worklist only, strip on merge
+            "received_at": row.get("received_at"),    # server receipt time
+            "created": payload.get("created"),        # user capture time (distinct)
+            "schema_version": payload.get("schema_version"),
+        },
+    }
+
+
+def process_export(export, checker, ledger_ids):
+    """Bucket every export row. Deterministic: input order preserved, no
+    timestamps, so the same input yields byte-identical output."""
+    if not isinstance(export, dict) or not isinstance(export.get("learnings"), list):
+        die("not a learnings-export (expected an object with a `learnings` array)")
+
+    validator = checker.build_validator()
+    domain_values = checker.valid_domain_values()
+
+    entries, rejected, deferred, duplicates, warnings = [], [], [], [], []
+    for i, row in enumerate(export["learnings"]):
+        if not isinstance(row, dict) or not isinstance(row.get("payload"), dict):
+            rejected.append({"index": i, "learning_id": None,
+                             "reasons": ["export row has no payload object"]})
+            continue
+        payload = row["payload"]
+        lid = payload.get("learning_id")
+
+        sv = payload.get("schema_version")
+        if sv != SUPPORTED_SCHEMA_VERSION:
+            deferred.append({"index": i, "learning_id": lid, "schema_version": sv,
+                             "note": "re-export once a v%s-aware intake exists "
+                                     "(row stays available via includeExported)" % sv})
+            continue
+
+        errors = checker.validate_record(payload, validator, domain_values)
+        if errors:
+            rejected.append({"index": i, "learning_id": lid, "reasons": errors})
+            continue
+
+        # server-bug detector: the export's domain column should mirror payload.domain.
+        if row.get("domain") != payload.get("domain"):
+            warnings.append({"index": i, "learning_id": lid,
+                             "detail": "export domain column %r != payload.domain %r"
+                                       % (row.get("domain"), payload.get("domain"))})
+
+        cand = map_candidate(payload, row)
+        if isinstance(lid, str) and lid.lower() in ledger_ids:
+            cand["duplicate_in_ledger"] = True
+            duplicates.append({"index": i, "learning_id": lid})
+        entries.append(cand)
+
+    return {
+        "source": "curation-intake",
+        "generated_from": export.get("source", "learnings-export"),
+        "counts": {"valid": len(entries), "rejected": len(rejected),
+                   "deferred": len(deferred), "duplicates": len(duplicates),
+                   "warnings": len(warnings)},
+        "warnings": warnings,
+        "rejected": rejected,
+        "deferred": deferred,
+        "entries": entries,
+    }
+
+
+def run(export, out_path=None):
+    worklist = process_export(export, load_checker(), load_ledger_learning_ids())
+    text = json.dumps(worklist, ensure_ascii=False, indent=2) + "\n"
+    if out_path and out_path != "-":
+        pathlib.Path(out_path).write_text(text, encoding="utf-8")
+        c = worklist["counts"]
+        print(f"ingest-learnings-export: wrote {out_path} "
+              f"(valid={c['valid']} rejected={c['rejected']} deferred={c['deferred']} "
+              f"duplicates={c['duplicates']})", file=sys.stderr)
+    else:
+        sys.stdout.write(text)
+    return worklist
+
+
+def _self_test():
+    """Verify bucketing against the committed export fixture (the cross-repo
+    contract artifact): valid rows map (cardinality > 0), a bad-domain row is
+    rejected with a domain reason (negative control), a v2 row is deferred not
+    rejected, mapping preserves context + meets_bar rename, and output is
+    deterministic. Exits non-zero on any failure."""
+    export = json.loads(FIXTURE.read_text(encoding="utf-8"))
+    checker = load_checker()
+    w1 = process_export(export, checker, {"0f8c1c2a-4d1e-4abc-9def-000000000001"})
+    w2 = process_export(export, checker, {"0f8c1c2a-4d1e-4abc-9def-000000000001"})
+
+    valid_ids = {e["learning_id"] for e in w1["entries"]}
+    rej_reasons = " ".join(r for row in w1["rejected"] for r in row["reasons"])
+    deferred_svs = {d["schema_version"] for d in w1["deferred"]}
+    full = next((e for e in w1["entries"]
+                 if e["learning_id"] == "0f8c1c2a-4d1e-4abc-9def-000000000002"), None)
+
+    checks = [
+        ("valid rows mapped (cardinality > 0)", w1["counts"]["valid"] >= 3),
+        ("bad-domain row rejected", w1["counts"]["rejected"] >= 1),
+        ("reject reason names the domain (negative control)", "domain" in rej_reasons),
+        ("v2 row deferred, not rejected", deferred_svs == {2}),
+        ("deferred row absent from entries",
+         "0f8c1c2a-4d1e-4abc-9def-00000000000a" not in valid_ids),
+        ("context preserved verbatim", full is not None and full["context"]
+         and "4분짜리" in full["context"]),
+        ("meets_bar -> meets_promotion_bar",
+         full is not None and full["classification"]["meets_promotion_bar"] is True),
+        ("classification.proposed is boolean false",
+         full is not None and full["classification"]["proposed"] is False),
+        ("provenance carries user_email (worklist-only PII)",
+         full is not None and full["_provenance"]["user_email"] == "alice@day1company.co.kr"),
+        ("provenance keeps both created and received_at",
+         full is not None and full["_provenance"]["created"] != full["_provenance"]["received_at"]),
+        ("ledger dedup flags a known learning_id", w1["counts"]["duplicates"] == 1),
+        ("deterministic (same input -> identical output)",
+         json.dumps(w1, ensure_ascii=False) == json.dumps(w2, ensure_ascii=False)),
+    ]
+    failed = [name for name, ok in checks if not ok]
+    if failed:
+        for name in failed:
+            print(f"ingest-learnings-export --self-test: FAIL: {name}", file=sys.stderr)
+        sys.exit(1)
+    print(f"ingest-learnings-export --self-test: OK ({len(checks)} intake checks)")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Map a learnings export to ledger candidates.")
+    ap.add_argument("export", nargs="?", default="-",
+                    help="learnings-export JSON file ('-' or omitted = stdin)")
+    ap.add_argument("--out", default=None, help="write the worklist here (default: stdout)")
+    ap.add_argument("--self-test", action="store_true",
+                    help="run the intake self-test against the fixture and exit")
+    args = ap.parse_args()
+
+    if args.self_test:
+        _self_test()
+        return
+
+    if args.export == "-":
+        raw = sys.stdin.read()
+    else:
+        try:
+            raw = pathlib.Path(args.export).read_text(encoding="utf-8")
+        except OSError as e:
+            die(f"cannot read export {args.export!r}: {e}")
+    try:
+        export = json.loads(raw)
+    except json.JSONDecodeError as e:
+        die(f"export is not valid JSON: {e}")
+    run(export, args.out)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install.sh

@@ -23,6 +23,9 @@ set -euo pipefail
 # or env var. Detach stdin so no child (the codex-helm dry-run, pip, git) can
 # block forever on an inherited idle stdin — that is what hangs an install under
 # CI, pipes, and background runs, where stdin stays open but never delivers.
+# `learn` is the one subcommand whose payload IS stdin, so keep the caller's on
+# fd 3 first and hand it back only there; every other path still sees /dev/null.
+exec 3<&0 2>/dev/null || exec 3</dev/null   # tolerate a caller that closed fd 0
 exec </dev/null
 
 # Resolve this script through symlinks before locating the package: npm links the
@@ -562,6 +565,16 @@ PY
   else
     log "note: managed venv/textual unavailable (numbered-prompt fallback applies)"
   fi
+  # A file this installer executes but never ships is invisible from a clone and
+  # fatal on npm, so the payload gate runs wherever it exists (maintainer-side).
+  if [ -x "$REPO/scripts/check-package.sh" ]; then
+    if "$REPO/scripts/check-package.sh" >/dev/null 2>&1; then
+      info "npm payload OK"
+    else
+      log "npm payload incomplete; run scripts/check-package.sh"
+      fail=1
+    fi
+  fi
   # Repo-internal mirror parity is a maintainer gate; only meaningful from a clone.
   if [ -d "$REPO/ko" ] && [ -x "$REPO/scripts/check-parity.sh" ]; then
     if "$REPO/scripts/check-parity.sh" >/dev/null 2>&1; then info "repo mirror parity OK"; else log "repo mirror parity FAILED"; fail=1; fi
@@ -688,6 +701,9 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
   agent-bios install     deploy into this environment (backs up + verifies)
   agent-bios onboard     interactive domain selection + packaged install + activation canary
   agent-bios verify      check the deployed state matches the source
+  agent-bios learn       submit a session learning (reads the JSON record on
+                         stdin; this is what the learn! flow calls, and it
+                         works from any directory, unlike a repo-relative path)
   agent-bios status      show what is installed and where
   agent-bios update      git pull + reinstall (clone), or print the npm update line
   agent-bios uninstall   remove deployed files and the zsh hook
@@ -713,6 +729,18 @@ EOF
 # ---- dispatch ------------------------------------------------------------
 CMD="${1:-help}"
 if [ $# -gt 0 ]; then shift; fi
+
+# `learn` forwards its arguments and stdin straight to the collector, so it must
+# bypass the flag parser below (which rejects anything it does not know). This
+# subcommand is the only PATH-reachable entry to capture: the corpus guide used
+# to invoke scripts/collect-learning.py relative to the cwd, which works from a
+# clone and silently fails for every other install.
+if [ "$CMD" = "learn" ]; then
+  collector="$REPO/scripts/collect-learning.py"
+  [ -f "$collector" ] || { log "learn: collector missing at $collector"; exit 1; }
+  exec python3 "$collector" "$@" <&3
+fi
+
 WITH=""
 DOMAINS_ARG=""
 DOMAINS_SET=0

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))