docs(ai-agents): assert_equals strips control chars, it does not trim

CHANGELOG.md

@@ -9,6 +9,7 @@
 - `bashunit doc <filter>` says `No assertion matches '<filter>'` instead of printing nothing, which was indistinguishable from a broken install. Mirrors the existing `--custom` wording; the exit code stays 0 because `doc` is informational (#1201)
 - `install.sh` destination errors no longer advise a `-d` flag that does not exist — the script takes positional arguments, so following the advice produced `Invalid arguments`. The one message whose job is to tell you how to recover pointed at a form the parser rejects (#1221)
 - The `example/` demo is covered by the suite. `docs/examples.md` and `example/README.md` send new users to `./bashunit example` as their first contact with the framework, and nothing ran it — `make test` collects from `tests/` only — so it could break while CI stayed green. The dead `EXAMPLE_TEST_SCRIPTS` variable, pointing at a file deleted several releases ago, is gone with it (#1219)
+- Docs: the drop-in agent rules described `assert_equals` as trimming or normalizing. It strips ANSI colour codes, tabs and newlines — not spaces, so `assert_equals "a" " a "` fails. That block is written to be pasted verbatim into an `AGENTS.md`, so the error propagated into every repo adopting it (#1225)
 - Docs: an empty entry in the `-e/--env/--boot` file assigns an empty value rather than restoring the built-in default, so blanking a boolean disables it; the guide said it "wipes" the value, which reads as a reset. The rest of the precedence ladder is now covered by tests (#1217)
 - Docs: the test-function name rule is stated correctly — the prefix is a literal, lowercase `test_`, so the guide's own `testRenderAllTestsPassedWhenNotFailedTests` example and its claim that names are case-insensitive were both wrong, and a function named either way is silently never run (#1215)
 - Docs: `assert_matches` runs `grep -E` in a subprocess per call — ~2.5ms against ~0.065ms for `assert_same`, about 38x — so hot loops matching a fixed substring should prefer `assert_contains`. The subprocess is required by the Bash 3.0 floor (#1187)

docs/ai-agents.md

@@ -108,7 +108,9 @@ actually make against this API:
 - Run one test: `bashunit --filter <function_name> tests/` — it matches the function
   name (`test_parses_the_header`), not the humanized title shown in the report, so a
   filter with spaces silently matches nothing. Run everything: `bashunit tests/`.
-- Prefer `assert_same` (exact) over `assert_equals` (which trims/normalizes).
+- Prefer `assert_same` (exact) over `assert_equals`, which strips ANSI colour codes,
+  tabs and newlines before comparing — useful for asserting on coloured CLI output,
+  misleading everywhere else. Neither trims spaces: `assert_equals "a" " a "` fails.
 - **Exit-code assertions take the code as the THIRD argument**, not the first:
   `assert_general_error "" "" "$exit_code"`. With no arguments at all they read `$?`.
 - Capture an exit code before asserting, or `set -e` will kill the test first:

tests/unit/assert/basic_test.sh

@@ -277,6 +277,25 @@ function test_assert_equals_distinguishes_a_backslash_from_an_escaped_one() {
     "$(assert_equals "$one" "$two")"
 }
 
+# What assert_equals ignores is control characters, not whitespace. The
+# drop-in rules in docs/ai-agents.md called it "trims/normalizes", which reads
+# as whitespace tolerance and is the one part of the docs written to be pasted
+# verbatim into an agent's rules file (#1225). Pin both sides of the boundary.
+function test_assert_equals_ignores_colour_but_not_spaces() {
+  local coloured
+  coloured="$(printf '\033[31mhello\033[0m')"
+
+  # Colour is stripped: this is the case assert_equals exists for.
+  assert_equals "hello" "$coloured"
+
+  # A space is not a control character, so it is compared like any other byte.
+  assert_same \
+    "$(bashunit::console_results::print_failed_test \
+      "Assert equals ignores colour but not spaces" \
+      "a" "but got " " a ")" \
+    "$(assert_equals "a" " a ")"
+}
+
 function test_assert_equals_distinguishes_an_escape_sequence_from_the_character() {
   local with_real_tab
   with_real_tab="$(printf 'a\tb')"