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

Author: orenlab

AGENTS.md

@@ -92,8 +92,11 @@ uv run pytest -q tests/test_mcp_service.py tests/test_mcp_server.py
 If you touched the VS Code extension surface, also run:
 
 ```bash
+node --check extensions/vscode-codeclone/src/support.js
 node --check extensions/vscode-codeclone/src/mcpClient.js
 node --check extensions/vscode-codeclone/src/extension.js
+node --test extensions/vscode-codeclone/test/*.test.js
+node extensions/vscode-codeclone/test/runExtensionHost.js
 ```
 
 If you touched VS Code extension packaging metadata (`package.json`,
@@ -102,7 +105,7 @@ smoke:
 
 ```bash
 cd extensions/vscode-codeclone
-NPM_CONFIG_CACHE=/tmp/codeclone-vsce-cache npx @vscode/vsce package --pre-release --out /tmp/codeclone.vsix
+vsce package --pre-release --out /tmp/codeclone.vsix
 ```
 
 ---
@@ -458,7 +461,7 @@ If you change a contract-sensitive zone, route docs/tests/approval deliberately.
 | Fingerprint-adjacent analysis (`extractor/cfg/normalize/grouping`)                                                                  | `docs/book/05-core-pipeline.md`, `docs/cfg.md`, `docs/book/14-compatibility-and-versioning.md`, `CHANGELOG.md`                                                      | `tests/test_fingerprint.py`, `tests/test_extractor.py`, `tests/test_cfg.py`, golden tests (`tests/test_detector_golden.py`, `tests/test_golden_v2.py`)              | always (see Section 1.6)                                                                     | clone identity / NEW-vs-KNOWN / fingerprint inputs change                                     |
 | Suppression semantics/reporting (`suppressions`, extractor dead-code wiring, report/UI counters)                                    | `docs/book/19-inline-suppressions.md`, `docs/book/16-dead-code-contract.md`, `docs/book/08-report.md`, and interface docs if surfaced (`09-cli`, `10-html-render`)  | `tests/test_suppressions.py`, `tests/test_extractor.py`, `tests/test_metrics_modules.py`, `tests/test_pipeline_metrics.py`, report/html/cli tests                   | declaration scope semantics, rule effect, or contract-visible counters/fields change         | suppression changes alter active finding output or contract-visible report payload            |
 | MCP interface (`codeclone/mcp_service.py`, `codeclone/mcp_server.py`, packaging extra/launcher)                                     | `README.md`, `docs/book/20-mcp-interface.md`, `docs/mcp.md`, `docs/book/01-architecture-map.md`, `docs/book/14-compatibility-and-versioning.md`, `CHANGELOG.md`     | `tests/test_mcp_service.py`, `tests/test_mcp_server.py`, plus CLI/package tests if launcher/install semantics change                                                | tool/resource shapes, read-only semantics, optional-dependency packaging behavior change     | public MCP tool names, resource URIs, launcher/install behavior, or response semantics change |
-| VS Code extension surface (`extensions/vscode-codeclone/*`)                                                                         | `README.md`, `docs/book/21-vscode-extension.md`, `docs/vscode-extension.md`, `docs/book/01-architecture-map.md`, `docs/README.md`, `CHANGELOG.md`                   | `node --check extensions/vscode-codeclone/src/mcpClient.js`, `node --check extensions/vscode-codeclone/src/extension.js`; package smoke when manifest/assets change | command/view UX, trust/runtime model, source-first review flow, or packaging metadata change | documented commands/views/setup/trust behavior, packaged assets, or publish metadata change   |
+| VS Code extension surface (`extensions/vscode-codeclone/*`)                                                                         | `README.md`, `docs/book/21-vscode-extension.md`, `docs/vscode-extension.md`, `docs/book/01-architecture-map.md`, `docs/README.md`, `CHANGELOG.md`                   | `node --check extensions/vscode-codeclone/src/support.js`, `node --check extensions/vscode-codeclone/src/mcpClient.js`, `node --check extensions/vscode-codeclone/src/extension.js`, `node --test extensions/vscode-codeclone/test/*.test.js`, plus local extension-host smoke and package smoke when surface/manifest/assets change | command/view UX, trust/runtime model, source-first review flow, or packaging metadata change | documented commands/views/setup/trust behavior, packaged assets, or publish metadata change   |
 | Docs site / sample report publication (`docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`, `scripts/build_docs_example_report.py`) | `docs/README.md`, `docs/publishing.md`, `docs/examples/report.md`, and any contract pages surfaced by the change, `CHANGELOG.md` when user-visible behavior changes | `mkdocs build --strict`, sample-report generation smoke path, and relevant report/html tests if generated examples or embeds change                                 | published docs navigation, sample-report generation, or Pages workflow semantics change      | published documentation behavior or sample-report generation contract changes                 |
 
 Golden rule: do not “fix” failures by snapshot refresh unless the underlying contract change is intentional, documented,

CHANGELOG.md

@@ -3,9 +3,8 @@
 ## [2.0.0b4]
 
 2.0.0b4 deepens the platform model introduced in b3: MCP becomes more self-guiding, report-only analysis expands with
-module-level hotspot ranking, findings and suggestions are separated more cleanly by role, and Health Score
-documentation now formalizes how new signal families can be introduced gradually without pretending the scoring model is
-static.
+module-level hotspot ranking, findings and suggestions are separated more cleanly by role, Health Score documentation
+now formalizes phased score-model evolution, and CodeClone gains its first native IDE surface in preview.
 
 ### MCP server
 
@@ -36,8 +35,13 @@ static.
 
 ### IDE integration
 
-- Add a preview VS Code extension as a native, read-only control surface over `codeclone-mcp`, with baseline-aware,
-  triage-first review flow, guided source-first drill-down, and explicit setup/session semantics.
+- Add a preview VS Code extension as the first native IDE surface for `codeclone-mcp`, bringing baseline-aware,
+  triage-first structural review and guided source-first drill-down into the editor.
+- Establish the initial extension interaction model, including explicit setup/session semantics, review-loop navigation,
+  hotspot focus persistence, lightweight Explorer decorations, safe HTML-report bridging, and accessibility/status
+  polish.
+- Add extension-side regression coverage with Node unit tests, local extension-host smoke, and validated preview `.vsix`
+  packaging.
 
 ## [2.0.0b3] - 20260401
 

README.md

@@ -200,6 +200,16 @@ It is:
 - triage-first
 - read-only with respect to repository state
 - powered by the same `codeclone-mcp` contract surface
+- limited in Restricted Mode until workspace trust is granted
+
+It focuses on source-first structural review inside the editor: overview,
+hotspots, review loop, changed-files pass, and explicit drill-down into finding,
+remediation, or local HTML report when needed.
+
+Docs:
+[VS Code extension guide](https://orenlab.github.io/codeclone/vscode-extension/)
+·
+[VS Code extension contract](https://orenlab.github.io/codeclone/book/21-vscode-extension/)
 
 ## Configuration
 

docs/book/01-architecture-map.md

@@ -13,7 +13,8 @@ Main ownership layers:
 - Contracts and persistence: baseline, metrics baseline, cache, exit semantics.
 - Report model and projections: canonical JSON + deterministic TXT/Markdown/SARIF + explainability facts.
 - MCP agent surface: read-only server layer over the same pipeline/report contracts.
-- VS Code extension surface: native IDE client over the MCP layer and the same canonical report semantics.
+- VS Code extension surface: native IDE client over the MCP layer and the same canonical report semantics, with
+  limited Restricted Mode and source-first review flow.
 - Render layer: HTML rendering and template assets.
 
 ## Data model
@@ -30,7 +31,7 @@ Main ownership layers:
 | Persistence           | `codeclone/baseline.py`, `codeclone/metrics_baseline.py`, `codeclone/cache.py`                                                                                                                     | Baseline/cache trust/compat/integrity and atomic persistence                                    |
 | Runtime orchestration | `codeclone/pipeline.py`, `codeclone/cli.py`, `codeclone/_cli_args.py`, `codeclone/_cli_paths.py`, `codeclone/_cli_summary.py`, `codeclone/_cli_config.py`, `codeclone/ui_messages.py`              | CLI UX, stage orchestration, status handling, outputs, error markers                            |
 | MCP agent interface   | `codeclone/mcp_service.py`, `codeclone/mcp_server.py`                                                                                                                                              | Read-only MCP tools/resources over canonical analysis and report layers                         |
-| VS Code extension     | `extensions/vscode-codeclone/*`                                                                                                                                                                    | Native VS Code control surface over MCP, with triage-first review and source-first drill-down   |
+| VS Code extension     | `extensions/vscode-codeclone/*`                                                                                                                                                                    | Native VS Code control surface over MCP, with limited Restricted Mode, triage-first review, and source-first drill-down |
 | Rendering             | `codeclone/html_report.py`, `codeclone/_html_report/*`, `codeclone/_html_badges.py`, `codeclone/_html_js.py`, `codeclone/_html_escape.py`, `codeclone/_html_snippets.py`, `codeclone/templates.py` | HTML-only view layer over report data                                                           |
 
 Refs:

docs/book/21-vscode-extension.md

@@ -16,6 +16,7 @@ The VS Code extension is:
 - read-only with respect to repository state
 - baseline-aware and triage-first
 - code-centered rather than report-dashboard-centered
+- limited in Restricted Mode and fully active only after workspace trust
 
 The extension exists to make the current CodeClone review workflow easier to
 use inside the editor. It must not reinterpret report semantics or invent
@@ -49,7 +50,9 @@ It also provides:
 - command palette entry points for analysis and review
 - one onboarding walkthrough
 - markdown detail panels for findings, remediation, help topics, setup help,
-  and report-only God Module detail
+  restricted-mode guidance, and report-only God Module detail
+- lightweight Explorer file decorations for review-relevant files
+- editor-local CodeLens and title actions for the active review target
 
 ## Workflow model
 
@@ -64,6 +67,23 @@ The intended IDE path mirrors CodeClone MCP:
 This is deliberately different from a lint-list model. The extension should
 prefer guided review over broad enumeration.
 
+## Current capabilities
+
+The extension currently supports:
+
+- full-workspace analysis
+- changed-files analysis against a configured git diff reference
+- compact overview of structural health, current run state, and baseline drift
+- review queues for new regressions, production hotspots, changed-scope
+  findings, and report-only `God Modules`
+- source reveal, peek, canonical finding detail, remediation detail, and
+  session-local reviewed markers
+- bounded MCP help topics inside the IDE
+- explicit HTML-report bridge when a local HTML report already exists
+
+These capabilities must remain clients of MCP and canonical report truth rather
+than parallel extension-only logic.
+
 ## State boundaries
 
 The extension must keep three state classes visibly separate:
@@ -92,16 +112,34 @@ Reviewed markers:
 
 The extension runs as a workspace extension and requires:
 
-- a trusted workspace
 - local filesystem access
 - local git access for changed-files review
 - a local `codeclone-mcp` launcher, or an explicitly configured launcher
 
 For this reason:
 
-- untrusted workspaces are unsupported
+- Restricted Mode support is `limited`
+- untrusted workspaces may show setup/onboarding/help surfaces only
+- local analysis and local MCP startup remain disabled until trust is granted
 - virtual workspaces are unsupported
 
+## Design decisions
+
+The extension follows these implementation rules:
+
+- **Native VS Code first**: tree views, status bar, Quick Pick, CodeLens, and
+  file decorations come before any richer custom UI.
+- **Source-first review**: findings prefer `Reveal Source` over immediate
+  detail panels.
+- **Explicit deepening**: canonical finding detail, remediation, and HTML
+  report bridges remain opt-in actions.
+- **Report-only separation**: `God Modules` stay clearly outside findings,
+  gates, and health dimensions.
+- **Safe local HTML bridge**: `Open in HTML Report` must verify that a local
+  `report.html` exists and is not obviously older than the current run.
+- **Session-local workflow state**: reviewed markers may shape the review UX
+  but must not leak into repository truth.
+
 ## UX rules
 
 The extension should preserve these product rules:
@@ -114,6 +152,10 @@ The extension should preserve these product rules:
   findings, gates, and health dimensions.
 - The extension should minimize noise and avoid duplicating the HTML report in
   the sidebar.
+- Restricted Mode should still explain what the extension needs, without
+  pretending local analysis is available before trust is granted.
+- Accessibility labels should stay meaningful on tree items and status
+  surfaces.
 
 ## Relationship to other interfaces
 
@@ -127,3 +169,5 @@ The extension should preserve these product rules:
 - Exact view grouping and copy may evolve between beta releases.
 - Internal client-side caching and view-model shaping may evolve as long as the
   extension remains faithful to MCP and canonical report semantics.
+- Explorer decoration styling, review-loop polish, and other non-contract UI
+  details may evolve without changing the extension contract.

docs/vscode-extension.md

@@ -6,7 +6,7 @@ CodeClone ships a preview VS Code extension in
 It is a native IDE surface over `codeclone-mcp` and is designed for
 baseline-aware, triage-first structural review inside the editor.
 
-## What it does
+## What it is for
 
 The extension helps you:
 
@@ -15,6 +15,7 @@ The extension helps you:
 - focus on new regressions and production hotspots first
 - jump directly to source locations
 - open canonical finding or remediation detail only when needed
+- inspect report-only God Module candidates without treating them like findings
 
 It does not create a second truth model and it does not mutate the repository.
 
@@ -44,7 +45,7 @@ codeclone-mcp --help
 
 ### Overview
 
-Compact health, current run state, and next-best review action.
+Compact health, current run state, baseline drift, and next-best review action.
 
 ### Hotspots
 
@@ -64,6 +65,21 @@ Session-local state:
 - reviewed findings
 - MCP help topics
 
+## Review model
+
+The extension stays source-first:
+
+- `Review Priorities` and `Next Hotspot` / `Previous Hotspot` drive the review
+  loop
+- `Reveal Source` is the default action for findings
+- editor-local actions appear only when the current file matches the active
+  review target
+- Explorer decorations stay lightweight and focus on new, production, or
+  changed-scope relevance
+
+`Open in HTML Report` exists as an explicit bridge to the richer human report,
+not as the primary IDE workflow.
+
 ## First-run path
 
 1. Open the `CodeClone` view container.
@@ -75,12 +91,32 @@ If the launcher is missing, use `Setup Help` from the extension.
 
 ## Trust model
 
-The extension requires a trusted local workspace and is not intended for
-virtual workspaces.
+The extension uses a **limited Restricted Mode**:
+
+- onboarding and setup help remain available in untrusted workspaces
+- local analysis and the local MCP server stay disabled until workspace trust
+  is granted
+
+The extension is not intended for virtual workspaces.
 
 That is intentional: CodeClone reads repository contents, local git state, and
 the local MCP launcher.
 
+## Design decisions
+
+- native VS Code views first, not a custom report dashboard
+- baseline-aware review instead of broad lint-style listing
+- report-only layers stay visually separate from findings and health
+- repository truth stays in CodeClone MCP and canonical report semantics
+
+## Current limits
+
+- no always-on background analysis
+- no `Problems`-panel duplication
+- no persistent reviewed markers across MCP sessions
+- `Open in HTML Report` opens a local HTML report only when it exists and looks
+  fresh enough for the current run
+
 ## Source of truth
 
 The extension reads the same canonical analysis semantics already exposed by:

extensions/vscode-codeclone/.vscodeignore

@@ -4,3 +4,4 @@ DESIGN.md
 media/.thumb/**
 media/icon-source.svg
 *.vsix
+test/**