agent-bios 0.9.8 → 0.10.0

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/review-request.md

@@ -26,10 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the staged-workflow guide's severity ladder and review loop own that),
-which reviewer kind to route to (the multi-model guide's convergence heuristic),
-or how to phrase a prompt for a given model family (the per-family prompting
-guides).
+material (the severity ladder and review loop in `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` own that),
+which reviewer kind to route to — the convergence heuristic in
+`${CODEX_HOME:-$HOME/.codex}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
+family is out of scope here; where that guidance ships, the rule that needs it
+points at it.
 
 The rules below are derived from ~330 real multi-lens review sessions run in
 this environment. That corpus is one model family in practice, so nothing here
@@ -80,8 +81,9 @@ So state the floor in the request: **do not report a finding you would rate low.
 It will be discarded; spend the effort on a medium-or-above finding instead.**
 This is not a quality bar on the reviewer, it is a cost decision — the corpus
 shows the discard happens regardless, so the only question is whether you pay to
-generate it first. (What counts as each severity is the staged-workflow guide's
-ladder, not this guide's.)
+generate it first. (What counts as each severity is the ladder in
+`${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md`, not
+this guide's.)
 
 ## Forbid carry-forward findings
 
@@ -128,7 +130,7 @@ nicely: the submit schema refuses output without them. The result is a corpus
 where reviewers are right about existence (0.3% of issues end unresolved after
 argument) and where "found nothing" is a verified statement rather than silence.
 
-This is the general rule from the capability-boundary guide applied to review:
+This is the general capability-boundary rule applied to review:
 when output must have a property, make it unavailable without it. If your review
 route has a schema, put the anchor there. If it does not, the demand belongs in
 the request — but expect the weaker result that a request-only rule gives you.

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
@@ -99,12 +108,29 @@ depends on it, pin it explicitly instead of trusting the environment.
 
 ## Git operations
 
+- **A stale local base inflates the range**: before reasoning about what a branch
+  contains or opening a PR, `git fetch`, then ask against the remote rather than the
+  local tracking ref — `git log origin/<base>..HEAD` for which commits are yours, and
+  the merge-base form below for the diff. On a shared repo the local base lags until
+  you pull, so `<base>..HEAD` quietly folds in work that already merged. When a range
+  looks surprisingly large, suspect the base before the branch.
+- **"Mergeable" is measured against the base, not against siblings**: the platform
+  flag says each PR merges into the base, and two PRs can both be clean while
+  conflicting with each other. Before choosing a merge order, diff their changed-file
+  sets and simulate the sequence.
 - **Two-dot diff semantics**: `git diff A..B` is a direct snapshot
   comparison — unlike `git log A..B` it excludes nothing, so a lagging
   merge-base injects unrelated upstream changes into the diff. For PR/review
   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/codex/guides/verification-discipline.md

@@ -0,0 +1,166 @@
+---
+guide_id: verification-discipline
+language: en
+status: active
+use_when:
+  - deciding how much verification a change deserves, before spending on a slow or expensive run
+  - choosing what to run for a domain — code, ontology, config/data, spreadsheets, docs, a release
+  - building the case space for a check, or deciding what its expected answer should be
+  - a check came back green, empty, or fast, and you are about to believe it
+  - running independent or adversarial review, and judging what its agreement is worth
+core_rules:
+  - a check is only evidence if it could have failed — assert a non-empty subject before any "no bad X" claim
+  - enumerate the case space from the artifact that defines it, and record real output instead of typing an expectation
+  - proportion depth to cost, risk, and information gain; a single-user tool does not warrant production assurance
+  - same-kind reviewers share blind spots, so their shared "clean" is an absence of objection, not verification
+---
+
+# Verification Discipline
+
+A scoped extension of the global Verification Discipline section. Its subject is not "did you
+test it" but the harder question underneath: **could this check have failed?** Everything below
+is a way of answering that before the result is believed rather than after it is quoted.
+
+The global rules that stay always-loaded are the ones whose moment does not announce itself — you
+believe you are finished, and that belief is the failure. This guide is what you open once you
+know you are verifying.
+
+## Proportion the depth before you spend
+
+Verification has a cost and an information yield, and they are not correlated by default. Decide
+the depth first:
+
+- Diagnose in code before running anything expensive, and replay the changed deterministic logic
+  over persisted real artifacts rather than re-running the whole pipeline to observe it.
+- Probe at N=1 with the inputs precondition-checked. A single well-chosen case that reaches the
+  real path outranks a hundred that stop short of it.
+- Reserve the full design-review-plus-live-verification treatment for first-of-kind work and for
+  changes that move authority — who may decide, who may write, what is irreversible.
+- Proportion assurance to the deployment context. A single-user tool operating on its owner's own
+  data does not warrant production-grade assurance, and treating it as if it did buys nothing
+  while delaying delivery. Prefer shipping.
+
+The failure this prevents is not under-testing. It is spending the verification budget on the
+cheap half of the risk and having nothing left for the part that could actually hurt.
+
+## The static floor
+
+Run the broad, cheap checks first and let them fail before anything slower starts: typecheck,
+lint, build, format, schema and config validation, graph validation, workbook structure checks,
+import boundaries, and security checks where they exist. These are a floor, not a verdict — they
+prove the artifact is well-formed, never that it behaves.
+
+## Verification Menus
+
+Pick the narrowest reliable mix that proves the changed behavior, meaning, or contract. Inside the
+mix, the unit to add is the narrowest reliable runtime or semantic test that proves it — narrowest
+meaning the smallest test that would fail if the change were wrong, which is not the same as the
+cheapest one to write.
+
+- Code: a layered mix of unit tests, integration tests for E2E segments, targeted E2E for changed flows, and full E2E for release or high-risk changes.
+- Ontology: static graph checks, concept economy gates, changed-path integration checks, and competency-question E2E checks.
+- Config or data: real parsers, schema checks, fixture validation, and sample transformations.
+- Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
+- Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
+- Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
+- A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
+- Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
+- 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
+
+Which scenarios exist is semantic work: derive them from the diff, the user impact, the
+concept impact, and the failure modes. Running them is not — tools and code execute the
+cases and report the evidence. Keeping that split is what stops a suite from being a
+record of what someone imagined.
+
+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.
+
+- Make the criterion falsifiable before you make it green. Prefer a signal that fails when
+  the mechanism is wrong — a negative or contrast control. Where no existing gate can judge
+  a criterion, build the executable judge or do not claim the criterion met: a criterion
+  nothing can fail is a description of the work, not a check on it.
+- 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.
+
+## When a green means nothing
+
+A passing check and a check that never ran look identical from outside. These are the shapes that
+produce a green with no evidence behind it:
+
+- **The empty subject.** Any "no bad X" or "all X satisfy P" claim over an empty set is
+  vacuously true. Assert the entity-under-test set has cardinality greater than zero **before**
+  the claim, and make the gate itself refuse to report clean when it judged nothing.
+- **The fixture that misses the guard.** For a test touching a branch you are adding or deleting,
+  confirm its inputs satisfy the live branch's entry guard. A copied fixture that fails the new
+  guard routes silently into the about-to-be-deleted dead branch and stays green after the real
+  behavior breaks.
+- **The permissive fallback in the checker.** A `a || b` inside a gate absorbs a wrong assumption
+  and keeps passing. Checker code must assert the shape it expects and fail loud.
+- **The suspiciously fast or empty run.** When a check goes green unexpectedly quickly, or reports
+  nothing at all, dump what it actually ran over before believing it. A harness that crashed early
+  and one that found nothing produce the same exit code.
+- **The control that went quiet.** A negative control indexing a live list stops testing when that
+  list empties, and says nothing about it. New controls build their own subject; resolving an item
+  means re-reading the controls for ones that have gone silent.
+
+The discipline that covers all five: after adding a check, revert the fix it guards and watch the
+check fail. A control that survives a faithful revert was never testing the thing it names.
+
+## Keeping E2E honest
+
+E2E is where flakiness is mistaken for environment noise and then ignored. Keep it deterministic
+with fixed data, resilient selectors, isolated external dependencies, and explicit waits rather
+than sleeps. A flaky E2E is not a weaker test; it is a test whose result carries no information,
+and a suite that people re-run until it passes has been switched off without anyone deciding to.
+
+## Independent review, and what agreement is worth
+
+For non-trivial designs and high-risk changes, run independent adversarial review across distinct
+lenses — ideally on the design, before implementation, when a finding is still cheap to act on.
+Then re-verify each finding against real code before acting on it: a reviewer reasons from what it
+was shown, and what it was shown may be wrong.
+
+Apply the **convergence heuristic by reviewer kind** — judge the result by reviewer kind, not by count:
+
+- Same-kind convergence is high confidence but blind-spot-sharing. Two reviewers of the same kind
+  agreeing that something is clean is an absence of objection, not verification.
+- Different-kind divergence is the expected signal, not a problem to resolve. Act on the union of
+  what they found rather than the intersection.
+- An orchestrated workflow's self-reported all-green is never sufficient on its own. Re-run the
+  diff inspection and the verification suite yourself.
+
+The cheapest way to buy real independence is a different provider; after that a different model;
+after that strictly higher effort. A reviewer run at lower effort than the work it checks buys
+nothing — cheaper is not another perspective.
+
+## Reporting
+
+Before calling the work done, state the checks that ran, their results, and any risk left
+unverified. "Unverified" is a legitimate outcome and a useful one; silence about it is not.

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,30 @@ 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 hook_command_matches(command, name):
+    """A complete `/hooks/<name>` token: the command ends with it, or it is followed by an
+    argument. One matcher for the merge below AND the domain gate's settings leg — the gate
+    used a substring test, so `central/hooks/<name>.disabled` passed the gate while this
+    merge skipped it, and the install carried no hook under a green gate."""
+    return command.endswith("/hooks/" + name) or f"/hooks/{name} " in command + " "
 
 
 def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names=None):
@@ -180,7 +262,8 @@ def merge_settings(claude_dir, hook_names, template_path, dry=False, owned_names
     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)
+            owner = next((n for n in hook_names
+                          if any(hook_command_matches(c, n) for c in cmds)), None)
             if owner is None:
                 continue
             clone = json.loads(json.dumps(en))
@@ -200,7 +283,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 +294,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 +319,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 +357,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 +409,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 +441,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 +471,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 +502,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.")