feat(mcp): deliver b3 diff-aware agent workflows, SARIF hardening, and changed-scope CLI UX

- add optional read-only MCP server with diff-aware analysis, compare-runs,
  remediation payloads, reviewed state, and stable resources
- complete b3 MCP and SARIF review spec work without changing baseline semantics
- add changed-scope CLI flags and render changed-scope as a first-class summary block
- add HTML IDE deep links and stable finding anchors for agent/IDE navigation
- sync docs, AGENTS, and changelog with the new MCP/CLI/report surface

Author: orenlab

AGENTS.md

@@ -61,6 +61,8 @@ Key artifacts:
 - `.cache/codeclone/cache.json` — analysis cache (integrity-checked)
 - `.cache/codeclone/report.html|report.json|report.md|report.sarif|report.txt` — reports
 - `codeclone-mcp` — optional read-only MCP server (install via `codeclone[mcp]`)
+- MCP runs are in-memory only; review markers are session-local and must never
+  leak into baseline/cache/report artifacts
 - `docs/`, `mkdocs.yml`, `.github/workflows/docs.yml` — published documentation site and docs build pipeline
 
 ---
@@ -170,6 +172,7 @@ Reports come in:
 
 MCP is a separate optional interface, not a report format. It must remain a
 read-only agent layer over the same canonical report/baseline/cache contracts.
+Session review markers are allowed only as ephemeral MCP process state.
 
 ### Report invariants
 
@@ -179,6 +182,10 @@ read-only agent layer over the same canonical report/baseline/cache contracts.
     - baseline fingerprint + schema versions
     - baseline generator version
     - cache path / cache used
+- SARIF `partialFingerprints.primaryLocationLineHash` must remain stable across
+  line-only shifts for the same finding identity.
+- SARIF `automationDetails.id` must be unique per run; result `kind` should be
+  explicit when emitted.
 
 ### Explainability contract (core owns facts)
 
@@ -256,6 +263,13 @@ Agents must preserve these semantics:
 - **3** — analysis gating failure (e.g., `--fail-threshold` exceeded or new clones in `--ci` as designed)
 - **5** — internal error (unexpected exception escaped top-level CLI handling)
 
+Changed-scope flags are contract-sensitive:
+
+- `--changed-only` keeps the canonical analysis/report full, but applies clone
+  summary/threshold evaluation to the changed-files projection.
+- `--diff-against` requires `--changed-only`.
+- `--paths-from-git-diff` implies `--changed-only`.
+
 If you introduce a new exit reason, document it and add tests.
 
 ---
@@ -349,7 +363,8 @@ Use this map to route changes to the right owner module.
 - `codeclone/report/*.py` (other modules) — deterministic projections/format transforms (
   text/markdown/sarif/derived/findings/suggestions); avoid injecting new analysis heuristics here.
 - `codeclone/mcp_service.py` — typed, in-process MCP service adapter over the current pipeline/report contracts; keep
-  it read-only and deterministic; do not move shell UX or `sys.exit` behavior here.
+  it deterministic; allow only session-local in-memory state such as reviewed markers, and never move shell UX or
+  `sys.exit` behavior here.
 - `codeclone/mcp_server.py` — optional MCP launcher/server wiring, transport config, and MCP tool/resource
   registration; keep dependency loading lazy so base installs/CI do not require MCP runtime packages.
 - `codeclone/html_report.py` — public HTML facade/re-export surface; preserve backward-compatible imports here; do not
@@ -453,6 +468,7 @@ Policy:
 - Canonical report JSON schema/payload semantics (`REPORT_SCHEMA_VERSION` contract family).
 - Documented report projections and their machine/user-facing semantics (HTML/Markdown/SARIF/Text).
 - Documented MCP launcher/install behavior, tool names, resource URIs, and read-only semantics.
+- Session-local MCP review state semantics (`mark_finding_reviewed`, `exclude_reviewed`) as documented public behavior.
 - Documented finding families/kinds/ids and suppression-facing report fields.
 - Metrics baseline schema/compatibility where used by CI/gating.
 - Benchmark schema/outputs if consumed as a reproducible contract surface.

CHANGELOG.md

@@ -6,7 +6,29 @@
 
 - Add optional `codeclone[mcp]` extra and `codeclone-mcp` launcher.
 - Add a deterministic, read-only MCP server over the canonical pipeline and report contracts.
-- Expose MCP tools/resources for repository analysis, run summaries, report sections, findings, hotlists, and gate previews.
+- Expose diff-aware MCP tools/resources for changed-files analysis, run comparison, report sections, findings,
+  remediation payloads, hotlists, granular checks, and gate previews.
+- Add stable MCP resources for latest-run summary/report/health/gates/changed projections and schema discovery.
+- Add session-local reviewed-finding state for long AI-agent workflows without mutating baseline or repo state.
+- Add stable HTML deep-link anchors (`finding-{finding_id}`) for clone and structural finding cards.
+
+### CLI
+
+- Add `--changed-only`, `--diff-against`, and `--paths-from-git-diff` for changed-scope clone review and gating over a
+  full canonical analysis.
+- Render changed-scope results as a first-class summary block in normal CLI output while keeping quiet mode compact.
+
+### SARIF
+
+- Stabilize `primaryLocationLineHash` across line-only shifts by hashing finding identity without line numbers.
+- Emit run-unique `automationDetails.id`, optional `startTimeUtc`, and explicit result `kind: "fail"`.
+- Move ancillary finding identity fields to SARIF `properties` and keep `partialFingerprints` minimal.
+
+### HTML
+
+- Add IDE picker with persistent selection (localStorage) supporting PyCharm, IntelliJ IDEA, VS Code, Cursor, Fleet, and
+  Zed.
+- Make file paths across Clones, Quality, Suggestions, Dead Code, and Findings tabs clickable IDE deep links.
 
 ## [2.0.0b2]
 

README.md

@@ -26,6 +26,13 @@ Docs: [orenlab.github.io/codeclone](https://orenlab.github.io/codeclone/) ·
 Live sample report:
 [orenlab.github.io/codeclone/examples/report/](https://orenlab.github.io/codeclone/examples/report/)
 
+> [!NOTE]
+> This README and docs site track the in-development `v2.0.x` line from `main`.
+> For the latest stable CodeClone documentation (`v1.4.4`), see the
+> [`v1.4.4` README](https://github.com/orenlab/codeclone/blob/v1.4.4/README.md)
+> and the
+> [`v1.4.4` docs tree](https://github.com/orenlab/codeclone/tree/v1.4.4/docs).
+
 ## Features
 
 - **Clone detection** — function (CFG fingerprint), block (statement windows), and segment (report-only) clones
@@ -48,6 +55,8 @@ codeclone . --html           # generate HTML report
 codeclone . --html --open-html-report   # generate and open HTML report
 codeclone . --json --md --sarif --text   # generate machine-readable reports
 codeclone . --html --json --timestamped-report-paths   # keep timestamped report snapshots
+codeclone . --changed-only --diff-against main   # changed-scope clone gating against git diff
+codeclone . --paths-from-git-diff HEAD~1         # shorthand diff source for changed-scope review
 codeclone . --ci             # CI mode (--fail-on-new --no-color --quiet)
 ```
 
@@ -80,8 +89,29 @@ For local command-based clients, prefer `stdio`. Use `streamable-http` only
 when the client expects a remote MCP endpoint.
 
 CodeClone MCP is read-only and baseline-aware. It exposes deterministic tools
-for analysis, summaries, findings, hotspots, report sections, and gate previews
-without mutating source files or baselines.
+for:
+
+- full repository analysis and changed-files analysis
+- run summaries and run-to-run comparison
+- findings, hotspots, remediation payloads, and PR summaries
+- granular clone / complexity / coupling / cohesion / dead-code checks
+- session-local review markers for long agent workflows
+
+It never mutates source files, baselines, or repo state.
+Diff-aware MCP calls use repo-relative `changed_paths` lists (or `git_diff_ref`)
+and may reuse the same `run_id` when the canonical report digest stays
+unchanged.
+Focused `check_*` MCP tools may trigger a full analysis first when no stored run
+exists yet.
+
+Latest-run resources are also available for MCP-capable clients:
+
+- `codeclone://latest/summary`
+- `codeclone://latest/report.json`
+- `codeclone://latest/health`
+- `codeclone://latest/gates`
+- `codeclone://latest/changed`
+- `codeclone://schema`
 
 Docs:
 [MCP interface contract](https://orenlab.github.io/codeclone/book/20-mcp-interface/)
@@ -240,6 +270,7 @@ Dynamic/runtime false positives are resolved via explicit inline suppressions, n
       "...": "..."
     },
     "runtime": {
+      "analysis_started_at_utc": "...",
       "report_generated_at_utc": "..."
     }
   },
@@ -329,20 +360,20 @@ CFG semantics: [CFG semantics](https://orenlab.github.io/codeclone/cfg/)
 
 ## Documentation
 
-| Topic                      | Link                                                                                               |
-|----------------------------|----------------------------------------------------------------------------------------------------|
-| Contract book (start here) | [Contracts and guarantees](https://orenlab.github.io/codeclone/book/00-intro/)                    |
-| Exit codes                 | [Exit codes and failure policy](https://orenlab.github.io/codeclone/book/03-contracts-exit-codes/) |
-| Configuration              | [Config and defaults](https://orenlab.github.io/codeclone/book/04-config-and-defaults/)           |
-| Baseline contract          | [Baseline contract](https://orenlab.github.io/codeclone/book/06-baseline/)                        |
-| Cache contract             | [Cache contract](https://orenlab.github.io/codeclone/book/07-cache/)                              |
-| Report contract            | [Report contract](https://orenlab.github.io/codeclone/book/08-report/)                            |
+| Topic                      | Link                                                                                                |
+|----------------------------|-----------------------------------------------------------------------------------------------------|
+| Contract book (start here) | [Contracts and guarantees](https://orenlab.github.io/codeclone/book/00-intro/)                      |
+| Exit codes                 | [Exit codes and failure policy](https://orenlab.github.io/codeclone/book/03-contracts-exit-codes/)  |
+| Configuration              | [Config and defaults](https://orenlab.github.io/codeclone/book/04-config-and-defaults/)             |
+| Baseline contract          | [Baseline contract](https://orenlab.github.io/codeclone/book/06-baseline/)                          |
+| Cache contract             | [Cache contract](https://orenlab.github.io/codeclone/book/07-cache/)                                |
+| Report contract            | [Report contract](https://orenlab.github.io/codeclone/book/08-report/)                              |
 | Metrics & quality gates    | [Metrics and quality gates](https://orenlab.github.io/codeclone/book/15-metrics-and-quality-gates/) |
-| Dead code                  | [Dead-code contract](https://orenlab.github.io/codeclone/book/16-dead-code-contract/)             |
-| Docker benchmark contract  | [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmarking/)                |
-| Determinism                | [Determinism policy](https://orenlab.github.io/codeclone/book/12-determinism/)                    |
+| Dead code                  | [Dead-code contract](https://orenlab.github.io/codeclone/book/16-dead-code-contract/)               |
+| Docker benchmark contract  | [Benchmarking contract](https://orenlab.github.io/codeclone/book/18-benchmarking/)                  |
+| Determinism                | [Determinism policy](https://orenlab.github.io/codeclone/book/12-determinism/)                      |
 
-## * Benchmarking
+##  * Benchmarking
 
 <details>
 <summary>Reproducible Docker Benchmark</summary>

codeclone/_cli_args.py

@@ -130,6 +130,23 @@ def build_parser(version: str) -> _ArgumentParser:
         default=DEFAULT_PROCESSES,
         help=ui.HELP_PROCESSES,
     )
+    _add_bool_optional_argument(
+        analysis_group,
+        flag="--changed-only",
+        help_text=ui.HELP_CHANGED_ONLY,
+    )
+    analysis_group.add_argument(
+        "--diff-against",
+        default=None,
+        metavar="GIT_REF",
+        help=ui.HELP_DIFF_AGAINST,
+    )
+    analysis_group.add_argument(
+        "--paths-from-git-diff",
+        default=None,
+        metavar="GIT_REF",
+        help=ui.HELP_PATHS_FROM_GIT_DIFF,
+    )
     _add_optional_path_argument(
         analysis_group,
         flag="--cache-path",

codeclone/_cli_meta.py

@@ -67,6 +67,7 @@ class ReportMeta(TypedDict):
     health_grade: str | None
     analysis_mode: str
     metrics_computed: list[str]
+    analysis_started_at_utc: str | None
     report_generated_at_utc: str
 
 
@@ -91,6 +92,7 @@ def _build_report_meta(
     health_grade: str | None,
     analysis_mode: str,
     metrics_computed: tuple[str, ...],
+    analysis_started_at_utc: str | None,
     report_generated_at_utc: str,
 ) -> ReportMeta:
     project_name = scan_root.name or str(scan_root)
@@ -133,5 +135,6 @@ def _build_report_meta(
         "health_grade": health_grade,
         "analysis_mode": analysis_mode,
         "metrics_computed": list(metrics_computed),
+        "analysis_started_at_utc": analysis_started_at_utc,
         "report_generated_at_utc": report_generated_at_utc,
     }

codeclone/_cli_summary.py

@@ -25,6 +25,14 @@ class MetricsSnapshot:
     suppressed_dead_code_count: int = 0
 
 
+@dataclass(frozen=True, slots=True)
+class ChangedScopeSnapshot:
+    paths_count: int
+    findings_total: int
+    findings_new: int
+    findings_known: int
+
+
 class _Printer(Protocol):
     def print(self, *objects: object, **kwargs: object) -> None: ...
 
@@ -149,3 +157,34 @@ def _print_metrics(
                 suppressed=metrics.suppressed_dead_code_count,
             )
         )
+
+
+def _print_changed_scope(
+    *,
+    console: _Printer,
+    quiet: bool,
+    changed_scope: ChangedScopeSnapshot,
+) -> None:
+    if quiet:
+        console.print(
+            ui.fmt_changed_scope_compact(
+                paths=changed_scope.paths_count,
+                findings=changed_scope.findings_total,
+                new=changed_scope.findings_new,
+                known=changed_scope.findings_known,
+            )
+        )
+        return
+
+    from rich.rule import Rule
+
+    console.print()
+    console.print(Rule(title=ui.CHANGED_SCOPE_TITLE, style="dim", characters="\u2500"))
+    console.print(ui.fmt_changed_scope_paths(count=changed_scope.paths_count))
+    console.print(
+        ui.fmt_changed_scope_findings(
+            total=changed_scope.findings_total,
+            new=changed_scope.findings_new,
+            known=changed_scope.findings_known,
+        )
+    )

codeclone/_html_css.py

@@ -1075,6 +1075,11 @@
   .theme-toggle{font-size:0;gap:0;width:32px;height:32px;
     padding:0;align-items:center;justify-content:center}
   .theme-toggle svg{width:16px;height:16px}
+  .ide-picker-btn{font-size:0;gap:0;width:32px;height:32px;
+    padding:0;align-items:center;justify-content:center}
+  .ide-picker-btn svg{width:16px;height:16px}
+  .ide-picker-label{display:none}
+  .ide-menu{right:0;min-width:140px}
   .main-tabs-wrap{position:sticky;top:0;z-index:90;padding:var(--sp-2) 0 0}
   .main-tabs{padding:var(--sp-1);gap:2px;
     background:
@@ -1091,10 +1096,41 @@
   .brand-logo{width:28px;height:28px}
 }
 
+/* IDE link */
+.ide-link{color:inherit;text-decoration:none;cursor:default}
+[data-ide]:not([data-ide=""]) .ide-link{cursor:pointer;color:var(--accent-primary);
+  text-decoration-line:underline;text-decoration-style:dotted;text-underline-offset:2px}
+[data-ide]:not([data-ide=""]) .ide-link:hover{text-decoration-style:solid}
+
+/* IDE picker dropdown */
+.ide-picker{position:relative;display:inline-flex}
+.ide-picker-btn{display:inline-flex;align-items:center;gap:var(--sp-1);
+  padding:var(--sp-1) var(--sp-3);background:none;border:1px solid var(--border);
+  border-radius:var(--radius-md);cursor:pointer;color:var(--text-muted);font-size:.85rem;
+  font-weight:500;font-family:inherit;transition:all var(--dur-fast) var(--ease);
+  white-space:nowrap}
+.ide-picker-btn:hover{color:var(--text-primary);background:var(--bg-raised);border-color:var(--border-strong)}
+.ide-picker-btn svg{width:16px;height:16px;flex-shrink:0}
+.ide-picker-btn[aria-expanded="true"]{color:var(--accent-primary);border-color:var(--accent-primary)}
+.ide-menu{display:none;position:absolute;top:100%;right:0;margin-top:var(--sp-1);
+  min-width:160px;background:var(--bg-surface);border:1px solid var(--border);
+  border-radius:var(--radius);box-shadow:0 4px 12px rgba(0,0,0,.15);
+  z-index:100;padding:var(--sp-1) 0;list-style:none}
+.ide-menu[data-open]{display:block}
+.ide-menu li{padding:0}
+.ide-menu button{display:flex;align-items:center;gap:var(--sp-2);width:100%;
+  padding:var(--sp-1) var(--sp-3);background:none;border:none;color:var(--text-primary);
+  font-size:.8rem;font-family:var(--font-sans);cursor:pointer;text-align:left}
+.ide-menu button:hover{background:var(--bg-alt)}
+.ide-menu button[aria-checked="true"]{color:var(--accent-primary);font-weight:600}
+.ide-menu button[aria-checked="true"]::before{content:'\\2713';font-size:.7rem;
+  width:14px;text-align:center;flex-shrink:0}
+.ide-menu button[aria-checked="false"]::before{content:'';width:14px;flex-shrink:0}
+
 /* Print */
 @media print{
   .topbar,.toolbar,.pagination,.theme-toggle,.toast-container,
-  .novelty-tabs,.clear-btn,.btn{display:none!important}
+  .novelty-tabs,.clear-btn,.btn,.ide-picker{display:none!important}
   .tab-panel{display:block!important;break-inside:avoid}
   .group-body{display:block!important}
   body{background:#fff;color:#000}