CodeClone 2.1.0a1: intent-first structural change control, persistent engineering context, agent workflow evidence, platform self-observability, and broader IDE/agent integration.

CodeClone 2.1 introduces intent-first structural change control, persistent engineering context, agent workflow
evidence, platform self-observability, and broader IDE/agent integration.

Added

• Structural Change Controller with start_controlled_change / finish_controlled_change, bounded edit scope,
  blast-radius checks, patch verification, claim validation, multi-agent intent coordination, and deterministic review
  receipts.
• Live Implementation Context via get_implementation_context, including bounded structural context, call
  relationships, contract-oriented truth maps, freshness, test anchors, and active intent boundaries. Context remains
  read-only and never authorizes edits.
• Engineering Memory, Trajectory Memory, Patch Trail, and Experience Layer for typed repository
  knowledge, historical agent workflows, change evidence, reusable patterns, and human-governed promotion.
• Semantic retrieval with optional LanceDB hybrid search, FTS5/BM25, vector search, and deterministic Reciprocal
  Rank Fusion.
• Platform Observability for development-time tracing of CLI, MCP, analysis phases, database activity, semantic
  indexing, worker chains, memory/CPU use, MCP payload pressure, and costly no-ops.
• Corpus Analytics for offline intent clustering, interpretability, versioned profiles, sweep comparison, maintainer
  selection, and inspectable JSON/HTML outputs.
• Module Map as a deterministic report-only package/module graph with cycle, hub, overloaded-module, and
  unwind-candidate views.
• Guided Finding Review as a prioritized report-only review queue with shared finding cards, filters, progress
  tracking, and reviewed-state persistence.
• Native agent and IDE integrations for VS Code, Claude Desktop, Claude Code, Codex, and Cursor, including
  governance, audit, memory, trajectory, and structural-review workflows.
• codeclone setup — lazy-loaded CLI readiness surface (status, doctor, plan, apply, wizard) with
  capability-aware snapshots, read-only diff preview, and bounded pyproject.toml / .gitignore merges (no MCP
  intent, no baseline or report writes). The CLI also gains a guided --help tour.
• Expanded controller, memory, trajectory, analytics, semantic-search, observability, blast-radius, patch-verification,
  and diagnostic CLI/MCP surfaces. The default MCP server surface is now 38 tools (40 when VS Code enables the
  IDE governance channel).
• Reorganized documentation into a task-oriented site (concepts, guides, reference, integrations) with unified
  integration guidance and explicit edition tiers.
• MCP schemas now include parameter descriptions, deterministic next_tool guidance, token-budget tracking, workspace
  hygiene warnings, and documentation-contract linting.
• MCP response governance now advertises context_governance metadata for bounded agent replies. Workflow, memory, and
  implementation-context responses preserve mandatory control facts inline, compact recoverable evidence under
  partial_enforce, disclose omitted lanes, and expose exact drill-down through durable receipt, Patch Trail, blast
  artifact, memory continuation, and implementation-context page retrieval.

Contract changes

• Cache schema advanced to 2.9 for the rebuildable per-function relationship-fact projection and to 2.10 for
  intra-module, class-method, and receiver-aware call resolution.
• Engineering Memory schema advanced to 1.7 for trajectory and Patch Trail evidence.
• Semantic index format advanced to 3 for LanceDB rows with source_revision; existing semantic sidecars should be
  rebuilt.
• Corpus Analytics store schema advanced to 1.2.
• Corpus Analytics JSON export schema advanced through 1.2 and 1.3.
• Corpus Analytics representation contract advanced to 3.
• Corpus Analytics control-plane contract introduced at 1.0.
• MCP response governance contract introduced at 1.0 with deterministic utf8_bytes_div_4_v1 context-unit
  estimation and explicit observe / partial_enforce modes.
• compare_runs parameters are unified to before_run_id / after_run_id.
• derived.module_map and derived.review_queue remain report-only projections excluded from the integrity digest;
  they add no analysis pass, metrics family, or report schema bump.
• Live Implementation Context relationship facts remain off the canonical report and do not change canonical report
  identity.

Changed

• Default project workspace moved from .cache/codeclone/ to .codeclone/; legacy paths emit a migration warning.
• Documentation builds now use Zensical with strict clean builds.
• pydantic is now a base dependency.
• LCOM4 excludes Protocol methods and Pydantic validation/serialization hooks; computed_field remains included.
• Repository coverage is enforced at >=99%.

Performance

• Relationship facts are collected during the primary module walk instead of a second traversal (cold-cache
  phase_relationship −28%), and reachability facts replay captured handler nodes instead of a third full AST pass.
• MCP hot paths are bounded: findings are paged before decoration, hotspot and intent-scoped blast projections are
  capped, analysis no longer round-trips through the report, and cache loads retain less transient memory.

Fixed

• Engineering Memory writes are durable, batch ingestion is atomic, and memory/trajectory/Patch Trail lifecycle
  handling avoids premature staleness, duplicate projections, stale workflow rows, and broken evidence links.
• Best-effort audit and memory-proposal failures are now observable instead of silently swallowed.
• Implementation-context misses return a compact actionable payload instead of empty scaffolding.
• Workspace hygiene, intent attribution, continuation of owned work, queue handling, and recoverable-intent behavior
  were corrected.
• Patch verification now rejects identical before/after runs where required, surfaces health regressions, and warns on
  overstated review claims.
• Semantic retrieval now preserves lexical/vector relevance, avoids source crowding, loads embeddings lazily, and
  coalesces redundant projection work.
• Blast-radius graph logic moved into codeclone/analysis/blast_radius.py, removing the CLI-to-MCP dependency
  violation.
• respect_pyproject=false no longer reports golden-fixture clone groups as false new regressions.
• Documentation URLs, integration references, and contract tests were aligned with the reorganized site.

CodeClone 2.0.2: is a focused patch release for VS Code extension packaging metadata and dead-code runtime reachability precision.

2.0.2 is a focused patch release for VS Code extension packaging metadata, README link behavior, and dead-code runtime reachability precision.

Enhancements

• Extend runtime reachability with exact Aiogram Router/Dispatcher observer decorators, Starlette BaseHTTPMiddleware.dispatch hooks, Flask/Blueprint routes, aiohttp RouteTableDef route decorators, FastAPI route decorator factories, and SQLAlchemy TypeDecorator runtime hooks to reduce false-positive dead-code findings without name-only heuristics.
• Exclude node_modules from the default Python scanner so vendored frontend dependencies do not appear as project dead-code findings.

Bug Fixes

• Fix HTML report PyCharm/IntelliJ source links so they preserve line navigation when opening files from report tables.
• Fix README package badges so PyPI/status/download/Python-version links open the PyPI project page instead of scrolling to the installation section.
• Treat __all__ re-exports, PEP 562 lazy _EXPORTS modules, and guarded dynamic getattr(..., "method") callable dispatch as dead-code reachability evidence.
• Show a one-time interactive CLI migration note when a trusted 2.0.1 baseline is analyzed by 2.0.2, clarifying that fewer dead-code findings are expected after the refined reachability model.

Internal

• Bump cache schema to 2.8 so projects rebuild cached dead-code and runtime reachability facts after the refined framework model.
• Bump the Python package and composite GitHub Action default install version to 2.0.2.
• Record the VS Code extension 0.2.7 metadata that matches the Marketplace build carrying Coverage Join hotspot support and workspace-root coverage.xml discovery.

CodeClone 2.0.1: stability release for dead-code precision

2.0.1 is a focused stability release for dead-code precision and cache/report contract parity after the 2.0 line.

Dead code

• Add framework-aware runtime reachability for dead-code analysis: FastAPI/Starlette routes and Annotated[..., Depends/Security(...)] dependencies, Django URL patterns, Dependency Injector providers, Typer/Click commands, Celery tasks, top-level __all__ exports, package entry points, and Pydantic validator/serializer hooks. Supported registrations suppress false dead-code findings without framework execution or name-only heuristics.
• Treat typing.Protocol and typing_extensions.Protocol declarations, including generic Protocol[T], as type-only contracts so structural interfaces do not produce false-positive dead-code findings.
• Show a one-time interactive CLI migration note for projects upgrading from the 2.0.0 line when the refined reachability model may reduce dead-code findings.
• Bump cache schema to 2.7 and report schema to 2.11 to carry reachability facts for cold/warm parity and report explainability.

CodeClone 2.0.0: a baseline-aware structural review platform for Python.

CodeClone 2.0.0 is the first stable 2.x release: a baseline-aware structural review platform for Python with CLI, MCP, VS Code, Claude Desktop, Codex, and GitHub Action surfaces built on one canonical report contract.

Highlights

• Canonical package layout — global architecture refactor completed in 2.0.0b6; the entire runtime now lives in stable, directly importable modules.
• Stable CLI, report, MCP, and baseline contracts for the full 2.x line.
• Adaptive dependency-depth scoring — project-relative model replacing the old fixed threshold; avg/p95/max chain metrics surface in reports and CLI.
• Security Surfaces — report-only trust-boundary inventory: subprocess, filesystem mutations, crypto, dynamic loading. No vulnerability claims, no score impact.
• Coverage Join — fuse external Cobertura XML into the structural review to surface hotspots against real pytest coverage.
• Native client surfaces — VS Code extension, Claude Desktop bundle, Codex plugin, and composite GitHub Action, all over the same codeclone-mcp contract.
• Dedicated PyPI README and refreshed CodeClone branding.

Install

uv tool install codeclone
uv tool install "codeclone[mcp]"

See CHANGELOG.md for the full contract and migration details.

CodeClone 2.0.0b7: is a beta hotfix for packaging-only issues found after the 2.0.0b6 publish.

Packaging

• Constrain the optional MCP extra to httpx>=0.27.1,<1 so prerelease install flows such as
  uv tool install --pre "codeclone[mcp]" do not resolve incompatible httpx 1.0.dev* builds through the upstream MCP
  dependency graph.
• Pin the preview VS Code extension packaging tool to @vscode/vsce@2.25.0, removing the vulnerable transitive
  uuid<14 chain from package-lock.json while preserving .vsix packaging.
• Keep local pre-commit runs stable after package builds by letting mypy use the configured source roots and ignoring
  generated build/ and site/ artifacts.

CodeClone 2.0.0b6: land the architecture split, adaptive dependency profiling, and security review surfaces

The global package refactor lands here: the entire runtime moves onto the canonical module layout and legacy shims are removed for good. On top of that, dependency-depth scoring is replaced with an adaptive project-relative model, and the report/cache contracts advance to surface the new depth profile and the report-only security_surfaces layer.

Package layout and contracts

• Move the runtime fully onto the canonical package layout: main + surfaces/cli, surfaces/mcp, core, analysis, baseline, cache, contracts, report/document, report/renderers, and report/html.
• Remove remaining legacy root shims and stale compatibility modules in favor of direct canonical imports.
• Remove stale deleted-file cache entries and trim post-refactor import tails that were inflating dependency depth and clone pressure.
• Bump report schema to 2.10 and cache schema to 2.6 for additive dependency depth profile fields and security_surfaces facts; keep clone baseline schema 2.1 and metrics-baseline schema 1.2 unchanged.
• Preserve deterministic contracts and read-only MCP semantics across the new layout.

Dependency depth scoring

• Replace the old fixed dependency-depth penalty (max_depth > 8) with an adaptive internal-graph profile based on avg_depth, p95_depth, and max_depth.
• Keep dependency cycles as the hard signal; treat acyclic depth as adaptive pressure relative to the project's own dependency profile.
• Limit dependency-depth scoring to the internal module graph instead of external imports such as typing or argparse.
• Surface the dependency depth profile in the canonical report, HTML Dependencies tab, and CLI/CI summaries.

Security surfaces

• Add metrics.families.security_surfaces: a report-only exact inventory of security-relevant capability surfaces and trust-boundary code.
• Surface compact security_surfaces facts in canonical report JSON, CLI Metrics, HTML Quality, text/markdown projections, and MCP summaries / metrics_detail.
• Keep the layer honest: no vulnerability claims, no score impact, no gates, no SARIF security findings, and no baseline truth.

Tooling, docs, and UX

• Refresh AGENTS, docs/book, and changelog content for the b6 package layout and report schema 2.10.
• Tighten preview client metadata and install guidance for VS Code, Claude Desktop, and Codex.
• Replace the Codex plugin shell snippet with a repo-local shell-free launcher, and parallelize VS Code post-run MCP artifact hydration.
• Add a quiet one-time VS Code extension hint in interactive VS Code terminals, tracked per CodeClone version next to the resolved project cache path.

CodeClone 2.0.0b5: coverage-aware metrics and baseline-honest review surfaces

Contracts, metrics, and review surfaces

• Report schema 2.8: add coverage_adoption, api_surface, coverage_join, and optional clones.suppressed.* (for golden_fixture_paths); separate coverage hotspots vs scope gaps.
• Baselines: clone 2.1, metrics 1.2; compact api_surface payload (local_name on disk, qualnames at runtime); read-compatible with 2.0 / 1.1.
• Add public/private visibility classification for public-symbol metrics (no clone/fingerprint changes).
• Add annotation/docstring adoption coverage: parameter, return, public docstrings, explicit Any.
• Add opt-in API surface inventory + baseline diff (snapshots, additions, breaking changes).
• Add coverage join (--coverage): per-function facts + findings for below-threshold or missing-in-scope functions;
  current-run only (not baseline truth, no fingerprint impact).
• Add golden_fixture_paths: exclude matching clone groups from health/gates while keeping suppressed facts.
• Add gates: --min-typing-coverage, --min-docstring-coverage, --fail-on-typing-regression, --fail-on-docstring-regression, --fail-on-api-break, --fail-on-untested-hotspots, --coverage-min.
• Surface adoption/API/coverage-join in MCP, CLI Metrics, report payloads, and HTML (Overview + Quality subtab).
• Preserve embedded metrics and optional api_surface in unified baselines.
• Cache 2.5: make analysis-profile compatibility API-surface-aware; invalidate stale non-API warm caches; preserve parameter order; align warm/cold API diffs.

MCP, HTML, and client interpretation

• Surface effective analysis profile in report meta, MCP summary/triage, and HTML subtitle.
• Add health_scope, focus, new_by_source_kind to MCP summary/triage.
• Make baseline mismatch explicit (python tags + no-valid-baseline signal).
• Surface Coverage Join facts and the optional coverage MCP help topic in the VS Code extension when the connected server supports them.
• Prefer workspace-local launchers over PATH (Poetry fallback).
• Add workspace_root to force project .venv selection.

Safety and maintenance

• Validate git_diff_ref as safe single-revision expressions.
• Replace segment digest repr() with canonical JSON bytes (determinism).
• Align CI coverage gate (fail_under = 99) and refresh actions/checkout pin.
• Refresh branch metadata/docs for 2.0.0b5; update README badge to 89 (B).

CodeClone 2.0.0b4: with first-class MCP, VS Code, Claude, and Codex surfaces

MCP server

• Add help(topic=...) tool for workflow guidance, baseline semantics, analysis profile, and review-state routing
  (tool count: 20 → 21).
• Add analysis_profile help topic for explicit conservative-first / deeper-review threshold guidance.
• Enrich _SERVER_INSTRUCTIONS with triage-first workflow, budget-aware drill-down, and conservative-first threshold
  guidance so MCP-capable clients receive structured behavioral context on connect.
• Optimize MCP payloads: short finding IDs (sha256-based for block clones), compact derived section projection,
  bounded metrics_detail with pagination.
• Fix MCP initialize metadata so serverInfo.version reports the CodeClone package version rather than the underlying
  mcp runtime version.

Report contract

• Bump canonical report schema to 2.3.
• Add metrics.overloaded_modules — report-only module-hotspot ranking by size, complexity, and coupling pressure.
• Surface Overloaded Modules across JSON, text/markdown, HTML, and MCP without affecting findings, health, or gates.
• Normalize the canonical family name and MCP/report output to overloaded_modules; god_modules remains accepted as a
  read-only MCP input alias during transition.

CLI and HTML

• Align CLI and HTML scope summaries with canonical inventory totals.
• Redesign Overview tab: Executive Summary becomes 2-column (Issue Breakdown + Source Breakdown) with scan scope in
  the section subtitle; Overloaded Modules section replaces the earlier stretched module-hotspot layout.

Documentation

• Add Health Score chapter: scoring inputs, report-only layers, phased expansion policy.
• Document that future releases may lower scores due to broader scoring model, not only worse code.

IDE and client integration (preview)

• Add VS Code extension (codeclone-mcp client) with baseline-aware triage, source drill-down, Explorer decorations,
  and HTML-report bridging.
• Add conservative, deeper-review, and custom analysis profiles to the VS Code extension and pass them through to MCP.
• Add limited Restricted Mode: onboarding works in untrusted workspaces, analysis stays gated until trust is granted.
• Add Node unit tests, extension-host smoke tests, and .vsix packaging.
• Tighten the VS Code extension to current VS Code UX guidance: one primary editor action, titled Quick Picks,
  per-view icons, non-button tree details, and a hard minimum local CodeClone version gate (>= 2.0.0b4).
• Add Claude Desktop .mcpb bundle wrapper for the local codeclone-mcp launcher with pre-loaded review instructions,
  explicit launcher settings, platform auto-discovery (macOS, Linux, Windows), local-stdio enforcement, signal
  forwarding, and deterministic package build smoke.
• Add a native Codex plugin with repo-local discovery metadata, bundled codeclone-mcp config, pre-loaded instructions,
  and two skills: conservative-first full review and quick hotspot discovery.

Internal

• Extract shared _json_io module for deterministic JSON serialization across baseline, cache, and report paths.
• Remove low-signal structural clone noise surfaced by stricter analysis passes without touching golden fixture debt.

CodeClone 2.0.0b3: MCP, UX and Platform Tightening

2.0.0b3 is the release where CodeClone stops looking like "a strong analyzer with extras" and starts looking like a coherent platform: canonical-report-first, agent-facing, CI-native, and product-grade.

Licensing & packaging

• Re-license source code to MPL-2.0 while keeping documentation under MIT.
• Ship dual LICENSE / LICENSE-docs files and sync SPDX headers.

MCP server (new)

• Add optional codeclone[mcp] extra with codeclone-mcp launcher (stdio and streamable-http).
• Introduce a read-only MCP surface with 20 tools, fixed resources, and run-scoped URIs for analysis, changed-files
  review, run comparison, findings / hotspots / remediation, granular checks, and gate preview.
• Add bounded run retention (--history-limit), --allow-remote guard, and reject cache_policy=refresh to preserve
  read-only semantics.
• Optimize MCP payloads for agents with short ids, compact summaries/cards, bounded metrics_detail, and slim
  changed-files / compare-runs responses — without changing the canonical report contract.
• Make MCP explicitly triage-first and budget-aware: clients are guided toward summary/triage → hotspots / check_* →
  single-finding drill-down instead of broad early listing.
• Add cache.freshness marker and get_production_triage / codeclone://latest/triage for compact production-first
  overview.
• Improve run-comparison honesty: compare_runs now reports mixed / incomparable, and clones_only runs surface
  health: unavailable instead of placeholder values.
• Harden repository safety: MCP analysis now requires an absolute repository root and rejects relative roots like .
  to avoid analyzing the wrong directory.
• Fix hotlist key resolution for production_hotspots and test_fixture_hotspots.
• Bump cache schema to 2.3 (stale metric entries rebuilt, not reused).

Report contract

• Bump canonical report schema to 2.2.
• Add canonical meta.analysis_thresholds.design_findings provenance and move threshold-aware design findings fully
  into the canonical report, so MCP and HTML read the same design-finding universe.
• Add derived.overview.directory_hotspots and render it in the HTML Overview tab as Hotspots by Directory.

CLI

• Add --changed-only, --diff-against, and --paths-from-git-diff for changed-scope review and gating with
  first-class summary output.

SARIF

• Stabilize primaryLocationLineHash (line numbers excluded), add run-unique automationDetails.id /
  startTimeUtc, set explicit kind: "fail", and move ancillary fields to properties.

HTML report

• Add Hotspots by Directory to the Overview tab, surfacing directory-level concentration for all, clones, and low-cohesion findings with scope-aware badges and compact counts.
• Add IDE picker (PyCharm, IDEA, VS Code, Cursor, Fleet, Zed) with persistent selection.
• Add clickable file-path deep links across all tabs and stable finding-{id} anchors.

GitHub Action

• Ship Composite Action v2 with configurable quality gates, SARIF upload to Code Scanning, and PR summary comments.

CodeClone 2.0.0b2: fix UI errors and update deps

Dependencies

• Upgrade requests (dev dep) to 2.33.0 for extract_zipped_paths security fix (CVE-2026-25645)

HTML

• Fix page-level horizontal scrolling in wide table tabs by constraining overflow to local table wrappers (#14).
• Fix mobile header brand block layout on narrow viewports (#15).
• Make mobile navigation tabs sticky and horizontally scrollable with scroll-shadow affordance.
• Keep Overview KPI micro-badges inside cards at extreme browser/mobile widths.
• Restyle Report Provenance summary badges to match the card-style badge language used across the report.