fix(#38): single-source-of-truth for command + MCP tool counts

[Wolfvin]

Closes #38

Problem

The CodeLens command count was hardcoded in 8 different places across the repo and had drifted to 5 different values (41, 45, 56, 57, 60). The actual runtime count is 64 commands. The existing regression test (tests/test_integration.py L281) used a loose >= 41 assertion that would not catch silent command loss — every command could disappear and the test would still pass.

The MCP tool count was also inconsistent: README said 55, SKILL.md said 54, SKILL-QUICK.md said 58 (with broken math: "51 static + 7 dynamic = 58" doesn't even add up).

Actual Counts Found (runtime)

Metric	Value	Source
CLI commands	64	len(COMMAND_REGISTRY) (auto-registered from scripts/commands/*.py minus __init__.py)
MCP tools (total)	62	len(COMMAND_REGISTRY) - 2 (excludes watch, serve)
MCP tools (static)	51	len(_TOOL_DEFINITIONS) in mcp_server.py
MCP tools (dynamic)	11	total - static (auto-discovered from COMMAND_REGISTRY)

Single-Source-of-Truth Mechanism

KISS design: one helper + tests that enforce it. No codegen, no build system.

1. scripts/sync_command_count.py (new)

Reads COMMAND_REGISTRY and _TOOL_DEFINITIONS at runtime and rewrites every doc/metadata file with the correct counts. Regex-driven, declarative rule list.

python3 scripts/sync_command_count.py            # alias for --check
python3 scripts/sync_command_count.py --check    # exit 1 if drift
python3 scripts/sync_command_count.py --apply    # write to disk

When adding a new rule (e.g. for a new doc file that mentions counts), add one entry to _build_rules() in this file. The docs themselves never hardcode the number.

2. scripts/codelens.py — --command-count flag (new)

Prints len(COMMAND_REGISTRY) and exits. Used by tests/CI to introspect without parsing --help. The --help description now also includes the count.

3. tests/test_integration.py — strict assertion

The loose >= 41 is now strict == EXPECTED_COMMAND_COUNT (= 64). Detailed docstring explains the update procedure when count intentionally changes. The sentinel EXPECTED_COMMAND_COUNT = 64 is the ONE place where the count is intentionally hardcoded — it is the regression anchor; the sync helper intentionally does NOT touch it.

4. tests/test_command_count.py (new)

Four enforcement tests:

• test_command_count_helper_matches_runtime_registry — sync helper reports correct count
• test_mcp_tool_count_math_is_consistent — total = cmd - {watch,serve}; static + dynamic = total
• test_all_docs_in_sync_with_command_registry — runs sync --check; fails on any drift
• test_sync_helper_idempotent_after_apply — running --apply twice is a no-op the second time

5. CONTRIBUTING.md — updated

Added a "Syncing Command Counts (issue #38)" section so contributors know the procedure when adding/removing commands.

Files Changed

File	Change
scripts/sync_command_count.py	NEW — single-source-of-truth sync helper
tests/test_command_count.py	NEW — 4 enforcement tests
scripts/codelens.py	Added --command-count flag + count in --help description
tests/test_integration.py	Strict == assertion (was >= 41); updated docstring
CONTRIBUTING.md	New "Syncing Command Counts" section
README.md	6 substitutions: 57→64 (CLI), 55→62 (MCP), 50→51 (static), 5→11 (dynamic), 56→64 (file tree), 57→64 (commands dir)
SKILL.md	56→64 (commands), 54→62 (MCP)
SKILL-QUICK.md	56→64 (heading), 60→64 (Total line, also collapsed stale per-issue breakdown), 58→62 (MCP heading), 51→51 (static, unchanged), 7→11 (dynamic), dropped stale issue-number annotations
pyproject.toml	45→64 (description)
skill.json	45→64 (description)
scripts/mcp_server.py	45+→64 (docstring)
scripts/graph_model.py	56→64 (docstring)

Total: 12 files changed, 588 insertions, 22 deletions.

How It Prevents Future Drift

• Developer adds a command → strict test fails (len(COMMAND_REGISTRY) went from 64 → 65)
• Developer removes a command → strict test fails (64 → 63)
• Developer updates sentinel but forgets docs → test_all_docs_in_sync_with_command_registry fails (sync --check exits 1)
• Developer updates sentinel + runs sync --apply → both tests pass, all docs auto-updated

The one-place-to-update is EXPECTED_COMMAND_COUNT in tests/test_integration.py; everything else is automatic.

Test Results

tests/test_command_count.py (new enforcement tests)

============================== test session starts ==============================
collected 4 items
tests/test_command_count.py ....                                         [100%]
============================== 4 passed in 1.76s ===============================

tests/test_integration.py (strict assertion + all smoke tests)

============================== test session starts ==============================
collected 95 items
tests/test_integration.py ...............................................................................
============================== 95 passed ======================================

(95 dots, 0 failures, 0 skips. Pytest was killed by timeout 540 before writing the final summary line, but the dot output confirms all 95 tests passed.)

Full suite minus integration tests

1 failed, 843 passed, 12 skipped in 16.64s

The 1 failure is pre-existing and unrelated to this PR:
tests/test_architecture.py::TestArchitectureBasic::test_auto_scans_on_fresh_workspace
— fails because benchmarks/fixtures/clean_app/.codelens/ is committed to git and gets copied by the fresh_clean_app fixture (which is supposed to yield a workspace WITHOUT a .codelens/ dir). Verified failing on pristine main (commit 241c762) before any of my changes.

python3 scripts/codelens.py --help (Definition of Done #1)

CodeLens v8.2.0 — Live Codebase Reference Intelligence (Tree-sitter Edition).
64 commands available; run `python3 scripts/codelens.py --command-count` to
                       print just the count.

python3 scripts/codelens.py --command-count

64

python3 scripts/sync_command_count.py --check

Command count (runtime COMMAND_REGISTRY): 64
MCP tools: 62 total = 51 static + 11 dynamic (excluded from MCP: ['serve', 'watch'])

All documentation files are in sync with COMMAND_REGISTRY.

Definition of Done

• python3 scripts/codelens.py --help shows the same correct count (64) as all doc/metadata files
• PYTHONPATH=scripts python3 -m pytest tests/test_integration.py -v PASS, with strict == assertion
• PYTHONPATH=scripts python3 -m pytest tests/ -v — 843 pass + 12 skip + 1 pre-existing unrelated failure (no regressions introduced)

Closes #38.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud