follow-up: filter shell syntax / parser-noise out of Top unhandled commands

Summary

Follow-up to #1459.

rtk discover should suppress obvious shell syntax / wrapper noise from the user-facing Top unhandled commands output instead of ranking those entries alongside meaningful commands.

Right now, entries like these can appear near the top of the report:

• [
• if [
• python3 <<
• # Check
• # Test
• '^RXRESUME_API_KEY='
• null
• eval "$(...)"

These are not product-like command gaps. They are shell syntax fragments, comment sentinels, heredoc headers, wrapper-private patterns, or parser artifacts.

Why this deserves its own issue

#1459 identifies the broader overcounting problem.

This issue is specifically about the reporting layer / UX contract: even if parser fallbacks exist upstream, discover should not surface obviously low-value fragments as first-class “commands”.

Concrete example

A recent local unhandled-command summary included all of the following in the top ranks:

Entry	Count
$B goto	62
# Check	36
eval "$(..	36
[	21
# Test	19
python3 <<	16
'^RXRESUME_API_KEY='	12
if [	9
null	9
eval	8
rev-parse	7

Even if some of these originate from real shell activity, the report quality is poor because the output mixes:

• meaningful executable gaps,
• wrapper internals,
• shell syntax,
• and parser garbage.

Expected

Top-unhandled-command reporting should favor entries that look like real user-level commands, and suppress or quarantine obviously low-confidence fragments.

Possible behavior:

Option A: Filter them out entirely

Exclude entries that match patterns like:

• shell builtins / syntax markers ([, if [, then, fi)
• comment lines (# ...)
• heredoc starters (python3 <<, cat <<, etc.)
• env-assignment or grep-pattern fragments
• null / empty / malformed tokens

Option B: Separate them into a different bucket

Keep a secondary section such as:

• LOW-CONFIDENCE / PARSER-NOISE ENTRIES

so the primary Top-unhandled table stays actionable.

Option C: Add confidence / source annotations

Examples:

• [ — source: shell syntax, confidence: low
• # Check — source: comment sentinel, confidence: low
• python3 << — source: heredoc wrapper, confidence: low

Actual

These fragments are surfaced in the same top-level ranking as meaningful commands, which makes the report feel noisy and misleading.

Why this matters

If discover is meant to help users decide where RTK support gaps are, the top-level report needs to be decision-quality.

Right now, noisy entries can:

• distract from real executable gaps,
• cause users to file the wrong issues,
• and reduce trust in discover output.

Potential fixes

1. Add a suppression list / regex layer for obvious syntax fragments.
2. Require a minimum command-shape quality bar before an entry can appear in the primary ranking.
3. Bucket low-confidence entries separately rather than mixing them into the main table.
4. Annotate entries with source kind when they come from parser fallback rather than direct command classification.

Relation to existing issues

• #1459 — broader shell-wrapper fallback overcounting
• #1406 / #1397 — raw top-unhandled data examples from real usage

This issue focuses on the UX/analytics layer: even imperfect upstream parsing should not produce a misleading primary report.

Environment

• Observed on: April 22, 2026
• Context: Codex / OMX / gstack-heavy shell-wrapper workflows
• OS: macOS