Skip to content

feat(tri-comparison): superscript markers for args-granularity mismatches - #1931

Merged
squid-protocol merged 2 commits into
mainfrom
feat/args-granularity-chart-markers
Aug 20, 2026
Merged

feat(tri-comparison): superscript markers for args-granularity mismatches#1931
squid-protocol merged 2 commits into
mainfrom
feat/args-granularity-chart-markers

Conversation

@squid-protocol

Copy link
Copy Markdown
Owner

Summary

  • "args" doesn't mean the same unit across every language, even when a real comparison tool exists for other metrics -- COBOL's Args Found panel was silently rendering nothing at all (0/126 real args comparisons ever possible, since ctags has no per-paragraph signature for COBOL either), which read as "no data" rather than "this language measures args differently by design."
  • Adds ARGS_GRANULARITY, a small per-language classification with its own superscript marker + legend line (same convention */** already use):
    • program_level (†): one whole-program signature, not per-callable. cobol: PROCEDURE DIVISION USING/RETURNING is a program-level header; paragraphs don't take individual arguments at all.
    • none (‡): no parameter-list concept exists, ever. dockerfile/yaml/jcl: func_start matches a document-structural marker (RUN/CMD/EXEC/script:) as a pseudo-callable, same reason non-function-shaped languages get a func_start rule at all.
    • proxy (§): a real, non-trivial measurement via something other than a parenthesized parameter list. assembly/agc_assembly: counts calling-convention register mentions as an arg-count heuristic, same spirit as the existing bash/Perl $1/$2/$3 precedent.
    • default (no marker): ordinary per-callable parameter-list count.
  • The classification and the "don't guess -- rule out a real recall bug first" methodology behind it live in .claude/skills/tri-comparison-ledger-sweep/SKILL.md's "Args granularity" section (docs(skill): document args-granularity classification in tri-comparison-ledger-sweep #1924); this PR is the chart-rendering implementation of that design.

Verification

  • Regenerated the full 45-language chart, diffed by label TEXT CONTENT (not raw SVG, since bumping top_margin by 14px for the new legend line shifts every row's y-coordinate) -- confirmed exactly 4 new bar labels appeared (cobol 14†, dockerfile 0‡, assembly 77§, agc_assembly 469§) and exactly 1 new legend line, nothing else in the chart changed.
  • Confirmed the ranked-panel summary tally is untouched (Args Found stays unranked per the module's own PANELS docstring).
  • ruff_audit.py --ci / mypy_audit.py --ci: clean, no new findings (pre-existing, unrelated formatting drift in this file confirmed present even on a clean checkout with my changes stashed out, left untouched per repo convention for pre-existing debt).

Test plan

  • Test-rendered a small language subset first (cobol/dockerfile/assembly/agc_assembly/python) to confirm markers render and defaults are unaffected, before the full --all --write run
  • Full chart diff verified by label content, not raw coordinates
  • Confirmed unrelated stray ledger.json churn (non-deterministic anonymous-name IDs in capped examples, from running the full reconciliation) was reverted out of this PR -- kept focused on the chart-rendering change only

🤖 Generated with Claude Code

…ches

"args" doesn't mean the same unit across every language, even when a real
comparison tool exists for other metrics -- COBOL's Args Found panel was
silently rendering nothing at all (0/126 real args comparisons ever
possible, since ctags has no per-paragraph signature for COBOL either),
which read as "no data" rather than "this language measures args
differently by design."

Adds ARGS_GRANULARITY, a small per-language classification with its own
superscript marker + legend line (same convention `*`/`**` already use):
  - program_level (†): one whole-program signature, not per-callable.
    cobol: PROCEDURE DIVISION USING/RETURNING is a program-level header;
    paragraphs don't take individual arguments at all.
  - none (‡): no parameter-list concept exists, ever. dockerfile/yaml/jcl:
    func_start matches a document-structural marker (RUN/CMD/EXEC/script:)
    as a pseudo-callable, same reason non-function-shaped languages get a
    func_start rule at all.
  - proxy (§): a real, non-trivial measurement via something other than a
    parenthesized parameter list. assembly/agc_assembly: counts
    calling-convention register mentions as an arg-count heuristic, same
    spirit as the existing bash/Perl $1/$2/$3 precedent.
  - default (no marker): ordinary per-callable parameter-list count.

The classification and the "don't guess -- rule out a real recall bug
first" methodology behind it live in .claude/skills/tri-comparison-ledger-
sweep/SKILL.md's "Args granularity" section (added in a prior commit) --
this PR is the actual chart-rendering implementation of that design.

Verified: regenerated the full 45-language chart, diffed by label TEXT
CONTENT (not raw SVG, since bumping top_margin by 14px for the new legend
line shifts every row's y-coordinate) -- confirmed exactly 4 new bar
labels appeared (cobol "14†", dockerfile "0‡", assembly "77§",
agc_assembly "469§") and exactly 1 new legend line, nothing else in the
chart changed (no ranked-panel/summary-tally content moved, since Args
Found stays unranked per the module's own PANELS docstring). ruff/mypy
baseline-gated audits clean (pre-existing, unrelated formatting drift in
this file confirmed present even on a clean stash, left untouched).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab

@squid-protocol
squid-protocol enabled auto-merge (squash) August 20, 2026 17:09
…-chart-markers

# Conflicts:
#	docs/self_scan/tri_comparison_chart.svg
@squid-protocol
squid-protocol merged commit e986630 into main Aug 20, 2026
26 checks passed
@squid-protocol
squid-protocol deleted the feat/args-granularity-chart-markers branch August 20, 2026 17:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant