agent-bios 0.9.6 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bios",
-  "version": "0.9.6",
+  "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/",
@@ -26,8 +26,6 @@
     "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

@@ -90,6 +90,8 @@ 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
@@ -196,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
@@ -219,8 +248,19 @@ def self_test(manifest, bullets):
     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/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,210 +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
-
-sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
-import pkgid  # noqa: E402  (sibling module; scripts/ is a flat toolbox)
-
-REPO = pathlib.Path(__file__).resolve().parent.parent
-LEDGER = REPO / "design" / "session-distill" / "ledger.json"
-DOMAINS = REPO / "config" / "domains.json"
-MANIFEST = REPO / "config" / "promotions.json"
-FIXTURE = REPO / "design" / "collection-loop" / "fixtures" / "ledger-promote-sample.json"
-MANIFEST_VERSION = 2
-
-
-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
-        pid = pkgid.resolve(e, "placed_package_id")
-        if not pkgid.is_valid(pid):
-            raise ManifestError(
-                f"placed_package_id {pid!r} (learning {lid}) is not @scope/name")
-        # `anchor` ships alongside the derived audience because the consumer
-        # (migrate-learnings) must verify the bullet is REALLY in the user's
-        # deployed corpus before deleting their personal copy. Audience metadata
-        # alone cannot answer that — it is a build-time projection that drifts.
-        promotions.append({"learning_id": lid.lower(), "package_id": pid,
-                           "anchor": anchor, "tier": tier, "domains": domains})
-    promotions.sort(key=lambda p: p["learning_id"])
-    return {"version": MANIFEST_VERSION, "promotions": promotions}
-
-
-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"))))
-
-    # v2 identity + locator. Without these the manifest looks fine while the
-    # consumer that must verify placement has nothing to verify against.
-    checks.append(("manifest is v2", m["version"] == 2))
-    checks.append(("every promotion carries its anchor",
-                   all(p.get("anchor") for p in m["promotions"])))
-    checks.append(("absent placed_package_id resolves to core",
-                   all(p.get("package_id") == pkgid.CORE for p in m["promotions"])))
-    led2 = json.loads(FIXTURE.read_text(encoding="utf-8"))
-    led2["entries"][0]["placed_package_id"] = "@acme/security"
-    checks.append(("declared placed_package_id is carried through",
-                   any(p["package_id"] == "@acme/security"
-                       for p in build_manifest(led2, domains)["promotions"])))
-    checks.append(("malformed placed_package_id fails",
-                   raises(lambda l: l["entries"][0].__setitem__("placed_package_id", "Acme/Sec"))))
-
-    failed = [n for n, ok in checks if not ok]
-    if failed:
-        for n in failed:
-            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()