agent-bios 0.9.9 → 0.11.0

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

package/codex/AGENTS.md

@@ -52,57 +52,25 @@
 
 ## Concept Economy
 
-- Keep the concept graph compact by reusing existing concepts that clearly cover the behavior.
-- Treat lasting or shared names as concept candidates: features, entities, variables, types, helper modules, artifacts, config keys, CLI flags, MCP/tool fields, public response fields, artifact fields, enum values, failure kinds, retry/recovery tokens, process names, and documentation terms.
-- Before adding or changing a concept, find the nearest existing concept and choose one path explicitly: reuse, extend, rename, or split.
-- Prefer broad, stable concepts with precise properties over narrow near-duplicates.
+- When adding, changing, renaming, splitting, or exposing anything lasting or shared — a feature, entity, type, field, config key, CLI flag, enum value, failure kind, artifact, or documentation term — read and use `${CODEX_HOME:-$HOME/.codex}/guides/concept-economy.md` as a scoped extension of this section.
 - Before fixing a review finding or test failure, classify the fix as reducing, preserving, or increasing the active concept surface.
-- Split or promote a concept when it changes runtime behavior, ownership, lifecycle, validation, failure mode, user-visible behavior, audit/replay requirements, authority, persistence, user control, or failure handling.
-- Keep derived values as properties or projections of their source concept when tools/code can derive them from the source authority.
-- Keep internal projections and helper outputs internal unless public exposure is required for user behavior, product contract, or artifact truth.
-- Distinguish authority from visibility: public responses may expose bounded views, while the source concept or artifact remains the truth location.
-- Reuse existing enum values, failure kinds, retry/recovery tokens, and result/failure surfaces before introducing new vocabulary.
-- Use fallback paths, compatibility shims, and deprecated alias normalization when explicit migration compatibility is required.
-- Keep comments and active docs aligned with runtime behavior, failure semantics, retry policy, ownership, and authority.
-- When a split is necessary, name the parent concept, explain the reason for the split, and map aliases or variants back to the canonical concept.
-- In ontology work, check existing entities and relations first, then keep the concept graph compact.
-- In code work, follow existing naming patterns and consolidate variations introduced by the current change.
-- Let the repository's shape mirror its concept graph: keep each shared, lasting concept's canonical name traceable across the layers it appears in — path, module, type/interface, field, and public API — so the structure is navigable by name (grep-findable, path-guessable) without a translation table. This binds shared concepts only; transient locals, generic containers, and framework- or tooling-imposed layout may diverge.
 
 ## Coding Guidelines
 
 - For `.xlsx` editing, generation, reconciliation, validation, or connected spreadsheet processing, use the installed `spreadsheet-processing` skill when present — with plain tools/code as the fallback — and validate formula-dependent Excel results with the real Microsoft Excel engine.
-- For meaningful development work, read and use `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines.
+- For development work, read and use `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines — a change too narrow to need it is what its lightweight path decides, not a reason to skip the read.
 - For mock, fixture, fake, stub, simulated-provider, or test-realization design, read and use `${CODEX_HOME:-$HOME/.codex}/guides/mock-realization-boundary.md` as a scoped extension of these Coding Guidelines.
-- When the user asks to "설계" or design, read the coding-staged-workflow guide and focus on high-level design and implementation-process design; move to implementation only after the user asks to implement or approves the plan.
-- Think before coding: state key assumptions and surface ambiguity early.
-- Build the smallest viable functional path that satisfies the qualitative completion criteria. Minimum limits surface area, configuration, abstractions, optional scope, and implementation spread; it must not reduce required behavior, runtime authority, evidence quality, or verification depth.
-- Treat viability as real behavior against real inputs, real authority, and the intended runtime path. Use mocks only for tests, fixtures, or explicitly requested simulations; mock-backed paths support verification but do not count as product completion.
-- Make surgical changes. Touch only what the request requires, preserve existing style, and avoid casual adjacent refactors.
-- Clean up issues introduced by the current change. Mention unrelated dead code separately.
 - Own the full lifecycle of what you create — spawned processes and handles through teardown, artifacts out of tool-managed temp locations into a durable home — and keep differently-owned state separate: never colocate deploy-managed and user-owned data in one overwrite-managed file.
-- Define success criteria before multi-step coding work, then verify against them.
-- For bugs, prefer a reproducing test before the fix when practical.
-- Every changed line should trace back to the user's request.
-- Fix the root cause at its authority rather than the visible symptom: when downstream patches keep compensating for bad inputs, fix upstream at the source; when each fix only exposes another instance of the same defect, single-source the value and fix the whole class instead of patching instances.
 - Land risky or behavior-changing work behind a default-off path that preserves current behavior when off (proven by diff) and is enabled by an explicit opt-in, so the change stays reversible and the on/off difference is isolated. When a request would weaken a security or authority posture — removing or loosening an authentication/authorization check or access scope, or lowering a protective value such as session/token lifetime, password/crypto strength, rate limit, lockout threshold, or audit retention — treat it as a decision, not a rote edit, even when it is a one-line change and nothing in the code labels the value as security-relevant: state the consequence and at least one safer path to the real goal, and do not apply the weakening in the same turn — proceed only after the user confirms they accept the tradeoff.
 
 ## Verification Discipline
 
 - For composing a review request, packet, or reviewer role — the evidence bar, the verdict shape, and why a review returned noise, nothing, or a clean bill of health — read and use `${CODEX_HOME:-$HOME/.codex}/guides/review-request.md` as a scoped extension of this section.
 - After every meaningful code, ontology, config, data, spreadsheet, or documentation change, run a verification loop regardless of commit or handoff status.
-- Use static checks broadly: typecheck, lint, build, format, schema/config validation, graph validation, workbook structure checks, import boundaries, and security checks when available.
-- Add the narrowest reliable runtime or semantic test that proves the changed behavior, meaning, or contract.
-- Pick each domain's verification mix (code, ontology, config/data, spreadsheets, docs) from the Verification Menus in the coding-staged-workflow guide.
-- Let the LLM derive scenarios from the diff, user impact, concept impact, and failure modes; let tools/code execute and verify them. Where an artifact already defines the case space — a config, a schema, a route table — enumerate the cases from it rather than from judgment, and record real output as the expectation instead of typing one: a hand-listed set of cases silently stops covering as the artifact grows past it.
-- Keep E2E stable with deterministic data, resilient selectors, isolated external dependencies, and explicit waits.
+- For choosing verification depth, the per-domain mix, the case space, what makes a completion criterion falsifiable, how to keep an E2E stable, or what a green result is worth, read and use `${CODEX_HOME:-$HOME/.codex}/guides/verification-discipline.md` as a scoped extension of this section — its Verification Menus carry the per-domain mixes.
 - Report the checks run, results, and any unverified risk before calling the work done.
 - Trust a green check only when it traversed the actual changed code through the real dispatch and real calls (not a mock, dry-run, or bypass), and remember that "it ran" is not "quality met" — a fallback, floor, or mock run is not done; treat a zero-findings verdict as suspect until you confirm the harness ran rather than silently crashed, and make PASS mean concrete assertions on real output from the real path.
-- Make completion criteria falsifiable: prefer signals that fail when the mechanism is wrong (negative or contrast controls), and if no existing gate can judge a criterion, build the executable judge or do not claim the criterion met.
 - Before comparing two of anything (cost, performance, quality, frequency), fix a common basis — units, denominators, population, measurement surface — compare on equivalent output, and exclude or flag non-representative data (promotions, outages, smoke slices).
-- For non-trivial designs or high-risk changes, run independent adversarial review across distinct lenses, ideally on the design before implementation, and re-verify each finding against real code before acting on it. Apply the convergence heuristic by reviewer kind (detailed in the multi-model guide): same-kind convergence is high confidence but same-kind reviewers share blind spots — their shared "clean" is not verification; different-kind divergence is the expected signal — act on the union. Never accept an orchestrated workflow's self-reported all-green as sufficient; independently re-run the diff inspection and verification suite yourself.
-- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work; proportion assurance to the deployment context — a single-user, own-data tool does not warrant production-grade assurance; prefer delivery.
-- Trust a green / zero-findings verdict only if the check could have failed over a real, non-empty subject: assert the entity-under-test set has cardinality > 0 before any "no bad X" or "all X satisfy P" claim (an empty subject set passes vacuously and proves nothing), and for any test touching a branch you add or delete, confirm its inputs satisfy the live branch's entry guard — a copied fixture that fails the new guard silently routes into the about-to-be-deleted dead branch and stays green even after the real behavior breaks. When a check goes green unexpectedly fast or empty, dump what it actually ran over. Checker code itself must assert the expected shape and fail loud — a permissive fallback (`a || b`) inside a gate absorbs wrong assumptions and keeps passing.
 
 ## Tooling and Operational Safety
 
@@ -113,7 +81,6 @@
 - Never accept secrets through transcript- or history-logged channels.
 - When a secret must be supplied, provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
-- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
 ## Multi-Model Workflow
 
@@ -131,11 +98,7 @@
 ## Documentation Hygiene
 
 - Keep runtime code, active docs, and execution-facing docs focused on current behavior, current decisions, current contracts, current authority, and current failure handling.
-- Use comments for non-obvious current behavior, invariants, constraints, or risks that still apply.
-- Put backward-compatibility notes, deprecated behavior, migration rationale, historical alternatives, change narratives, and handoff logs in isolated documentation paths such as `docs/`, `design/`, `archive/`, or `deprecated/`.
-- Link from active docs or code to isolated notes only when the current task needs that history or the reference helps future maintainers.
-- Phrase guidelines as desired behavior and preferred patterns.
-- Prefer established docs such as `CHANGELOG.md`, `IMPLEMENTATION_MAP.html`, or handoff notes for change history and implementation context.
+- For where a comment, a compatibility note, deprecated behavior, a rejected alternative, a migration rationale, a change narrative, or a handoff log belongs — how to phrase a rule others will follow, and whether active docs should link to history — read and use `${CODEX_HOME:-$HOME/.codex}/guides/documentation-hygiene.md` as a scoped extension of this section.
 
 ## Visual Explanations
 

package/codex/guides/cli-multi-model-workflow.md

@@ -57,7 +57,7 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
 - Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
 - After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
 - Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
-- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
 - Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
@@ -127,9 +127,9 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 
 ## Dual-Provider Design Drafts
 
-- Trigger: the task is design (the staged-workflow guide's design stages) AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
+- Trigger: the task is design — high-level shape and implementation process, before any code — AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
 - Mechanics: compose ONE blind packet (evidence, constraints, rubric, neutral alternatives — the escalation-gate packet shape) and dispatch it unchanged to one frontier-tier model per provider; drafts stay independent — neither sees the other's output. Then adjudicate: compare the two dual-provider frontier design drafts against the rubric, take the winner as the skeleton, graft the loser's superior parts, and record what differed and why the synthesis chose as it did (FRONTIER disposition line).
-- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged-workflow design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
+- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
 
 ## Unattended Batch Safety
 
@@ -173,7 +173,7 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
 
-Binding (2026-07-25):
+Binding (2026-08-10):
 
 | Slot | Binding | Notes |
 |---|---|---|
@@ -181,13 +181,13 @@ Binding (2026-07-25):
 | HELM | Claude Opus 5 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
 | WORKHORSE | Claude Opus 5 (medium) · GPT-5.6 Terra (high) | implementation and per-item judgment |
 | SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
-| VERIFIER-A | onto-mcp review | logic/authority kind; tier units per funnel |
-| VERIFIER-B | `ultracode-for-codex` CLI v0.4.5 (Codex-backed; callable from Claude or Codex) | code/execution kind |
+| VERIFIER-A | plain `codex exec` deep pass — GPT-5.6 Sol at ultra effort, packet on stdin (`-c service_tier="fast"` as explicit fast opt-in) | strongest single reader; cross-family from a Claude main |
+| VERIFIER-B | Claude Code ultracode workflow (keyword-opened, many-agent) | code/execution kind; fan-out counterpart |
 | INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
 | Claude relocation | EnterWorktree, `/cd`, `--worktree`; resume is directory-scoped | verified 2.1.207 |
 | Codex relocation | `codex resume` (cwd-filtered; `--all` lifts), fork | verified 0.144.1 |
 | Claude teammate | named mailbox continuation; completed-agent message may cold-rerun on main model | keep resident; avoid completed resume |
-| Rate-limit fallback | OpenAI limited → VERIFIER-A on Anthropic; Claude limited → VERIFIER-B on Codex | record family collapse |
+| Rate-limit fallback | OpenAI limited → VERIFIER-B (Anthropic workflow); Claude limited → VERIFIER-A (Codex exec) | record family collapse |
 
 Codex direct-drive (verified 0.144.1, 2026-07-12):