From abaf23d2b36933d29e4a068e25bd2c5f4ae2e065 Mon Sep 17 00:00:00 2001
From: Mary Georgiou <mary.georgiou@sonarsource.com>
Date: Thu, 20 Aug 2026 11:03:25 +0200
Subject: [PATCH] Integrate Vortex (SonarQube agentic analysis) protocol

Ports SonarSource/gh-action-lt-backlog#408. Project key used: org.sonarsource.java:java (verified).
---
 .claude/CLAUDE.md | 31 +++++++++++++++++++++++++++++++
 .mcp.json         | 13 +++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 .claude/CLAUDE.md
 create mode 100644 .mcp.json

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 00000000000..c692aad9fbe
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,31 @@
+<!-- sonar:begin:sonarqube-agentic-analysis-protocol -->
+# Vortex analysis protocol
+
+Vortex analysis is the final confirmation layer at the end of every turn in which you wrote to one or more files in the workspace (create, edit, patch, format — any tool call that changed file contents on disk).
+
+**Trigger:** the moment before you send your final reply for the turn.
+
+When the trigger fires, you **MUST** run Vortex analysis on the full set of files you modified this turn — **one command, not a per-file loop**.
+
+**Preferred:** pass every path you modified this turn in a single invocation (repeat `--file` for each path). Use paths **relative to the project root** (e.g. `src/foo.ts`). For end-of-turn analysis, **always** pass `--depth DEEP` — even when you changed only one file — so cross-file findings are included.
+
+```bash
+sonar analyze agentic --project org.sonarsource.java:java --depth DEEP --file <path/to/file1> --file <path/to/file2>
+```
+
+**Fallback:** when you cannot reliably list every modified path (e.g. you did not track them, or git state is the only source of truth), use the git change set with DEEP analysis:
+
+```bash
+sonar analyze agentic --project org.sonarsource.java:java --depth DEEP
+```
+
+Per-edit hooks run faster STANDARD analysis. End-of-turn analysis must always use `--depth DEEP` (including a single `--file`). Use `--depth STANDARD` only for optional faster passes — never for the mandatory end-of-turn run.
+
+Non-negotiable rules:
+
+1. Mid-turn edits do **not** need Vortex analysis — only the final on-disk state matters. Skipping Vortex analysis at end-of-turn is a protocol violation.
+2. Run Vortex analysis **before** sending your final reply, marking the task done, or handing control back to the user.
+3. If Vortex analysis reports issues on lines you touched in this turn, fix them, then re-run Vortex analysis on the same scope (change set or explicit file list). Repeat until clean (or only pre-existing findings on lines you did not touch remain). Pre-existing findings on untouched lines are out of scope — do not "fix" them unless the user asked.
+4. If Vortex analysis is skipped (no SonarQube Cloud connection, or no project configured), state the skip reason to the user once and continue — do not retry.
+5. Do not suppress, summarize away, or omit Vortex analysis findings from your reply. Surface them verbatim.
+<!-- sonar:end:sonarqube-agentic-analysis-protocol -->
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 00000000000..a60b72cc6e0
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "sonarqube": {
+      "command": "sonar",
+      "args": [
+        "run",
+        "mcp",
+        "--project",
+        "org.sonarsource.java:java"
+      ]
+    }
+  }
+}