agent-bios 0.9.8 → 0.10.0

package/{config → compose}/domains.json

@@ -48,51 +48,19 @@
     {"anchor": "Treat a produced field, flag, signal", "tier": "domain", "domains": ["llm-pipeline-dev"]},
     {"anchor": "Hard-block only deterministically decidable structural", "tier": "domain", "domains": ["llm-pipeline-dev"]},
     {"anchor": "Runtime/code may enforce the contract", "tier": "domain", "domains": ["llm-pipeline-dev"]},
-    {"anchor": "Keep the concept graph compact by reusing", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Treat lasting or shared names as concept", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Before adding or changing a concept", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Prefer broad, stable concepts with precise", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "When adding, changing, renaming, splitting, or exposing anything lasting or shared", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Before fixing a review finding or test failure", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Split or promote a concept when it changes", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Keep derived values as properties or projections", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Keep internal projections and helper outputs internal", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Distinguish authority from visibility", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Reuse existing enum values, failure kinds", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Use fallback paths, compatibility shims", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Keep comments and active docs aligned", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "When a split is necessary, name the parent", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "In ontology work, check existing entities", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "In code work, follow existing naming patterns", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Let the repository's shape mirror its concept graph", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "For `.xlsx` editing, generation, reconciliation", "tier": "domain", "domains": ["office-work"]},
-    {"anchor": "For meaningful development work, read and use", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For development work, read and use", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "For mock, fixture, fake, stub, simulated-provider", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "When the user asks to", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Think before coding: state key assumptions", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Build the smallest viable functional path", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Treat viability as real behavior against", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Make surgical changes. Touch only what", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Clean up issues introduced by the current", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Own the full lifecycle of what you create", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Define success criteria before multi-step coding work", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "For bugs, prefer a reproducing test", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Every changed line should trace back", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Fix the root cause at its authority", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Land risky or behavior-changing work behind", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "For composing a review request, packet", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "After every meaningful code, ontology, config", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Use static checks broadly: typecheck, lint", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Add the narrowest reliable runtime or semantic test", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Pick each domain's verification mix", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Let the LLM derive scenarios from the diff", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Keep E2E stable with deterministic data", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For choosing verification depth, the per-domain mix, the case space, what makes a completion criterion falsifiable", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Report the checks run, results", "tier": "core", "domains": []},
     {"anchor": "Trust a green check only when it traversed", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Make completion criteria falsifiable", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Before comparing two of anything", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "For non-trivial designs or high-risk changes", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Proportion verification to cost, risk, and information gain", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Trust a green / zero-findings verdict only", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "For concrete shell/CLI traps", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Ambient state — the active shell", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Before relying on any model id", "tier": "domain", "domains": ["builder-base"]},
@@ -100,21 +68,17 @@
     {"anchor": "Never accept secrets through transcript- or history-logged channels", "tier": "core", "domains": []},
     {"anchor": "When a secret must be supplied", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Treat a coarse runtime signal", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Before reasoning about what a branch contains", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "Standing spawn policy: check the spawn gates", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "Down-spawns carry a machine-checkable done-when", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "For work spanning multiple models or CLI agents", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "For composing a prompt, packet, or tool description", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "Allocate models by difficulty", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "Judge a review by how much independence", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "dual-provider frontier design drafts", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "Never retry-storm a live rate limit", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "On any resumed, cleared, or relocated session", "tier": "domain", "domains": ["multi-agent-orchestration"]},
     {"anchor": "Keep runtime code, active docs, and execution-facing", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Use comments for non-obvious current behavior", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Put backward-compatibility notes, deprecated behavior", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Link from active docs or code to isolated notes", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Phrase guidelines as desired behavior", "tier": "domain", "domains": ["builder-base"]},
-    {"anchor": "Prefer established docs such as", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For where a comment, a compatibility note, deprecated behavior, a rejected alternative", "tier": "domain", "domains": ["builder-base"]},
     {"anchor": "For SVG diagrams, service blueprints", "tier": "domain", "domains": ["visualization-docs"]},
     {"anchor": "When a concept is easier to understand visually", "tier": "domain", "domains": ["visualization-docs"]},
     {"anchor": "Use HTML for comparisons, flows, state changes", "tier": "domain", "domains": ["visualization-docs"]},
@@ -125,10 +89,12 @@
     {"anchor": "`learn!` — session learning", "tier": "core", "domains": []}
   ],
   "guides": {
-    "claude-prompting.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
-    "cli-multi-model-workflow.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "claude-prompting.md": {"tier": "domain", "domains": ["multi-agent-orchestration"], "handles": ["per-family prompting guide", "계열별 prompting guide"]},
+    "cli-multi-model-workflow.md": {"tier": "domain", "domains": ["multi-agent-orchestration"], "handles": ["multi-model guide", "multi-model 가이드"]},
     "coding-staged-workflow.md": {"tier": "domain", "domains": ["builder-base"]},
-    "gpt-prompting.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "concept-economy.md": {"tier": "domain", "domains": ["builder-base"]},
+    "documentation-hygiene.md": {"tier": "domain", "domains": ["builder-base"]},
+    "gpt-prompting.md": {"tier": "domain", "domains": ["multi-agent-orchestration"], "handles": ["prompting guides for gpt-family"]},
     "implementation-map.md": {"tier": "domain", "domains": ["visualization-docs"]},
     "llm-capability-boundary-examples.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
     "llm-capability-boundary-patterns.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
@@ -138,6 +104,7 @@
     "session-distill-workflow.md": {"tier": "infra", "domains": []},
     "learning-flow.md": {"tier": "infra", "domains": []},
     "svg-visualization-guide.md": {"tier": "domain", "domains": ["visualization-docs"]},
+    "verification-discipline.md": {"tier": "domain", "domains": ["builder-base"]},
     "tooling-gotchas.md": {"tier": "domain", "domains": ["builder-base"]}
   },
   "hooks": {

package/{scripts → compose}/pkgid.py

@@ -39,7 +39,14 @@ def resolve(obj, key="package_id"):
 
 
 def segments(pid):
-    """('scope', 'name') for deriving deploy paths. Only call on a valid id."""
+    """('scope', 'name') for deriving deploy paths. Only call on a valid id.
+
+    No caller yet, and that is recorded rather than left to be rediscovered: deploy-path
+    derivation belongs to the multi-package composer, which
+    design/adapter-split/ECOSYSTEM-ARCHITECTURE.md defers "to the first real second package".
+    Kept because the id grammar it splits is settled and rewriting it later would re-derive the
+    same two lines; delete it if that deferral is ever abandoned rather than landed.
+    """
     if not is_valid(pid):
         raise ValueError(f"not a package id: {pid!r}")
     return tuple(pid[1:].split("/", 1))

package/compose/prune-backups.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Retention for the copies this repo makes before it overwrites or removes something.
+
+A backup exists so a mistake is recoverable, so pruning is the one operation here that can
+destroy the thing the feature is for. That decides the rule: a copy is deleted only when it is
+BOTH older than the age window AND outside the most recent N. Either condition alone would be
+enough to delete something someone still wants — a busy week would age out yesterday's work, and
+a quiet quarter would trim a set small enough to keep whole.
+
+Worked through, that single condition gives the intended behaviour:
+
+  20 copies made inside one month   -> none are old enough; keep all 20
+  8 copies spread over two months   -> none are outside the newest 10; keep all 8
+  11 copies, 7 of them this month   -> the oldest is both aged and outside the 10; keep 10
+
+Two groups are pruned, because this repo writes backups in two shapes: timestamped directories
+under the state dir, and sibling backup files next to the file they copy (assemble, learn and
+migrate write those). They are pruned independently — ten of each — since losing one group's
+history to the other group's churn is not what either was kept for.
+
+This module also answers WHICH loose files are ours (`OWNED_SIBLING`, `owned_siblings`), for
+itself and for uninstall. Both delete, so the rule lives in one place.
+
+  --claude-dir/--codex-dir/--state-dir   where to look
+  --dry-run     print what would go, delete nothing
+  --list-owned  print the owned loose backups, NUL-separated (uninstall reads this)
+  --self-test   the retention rule and the ownership rule, both directions
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import pathlib
+import re
+import shutil
+import sys
+import time
+
+KEEP_RECENT = 10
+MAX_AGE_DAYS = 30
+
+# What counts as OUR loose backup — and the only place that question is answered.
+# `install.sh` asks this module rather than restating the pattern, because both sides
+# delete, and a rule stated twice is a rule that drifts on one side.
+#
+# The shapes below are exactly what this repo writes: compose/assemble.py (a plain
+# timestamp for settings.json, `legacy` for a migrated entry file), learn/collect-learning.py,
+# learn/migrate-learnings.py, and install.sh's codex-config removal. A bare `.bak-`
+# substring — what this used to match — also claims `notes.bak-old`, which is the user's.
+# These live in directories we SHARE with the user and with other tools, so ownership has
+# to be carried by the name; the directory cannot confer it.
+# The bare `.bak-<timestamp>` form carries no marker of its own, so it is pinned to the ONE
+# basename that receives it — `settings.json`, from merge_settings. Left generic it also claimed
+# a `notes.bak-20260101-000000` the user wrote, which is a correctly shaped timestamp on a file
+# that is not ours; matching the timestamp SHAPE is not the same as matching our ownership.
+_TS = r"\d{8}-\d{6}"
+OWNED_SIBLING = re.compile(
+    rf"^(?:settings\.json\.bak-{_TS}"
+    rf"|.+\.bak-(?:legacy|learn|migrate)-{_TS}"
+    rf"|.+\.bak-agent-bios-uninstall)$")
+
+
+def owned_siblings(root):
+    """Every loose backup under `root` that this repo wrote. Nothing else is ours."""
+    if not root.is_dir():
+        return []
+    return [f for f in root.rglob("*") if f.is_file() and OWNED_SIBLING.search(f.name)]
+
+
+def to_delete(entries, now, keep_recent=KEEP_RECENT, max_age_days=MAX_AGE_DAYS):
+    """(path, mtime) pairs -> the ones both aged out AND outside the newest `keep_recent`.
+
+    Both conditions, never either: this is the whole retention policy, and it is a pure function
+    so the policy can be tested without creating and destroying real backups.
+    """
+    newest_first = sorted(entries, key=lambda e: e[1], reverse=True)
+    cutoff = now - max_age_days * 86400
+    return [path for i, (path, mtime) in enumerate(newest_first)
+            if i >= keep_recent and mtime < cutoff]
+
+
+def _entries(paths):
+    out = []
+    for p in paths:
+        try:
+            out.append((p, p.stat().st_mtime))
+        except OSError:
+            continue  # vanished under us; nothing to prune
+    return out
+
+
+def prune(state_dir, homes, now=None, dry=False):
+    """Prune both groups. Returns the paths removed (or that would be)."""
+    now = time.time() if now is None else now
+    removed = []
+
+    backups = state_dir / "backups"
+    if backups.is_dir():
+        for path in to_delete(_entries([d for d in backups.iterdir() if d.is_dir()]), now):
+            removed.append(path)
+            if not dry:
+                shutil.rmtree(path, ignore_errors=True)
+
+    for home in homes:
+        for path in to_delete(_entries(owned_siblings(home)), now):
+            removed.append(path)
+            if not dry:
+                path.unlink(missing_ok=True)
+    return removed
+
+
+def self_test():
+    day = 86400
+    now = 1_000_000_000.0
+    cases = [
+        ("20 within a month -> keep all",
+         [(f"b{i}", now - i * day) for i in range(20)], 0),
+        ("8 over two months -> keep all",
+         [(f"b{i}", now - i * 8 * day) for i in range(8)], 0),
+        ("11 with 7 recent -> drop the oldest one",
+         [(f"b{i}", now - i * day) for i in range(7)]
+         + [(f"o{i}", now - (40 + i * 5) * day) for i in range(4)], 1),
+        ("11 all recent -> drop none",
+         [(f"b{i}", now - i * day) for i in range(11)], 0),
+        ("30 all aged -> keep the newest ten",
+         [(f"b{i}", now - (40 + i) * day) for i in range(30)], 20),
+    ]
+    bad = 0
+    for label, entries, want in cases:
+        got = len(to_delete(entries, now))
+        ok = got == want
+        bad += not ok
+        print(f"  {'ok  ' if ok else 'FAIL'} {label} (deleted {got}, want {want})")
+    # A rule that deletes nothing whatever the input would pass every case above by accident.
+    proof = to_delete([(f"x{i}", now - (100 + i) * day) for i in range(50)], now)
+    if len(proof) != 40:
+        print("  FAIL contrast control: the rule never deletes anything")
+        bad += 1
+    else:
+        print("  ok   contrast control: it does delete when both conditions hold")
+
+    # Ownership, in both directions. The first list is every shape this repo writes; the
+    # second is what a person or another tool leaves in the same directories. Matching the
+    # first proves the rule still finds our copies after a rename; refusing the second is
+    # the half that matters, because uninstall DELETES whatever this claims.
+    ours = ["settings.json.bak-20260101-000000", "CLAUDE.md.bak-legacy-20260101-000000",
+            "learnings.md.bak-learn-20260101-000000", "learnings.md.bak-migrate-20260101-000000",
+            "config.toml.bak-agent-bios-uninstall"]
+    theirs = ["notes.bak-old", "db.bak-2026", "x.bak-", "report.bak-final.txt",
+              "settings.json.bak-2026010-000000", "a.bak-legacy-nope",
+              # A correctly shaped timestamp on a basename that is not ours. The first pass
+              # only rejected MALFORMED timestamps, which tested the shape and not the
+              # ownership — so the rule went on claiming these and the control stayed green.
+              "notes.bak-20260101-000000", "db.bak-20240301-120000",
+              "settings.json.txt.bak-20260101-000000"]
+    missed = [n for n in ours if not OWNED_SIBLING.search(n)]
+    grabbed = [n for n in theirs if OWNED_SIBLING.search(n)]
+    for name in missed:
+        print(f"  FAIL ownership: {name} is ours but went unclaimed")
+    for name in grabbed:
+        print(f"  FAIL ownership: {name} is NOT ours but was claimed for deletion")
+    bad += len(missed) + len(grabbed)
+    if not missed and not grabbed:
+        print(f"  ok   ownership: claims {len(ours)} shapes we write, "
+              f"refuses {len(theirs)} we do not")
+    print(f"prune-backups self-test: {'OK' if not bad else 'FAIL'} ({len(cases) + 2} checks)")
+    return 1 if bad else 0
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--state-dir")
+    ap.add_argument("--claude-dir")
+    ap.add_argument("--codex-dir")
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--self-test", action="store_true")
+    ap.add_argument("--list-owned", action="store_true",
+                    help="print every owned loose backup under the config dirs, NUL-separated, "
+                         "then exit. uninstall consumes this instead of restating the rule.")
+    args = ap.parse_args()
+    if args.self_test:
+        sys.exit(self_test())
+
+    state = pathlib.Path(args.state_dir or pathlib.Path.home() / ".local/share/agent-bios")
+    homes = [pathlib.Path(d) for d in (
+        args.claude_dir or os.environ.get("CLAUDE_CONFIG_DIR") or pathlib.Path.home() / ".claude",
+        args.codex_dir or os.environ.get("CODEX_HOME") or pathlib.Path.home() / ".codex")]
+    if args.list_owned:
+        # NUL-separated: these are real paths from a user's home, and a newline in one would
+        # otherwise split a single file into two entries — one of which the caller then deletes.
+        for home in homes:
+            for path in owned_siblings(home):
+                sys.stdout.write(f"{path}\0")
+        return
+    removed = prune(state, homes, dry=args.dry_run)
+    for path in removed:
+        print(f"  {'[dry] ' if args.dry_run else ''}pruned backup  {path}")
+    if removed and not args.dry_run:
+        print(f"  pruned {len(removed)} backup(s) past retention "
+              f"(kept: newest {KEEP_RECENT}, plus anything under {MAX_AGE_DAYS} days)")
+
+
+if __name__ == "__main__":
+    main()

package/{scripts → compose}/register-hooks.py

@@ -18,8 +18,8 @@ import sys
 
 
 def load_assemble(repo):
-    """Import assemble.py by path — scripts/ is a flat toolbox, not a package."""
-    spec = importlib.util.spec_from_file_location("assemble", repo / "scripts" / "assemble.py")
+    """Import assemble.py by path — compose/ is a flat toolbox, not a package."""
+    spec = importlib.util.spec_from_file_location("assemble", repo / "compose" / "assemble.py")
     mod = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(mod)
     return mod
@@ -29,7 +29,7 @@ def main():
     if len(sys.argv) != 3:
         sys.exit("usage: register-hooks.py <repo> <claude-dir>")
     repo, claude_dir = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])
-    manifest = json.loads((repo / "config" / "domains.json").read_text(encoding="utf-8"))
+    manifest = json.loads((repo / "compose" / "domains.json").read_text(encoding="utf-8"))
     names = sorted(manifest.get("hooks", {}))
     if not names:
         sys.exit("register-hooks: manifest declares no hooks — refusing to rewrite settings")