agent-bios 0.9.4 → 0.9.6

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/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,13 +1,14 @@
 {
   "name": "agent-bios",
-  "version": "0.9.4",
-  "releaseDate": "2026-07-25",
+  "version": "0.9.6",
+  "releaseDate": "2026-07-26",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
     "agent-bios": "scripts/install.sh"
   },
   "files": [
     "claude/CLAUDE.md",
+    "claude/settings.json",
     "claude/guides/",
     "claude/hooks/",
     "claude/agents/",
@@ -21,6 +22,12 @@
     "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

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