agent-bios 0.9.9 → 0.10.0

package/claude/guides/tooling-gotchas.md

@@ -108,6 +108,16 @@ 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

package/claude/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/claude/hooks/tooling-gotchas-hook.py

@@ -12,53 +12,159 @@ import sys
 
 GUIDE = "guides/tooling-gotchas.md"
 
-# (name, compiled trigger, one-line reminder). Priority order; max 2 injected.
+# (name, compiled trigger, one-line reminder, guide anchor). Priority order; max 2 injected.
+#
+# The anchor is the heading in tooling-gotchas.md this rule compresses. It exists because the
+# hook is Claude-only and the guide is what a Codex reader gets instead: a rule admitted here
+# with no counterpart there would silently give the two hosts different guidance. The mapping
+# is declared rather than matched, because a rule name and a guide heading do not share a
+# string. --self-test checks every anchor against the guide AND its codex mirror.
 RULES = [
     ("reserved-shell-names",
      re.compile(r"\b(UID|EUID|GID|PPID)="),
      "Assigning reserved shell names (UID/EUID/GID/PPID) can invoke the bound "
-     f"system behavior instead of storing a value — use unreserved names ({GUIDE})."),
+     f"system behavior instead of storing a value — use unreserved names ({GUIDE}).",
+     "Reserved parameter names"),
     ("git-diff-two-dot",
      re.compile(r"git\s+diff\s+[^|;&]*(?<!\.)\.\.(?!\.)"),
      "git diff A..B is a direct snapshot comparison, not a range exclusion — "
-     f"for PR/review diffs use three-dot origin/base...HEAD ({GUIDE})."),
+     f"for PR/review diffs use three-dot origin/base...HEAD ({GUIDE}).",
+     "Two-dot diff semantics"),
     ("git-pull-dirty",
      re.compile(r"\bgit\s+pull\b"),
      "Before pulling into a worktree with local changes: fetch first, compare "
-     f"incoming paths against dirty paths, prefer --ff-only ({GUIDE})."),
+     f"incoming paths against dirty paths, prefer --ff-only ({GUIDE}).",
+     "Dirty-worktree pulls"),
     ("metachar-inline-arg",
      re.compile(r"(codex-run|codex-helm|codex\s+exec|claude\s+-p)\b[^|;&]*[\"'][^\"']*(\$\(|`)"),
      "Values with shell metacharacters must reach the target via stdin or a "
-     f"file, not inline arguments — the shell expands them first ({GUIDE})."),
+     f"file, not inline arguments — the shell expands them first ({GUIDE}).",
+     "Metacharacter-bearing values"),
     ("pipe-exit-masking",
      re.compile(r"\$\?"),
      "A pipeline's $? reflects only the last stage — capture the tested "
-     f"stage's own status (unpiped run, PIPESTATUS, per-command pipefail) ({GUIDE})."),
+     f"stage's own status (unpiped run, PIPESTATUS, per-command pipefail) ({GUIDE}).",
+     "Pipe exit masking"),
     # Path-shaped argument only: `git checkout main` is a branch switch and needs no
     # warning, while `git checkout src/x.py` silently discards every uncommitted edit in
     # that file — including ones the caller did not put there.
     ("git-checkout-path",
      re.compile(r"\bgit\s+(checkout|restore)\b[^|;&]*(--\s|[\w.-]*[./][\w./-]*)"),
      "Reverting a path discards ALL uncommitted edits in that file, not just the one "
-     f"you planted — check `git diff <path>` first, or restore from a copy ({GUIDE})."),
+     f"you planted — check `git diff <path>` first, or restore from a copy ({GUIDE}).",
+     "Reverting a path is not undoing your edit"),
     ("grep-binary-heuristic",
-     re.compile(r"(^|[;&(]\s*|&&\s*|\|\|\s*)grep\s"),
+     # Applied per extracted STAGE by matches(), not to the raw line. The stage's
+     # COMMAND WORD must be grep — after optional reserved words (`if ! grep -q`
+     # is the assert-absence idiom) and per-command assignments (`LC_ALL=C grep`
+     # — locale pinning is what our own guides recommend); bare, path-prefixed,
+     # or the DIRECT git subcommand (git grep shares the binary heuristic). A
+     # stage that merely passes the word along (`echo grep needle`) runs no grep
+     # and gets no reminder. Greps reached through any other prefix — sudo,
+     # xargs, git global options between git and the subcommand (`git -C repo
+     # grep`), env, timeout, and their successors — are accepted residual by
+     # decision: each is one rung of an endless prefix ladder, and a missed
+     # reminder is the failure mode this advisory-only hook tolerates.
+     re.compile(r"\s*(?:(?:!|if|elif|else|then|do|while|until|time)\s+)*"
+                r"(?:\w+=\S*\s+)*(?:\S+/)?(?:git\s+)?grep\s"),
      "grep can misread text with heavy non-ASCII/NUL as binary and return a "
-     f"false no-match — prefer the Grep tool (ripgrep) or grep -a ({GUIDE})."),
+     f"false no-match — prefer the Grep tool (ripgrep) or grep -a ({GUIDE}).",
+     "grep binary heuristic"),
 ]
 MAX_INJECT = 2
 
 
-def matches(command: str):
+def matches(command: str, limit: int | None = MAX_INJECT):
+    """Rules this command trips. `limit` is a DELIVERY policy — at most two reminders are
+    worth injecting at once — not a judgement about which rules matched, so the self-test
+    asks for the untruncated list rather than re-deriving the matching itself."""
     hits = []
-    for name, rx, msg in RULES:
+    for name, rx, msg, _ in RULES:
         if name == "pipe-exit-masking" and "|" not in command:
             continue
-        if name == "grep-binary-heuristic" and re.search(r"(^|\s)(-a\b|--text)", command):
+        if name == "grep-binary-heuristic":
+            # Per STAGE, not per command: -a on an upstream grep does nothing for a
+            # downstream one (`git grep -a foo | grep bar` leaves bar's stage on the
+            # binary heuristic), so the exemption holds only when EVERY grep stage
+            # carries its own text-mode flag.
+            # Every separator starts a new stage: a single & (background) and a newline
+            # join commands as surely as ; and | — `grep -a foo a & grep bar b` left the
+            # -a covering a stage it never touches.
+            # A command substitution executes regardless of the quotes around it:
+            # `echo "$(grep needle payload)"` runs that grep, and quote-blanking was
+            # hiding it from the stage list so an outer -a covered it. Substitution
+            # bodies are lifted out (innermost-first, to a fixpoint) and judged as
+            # stages of their own.
+            scan = command
+            seen_subs = set()
+            while True:
+                subs = [s2 for s2 in re.findall(r"\$\(([^()]*)\)", scan)
+                        + re.findall(r"`([^`]*)`", scan)
+                        if s2 not in seen_subs]
+                if not subs:
+                    break
+                seen_subs.update(subs)
+                scan = scan + "\n" + "\n".join(subs)
+            # Quotes are blanked BEFORE splitting: a separator inside a quoted pattern
+            # (`grep 'grep -a;foo'`) manufactured a pseudo-stage carrying a text-mode
+            # flag that exists only as pattern content. Blanked to a placeholder TOKEN,
+            # not to nothing: `grep -e "needle" -a file` blanked to whitespace left -e
+            # to consume the -a as its argument, and the real text-mode flag vanished
+            # with the operand's token boundary.
+            blanked = re.sub(r"'[^']*'|\"(?:\\\\.|[^\"\\\\])*\"", "0", scan)
+            # Comments go after the quotes: with quoted text blanked, any remaining # is
+            # a real comment, and `grep needle payload # use -a next time` was exempting
+            # itself with advice bash never passes to grep.
+            blanked = re.sub(r"#[^\n]*", "", blanked)
+            # Parens split as the old line-shaped trigger's [;&(|] class did: a
+            # subshell or group opener starts a command (`(grep needle)` runs grep),
+            # and dropping ( from the boundaries regressed exactly that form.
+            stages = [st for st in re.split(r"\|\||&&|[|;&\n()]", blanked)
+                      if rx.match(st)]
+            # The STAGES are the trigger: a grep whose only appearance is inside a
+            # lifted substitution (`echo "\`grep needle payload\`"`) never matched a
+            # line-shaped regex, and a quoted assignment value (`FILTER='two words'
+            # grep ...`) hid the command word from it. The rule's regex judges each
+            # stage in COMMAND-WORD position — `echo grep needle` passes the word as
+            # an argument, runs no grep, and stays quiet.
+            if not stages:
+                continue
+            # Options end at `--`: after it, `-a` is the PATTERN operand (grep's usage is
+            # [OPTION]... PATTERNS [FILE]...), so `grep -- -a payload` is still on the
+            # binary heuristic and must keep its reminder.
+            # And `-e <pattern>` consumes its argument: in `grep -e -a payload` the -a
+            # is the PATTERN (grep --help: -e, --regexp=PATTERNS), so it must not read
+            # as text mode. The pattern-taking options are blanked before the flag scan.
+            # -f/--file consumes its argument the same way (-f, --file=FILE): every
+            # pattern-taking option is blanked, or its argument reads as a flag.
+            # Quoted text is pattern content, never options: `grep 'foo -a bar'` has no
+            # text-mode flag, and the unquoted scan read the -a inside the pattern.
+            # Quotes are blanked first, then the -- operand split, then pattern-taking
+            # option arguments.
+            opts = [re.sub(r"(^|\s)(?:-e|--regexp|-f|--file)(?:=\S+|\s+\S+)", " ",
+                           st.split(" -- ", 1)[0])
+                    for st in stages]
+
+            # Bundled short options count too: `grep -qa` enables text mode (grep
+            # --help: -a, --text), and requiring a whitespace-delimited -a warned
+            # about binary data on a grep that reads it as text. A letter that takes
+            # an argument (-e -f -m -A -B -C -d -D) consumes the REST of the bundle,
+            # so in `-ea` the a is the PATTERN, not a flag — an `a` reads as text
+            # mode only when every letter before it is argument-free.
+            def text_mode(o):
+                if re.search(r"(^|\s)(-a\b|--text\b|--binary-files(?:=|\s+)text\b)", o):
+                    return True
+                return any(len(halves) == 2 and not set(halves[0]) & set("efmABCdD")
+                           for tok in re.findall(r"(?:^|\s)-([A-Za-z0-9]+)", o)
+                           for halves in [tok.split("a", 1)])
+
+            if all(text_mode(o) for o in opts):
+                continue
+            hits.append((name, msg))
             continue
         if rx.search(command):
             hits.append((name, msg))
-    return hits[:MAX_INJECT]
+    return hits if limit is None else hits[:limit]
 
 
 def main() -> int:
@@ -82,5 +188,209 @@ def main() -> int:
     return 0
 
 
+def self_test() -> int:
+    """Two halves, because this hook serves two hosts differently.
+
+    Claude gets the injection, so the first half runs the real entry point over real stdin and
+    requires the message out. Codex gets nothing from a hook, so its equivalent is the guide —
+    and the second half is the only thing that keeps the two hosts saying the same thing.
+    """
+    import pathlib, subprocess
+
+    here = pathlib.Path(__file__).resolve()
+    repo = here.parent.parent.parent
+    problems = []
+    assert RULES, "no rules: this self-test would pass over nothing"
+
+    # -- half 1: the hook runs, matches, and emits. A file that is copied and registered but
+    # crashes on every invocation satisfies every other check in this repository.
+    fires = "UID=0 echo hi"
+    payload = json.dumps({"tool_name": "Bash", "tool_input": {"command": fires}})
+    r = subprocess.run([sys.executable, str(here)], input=payload,
+                       capture_output=True, text=True)
+    if r.returncode != 0:
+        problems.append(f"hook exited {r.returncode} on a matching command: {r.stderr.strip()[:120]}")
+    elif "additionalContext" not in r.stdout:
+        problems.append(f"hook emitted no context for {fires!r}; got {r.stdout.strip()[:80]!r}")
+
+    # A non-matching command must stay silent, or "it fired" proves nothing.
+    quiet = json.dumps({"tool_name": "Bash", "tool_input": {"command": "echo hello"}})
+    r2 = subprocess.run([sys.executable, str(here)], input=quiet, capture_output=True, text=True)
+    if r2.stdout.strip():
+        problems.append(f"hook injected on a command that matches nothing: {r2.stdout.strip()[:80]!r}")
+
+    # Every rule needs a command that must reach it. A nonempty pattern is not evidence: a
+    # trigger of `(?!)` can never match, and a rule suppressed by the special-case logic in
+    # matches() never reaches the caller either — both leave the rule inert while this file
+    # goes on reporting that all of them fire.
+    FIXTURES = {
+        "reserved-shell-names":  "UID=0 echo hi",
+        "git-diff-two-dot":      "git diff main..HEAD",
+        "git-pull-dirty":        "git pull origin main",
+        "metachar-inline-arg":   'codex exec "$(cat packet.md)"',
+        "pipe-exit-masking":     "make build | tail -1; echo $?",
+        "git-checkout-path":     "git checkout src/thing.py",
+        "grep-binary-heuristic": "grep needle haystack.md",
+    }
+    # A pipeline-stage grep must reach the rule too — the fixture alone exercises only
+    # command-start grep, and the reminder is most needed mid-pipeline.
+    if "grep-binary-heuristic" not in [h for h, _ in matches("cat payload | grep needle", limit=None)]:
+        problems.append("grep-binary-heuristic: does not fire on a pipeline stage "
+                        "('cat payload | grep needle')")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("git grep -a foo | grep bar", limit=None)]:
+        problems.append("grep-binary-heuristic: an upstream -a cancelled the reminder for "
+                        "a downstream grep that has no text-mode flag")
+    if "grep-binary-heuristic" in [h for h, _ in matches("git grep -a foo | grep -a bar", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although every grep stage carries "
+                        "its own text-mode flag")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep -- -a payload", limit=None)]:
+        problems.append("grep-binary-heuristic: '-a' AFTER the -- marker is the pattern "
+                        "operand, not a flag, and the reminder was suppressed")
+    if "grep-binary-heuristic" in [h for h, _ in matches("grep -a -- pattern file.md", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although -a precedes the -- marker")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep -e -a payload", limit=None)]:
+        problems.append("grep-binary-heuristic: '-a' as the ARGUMENT of -e is the pattern, "
+                        "not text mode, and the reminder was suppressed")
+    if "grep-binary-heuristic" in [h for h, _ in matches("grep -a -e pattern file.md", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although -a stands alone before -e")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep -f -a payload", limit=None)]:
+        problems.append("grep-binary-heuristic: '-a' as the ARGUMENT of -f is a pattern "
+                        "file, not text mode, and the reminder was suppressed")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep 'foo -a bar' payload", limit=None)]:
+        problems.append("grep-binary-heuristic: a text-mode spelling INSIDE a quoted "
+                        "pattern is pattern content, and the reminder was suppressed")
+    if "grep-binary-heuristic" in [h for h, _ in matches("grep -a 'foo bar' payload", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although -a stands outside the "
+                        "quoted pattern")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep 'grep -a;foo' payload", limit=None)]:
+        problems.append("grep-binary-heuristic: a separator inside a quoted pattern "
+                        "manufactured a pseudo-stage whose -a suppressed the reminder")
+    if "grep-binary-heuristic" in [h for h, _ in matches("grep -a 'x;y' payload", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although the real stage carries -a "
+                        "and the separator is only pattern content")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches('echo "`grep needle payload`" | grep -a foo', limit=None)]:
+        problems.append("grep-binary-heuristic: a LEGACY backtick substitution's grep lost "
+                        "its reminder to the outer stage's -a")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches('echo "`grep needle payload`"', limit=None)]:
+        problems.append("grep-binary-heuristic: a grep whose ONLY appearance is a lifted "
+                        "substitution never triggered")
+    if "grep-binary-heuristic" in [h for h, _ in
+                                   matches("grep -a needle payload # note", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although the real invocation "
+                        "carries -a and only the comment follows")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches("grep needle payload # use -a next time", limit=None)]:
+        problems.append("grep-binary-heuristic: advice in a trailing comment exempted a "
+                        "grep bash never passes it to")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches("FILTER='two words' grep needle payload", limit=None)]:
+        problems.append("grep-binary-heuristic: a quoted assignment value hid the command "
+                        "word from the trigger")
+    for argcmd in ("echo grep needle", "command -v grep"):
+        if "grep-binary-heuristic" in [h for h, _ in matches(argcmd, limit=None)]:
+            problems.append(f"grep-binary-heuristic: fired although grep is an ARGUMENT, "
+                            f"not the stage's command word ({argcmd!r})")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches("if ! grep -q needle payload; then echo none; fi",
+                                               limit=None)]:
+        problems.append("grep-binary-heuristic: reserved words and negation before the "
+                        "command word suppressed the reminder")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches("/usr/bin/grep needle payload", limit=None)]:
+        problems.append("grep-binary-heuristic: a path-prefixed grep is still grep, and "
+                        "the reminder was suppressed")
+    for bundled in ("grep -qa needle payload", "grep -aH needle payload",
+                    "cat payload | grep -qa needle"):
+        if "grep-binary-heuristic" in [h for h, _ in matches(bundled, limit=None)]:
+            problems.append(f"grep-binary-heuristic: fired although a bundled short "
+                            f"option enables text mode ({bundled!r})")
+    for consumed in ("grep -ea payload", "grep -fa payload"):
+        if "grep-binary-heuristic" not in [h for h, _ in matches(consumed, limit=None)]:
+            problems.append(f"grep-binary-heuristic: an 'a' consumed as an option "
+                            f"ARGUMENT read as text mode ({consumed!r})")
+    for grouped in ("(grep needle payload)", "if (grep needle payload); then echo found; fi"):
+        if "grep-binary-heuristic" not in [h for h, _ in matches(grouped, limit=None)]:
+            problems.append(f"grep-binary-heuristic: a subshell-grouped grep lost its "
+                            f"reminder to the opening paren ({grouped!r})")
+    for qop in ('grep -e "needle" -a file', 'grep -f "patterns.txt" -a file'):
+        if "grep-binary-heuristic" in [h for h, _ in matches(qop, limit=None)]:
+            problems.append(f"grep-binary-heuristic: fired although -a stands after a "
+                            f"QUOTED pattern operand — blanking ate the token boundary "
+                            f"({qop!r})")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches('grep -e "needle" file', limit=None)]:
+        problems.append("grep-binary-heuristic: a quoted pattern operand with no "
+                        "text-mode flag was read as exempt")
+    for bf in ("grep --binary-files=text needle payload",
+               "grep --binary-files text needle payload"):
+        if "grep-binary-heuristic" in [h for h, _ in matches(bf, limit=None)]:
+            problems.append(f"grep-binary-heuristic: fired although --binary-files "
+                            f"selects text handling ({bf!r})")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches("grep --binary-files without-match needle payload",
+                                               limit=None)]:
+        problems.append("grep-binary-heuristic: a non-text --binary-files TYPE was "
+                        "read as text mode")
+    if "grep-binary-heuristic" in [h for h, _ in matches("(grep -a needle payload)", limit=None)]:
+        problems.append("grep-binary-heuristic: fired although the subshell-grouped "
+                        "grep carries its own text-mode flag")
+    for envcmd in ("LC_ALL=C grep needle payload", "cat payload | LC_ALL=C grep needle"):
+        if "grep-binary-heuristic" not in [h for h, _ in matches(envcmd, limit=None)]:
+            problems.append(f"grep-binary-heuristic: an env-assignment prefix hid the "
+                            f"command word ({envcmd!r})")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches('echo "$(grep needle payload)" | grep -a foo', limit=None)]:
+        problems.append("grep-binary-heuristic: a grep inside a command substitution lost "
+                        "its reminder to the outer stage's -a")
+    if "grep-binary-heuristic" in [h for h, _ in
+                                   matches('echo "$(grep -a needle payload)" | grep -a foo', limit=None)]:
+        problems.append("grep-binary-heuristic: fired although every invocation, nested "
+                        "included, carries its own text-mode flag")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep -a foo a & grep bar b", limit=None)]:
+        problems.append("grep-binary-heuristic: a background-joined second grep with no "
+                        "text-mode flag lost its reminder to the first stage's -a")
+    if "grep-binary-heuristic" not in [h for h, _ in matches("grep -a foo a\ngrep bar b", limit=None)]:
+        problems.append("grep-binary-heuristic: a newline-joined second grep with no "
+                        "text-mode flag lost its reminder to the first stage's -a")
+    if "grep-binary-heuristic" not in [h for h, _ in
+                                       matches('grep "foo \\" -a bar" payload', limit=None)]:
+        problems.append("grep-binary-heuristic: an escaped quote inside the pattern closed "
+                        "the blanking early and the embedded -a read as a flag")
+    uncovered = [n for n, _rx, _m, _a in RULES if n not in FIXTURES]
+    if uncovered:
+        problems.append(f"rules with no fixture, so nothing proves they fire: {uncovered}")
+    for name, _rx, _msg, _anchor in RULES:
+        cmd = FIXTURES.get(name)
+        if cmd is None:
+            continue
+        if name not in [hit for hit, _ in matches(cmd, limit=None)]:
+            problems.append(f"{name}: its own fixture {cmd!r} does not reach it — the rule is inert")
+
+    # -- half 2: the Codex fallback. SURFACES.md admits a hook rule only with a guide
+    # counterpart, because the guide is what the other host receives.
+    for tree in ("claude", "codex"):
+        g = repo / tree / "guides" / "tooling-gotchas.md"
+        if not g.is_file():
+            problems.append(f"{tree}/guides/tooling-gotchas.md missing — no fallback to check")
+            continue
+        body = g.read_text(encoding="utf-8")
+        for name, _rx, _msg, anchor in RULES:
+            if anchor not in body:
+                problems.append(f"{name}: anchor {anchor!r} absent from {tree}/guides/tooling-gotchas.md")
+
+    for p in problems:
+        print(f"self-test [FAIL] {p}")
+    if problems:
+        print(f"HOOK SELF-TEST FAIL: {len(problems)} problem(s)")
+        return 1
+    print(f"HOOK SELF-TEST OK: {len(RULES)} rules each fire on their own fixture, stay quiet "
+          f"when they should, and each has its guide counterpart on both hosts")
+    return 0
+
+
 if __name__ == "__main__":
+    if "--self-test" in sys.argv[1:]:
+        sys.exit(self_test())
     sys.exit(main())