docs: the M5b review, and tips T45 to T48

The review of tasks 01 to 14 in the implementer log (task 14's row
renamed to its file's name), and four tips for writing tasks: what to
do with a skeleton's comments, golden files for scanners, naming the
log row, and running the implementer without plugins.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/implementer-lessons.md

@@ -82,6 +82,10 @@ How it is used:
 | T42 | Before hand-over, grep every earlier given file and fixture for anything the task changes (strings, sentences, JSON shapes, counts). | T19 is one case of it (M3a `strict.rs`); crossbar had five such breaks (Ornith guidance §5). M5a task 22 handled it by keeping `edit.rs-task06` and `serve.rs-task10`. |
 | T43 | Run the gate's own checks on the given files themselves (`cargo fmt --check`, the line limit, clippy on test targets) before hand-over. A given file that fails the gate stalls the run, and the implementer may not edit it. | M4a task 16: a given test copied into the plan before `cargo fmt` came back reformatted (T29); crossbar stalled on given files that failed its gate (Ornith guidance §5). |
 | T44 | Every path a given test creates (directory, socket, file) is removed by a guard that deletes it on drop, never by a line at the end of the test, which a failing test skips. A struct that holds a test's home declares it last, since fields drop in order, and a guard for a running server waits (with a limit) for it to stop before the home goes. Check before hand-over: run the gate and compare `/tmp` before and after. | 2026-09-26: about 10,000 leftovers in titan's `/tmp` from `loopd`, `bxctl`, `inferproxy`, `brokerd` and `toolkit` tests that never removed their paths, plus two `gatewayd` races (a `Running` that only signalled stop, and a home declared first). Fixed in `a15c428`; the gate now leaves nothing. |
+| T45 | Say what the implementer does with a skeleton's instruction comment when it fills the body: delete it and keep only the doc comment. Left unsaid, the implementer chooses, and chooses differently from task to task. | M5b: tasks 03 and 04 kept every instruction comment inside the filled bodies (28 lines in `refuse.rs` and `tags.rs`); task 05 removed them. The review deleted them. |
+| T46 | For a parser or scanner, give a golden file: the reference's output on a few thousand generated inputs, checked by a given test. Mutations show the given tests catch one-line breaks of the reference; they cannot show the tests pin every clause of every comment, and a scanner has more clauses than tests. | M5b task 10: Ornith's `url_len` ended a clean reply's URL at any `<` outside parentheses instead of the comment's rule; every given test, and all 71 of the reference's mutations' catchers, still passed. A random differential run against the reference found it in the review. |
+| T47 | Name the log row in the task ("the row's Task cell is `M5b/14-runbook`"). The driver checks the row by the file's name; the implementer takes it from the task's heading. | M5b task 14: the row was `M5b/14-runbook-sanitizer-rules`, from the heading "the runbook entry `sanitizer-rules`", and `run-plan.sh` stopped on a finished task. |
+| T48 | Run the implementer with no plugins and no borrowed rules: `opencode run --pure` and `OPENCODE_DISABLE_CLAUDE_CODE=1`. Global plugins load into every session, and a plugin that rewrites the system prompt forces a full re-read of the conversation on a model that cannot rewind its cache. | M5b run (2026-09-26): a short-term-memory plugin rewrote the system prompt every fourth request (a 35,633-token re-read in task 10), 22 plugin tools rode in every request (about 2,400 tokens), and in tasks 01 to 10 prompt reads of 10,000 tokens or more took 76 of 111 minutes of prompt processing: 42 of them, of which only about 11 were session starts (about 15,000 tokens each). Tasks 11 to 14, run after the plugins were removed, had 5 such reads (4 session starts), 4 minutes in all. |
 
 ## What worked and should be kept
 

docs/implementer-log.md

@@ -6,7 +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/14-runbook | 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 |
@@ -804,3 +804,38 @@ What was good: every task's code was exact. Task 16's session found a failure in
 touch, proved it happens without its change, committed only its log row and stopped, which is
 what the task asked. Tasks 17, 18, 20 and 22 passed the gate on the first run. The device check
 found the milestone's worst defect, which review, reference and tests had all missed.
+
+### M5b, tasks 01 to 14 — reviewed 2026-09-27 by the design model (Claude)
+
+Accepted, with fixes made in review (below). Tasks 01 to 14 by Ornith-1.5-35B-A3B on titan through
+`tools/run-plan.sh`, 2026-09-26 17:40 to 2026-09-27 17:57. Every edit the tasks gave whole, and
+every given test and fixture, is byte-identical to the reference (the bundle on straylight); the
+branch differs from it only in the nine files where Ornith filled bodies from comments, and there
+almost only in style. The device check (spec, section 13) is still to do.
+
+| Check | Result |
+|---|---|
+| 14 task commits, each with `Co-Authored-By: ornith-1.5-35b-a3b <agent@wntrmute.dev>` | pass |
+| Given tests and fixtures identical to the plan | pass |
+| Protected files | untouched; the manifest changes are task 02's (`secrets` feature, optional `zeroize`) |
+| `make gate` on titan (rustc 1.98.1) | `gate: ok`, 1118 tests at task 14, the count the plan gave; 1120 after the review's two tests |
+| Banned constructs in new library code | one index, `lines[at]` in `links::fence_end`, in range by its caller; replaced |
+| Random differential run of `links::disarm` against the reference | 100,000 generated replies, both modes: no image and no untrusted URL left outside code where the reference disarmed it; 261 of 40,001 outputs differed, from finding 1 and from equivalent orderings |
+
+| # | Severity | Owner | Finding | Fix |
+|---|---|---|---|---|
+| 1 | low | Ornith (task 10) | `links::url_len` ended a clean reply's URL at any `<` outside parentheses and before any `>`, not at a `<` before white space, a bracket, `<`, `>` or the end, as its comment says. No leak found: an image inside such a URL is wrapped with it. Every given test passed, as did the catchers of the reference's 71 mutations. | Review: the reference's body restored; `tests/links_review.rs`; tip T46 |
+| 2 | low | Ornith (task 10) | `links::closes` counted leading no-break spaces in characters and used the count as a byte offset, so a closer indented with one did not close its fence; the block was then read as prose (the safe way). | Review: the reference's body restored; `tests/links_review.rs` |
+| 3 | nit | Ornith (tasks 03, 04), plan | The instruction comments of the skeletons stayed inside the filled bodies (28 lines); task 05 removed its own. The tasks never said which. | Review: deleted; tip T45 |
+| 4 | nit | Ornith (task 11) | The `bxctl` usage text gained a space of indent on four lines. | Review: restored |
+| 5 | nit | Ornith (task 14), plan | The log row was named `M5b/14-runbook-sanitizer-rules`, from the task's heading, so `run-plan.sh` stopped on a finished task. | Row corrected; tip T47 |
+| 6 | nit | Ornith (task 10) | The row gives one gate run and a first pass; its notes say the first run failed on six clippy warnings. | Noted here |
+| 7 | medium | the run, not the code | Task 10 ran past the 90-minute limit, and `RESUME` resumes only a session that ended by itself, so the run stopped; the owner resumed it by hand. Global OpenCode plugins loaded into every session: one rewrote the system prompt every fourth request, forcing full re-reads (tasks 01 to 10: prompt reads of 10,000 tokens or more took 76 of 111 minutes of prompt processing). | Plugins removed (owner, 2026-09-27); tip T48; `run-plan.sh` to pass `--pure` and resume after the limit |
+| 8 | low | tests (M4b) | `brokerd`'s `a_torn_tail_is_recovered_and_it_serves` failed once under full load (task 07's first gate) and passed alone. | Open |
+| 9 | low | tests (M2b) | `loopd`'s `serve_refuses_to_start_when_the_self_test_fails` and `a_failed_self_test_names_its_entry` wait on the process with no deadline; a `serve` that skipped the self-test would hang the gate (found while writing task 08). | Open |
+
+What was good: Ornith copied every given file unchanged and made every exact edit as written, in
+fourteen tasks, one of them 23 edits long. It wrote 16 small helpers of a Markdown scanner from
+their comments; the one real slip (finding 1) is a rule the tests did not pin. Its own `Out::wrap`
+wrote the `\n` of a `\r\n` twice; it fixed that when the resume prompt named it. Task 07's session
+proved a failing `brokerd` test flaky before re-running the gate instead of changing it.