"Every muxa reply names the mechanism" is overbroad in CLAUDE.md and decisions.md

open   by a73x

Labels: backlog

CLAUDE.md's muxa invariants include:

    Every `muxa` reply names the `mechanism` that answered it.

The code is narrower. `{"sent":true}` (src/muxa.zig:1210) carries no
mechanism; neither does `{"reason":"session_ended","exit_code":N}`, nor
the house `{"error":...,"detail":...}` shape. Mechanism accompanies
replies whose `exit_code` needs interpreting — which is the rule
docs/decisions.md:3131 is actually arguing for when it says "Only
`mechanism == "marks"` carries a trustworthy exit code, which is why
every reply names its mechanism".

So both documents carry the overbroad phrasing and the code is the
narrow one. An agent author reading CLAUDE.md literally would expect a
field that is not there.

Found by the 2026-08-23 drift review. Not fixed there because CLAUDE.md
is the user's instruction file, not something a review pass should edit.

If taken: narrow the wording in both CLAUDE.md and decisions.md:3131 to
scope the rule to replies carrying an exit code.

Comments

2026-08-29: still true. CLAUDE.md:123 'Every mux a reply names the mechanism'; the code is src/cli/muxa.zig now. Fix is the wording in CLAUDE.md and decisions.md, scoped to replies that carry an exit code.