agent-bios 0.9.4 → 0.9.5

package/claude/CLAUDE.md

@@ -150,4 +150,4 @@
 
 ## Session Learning
 
-- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `scripts/collect-learning.py`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).
+- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `agent-bios learn`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).

package/claude/guides/learning-flow.md

@@ -9,7 +9,7 @@ use_when:
 core_rules:
   - three gates BEFORE asking the user — admission bar, type, consumption layer
   - the user approves every recorded learning; nothing is written without it
-  - submit ONLY through scripts/collect-learning.py; never hand-write the record
+  - submit ONLY through `agent-bios learn`; never hand-write the record
 ---
 
 # Session learning flow (`learn!`)
@@ -83,7 +83,7 @@ match your host):
     echo '{"lesson":"…","domain":"builder-base","supporting_sessions":["<tool>:<session-short-id>"],
            "criteria":["recurrent_error"],
            "classification":{"type":"B","layer":"hook","meets_bar":true}}' \
-      | python3 scripts/collect-learning.py --host <claude|codex>
+      | agent-bios learn --host <claude|codex>
 
 The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
 validates against `config/learning.schema.json`, logs the JSON record, and writes

package/claude/settings.json

@@ -0,0 +1,60 @@
+{
+  "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/codex/AGENTS.md

@@ -151,4 +151,4 @@
 
 ## Session Learning
 
-- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CODEX_HOME:-$HOME/.codex}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `scripts/collect-learning.py`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).
+- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CODEX_HOME:-$HOME/.codex}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `agent-bios learn`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).

package/codex/guides/learning-flow.md

@@ -9,7 +9,7 @@ use_when:
 core_rules:
   - three gates BEFORE asking the user — admission bar, type, consumption layer
   - the user approves every recorded learning; nothing is written without it
-  - submit ONLY through scripts/collect-learning.py; never hand-write the record
+  - submit ONLY through `agent-bios learn`; never hand-write the record
 ---
 
 # Session learning flow (`learn!`)
@@ -83,7 +83,7 @@ match your host):
     echo '{"lesson":"…","domain":"builder-base","supporting_sessions":["<tool>:<session-short-id>"],
            "criteria":["recurrent_error"],
            "classification":{"type":"B","layer":"hook","meets_bar":true}}' \
-      | python3 scripts/collect-learning.py --host <claude|codex>
+      | agent-bios learn --host <claude|codex>
 
 The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
 validates against `config/learning.schema.json`, logs the JSON record, and writes

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "agent-bios",
-  "version": "0.9.4",
-  "releaseDate": "2026-07-25",
+  "version": "0.9.5",
+  "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": {
     "agent-bios": "scripts/install.sh"
   },
   "files": [
     "claude/CLAUDE.md",
+    "claude/settings.json",
     "claude/guides/",
     "claude/hooks/",
     "claude/agents/",
@@ -21,6 +22,11 @@
     "config/promotions.json",
     "shell/agent-launch.zsh",
     "scripts/agent-launch.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

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""Per-selection assembler: canonical corpus + domains.json -> deployed trees.
+
+Claude side (central-managed tree, overwritten on every run):
+  <claude-dir>/central/bundle.md     core+infra+selected-domain bullets, the
+                                     monolith's section structure preserved,
+                                     guide references rewritten to central/guides/
+  <claude-dir>/central/guides|hooks|agents/   audience-filtered copies
+  <claude-dir>/settings.json         merge, not overwrite: entries whose hook
+                                     command lives under central/hooks/ are
+                                     central-owned (path IS the ownership
+                                     marker); user-owned entries untouched
+Entry file (<claude-dir>/CLAUDE.md) is personal-owned: seeded once when absent
+(or when it byte-matches the legacy deployed monolith), read-checked otherwise
+— never rewritten. Exit 2 = entry file needs user action.
+
+Codex side: AGENTS.md central region between markers is replaced; text outside
+the markers is preserved (weaker-guarantee realization; AGENTS.md has no
+imports). Codex guides deploy filtered to <codex-dir>/guides as today.
+
+env-personal is never assembled. The domains gate must be green first.
+"""
+import argparse
+import json
+import pathlib
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+MARK_START = "<!-- agent-bios:central:start -->"
+MARK_END = "<!-- agent-bios:central:end -->"
+IMPORT_LINE = "@central/bundle.md"
+PERSONAL_IMPORT_LINE = "@personal/learnings.md"
+CLAUDE_VAR = "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+CODEX_VAR = "${CODEX_HOME:-$HOME/.codex}"
+CODEX_ONLY_PREFIX = "- Codex-only standing authorization:"
+
+ENTRY_SEED = f"""# CLAUDE.md
+
+{IMPORT_LINE}
+{PERSONAL_IMPORT_LINE}
+
+## Personal
+<!-- Yours. The installer never rewrites this file after seeding. The first
+     import pulls in the centrally managed bundle; the second pulls in your
+     session learning file ({CLAUDE_VAR}/personal/learnings.md — automation-owned,
+     written by `learn!`). Add your own personal rules below. -->
+"""
+
+# Automation-owned personal learnings file, pulled in by PERSONAL_IMPORT_LINE.
+# Kept in sync with scripts/collect-learning.py (the light-flow submit tool),
+# which appends learnings here; seeding it keeps the import from dangling.
+PERSONAL_LEARNINGS_HEADER = """# Personal learnings
+
+<!-- Automation-owned: written by the session learning flow (`learn!`,
+     scripts/collect-learning.py). Do NOT hand-edit — promote→migrate clears
+     applied items by learning_id when the org redistributes them. Your own
+     personal rules belong in the entry CLAUDE.md '## Personal' section, never
+     here. This file is pulled into context by the entry file's
+     `@personal/learnings.md` import. -->
+"""
+
+
+def die(msg, code=1):
+    print(f"assemble: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def audience(entry):
+    tier = entry.get("tier")
+    if tier in ("core", "infra"):
+        return "UNIVERSAL"
+    if tier == "domain":
+        return frozenset(entry.get("domains", []))
+    return "NEVER"  # env-personal
+
+
+def kept(entry, selection):
+    aud = audience(entry)
+    return aud == "UNIVERSAL" or (isinstance(aud, frozenset) and aud & selection)
+
+
+def parse_monolith(text):
+    """-> (title, [(header, [bullets])])"""
+    title, sections, cur = None, [], None
+    for ln in text.splitlines():
+        if ln.startswith("# ") and title is None:
+            title = ln
+        elif ln.startswith("## "):
+            cur = (ln, [])
+            sections.append(cur)
+        elif ln.startswith("- "):
+            if cur is None:
+                die("bullet before first section header")
+            cur[1].append(ln)
+    return title, sections
+
+
+def build_bundle(monolith_text, manifest, selection, tool):
+    entry_of = {}
+    for e in manifest["bullets"]:
+        entry_of[e["anchor"]] = e
+    title, sections = parse_monolith(monolith_text)
+    out, kept_anchors = [], set()
+    out.append(title if tool == "claude" else "# AGENTS.md")
+    for header, bullets in sections:
+        keep = []
+        for b in bullets:
+            matches = [a for a in entry_of if a in b]
+            if len(matches) != 1:
+                die(f"bullet has {len(matches)} manifest anchors (gate should have failed): {b[:60]!r}")
+            if kept(entry_of[matches[0]], selection):
+                keep.append(b)
+                kept_anchors.add(matches[0])
+        if keep:
+            out.extend(["", header, ""])
+            out.extend(keep)
+    text = "\n".join(out) + "\n"
+    if tool == "claude":
+        text = text.replace(f"{CLAUDE_VAR}/guides/", f"{CLAUDE_VAR}/central/guides/")
+        # Canary marker: a plain, verbatim-quotable line the activation canary
+        # asks a live session to echo back — proves the bundle entered context.
+        import hashlib
+        rev = hashlib.sha256(text.encode("utf-8")).hexdigest()[:8]
+        text += f"\nagent-bios-bundle-rev: {rev}\n"
+    else:
+        text = text.replace(CLAUDE_VAR, CODEX_VAR)
+    expected = {e["anchor"] for e in manifest["bullets"] if kept(e, selection)}
+    if kept_anchors != expected:
+        die(f"extracted set != manifest expectation ({len(kept_anchors)} vs {len(expected)}): "
+        	f"missing={sorted(expected - kept_anchors)[:3]} extra={sorted(kept_anchors - expected)[:3]}")
+    return text, len(kept_anchors)
+
+
+def filtered_files(manifest, key, selection):
+    return sorted(n for n, e in manifest.get(key, {}).items() if kept(e, selection))
+
+
+def copy_filtered(src_dir, names, dest, rewrite=None, dry=False):
+    if not dry:
+        dest.mkdir(parents=True, exist_ok=True)
+    for n in names:
+        if dry:
+            print(f"  [dry] copy {n} -> {dest}")
+            continue
+        body = (src_dir / n).read_text(encoding="utf-8")
+        if rewrite:
+            body = body.replace(*rewrite)
+        (dest / n).write_text(body, encoding="utf-8")
+
+
+def merge_settings(claude_dir, hook_names, template_path, dry=False):
+    """Path-marker merge: central-owned hook entries reference central/hooks/."""
+    marker = "/central/hooks/"
+    spath = claude_dir / "settings.json"
+    settings = json.loads(spath.read_text(encoding="utf-8")) if spath.exists() else {}
+    template = json.loads(template_path.read_text(encoding="utf-8")) if template_path.exists() else {}
+    hooks = settings.setdefault("hooks", {})
+    for event, entries in list(hooks.items()):  # drop stale central-owned
+        hooks[event] = [en for en in entries
+                        if not any(marker in h.get("command", "") for h in en.get("hooks", []))]
+    for event, entries in template.get("hooks", {}).items():  # re-add per selection
+        for en in entries:
+            cmds = [h.get("command", "") for h in en.get("hooks", [])]
+            owner = next((n for n in hook_names if any(c.endswith("/hooks/" + n) or f"/hooks/{n} " in c + " " for c in cmds)), None)
+            if owner is None:
+                continue
+            clone = json.loads(json.dumps(en))
+            for h in clone.get("hooks", []):
+                h["command"] = re.sub(r"\S*/hooks/" + re.escape(owner),
+                                      str(claude_dir / "central" / "hooks" / owner),
+                                      h["command"])
+            hooks.setdefault(event, []).append(clone)
+    if dry:
+        print(f"  [dry] merge settings.json ({len(hook_names)} central hooks)")
+        return
+    if spath.exists():
+        shutil.copy2(spath, spath.with_suffix(f".json.bak-{time.strftime('%Y%m%d-%H%M%S')}"))
+    spath.write_text(json.dumps(settings, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def seed_personal_learnings(claude_dir, dry=False):
+    """Create the automation-owned personal learnings file when seeding the entry,
+    so the entry's @personal/learnings.md import always resolves before the first
+    learn!. scripts/collect-learning.py appends to it thereafter."""
+    md = claude_dir / "personal" / "learnings.md"
+    if md.exists():
+        return
+    if dry:
+        print("  [dry] seed personal/learnings.md")
+        return
+    md.parent.mkdir(parents=True, exist_ok=True)
+    md.write_text(PERSONAL_LEARNINGS_HEADER, encoding="utf-8")
+
+
+def seed_entry(claude_dir, legacy_monolith, dry=False):
+    entry = claude_dir / "CLAUDE.md"
+    if not entry.exists():
+        if dry:
+            print("  [dry] seed entry CLAUDE.md")
+            seed_personal_learnings(claude_dir, dry)
+            return "seeded"
+        claude_dir.mkdir(parents=True, exist_ok=True)
+        entry.write_text(ENTRY_SEED, encoding="utf-8")
+        seed_personal_learnings(claude_dir, dry)
+        return "seeded"
+    body = entry.read_text(encoding="utf-8")
+    if IMPORT_LINE in body:
+        return "ok"
+    if body == legacy_monolith:  # untouched legacy deploy squatting on the path
+        if dry:
+            print("  [dry] replace legacy deployed CLAUDE.md with seed (backup)")
+            seed_personal_learnings(claude_dir, dry)
+            return "seeded"
+        shutil.copy2(entry, entry.with_suffix(f".md.bak-legacy-{time.strftime('%Y%m%d-%H%M%S')}"))
+        entry.write_text(ENTRY_SEED, encoding="utf-8")
+        seed_personal_learnings(claude_dir, dry)
+        return "seeded"
+    return "needs-action"  # user content without the import line: report, never rewrite
+
+
+def merge_codex(codex_dir, central_text, dry=False):
+    agents = codex_dir / "AGENTS.md"
+    region = f"{MARK_START}\n{central_text}{MARK_END}\n"
+    if agents.exists():
+        body = agents.read_text(encoding="utf-8")
+        if MARK_START in body and MARK_END in body:
+            pre, rest = body.split(MARK_START, 1)
+            _, post = rest.split(MARK_END, 1)
+            new = pre + region + post
+        else:  # legacy whole-file deploy: back up, adopt markers, keep nothing implicit
+            if not dry:
+                shutil.copy2(agents, agents.with_suffix(f".md.bak-legacy-{time.strftime('%Y%m%d-%H%M%S')}"))
+            new = region + "\n## Personal\n"
+    else:
+        new = region + "\n## Personal\n"
+    if dry:
+        print(f"  [dry] write AGENTS.md central region ({len(central_text)} bytes)")
+        return
+    codex_dir.mkdir(parents=True, exist_ok=True)
+    agents.write_text(new, encoding="utf-8")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--domains", help="comma-separated selection; overrides selection.json")
+    ap.add_argument("--claude-dir", default=None)
+    ap.add_argument("--codex-dir", default=None)
+    ap.add_argument("--state-dir", default=None)
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args()
+
+    import os
+    claude_dir = pathlib.Path(args.claude_dir or os.environ.get("CLAUDE_CONFIG_DIR") or pathlib.Path.home() / ".claude")
+    codex_dir = pathlib.Path(args.codex_dir or os.environ.get("CODEX_HOME") or pathlib.Path.home() / ".codex")
+    state_dir = pathlib.Path(args.state_dir or pathlib.Path.home() / ".local/share/agent-bios")
+
+    gate = subprocess.run([sys.executable, str(REPO / "scripts" / "check-domains.py")],
+                          capture_output=True, text=True)
+    if gate.returncode != 0:
+        die("domains gate FAILED — fix manifest/corpus first:\n" + gate.stdout + gate.stderr)
+
+    manifest = json.loads((REPO / "config" / "domains.json").read_text(encoding="utf-8"))
+    if args.domains is not None:
+        selection = frozenset(d for d in args.domains.split(",") if d)
+    else:
+        sel_file = state_dir / "selection.json"
+        if not sel_file.exists():
+            die(f"no --domains and no {sel_file}; run onboarding or pass --domains")
+        selection = frozenset(json.loads(sel_file.read_text(encoding="utf-8"))["domains"])
+    unknown = selection - set(manifest["domains"])
+    if unknown:
+        die(f"unknown domains: {sorted(unknown)} (known: {sorted(manifest['domains'])})")
+
+    monolith = (REPO / "claude" / "CLAUDE.md").read_text(encoding="utf-8")
+    bundle, n_bullets = build_bundle(monolith, manifest, selection, "claude")
+    codex_src = (REPO / "codex" / "AGENTS.md").read_text(encoding="utf-8")
+    codex_bundle, _ = build_bundle(monolith, manifest, selection, "codex")
+    if "multi-agent-orchestration" in selection:
+        codex_only = next((ln for ln in codex_src.splitlines() if ln.startswith(CODEX_ONLY_PREFIX)), None)
+        if codex_only:
+            codex_bundle += codex_only + "\n"
+
+    guides = filtered_files(manifest, "guides", selection)
+    hooks = filtered_files(manifest, "hooks", selection)
+    agents = filtered_files(manifest, "agents", selection)
+    dry = args.dry_run
+
+    central = claude_dir / "central"
+    if dry:
+        print(f"[dry] bundle.md: {n_bullets} bullets; guides={guides} hooks={hooks} agents={agents}")
+    else:
+        central.mkdir(parents=True, exist_ok=True)
+        (central / "bundle.md").write_text(bundle, encoding="utf-8")
+    copy_filtered(REPO / "claude" / "guides", guides, central / "guides",
+                  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)
+    entry_state = seed_entry(claude_dir, monolith, dry=dry)
+
+    merge_codex(codex_dir, codex_bundle, dry=dry)
+    copy_filtered(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry)
+
+    if not dry:
+        state_dir.mkdir(parents=True, exist_ok=True)
+        (state_dir / "selection.json").write_text(
+            json.dumps({"version": 1, "domains": sorted(selection)}, indent=2) + "\n", encoding="utf-8")
+
+    print(f"ASSEMBLED: {n_bullets} bullets, {len(guides)} guides, {len(hooks)} hooks, "
+          f"{len(agents)} agents for selection {sorted(selection)}; entry={entry_state}")
+    if entry_state == "needs-action":
+        print(f"ACTION NEEDED: {claude_dir / 'CLAUDE.md'} is user-owned and lacks '{IMPORT_LINE}' — "
+              "add the import line manually; the installer will not rewrite your file.")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/build-promotions.py

@@ -0,0 +1,183 @@
+#!/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/canary.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Activation canary: proves the central bundle actually LOADS in a live
+# 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).
+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; }
+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; }
+
+probe="Somewhere in your loaded instruction context there may be a line that starts with 'agent-bios-bundle-rev:'. Reply with ONLY that line, verbatim. If no such line is in your context, reply with exactly: BUNDLE-NOT-LOADED"
+out="$(cd "$HOME" && claude -p "$probe" 2>/dev/null)"
+
+if printf '%s' "$out" | grep -qF "$expected"; then
+  echo "CANARY PASS: central bundle is loading ($expected)"
+  exit 0
+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)"
+echo "  Likely causes: the CLAUDE.md import approval was declined (open a session and re-approve imports),"
+echo "  or the entry file lost its '@central/bundle.md' line. Diagnose with: agent-bios verify"
+exit 1

package/scripts/check-domains.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Bijection/coverage gate: config/domains.json vs the canonical corpus.
+
+The manifest is the sole classification authority (tagged-monolith layout);
+claude/CLAUDE.md stays the sole text authority. This gate closes the
+silent-drop window: a bullet reworded without a manifest update, or a
+manifest entry whose anchor no longer matches, fails HERE, before landing.
+
+Blocking checks (any violation exits 1, all violations listed):
+  1. schema shape + registry legality (tiers/domains from the manifest's own
+     registry; domains list non-empty iff tier == "domain")
+  2. bullet bijection: every manifest anchor matches exactly ONE `- ` bullet
+     in claude/CLAUDE.md, and every bullet is claimed by exactly ONE entry
+  3. file coverage: every file in claude/guides|hooks|agents claimed exactly
+     once; every claimed file exists on disk
+  4. router-guide co-package: a bullet referencing guides/<g>.md must have an
+     audience covered by that guide's audience (universal bullet -> universal
+     guide; domain bullet -> guide covering all its domains)
+  5. hook source_guide: a hook naming its source guide must carry the same
+     tier + domain set as that guide
+  6. non-vacuity: every subject set this gate judges is non-empty, so a green
+     run cannot be vacuous
+
+Informational (non-blocking until budgets are set in the manifest): estimated
+token size per package.
+
+--self-test: runs negative controls (mutated manifests that MUST fail) and
+exits 0 only if every mutation is caught. Proves the gate can fail.
+"""
+import json
+import pathlib
+import re
+import sys
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+MANIFEST = REPO / "config" / "domains.json"
+MONOLITH = REPO / "claude" / "CLAUDE.md"
+FILE_SECTIONS = {  # manifest key -> corpus dir, glob
+    "guides": ("claude/guides", "*.md"),
+    "hooks": ("claude/hooks", "*"),
+    "agents": ("claude/agents", "*.md"),
+}
+
+
+def load_manifest(path=MANIFEST):
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def corpus_bullets(path=MONOLITH):
+    text = path.read_text(encoding="utf-8")
+    return [ln for ln in text.splitlines() if ln.startswith("- ")]
+
+
+def audience(entry, errors, ctx):
+    """Universal set marker, or the frozen domain set; records legality errors."""
+    tier = entry.get("tier")
+    domains = entry.get("domains", [])
+    if tier in ("core", "infra"):
+        if domains:
+            errors.append(f"{ctx}: tier {tier} must not list domains, got {domains}")
+        return "UNIVERSAL"
+    if tier == "env-personal":
+        if domains:
+            errors.append(f"{ctx}: env-personal must not list domains")
+        return "NEVER"
+    if tier == "domain":
+        if not domains:
+            errors.append(f"{ctx}: tier domain requires >=1 domain")
+        return frozenset(domains)
+    errors.append(f"{ctx}: illegal tier {tier!r}")
+    return "NEVER"
+
+
+def covers(guide_aud, bullet_aud):
+    if guide_aud == "UNIVERSAL":
+        return True
+    if bullet_aud in ("UNIVERSAL", "NEVER"):
+        return False  # universal bullet needs universal guide; NEVER refs nothing
+    return isinstance(guide_aud, frozenset) and guide_aud >= bullet_aud
+
+
+def run_gate(manifest, bullets, repo=REPO):
+    errors = []
+    tiers = set(manifest.get("tiers", []))
+    domains_reg = set(manifest.get("domains", {}))
+    if not tiers or not domains_reg:
+        errors.append("registry: tiers/domains registry empty")
+
+    def check_registry(entry, ctx):
+        if entry.get("tier") not in tiers:
+            errors.append(f"{ctx}: tier {entry.get('tier')!r} not in registry")
+        for d in entry.get("domains", []):
+            if d not in domains_reg:
+                errors.append(f"{ctx}: domain {d!r} not in registry")
+
+    # -- 2. bullet bijection ------------------------------------------------
+    mb = manifest.get("bullets", [])
+    if not bullets:
+        errors.append("non-vacuity: no bullets found in monolith")
+    if not mb:
+        errors.append("non-vacuity: manifest has no bullet entries")
+    if len(mb) != len(bullets):
+        errors.append(f"bijection: manifest has {len(mb)} bullet entries, monolith has {len(bullets)} bullets")
+    claimed = [0] * len(bullets)
+    seen_anchors = set()
+    for i, entry in enumerate(mb):
+        ctx = f"bullets[{i}] anchor={entry.get('anchor', '')!r:.60}"
+        check_registry(entry, ctx)
+        anchor = entry.get("anchor", "")
+        if not anchor:
+            errors.append(f"{ctx}: empty anchor")
+            continue
+        if anchor in seen_anchors:
+            errors.append(f"{ctx}: duplicate anchor")
+        seen_anchors.add(anchor)
+        hits = [j for j, b in enumerate(bullets) if anchor in b]
+        if len(hits) != 1:
+            errors.append(f"{ctx}: anchor matches {len(hits)} bullets (need exactly 1)")
+        for j in hits:
+            claimed[j] += 1
+    for j, n in enumerate(claimed):
+        if n != 1:
+            errors.append(f"bijection: bullet line {bullets[j][:70]!r} claimed {n} times (need exactly 1)")
+
+    # -- 3. file coverage ---------------------------------------------------
+    entries = {}
+    for key, (rel, glob) in FILE_SECTIONS.items():
+        section = manifest.get(key, {})
+        entries[key] = section
+        if not section:
+            errors.append(f"non-vacuity: manifest section {key!r} empty")
+        on_disk = {p.name for p in (repo / rel).glob(glob) if p.is_file()}
+        if not on_disk:
+            errors.append(f"non-vacuity: no files on disk under {rel}")
+        for name, entry in section.items():
+            check_registry(entry, f"{key}/{name}")
+            if name not in on_disk:
+                errors.append(f"{key}: claimed file {name} does not exist in {rel}")
+        for name in sorted(on_disk - set(section)):
+            errors.append(f"{key}: file {name} in {rel} not claimed by the manifest")
+
+    # -- 4. router-guide co-package ----------------------------------------
+    guide_aud = {n: audience(e, errors, f"guides/{n}") for n, e in entries["guides"].items()}
+    anchor_of = {id(e): e.get("anchor", "?") for e in mb}
+    ref_checks = 0
+    for entry in mb:
+        hits = [b for b in bullets if entry.get("anchor", "\0") in b]
+        if len(hits) != 1:
+            continue  # already reported by bijection
+        b_aud = audience(entry, errors, f"bullet {entry.get('anchor', '')!r:.40}")
+        for g in re.findall(r"guides/([a-z0-9-]+\.md)", hits[0]):
+            ref_checks += 1
+            if g not in guide_aud:
+                errors.append(f"router: bullet {entry['anchor']!r:.40} references unclaimed guide {g}")
+            elif not covers(guide_aud[g], b_aud):
+                errors.append(
+                    f"router: bullet {entry['anchor']!r:.40} (audience {b_aud}) references guide {g} "
+                    f"(audience {guide_aud[g]}) — user can hold the router without the guide"
+                )
+    if ref_checks == 0:
+        errors.append("non-vacuity: no router->guide references were checked")
+
+    # -- 5. hook source_guide -----------------------------------------------
+    for name, entry in entries["hooks"].items():
+        src = entry.get("source_guide")
+        if src:
+            g = entries["guides"].get(src)
+            if g is None:
+                errors.append(f"hooks/{name}: source_guide {src} not in manifest guides")
+            elif (entry.get("tier"), sorted(entry.get("domains", []))) != (g.get("tier"), sorted(g.get("domains", []))):
+                errors.append(f"hooks/{name}: tier/domains differ from source guide {src}")
+
+    # -- informational token report ------------------------------------------
+    sizes = {}
+    for entry in mb:
+        key = entry.get("tier") if entry.get("tier") != "domain" else ",".join(entry.get("domains", ["?"])[:1])
+        hit = next((b for b in bullets if entry.get("anchor", "\0") in b), "")
+        sizes[key] = sizes.get(key, 0) + len(hit) // 4
+    for name, entry in entries["guides"].items():
+        key = entry.get("tier") if entry.get("tier") != "domain" else ",".join(entry.get("domains", ["?"])[:1])
+        p = repo / FILE_SECTIONS["guides"][0] / name
+        if p.is_file():
+            sizes[key] = sizes.get(key, 0) + len(p.read_text(encoding="utf-8")) // 4
+    return errors, sizes
+
+
+def self_test(manifest, bullets):
+    """Negative controls: each mutation MUST make the gate fail."""
+    import copy
+
+    muts = []
+    m1 = copy.deepcopy(manifest)
+    m1["bullets"] = m1["bullets"][1:]
+    muts.append(("dropped bullet entry", m1, bullets))
+    m2 = copy.deepcopy(manifest)
+    m2["bullets"][0]["anchor"] = "zz-no-such-phrase-zz"
+    muts.append(("anchor matches nothing (reword drift)", m2, bullets))
+    m3 = copy.deepcopy(manifest)
+    m3["bullets"][1]["anchor"] = m3["bullets"][0]["anchor"]
+    muts.append(("duplicate anchor claim", m3, bullets))
+    m4 = copy.deepcopy(manifest)
+    first_guide = next(iter(m4["guides"]))
+    del m4["guides"][first_guide]
+    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))
+
+    failed = []
+    for name, mm, bb in muts:
+        errs, _ = run_gate(mm, bb)
+        if not errs:
+            failed.append(name)
+        print(f"self-test [{'CAUGHT' if errs else 'MISSED'}] {name}")
+    return failed
+
+
+def main():
+    manifest = load_manifest()
+    bullets = corpus_bullets()
+    if "--self-test" in sys.argv:
+        missed = self_test(manifest, bullets)
+        if missed:
+            print(f"SELF-TEST FAIL: gate missed: {missed}")
+            return 1
+        print("SELF-TEST OK: every negative control was caught")
+        return 0
+    errors, sizes = run_gate(manifest, bullets)
+    for e in errors:
+        print(f"FAIL: {e}")
+    print("-- package token estimate (informational) --")
+    for k in sorted(sizes):
+        print(f"  {k}: ~{sizes[k]} tokens")
+    if errors:
+        print(f"DOMAINS GATE FAIL: {len(errors)} violation(s)")
+        return 1
+    print(f"DOMAINS GATE OK: {len(bullets)} bullets bijective, all files claimed, routers co-packaged")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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