@codyswann/lisa 2.296.0 → 2.297.0

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

@@ -0,0 +1,108 @@
+---
+name: lisa-setup-sonar
+description: "Configure the official SonarQube plugin + MCP as Lisa's single Sonar substrate across every supported coding agent. Installs/updates the SonarQube CLI, authenticates (browser login on a dev machine, or SONARQUBE_TOKEN headless), selects the Test Manager target, runs `sonar integrate <agent>` for each supported agent (Claude, Codex, Cursor, Copilot, Antigravity) and wires the MCP for OpenCode, then writes only non-secret policy to .lisa.config.json. Separate from the CI SonarCloud scan gate, which is unchanged."
+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_TOKEN` — required.
+- `SONARQUBE_ORG` — for SonarQube Cloud.
+- `SONARQUBE_URL` — 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_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/skills/lisa-setup-sonar/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Sonar"
+short_description: "Configure the official SonarQube plugin + MCP as Lisa's single Sonar substrate across every supported coding agent"
+default_prompt:
+  - "Use $lisa-setup-sonar: Configure the official SonarQube plugin + MCP as Lisa's single Sonar substrate across every supported coding agent."

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

@@ -1,71 +1,76 @@
 ---
 name: lisa-sonarcloud-access
-description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud. Sonar triage skills MUST delegate through this skill rather than calling Sonar MCP tools or REST directly. Resolves Sonar MCP first when available, then falls back to SONAR_TOKEN + SonarCloud Web API."
+description: "Vendor-neutral access layer for SonarQube Cloud/Server. Sonar triage skills MUST delegate through this skill rather than calling the SonarQube MCP tools directly. Single substrate: the official SonarQube MCP server (mcp__sonarqube__*), authenticated headlessly from SONARQUBE_TOKEN (+ SONARQUBE_ORG for Cloud, SONARQUBE_URL for Server)."
 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_TOKEN` — required (Sonar user/analysis token).
+- `SONARQUBE_ORG` — required for SonarQube Cloud.
+- `SONARQUBE_URL` — required for a self-hosted SonarQube Server.
 
-## Substrate Selection
+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.
 
-Probe in order:
+## Probe (tool-access-gate)
 
-1. Sonar MCP, if available and authenticated.
-2. `SONAR_TOKEN` against the SonarCloud Web API.
+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):
 
-SonarCloud documents bearer-token authentication for the Web API. Use:
+- 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:
 
-```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"
-}
+```text
+Error: no SonarQube access. Run /lisa:setup:sonar (or `sonar integrate <agent>`), and set SONARQUBE_TOKEN (+ SONARQUBE_ORG for Cloud / SONARQUBE_URL for Server).
 ```
 
-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.
+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.
 
-If neither tier works, fail with:
-
-```text
-Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
-```
+## Operation → toolset map
 
-## REST Dispatch
+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_TOKEN` [+ `SONARQUBE_ORG` | `SONARQUBE_URL`]);
+  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/skills/lisa-sonarcloud-access/agents/openai.yaml

@@ -1,4 +1,4 @@
 display_name: "SonarCloud Access"
-short_description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud"
+short_description: "Vendor-neutral access layer for SonarQube Cloud/Server"
 default_prompt:
-  - "Use $lisa-sonarcloud-access: Vendor-neutral access layer for SonarCloud/SonarQube Cloud."
+  - "Use $lisa-sonarcloud-access: Vendor-neutral access layer for SonarQube Cloud/Server."

package/plugins/lisa-agy/commands/lisa/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_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-agy/plugin.json

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

package/plugins/lisa-agy/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_TOKEN` (+ `SONARQUBE_ORG` for Cloud / `SONARQUBE_URL` 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_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_ORG (Cloud) or SONARQUBE_URL (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-agy/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_TOKEN` (+ `SONARQUBE_ORG`/`SONARQUBE_URL`), 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_TOKEN`
+     (+ `SONARQUBE_ORG`/`SONARQUBE_URL`); 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-agy/skills/lisa-persist-learning/SKILL.md

@@ -174,6 +174,20 @@ No learning content is ever committed without a PR — there is no other write p
    - **Related entry found** → consolidate via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug that fails review.
    - **No related entry** → append via `persistLearningEntry(projectRoot, entry)` and state in the PR body why appending was correct.
    - Entry mapping: `id` = the fingerprint; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
+   - **On a budget-forced drop, signal saturation once (never silent).** When the writer's budget re-assertion cannot fit the entry even after consolidating harder — a durable capture has to be DROPPED for budget — the ledger is saturated, and that pressure must be visible to an operator instead of swallowed. Emit **exactly one** tracker signal via `lisa-tracker-write` (`issue_type: Task`; GitHub trackers carry the `type:Task` label), then continue — dropping the capture never blocks the build. Follow the same marker-dedupe discipline as every other comment here (match on the **marker, never the title**; **exactly one marker per body**; the eventual-consistency guard when the search index is stale), with **one deliberate difference: dedupe against OPEN signals only.** A *closed* saturation ticket means room was already reclaimed, so a fresh saturation is a new actionable event — searching closed tickets too (as the drop/upstream markers do) would permanently suppress every later saturation.
+
+     The saturation fingerprint keys on the **ledger, not the candidate**, so the signal fires once per saturation episode — never once per capture:
+
+     ```text
+     saturation-fingerprint = "sat-" + first 12 hex chars of sha1(<resolved learnings-file path>)
+     ```
+
+     ```markdown
+     <!-- [lisa-ledger-saturated] key=<saturation-fingerprint> -->
+     Learnings ledger saturated — a durable capture was dropped for budget. The projection is now omitting entries; promote or retire a learning to reclaim room. This is an operator-visible budget-pressure signal, not itself a new learning.
+     ```
+
+     The `[lisa-ledger-saturated]` marker sits **outside the `[lisa-learning-*]` namespace** that the gardener (`lisa-learnings-audit`) auto-excludes from candidacy. The gardener already derives budget pressure independently — it measures the entries its `projectLearnings` projection has to omit — so this ticket does not feed that measurement mechanically; its job is an idempotent, operator-visible notification that saturation happened. Keeping it outside `[lisa-learning-*]` matters so the audit tooling does not silently filter it as learning-machinery noise before an operator sees it. **Do not reuse a `[lisa-learning-*]` marker here.** The candidate itself is still dropped; this signal records the saturation, it does not persist the rule.
 4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
 5. **PR body.** Exactly one marker line plus the reviewable story:
 

package/plugins/lisa-agy/skills/lisa-setup-sonar/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: lisa-setup-sonar
+description: "Configure the official SonarQube plugin + MCP as Lisa's single Sonar substrate across every supported coding agent. Installs/updates the SonarQube CLI, authenticates (browser login on a dev machine, or SONARQUBE_TOKEN headless), selects the Test Manager target, runs `sonar integrate <agent>` for each supported agent (Claude, Codex, Cursor, Copilot, Antigravity) and wires the MCP for OpenCode, then writes only non-secret policy to .lisa.config.json. Separate from the CI SonarCloud scan gate, which is unchanged."
+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_TOKEN` — required.
+- `SONARQUBE_ORG` — for SonarQube Cloud.
+- `SONARQUBE_URL` — 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_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-agy/skills/lisa-sonarcloud-access/SKILL.md

@@ -1,71 +1,76 @@
 ---
 name: lisa-sonarcloud-access
-description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud. Sonar triage skills MUST delegate through this skill rather than calling Sonar MCP tools or REST directly. Resolves Sonar MCP first when available, then falls back to SONAR_TOKEN + SonarCloud Web API."
+description: "Vendor-neutral access layer for SonarQube Cloud/Server. Sonar triage skills MUST delegate through this skill rather than calling the SonarQube MCP tools directly. Single substrate: the official SonarQube MCP server (mcp__sonarqube__*), authenticated headlessly from SONARQUBE_TOKEN (+ SONARQUBE_ORG for Cloud, SONARQUBE_URL for Server)."
 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_TOKEN` — required (Sonar user/analysis token).
+- `SONARQUBE_ORG` — required for SonarQube Cloud.
+- `SONARQUBE_URL` — required for a self-hosted SonarQube Server.
 
-## Substrate Selection
+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.
 
-Probe in order:
+## Probe (tool-access-gate)
 
-1. Sonar MCP, if available and authenticated.
-2. `SONAR_TOKEN` against the SonarCloud Web API.
+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):
 
-SonarCloud documents bearer-token authentication for the Web API. Use:
+- 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:
 
-```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"
-}
+```text
+Error: no SonarQube access. Run /lisa:setup:sonar (or `sonar integrate <agent>`), and set SONARQUBE_TOKEN (+ SONARQUBE_ORG for Cloud / SONARQUBE_URL for Server).
 ```
 
-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.
+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.
 
-If neither tier works, fail with:
-
-```text
-Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
-```
+## Operation → toolset map
 
-## REST Dispatch
+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_TOKEN` [+ `SONARQUBE_ORG` | `SONARQUBE_URL`]);
+  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-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.296.0",
+  "version": "2.297.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.296.0",
+  "version": "2.297.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.296.0",
+  "version": "2.297.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"