Files
STM32F4-Base/.dsh
wandering1 8bd12c0aa8 docs(roles): record the traps the agents actually fell into
Each of these four role files was changed only where this session produced
evidence that the existing wording was not enough.

The MCU specialist had no clause at all saying a task brief is not a
source of fact, yet twice in this session it overrode a brief by checking
the code and was right both times. The new section states the two ways a
brief goes wrong (reading a function without reading its caller;
inventing a convention that conflicts with the repository's existing
ones) and the rule that matters: report the conflict, keep working on
whatever is not blocked, do not silently comply.

The reviewer role said "read only, do not modify" and stopped there.
Verification often needs a mutation test to prove an assertion can fail
at all, and the reviewer did exactly that by editing a tracked file in
place. Restored byte for byte, but the evidence chain had a gap while it
was in flight. The clause now says read-only does not mean unable to
verify, mutation tests happen on a copy, and git stash or git checkout of
a single file is forbidden because the tree may hold other people's
uncommitted work.

The UI role said BOM is stripped by Edit and must be put back. True but
too weak: it reads as one cleanup at the end, when every single edit
drops it. One agent measured four edits, four losses. Rewritten as put it
back N times for N edits, with the check right after each one, and with
what the failure actually looks like: eleven compiler errors pointing at
perfectly good Chinese lines, because ARMCC stops treating the file as
UTF-8 and the first multibyte line takes every diagnostic with it.

The lead role already said briefs are unverified until checked, but that
only holds the reading side. Added the writing side: before stating
something as fact, ask whether it was measured or inferred, and label it
accordingly. The real failure was a brief claiming a generator preserves
the input file, inferred from one branch inside a function while the
caller rewrote the file every run.

Only these four were touched. The algorithm-specialist role owns the
ui_data work landed in 2b466b85 (frame fields, feed, host tests) and has
real gaps of its own, but this pass did not cover it.
2026-11-17 00:08:47 +08:00
..