agent-bios 0.9.8 → 0.9.9

package/codex/guides/coding-staged-workflow.md

@@ -60,6 +60,38 @@ Per-domain menus for the global Verification Discipline loop; pick the narrowest
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
 - Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
 
+### Deriving the case space
+
+A check has two authored halves, and they rot differently. The **verdict** — what the
+answer should be — rots by encoding a belief that was wrong from the start. The
+**space** — which cases exist — rots by staying still while the thing it covers grows.
+Recording the verdict is common practice; deriving the space is the half usually left
+hand-written, and a suite can have every expectation derived and still cover a set
+someone typed once.
+
+- Record the verdict, do not type it. Run the real path and store what came back;
+  drift then shows as a diff instead of as a belief someone has to re-justify.
+- Enumerate the space from the artifact that defines it — the config's entries, the
+  schema's fields, the router's routes, the installer's call sites. Adding one there
+  should widen coverage with no edit here.
+- Derive the exemption rule too. If some cases legitimately have no answer, decide that
+  from a property the artifact carries, never from a list of names: the list is the
+  authored space coming back through a side door, and it absorbs the regression where
+  a case that should have an answer stops having one.
+- Dedupe on the tuple that actually determines the outcome, and report how many
+  collapsed. A coverage count that hides its own truncation reads as more than it is.
+- Split by cost, not by space. When the real path needs money, credentials, or a
+  network, run a cheap stand-in on every commit and the real one on demand — both from
+  the **same enumeration**, so the two can never disagree about which cases exist.
+- Derivation moves authorship rather than removing it: the extractor and the invariants
+  are still written by hand. Give them a negative control, or the derived suite is just
+  a larger unfalsifiable one.
+- Planting a violation to prove a control fires is a write into the working tree, and
+  the restore is not atomic with it: if the probe can time out, abort, or be
+  interrupted, a restore sitting after it never runs and the plant survives into a
+  commit. Plant in a copy where the shape allows it, and when it must be in place, snapshot
+  first and restore from the snapshot as its own step rather than trusting the probe to finish.
+
 ## Stop Conditions
 
 - If the issue boundary expands compared with the previous review, stop and ask the user to choose redesign/rework or continuing the current iteration.

package/codex/guides/gpt-prompting.md

@@ -114,5 +114,5 @@ Derived from the vendor's published prompting guidance for the `targets` models
 above. When a `targets` model changes, re-derive this guide from current vendor
 guidance rather than editing around the old rules — prompting guidance is
 version-bound, and the previous generation's advice inverted on this one.
-`scripts/check-prompting-targets.sh` fails when the launch config binds a model
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list.

package/codex/guides/learning-flow.md

@@ -18,9 +18,9 @@ The **light**, per-user, single-session capture flow: turn a lesson from the
 current session into a **learning** (prose + a JSON record) that (a) applies to
 the user's own next session and (b) reaches the org for curation. This is the
 counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
-many sessions and is curator/power-user only. Terms follow the agent-bios
-`LEXICON.md`; the full routing framework is
-`design/session-distill/PLACEMENT-FRAMEWORK.md` (agent-bios repo).
+many sessions and is curator/power-user only. Terminology and the full routing
+framework are maintained in the agent-bios repo; the criteria this flow applies
+are stated below.
 
 Defer to the preset mission: if this session runs the **Session distill** preset
 (trigger `distill!`), that mission owns capture — do not also run this flow.
@@ -62,7 +62,7 @@ still-valid candidates are surfaced for the user's approval.
 
 ## Domain tagging (the curation join key)
 
-Suggest a `domain` from the registered vocabulary in `config/domains.json`
+Suggest a `domain` from the registered vocabulary in `compose/domains.json`
 (domain keys for domain-specific lessons, or a tier name like `core`/`infra`
 for a genuinely cross-cutting lesson); the user **confirms**. If unsure, use
 `unclassified` (never blocks capture — the curator assigns later). If no
@@ -86,7 +86,7 @@ match your host):
       | 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
+validates against `learn/learning.schema.json`, logs the JSON record, and writes
 the lesson prose where THIS host loads it next session:
 - **Claude**: appended to the automation-owned personal learnings file, pulled in
   by the entry file's `@personal/learnings.md` import.

package/codex/guides/llm-capability-boundary.md

@@ -204,7 +204,12 @@ Use it per field or operation, not as a blanket replacement for LLM judgment.
 Use this procedure when designing a new LLM-assisted artifact or revising an
 existing one.
 
-1. Identify the canonical artifact and downstream consumers.
+1. Identify the canonical artifact and downstream consumers. When the consumer already
+   exists, read its **acceptance predicate**, not only its schema: the schema says which
+   fields may appear, and the predicate says which combinations are credited. A producer
+   designed against the schema alone can emit records that are valid and never
+   accepted — one record per event where the consumer judges one record per subject is
+   the common shape of this, and it survives every field-level check.
 2. Split fields into semantic fields, deterministic fields, provenance fields,
    and side-effect operations.
 3. Assign each field or operation one primary authority.

package/codex/guides/session-distill-workflow.md

@@ -2,13 +2,14 @@
 guide_id: session-distill-workflow
 language: en
 status: active
+audience: author
 use_when:
   - a session was launched with the Session distill preset (mission-injected)
   - the launcher nudge says enough sessions accumulated for a mining window
   - mining local Claude/Codex sessions for learnings absent from the corpus
   - promoting, incubating, or retiring items in the session-distill ledger
 core_rules:
-  - the ledger and HANDOFF are the SSOT; read them before touching the pipeline
+  - the ledger is the SSOT for state; read it before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
   - every promotion passes an explicit user-approval gate
   - global growth per round is hard-capped (~500 tokens) by a measured gate
@@ -17,19 +18,28 @@ core_rules:
 
 # Session-Distill Workflow
 
+**Requires an agent-bios checkout.** This runbook edits the corpus itself, so it
+names repo paths and runs repo scripts. On a packaged install those do not exist:
+say so and stop rather than following steps you cannot execute.
+
 Runbook for a session-distill run: mine recent main-context sessions,
 verify candidates, place them through the framework, and apply with the user.
 Everything durable lives in the agent-bios repo.
 
 ## Read first (SSOT)
 
-1. `design/session-distill/HANDOFF.md` — initiative state, prior decisions,
-   open threads. 2. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the
-   placement authority (typology A–G, layers, admission bars, lifecycle).
-3. `design/session-distill/ledger.json` — cumulative item states
-   (placed / incubating / absorbed / retired) with provenance.
+1. `design/session-distill/ledger.json` — the initiative's state. Every item
+   carries its status (placed / incubating / incubating-G / absorbed /
+   adopted-no-text), strength, and provenance, so what is open, what was
+   promoted, and what is still incubating are all queries against this file.
+   Read state here and nowhere else: a count or a status written into prose is
+   correct on the day it is written and silently wrong afterwards.
+2. `design/session-distill/versions.json` — which closed mining window maps to
+   which commit, and therefore what a rollback restores.
+3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement authority
+   (typology A–G, layers, admission bars, lifecycle).
 
-## Stage 1 — Mine (pipeline in `scripts/session-distill/`)
+## Stage 1 — Mine (pipeline in `session-distill/`)
 
 Run in order; each stage reads the previous stage's `out/`:
 
@@ -73,7 +83,7 @@ Run in order; each stage reads the previous stage's `out/`:
   stdout/stderr channel contracts) → codex/ + ko/ mirrors.
 - Verify per layer, not just by diff: enforcement/gate fixture tests
   (non-vacuous — known-bad must fire), hook trigger positive/negative sets,
-  `scripts/check-parity.sh` exit 0 unpiped, prompting-target gate, then
+  `gates/check-parity.sh` exit 0 unpiped, prompting-target gate, then
   `agent-bios install` to activate and re-verify.
 
 ## Stage 4 — G-pass (principles, not directives)
@@ -95,6 +105,6 @@ Run in order; each stage reads the previous stage's `out/`:
 3. Register the corpus version: append {version = window end, commit = the
    corpus-close commit} to `design/session-distill/versions.json` — this is
    what the launcher's Versions & rollback screen offers — then run
-   `python3 scripts/session-distill/update-state.py --window-end <date>`
+   `python3 session-distill/update-state.py --window-end <date>`
    (nudge baseline) and `corpus-state.py project` (launcher status panel).
 4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).

package/codex/guides/tooling-gotchas.md

@@ -62,6 +62,15 @@ depends on it, pin it explicitly instead of trusting the environment.
   early-exit consumers (`cmd | head -1` → SIGPIPE 141), so it is a per-command
   choice, not a global default. Does not apply when the final stage IS the
   assertion (`cmd | grep -q pattern`).
+- **Passthrough arguments in a CLI you author**: an option meant to carry
+  another command's own flags cannot use a greedy-but-dash-stopping arity —
+  Python's `nargs="+"` ends at the first token starting with `-`, so the
+  wrapped command's `--model x` lands on the next positional and the error
+  names a parameter the caller never mentioned. Use the parser's
+  everything-after form (`argparse.REMAINDER`). A bare `--` separator is a
+  second, separate trap: argparse consumes it as its own positional marker
+  before the remainder sees it, so the form every caller reaches for first is
+  the one that breaks — normalize it out of `argv` before parsing.
 - **Reserved parameter names**: assigning to reserved shell names (`UID`,
   `EUID`, `GID`, `PPID`) can invoke the bound system behavior instead of
   storing a value — silently changing process credentials mid-script. Use
@@ -105,6 +114,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   diffs use `git diff origin/base...HEAD` (merge-base form); suspect this
   mechanism first when a diff looks too large or shows deletions in untouched
   files.
+- **Reverting a path is not undoing your edit**: `git checkout <path>` and
+  `git restore <path>` discard *every* uncommitted change in that file. Used
+  to remove a planted probe it also removes whatever else was in flight there,
+  and the loss is silent. Check `git diff <path>` first, or plant in a copy and
+  restore from that. The same asymmetry makes the restore step fragile: if the
+  probe can time out or abort, the restore must not be the next command in the
+  same invocation — put it where a failure cannot skip it.
 - **Dirty-worktree pulls**: before pulling into a worktree with
   staged/unstaged/untracked changes, fetch first and compare incoming paths
   against every dirty path; on overlap or a non-fast-forward, stop and clear

package/{scripts → compose}/assemble.py

@@ -51,12 +51,12 @@ ENTRY_SEED = f"""# CLAUDE.md
 """
 
 # Automation-owned personal learnings file, pulled in by PERSONAL_IMPORT_LINE.
-# Kept in sync with scripts/collect-learning.py (the light-flow submit tool),
+# Kept in sync with learn/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
+     learn/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
@@ -139,9 +139,68 @@ 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):
+def author_only(path):
+    """Does this file's own frontmatter say it is for the corpus author?
+
+    A guide declaring `audience: author` documents a step only the author can
+    perform, and names repository paths that exist in a checkout and nowhere
+    else. The tier says who NEEDS the subject; this says who can ACT on it, and
+    the two are independent — the distill workflow is `infra`, so tier alone
+    delivered it to every selection.
+
+    The declaration in the file is the authority, deliberately not restated in
+    `domains.json`: a second copy is one more thing that can disagree, and until
+    this read existed the label was consumed only by the gate that the label
+    exempts. A clone is a checkout, so `install.sh`'s non-packaged path still
+    deploys these; this filter is the packaged one.
+
+    THE single reader of that declaration. `gates/check-package.sh` imports this
+    rather than parsing the frontmatter again: the gate tolerates references that
+    only this withholding makes safe, so a second parser drifting from this one
+    would exempt a file the assembler still installs — precisely the defect the
+    pair exists to close. The direction is fixed: author-side may import shipped
+    code, never the reverse, because the payload cannot depend on `gates/`.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    if not text.startswith("---\n"):
+        return False
+    front = text.split("---\n", 2)[1]
+    return any(ln.split(":", 1)[1].strip() == "author"
+               for ln in front.splitlines() if ln.startswith("audience:"))
+
+
+def copy_filtered(src_dir, names, dest, rewrite=None, dry=False, backup=None):
+    """Write the selected files, and remove the ones we deployed and no longer select.
+
+    Writing alone leaves the destination describing a selection nobody chose: a machine that
+    took every domain and later narrowed to one kept the whole set on disk, so selection.json
+    stopped describing what was deployed. merge_settings already drops a deselected hook's
+    REGISTRATION through `owned_names`; this is the same reconciliation for the files.
+
+    Ownership is "the name exists in our source tree", which is what keeps a file the user put
+    in the same directory safe — it is not in `src_dir`, so it is never a candidate.
+    """
     if not dry:
         dest.mkdir(parents=True, exist_ok=True)
+    keep_names = set(names)
+    if dest.is_dir() and src_dir.is_dir():
+        ours = {p.name for p in src_dir.iterdir() if p.is_file()}
+        for path in sorted(dest.iterdir()):
+            if not path.is_file() or path.name in keep_names or path.name not in ours:
+                continue
+            print(f"  {'[dry] ' if dry else ''}deselected, removed {path}")
+            if dry:
+                continue
+            # Backed up first, the way every other removal here is: these are copies of repo
+            # content, but a machine offline from the repo has no other way back.
+            if backup is not None:
+                kept = backup / "deselected" / str(path).lstrip("/")
+                kept.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(path, kept)
+            path.unlink()
     for n in names:
         if dry:
             print(f"  [dry] copy {n} -> {dest}")
@@ -149,7 +208,22 @@ def copy_filtered(src_dir, names, dest, rewrite=None, dry=False):
         body = (src_dir / n).read_text(encoding="utf-8")
         if rewrite:
             body = body.replace(*rewrite)
-        (dest / n).write_text(body, encoding="utf-8")
+        target = dest / n
+        # Replacing is as destructive as removing, and README promises a copy of the exact
+        # prior bytes under the state backup dir. install.sh's deploy_file kept that promise;
+        # the assembler is the default path now, so writing straight over a guide the user had
+        # edited broke it for every file it deploys. Identical content is not a replacement,
+        # and copying it would fill the backup dir on every no-op reinstall.
+        if backup is not None and target.is_file():
+            try:
+                changed = target.read_text(encoding="utf-8") != body
+            except (OSError, UnicodeDecodeError):
+                changed = True   # unreadable is not "unchanged"; keep the bytes
+            if changed:
+                kept = backup / "replaced" / str(target).lstrip("/")
+                kept.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(target, kept)
+        target.write_text(body, encoding="utf-8")
 
 
 def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names=None):
@@ -200,7 +274,7 @@ def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names
 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."""
+    learn!. learn/collect-learning.py appends to it thereafter."""
     md = claude_dir / "personal" / "learnings.md"
     if md.exists():
         return
@@ -211,7 +285,18 @@ def seed_personal_learnings(claude_dir, dry=False):
     md.write_text(PERSONAL_LEARNINGS_HEADER, encoding="utf-8")
 
 
-def seed_entry(claude_dir, legacy_monolith, dry=False):
+def seed_entry(claude_dir, legacy_monolith, prior_deployed=(), dry=False):
+    """Seed the entry, and never rewrite a file the user wrote.
+
+    Telling those apart used to be a byte-comparison against THIS commit's monolith, which
+    recognizes only a re-install of the same release. Anyone upgrading from an earlier one had
+    that release's monolith on disk — our file, not theirs — and it was reported as user-owned,
+    so the import line was never added and the corpus did not load until they edited it by hand.
+
+    `prior_deployed` is the previous install's manifest, which is the repo's existing answer to
+    "did we write this": deploy_file records every destination it writes, and the pre-unification
+    full install deployed the entry through it. Ownership is read the same way it was written.
+    """
     entry = claude_dir / "CLAUDE.md"
     if not entry.exists():
         if dry:
@@ -225,7 +310,11 @@ def seed_entry(claude_dir, legacy_monolith, dry=False):
     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
+    # Ours by content (a re-install of this release) OR by record (any earlier one).
+    # Both sides go through pathlib first: the manifest is written by shell, so a config dir
+    # with a trailing or doubled slash lands in it verbatim, and raw string equality then
+    # misses a path that is the same file.
+    if body == legacy_monolith or str(pathlib.Path(entry)) in prior_deployed:
         if dry:
             print("  [dry] replace legacy deployed CLAUDE.md with seed (backup)")
             seed_personal_learnings(claude_dir, dry)
@@ -259,12 +348,50 @@ def merge_codex(codex_dir, central_text, dry=False):
     agents.write_text(new, encoding="utf-8")
 
 
+def remove_owned(claude_dir, codex_dir, manifest, dry=False):
+    """Undo the two spans this file writes into files it does not own.
+
+    Every merge here needs a matching removal, and for a long time these two did not have one:
+    uninstall deleted the deployed hook FILES while leaving their registrations in the user's
+    settings.json, and deleted the guides while leaving the AGENTS.md central region that
+    references them. The user was left with hooks invoking missing paths and instructions
+    pointing at deleted files, after a command that reported success.
+
+    Ownership is read the same way it is written — `merge_settings` owning by manifest NAME, and
+    the marker pair for the Codex region — so removal can never reach further than the merge did.
+    Text outside the markers, and settings entries this repo did not register, are untouched.
+    """
+    owned = sorted({h for h in manifest.get("hooks", {})})
+    merge_settings(claude_dir, [], REPO / "claude" / "settings.template.json",
+                   dry=dry, owned_names=owned)
+
+    agents = codex_dir / "AGENTS.md"
+    if not agents.is_file():
+        return
+    body = agents.read_text(encoding="utf-8")
+    if MARK_START not in body or MARK_END not in body:
+        return  # nothing of ours in there; a whole-file legacy deploy is not ours to judge
+    pre, rest = body.split(MARK_START, 1)
+    _, post = rest.split(MARK_END, 1)
+    if dry:
+        print("  [dry] strip AGENTS.md central region, keep everything outside the markers")
+        return
+    agents.write_text((pre + post).lstrip("\n"), encoding="utf-8")
+
+
 def main():
     ap = argparse.ArgumentParser()
+    ap.add_argument("--remove-owned", action="store_true",
+                    help="undo the settings registrations and the AGENTS.md central region "
+                         "(uninstall's half of the merge); writes nothing else")
     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("--prior-manifest", default=None,
+                    help="the previous install's manifest. Ownership of the entry file is read "
+                         "from it, so an earlier release's deployed CLAUDE.md is recognized as "
+                         "ours instead of being reported as the user's.")
     ap.add_argument("--dry-run", action="store_true")
     args = ap.parse_args()
 
@@ -273,12 +400,17 @@ def main():
     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")],
+    manifest = json.loads((REPO / "compose" / "domains.json").read_text(encoding="utf-8"))
+    if args.remove_owned:
+        # No domains gate: removal does not depend on the manifest being well-formed, and an
+        # uninstall that refuses to run because the corpus is mid-edit would strand the user.
+        remove_owned(claude_dir, codex_dir, manifest, dry=args.dry_run)
+        return
+
+    gate = subprocess.run([sys.executable, str(REPO / "compose" / "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:
@@ -300,6 +432,29 @@ def main():
             codex_bundle += codex_only + "\n"
 
     guides = filtered_files(manifest, "guides", selection)
+    withheld = [n for n in guides if author_only(REPO / "claude" / "guides" / n)]
+    guides = [n for n in guides if n not in withheld]
+    # Not writing it is not enough for anyone who installed before this rule: the
+    # manifest is rebuilt from the current deploy, so a file that stops being
+    # deployed stops being tracked and would sit there for good.
+    stale = [d / n for n in withheld
+             for d in (claude_dir / "central" / "guides", codex_dir / "guides")
+             if (d / n).is_file()]
+    # Copy before removing, the way install.sh backs up a file it replaces. The
+    # name matching ours does not prove we wrote it — a shared or symlinked guides
+    # directory can hold somebody's own file under the same name, and a deleted
+    # one is not recoverable from anywhere else.
+    # One timestamped directory per run, with a subdirectory per reason for the removal:
+    # `withheld` is an audience decision, `deselected` is a selection change.
+    run_backup = state_dir / "backups" / time.strftime("%Y%m%d-%H%M%S")
+    backup = run_backup / "withheld"
+    for path in stale:
+        print(f"  {'[dry] ' if args.dry_run else ''}remove withheld {path}")
+        if not args.dry_run:
+            keep = backup / str(path).lstrip("/")
+            keep.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(path, keep)
+            path.unlink()
     hooks = filtered_files(manifest, "hooks", selection)
     agents = filtered_files(manifest, "agents", selection)
     dry = args.dry_run
@@ -307,19 +462,30 @@ def main():
     central = claude_dir / "central"
     if dry:
         print(f"[dry] bundle.md: {n_bullets} bullets; guides={guides} hooks={hooks} agents={agents}")
+        if withheld:
+            print(f"  [dry] withheld (audience: author): {withheld}")
     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)
+                  rewrite=(f"{CLAUDE_VAR}/guides/", f"{CLAUDE_VAR}/central/guides/"), dry=dry,
+                  backup=run_backup)
+    copy_filtered(REPO / "claude" / "hooks", hooks, central / "hooks", dry=dry, backup=run_backup)
+    copy_filtered(REPO / "claude" / "agents", agents, central / "agents", dry=dry,
+                  backup=run_backup)
     merge_settings(claude_dir, hooks, REPO / "claude" / "settings.template.json", dry=dry,
                    owned_names=manifest.get("hooks", {}))   # deselected hooks must drop too
-    entry_state = seed_entry(claude_dir, monolith, dry=dry)
+    prior_deployed = set()
+    if args.prior_manifest:
+        prior = pathlib.Path(args.prior_manifest)
+        if prior.is_file():
+            prior_deployed = {str(pathlib.Path(ln.strip())) for ln in
+                              prior.read_text(encoding="utf-8").splitlines() if ln.strip()}
+    entry_state = seed_entry(claude_dir, monolith, prior_deployed, dry=dry)
 
     merge_codex(codex_dir, codex_bundle, dry=dry)
-    copy_filtered(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry)
+    copy_filtered(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry,
+                  backup=run_backup)
 
     if not dry:
         state_dir.mkdir(parents=True, exist_ok=True)
@@ -327,7 +493,9 @@ def main():
             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}")
+          f"{len(agents)} agents for selection {sorted(selection)}; entry={entry_state}"
+          + (f"; withheld {len(withheld)} author-only guide(s): {', '.join(withheld)}"
+             if withheld else ""))
     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.")

package/{scripts → compose}/canary.sh

@@ -14,13 +14,15 @@ set -u
 CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
 BUNDLE="$CLAUDE_DIR/central/bundle.md"
 
-# 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.
+# Every install assembles a central bundle now — the shape that had none, where the entry file
+# WAS the corpus, is gone. So a missing bundle is a real failure again rather than the N/A it
+# used to be, and an entry file with no bundle beside it is a pre-convergence layout that a
+# re-install fixes.
 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
+    echo "CANARY FAIL: entry file present but no central bundle at $BUNDLE — this is the old"
+    echo "             whole-file layout; re-run: agent-bios install"
+    exit 1
   fi
   echo "CANARY FAIL: no corpus deployed at $CLAUDE_DIR (run: agent-bios install)"
   exit 1
@@ -34,6 +36,13 @@ probe="Somewhere in your loaded instruction context there may be a line that sta
 out="$(cd "$HOME" && claude -p "$probe" 2>/dev/null)"
 
 if printf '%s' "$out" | grep -qF "$expected"; then
+  # Record WHICH bundle was proven to load. This is the only evidence in the system that
+  # distinguishes a corpus that landed from one that is read, so the irreversible act that
+  # depends on that distinction — pruning a user's personal copy of a promoted learning — reads
+  # this file rather than re-deriving a weaker answer from file contents. The rev is part of the
+  # proof: a later reassembly invalidates it instead of inheriting it.
+  STATE_DIR="${AGENT_BIOS_STATE_DIR:-$HOME/.local/share/agent-bios}"
+  mkdir -p "$STATE_DIR" 2>/dev/null && printf '%s\n' "$expected" > "$STATE_DIR/activation.txt" 2>/dev/null || true
   echo "CANARY PASS: central bundle is loading ($expected)"
   exit 0
 fi

package/{scripts → compose}/check-domains.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Bijection/coverage gate: config/domains.json vs the canonical corpus.
+"""Bijection/coverage gate: compose/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
@@ -33,10 +33,10 @@ import re
 import sys
 
 sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
-import pkgid  # noqa: E402  (sibling module; scripts/ is a flat toolbox, not a package)
+import pkgid  # noqa: E402  (sibling module in compose/)
 
 REPO = pathlib.Path(__file__).resolve().parent.parent
-MANIFEST = REPO / "config" / "domains.json"
+MANIFEST = REPO / "compose" / "domains.json"
 MONOLITH = REPO / "claude" / "CLAUDE.md"
 FILE_SECTIONS = {  # manifest key -> corpus dir, glob
     "guides": ("claude/guides", "*.md"),
@@ -272,6 +272,12 @@ def self_test(manifest, bullets):
 def main():
     manifest = load_manifest()
     bullets = corpus_bullets()
+    extra = [a for a in sys.argv[1:] if a != "--self-test"]
+    if extra:
+        sys.exit(f"check-domains: refusing unknown argument(s) {extra!r}. This gate "
+                 f"validates the core manifest only; a package manifest path would be "
+                 f"silently ignored, reporting a check that never ran. Parameterizing "
+                 f"it is contract v2 §3.")
     if "--self-test" in sys.argv:
         missed = self_test(manifest, bullets)
         if missed:

package/{config → compose}/domains.json

@@ -106,6 +106,7 @@
     {"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"]},

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