@codyswann/lisa 2.296.1 → 2.297.1

package/dist/sonar/sonar-installer.d.ts

@@ -0,0 +1,19 @@
+/** Result of the apply-time Sonar integrate pass. */
+export interface SonarIntegrateResult {
+    /** True when the project opted in via `verification.sonar.enabled`. */
+    readonly enabled: boolean;
+    /** True when opted in AND the `sonar` CLI was on PATH (integrate attempted). */
+    readonly attempted: boolean;
+    /** Vendor agent names whose `sonar integrate` exited zero. */
+    readonly integrated: readonly string[];
+    /** Vendor agent names whose `sonar integrate` failed. */
+    readonly failed: readonly string[];
+}
+/**
+ * Wire the official SonarQube MCP into each supported agent via `sonar integrate`.
+ * @param projectRoot - Downstream project root (holds `.lisa.config.json`)
+ * @param vendorAgents - Vendor agent names to integrate, derived from the harness
+ * @returns Integrate result describing opt-in, attempt, and per-agent outcomes
+ */
+export declare function installSonarIntegrations(projectRoot: string, vendorAgents: readonly string[]): Promise<SonarIntegrateResult>;
+//# sourceMappingURL=sonar-installer.d.ts.map

package/dist/sonar/sonar-installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sonar-installer.d.ts","sourceRoot":"","sources":["../../src/sonar/sonar-installer.ts"],"names":[],"mappings":"AAkBA,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AA8BD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAyB/B"}

package/dist/sonar/sonar-installer.js

@@ -0,0 +1,69 @@
+/**
+ * Detect the `sonar` CLI and run the vendor's per-agent integrate at apply time.
+ *
+ * This delegates to SonarSource's official `sonar integrate <agent>` — Lisa does
+ * not reimplement the vendor's wiring. It is hard-gated so it never surprises a
+ * project: it is a no-op unless the project has explicitly opted in
+ * (`verification.sonar.enabled`) AND the `sonar` CLI is on `$PATH`. Per-agent
+ * failures are swallowed so a partial or unauthenticated environment never breaks
+ * `lisa apply`; `lisa doctor` surfaces the readiness gap instead.
+ * @module sonar/sonar-installer
+ */
+import { exec, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readProjectConfig } from "../core/project-config.js";
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+/**
+ * Detect whether `sonar` is on PATH.
+ * @returns True when sonar is callable.
+ */
+async function detectSonar() {
+    try {
+        await execAsync("command -v sonar");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the vendor's non-interactive integrate for one agent.
+ * @param agent - Vendor agent name (claude | codex | cursor | copilot | antigravity)
+ * @returns True when integrate exited zero.
+ */
+async function integrateAgent(agent) {
+    try {
+        // execFile (no shell) so an agent token can never be interpreted.
+        await execFileAsync("sonar", ["integrate", agent, "--non-interactive"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wire the official SonarQube MCP into each supported agent via `sonar integrate`.
+ * @param projectRoot - Downstream project root (holds `.lisa.config.json`)
+ * @param vendorAgents - Vendor agent names to integrate, derived from the harness
+ * @returns Integrate result describing opt-in, attempt, and per-agent outcomes
+ */
+export async function installSonarIntegrations(projectRoot, vendorAgents) {
+    const config = (await readProjectConfig(projectRoot)).verification?.sonar;
+    if (config?.enabled !== true) {
+        return { enabled: false, attempted: false, integrated: [], failed: [] };
+    }
+    if (!(await detectSonar())) {
+        return { enabled: true, attempted: false, integrated: [], failed: [] };
+    }
+    // Integrate agents one at a time (the vendor CLI mutates config), threading an
+    // immutable accumulator so no array is mutated in place.
+    const outcome = await vendorAgents.reduce(async (accP, agent) => {
+        const acc = await accP;
+        return (await integrateAgent(agent))
+            ? { integrated: [...acc.integrated, agent], failed: acc.failed }
+            : { integrated: acc.integrated, failed: [...acc.failed, agent] };
+    }, Promise.resolve({ integrated: [], failed: [] }));
+    return { enabled: true, attempted: true, ...outcome };
+}
+//# sourceMappingURL=sonar-installer.js.map

package/dist/sonar/sonar-installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sonar-installer.js","sourceRoot":"","sources":["../../src/sonar/sonar-installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAClC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAc1C;;;GAGG;AACH,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,kBAAkB,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,cAAc,CAAC,KAAa;IACzC,IAAI,CAAC;QACH,kEAAkE;QAClE,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,YAA+B;IAE/B,MAAM,MAAM,GAAG,CAAC,MAAM,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,EAAE,KAAK,CAAC;IAC1E,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACzE,CAAC;IACD,+EAA+E;IAC/E,yDAAyD;IACzD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,MAAM,CAMvC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC;QACvB,OAAO,CAAC,MAAM,cAAc,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;YAChE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;IACrE,CAAC,EACD,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAChD,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AACxD,CAAC"}

package/package.json

@@ -113,7 +113,7 @@
     "brace-expansion": ">=5.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.296.1",
+  "version": "2.297.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.296.1",
+  "version": "2.297.1",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.296.1",
+  "version": "2.297.1",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-analyze-claude-remote/SKILL.md

@@ -195,7 +195,7 @@ Group the findings as:
    | Match | Substrate | Env | Setup / wiring | Domains |
    |---|---|---|---|---|
    | `mcp.jam.dev`, `jam`, or Jam MCP entries | Jam CLI (`jam`) authenticated by PAT | `JAM_PAT` | install with `curl -fsSL https://native.jam.dev/install | bash`; export `~/.local/bin`; run `printf '%s' "$JAM_PAT" | jam auth login --token`; optionally `jam skills install` | `native.jam.dev`, `api.jam.dev` |
-   | `mcp/sonarqube`, `sonarqube`, or SonarCloud/SonarQube MCP entries | SonarCloud Web API | `SONAR_TOKEN` | use REST calls against `https://sonarcloud.io/api/`; if a host needs legacy token-as-basic-auth, put that in the access adapter | `sonarcloud.io` |
+   | `mcp/sonarqube`, `sonarqube`, or SonarQube/SonarCloud MCP entries | Official SonarQube MCP (`sonar run mcp`), token-authed — runs headless as-is, no REST substitute | `SONARQUBE_CLI_TOKEN` (+ `SONARQUBE_CLI_ORG` for Cloud / `SONARQUBE_CLI_SERVER` for Server) | install the SonarQube CLI (`curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh \| bash`) and `sonar integrate <agent>`; pre-pull the MCP container image in the setup script so it fits the cache budget; the MCP authenticates from the env token — never `sonar auth login` | `sonarcloud.io`, `sonarqube.us` (or the Server URL) |
 
    For PAT-bearer MCP substrates that really use the same MCP transport, include `mcpHeaders` in
    the inventory with a snippet such as `headers: { "Authorization": "Bearer ${VAR}" }` so the
@@ -353,17 +353,17 @@ so the generator can render acquisition comments into its template:
       "setupSnippet": "curl -fsSL https://native.jam.dev/install | bash; export PATH=\"$HOME/.local/bin:$PATH\"; printf '%s' \"$JAM_PAT\" | jam auth login --token; jam skills install"
     },
     {
-      "name": "SONAR_TOKEN", "required": false, "secret": true, "integration": "sonarcloud",
-      "reason": "optional non-tracker MCP recovery; SonarQube MCP wraps the token-authenticated SonarCloud Web API",
-      "headlessSubstrate": "SonarCloud Web API (token)",
+      "name": "SONARQUBE_CLI_TOKEN", "required": false, "secret": true, "integration": "sonarcloud",
+      "reason": "authenticates the official SonarQube MCP headlessly; the MCP runs as-is in a cloud routine (Docker is preinstalled), so no REST substitute is needed",
+      "headlessSubstrate": "Official SonarQube MCP (token-authed)",
       "acquireUrl": "https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens",
-      "accessScope": "token must be able to read the target SonarCloud organization/project quality gate, issues, hotspots, rules, and source snippets"
+      "accessScope": "token must be able to read the target Sonar organization/project quality gate, issues, hotspots, rules, coverage, duplications, and dependency risks; add SONARQUBE_CLI_ORG (Cloud) or SONARQUBE_CLI_SERVER (Server)"
     }
   ],
   "mcp": [
     { "name": "linear-server", "transport": "http", "auth": "oauth", "headlessUsable": false, "replacedBy": "LINEAR_API_KEY + Linear GraphQL", "dormant": true },
     { "name": "jam", "transport": "http", "auth": "oauth", "headlessUsable": true, "replacedBy": "jam CLI + JAM_PAT", "dormant": true },
-    { "name": "sonarqube", "transport": "stdio", "auth": "local-wrapper", "headlessUsable": true, "replacedBy": "SONAR_TOKEN + SonarCloud Web API", "dormant": true }
+    { "name": "sonarqube", "transport": "stdio", "auth": "env-token", "headlessUsable": true, "replacedBy": null, "dormant": true }
   ],
   "awsProfiles": [
     {

package/plugins/lisa/.codex-plugin/skills/lisa-generate-claude-remote-build-script/SKILL.md

@@ -69,9 +69,9 @@ tracker/source, plus the host project's own package manager and tooling — not
    sibling repos reachable through the routine's GitHub proxy.
    For OPTIONAL non-tracker MCP recovery entries discovered by
    `/lisa:analyze-claude-remote`, preserve the same names-only behavior:
-   include `JAM_PAT`, `SONAR_TOKEN`, or similar documented substrate env vars
-   only as optional secrets, with their acquire/scope comments when the analysis
-   supplied them. Never invent values or promote dormant substrates to required.
+   include `JAM_PAT`, `SONARQUBE_CLI_TOKEN` (+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`), or
+   similar documented substrate env vars only as optional secrets, with their
+   acquire/scope comments when the analysis supplied them. Never invent values or promote dormant substrates to required.
    When AWS entries are present, list only `LISA_AWS_BOOTSTRAP_JSON` as the
    required secret and `LISA_REMOTE_AGENT=claude` as plain configuration. Never
    emit standard `AWS_ACCESS_KEY_ID` variables and never recommend `aws sso login`.
@@ -84,9 +84,17 @@ tracker/source, plus the host project's own package manager and tooling — not
      `export PATH="$HOME/.local/bin:$PATH"`, `printf '%s' "$JAM_PAT" | jam auth login --token`,
      and `jam skills install`, all inside `[ -n "${JAM_PAT:-}" ] && ...` guards so missing
      optional secrets do not fail the environment build.
-   - REST substitute substrates: do not install an MCP. Emit comments naming the
-     REST host and env var (for example `SONAR_TOKEN` with `https://sonarcloud.io/api/`) and
-     rely on the access skill or generated consumer to call the API.
+   - Container-backed MCP substrates (e.g. the official SonarQube MCP): the MCP
+     runs headless as-is in a cloud routine — Docker is preinstalled — so wire the
+     real MCP rather than substituting REST. Emit, guarded on the optional env
+     token, the vendor CLI install (`curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash`),
+     `sonar integrate <agent>`, and a `sonar run mcp`-image pre-pull so the first
+     run fits the ~5-min cache budget. Provide `SONARQUBE_CLI_TOKEN`
+     (+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`); never emit `sonar auth login` (keychain
+     does not exist headless).
+   - REST-only substitute substrates: for a vendor whose MCP genuinely cannot run
+     headless, do not install an MCP — emit comments naming the REST host and env
+     var, and rely on the access skill or generated consumer to call the API.
    - PAT-bearer MCP substrates: print a commented `.mcp.json` `headers` snippet from the
      inventory's `mcpHeaders`. Use this only when the analysis explicitly says the same MCP
      transport supports static-token auth. Do not print a Jam `.mcp.json` header snippet because

package/plugins/lisa/.codex-plugin/skills/lisa-setup-sonar/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: lisa-setup-sonar
+description: "Configure the official…"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "AskUserQuestion", "Skill"]
+---
+
+# Set up SonarQube (official plugin + MCP)
+
+This is an explicit exterior setup gate. Run it **outside** any active Build, QA,
+Monitor, or Verify factory — authentication and MCP wiring must be complete before
+unattended factories run. It replaces Lisa's former hand-rolled SonarCloud REST
+access with the vendor's official token-authed MCP, which is Lisa's single Sonar
+substrate on both developer machines and headless cloud routines.
+
+This does **not** touch the CI SonarCloud SAST job in `quality.yml` or its
+`SONAR_TOKEN` secret — that enforcement gate is separate and stays as-is.
+
+## Supported agents
+
+Wire only Lisa's supported agents: **Claude Code, Codex, Cursor, GitHub Copilot,
+Antigravity (agy)** via `sonar integrate <agent>`, and **OpenCode** via its MCP
+config. **Never** wire Kiro or Gemini CLI even though the vendor supports them —
+they are not Lisa-supported agents.
+
+## 1. Install or update the SonarQube CLI
+
+Check `sonar` on PATH (`command -v sonar`). If present, update it (`sonar
+self-update`, or the package manager that owns it); if absent, install it and ask
+for confirmation before running the install:
+
+```bash
+# macOS/Linux (script) — default, works everywhere
+curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash
+# or Homebrew: brew install --cask sonarqube-cli
+# or mise:     mise use -g aqua:SonarSource/sonarqube-cli
+```
+
+A container runtime (Docker/Podman/Nerdctl) must be installed and running — the
+MCP runs as a container via `sonar run mcp`. Probe with `docker ps` (falling back
+to `podman ps` / `nerdctl ps`). If none succeed, tell the operator to start it and
+note the agent session must restart afterward for the MCP tools to load.
+
+## 2. Authenticate — token for factories, login for dev machines
+
+The MCP authenticates from environment variables — this is the headless path and
+the one factories use. **Never** write credentials to `.lisa.config.json` or
+`.lisa.config.local.json`; provide them as environment variables / CI secrets:
+
+- `SONARQUBE_CLI_TOKEN` — required.
+- `SONARQUBE_CLI_ORG` — for SonarQube Cloud.
+- `SONARQUBE_CLI_SERVER` — for a self-hosted SonarQube Server.
+
+On an interactive developer machine you may instead run `sonar auth login`
+(browser flow; token stored in the OS keychain). Do **not** use the keychain flow
+for headless/cloud-routine environments — provision the env token there instead
+(see `/lisa:generate-claude-remote-build-script`, which now installs the CLI,
+pre-pulls the MCP image, and sets `SONARQUBE_CLI_TOKEN`). Verify with `sonar auth
+status`; record the identity label only, never token material.
+
+## 3. Select the Test Manager target
+
+Use `sonar config project` (and optional `sonar config folder`), then `sonar
+config show`. Capture the non-secret project/organization identifiers.
+
+## 4. Integrate per supported agent
+
+Confirm the target scope (single-choice: current project / global), then for each
+supported agent detected on PATH run its non-interactive integrate:
+
+```bash
+sonar integrate claude       --non-interactive
+sonar integrate codex        --non-interactive
+sonar integrate cursor       --non-interactive
+sonar integrate copilot      --non-interactive
+sonar integrate antigravity  --non-interactive
+```
+
+For **OpenCode** (no vendor integrate path), wire the MCP through OpenCode's own
+MCP config so it launches `sonar run mcp`, authenticated from the same env token.
+
+Skip any agent whose CLI is not installed; never wire Kiro or Gemini.
+
+## 5. Write non-secret policy config
+
+Merge only non-secret identifiers into committed `.lisa.config.json`, preserving
+every unrelated key (never credentials):
+
+```json
+{
+  "verification": {
+    "sonar": {
+      "enabled": true,
+      "edition": "cloud",
+      "organization": "<org-key>",
+      "projectKey": "<project-key>"
+    }
+  }
+}
+```
+
+Use `"edition": "server"` with a `"serverUrl"` for a self-hosted Server.
+
+## 6. Prove readiness
+
+Run the `lisa-sonarcloud-access` probe (an `mcp__sonarqube__*` project search) and
+confirm a `mcp__sonarqube__*` tool answers. Then run `lisa doctor` and confirm the
+Sonar provider check is green. If the MCP tools do not appear, verify the container
+runtime is running and restart the agent session.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-sonar/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Sonar"
+short_description: "Configure the official…"
+default_prompt:
+  - "Use $lisa-setup-sonar: Configure the official…."

package/plugins/lisa/.codex-plugin/skills/lisa-sonarcloud-access/SKILL.md

@@ -6,66 +6,78 @@ allowed-tools: ["Bash", "Read", "Skill"]
 
 # SonarCloud Access: $ARGUMENTS
 
-Single chokepoint for SonarCloud operations. Caller skills MUST NOT call
-`mcp__sonarqube__*` tools directly or curl `https://sonarcloud.io/api/`
-themselves.
+Single chokepoint for Sonar quality and security data. Caller skills MUST NOT
+invoke `mcp__sonarqube__*` tools directly; they ask for data by operation name and
+this skill owns the tool selection.
 
-## Invocation Contract
+## Substrate
 
-```text
-operation: gate-status project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
-operation: issues project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>] [types:<csv>] [severities:<csv>]
-operation: hotspots project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
-operation: rule-detail key:<RULE_KEY>
-operation: source-snippet component:<COMPONENT_KEY> from:<N> to:<N>
-```
+There is exactly one substrate: the **official SonarQube MCP server**, provided by
+the `sonarqube` plugin and launched by the `sonar` CLI (`sonar run mcp`). It
+authenticates headlessly from environment variables — no browser, no OS keychain —
+so it is the same substrate on a developer machine and in a headless cloud routine:
 
-Return parsed JSON in a `<result>` block.
+- `SONARQUBE_CLI_TOKEN` — required (Sonar user/analysis token).
+- `SONARQUBE_CLI_ORG` — required for SonarQube Cloud.
+- `SONARQUBE_CLI_SERVER` — required for a self-hosted SonarQube Server.
 
-## Substrate Selection
+These are the **SonarQube CLI** variable names (`SONARQUBE_CLI_*`), which the
+`sonar run mcp` wrapper forwards into the MCP container — verified against a live
+SonarQube Cloud org. Do **not** substitute the raw MCP-image names
+(`SONARQUBE_TOKEN`/`SONARQUBE_ORG`/`SONARQUBE_URL`): those are read only when
+running the Docker image directly, and the `sonar` CLI ignores them (auth exits
+non-zero). The CI scan gate's `SONAR_TOKEN` is a third, separate name.
 
-Probe in order:
+Wiring is performed once by `/lisa:setup:sonar` (which drives `sonar integrate
+<agent>`); this access layer assumes the MCP is already wired. This is distinct
+from the CI `SONAR_TOKEN` secret that authenticates the SonarCloud scan job in
+`quality.yml` — that gate is separate and unchanged.
 
-1. Sonar MCP, if available and authenticated.
-2. `SONAR_TOKEN` against the SonarCloud Web API.
+## Probe (tool-access-gate)
 
-SonarCloud documents bearer-token authentication for the Web API. Use:
-
-```bash
-sonar_api() {
-  local path="$1"
-  [ -n "$SONAR_TOKEN" ] || {
-    echo "Error: SONAR_TOKEN is not set." >&2
-    return 1
-  }
-  curl -sS "https://sonarcloud.io/api${path}" \
-    -H "Authorization: Bearer $SONAR_TOKEN"
-}
-```
+Prove access with a cheap read-only MCP call before relying on it — the `sonar` CLI
+being on PATH is not access. Probe by searching projects (the `projects` toolset is
+always enabled):
 
-If a host still requires the legacy token-as-basic-auth form, make that an
-explicit adapter branch in this skill; consumers do not choose auth style.
-
-If neither tier works, fail with:
+- If a `mcp__sonarqube__*` project-search tool returns, access is proven.
+- If no `mcp__sonarqube__*` tool is present, or the call fails authentication, fail
+  loudly and do not improvise a substitute:
 
 ```text
-Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
+Error: no SonarQube access. Run /lisa:setup:sonar (or `sonar integrate <agent>`), and set SONARQUBE_CLI_TOKEN (+ SONARQUBE_CLI_ORG for Cloud / SONARQUBE_CLI_SERVER for Server).
 ```
 
-## REST Dispatch
+There is no hand-rolled REST fallback: the official MCP is headless-capable via the
+token env vars, so it is the only sanctioned substrate. A missing MCP is a
+tool-access-gate failure to surface, not a reason to curl the Web API.
+
+## Operation → toolset map
+
+Consumers pass a coarse, vendor-native operation; resolve it with the matching
+`mcp__sonarqube__*` tool from the named toolset and return parsed JSON in a
+`<result>` block.
 
-| Operation | REST path |
+| Operation | SonarQube MCP toolset |
 |---|---|
-| `gate-status` | `/qualitygates/project_status?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
-| `issues` | `/issues/search?componentKeys=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]...` |
-| `hotspots` | `/hotspots/search?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
-| `rule-detail` | `/rules/show?key=<RULE_KEY>` |
-| `source-snippet` | `/sources/lines?key=<COMPONENT_KEY>&from=<N>&to=<N>` |
+| `gate-status` | `quality-gates` |
+| `issues` | `issues` |
+| `hotspots` | `security-hotspots` |
+| `rule-detail` | `rules` |
+| `source-snippet` | `cag` (context augmentation) / component source |
+| `coverage` | `coverage` |
+| `duplication` | `duplications` |
+| `dependency-risks` | `dependency-risks` |
+| `projects` | `projects` |
+
+Pass the project key through the tool's `projectKey` argument (or rely on a
+server-configured `SONARQUBE_PROJECT_KEY`); pass `branch` / `pullRequest` where the
+tool accepts them.
 
 ## Invariants
 
-- Fallback is gated on `SONAR_TOKEN`.
-- SonarCloud host access requires `sonarcloud.io` in any custom remote network
-  allowlist.
-- Consumers ask for analysis data by operation name; this skill owns the Web API
-  path shape.
+- The official SonarQube MCP is the only substrate; there is no REST fallback.
+- Auth is env-var only (`SONARQUBE_CLI_TOKEN` [+ `SONARQUBE_CLI_ORG` | `SONARQUBE_CLI_SERVER`]);
+  never the interactive `sonar auth login` keychain flow inside a factory.
+- Sonar host access requires the host (`sonarcloud.io`, `sonarqube.us`, or the
+  Server URL) in any custom remote-network allowlist.
+- Consumers ask for data by operation name; this skill owns tool selection.

package/plugins/lisa/commands/setup/sonar.md

@@ -0,0 +1,7 @@
+---
+description: "Wire the official SonarQube plugin + MCP into this project across every supported coding agent. Installs/updates the SonarQube CLI, authenticates (browser login on a dev machine, or SONARQUBE_CLI_TOKEN headless), selects the Test Manager target, runs `sonar integrate <agent>` for each supported agent, and writes only non-secret policy to `.lisa.config.json`. Does not touch the separate CI SonarCloud scan gate."
+allowed-tools: ["Skill"]
+argument-hint: "[--org=<org-key>] [--server-url=<url>] [--global]"
+---
+
+Use the /lisa-setup-sonar skill to wire the official SonarQube MCP for this project across every supported agent. $ARGUMENTS

package/plugins/lisa/rules/reference/integration-access-layer.md

@@ -15,6 +15,14 @@ Do not blind-retry a failed or absent MCP. Fall back only after checking the
 documented env var for that vendor, and never silently no-op when neither tier is
 available.
 
+Some MCPs authenticate headlessly from an env token and need no separate REST
+tier — the MCP **is** the headless substrate on both developer machines and cloud
+routines. The official SonarQube MCP is one such case (`SONARQUBE_CLI_TOKEN`
+[+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`]): `lisa-sonarcloud-access` resolves it as a
+single substrate with no hand-rolled REST fallback. Reserve the two-tier
+MCP-then-REST shape for vendors whose MCP is browser-OAuth or keychain-bound and
+therefore dead headless.
+
 ## Access Skills
 
 | Vendor | Access skill | Headless env var | REST/token substrate |
@@ -23,7 +31,7 @@ available.
 | Notion | `lisa-notion-access` | `NOTION_API_TOKEN` | Notion REST |
 | Linear | `lisa-linear-access` | `LINEAR_API_KEY` | Linear GraphQL |
 | Jam | `lisa-jam-access` | `JAM_PAT` | Jam CLI |
-| SonarCloud | `lisa-sonarcloud-access` | `SONAR_TOKEN` | SonarCloud Web API |
+| SonarCloud | `lisa-sonarcloud-access` | `SONARQUBE_CLI_TOKEN` (+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`) | Official SonarQube MCP (headless via token) |
 | Sentry | `lisa-sentry-access` | `SENTRY_AUTH_TOKEN` | Sentry REST API |
 | PostHog | `lisa-posthog-access` | `POSTHOG_PERSONAL_API_KEY` | PostHog REST API |
 | Google Play | `lisa-expo:play-store-access` | `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` or `GOOGLE_PLAY_SERVICE_ACCOUNT_KEY_BASE64` | Google Play Developer API |
@@ -39,7 +47,7 @@ Source audit date: 2026-06-23. Scope: `plugins/src/**/skills/**` and
 | Notion | setup-only references | `notion-access` | Done. |
 | Linear | Multiple base queue/read/write/verify skills | Raw Linear MCP | Access layer added; consumers still need migration to `linear-access`. |
 | Jam | None in `plugins/src` at audit time | No access layer | Access layer added for host rules that include Jam triage. |
-| SonarCloud | None in `plugins/src` at audit time | No access layer | Access layer added for host rules that include SonarCloud gate triage. |
+| SonarCloud | Routed through `sonarcloud-access` | Official SonarQube MCP (single substrate) | Migrated to the official token-authed SonarQube MCP; bespoke REST dispatch removed. |
 | Sentry | No Sentry MCP references in `plugins/src`; CLI/REST mentions only | CLI/REST scattered in observability docs | Access layer added for future MCP-backed consumers. |
 | PostHog | No PostHog MCP references in `plugins/src`; observability docs mention PostHog detection | No access layer | Access layer added for future MCP-backed consumers. |
 | Google Play | No MCP surface; EAS submit docs only | `play-store-access` for Expo post-submit release visibility | Done for Expo stack. |

package/plugins/lisa/skills/lisa-analyze-claude-remote/SKILL.md

@@ -195,7 +195,7 @@ Group the findings as:
    | Match | Substrate | Env | Setup / wiring | Domains |
    |---|---|---|---|---|
    | `mcp.jam.dev`, `jam`, or Jam MCP entries | Jam CLI (`jam`) authenticated by PAT | `JAM_PAT` | install with `curl -fsSL https://native.jam.dev/install | bash`; export `~/.local/bin`; run `printf '%s' "$JAM_PAT" | jam auth login --token`; optionally `jam skills install` | `native.jam.dev`, `api.jam.dev` |
-   | `mcp/sonarqube`, `sonarqube`, or SonarCloud/SonarQube MCP entries | SonarCloud Web API | `SONAR_TOKEN` | use REST calls against `https://sonarcloud.io/api/`; if a host needs legacy token-as-basic-auth, put that in the access adapter | `sonarcloud.io` |
+   | `mcp/sonarqube`, `sonarqube`, or SonarQube/SonarCloud MCP entries | Official SonarQube MCP (`sonar run mcp`), token-authed — runs headless as-is, no REST substitute | `SONARQUBE_CLI_TOKEN` (+ `SONARQUBE_CLI_ORG` for Cloud / `SONARQUBE_CLI_SERVER` for Server) | install the SonarQube CLI (`curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh \| bash`) and `sonar integrate <agent>`; pre-pull the MCP container image in the setup script so it fits the cache budget; the MCP authenticates from the env token — never `sonar auth login` | `sonarcloud.io`, `sonarqube.us` (or the Server URL) |
 
    For PAT-bearer MCP substrates that really use the same MCP transport, include `mcpHeaders` in
    the inventory with a snippet such as `headers: { "Authorization": "Bearer ${VAR}" }` so the
@@ -353,17 +353,17 @@ so the generator can render acquisition comments into its template:
       "setupSnippet": "curl -fsSL https://native.jam.dev/install | bash; export PATH=\"$HOME/.local/bin:$PATH\"; printf '%s' \"$JAM_PAT\" | jam auth login --token; jam skills install"
     },
     {
-      "name": "SONAR_TOKEN", "required": false, "secret": true, "integration": "sonarcloud",
-      "reason": "optional non-tracker MCP recovery; SonarQube MCP wraps the token-authenticated SonarCloud Web API",
-      "headlessSubstrate": "SonarCloud Web API (token)",
+      "name": "SONARQUBE_CLI_TOKEN", "required": false, "secret": true, "integration": "sonarcloud",
+      "reason": "authenticates the official SonarQube MCP headlessly; the MCP runs as-is in a cloud routine (Docker is preinstalled), so no REST substitute is needed",
+      "headlessSubstrate": "Official SonarQube MCP (token-authed)",
       "acquireUrl": "https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens",
-      "accessScope": "token must be able to read the target SonarCloud organization/project quality gate, issues, hotspots, rules, and source snippets"
+      "accessScope": "token must be able to read the target Sonar organization/project quality gate, issues, hotspots, rules, coverage, duplications, and dependency risks; add SONARQUBE_CLI_ORG (Cloud) or SONARQUBE_CLI_SERVER (Server)"
     }
   ],
   "mcp": [
     { "name": "linear-server", "transport": "http", "auth": "oauth", "headlessUsable": false, "replacedBy": "LINEAR_API_KEY + Linear GraphQL", "dormant": true },
     { "name": "jam", "transport": "http", "auth": "oauth", "headlessUsable": true, "replacedBy": "jam CLI + JAM_PAT", "dormant": true },
-    { "name": "sonarqube", "transport": "stdio", "auth": "local-wrapper", "headlessUsable": true, "replacedBy": "SONAR_TOKEN + SonarCloud Web API", "dormant": true }
+    { "name": "sonarqube", "transport": "stdio", "auth": "env-token", "headlessUsable": true, "replacedBy": null, "dormant": true }
   ],
   "awsProfiles": [
     {

package/plugins/lisa/skills/lisa-generate-claude-remote-build-script/SKILL.md

@@ -69,9 +69,9 @@ tracker/source, plus the host project's own package manager and tooling — not
    sibling repos reachable through the routine's GitHub proxy.
    For OPTIONAL non-tracker MCP recovery entries discovered by
    `/lisa:analyze-claude-remote`, preserve the same names-only behavior:
-   include `JAM_PAT`, `SONAR_TOKEN`, or similar documented substrate env vars
-   only as optional secrets, with their acquire/scope comments when the analysis
-   supplied them. Never invent values or promote dormant substrates to required.
+   include `JAM_PAT`, `SONARQUBE_CLI_TOKEN` (+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`), or
+   similar documented substrate env vars only as optional secrets, with their
+   acquire/scope comments when the analysis supplied them. Never invent values or promote dormant substrates to required.
    When AWS entries are present, list only `LISA_AWS_BOOTSTRAP_JSON` as the
    required secret and `LISA_REMOTE_AGENT=claude` as plain configuration. Never
    emit standard `AWS_ACCESS_KEY_ID` variables and never recommend `aws sso login`.
@@ -84,9 +84,17 @@ tracker/source, plus the host project's own package manager and tooling — not
      `export PATH="$HOME/.local/bin:$PATH"`, `printf '%s' "$JAM_PAT" | jam auth login --token`,
      and `jam skills install`, all inside `[ -n "${JAM_PAT:-}" ] && ...` guards so missing
      optional secrets do not fail the environment build.
-   - REST substitute substrates: do not install an MCP. Emit comments naming the
-     REST host and env var (for example `SONAR_TOKEN` with `https://sonarcloud.io/api/`) and
-     rely on the access skill or generated consumer to call the API.
+   - Container-backed MCP substrates (e.g. the official SonarQube MCP): the MCP
+     runs headless as-is in a cloud routine — Docker is preinstalled — so wire the
+     real MCP rather than substituting REST. Emit, guarded on the optional env
+     token, the vendor CLI install (`curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash`),
+     `sonar integrate <agent>`, and a `sonar run mcp`-image pre-pull so the first
+     run fits the ~5-min cache budget. Provide `SONARQUBE_CLI_TOKEN`
+     (+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`); never emit `sonar auth login` (keychain
+     does not exist headless).
+   - REST-only substitute substrates: for a vendor whose MCP genuinely cannot run
+     headless, do not install an MCP — emit comments naming the REST host and env
+     var, and rely on the access skill or generated consumer to call the API.
    - PAT-bearer MCP substrates: print a commented `.mcp.json` `headers` snippet from the
      inventory's `mcpHeaders`. Use this only when the analysis explicitly says the same MCP
      transport supports static-token auth. Do not print a Jam `.mcp.json` header snippet because