The UI role carried three standard outlines: IEC 62366-1 for medical
device usability, ISO 9241 for ergonomics, WCAG for accessibility. All
three are built around touch target size, colour contrast and multimodal
feedback. This screen is 160x160, monochrome, and navigated by keys, so
none of the three premises exists. Reading those sections could only lead
to the wrong conclusions.
Kept the three things that actually transfer, in their own section
instead: state needs a second encoding beyond position because 1bpp has
no colour channel at all; contrast here is nothing but ink versus
ground; and alarm priority has to survive in the layout because it is not
carried visually.
The role README still advertised the removed standards, so it now states
what applies to this screen and says explicitly that the generic
standards were removed as inapplicable. That keeps the summary and the
role file from disagreeing.
Also renamed the part heading from general knowledge plus industry
standards to general knowledge plus this screen's constraints, since the
standards are no longer there.
The UI role stated the content-page golden-reference count twice and
disagreed with itself: 66 in one line, 74 in another, 76 on disk. The
skill file repeated the 74. The font charset line had drifted the same
way, from 224 characters to 230.
Counts like these go stale the moment a page is added or a character is
set, so the file should not carry them at all. Both places now say to
read the number from the gate that prints it: check_content_pages.py
reports the frame count, check_font_charset.py reports the charset size,
and ui_font_cn_12.c carries the glyph list.
A role file that contradicts itself is worse than one with a gap,
because the reader cannot tell which number to trust and has to go
measure, which is exactly what the number was supposed to save.
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.
The BOM gate claimed to stop BOMs from being stripped, but it only ever
inspected files that were already tracked AND already had a BOM. A new
file under a BOM-listed directory could be born without one and never
be noticed, because the scan never returned it and, even if it had, the
"no HEAD version" branch skipped it. Editing a listed file and losing
its BOM is a real accident that already happened once; creating one
without a BOM was the same accident with no safety net at all.
Measured before and after on the same untracked file with no BOM:
before: checked 101 files, no drift, exit 0
after: FAIL, names the file, exit 1
The count of 101 was itself the symptom: with one more file present the
honest number is 102. The old code was not "silently passing a clean
tree", it was not looking.
The scan now includes untracked files, and a listed file with no HEAD
version must carry a BOM. Files that are tracked without a BOM keep
their historical pass so this does not flood existing code with
failures; instead the two that were listed but had no BOM were given one
so the list means what it says.
That exposed a conflict nobody had hit yet. The font file is generated,
and the generator rewrites it from scratch on every run, so a hand-added
BOM survived until the next regeneration and then vanished. The BOM gate
and the generated-fresh gate could not both pass. The generator now puts
the BOM back as its last step, idempotently, so the two gates agree and
the whole UI directory keeps its uniform encoding. Font content is
untouched: everything after the first three bytes is byte-identical.
The menu generator gains a real read-only mode. It previously had no
options at all and always rewrote its outputs; the arrows it printed
were accurate. That made it easy to mistake for a checker, since an
unchanged tree produces identical bytes and looks untouched. --check now
reports up to date or stale without writing anything, and the
registration tables are checked the same way. Default behaviour and
output are unchanged.
The telemetry page header no longer restates the board's input hardware
facts. They live in the IOBOARD README, which is where the board's
electrical behaviour belongs; the page keeps only what it alone can say:
that the output rows show the shadow register rather than contact
feedback, why an invalid sample draws -- instead of 分, and that these
twelve rows are not in the point table. One fact, one place.
The team rule for experiments now requires the file hash, the located
line number, and both runs. A report once cited a line number that did
not exist in the final file, which left no way to confirm which version
had actually been tested.
A rule can describe an action and still be unusable when the action's
input has no source. That is what happened here: the acceptance-side
rules were amended three times before the wording could be executed.
Add rule one, item four: a checker must print the denominator, that is
how many objects it was supposed to verify, and silence is not a pass.
The rule carries both halves:
- output side: list every object name together with its verdict,
never a bare aggregate OK
- checking side: write down the expected object list first, count how
many distinct objects appear in the output, then reconcile the two
The object list may only come from the task description or from the
dispatcher. It must never be derived from the checker's own output,
because a derived list always agrees with that output and the check
can then never turn red. A report whose object list is absent or has
no traceable origin is treated as coverage unverified, not as passed.
Task description gains a fifth required item, the expected object list.
A dispatcher who omits it has not defined the denominator, and the
executor must ask instead of guessing. write_scopes and any list of
files an executor happened to touch are action ranges, not object
lists; the two sets may be entirely disjoint.
Recorded with the measured contrast that motivated it: the same
checker with the list taken from its own output passes both when one
side is injected and when both are; with the list fixed by the task
description it fails as soon as one object is missing.
The reference case is a self-check script over two role files that was
only ever fed a bad sample for one of them. It reported two failures
instead of four and nobody noticed, because the count itself carries
no information about how many objects were covered.
Wording only where the subject changed; no rule bodies from the two
earlier rounds were rewritten.
The acceptance stage has no stage above it. An executor's work is
reviewed by a reviewer, but the reviewer's own conclusion is never
reviewed. These rules close that gap: they do not raise the bar, they
make the reviewer state how much its own conclusion can be trusted.
Three rules go under a new subsection of the acceptance section in
lead-orchestrator.md, and a condensed action version goes into
code-reviewer.md, because that file is the persona injected into
reviewer teammates while lead-orchestrator.md is not.
Rule one: before rejecting, run your own check on an input known to be
good. A check that only ever turns green is not a check. When you can
only afford one direction, test the one that should turn red. Building
a counter-example has three cost tiers, cheapest first: replay a
recorded failure, change one byte, or construct a case from scratch.
For the first tier the sample must itself be known good and its defect
already located, otherwise you are validating your check against a
guess.
Rule two: write every technical claim in a task brief as unverified, and
say so, so that the executor checks it rather than trusting it. This
upgrades an earlier note that merely allowed the Lead to invite
pushback into a default shape for every brief.
Rule three: copy out every proper name and every number in the text
under review and check each one individually. The list must also cover
your own check and its inputs, because a check that is wrong is the one
thing you will not think to check.
Separately, a table in the acceptance section now requires the evidence
behind any conclusion to be labelled: static, build, runtime that the
reviewer can rerun, or runtime that needs the board. A conclusion the
reviewer cannot reproduce stays marked as unverified.
Everything here came out of two rounds of review that went wrong in the
same way. Both times an error was written into an accepted document and
survived because nobody re-checked the source of the claim.
Verification:
- anti-pattern table still has 14 rows, all sections present
- rule boundaries differ between the two files; the cross-reference
therefore names the section rather than a rule number
- CRLF 0, no BOM, bom drift check passes
- doc link check reports the same 6 pre-existing issues, none here
- mojibake check passes
- the self-check script prints what it scanned and turns red when a
regression is injected
Add two rows to the anti-pattern table in lead-orchestrator.md, both
learned from the DI/DO board verification on 2026-11-16.
Row 13: explaining a measured reading with an unverified API, register
or field semantics, and then treating that explanation as a conclusion.
Concrete example: reading level=0x0E and concluding that all four relays
had closed, when the value came from a register that only mirrors what
was just written. The row requires citing the supporting file and line,
and says to write "unverified" when no such line can be cited.
Row 14: writing an expected reading into a task brief as fact. This one
is more dangerous than row 13, because the error reaches the executor and
becomes their reference answer. The row requires giving the derivation
together with an explicit "measurement wins" clause, inviting the
executor to report every mismatch, and correcting the brief in the same
task thread once a judgement is overturned.
Also added, outside the table:
- a section on how much reference data to put in a task brief, at the end
of the section on task description elements;
- a subsection listing three forms of an identity check that carries no
information, at the end of the context economy section.
Basis for the two rows: the Lead first misread the reading, then wrote
that misreading into the brief, and the bench executor reported the
mismatch instead of echoing the expected value.
Verification:
- anti-pattern table has 14 data rows, all three columns wide
- nothing in the file contains the string ZF as a register name
- the row 14 text is byte-identical to before the rework
- CRLF 0, BOM absent, bom drift check passes
- doc link check reports the same 6 pre-existing issues, none here
- mojibake check passes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.
What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.
New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
It also carries the full list of the twelve translation units that have
tightened it, plus the grep command that decides the truth if the list
and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
that was never actually written down anywhere: exit 2 does not simply
mean environment error, argparse also exits 2 and the wrapper script
was remapped so the two no longer collide.
Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.
Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
they describe what happened, not what is true now.
Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
The entry file had grown to 194 lines, of which a large part duplicated
knowledge that already lived in skills, docs or role files. Worse, three
pieces of project knowledge existed only there, and ten roles were all
module implementers or reviewers: no role carried the Lead side
collaboration protocol, so "Lead only orchestrates, never implements" and
"the reviewer must not be the implementer" had no home anywhere.
AGENTS.md 194 lines / 13908 B -> 121 lines / 12283 B, 13 sections -> 9.
- Dropped four sections whole, each with an existing landing point:
build and verify (keil-build / serial-boot-test skills), Python env
(new-machine-setup skill), hardware pins (hardware spec doc section 2),
docs and diagrams (writing standard plus draw-diagram skill).
- Compressed project overview, iron rules, pre-commit, platform
constraints and module conventions into pointers plus the few facts that
must be seen every turn.
- The directory map changes from "directory | responsibility | can I
modify it" to "directory | can I modify it" and hands the detail to the
architecture overview section 7. The value of this table on the entry
file is the permission semantics, not a second copy of the tree.
- Delegation policy is the one section that grows in substance: four
always-present rules, reviewer is not implementer, rework needs fresh
evidence, the gate flow, three measured limits of the ledger plugin and
member revive/rebind.
Three machine anchors are untouched: the TASK_TABLE comment pair and its
body, the BOM list line (one line, four paths, the bom-drift checker
concatenates every line containing BOM), and the hook count sentence.
Line endings stay CRLF.
New roles:
- .dsh/roles/lead-orchestrator.md: the Lead collaboration protocol in two
parts, generic methodology and this project's specifics. Twelve
anti-patterns with the case behind each, an eleven-role split table
(what it owns, what it must not touch, when to call it), and ten
documented gaps between what the entry file claimed and what
dsh-plugin-team-ledger v0.2.0 actually does.
- .dsh/roles/bench-runner.md: bench execution and evidence collection, an
execution layer and explicitly not a decision layer. It has no write
tools and no gate submit/accept, because the person who reads the log
must not also judge the run.
Existing roles:
- mcu-specialist gains the kernel-before-start rule, including the legal
counterexample vTaskDelete(testTaskHandle) in Src/freertos.c. The
criterion is not "create or delete" but whether the call waits for the
scheduler or for time.
- algo-specialist gains the RS-485 wiring gate with the two contract
defects it stands on: a weak rx hook with a single 256 byte buffer, and
a direction switch back to RX that does not wait for TC.
- storage-specialist's owner statement is rewritten rather than appended:
defaultTask owns the config engine because its static state is unlocked,
and reading still advances the poll baseline and the debounce counters.
- README: eleven roles, order unified across the overview table, the
detailed sections and the selection guide.
Verified: gen_task_table --check, bom drift, mojibake, generated fresh and
doc links all clean, and doc links report the same six pre-existing
findings as before this change. Role files are CRLF free, no BOM.