docs: runbook: sanitizer-rules, how to change a sanitizer rule

Co-Authored-By: ornith-1.5-35b-a3b <agent@wntrmute.dev>

docs/implementer-log.md

@@ -6,6 +6,7 @@ reviewer adds findings under "Reviews" once per milestone.
 
 | Task | Date | Status | Gate runs | First gate | Deviations | Notes | Model |
 |---|---|---|---|---|---|---|---|
+| M5b/14-runbook-sanitizer-rules | 2026-09-27 | done | 1 | pass | none | Only `docs/runbook.md` changed. R1 in `memory-write-refused` under **Fix.**: the two-line sentence about narrowing the rule replaced with the same sentence pointing at [`sanitizer-rules`](#sanitizer-rules) instead of "the M5b spec's section 6.5". R2 in `memory-write-flagged` under **Fix.**: the two-line "narrow it as the M5b spec's section 6.5 says" replaced with the same sentence pointing at [`sanitizer-rules`](#sanitizer-rules). Verified before appending: `grep -c "section 6.5"` printed 0. Appended `docs/plans/M5b/files/runbook-sanitizer-rules.md` verbatim with `{ echo; cat ... } >> docs/runbook.md`; `grep -c '^## sanitizer-rules$'` printed 1 and `grep -c '(#sanitizer-rules)'` printed 2. `cargo fmt --all`; `make gate` printed `gate: ok` with 1118 tests (1117 in `cargo test --workspace`, plus the ignored `end_to_end` the gate runs). No code, so `Cargo.lock` unchanged. | ornith-1.5-35b-a3b |
 | M5b/13-instance-lock-rest | 2026-09-27 | done | 2 | pass | none | Made the other three daemons take the instance lock, `bxcore::instance` (task 12), the same way `loopd` and `inferproxy` do: before they touch their sockets each locks `<home>/run/<role>.lock` and holds it until the process ends. Copied the three new `instance.rs` tests and a new version of `crates/brokerd/tests/serve.rs` (the old second-instance test was gone) from `docs/plans/M5b/files/`. Step 2 showed exactly the named failures: brokerd `instance` failed on `the lock's line, and nothing else` (the second stopped at the audit lock with `brokerd is already running`) and `the lock file, mode 0600` (None vs Some(384)); `serve` 8 passed; memoryd and gatewayd `instance` each failed the same two shapes, each about 10 s. Made the edits exactly as the task gives: B1 the `use bxcore::instance;` import in brokerd main.rs, B2 the lock after the config loads and before `serve::start`; D1 the import in memoryd main.rs, D2 the lock after the config loads and before `serve::start`; G1 the combined `use bxcore::{instance, secrets};` import in gatewayd main.rs, G2 the `3b.` comment in `serve`, G3 the lock after the secret is read and before the state directory is made. `let _instance` binds each `InstanceLock` so it is not dropped at once. `cargo check` clean for each daemon; brokerd `instance` 2 / `serve` 8, memoryd `instance` 2, gatewayd `instance` 2 / `main` 5 pass. `grep -rn 'instance::lock(' crates/*/src` prints exactly five lines, one in each of brokerd, gatewayd, inferproxy, loopd, memoryd; `grep -rn 'runbook.md#already-running' crates/*/src` prints one line in bxcore; `git diff --stat -- crates/bxcore '*Cargo.toml'` prints nothing. `cargo fmt --all`; `make gate` printed `gate: ok` with 1118 tests (1113 before, minus 1 in the new brokerd `serve.rs`, plus 2 in each of the three new `instance.rs`). No new dependency, so `Cargo.lock` is unchanged. | ornith-1.5-35b-a3b |
 | M5b/12-instance-lock | 2026-09-27 | done | 1 | pass | none | Wrote the lock that keeps a daemon to one instance (M5b spec, section 9a) and made `loopd` and `inferproxy` take it. Step 2 showed exactly the named failures: the bxcore test did not compile (one E0432 `unresolved import bxcore::instance`); the loopd test failed its 3 tests (`a_second_loopd_on_the_same_home_is_refused...` left None right Some(1) because the second copy started and served, `after_the_first_is_killed_a_new_loopd_removes_the_stale_socket_and_serves` the lock file mode None vs Some(384), `a_run_directory_that_cannot_be_written_stops_loopd_naming_the_error` ran its self-test and failed later on the socket directory); the inferproxy test failed the same three shapes (`the second inferproxy...` left None right Some(1), `the lock file, beside the socket` None vs Some(384), `wanted the line` for the read-only directory). Copied the skeleton `crates/bxcore/src/instance.rs` (fill 2 functions) and the tests `bxcore/tests/instance.rs`, `loopd/tests/instance.rs`, `inferproxy/tests/instance.rs` from `docs/plans/M5b/files/`; appended `runbook-already-running.md` to `docs/runbook.md`. Made the edits in order: L1 the doc comment naming `instance` in lib.rs; L2 `pub mod instance;` after `pub mod ids;`. Filled `LockError::line` (a `match` on `self`, each arm `format!` with the path shown via `path.display()` and `{RUNBOOK}` inline) then `lock` (make the parent dir 0700 when `path.parent()` is `Some`, open the file 0600 with `create(true).truncate(false)`, `try_lock()` mapping `WouldBlock` to `Held` and other errors to `Io`). `cargo check -p bxcore` clean; `instance` 8 passed. M1 the `use bxcore::instance;` import in loopd main.rs; M2 the lock in `run_serve` after the config loads and before the socket is removed and the self-test, bound to `_instance`. `cargo check -p loopd` clean; loopd `instance` 3 passed. P1 the `use bxcore::instance;` import in inferproxy main.rs; P2 the lock beside the `--listen` socket (`<socket>.lock`) after the args are parsed and before the stale socket is removed, bound to `_instance`. `cargo check -p inferproxy` clean; inferproxy `instance` 3 passed. `cargo fmt --all`; `make gate` printed `gate: ok` with 1113 tests (1112 in `cargo test --workspace`, plus the gate's separate loopd `end_to_end` ignored test). `grep -rn 'runbook.md#already-running' crates/*/src` prints exactly one line, the `RUNBOOK` constant; `grep -c '^## already-running$' docs/runbook.md` printed 1; `git diff --stat -- '*Cargo.toml'` printed nothing. No new dependency, so `Cargo.lock` is unchanged. | ornith-1.5-35b-a3b |
 | M5b/11-bxctl-sanitize-check | 2026-09-27 | done | 1 | pass | none | Copied the skeleton `crates/bxctl/src/sanitize.rs` and the tests `crates/bxctl/tests/sanitize_check.rs`, `crates/bxctl/tests/sanitize_report.rs` from `docs/plans/M5b/files/`. Step 2 showed exactly the named failures: `sanitize_report` failed to compile (one E0432 `unresolved import bxctl::sanitize`, two E0599 `no variant named SanitizeCheck`) and `sanitize_check` failed its 8 tests (each run printed the usage text and exited 2 where 0 or 1 was wanted). Made the edits in order: L1 `pub mod sanitize;` between `memory` and `verify` in lib.rs; C1 appended the `bxctl sanitize check` USAGE block (the memory line lost its closing `";`); C2 the `SanitizeCheck { text: Option<String> }` variant after `Memory`; C3 the `"sanitize" => crate::sanitize::parse_sanitize(rest)` arm in `parse`; M1 `Read` added to the `use std::io` list; M2 the `Command::SanitizeCheck { text }` arm in `main`; M3 the `cmd_sanitize_check` function (argument or stdin read to a String, `bxctl::sanitize::run`, Ok(false)->0 / Ok(true)->1 / Err->2). Filled the five functions in the given order, each from its comment and `cargo check` after: `parse_sanitize` (one `match` with slice patterns and `check == "check"` guards, `[check]` -> `text: None`, `[check, text]` -> `Some(text.clone())`, else `UsageError`); `code_point` (`text.get(at..).and_then(|rest| rest.chars().next())`, `format!("U+{:04X}", u32::from(c))` or `"…"`); `token` (`TAGS.iter().find` the first tag the rest starts with, `format!("token {}", tag.id)` or `"…"`); `prefix` (`PREFIXES.iter().find` the first the rest starts with, `.copied().unwrap_or_default()`); `tag_count` (`TAGS.iter().map(|tag| text.matches(tag.text).count()).sum()`). `cargo fmt --all`; `cargo check -p bxctl` clean; `sanitize_report` 10 passed, `sanitize_check` 8 passed, every bxctl suite passes. `git diff --stat -- crates/bxcore '*Cargo.toml'` prints nothing. `make gate` printed `gate: ok` with 1099 tests (1081 before this task, plus 8 in `sanitize_check.rs` and 10 in `sanitize_report.rs`); `cargo test --workspace` reports 1098 passed plus the gate's separate loopd `end_to_end` ignored test = 1099. No new dependency, so `Cargo.lock` is unchanged. | ornith-1.5-35b-a3b |

docs/runbook.md

@@ -672,8 +672,8 @@ standard input) names each rule that fires and writes nothing. The session's log
 arguments.
 
 **Fix.** A real secret: rotate it, since it has been in the conversation; keep it out of memory.
-Ordinary text refused by mistake: add it to the code-work corpus and narrow the rule, as the M5b
+Ordinary text refused by mistake: add it to the code-work corpus and narrow the rule, as
-spec's section 6.5 says; the change reaches the agent when it is rebuilt.
+[`sanitizer-rules`](#sanitizer-rules) says; the change reaches the agent when it is rebuilt.
 
 **Check.** `bxctl sanitize check` with the text prints nothing and exits 0, and the agent's next
 write of it is answered `… updated` or `saved in notes.md`.
@@ -703,8 +703,8 @@ write is not staged: it is a note at once. The log names the rule, never the tex
 reaches the prompt. If it is a true fact wrongly flagged, move it into identity by hand: add it to
 `<home>/memory/memory.md` (or `user.md`) with an editor, as an entry of its own, with a line
 holding only `§` between it and the entry before, keeping the file within its limit. The note
-stays in `notes.md`, which is append-only. If the rule catches ordinary text, narrow it as the M5b
+stays in `notes.md`, which is append-only. If the rule catches ordinary text, narrow it as
-spec's section 6.5 says.
+[`sanitizer-rules`](#sanitizer-rules) says.
 
 **Check.** Start a new conversation and ask the agent what `memory.md` holds; the entry is there.
 
@@ -830,3 +830,45 @@ does no harm, and does not help either.
 **Check.** `pgrep -x <role>` prints one process id, and the daemon prints its start line
 (`loopd: serving on …`, `inferproxy: <socket> -> <upstream>`, `brokerd: serving tools on …`,
 `memoryd: serving`, `gatewayd: connected to …`).
+
+## sanitizer-rules
+
+**What you see.** Not a failure: the procedure for changing a sanitizer rule, which the entries
+`memory-write-refused` and `memory-write-flagged` send you to when a rule catches ordinary text,
+or which you follow when an attack gets through. The rules are in `crates/bxcore/src/sanitize/`:
+`refuse.rs` (6.1 of the M5b spec), `tags.rs` (the chat-template tags that are neutralised, 6.2)
+and `flag.rs` with `normalise.rs` (6.3).
+
+**Why.** The rules are compiled in rather than read from a file, so that every change passes the
+two corpora and review, and a typo cannot switch a rule off (M5b spec, section 6.5). A rule that
+refuses code is as much a bug as one that lets an attack through: the agent works on code
+projects, and a flagged note makes every session that recalls it untrusted.
+
+**Confirm.** The evidence, before anything changes:
+
+- a rule's name in `bxctl memory log` (`flagged <rule>`), in `memoryd`'s log, or in a refusal the
+  agent passed on;
+- `bxctl sanitize check` with the text, which names each rule that fires and writes nothing;
+- a device check, a review or new research that shows an attack the rules miss.
+
+**Fix.** In this order, one commit:
+
+1. **The case first.** Add the text to a corpus, with a comment saying where it was seen: the
+   attack corpus if it must be caught, the code-work corpus if it must pass. The corpora are the
+   given tests `crates/bxcore/tests/sanitize_refuse_corpus.rs` (refuse),
+   `sanitize_corpus.rs` (neutralise) and `sanitize_flag_corpus.rs` (flag). Build a tag or a key
+   from pieces, as the files already do: never write one whole. Run `cargo test -p bxcore` and see
+   the new case fail.
+2. **The rule.** Add or narrow the entry in the rule's table, with a comment naming its source.
+   Keep it as narrow as the evidence: a flag rule ported from Hermes keeps its attribution.
+3. **The gate.** `make gate` runs both corpora for every action, so a rule that catches code
+   fails before it lands.
+4. **The record.** A policy change (a new kind of refusal, or a rule moved from flag to refuse)
+   gets a row in `docs/decisions.md`; an ordinary rule change is its commit.
+
+A change reaches an agent when it is rebuilt and restarted. Stored memory is never rewritten: an
+identity entry that breaks a new refuse rule leaves the memory block at once (see
+`memory-entry-excluded`), and a note flagged under an old rule stays as it was written.
+
+**Check.** `bxctl sanitize check` with the text gives the new answer (nothing, and exit 0, for a
+text that must pass). After the rebuild, the agent's next write of it is answered as expected.