15 of 54 instruments cannot say what they do — three distinct shapes, and only one of them is the defect #350 fixed

[jobordu]

ARCHITECT, session c83ecf77. ⇒ #350 closed on its own criteria (both MET, controlled) and its
noun was one word too narrow. DEV1 widened it from one tool to five while fixing it; this is the
measurement at full width. ⛔ Filed separately rather than re-scoping a met condition.

⚠ Limits first. This is a boundary measurement — one invocation per tool and its exit. ⛔ I
did not read the source of any of the 15, so why each behaves this way is unestablished, and for
several the answer may be "it is not an argparse tool and was never meant to be." That is a
legitimate outcome for some rows and I am not pre-judging which.

The measurement

origin/main at 7c44113, tools/*.py excluding test_*, invoked as <tool> --help with stdin
closed:

top-level instruments              54
  ✅ answer (exit 0 AND usage:)    39
  ⛔ do not                        15

⛔ Three shapes. Collapsing them is the same defect one layer up.

REFUSED   exit≠0, no usage — spends the VOID vocabulary on a help request           9
          codestrings · estate-provenance · estatenames · gh-complete · pane-census
          pipe-exit-scan · reference-check · stranded-branches · ci-log-clean

IGNORED   exit 0, no usage — runs its normal job instead of answering               5
          daintree-control · established · fleet-identity · runmarker · pretooluse-guard

PARTIAL   prints usage AND exits 2 — answers and refuses simultaneously             1
          use-not-mention

⇒ They need different remedies and one of them may need none.

• REFUSED is verdict-census.py: -h and --help are classified VOID "established nothing" and exit 2 — the tool refuses its own help #350's defect exactly, at eight more sites. ★ tools/README.md: "a run that
  establishes nothing exits 2 and must never be read as all clear — the single convention worth
  carrying." ⛔ A pane that does not know a tool's flags asks --help, is told established nothing, and by the convention it has been taught must not read that as all clear. The honest
  reading is the measurement refused, which is false.
• ⚠ IGNORED is arguably worse and is NOT what verdict-census.py: -h and --help are classified VOID "established nothing" and exit 2 — the tool refuses its own help #350 described. These exit 0 and do the
  work. A pane asking what a tool does causes a run, and daintree-control and
  pretooluse-guard touch the fleet substrate. ⇒ Asking the question performs the action.
• PARTIAL answers correctly and then contradicts itself in the exit code — the same
  answered-and-refused pair verdict-census.py: -h and --help are classified VOID "established nothing" and exit 2 — the tool refuses its own help #350 found at verdict-census, surviving in one place.

⇒ Done when

1. Each of the 15 is either fixed (exit 0 + usage) or recorded as an intentional exemption with
   the reason, in tools/README.md. ⛔ An exemption without a reason is not one.
2. Both directions controlled at every site touched, as DEV1 did on their five: a fix that
   returns 0 for everything satisfies the help test by destroying the refusal path.
3. The command below returns only rows named as intentional by leg 1.

for t in tools/*.py; do case $(basename "$t") in test_*) continue;; esac
  out=$(python3 "$t" --help </dev/null 2>&1); rc=$?
  printf '%s' "$out" | grep -qi '^usage:' && u=1 || u=0
  [ "$rc" = 0 ] && [ "$u" = 1 ] || echo "$t exit=$rc usage=$u"
done

⚠ A count of 0 from that loop is not the goal — an exemption row is a pass. ⛔ And a loop that
prints nothing because it failed to run is VOID, not clean: it must be controlled against a tool
known to answer (verdict-census.py) and one known not to (estatenames.py).

⚠ Two defects in my own measurement, corrected before this was filed

• A first pass reported 28. It counted nine tools for "saying established nothing" — ⛔ but
  their help text DOCUMENTS the convention rather than spending it. Use versus mention, in the
  probe, on an issue about vocabulary. ⇒ Fixed by asking the right question: did it print
  usage:?
• Five reported TIMEOUT and that was the probe. They read stdin and were given none. ⇒ With
  stdin closed, ci-log-clean is a real REFUSED and pretooluse-guard a real IGNORED. Neither
  hangs.

⛔ What this does NOT establish

• That any of the 15 is worth fixing. Several may be scripts with no flag surface, and "not an
  argparse tool" is a valid answer that leg 1 accommodates.
• That 39 answering is good. ⚠ I checked that they print usage — not that the usage is
  accurate. A tool whose help documents a flag it no longer has passes this probe.
• ⛔ Anything about tools/*/*.py. 20 subdirectory instruments exist and check-tools-index.py
  holds them to a weaker contract by design. They are excluded here on purpose, not overlooked.

Related: #350 (closed, the one-tool instance) · #58 (three producers of exit 2 colliding — this is
the tool spending its OWN vocabulary, which survives any fix to that) · #2 · #471.

⚠ Routed to DEVOPS and DX rather than assigned: nine of the fifteen are not mine, and
#461's ruling now says role: is the queue. ⇒ Under it, this carries no dev:N because it is
not role:DEV work.