skilldrop-cli 0.2.0

package/skills/sonar-onboard/templates/github-actions-sonar-server.yml.tmpl

@@ -0,0 +1,50 @@
+name: SonarQube
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  sonarqube:
+    name: Scan + quality gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history is required for accurate blame and new-code-period detection.
+          fetch-depth: 0
+
+      # ─── BUILD + TEST + COVERAGE ───────────────────────────────────────────
+      # Replace this block with the project's actual build/test commands.
+      # The scanner imports the coverage report produced here — if this step
+      # doesn't generate it, Sonar reports 0% coverage on new code.
+      #
+      # Examples:
+      #   JS/TS:    npm ci && npm test -- --coverage
+      #   Java:     mvn -B verify
+      #   Python:   pip install -r requirements.txt && pytest --cov --cov-report=xml
+      #   Go:       go test ./... -coverprofile=coverage.out
+      #
+      - name: Build, test, and produce coverage
+        run: |
+          {{BUILD_TEST_COMMAND}}
+
+      # ─── SCAN ──────────────────────────────────────────────────────────────
+      - name: SonarQube scan
+        uses: sonarsource/sonarqube-scan-action@v3
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+
+      # ─── QUALITY GATE ──────────────────────────────────────────────────────
+      # Fails the job (and therefore the PR check) when the gate fails.
+      # Without this step, scans run but never block merge — defeats the point.
+      - name: Quality gate
+        uses: sonarsource/sonarqube-quality-gate-action@master
+        timeout-minutes: 5
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

package/skills/sonar-onboard/templates/github-actions-sonarcloud.yml.tmpl

@@ -0,0 +1,53 @@
+name: SonarCloud
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  sonarcloud:
+    name: Scan + quality gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history is required for accurate blame and new-code-period detection.
+          fetch-depth: 0
+
+      # ─── BUILD + TEST + COVERAGE ───────────────────────────────────────────
+      # Replace this block with the project's actual build/test commands.
+      # The scanner imports the coverage report produced here — if this step
+      # doesn't generate it, SonarCloud reports 0% coverage on new code.
+      #
+      # Examples:
+      #   JS/TS:    npm ci && npm test -- --coverage
+      #   Java:     mvn -B verify
+      #   Python:   pip install -r requirements.txt && pytest --cov --cov-report=xml
+      #   Go:       go test ./... -coverprofile=coverage.out
+      #
+      - name: Build, test, and produce coverage
+        run: |
+          {{BUILD_TEST_COMMAND}}
+
+      # ─── SCAN ──────────────────────────────────────────────────────────────
+      # The SonarCloud action runs the scanner AND waits for the gate, in one step.
+      # Host URL defaults to https://sonarcloud.io — do not override unless you
+      # know what you're doing.
+      - name: SonarCloud scan
+        uses: SonarSource/sonarcloud-github-action@master
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          # GITHUB_TOKEN is used to decorate the PR with findings.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # ─── QUALITY GATE ──────────────────────────────────────────────────────
+      # Fails the job (and therefore the PR check) when the gate fails.
+      - name: Quality gate
+        uses: SonarSource/sonarqube-quality-gate-action@master
+        timeout-minutes: 5
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: https://sonarcloud.io

package/skills/sonar-onboard/templates/readme-snippet.md

@@ -0,0 +1,38 @@
+## Code quality
+
+This repo is gated by **{{SONAR_FLAVOR}}** ({{SONAR_FLAVOR}} = `SonarQube` for self-hosted, `SonarCloud` for SaaS). Every push to the default branch and every pull request runs a scan; the PR check fails if the quality gate fails.
+
+**What the gate enforces** (Sonar default — tune in the Sonar UI per project):
+
+| Condition | Threshold |
+|---|---|
+| New bugs | 0 |
+| New vulnerabilities | 0 |
+| New security hotspots reviewed | 100% |
+| Coverage on new code | ≥ 80% |
+| Duplicated lines on new code | ≤ 3% |
+| Maintainability rating on new code | A |
+| Reliability rating on new code | A |
+| Security rating on new code | A |
+
+The gate measures **new code** (since the previous version), not the whole codebase — so existing debt doesn't block your PR, but new debt does.
+
+**Required GitHub secrets:**
+
+<!-- For SonarQube server, keep both. For SonarCloud, keep only SONAR_TOKEN. -->
+- `SONAR_TOKEN` — project token from {{SONAR_FLAVOR}} (My Account → Security → Generate Token)
+- `SONAR_HOST_URL` — e.g. `https://sonar.company.com`  *(SonarQube server only; omit for SonarCloud)*
+
+**Run a scan locally** (against the same {{SONAR_FLAVOR}} project):
+
+```bash
+export SONAR_TOKEN=<your-token>
+# SonarQube server only:
+export SONAR_HOST_URL=<your-sonar-host>
+# SonarCloud: omit SONAR_HOST_URL — it defaults to https://sonarcloud.io
+sonar-scanner
+```
+
+Findings appear at:
+- **SonarQube server:** `${SONAR_HOST_URL}/dashboard?id=<project-key>`
+- **SonarCloud:** `https://sonarcloud.io/dashboard?id=<project-key>`

package/skills/sonar-onboard/templates/sonar-project.properties.tmpl

@@ -0,0 +1,31 @@
+# SonarQube project configuration.
+# Host URL and auth token are passed via env vars (SONAR_HOST_URL, SONAR_TOKEN),
+# not committed here — keeps the file portable across forks and local runs.
+
+sonar.projectKey={{PROJECT_KEY}}
+sonar.projectName={{PROJECT_NAME}}
+sonar.projectVersion=1.0
+
+# SonarCloud ONLY — required, set to your SonarCloud organization key.
+# Delete this line for self-hosted SonarQube server.
+sonar.organization={{ORG_KEY}}
+
+# Source layout — comma-separate for multi-language repos.
+sonar.sources={{SOURCES}}
+sonar.tests={{TESTS}}
+
+# Encoding (UTF-8 unless the project has a documented exception).
+sonar.sourceEncoding=UTF-8
+
+# Coverage report — paths are relative to the repo root.
+# Each language has its own importer; uncomment the one(s) you generate.
+# {{COVERAGE_PROPERTY}}={{COVERAGE_PATH}}
+# TODO: wire up coverage in your test step, then uncomment the line above.
+
+# Exclusions — keep the gate honest by skipping generated, vendored, and migration code.
+sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/.next/**,**/__pycache__/**,**/*.generated.*,**/vendor/**,**/migrations/**
+sonar.test.exclusions=**/*.test.*,**/*.spec.*,**/test/**,**/tests/**
+sonar.coverage.exclusions=**/*.test.*,**/*.spec.*,**/test/**,**/tests/**,**/*.stories.*,**/index.{js,ts}
+
+# New-code period — issues in code changed since this reference are what the gate enforces.
+# Defaults to "previous_version"; override in the Sonar UI per-project if needed.

package/skills/sonar-review/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: sonar-review
+description: Run a Sonar scan against the just-changed code on the current branch and produce a structured compliance report — quality-gate verdict (PASS / FAIL), then severity-tagged findings (🟥 blocker / 🟧 critical / 🟨 major / ⚪ minor / ⚪ info) scoped to changed files, each with file:line, the Sonar rule ID, the category (bug / vulnerability / security hotspot / code smell), why it matters, and a concrete fix. Works against both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS) — mode is detected from `sonar-project.properties`. Sister skill to `devils-advocate`, but enforces Sonar's rule catalog and the project's quality gate rather than a hand-rolled lens sweep. Use after writing code, before pushing or opening a PR, when the user says "is this Sonar-compliant?", "run Sonar on this", "will the quality gate pass?", or any pre-merge compliance check.
+---
+
+# sonar-review
+
+You run a Sonar scan against the user's just-changed code and produce a structured pre-merge compliance report. The artifact is a markdown review the user acts on — not raw scanner output, not a quiet "scan complete".
+
+This skill is the **Sonar-flavored counterpart to [`devils-advocate`](../devils-advocate/SKILL.md)**: same shape (severity-tagged findings, file:line evidence, concrete fixes, verdict on top), but the rules come from Sonar's catalog and the verdict comes from the project's quality gate, not your judgment.
+
+Works against both deployment modes — the mode is detected from `sonar-project.properties`, not asked:
+
+| Mode | Detection | Host | Token env |
+|---|---|---|---|
+| **SonarQube server** | No `sonar.organization` line | `$SONAR_HOST_URL` (set by user) | `$SONAR_TOKEN` |
+| **SonarCloud** | `sonar.organization=<key>` present | `https://sonarcloud.io` (fixed) | `$SONAR_TOKEN` |
+
+The API endpoints are identical between the two — only the host differs. If the user is jumping in cold and the repo isn't wired up, run [`sonar-onboard`](../sonar-onboard/SKILL.md) first.
+
+## How to respond
+
+1. **Detect the mode.** First thing — read `sonar-project.properties` and check for a `sonar.organization=` line:
+   - **Present** ⇒ SonarCloud. Host is `https://sonarcloud.io` (don't read `$SONAR_HOST_URL`).
+   - **Absent** ⇒ SonarQube server. Host comes from `$SONAR_HOST_URL`.
+
+   Use the detected mode for every subsequent step. Don't ask the user — the properties file is the source of truth.
+
+2. **Verify the environment before scanning.** Checks differ by mode:
+
+   | Check | Applies to | If missing |
+   |---|---|---|
+   | `sonar-project.properties` at repo root | both | Stop. Tell the user to run `sonar-onboard` first — there's no project config to scan against. |
+   | `sonar-scanner` on `PATH` | both | Stop. Print the install hint (see step 3). Do not attempt to install it. |
+   | `SONAR_TOKEN` env var set | both | Stop. Tell the user to export it from their Sonar account → Security → Tokens. |
+   | `SONAR_HOST_URL` env var set | **server only** | Stop. Tell the user to export it (e.g. `export SONAR_HOST_URL=https://sonar.company.com`). |
+
+   These are non-negotiable. Don't fabricate findings, don't run a partial scan, don't fall back to a local linter — the artifact this skill produces is a *Sonar* report or it's nothing.
+
+3. **Install hint** if `sonar-scanner` is missing — print verbatim, don't drive the install:
+
+   ```
+   sonar-scanner CLI not found on PATH. Install it:
+     macOS:    brew install sonar-scanner
+     Linux:    https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner/
+     Docker:   docker run --rm -v "$(pwd):/usr/src" sonarsource/sonar-scanner-cli
+   Then re-run this skill.
+   ```
+
+4. **Identify the change under review.** Same precedence as `devils-advocate`:
+   - User has shown you a diff or named files — that's the scope.
+   - Git working tree has unstaged + uncommitted changes — `git diff` is the scope.
+   - User says "the feature I just built" — run `git diff origin/main...HEAD` (or `HEAD~1` if no upstream).
+
+   The scope is the **set of changed files**, not the whole repo. The scan itself runs against the whole project (Sonar needs the full graph for accurate cross-file analysis), but **findings you report are filtered to changed files only** — anything else is out-of-scope noise.
+
+5. **Set the host variable for the run.** Same logic, both modes:
+
+   ```bash
+   if grep -q '^sonar.organization=' sonar-project.properties; then
+     SONAR_HOST="https://sonarcloud.io"  # SonarCloud is fixed
+   else
+     SONAR_HOST="$SONAR_HOST_URL"        # server reads env var
+   fi
+   ```
+
+   Use `$SONAR_HOST` for both the scanner CLI and the API calls below.
+
+6. **Run the scan.** From the repo root:
+
+   ```bash
+   sonar-scanner \
+     -Dsonar.host.url="$SONAR_HOST" \
+     -Dsonar.token="$SONAR_TOKEN" \
+     -Dsonar.branch.name="$(git rev-parse --abbrev-ref HEAD)"
+   ```
+
+   Note on `sonar.branch.name`: SonarCloud accepts it on all tiers; SonarQube Community Edition does not. If you see `License not valid for branch analysis`, drop the flag and re-run — the scan will overwrite the default branch's history (acceptable for a local pre-merge check, not for CI).
+
+   If the project uses Maven, Gradle, or `dotnet-sonarscanner`, prefer those wrappers (they hook into the compile step) — check `sonar-project.properties` and the build files to decide. See [`reference.md`](reference.md).
+
+   The scan typically takes 30s–3min. **Wait for it.** Do not summarize before results land — a "should pass" guess is worse than waiting.
+
+7. **Fetch the gate status and issues from the Sonar API.** After the scan finishes, the scanner writes `.scannerwork/report-task.txt` with a `ceTaskUrl` — poll it until `status=SUCCESS`, then fetch (same endpoints for server and cloud — only `$SONAR_HOST` differs):
+
+   ```bash
+   PROJECT_KEY=$(grep '^sonar.projectKey=' sonar-project.properties | cut -d= -f2)
+   BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+   # Quality gate
+   curl -s -u "$SONAR_TOKEN:" \
+     "$SONAR_HOST/api/qualitygates/project_status?projectKey=$PROJECT_KEY&branch=$BRANCH"
+
+   # Issues (scoped to new code in this branch)
+   curl -s -u "$SONAR_TOKEN:" \
+     "$SONAR_HOST/api/issues/search?componentKeys=$PROJECT_KEY&branch=$BRANCH&inNewCodePeriod=true&ps=500"
+
+   # Security hotspots
+   curl -s -u "$SONAR_TOKEN:" \
+     "$SONAR_HOST/api/hotspots/search?projectKey=$PROJECT_KEY&branch=$BRANCH&inNewCodePeriod=true"
+   ```
+
+   Filter the issues list to changed files (compare each issue's `component` field against the diff). See [`reference.md`](reference.md) for the exact JSON shapes.
+
+8. **Map Sonar severities to the report's severity markers.** Keep the mapping consistent across reports:
+
+   | Sonar severity | Marker | Meaning in the report |
+   |---|---|---|
+   | `BLOCKER` | 🟥 **Blocker** | Will ship a bug or security issue. Must fix before merge. |
+   | `CRITICAL` | 🟧 **Critical** | High-impact bug, hotspot, or vulnerability that needs review before merge. |
+   | `MAJOR` | 🟨 **Major** | Code smell or quality issue that will hurt within months. Fix before merge if reasonable. |
+   | `MINOR` | ⚪ **Minor** | Quality nit. Fine to defer. |
+   | `INFO` | ⚪ **Info** | Optional. List only if there are < 5 of them; otherwise summarize the count. |
+
+   **Do not invent severity.** Sonar's catalog assigns it — copy it. The mapping is mechanical, not judgmental.
+
+9. **Sweep the five lenses.** Sonar categorizes every finding into one of these — group the report by lens, same as `devils-advocate`. Each lens file describes what to look for and how to phrase the fix:
+
+   | Lens | File | Sonar issue type |
+   |---|---|---|
+   | 1. Bugs | [`lenses/bugs.md`](lenses/bugs.md) | `BUG` |
+   | 2. Vulnerabilities | [`lenses/vulnerabilities.md`](lenses/vulnerabilities.md) | `VULNERABILITY` |
+   | 3. Security hotspots | [`lenses/security-hotspots.md`](lenses/security-hotspots.md) | `SECURITY_HOTSPOT` (separate API) |
+   | 4. Code smells | [`lenses/code-smells.md`](lenses/code-smells.md) | `CODE_SMELL` |
+   | 5. Coverage + duplication | [`lenses/coverage-and-duplication.md`](lenses/coverage-and-duplication.md) | Quality-gate condition failures |
+
+10. **For every finding, write four parts** (same shape as `devils-advocate`):
+
+   - **Where:** `file:line` — quote 5–15 chars of the offending line.
+   - **Rule + category:** `[BUG · javascript:S2228] Console logging should not be used`. The rule ID is what the user clicks in the Sonar UI to read the catalog page.
+   - **Why it matters:** one sentence — what the rule prevents *in this scenario*. ✅ "Mutable shared state in `parseConfig` will desync between requests under concurrent load." ❌ "Avoid shared state."
+   - **Fix:** ✅ "Wrap the cache in `Object.freeze()` on line 23, or move the mutable copy inside `parseConfig` (preferred — matches the pattern in `parseUserConfig`:51)." ❌ "Refactor to avoid mutation."
+
+11. **Open with the gate verdict, not the findings.** The first thing the user sees:
+
+   ```
+   Quality gate: ❌ FAIL — coverage on new code is 71% (gate requires ≥ 80%), 1 new vulnerability.
+   Findings on changed code: 1 blocker · 3 critical · 7 major · 4 minor.
+
+   The blocker is a SQL-injection-shaped query construction at api/users.ts:142 (rule javascriptsecurity:S3649) — parameterize before merging. The vulnerability and the coverage shortfall are what's failing the gate; the major findings are all in the new payment-handler module and are fixable with the patterns used elsewhere in the codebase.
+   ```
+
+   If the gate passed, lead with that and still report findings (a passing gate doesn't mean zero issues — it means the *new code* met the conditions; minor findings may still be worth fixing).
+
+12. **Use [`templates/report.md`](templates/report.md)** for the output structure:
+
+    ```markdown
+    # Sonar review: {feature / PR title}
+    _Scope: {N changed files} · Branch: {branch} · Scanned: {YYYY-MM-DD HH:MM}_
+    _Sonar project: [{project-key}]({sonar-url}/dashboard?id={project-key}&branch={branch})_
+
+    ## Quality gate
+    {PASS / FAIL} — {one-line reason}
+    {2-sentence summary, lead with what failed the gate}
+
+    ## Findings on changed code
+    {counts table}
+
+    ### 1. Bugs
+    ### 2. Vulnerabilities
+    ### 3. Security hotspots
+    ### 4. Code smells
+    ### 5. Coverage + duplication
+
+    ## Pre-existing issues touched (FYI)
+    {issues in files you changed that pre-date this branch — for awareness, not blocking}
+
+    ## Suggested order to address
+    1. Fix anything failing the quality gate (blockers + vulnerabilities + coverage)
+    2. Review the security hotspots — Sonar can't auto-decide, you have to mark them
+    3. Major findings, especially anything in load-bearing or security-adjacent code
+    4. Minors as time allows
+    ```
+
+13. **End with the Sonar dashboard link.** The full picture — including pre-existing debt, history, and the gate's detailed conditions — lives in the Sonar UI. Always end with `Full report: ${SONAR_HOST}/dashboard?id=<project-key>&branch=<branch>` — `$SONAR_HOST` is the value you set in step 5 (so the link works whether the project is on SonarQube server or SonarCloud).
+
+## Useful references in this skill
+
+- [`lenses/bugs.md`](lenses/bugs.md) — how to phrase Bug findings
+- [`lenses/vulnerabilities.md`](lenses/vulnerabilities.md) — Vulnerability findings (CWE / OWASP-tagged)
+- [`lenses/security-hotspots.md`](lenses/security-hotspots.md) — Hotspots need human review, not auto-fix
+- [`lenses/code-smells.md`](lenses/code-smells.md) — Maintainability findings
+- [`lenses/coverage-and-duplication.md`](lenses/coverage-and-duplication.md) — Gate conditions that aren't issues
+- [`templates/report.md`](templates/report.md) — Report skeleton
+- [`reference.md`](reference.md) — Sonar API shapes, Maven/Gradle/dotnet variants, scoping to PR diffs
+
+## Quality bar
+
+- **Verdict comes from the gate, not from you.** The quality gate is the source of truth. ✅ "Gate FAIL — 1 new vulnerability." ❌ "Looks risky to me." If the gate passed, say PASS even if you'd personally flag issues.
+- **Findings are scoped to changed files.** The repo has pre-existing debt; this skill is a pre-merge check, not a backlog dump. Pre-existing issues in *touched* files go in a separate "FYI" section — issues in untouched files don't appear at all.
+- **Every finding cites `file:line` and the Sonar rule ID.** `javascript:S2228` is a click-through to the Sonar UI catalog. Strip either and the finding becomes unactionable.
+- **Severity is Sonar's, not yours.** Don't downgrade a `CRITICAL` because you disagree, and don't upgrade a `MINOR` to make the report scarier. If you disagree with the catalog, raise it in the lens body, don't rewrite the severity.
+- **Fixes name a concrete change.** A patch line, a function rename, a missing test case — not "consider refactoring".
+- **Don't recommend disabling rules to pass the gate.** That's a code-quality conversation. Suggest fixes or scoping (Sonar-scoping comments like `// NOSONAR` should be rare and justified in the code, not as a default).
+- **Security hotspots are flagged for review, not "fixed".** Hotspots ask "is this safe?" — the resolution is a human decision (mark Safe, At Risk, Acknowledged). The fix you write is *the evidence the user needs to make that call*, not a code patch.
+
+## When to use this skill
+
+- ✅ After implementing a feature, before opening a PR ("is this Sonar-compliant?")
+- ✅ When CI shows a failed Sonar gate and the user wants the findings explained locally before pushing again
+- ✅ Before merging a long-lived branch back to main — final gate check
+- ✅ Sanity check after rebasing onto main, to catch newly-applied rules
+
+## When NOT to use this skill
+
+- ❌ Repo isn't set up for Sonar (no `sonar-project.properties`). Run `sonar-onboard` first.
+- ❌ User wants a code review broader than Sonar's catalog covers (architecture, idiomatic concerns, test-design). Use `devils-advocate` instead — different lens.
+- ❌ User wants to fix the *whole codebase*'s Sonar debt. This skill is per-change; for a debt-paydown plan, query the Sonar UI directly.
+- ❌ Repo only has linters (ESLint, Pylint, golangci-lint) and no Sonar. Different tool, different catalog — running this skill would produce nothing.
+- ❌ Repo isn't wired to *either* SonarQube server or SonarCloud — no `sonar-project.properties` means there's nothing to scan against. Run `sonar-onboard` first.
+
+## Anti-patterns to avoid
+
+- ❌ **Guessing the gate result.** Always wait for the actual scan + API call. A "should pass" prediction without the scan is the worst possible output — it builds false confidence.
+- ❌ **Reporting issues from untouched files.** The user opened a PR for one feature; flooding them with debt from other files is noise. Scope strictly to changed files; pre-existing-in-touched-files go in the FYI section.
+- ❌ **Translating rule IDs into prose.** Keep `javascript:S2228` literal — that's the click-through key. ❌ "Use of console logging" ✅ "[javascript:S2228] Use of console logging".
+- ❌ **Suggesting `// NOSONAR` as the default fix.** That's "make the linter shut up", not compliance. Reserve for documented exceptions with a comment explaining why.
+- ❌ **Auto-fixing the code.** This skill produces a *report*. The user (or another agent / skill) decides what to change. Auto-fixes hide the learning and the audit trail.
+- ❌ **Hiding the FAIL.** If the gate fails, lead with FAIL. Don't bury it under "but here's what's good" — the user opened this skill to know whether they can merge.
+- ❌ **Treating security hotspots as bugs.** Hotspots are *review-required*; the resolution is human judgment. Show the evidence, then ask the user to mark Safe / At Risk / Acknowledged — don't patch them silently.

package/skills/sonar-review/lenses/bugs.md

@@ -0,0 +1,48 @@
+# Lens 1 — Bugs
+
+Sonar's **Bug** category is code that is **demonstrably broken or will break**: null dereferences, off-by-one, dead branches, resource leaks, race-shaped APIs, contracts that don't hold. Bugs are the highest-signal lens — every bug is, by Sonar's definition, a defect waiting to ship.
+
+## What you're looking at
+
+Pull the issues list, filter to `type=BUG`, then filter further to the changed-files set. Common bug rules to recognize on sight:
+
+| Rule family | Example IDs | What it catches |
+|---|---|---|
+| Null dereference | `javascript:S2259`, `java:S2259`, `python:S5713`, `csharpsquid:S2259` | `x.foo` where `x` can be null/None |
+| Off-by-one / loop bound | `S2440`, `S2189`, `S2583` | `<=` vs `<`, infinite loops, dead branches |
+| Resource leak | `S2095`, `S2093` | unclosed streams, files, DB connections |
+| Exception handling | `S2737`, `S108`, `S1166` | empty catch, swallowed throwables, `throw` lost in finally |
+| Equality / comparison | `S2159`, `S1698`, `S3403` | `==` on incompatible types, `equals` vs `==` |
+| Floating-point comparison | `S1244` | `if (x == 0.1)` |
+| Date / time | `S3725`, `S6353` | wrong timezone, deprecated `Date` mutation |
+| Promise / async (JS/TS) | `S4123`, `S6544` | unawaited promises, missing error handlers |
+| Mutable shared state | `S2386`, `S3008` | non-final static, mutable singletons |
+
+If the rule isn't in this list, look it up at `${SONAR_HOST_URL}/coding_rules?open=<rule-id>` — Sonar links every issue to its catalog page with examples.
+
+## How to phrase each finding
+
+Four parts, same as the report skeleton:
+
+1. **Where** — `file:line` + a 5–15 char quote of the offending code.
+2. **Rule + category** — `[BUG · javascript:S2259] Null dereference` — keep the rule ID literal.
+3. **Why it matters** — name the **runtime scenario**, not the rule. ✅ "When `req.body.discount` is omitted from the request, `discount.amount` throws `TypeError: Cannot read properties of undefined` — the endpoint 500s." ❌ "Possible null dereference."
+4. **Fix** — concrete. Either:
+   - **Paste-able patch** — a one-line guard, a `??`, an `if (x == null) return`, a `try/finally`. Quote the line numbers.
+   - **Pattern reference** — "Use the `withConnection` helper from `db.ts:14` instead of opening directly; it handles the `finally` close."
+
+## Calibration
+
+- **BLOCKER bug** ≈ ships a defect on the happy path or a security-shaped fault (e.g. unsanitized `eval`, SQL string concat). Treat as merge-blocking.
+- **CRITICAL bug** ≈ defect on a common error path (null on optional field, leak on retry). Fix before merge.
+- **MAJOR bug** ≈ defect on an uncommon path (rare race, edge encoding). Fix or file a follow-up issue.
+- **MINOR bug** is rare for the Bug category — usually means Sonar isn't sure. Verify before reporting.
+
+Trust Sonar's severity here; the Bug catalog is the most-calibrated of the five lenses.
+
+## Anti-patterns when reporting Bugs
+
+- ❌ Restating the rule name as the "why". The rule name is in the catalog — your job is the *scenario* in this codebase.
+- ❌ Fixing the symptom not the cause. ❌ "Wrap in try/catch and log." ✅ "The caller passes `null` from `getDiscount` when no promo applies — change `getDiscount` to return `{amount: 0}` instead of null, then this site needs no guard."
+- ❌ Down-grading a BLOCKER because it "looks fine to you". The bug catalog is mechanical — if Sonar caught a null deref, there's a path to it. Find the path or trust the rule.
+- ❌ Recommending `// NOSONAR` as the fix. Reserve that for documented exceptions; it's never the right answer for a Bug.

package/skills/sonar-review/lenses/code-smells.md

@@ -0,0 +1,64 @@
+# Lens 4 — Code Smells
+
+The **maintainability** lens. Code smells aren't bugs or security issues — they're patterns Sonar predicts will slow future change. The catalog is large and noisy; this lens is where over-reporting hurts the report most.
+
+## What you're looking at
+
+Filter issues to `type=CODE_SMELL` and changed files. Common families on new code:
+
+| Family | Example IDs | Worth reporting on changed code? |
+|---|---|---|
+| Cognitive complexity | `S3776` | ✅ Yes — predictive of bugs |
+| Function / method length | `S138`, `S104` | ✅ Yes — but often a refactor target, not a one-line fix |
+| Parameter count | `S107` | ✅ Yes |
+| Duplicated string literals | `S1192` | 🟨 Maybe — only if literal is meaningful (URL, key) |
+| Magic numbers | `S109` | 🟨 Maybe — extract a constant if used > 2 places |
+| Unused imports / variables | `S1481`, `S1128` | ✅ Yes — trivial fix |
+| Empty methods / classes | `S1186`, `S1186` | ✅ Yes |
+| TODO / FIXME comments | `S1135` | ⚪ Info — surface in count, don't list each |
+| Naming conventions | `S100`, `S116` | 🟨 Only flag if the new identifier breaks the project's pattern |
+| `console.log` / `print` | `S2228`, `S1854` | ✅ Yes if not behind a logger |
+| Deprecated API use | `S1874` | ✅ Yes |
+| Commented-out code | `S125` | 🟨 Maybe — sometimes intentional (TODO + commented call) |
+
+The principle: **report what's actionable in this PR, summarize what isn't**. A finding the user can fix in five minutes is worth a line; a refactor finding that requires opening four files is worth one line in summary form.
+
+## How to phrase each finding
+
+Standard four parts:
+
+1. **Where** — `file:line` + a quote.
+2. **Rule + category** — `[SMELL · typescript:S3776] Cognitive complexity 22 > 15`.
+3. **Why it matters** — the *future-maintenance* cost, in concrete terms. ✅ "`processOrder` has six nested conditionals; the next person debugging a refund flow has to trace all six to know which branch they're in." ❌ "Code is too complex."
+4. **Fix** — concrete:
+   - Complexity → extract one of the conditional branches into a named function. Suggest the name.
+   - Long parameter list → struct/object parameter. Name the fields.
+   - Magic number → name the constant. Suggest the name and the scope (file-level vs class-level).
+   - Duplicated literal → suggest the constant name + the line numbers that should reference it.
+
+## Calibration
+
+Sonar's severity on code smells is **less reliable** than on bugs/vulns — the same `S3776` is CRITICAL when complexity is 30 and MAJOR when it's 16. Trust the severity, but don't expect every CRITICAL smell to actually block merge.
+
+| Severity | Treat as |
+|---|---|
+| 🟥 BLOCKER | Rare for smells; usually means complexity is extreme (>25). Treat as merge-blocker. |
+| 🟧 CRITICAL | High-cost smell on load-bearing code. Fix before merge. |
+| 🟨 MAJOR | Most common smell severity. Fix if cheap; defer if the refactor is large. |
+| ⚪ MINOR | Style + naming. Roll up into a count if there are > 5. |
+
+## Aggregation rule
+
+If the new code has more than **8 minor code smells of the same rule** (e.g. 12 magic numbers in one file), don't list each — emit one rolled-up finding:
+
+> 🟨 **`typescript:S1192` — String literal duplication × 12** in `src/api/orders.ts`. The literal `"USD"` appears 12 times across `createOrder`, `applyDiscount`, and `formatTotal`. Extract `const CURRENCY = "USD"` at the top of the file and reference it from each site.
+
+Don't bury single-instance findings in rollups — only roll up repeats of the same rule in the same area.
+
+## Anti-patterns when reporting Code Smells
+
+- ❌ **Listing every smell**. The report becomes unreadable. Prioritize, aggregate, summarize the tail.
+- ❌ **Recommending a rename as the fix for a complexity smell.** Renaming doesn't reduce complexity. Extract a function or flip a guard clause.
+- ❌ **Flagging style on a PR that fixes a bug.** If the change is a targeted bug fix and the smells are pre-existing in the same function, those go in the "pre-existing issues touched" FYI section, not the main report.
+- ❌ **Treating `S1192` (string duplication) as serious in tests.** Tests are *supposed* to repeat literals — that's how you read them. If Sonar flags `"alice"` appearing 8 times across tests, downgrade to nit or drop.
+- ❌ **Confusing "long function" with "complex function".** A 200-line function with no branching is fine; a 30-line function with seven nested `if`s is the smell. Cite `S3776` (cognitive complexity), not `S138` (length), when complexity is the real issue.

package/skills/sonar-review/lenses/coverage-and-duplication.md

@@ -0,0 +1,74 @@
+# Lens 5 — Coverage + Duplication
+
+These aren't "issues" in Sonar's data model — they're **quality-gate conditions** measured against the project's new code. They're reported in the gate's `conditions` array, not the issues list. They're often what fails an otherwise-clean gate.
+
+## Coverage on new code
+
+Sonar measures *lines and branches added or modified in this branch*. A file that wasn't touched contributes nothing to the new-code coverage metric; touching it forces the touched lines into the measurement.
+
+**Default gate condition:** ≥ 80% coverage on new code.
+
+### What to report
+
+Fetch the gate JSON, find conditions where `metricKey=new_coverage` and `status=ERROR`. Then drill into:
+
+```bash
+curl -s -u "$SONAR_TOKEN:" \
+  "$SONAR_HOST_URL/api/measures/component_tree?component=$PROJECT_KEY&branch=$BRANCH&metricKeys=new_uncovered_lines,new_lines_to_cover&qualifiers=FIL"
+```
+
+Identify the files dragging the percentage down. Report:
+
+> ❌ **Coverage on new code: 71%** (gate requires ≥ 80%)
+> - `src/jobs/export.ts` — 47/82 new lines covered (57%). Uncovered: error paths at lines 55–62 and 71–78.
+> - `src/api/checkout.ts` — 31/40 new lines covered (78%). Uncovered: the new `null discount` branch at line 47.
+>
+> **Fix:** Add three tests covering the error paths in `export.ts` and the null-discount branch in `checkout.ts`. The happy path is already covered.
+
+### Naming the missing tests
+
+Don't say "add tests" — name them. ✅ "Add a test `it('returns empty when upstream API 500s', ...)` covering `export.ts:55–62`." ❌ "Improve test coverage."
+
+If you can't name the missing test scenario, the coverage finding isn't actionable — you don't understand the uncovered branch well enough to flag it as a finding. Drop it and let the gate fail until the user adds the case themselves.
+
+### When coverage looks worse than it is
+
+- **Tests in changed dirs not running.** The coverage tool ran but didn't include the new tests. Symptom: 0% on a file that clearly has tests beside it. Check `sonar.tests` and the coverage report path in `sonar-project.properties`.
+- **Coverage exclusions stripped the wrong files.** Symptom: clearly-covered file shows uncovered. Check `sonar.coverage.exclusions`.
+- **Generated files counted.** Symptom: lots of "uncovered" in `__generated__` or `dist/`. Add to `sonar.exclusions`.
+
+If you suspect a config issue, **say so explicitly** rather than reporting the bad number as fact: "Coverage shows 0% on `src/payments/`, but `payments.test.ts` exists at the same level — the coverage importer may not be picking up the report. Check `sonar.javascript.lcov.reportPaths` in `sonar-project.properties`."
+
+## Duplication
+
+**Default gate condition:** ≤ 3% duplicated lines on new code.
+
+Duplication catches copy-paste — a block of ≥ 100 tokens (≈ 10 lines for most languages) that appears more than once. The catalog rule is `common-{language}:DuplicatedBlocks`.
+
+### What to report
+
+For each duplication block on changed code:
+
+> 🟨 **Duplication: `src/api/checkout.ts:47–78` duplicates `src/api/refund.ts:32–63`** (32 lines, 89% match).
+>
+> The discount-application logic is now copied across both endpoints — the next change to discount handling has to be made twice. Extract `applyDiscount` into `src/lib/discounts.ts` and call it from both.
+
+If duplication is *within* the same file, treat it as a single-file refactor — extract a helper at the file top.
+
+If duplication is *between* a new file and an existing one, the fix usually means modifying the existing file too. Flag this explicitly — the user may have been told not to touch the other file. Suggest the extraction location, then let them decide.
+
+### When duplication is intentional
+
+Sometimes duplication is correct — test fixtures, parallel implementations across services, migration scripts that intentionally mirror old code. If you can see this is the case (e.g. the duplicated code is in `tests/` or named `migrate_*`), say so:
+
+> 🟨 **Duplication: `tests/checkout.test.ts:47–78` duplicates `tests/refund.test.ts:32–63`**.
+>
+> The two tests share setup. This is the common-fixture case — extract `setupTestOrder()` into `tests/_helpers.ts`. Not a quality-gate blocker (tests are excluded by default in `sonar.coverage.exclusions` but counted for duplication unless excluded explicitly).
+
+## Anti-patterns when reporting Coverage / Duplication
+
+- ❌ **Reporting the percentage without the files dragging it.** "Coverage is 71%" isn't actionable. Name the under-covered files and the uncovered branches.
+- ❌ **Demanding 100% coverage** on the new code. The gate asks for 80% (or whatever the project sets); 100% is rarely worth the test brittleness.
+- ❌ **Demanding tests for log statements / pass-through error paths.** Coverage of a `console.log(...)` line teaches nothing. Suggest the *meaningful* missing scenarios.
+- ❌ **Treating duplication in tests as urgent.** Test fixtures often repeat; the refactor is "nice to have", not gate-blocking, and Sonar agrees if `sonar.cpd.exclusions` is set on `**/*.test.*`.
+- ❌ **Telling the user to disable the gate condition.** The fix is more tests or a small refactor, not weakening the gate. If 80% is structurally impossible for this project, raise it as a separate gate-tuning conversation, not a per-PR finding.

package/skills/sonar-review/lenses/security-hotspots.md

@@ -0,0 +1,56 @@
+# Lens 3 — Security Hotspots
+
+Hotspots are the lens most agents get wrong. They are **not** vulnerabilities. They are **security-sensitive code patterns Sonar can't auto-decide are safe** — the resolution is a *human security review*, recorded in Sonar as **Safe**, **At Risk**, or **Acknowledged**.
+
+Hotspots come from a **different API** (`/api/hotspots/search`) than Issues. The quality gate counts unresolved hotspots — so an un-reviewed hotspot fails the gate even if the code is secure.
+
+## What you're looking at
+
+| Family | Example IDs | What it catches |
+|---|---|---|
+| Cryptographic operations | `S4426`, `S2278` | Use of crypto APIs (could be configured weakly) |
+| Random number generation | `S2245` | `Math.random()` / `Random` — fine for UI, dangerous for tokens |
+| Regex DoS | `S5852` | Catastrophic backtracking patterns |
+| File permissions | `S2612` | World-writable file creation |
+| Authentication / authorization | `S5332` | TLS disabled, `verify=False`, `--insecure` |
+| User-controlled file paths | `S2083` (sometimes Hotspot) | Where validation might be present |
+| Hardcoded IPs / CIDR | `S1313` | Could be a test fixture, could be a backdoor |
+| Cookie / session config | `S2092`, `S3330` | Missing flags Sonar can't verify in context |
+| HTTP method overrides | `S5122` | CORS / `_method` rewriting |
+| Command execution | `S4721` | `exec`-shaped calls (may be safe with constants) |
+
+## How to phrase each Hotspot finding
+
+This lens has **five** parts, not four — because the artifact you produce isn't "fix this", it's "evidence for the user to make a decision":
+
+1. **Where** — `file:line` + the sensitive call. Quote 5–15 chars.
+2. **Rule + category** — `[HOTSPOT · javascript:S2245] Pseudorandom generator use`.
+3. **Why it's flagged** — what *category* of risk Sonar is asking about. ✅ "`Math.random()` is fine for UI shuffling but unsafe for security tokens." ❌ "Insecure RNG."
+4. **Evidence for review** — what *this codebase* tells you about whether the usage is actually risky. Quote the surrounding context:
+   - Where does the value flow next? (logged? sent? stored? returned to user?)
+   - Are there upstream guards? Quote them with `file:line`.
+   - Is this test/dev-only code? Quote the file path or test scaffolding around it.
+5. **Action** — name the **resolution the user should record in Sonar**, with the reasoning they should paste into the resolution comment:
+   - **Safe** — quote the upstream guard or the non-security usage that makes it OK.
+   - **At Risk** — name the path you can't rule out + the code fix.
+   - **Acknowledged** — for known issues with a tracked follow-up. Include the ticket reference.
+
+## Calibration
+
+Hotspots don't carry the BLOCKER/CRITICAL/MAJOR severities issues do — they have a **review priority** (`HIGH`/`MEDIUM`/`LOW`) and a **status** (`TO_REVIEW`/`REVIEWED`). Map to your report:
+
+| Hotspot priority | Report marker |
+|---|---|
+| HIGH | 🟧 |
+| MEDIUM | 🟨 |
+| LOW | ⚪ |
+
+Group hotspots in their own section — don't intermix with bugs/vulnerabilities. They're a different shape of finding.
+
+## Anti-patterns when reporting Hotspots
+
+- ❌ **Treating Hotspots like Vulnerabilities.** A Hotspot isn't a defect — it's a question. Reporting "fix this insecure RNG" when the value flows to a UI shuffle is wrong; the answer is "mark Safe with this evidence."
+- ❌ **Recommending a code patch without naming the resolution.** A code patch alone doesn't clear the hotspot in Sonar — the user still needs to mark it Reviewed. Always include "and mark `<status>` in the Sonar UI with the evidence above".
+- ❌ **Skipping the evidence step.** "Looks fine to me" isn't actionable. Quote the upstream guard or the test-only usage that lets the user click Safe with confidence.
+- ❌ **Marking everything At Risk to be cautious.** If the evidence is "no upstream guard, flows to user output", say At Risk. If the evidence is "constant string from build config, never user-influenced", say Safe. Hedging defeats the workflow.
+- ❌ **Forgetting that un-reviewed hotspots fail the gate.** Even a clearly-safe hotspot fails the gate until reviewed. Tell the user explicitly: "marking this Safe is what unblocks the gate — not a code change."