agent-bios 0.9.5 → 0.9.7

package/claude/settings.template.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 central/hooks/tooling-gotchas-hook.py"
+          }
+        ]
+      }
+    ]
+  }
+}

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.7",
   "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": {
@@ -8,7 +8,7 @@
   },
   "files": [
     "claude/CLAUDE.md",
-    "claude/settings.json",
+    "claude/settings.template.json",
     "claude/guides/",
     "claude/hooks/",
     "claude/agents/",
@@ -22,11 +22,10 @@
     "config/promotions.json",
     "shell/agent-launch.zsh",
     "scripts/agent-launch.py",
+    "scripts/pkgid.py",
     "scripts/assemble.py",
     "scripts/check-domains.py",
     "scripts/canary.sh",
-    "scripts/build-promotions.py",
-    "scripts/ingest-learnings-export.py",
     "scripts/check-parity.sh",
     "scripts/check-prompting-targets.sh",
     "scripts/check-learning.py",

package/scripts/assemble.py

@@ -299,7 +299,7 @@ def main():
                   rewrite=(f"{CLAUDE_VAR}/guides/", f"{CLAUDE_VAR}/central/guides/"), dry=dry)
     copy_filtered(REPO / "claude" / "hooks", hooks, central / "hooks", dry=dry)
     copy_filtered(REPO / "claude" / "agents", agents, central / "agents", dry=dry)
-    merge_settings(claude_dir, hooks, REPO / "claude" / "settings.json", dry=dry)
+    merge_settings(claude_dir, hooks, REPO / "claude" / "settings.template.json", dry=dry)
     entry_state = seed_entry(claude_dir, monolith, dry=dry)
 
     merge_codex(codex_dir, codex_bundle, dry=dry)

package/scripts/canary.sh

@@ -3,12 +3,29 @@
 # session — file presence cannot detect a declined @import approval or a
 # broken entry import line, so this asks a headless session to echo the
 # bundle's rev marker back.
-# Exit: 0 loaded | 1 not loading (or no bundle) | 3 cannot probe (no CLI).
+#
+# Exit: 0 loading | 1 NOT loading | 3 nothing to probe / cannot probe.
+#
+# The 1-vs-3 split is the point. A canary that answers "not loading" when it
+# never ran a probe sends you to debug imports while the real cause is that
+# there is no packaged bundle here, or that the CLI is not authenticated. Only
+# a real probe that really replied may return 1.
 set -u
 CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 BUNDLE="$CLAUDE_DIR/central/bundle.md"
 
-[ -f "$BUNDLE" ] || { echo "CANARY FAIL: no bundle at $BUNDLE (run: agent-bios install --domains ...)"; exit 1; }
+# A full (non-packaged) install has no central bundle by design — the entry file
+# IS the corpus. That is not a failure, and telling the user to reinstall with
+# --domains would silently narrow their corpus to fix a non-problem.
+if [ ! -f "$BUNDLE" ]; then
+  if [ -f "$CLAUDE_DIR/CLAUDE.md" ]; then
+    echo "CANARY N/A: full install — no central bundle to probe (packaged mode creates one)"
+    exit 3
+  fi
+  echo "CANARY FAIL: no corpus deployed at $CLAUDE_DIR (run: agent-bios install)"
+  exit 1
+fi
+
 expected="$(grep -m1 '^agent-bios-bundle-rev: ' "$BUNDLE")"
 [ -n "$expected" ] || { echo "CANARY FAIL: bundle has no rev marker (reassemble with a current assemble.py)"; exit 1; }
 command -v claude >/dev/null 2>&1 || { echo "CANARY SKIP: claude CLI not found — cannot probe activation"; exit 3; }
@@ -20,6 +37,25 @@ if printf '%s' "$out" | grep -qF "$expected"; then
   echo "CANARY PASS: central bundle is loading ($expected)"
   exit 0
 fi
+
+# A pre-dispatch refusal produces no model output at all, so the reply carries
+# nothing about activation. Attributing it to a declined import would blame the
+# corpus for an auth or quota problem.
+case "$out" in
+  *"Not logged in"*|*"/login"*|*"Invalid API key"*|*"authentication"*|*"Authentication"*)
+    echo "CANARY SKIP: claude CLI is not authenticated for this config dir — cannot probe activation"
+    echo "  probe replied:   $(printf '%s' "$out" | head -c 200)"
+    exit 3 ;;
+  *"usage limit"*|*"rate limit"*|*"quota"*)
+    echo "CANARY SKIP: provider refused the probe (limit) — cannot probe activation"
+    echo "  probe replied:   $(printf '%s' "$out" | head -c 200)"
+    exit 3 ;;
+esac
+if [ -z "$out" ]; then
+  echo "CANARY SKIP: probe produced no output — cannot tell activation from a failed dispatch"
+  exit 3
+fi
+
 echo "CANARY FAIL: central bundle is NOT loading in live sessions."
 echo "  expected marker: $expected"
 echo "  probe replied:   $(printf '%s' "$out" | head -c 200)"

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,16 @@ def run_gate(manifest, bullets, repo=REPO):
     if not tiers or not domains_reg:
         errors.append("registry: tiers/domains registry empty")
 
+    errors += check_settings_template(manifest, repo)
+
+    # -- 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")
@@ -185,6 +198,33 @@ def run_gate(manifest, bullets, repo=REPO):
     return errors, sizes
 
 
+def check_settings_template(manifest, repo=REPO):
+    """Every hook registered in the shipped settings template must be a hook the
+    manifest declares.
+
+    `merge_settings` only re-adds template entries whose command names a
+    manifest-declared hook (assemble.py:167-169), so an entry for anything else
+    is silently inert — it looks registered, ships to every user, and never runs.
+    That is how a machine-local registration ends up committed in a
+    deploy-managed file. Make it invalid instead of asking people to remember.
+    """
+    errors = []
+    spath = repo / "claude" / "settings.template.json"
+    if not spath.is_file():
+        return ["settings: claude/settings.template.json missing"]
+    names = set(manifest.get("hooks", {}))
+    entries = [(ev, h.get("command", ""))
+               for ev, evs in json.loads(spath.read_text(encoding="utf-8")).get("hooks", {}).items()
+               for en in evs for h in en.get("hooks", [])]
+    if not entries:
+        errors.append("non-vacuity: settings template registers no hooks")
+    for ev, cmd in entries:
+        if not any(("/hooks/" + n) in cmd for n in names):
+            errors.append(f"settings: {ev} hook {cmd!r} names no manifest hook "
+                          f"(known: {sorted(names)}) — it would never deploy")
+    return errors
+
+
 def self_test(manifest, bullets):
     """Negative controls: each mutation MUST make the gate fail."""
     import copy
@@ -205,8 +245,22 @@ 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))
+    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))
+
+    # Targeted: the settings rule itself must speak, not just some neighbouring
+    # check tripping on the same mutation.
+    import copy as _c
+    m_off = _c.deepcopy(manifest)
+    m_off["hooks"] = {"renamed-hook.py": {"tier": "core", "domains": []}}
+    settings_errs = [e for e in check_settings_template(m_off) if e.startswith("settings:")]
+    print(f"self-test [{'CAUGHT' if settings_errs else 'MISSED'}] settings rule fires on its own")
 
-    failed = []
+    failed = [] if settings_errs else ["settings rule fires on its own"]
     for name, mm, bb in muts:
         errs, _ = run_gate(mm, bb)
         if not errs:

package/scripts/install.sh

@@ -516,6 +516,10 @@ verify_present() { if [ -f "$1" ]; then return 0; else log "missing  $1"; return
 
 cmd_verify() {
   local fail=0 gp
+  if [ ! -d "$REPO/.git" ] && [ "$(drift_state)" = "drift" ]; then
+    log "deploy drift: deployed $(deployed_version), package $(source_version) — run: agent-bios install"
+    fail=1
+  fi
   if packaged_mode; then
     # Packaged: corpus surfaces are selection-derived, not repo-identical.
     # The entry file is user-owned — READ-check the import line, never rewrite.
@@ -664,6 +668,33 @@ cmd_onboard() {
   }
 }
 
+# ---- deploy-chain drift ---------------------------------------------------
+# A repo edit is inert until it is published AND globally installed AND
+# deployed. The middle two are checkable: the installer stamps the package
+# version it deployed into the state dir, so a stamp older than the package now
+# running means someone updated the package and never re-deployed. Reading the
+# registry cannot see this, which is why it went unnoticed three times.
+json_field() {  # $1=file $2=key
+  [ -f "$1" ] || return 1
+  python3 -c 'import json,sys
+try:
+    v=json.load(open(sys.argv[1])).get(sys.argv[2])
+except Exception:
+    sys.exit(1)
+sys.exit(0) if v is None else print(v)' "$1" "$2" 2>/dev/null
+}
+
+deployed_version() { json_field "$STATE_DIR/version.json" version; }
+source_version()   { json_field "$REPO/package.json" version; }
+
+drift_state() {  # prints: match | drift | unknown
+  local d s
+  d="$(deployed_version)" || { echo unknown; return; }
+  s="$(source_version)"   || { echo unknown; return; }
+  [ -n "$d" ] && [ -n "$s" ] || { echo unknown; return; }
+  [ "$d" = "$s" ] && echo match || echo drift
+}
+
 cmd_status() {
   local version p
   if [ -d "$REPO/.git" ]; then
@@ -676,6 +707,11 @@ cmd_status() {
     log "agent-bios"
   fi
   log "  source:  $REPO"
+  case "$(drift_state)" in
+    match)   info "deployed version $(deployed_version) (matches this package)" ;;
+    drift)   log  "DRIFT    deployed $(deployed_version) but this package is $(source_version) — run: agent-bios install" ;;
+    unknown) info "deployed version unknown (no state marker yet)" ;;
+  esac
   for p in "$CLAUDE_DIR/CLAUDE.md" "$CODEX_DIR/AGENTS.md" "$BIN_DIR/agent-launch" \
            "$LAUNCH_DIR/profiles.toml" "$LAUNCH_DIR/shell.zsh"; do
     if [ -e "$p" ]; then info "present  $p"; else info "MISSING  $p"; fi
@@ -691,6 +727,9 @@ cmd_update() {
   else
     log "Installed as an npm package. Update with:"
     log "  npm install -g agent-bios@latest && agent-bios install"
+    log "Then confirm what actually landed — right after a publish the cached"
+    log "packument can serve the PREVIOUS version at exit 0:"
+    log "  agent-bios status   # must show the version you expected, and no DRIFT"
   fi
 }
 

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

package/claude/settings.json

@@ -1,60 +0,0 @@
-{
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/opt/homebrew/bin/node /Users/kangmin/.claude/hooks/collect-session.js"
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/opt/homebrew/bin/node /Users/kangmin/.claude/hooks/collect-session.js"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/opt/homebrew/bin/node /Users/kangmin/.claude/hooks/collect-session.js"
-          }
-        ]
-      }
-    ],
-    "PostToolUseFailure": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/opt/homebrew/bin/node /Users/kangmin/.claude/hooks/collect-session.js"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 /Users/kangmin/.claude/hooks/tooling-gotchas-hook.py"
-          }
-        ]
-      }
-    ]
-  },
-  "remoteControlAtStartup": false
-}

package/scripts/build-promotions.py

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

package/scripts/ingest-learnings-export.py

@@ -1,258 +0,0 @@
-#!/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()