Rewrite CLAUDE.md against the real architecture; resolve the 3-way mocking-policy contradiction #125

Part of #108 · Phase 5 · label: documentation

Problem

CLAUDE.md is the file every AI coding session loads as ground truth, so its inaccuracies propagate into work. Verified inaccuracies:

• "Add new cluster type to ClusterType enum in config.py" — no such symbol exists. grep -rn ClusterType clustrix/ returns nothing; config.py:19 uses a plain cluster_type: str. Anyone following this instruction is looking for a thing that isn't there.
• "ClusterExecutor (clustrix/executor.py): Central execution engine handling job submission, SSH connection management, file transfer, job monitoring..." — executor.py is a 39-line re-export shim (:1-38). The real logic lives in executor_core.py (466), executor_connections.py (389), executor_schedulers.py (378), executor_scheduler_status.py (651), executor_kubernetes.py (461), executor_cloud.py (470) — none of which CLAUDE.md mentions.
• "Implement _submit_{type}_job method in ClusterExecutor" — these are back-compat wrappers (executor_core.py:430-448); real work is in SchedulerManager.submit_*_job / KubernetesJobManager.
• The architecture section omits most of the package: the entire notebook stack (notebook_magic_{core,config,widget,mocks,enhanced,aws,azure,gcp,ssh}.py, modern_notebook_widget.py at 1,631 lines), plus cloud_providers/, cost_providers/, pricing_clients/, kubernetes/, credential_manager.py, auth_manager.py, function_flattening.py, gpu_utils.py.
• "The project is in beta (v0.1.0)" — pyproject.toml and setup.py say 0.1.1.
• Direct self-contradiction on mocking. CLAUDE.md says unit tests "Mock external dependencies"; .claude/CLAUDE.md says "Do not use mock services for anything ever"; README.md claims "Zero use of @patch, Mock()". Three files, three incompatible policies — which is a large part of how the suite ended up with 2,513 mock occurrences while claiming to have none.

Verified accurate, for the record (do not "fix" these): scripts/check_quality.py, scripts/pre_push_check.py, scripts/run_real_world_tests.py with its documented flags, both installed git hooks, and the entire filesystem-utilities section.

Stale project-management state

Acceptance criteria

• CLAUDE.md architecture section regenerated from the actual module layout
• The ClusterType enum instruction removed or the enum introduced
• "Adding a new cluster type" rewritten against the real extension points (SchedulerManager, the provider ABC from the Phase 3 issue)
• One mocking policy, stated once, consistent across CLAUDE.md, .claude/CLAUDE.md, and README.md
• Version reference removed from prose, or sourced from a single location
• notes/ and .claude/epics/ reconciled with reality or archived
• A CI check that fails when CLAUDE.md references a symbol or path that does not exist — the same drift will otherwise recur