refactor(commands): consolidate 78 commands → 12 focused umbrella commands (closes #195)

[Wolfvin]

Closes #195

Summary

Consolidates 78 legacy commands into 12 focused umbrella commands per issue #195. Each umbrella command accepts --check <category> (or --mode for search) to select a specific sub-analysis, or runs all by default. Legacy command names remain callable as hidden deprecated aliases (backward compat for one version) that print a redirect warning to stderr.

The 12 Umbrella Commands

Command	Absorbs	--check / --mode choices
scan	scan, init, rescan	--check scan|init|rescan
search	symbols, semantic-query, query-graph, search	--mode semantic|symbol|regex|graph
context	context, outline, trace, orient	--check orient|outline|trace|context (default: orient)
deps	affected, dependents, circular, import-snapshot	--check affected|dependents|circular|import-snapshot
audit	dead-code, complexity, smell, staleness, perf-hint, side-effect	--check dead-code|complexity|smell|staleness|perf-hint|side-effect
security	secrets, vuln-scan, taint, binary-scan, regex-audit	--check secrets|vuln-scan|taint|binary-scan|regex-audit
summary	summary, dashboard, arch-metrics, architecture	--check summary|dashboard|arch-metrics|architecture (default: summary)
impact	impact, diff, dataflow	--check impact|diff|dataflow (default: impact)
api-map	api-map, graph-schema	--check api-map|graph-schema (default: api-map)
doctor	doctor, env-check, lsp-status	--check doctor|env-check|lsp-status (default: doctor)
history	history, ownership, git-status	--check history|ownership|git-status (default: history)
graph	query-graph (raw Cypher)	— (power-user pass-through)

Definition of Done checklist

• All 12 umbrella commands functional with --check/--mode dispatch
• Absorbed commands callable as deprecated aliases (print redirect warning to stderr)
• --help shows only 12 commands; --command-count prints 12
• README.md updated with mapping table
• Drop-total command files deleted (25 files)
• Tests for 12 umbrella commands (17 new tests in test_issue195_consolidation.py)

Commands Dropped Total (25 files deleted)

adr, a11y, handbook, ask, serve, sessions, watch, registry-validate, rule-test, rule-validate, artifact-scan, css-deep, debug-leak, detect, export-snapshot, refactor-safe, resolve-types, stack-trace, benchmark, fix, self-analyze, guard, llm, memory.

Findings (needs BOS decision)

1. 13 commands not in absorb list nor drop list

The issue body lists 78 → 12, but 13 commands are neither absorbed nor explicitly dropped:
analyze, check, config-drift, deps-audit, entrypoints, lsp, list, missing-refs, plugin, query, state-map, test-map, type-infer.

These are marked hidden (callable but not in --help) pending BOS decision on where they belong. Notable concerns:

• check is the CI quality gate — deleting it would break .github/workflows/. Kept hidden but functional.
• analyze is the "full repo analysis" aggregator.
• query is the pre-write safety check (referenced by the old context deprecation message).

Recommendation: Either (a) absorb these into a 13th umbrella, (b) drop them, or (c) keep them hidden permanently. Worker did not decide unilaterally — flagged for BOS.

2. lsp-status and migrate kept as utility modules

• lsp_status.py — file kept (not deleted) but command unregistered. doctor --check lsp-status imports it directly. The codelens --lsp-status top-level flag still works (handled in codelens.py main).
• migrate.py — file kept as a utility wrapper around PersistentRegistry.migrate_from_json. The migrate command is NOT registered (dropped per issue), but the module exists so existing tests that from commands.migrate import cmd_migrate continue to work.

3. serve (MCP server) dropped

The MCP server CLI entry point (codelens serve) is dropped per the issue. The mcp_server.py module still exists and the MCP tool count is now 12 (6 static + 6 dynamic, matching the 12 umbrella commands). If MCP server access is still needed, it can be re-exposed via a different entry point in a follow-up issue.

4. Shared utility extraction

• _extract_project_identity moved from commands/handbook.py → scripts/handbook_helpers.py (used by summary and analyze).
• _watch_polling import removed from mcp_server.py (was an unused import — the MCP watcher has its own inline polling loop).

Test results

• tests/test_issue195_consolidation.py: 17 new tests, all pass
• tests/test_command_count.py: 4 tests, all pass (updated for visible-only counting)
• tests/test_command_registry.py: 2 tests, all pass (allowlist for migrate.py utility)
• tests/test_persistent_registry.py::TestMigration: 3 tests, all pass (migrate wrapper)
• Skipped tests for dropped commands (adr, llm, resolve-types, sessions, snapshot, memory) — marked with @pytest.mark.skip + reason
• Pre-existing failures (unrelated to this PR): test_formatters_phase2::TestCLISmoke::test_help_lists_new_formats, test_universal_grammar_loader (tree_sitter dep missing in env), test_confidence schema-version tests — all verified to fail on clean main too.

Files changed

101 files changed, +2767 / -6402 lines.

Sebelum → Sesudah

Sebelum (78 commands visible):

codelens --help → {a11y,adr,affected,analyze,api-map,...78 total...}

Sesudah (12 commands visible):

codelens --help → {api-map,audit,context,deps,doctor,graph,history,impact,scan,search,security,summary}
codelens --command-count → 12

Old commands still work but warn:

$ codelens dead-code .
[CodeLens] DEPRECATED: 'dead-code' is a deprecated alias. Use 'codelens audit' instead. This alias will be removed in the next version (issue #195).
{...normal output...}

[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 failed

Failed conditions
5.9% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud