From f2ef9d20229a4ba02796d3e3e330e30a533391b6 Mon Sep 17 00:00:00 2001 From: chaoz23 Date: Tue, 18 Aug 2026 20:57:20 -0700 Subject: [PATCH] docs: SKILL.md named the wrong stream for every envelope SKILL.md:37 told consuming agents "Failures print JSON on stderr, never a traceback." Every dmcheck envelope goes to stdout. stderr is empty. Verified across all three verdict paths, not just the failing one: clean session exit 0 stdout 894B stderr 0B findings exit 1 stdout 3867B stderr 0B unreadable input exit 2 stdout 423B stderr 0B bad flag exit 2 stdout 0B stderr 512B (argparse, no envelope) Mechanism: cli.py:74-77, _print_invalid uses print(). An agent that followed the file read stderr for the failure payload and found nothing -- an exit code with no envelope, indistinguishable from a crash. This broke the recovery path silently rather than degrading it. The replacement also disambiguates the exit-2 overload tracked in #15, since the probe made the rule obvious: exit 2 with an envelope on stdout is the honest lane; exit 2 with empty stdout is a malformed call. Detected as STREAM_MISMATCH by chaoz23/srdcheck's family conformance gate. Closes #13 Co-Authored-By: Claude Opus 5 --- SKILL.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/SKILL.md b/SKILL.md index 5fe2e7c..6a9cb75 100644 --- a/SKILL.md +++ b/SKILL.md @@ -33,8 +33,11 @@ deterministic: same transcript, same findings, every time. ## Exit codes ARE the verdict `0` = clean (silence) · `1` = findings · `2` = unusable input/charter (the -honest lane — fix the input, don't retry blind). Failures print JSON on -stderr, never a traceback. +honest lane — fix the input, don't retry blind). **Every envelope — clean, +findings, and the honest lane — prints JSON on `stdout`**, never a traceback. +`stderr` carries only argparse usage errors, which also exit 2 but emit no +JSON. So: exit 2 with an envelope on stdout is the honest lane; exit 2 with +empty stdout means the call was malformed — fix it and retry. Read stdout. ## Invocation