Ship CodeClone 2.0.0b4 with first-class MCP, VS Code, Claude, and Codex surfaces (#19)

* feat(mcp): add help tool for cheaper, more guided agent workflows

* feat(report): add report-only god modules and tighten MCP, health, and UX semantics

- add canonical `metrics.families.god_modules` as a report-only layer and surface it in JSON, CLI, HTML, and MCP without affecting health, gates, or findings
- tighten findings vs suggestions semantics for low-signal structural hints and keep action guidance inline where separate suggestions add no real value
- align CLI and HTML scope/inventory presentation with canonical report semantics and polish overview/God Modules rhythm
- add dedicated Health Score documentation, clarify phased health-model expansion, and document unified metrics-baseline behavior
- refresh MCP guidance/help wording and GitHub issue templates for the current b4 surface

* feat(vscode): add a publish-ready CodeClone VS Code extension and document it as a first-class surface

- add a native VS Code client over codeclone-mcp with baseline-aware, triage-first structural review and guided source-first drill-down
- stabilize extension lifecycle and setup UX with local launcher verification, fallback connection handling, review-focused hotspots, and human-readable command surfaces
- add CodeClone-native branding and marketplace-ready packaging assets, including a proper extension icon and validated .vsix packaging
- document the new VS Code interface across README, docs, contracts book, changelog, and issue-routing guidance
- update AGENTS.md to reflect the VS Code extension as a public surface and align validation/module-routing rules with the current codebase

* feat(vscode): harden the VS Code surface and document it as a first-class contract

- mature the preview VS Code extension into a safer, enterprise-grade MCP client with limited Restricted Mode, source-first review flow, persisted focus state, bounded transport handling, and a safer local HTML bridge
- add extension-side regression coverage with Node unit tests, local extension-host smoke, and validated preview VSIX packaging
- document the extension consistently across README, docs, the contracts book, changelog, and AGENTS with its current capabilities, design decisions, trust model, and limits

* feat(vscode): harden the VS Code client with trust-aware UX, safer launcher/runtime handling, and tested review workflows

* feat(vscode,report): rename overloaded modules canonically and harden the VS Code surface

* feat(vscode): add profile-aware review workflows and harden the VS Code extension lifecycle

- add conservative, deeper-review, and custom analysis profiles to the VS Code extension and pass them through to CodeClone MCP
- improve review UX with clearer analysis-depth affordances, conservative-first guidance, and profile-aware overview/session state
- harden extension lifecycle and resource handling with safer shutdown, single-flight MCP connection reuse, and cleanup of workspace/session state
- expand extension-side regression coverage and refresh VS Code extension docs to match the current behavior

* feat(mcp,report): harden core contracts, cleanup structural noise, and tighten MCP guidance

- implement the audit-driven cleanup across baseline/cache/report/html internals with shared JSON IO, safer normalization and path handling, and cleaner structural rendering boundaries
- remove safe non-golden structural and clone noise surfaced by stricter analysis passes without touching golden fixture debt
- strengthen MCP semantics with conservative-first threshold guidance, the new analysis_profile help topic, and tighter workflow/help wording
- refresh core docs and contract tests for baseline, report, MCP, and stricter analysis behavior

* feat(claude): make the Claude Desktop bundle

* feat(codex): add a native CodeClone plugin for Codex MCP review

* refactor(tests): split the golden v2 dummy executor into a narrower inline stub and update baseline

* feat(clients,docs): polish native client surfaces and harden the Claude bundle startup flow

* docs(clients): standardize uv installs and tighten Codex MCP-only guardrails

* feat(clients): harden MCP client surfaces and polish prerelease UX for b4

- make MCP initialize metadata report the CodeClone package version so clients can enforce runtime compatibility correctly
- harden the VS Code extension with a minimum supported CodeClone gate, uv-based setup guidance, moved-view icons, titled quick picks, and leaner editor actions aligned with current VS Code UX guidance
- improve the Claude Desktop bundle startup path and launcher handling, with refreshed tests and packaging flow
- refresh README, MCP/client docs, changelog, and related CI-facing metadata around the current VS Code, Claude, and Codex surfaces

* feat(vscode): improve launcher clarity, range-aware source reveal, and marketplace readiness

- make unsupported CodeClone runtime errors explain which launcher the extension resolved and whether it came from the workspace, explicit settings, PATH, or repo-local uv fallback
- document that auto launcher resolution prefers the current workspace virtualenv before falling back to PATH
- fix source reveal for clone review by hydrating canonical finding detail when summary locations are range-truncated, so block and segment findings reveal the full span instead of only the first line
- bump the preview VS Code extension to 0.2.1, refresh packaged metadata, and add the live Marketplace listing across the repo and extension docs

Author: orenlab

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "orenlab-local",
+  "interface": {
+    "displayName": "OrenLab Local Plugins"
+  },
+  "plugins": [
+    {
+      "name": "codeclone",
+      "source": {
+        "source": "local",
+        "path": "./plugins/codeclone"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

.dockerignore

@@ -18,3 +18,4 @@ docs
 codeclone.egg-info
 .pre-commit-config.yaml
 uv.lock
+extensions

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,5 +1,5 @@
 name: 🐞 Bug report
-description: Incorrect clone detection, crashes, or broken reports
+description: Incorrect analysis results, crashes, broken reports, or contract regressions
 title: "[Bug]: "
 labels: [ "bug" ]
 assignees: [ ]
@@ -16,7 +16,7 @@ body:
     attributes:
       label: CodeClone version
       description: Output of `codeclone --version`
-      placeholder: "1.1.0"
+      placeholder: "2.0.0b4"
     validations:
       required: true
 
@@ -26,11 +26,17 @@ body:
       label: Affected area
       options:
         - Function clone detection (Type-2)
-        - Block clone detection (Type-3-lite)
+        - Block clone detection
+        - Segment clone reporting
+        - Structural findings
+        - Quality metrics / health
         - CFG construction
         - AST normalization
+        - Canonical report / JSON
         - HTML report
-        - CLI / baseline
+        - CLI / baseline / cache
+        - GitHub Action / CI
+        - MCP server
     validations:
       required: true
 
@@ -62,4 +68,4 @@ body:
     id: notes
     attributes:
       label: Additional context
-      description: CFG structure, HTML screenshots, logs, etc.
+      description: Baseline/cache status, HTML screenshots, MCP payloads, logs, etc.

.github/ISSUE_TEMPLATE/cfg_semantics.yml

@@ -15,7 +15,7 @@ body:
     id: version
     attributes:
       label: CodeClone version
-      placeholder: "1.1.0"
+      placeholder: "2.0.0b4"
 
   - type: textarea
     id: scenario

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: CodeClone Docs
+    url: https://orenlab.github.io/codeclone/
+    about: Read the contracts book, MCP guide, and interface docs before opening a generic usage question.

.github/ISSUE_TEMPLATE/false_positive.yml

@@ -15,15 +15,27 @@ body:
     id: version
     attributes:
       label: CodeClone version
-      placeholder: "1.1.0"
+      placeholder: "2.0.0b4"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: family
+    attributes:
+      label: Detection family
+      options:
+        - Function clone
+        - Block clone
+        - Segment clone (report-only)
+        - Structural finding
     validations:
       required: true
 
   - type: textarea
     id: code
     attributes:
-      label: Code snippets detected as clones
-      description: Paste both snippets or a reduced example
+      label: Minimal reproduction
+      description: Paste both snippets, the reduced example, or the relevant finding evidence
       render: python
     validations:
       required: true
@@ -38,9 +50,11 @@ body:
     validations:
       required: true
 
-  - type: checkbox
+  - type: checkboxes
     id: cfg_related
     attributes:
-      label: CFG-related?
+      label: Additional signals
       options:
         - label: Control flow structure differs meaningfully
+        - label: Side effects or runtime behavior differ meaningfully
+        - label: The issue appears only in tests / fixtures

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,8 +1,8 @@
 name: ✨ Feature request
 description: Propose an enhancement to CodeClone
 title: "[Feature]: "
-labels: ["enhancement"]
-assignees: []
+labels: [ "enhancement" ]
+assignees: [ ]
 
 body:
   - type: markdown
@@ -18,9 +18,22 @@ body:
         - Clone detection logic
         - CFG semantics
         - AST normalization
+        - Structural findings / suggestions
+        - Metrics / health model
+        - Canonical report / contracts
         - HTML report / UX
         - CLI / CI integration
+        - MCP server / agent workflow
         - Performance
+        - Documentation
+    validations:
+      required: true
+
+  - type: textarea
+    id: user_impact
+    attributes:
+      label: Why is this worth adding?
+      description: What concrete workflow, quality, or UX problem would this solve?
     validations:
       required: true
 
@@ -44,3 +57,14 @@ body:
     id: alternatives
     attributes:
       label: Alternatives considered
+
+  - type: checkboxes
+    id: contracts
+    attributes:
+      label: Contract-sensitive areas
+      description: Tick any surfaces you believe this may affect.
+      options:
+        - label: Baseline / cache compatibility
+        - label: Canonical report JSON schema
+        - label: CLI exit codes or script-facing output
+        - label: MCP tool or resource semantics

.github/ISSUE_TEMPLATE/mcp_server.yml

@@ -0,0 +1,75 @@
+name: MCP server
+description: Report an MCP bug or propose an MCP workflow/tooling improvement
+title: "[MCP]: "
+labels: [ "mcp" ]
+assignees: [ ]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for issues about the **CodeClone MCP server**:
+        tools, resources, payload shape, routing, session semantics, root handling,
+        IDE/MCP client behavior, and agent-facing workflow quality.
+
+  - type: input
+    id: version
+    attributes:
+      label: CodeClone version
+      description: Output of `codeclone --version`
+      placeholder: "2.0.0b4"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: MCP category
+      options:
+        - Tool behavior
+        - Resource behavior
+        - Payload size / shape
+        - Session / latest-runs semantics
+        - Root / safety semantics
+        - Guidance / workflow routing
+        - Packaging / launcher / transport
+    validations:
+      required: true
+
+  - type: textarea
+    id: client
+    attributes:
+      label: MCP client or host
+      description: Codex, Claude Desktop, Cursor, VS Code, custom client, etc.
+      placeholder: "Codex desktop / stdio"
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: Describe the current MCP behavior and why it is wrong or awkward.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What should happen instead?
+      description: Focus on the safest and most budget-aware expected behavior.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction or request sequence
+      description: |
+        Include the relevant tool/resource calls when possible.
+        Small, exact examples are preferred over screenshots.
+      render: json
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional context
+      description: Payload excerpts, error text, screenshots, or workflow notes.

.github/actions/codeclone/README.md

@@ -149,7 +149,7 @@ Explicit prerelease:
 
 ```yaml
 with:
-  package-version: "2.0.0b3"
+  package-version: "2.0.0b4"
 ```
 
 Local/self-repo validation:

.github/workflows/codeclone.yml

@@ -2,8 +2,8 @@ name: CodeClone
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
-    paths: ["**/*.py"]
+    types: [ opened, synchronize, reopened ]
+    paths: [ "**/*.py" ]
 
 permissions:
   contents: read