clay-borg/evidence/CB-EV-0025-the-commentary-track.md

# CB-EV-0025 — the commentary track

CB-WP-0027 T05. Tier M (structural M — touches ADR-0007 D5's input
contract and the recorded-session format; chaos d8=7 → no override).
Declaration 10 of chaos window 2. Closed 2026-08-06.

**Delivered:** [ADR-0014](../decisions/ADR-0014-the-commentary-track.md),
a two-column page, a `/note` channel, `trials/<date>-<slug>.md`,
`tools/trials.py`, `make trials`, and `--trial` on `cb-play`.

---

## 1. The question this file cannot answer

**T05 asks whether a comment actually got written during play, by the
maintainer, unprompted.** It has not been asked yet, and **that is the
pass's real acceptance test, not any of the tests below.**

The protocol's own claim is that it must cost almost nothing or it will
not be done. Everything here is evidence that the mechanism *works*;
none of it is evidence that it *gets used*. I exercised it myself, which
proves the plumbing and proves nothing about the ergonomics — the person
who wrote the feature is the worst possible witness to whether it is
worth using.

**Stated plainly rather than answered optimistically**, because
CB-WP-0022 built a register whose first run found ten answers nobody had
collected: this project's failures are about whether things get *read*,
not whether they get *built*.

## 2. What ADR-0007 D5 turned out to be

The workplan expected D5 — *JavaScript may not construct commands* — to
be the hard part. It was the easy part, for a reason worth recording:

```rust
_ => return Err(format!("unrecognised field in pointer fact: {pair:?}")),
```

**`PointerFact::parse` refuses any unrecognised field**, so a comment
could not reach the command path even by accident. A parser that ignored
what it did not understand would have made this a real decision; one that
refuses made it a non-event.

**That is a control paying off two years of maintenance early**, and it is
the clearest instance in this project of strictness at a boundary being
cheaper than vigilance across one. D5 is **scoped, not amended**: the
command channel is untouched, and the note channel is a second one that
cannot become the first because `resolve` takes a `PointerFact` and
nothing converts a `Note` into one.

**The test asserts it anyway**, with a note whose text is a well-formed
pointer fact — because "the types don't connect" is a claim about code
layout until something checks the behaviour, and the inverse is asserted
too so the test is not vacuous.

## 3. Running it changed the design, again

`make trials`'s first version called **any note without a recording an
orphan**. A recording is only written when the game ends, so **every note
in a live session reported as broken.**

A metric that cries wolf is one nobody reads — **which is the exact
failure this pass exists to prevent**, reproduced inside the tool built to
prevent it. Now three states: `ok`, `pending` (no recording yet), `orphan`
(the recording exists and the position is not in it). Only the third has a
target of zero.

**This is the third pass running where building or running the thing found
something the design did not.** CB-WP-0024's `role` column, CB-WP-0025's
`K=2` infeasibility, and this. The pattern is consistent enough to state:
**the ADRs in this project are good at deciding and poor at predicting**,
and the loop's value comes disproportionately from the code loop rather
than from steps 1–3.

## 4. A latent defect surfaced by a name collision

`make trials` did nothing. `trials` is also a *directory*, so Make saw an
up-to-date file and ran the recipe not at all.

Checking `.PHONY` found that **`design`, `difficulty` and `trials` — added
by CB-WP-0022, CB-WP-0025 and this pass — were all missing from it.** Two
of them work by luck: no file happens to share their name.

**Three passes added a target and none added it to `.PHONY`**, which is a
process observation rather than a bug: the Makefile has no control that a
new target is declared, and the failure is silent until a name collides.
Not fixed beyond declaring the three, because a gate for this would cost
more than it catches — but it is the kind of thing that is invisible until
it is not.

## 5. What the escaping test found

`esc()` has escaped suit names since CB-WP-0012. This is the first
user-authored free text the renderer has handled, and the source comment
— *"cannot currently carry a `<`" is how injection bugs are written* — was
written in anticipation of exactly this.

It held. `<script>alert(1)</script>` renders escaped.

**The test asserts something the obvious version would miss:** that the
player's words are *still readable* afterwards. An escaper that dropped
the text would pass "no script tag in the output" while destroying the
note. Escaping that eats what someone wrote is its own defect, and only
the positive half of the assertion catches it.

## 6. Coverage cost of the reflow

**None.** All 41 pre-existing `cb-render-html` tests passed unchanged
through a full restructure of the document into two columns, including the
coverage gate that asserts every view field appears in the *parsed*
document.

**That is a stronger result than it looks.** The gate is coupled to
tokens, not to layout — so moving every element into new containers did
not disturb it. CB-WP-0024 saw the opposite when a probe was tied to a
rendering (`17 remaining`), and the contrast is the useful part: **a probe
that names a fact survives a reflow; a probe that names a presentation
does not.**

## 7. Chaos window 2

**Declaration 10 of 12.** Structural M, d8 = 7, no override.

**Twelve declarations, no 8 rolled**, so the window closes with **zero
overrides** and its retirement condition — *retire if an override changes
nothing twice running* — is untestable. CB-EV-0024 §6 said this; it is now
final rather than projected.

**The window's own verdict should be that d8 made the mechanism
unevaluable**, and that the choice was between a rate that produces
evidence and a rate that produces rarity. Window 1 at d4 produced two
overrides and both changed the outcome; window 2 at d8 produced none.

## 8. One flaky gate, reported rather than dismissed

`make all` failed once at `env-test` and passed on re-run with zero
failures. A `cb-play` server and several `cargo` processes were running
concurrently during the failing run, which is the likely cause — but
**"likely" is doing work in that sentence and I did not chase it.**

Recorded because a gate that fails intermittently and is re-run until
green is a gate being trained not to matter, and this project has enough
instances of that class already.

## Open after this pass

- **Nobody has used it yet** (§1). Until a note is written in anger, the
  ergonomic claim is unsupported.
- **Promotion is manual.** ADR-0014 D5 says a comment becomes a register
  note by a human's judgement, and T04 reports comments but does not
  offer a one-step promotion. That was in the workplan's controls and is
  the part not built.
- **The narrow-viewport rule is asserted on the stylesheet**, not on a
  layout. There is no browser in the test harness that can measure a
  reflow, and saying the assertion is weaker than the claim is the honest
  position.
- **The flaky `env-test`** (§8) has no explanation, only a plausible one.