[BUG-04] Command count is inconsistent across 7 sources — actual=60, docs say 45/56/57/41

[Wolfvin]

Summary

The advertised CodeLens command count disagrees across 7 locations in the repo. The actual count (auto-registered command modules in scripts/commands/) is 60 (61 .py files in scripts/commands/ minus __init__.py). Documentation and metadata cite anywhere from 41 to 60.

Evidence

Source	Claimed count	Location
README.md L5	"57 CLI commands"	Intro paragraph
README.md L9	"57 CLI Commands"	Features list
README.md L228	"56 commands registered"	File-tree comment
README.md L286	"57 commands incl. graph-schema"	File-tree comment
SKILL-QUICK.md L146	"Total: 60 commands"	Footer
SKILL.md L4	"56 commands"	Frontmatter description
pyproject.toml L8	"45 commands"	description field
skill.json L4	"45 commands"	description field
tests/test_integration.py L2	"41 CodeLens commands"	Module docstring
tests/test_integration.py L281	>= 41	Assertion (passes trivially)
Actual	60 command modules	ls scripts/commands/*.py | grep -v __init__.py | wc -l returns 60

Impact

1. Marketing vs reality mismatch: Users reading README.md see "57 commands" but codelens --help lists 60. Erodes trust in docs.
2. Packaging metadata lies: PyPI description (if shipped) would say "45 commands".
3. Test assertion is stale: assert len(COMMAND_REGISTRY) >= 41 passes trivially and provides no regression protection. A command could be silently dropped (see related BUG-09) and the test would still pass.
4. MCP tool count mismatch: SKILL-QUICK.md advertises "55 tools" / "51 static + 7 dynamic = 58 tools" — also inconsistent with the 60-command reality.

Suggested fix

1. Single source of truth: Add a codelens --count-commands dev subcommand (or a scripts/utils.py:get_command_count() helper) that returns len(COMMAND_REGISTRY) at runtime.
2. Generate docs from source: Replace hardcoded counts in README.md / SKILL.md / SKILL-QUICK.md with a CI step that rewrites them from the runtime value. (Or just write "60+" and stop pinning the exact number in prose.)
3. Bump pyproject + skill.json: Update both description fields to reflect 60 commands (or remove the count from the description entirely).
4. Strengthen the test: Change assert len(COMMAND_REGISTRY) >= 41 to assert len(COMMAND_REGISTRY) == EXPECTED_COUNT where EXPECTED_COUNT is loaded from a single config (or just >= 60 if you want a floor).
5. Reconcile MCP tool count: Update SKILL-QUICK.md MCP section to match the actual static+dynamic count after the command count is settled.

Files

• README.md (L5, L9, L228, L286)
• SKILL.md (L4)
• SKILL-QUICK.md (L146, MCP section)
• pyproject.toml (L8)
• skill.json (L4)
• tests/test_integration.py (L2, L281)

[Wolfvin]

Multi-worker analysis: direct duplicate confirmation + extension

This command count inconsistency issue is directly confirmed and extended by 2 worker reports:

Worker	Source file	What they add
Semgrep	update!/CodeLens_Upgrade_Issues_from_Semgrep.md \u00a79.1 "Quick Fix" #24	"README claims 56 commands, SKILL-QUICK claims 45 commands. Compute actual count from registry code and synchronize both docs." Listed as Quick Fix.
Semgrep	same file #25	"README claims 49 MCP tools but code uses dynamic discovery, so actual count may differ. Compute actual MCP tool count from mcp_server.py _TOOL_DEFINITIONS and sync README." Listed as Quick Fix. Extends this issue to cover MCP tool count drift, not just command count.
OpenTaint	update!/CodeLens_vs_OpenTaint_Upgrade_Analysis.md F2	"Auto-generate skill.json's command_categories field from scripts/commands/ directory listing. New script scripts/generate_skill_metadata.py reads scripts/commands/*.py and writes skill.json. CI check fails if skill.json doesn't match actual command files." Identified as quick win (3 days).

Recommendation

This issue should be extended to cover 3 dimensions of count drift, all fixable in one PR:

1. Command count in README / SKILL.md / SKILL-QUICK.md (currently this issue's scope)
2. MCP tool count in README (Semgrep [BUG] Incremental scan does not populate graph tables (only full scan does) #25) — currently says "49 tools" but _TOOL_DEFINITIONS has 51 static + 7 dynamic \u2212 2 excluded = 56 tools
3. Auto-generated skill.json (OpenTaint F2) — command_categories field should be generated from scripts/commands/ at build time, not hand-maintained

The auto-generation approach (OpenTaint F2) is the durable fix — once skill.json is generated, the README count can be generated from it too. Manual sync will always drift again.

Suggest retitling this issue to "Command/MCP/skill.json count drift \u2014 auto-generate from source" and shipping as one PR.

Aggregated from update!/ worker analysis reports by multi-worker triage.