@codyswann/lisa 2.176.12 → 2.177.0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.176.12",
+  "version": "2.177.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.12",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.12",
+  "version": "2.177.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.12",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.12",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.176.12",
+  "version": "2.177.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/rules/eager/integration-access-layer.md

@@ -0,0 +1,10 @@
+# Integration Access Layer
+
+Skills and rules that use external integrations route through the matching
+`*-access` skill. Do not call vendor MCP tools or REST APIs directly from a
+consumer skill.
+
+Resolution order is MCP when available and authenticated, then documented
+token/REST substrate when the env var is set, then a loud error naming the env
+var. Full matrix and migration rules:
+[reference/integration-access-layer.md](../reference/integration-access-layer.md).

package/plugins/src/base/rules/reference/integration-access-layer.md

@@ -0,0 +1,56 @@
+# Integration Access Layer
+
+Every Lisa skill or rule that consumes an external integration MUST route through
+the integration's `*-access` skill instead of calling that vendor's MCP tools or
+REST API directly.
+
+The access skill owns substrate resolution:
+
+1. MCP, when the tool is available and already authenticated to the configured
+   workspace/account.
+2. Token/REST substrate, only when the documented env var is present.
+3. Loud failure naming the exact env var to set.
+
+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.
+
+## Access Skills
+
+| Vendor | Access skill | Headless env var | REST/token substrate |
+|---|---|---|---|
+| Atlassian | `lisa:atlassian-access` | `ATLASSIAN_API_TOKEN` | Atlassian Cloud REST |
+| 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 MCP HTTP endpoint with bearer PAT |
+| SonarCloud | `lisa:sonarcloud-access` | `SONAR_TOKEN` | SonarCloud Web API |
+| Sentry | `lisa:sentry-access` | `SENTRY_AUTH_TOKEN` | Sentry REST API |
+| PostHog | `lisa:posthog-access` | `POSTHOG_PERSONAL_API_KEY` | PostHog REST API |
+
+## Current Coupling Matrix
+
+Source audit date: 2026-06-23. Scope: `plugins/src/**/skills/**` and
+`plugins/src/**/rules/**`.
+
+| Vendor | Direct source MCP references | Current route | Retrofit status |
+|---|---:|---|---|
+| Atlassian | setup-only references plus legacy stack-generated sources | `atlassian-access` for base runtime paths | Done for base hot paths; stack overlays still need sync from base patterns when touched. |
+| 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. |
+| 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. |
+
+## Migration Rule For Consumers
+
+When editing any skill listed in the matrix:
+
+- Replace direct `mcp__<vendor>__*` calls in `allowed-tools` with `Skill` and
+  delegate to the matching access skill.
+- Keep operation names coarse and vendor-native. Add new operation rows to the
+  access skill instead of embedding REST details in the consumer.
+- Preserve existing MCP behavior as the first tier where Claude/Codex can expose
+  the MCP, but make headless token fallback explicit and gated by the env var.
+- If a vendor has no documented token substrate, keep the MCP-only behavior and
+  fail with a clear "no documented headless substrate" message.

package/plugins/src/base/skills/jam-access/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jam-access
+description: "Vendor-neutral access layer for Jam. Jam triage rules and skills MUST delegate through this skill rather than calling Jam MCP tools directly. Resolves Jam MCP first when available, then falls back to JAM_PAT bearer auth for headless routines."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Jam Access: $ARGUMENTS
+
+Single chokepoint for Jam operations. Caller skills and rules MUST NOT call
+`mcp__Jam__*` tools directly.
+
+## Invocation Contract
+
+```text
+operation: get-trace url:<jam-url-or-id>
+operation: get-recording url:<jam-url-or-id>
+operation: get-bug-report url:<jam-url-or-id>
+```
+
+Return parsed JSON or a concise structured summary in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Jam MCP, if the tool is available and authenticated.
+2. `JAM_PAT` bearer token against Jam's MCP/trace HTTP substrate.
+
+Jam documents personal access tokens for MCP clients so a browser OAuth flow is
+not required. The headless tier uses:
+
+```bash
+curl -sS "https://mcp.jam.dev/mcp" \
+  -H "Authorization: Bearer $JAM_PAT" \
+  -H "Content-Type: application/json" \
+  --data-binary "$PAYLOAD"
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PAT.
+```
+
+## Invariants
+
+- Fallback is gated on `JAM_PAT`; do not retry Jam MCP failures blindly.
+- Never commit a Jam PAT into `.mcp.json`. Use env interpolation in host MCP
+  config, for example `Authorization: Bearer ${JAM_PAT}`.
+- If a requested operation is not yet mapped to the Jam HTTP substrate, surface
+  that exact missing adapter instead of pretending the trace is unavailable.

package/plugins/src/base/skills/linear-access/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear-access
+description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Resolves Linear MCP first when authenticated, then falls back to LINEAR_API_KEY + Linear GraphQL in headless environments."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Linear Access: $ARGUMENTS
+
+Single chokepoint for Linear operations. Caller skills (`linear-*`) MUST go
+through this skill. They MUST NOT call `mcp__linear-server__*` tools directly or
+curl `https://api.linear.app/graphql` themselves.
+
+## Invocation Contract
+
+```text
+operation: list-teams [query:<KEY>]
+operation: get-team id:<ID>
+operation: list-projects [team:<KEY>] [label:<NAME>] [state:<arr>]
+operation: get-project id:<ID>
+operation: save-project payload:{...}
+operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state_type:<arr>]
+operation: get-issue id:<ID>
+operation: save-issue payload:{...}
+operation: list-comments issue_id:<ID>
+operation: save-comment issue_id:<ID> body:"..."
+operation: list-issue-labels [team:<ID>]
+operation: create-issue-label payload:{...}
+operation: list-project-labels
+operation: create-project-label payload:{...}
+operation: list-documents project_id:<ID>
+operation: get-document id:<ID>
+```
+
+Return parsed JSON in a `<result>` block. On failure, prefix the message with
+`Error:` and include the failing operation name.
+
+## Substrate Selection
+
+Read config:
+
+```bash
+WORKSPACE=$(jq -r '.linear.workspace // empty' .lisa.config.json 2>/dev/null)
+TEAM_KEY=$(jq -r '.linear.teamKey // empty' .lisa.config.json 2>/dev/null)
+```
+
+Probe in order:
+
+1. Linear MCP, if `mcp__linear-server__list_teams` is available and can list the
+   configured workspace/team.
+2. `LINEAR_API_KEY` with Linear GraphQL (`https://api.linear.app/graphql`).
+
+The Linear GraphQL docs support personal API keys for scripts and authenticate
+with an `Authorization: <API_KEY>` header. Treat `LINEAR_API_KEY` as the
+headless substrate. If neither tier works, fail with:
+
+```text
+Error: no Linear access substrate available. Authenticate the Linear MCP or set LINEAR_API_KEY.
+```
+
+## GraphQL Adapter
+
+All GraphQL calls use:
+
+```bash
+linear_graphql() {
+  local query="$1"
+  local variables="${2:-{}}"
+  [ -n "$LINEAR_API_KEY" ] || {
+    echo "Error: LINEAR_API_KEY is not set." >&2
+    return 1
+  }
+  jq -n --arg query "$query" --argjson variables "$variables" \
+    '{query:$query, variables:$variables}' |
+    curl -sS -X POST "https://api.linear.app/graphql" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: '"$LINEAR_API_KEY"'" \
+      --data-binary @-
+}
+```
+
+Map operation names to Linear GraphQL queries/mutations in this access skill.
+Consumers pass business-shaped arguments only; they do not embed GraphQL.
+
+## Invariants
+
+- MCP is preferred when it is present and already authenticated.
+- GraphQL fallback runs only when `LINEAR_API_KEY` is present.
+- Missing MCP plus missing token is a hard failure naming `LINEAR_API_KEY`.
+- Mutations send only the fields being changed, matching existing Linear skill
+  guidance that `save_*` style updates should not clobber unrelated fields.

package/plugins/src/base/skills/posthog-access/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: posthog-access
+description: "Vendor-neutral access layer for PostHog. PostHog skills and observability rules MUST delegate through this skill rather than calling PostHog MCP tools or REST directly. Resolves PostHog MCP first when available, then falls back to POSTHOG_PERSONAL_API_KEY bearer auth."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# PostHog Access: $ARGUMENTS
+
+Single chokepoint for PostHog operations. Caller skills and rules MUST NOT call
+`mcp__posthog__*` tools or PostHog REST directly.
+
+## Invocation Contract
+
+```text
+operation: query project_id:<ID> payload:{...}
+operation: insights project_id:<ID>
+operation: persons project_id:<ID> [query:<QUERY>]
+operation: events project_id:<ID> [after:<ISO>] [before:<ISO>]
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. PostHog MCP, if available and authenticated.
+2. `POSTHOG_PERSONAL_API_KEY` bearer token against the configured PostHog host.
+
+PostHog documents personal API keys and bearer authentication. The headless REST
+tier uses:
+
+```bash
+POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+posthog_api() {
+  local path="$1"
+  local method="${2:-GET}"
+  local body="${3:-}"
+  [ -n "$POSTHOG_PERSONAL_API_KEY" ] || {
+    echo "Error: POSTHOG_PERSONAL_API_KEY is not set." >&2
+    return 1
+  }
+  local args=(-sS -X "$method" -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY")
+  [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
+  curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
+}
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
+```
+
+## Invariants
+
+- Fallback is gated on `POSTHOG_PERSONAL_API_KEY`.
+- `POSTHOG_HOST` defaults to PostHog Cloud but can point at a self-hosted
+  deployment.
+- Consumer skills do not embed PostHog REST paths.

package/plugins/src/base/skills/sentry-access/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: sentry-access
+description: "Vendor-neutral access layer for Sentry. Sentry-oriented skills MUST delegate through this skill rather than calling Sentry MCP tools, sentry-cli, or REST directly. Resolves Sentry MCP/CLI first when available, then falls back to SENTRY_AUTH_TOKEN + Sentry REST API."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Sentry Access: $ARGUMENTS
+
+Single chokepoint for Sentry operations. Caller skills MUST NOT call
+`mcp__sentry__*`, `sentry-cli`, or `https://sentry.io/api/` directly.
+
+## Invocation Contract
+
+```text
+operation: list-issues org:<ORG> project:<PROJECT> query:<QUERY> [environment:<ENV>]
+operation: get-issue issue_id:<ID>
+operation: events org:<ORG> project:<PROJECT> query:<QUERY>
+operation: releases org:<ORG> project:<PROJECT>
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Sentry MCP, if available and authenticated.
+2. `sentry-cli`, if installed and authenticated to the requested org/project.
+3. `SENTRY_AUTH_TOKEN` bearer token against Sentry REST.
+
+Sentry documents API auth tokens for REST API calls. The headless REST tier uses:
+
+```bash
+sentry_api() {
+  local path="$1"
+  [ -n "$SENTRY_AUTH_TOKEN" ] || {
+    echo "Error: SENTRY_AUTH_TOKEN is not set." >&2
+    return 1
+  }
+  curl -sS "https://sentry.io/api/0${path}" \
+    -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
+}
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set SENTRY_AUTH_TOKEN.
+```
+
+## Invariants
+
+- Fallback is gated on `SENTRY_AUTH_TOKEN`.
+- Org/project come from `.sentryclirc`, `.lisa.config.json`, or explicit
+  operation args; never infer by searching all accessible orgs.
+- Consumer skills do not embed Sentry REST paths.

package/plugins/src/base/skills/sonarcloud-access/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: 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."
+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.
+
+## Invocation Contract
+
+```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>
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Sonar MCP, if available and authenticated.
+2. `SONAR_TOKEN` against the SonarCloud Web API.
+
+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"
+}
+```
+
+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:
+
+```text
+Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
+```
+
+## REST Dispatch
+
+| Operation | REST path |
+|---|---|
+| `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>` |
+
+## 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.

package/scripts/generate-codex-plugin-artifacts.mjs

@@ -191,12 +191,28 @@ const ACRONYMS = new Set([
   "llm",
 ]);
 
+/**
+ * Brand names whose mixed-case capitalization cannot be reproduced by the
+ * simple title-case or all-upper-case rules above.
+ *
+ * Keys are lower-cased token forms (as they appear split from a kebab skill
+ * name). Values are the canonical display spellings. Entries here take
+ * precedence over both {@link ACRONYMS} and the default title-case path so
+ * that `posthog-access` -> "PostHog Access" rather than "Posthog Access".
+ */
+const BRAND_NAMES = new Map([
+  ["posthog", "PostHog"],
+  ["sonarcloud", "SonarCloud"],
+]);
+
 /**
  * Humanize a kebab/snake/space-delimited token into a Title-Cased display name.
  *
  * Splits on `-`, `_`, and runs of whitespace, then title-cases each word —
- * except tokens in {@link ACRONYMS}, which are upper-cased. This is the rule the
- * PRD (#521) specifies for `display_name`: `exploratory-qa` -> "Exploratory QA".
+ * except tokens in {@link ACRONYMS}, which are upper-cased, and tokens in
+ * {@link BRAND_NAMES}, which are emitted with their canonical spelling.
+ * This is the rule the PRD (#521) specifies for `display_name`:
+ * `exploratory-qa` -> "Exploratory QA".
  * Pure: same input always yields the same output.
  *
  * @param {string} raw The raw skill/frontmatter name token.
@@ -206,11 +222,16 @@ function humanizeName(raw) {
   return raw
     .split(/[-_\s]+/)
     .filter(word => word.length > 0)
-    .map(word =>
-      ACRONYMS.has(word.toLowerCase())
-        ? word.toUpperCase()
-        : word.charAt(0).toUpperCase() + word.slice(1)
-    )
+    .map(word => {
+      const lower = word.toLowerCase();
+      if (BRAND_NAMES.has(lower)) {
+        return BRAND_NAMES.get(lower);
+      }
+      if (ACRONYMS.has(lower)) {
+        return word.toUpperCase();
+      }
+      return word.charAt(0).toUpperCase() + word.slice(1);
+    })
     .join(" ");
 }