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

New issue

Open

opened 2026-08-23 10:28:59 +00:00 by a73x · 1 comment

a73x commented

2026-08-23 10:28:59 +00:00

(Migrated from git.a73x.sh)

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.

Migrated from git-collab issue 862ecafdcb519422d337691fa73d49ea35d33fe2.

Original author: a73x dev@a73x.sh.

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. --- Migrated from git-collab issue `862ecafdcb519422d337691fa73d49ea35d33fe2`. Original author: a73x <dev@a73x.sh>.

a73x commented

2026-08-29 12:30:05 +00:00

(Migrated from git.a73x.sh)

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.