@codyswann/lisa 3.4.1 → 3.5.0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "3.4.1",
+  "version": "3.5.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": "3.4.1",
+  "version": "3.5.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": "3.4.1",
+  "version": "3.5.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": "3.4.1",
+  "version": "3.5.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": "3.4.1",
+  "version": "3.5.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": "3.4.1",
+  "version": "3.5.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/credential-substrate-precedence.md

@@ -20,7 +20,9 @@ scope for that skill's work.
    `lisa-secrets-access`, chosen whenever its bootstrap credential is available **and**
    the resolved substrate identity-matches the configured tenant/workspace/site.
    `lisa-secrets-access` is the single chokepoint — never read an OS keychain a second
-   time.
+   time. The two legacy OS-keychain rungs that remain (`lisa-atlassian-access`,
+   `lisa-notion-access`) are a dated migration ramp with a **removal date of
+   2026-11-01**, not a standing exemption; no new access skill may add one.
 2. **Tier 2 — interactive MCP**, used only when tier 1 is *genuinely* unavailable:
    no bootstrap, no adapter for the operation (per-operation, not per-session), or a
    provider outage. "The MCP happens to be authenticated" and "tier 1 is slower" are

package/plugins/src/base/rules/reference/credential-substrate-precedence.md

@@ -139,6 +139,26 @@ operation, the fallback is guarded — never the normal path:
 A successful pre-flight switch is not sufficient for tenant safety — another process can
 mutate global state between the check and the write.
 
+## Legacy OS-keychain fallback — removal date 2026-11-01
+
+Two access skills (`lisa-atlassian-access`, `lisa-notion-access`) still read an
+OS keychain as a last rung below the chokepoint, because the guided
+`/lisa:setup:atlassian` and `/lisa:setup:notion` flows wrote credentials there
+before `lisa-secrets-access` existed. That rung is a **migration ramp with a
+removal date, not a standing exemption**: it is a second reader of the same
+credential, which is exactly how one credential ends up living in two places and
+drifting, and a keychain entry is machine-local ambient state that no headless
+surface can reach — so a project resting on it has no working tier 1 in cron, CI,
+or a cloud session.
+
+**Both rungs are deleted on 2026-11-01.** Before then, projects still on the
+keychain path move the credential into their configured provider — re-running
+`/lisa:setup:<vendor>` stores it through the chokepoint. After removal, a
+keychain-only project fails loudly with the exact variable named (tier 3), which
+is the intended outcome: it can never silently resolve through a substrate
+authenticated elsewhere. No new access skill may add a keychain rung; a credential
+the chokepoint cannot answer for is a setup gap to fix, not a store to add.
+
 ## Consequences to expect
 
 - **A stale or wrong token now fails identity-match instead of silently succeeding

package/plugins/src/base/skills/lisa-atlassian-access/SKILL.md

@@ -69,6 +69,13 @@ read_atlassian_token() {
   # Legacy fallback: the OS keychain written by the guided /lisa:setup:atlassian
   # flow, for projects that have not adopted a credentials provider. Reached only
   # when the chokepoint is absent or has no entry.
+  #
+  # This rung is REMOVED ON 2026-11-01 — a dated migration ramp, not a standing
+  # exemption (see credential-substrate-precedence, "Legacy OS-keychain fallback
+  # — removal date"). A keychain entry is machine-local ambient state no headless
+  # surface can reach, so a project resting on it has no working tier 1 in cron,
+  # CI, or a cloud session. Re-run /lisa:setup:atlassian before that date to
+  # store ATLASSIAN_API_TOKEN through the chokepoint instead.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;

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

@@ -39,20 +39,55 @@ headlessly — which is why it leads. The CLI tier uses:
 ```bash
 curl -fsSL https://native.jam.dev/install | bash
 export PATH="$HOME/.local/bin:$PATH"
-printf '%s' "$JAM_PAT" | jam auth login --token
+
+# Resolve the PAT through the chokepoint before giving up on the environment.
+# `$JAM_PAT` is the documented fallback, not the only rung: without this, a
+# project that keeps its credentials in Bitwarden, Doppler, or AWS has no tier 1
+# path at all and silently resolves through the interactive MCP — the exact
+# divergence `credential-substrate-precedence` exists to remove.
+read_jam_pat() {
+  [ -n "${JAM_PAT:-}" ] && { echo "$JAM_PAT"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get JAM_PAT 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
+# Piped, never written to disk and never passed as an argv token: a PAT on a
+# command line is readable from the process table by every user on the host.
+read_jam_pat | jam auth login --token
 jam skills install
 ```
 
 If neither tier works, fail with:
 
 ```text
-Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PAT.
+Error: no Jam access substrate available. Authenticate the Jam MCP, set JAM_PAT, or store JAM_PAT in this project's secrets provider.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — fetching a trace,
+a recording, or a bug report. So the `credential-substrate-precedence` guarded
+fallback for mutating operations (write, read back, assert the tenant from the
+response, roll back on mismatch) is not engaged here, and a failed tier is
+simply skipped. A future operation that mutates Jam state — commenting on or
+deleting a Jam — is a write and MUST reconcile by read-back before any retry.
+
 ## Invariants
 
 - Tier order is `credential-substrate-precedence`: `JAM_PAT` CLI first, Jam MCP as
   a preserved first-class fallback. Do not retry a failed tier blindly.
+- The PAT is resolved through `lisa-secrets-access`, with the bare `JAM_PAT`
+  environment variable as the documented fallback. Never read a second
+  credential store directly.
 - Never commit a Jam PAT into `.mcp.json` or any generated setup artifact.
 - Headless Jam access requires `native.jam.dev` for the installer and
   `api.jam.dev` for CLI/API calls in any custom remote network allowlist.

package/plugins/src/base/skills/lisa-notion-access/SKILL.md

@@ -70,6 +70,13 @@ read_notion_token() {
   # Legacy fallback: the OS keychain written by the guided /lisa:setup:notion
   # flow, for projects that have not adopted a credentials provider. Reached only
   # when the chokepoint is absent or has no entry.
+  #
+  # This rung is REMOVED ON 2026-11-01 — a dated migration ramp, not a standing
+  # exemption (see credential-substrate-precedence, "Legacy OS-keychain fallback
+  # — removal date"). A keychain entry is machine-local ambient state no headless
+  # surface can reach, so a project resting on it has no working tier 1 in cron,
+  # CI, or a cloud session. Re-run /lisa:setup:notion before that date to store
+  # NOTION_API_TOKEN through the chokepoint instead.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-notion -a "$workspace" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && \

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

@@ -40,15 +40,38 @@ works interactively and headlessly — which is why it leads. The REST tier uses
 
 ```bash
 POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+
+# Resolve the key through the chokepoint before giving up on the environment.
+# `$POSTHOG_PERSONAL_API_KEY` is the documented fallback, not the only rung:
+# without this, a project that keeps its credentials in Bitwarden, Doppler, or
+# AWS has no tier 1 path at all and silently resolves through the interactive
+# MCP — the exact divergence `credential-substrate-precedence` exists to remove.
+read_posthog_key() {
+  [ -n "${POSTHOG_PERSONAL_API_KEY:-}" ] && { echo "$POSTHOG_PERSONAL_API_KEY"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get POSTHOG_PERSONAL_API_KEY 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
 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
+  local key
+  key=$(read_posthog_key) || {
+    echo "Error: no PostHog key. Set POSTHOG_PERSONAL_API_KEY, or store it as" >&2
+    echo "POSTHOG_PERSONAL_API_KEY in this project's secrets provider." >&2
     return 1
   }
-  local args=(-sS -X "$method" -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY")
+  local args=(-sS -X "$method" -H "Authorization: Bearer $key")
   [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
   curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
 }
@@ -60,11 +83,25 @@ If neither tier works, fail with:
 Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — analytics
+retrieval. `query` is an HTTP POST, but it reads: it submits a query body and
+changes no PostHog state. So the `credential-substrate-precedence` guarded
+fallback for mutating operations (write, read back, assert the tenant from the
+response, roll back on mismatch) is not engaged here, and a failed tier is
+simply skipped. Adding a genuinely mutating operation — creating an insight,
+editing a feature flag — pulls that protocol in: a write of unknown outcome MUST
+reconcile by read-back before any retry.
+
 ## Invariants
 
 - Tier order is `credential-substrate-precedence`: `POSTHOG_PERSONAL_API_KEY`
   first, the PostHog MCP as a preserved first-class fallback. Identity-match
   against the configured project is mandatory on every tier.
+- The key is resolved through `lisa-secrets-access`, with the bare
+  `POSTHOG_PERSONAL_API_KEY` environment variable as the documented fallback.
+  Never read a second credential store directly.
 - `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/lisa-sentry-access/SKILL.md

@@ -39,28 +39,69 @@ Sentry documents API auth tokens for REST API calls, and the same token works
 interactively and headlessly — which is why it leads. The REST tier uses:
 
 ```bash
+# Resolve the token through the chokepoint before giving up on the environment.
+# `$SENTRY_AUTH_TOKEN` is the documented fallback, not the only rung: without
+# this, a project that keeps its credentials in Bitwarden, Doppler, or AWS has
+# no tier 1 path at all and silently resolves through the interactive MCP —
+# the exact divergence `credential-substrate-precedence` exists to remove.
+# Mirrors `linear-access`, `atlassian-access`, and `notion-access`.
+read_sentry_token() {
+  [ -n "${SENTRY_AUTH_TOKEN:-}" ] && { echo "$SENTRY_AUTH_TOKEN"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get SENTRY_AUTH_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
 sentry_api() {
   local path="$1"
-  [ -n "$SENTRY_AUTH_TOKEN" ] || {
-    echo "Error: SENTRY_AUTH_TOKEN is not set." >&2
+  local token
+  token=$(read_sentry_token) || {
+    echo "Error: no Sentry auth token. Set SENTRY_AUTH_TOKEN, or store it as" >&2
+    echo "SENTRY_AUTH_TOKEN in this project's secrets provider." >&2
     return 1
   }
   curl -sS "https://sentry.io/api/0${path}" \
-    -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
+    -H "Authorization: Bearer $token"
 }
 ```
 
+Tier 1a authenticates `sentry-cli` from the **same resolved token**
+(`SENTRY_AUTH_TOKEN=$(read_sentry_token) sentry-cli …`) — never from a second
+credential store, and never from an interactive `sentry-cli login` keychain.
+
 If neither tier works, fail with:
 
 ```text
 Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set SENTRY_AUTH_TOKEN.
 ```
 
+## Mutation boundary
+
+Every operation in the Invocation Contract is **read-only** — issue, event, and
+release retrieval. So the `credential-substrate-precedence` guarded fallback for
+mutating operations (write, read back, assert the tenant from the response, roll
+back on mismatch) is not engaged here, and a failed tier is simply skipped. Any
+future operation that mutates Sentry state — resolving an issue, editing a
+release — is a write and MUST reconcile by read-back under that protocol before
+any retry; do not add one to the contract without it.
+
 ## Invariants
 
 - Tier order is `credential-substrate-precedence`: `SENTRY_AUTH_TOKEN` first, the
   Sentry MCP as a preserved first-class fallback. Identity-match against the
   configured org/project is mandatory on every tier.
+- The token is resolved through `lisa-secrets-access`, with the bare
+  `SENTRY_AUTH_TOKEN` environment variable as the documented fallback. Never read
+  a second credential store (OS keychain, `~/.sentryclirc` token) directly — the
+  one-store rule lives at the chokepoint.
 - 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/lisa-sonarcloud-access/SKILL.md

@@ -34,6 +34,49 @@ SonarQube Cloud org. Do **not** substitute the raw MCP-image names
 running the Docker image directly, and the `sonar` CLI ignores them (auth exits
 non-zero). The CI scan gate's `SONAR_TOKEN` is a third, separate name.
 
+### Where those variables come from
+
+The `sonar` CLI reads them **from the environment only** — it has no provider
+integration of its own — so on a surface that deliberately materializes nothing
+to disk the credential can be provisioned and unreachable at the same time.
+Resolve it through `lisa-secrets-access` and export it into the launching
+process, exactly as the shared `sonar-secrets.sh` hook already does. The bare
+`$SONARQUBE_CLI_TOKEN` in the environment is the documented **fallback** rung,
+not the only one:
+
+```bash
+# Preferred: the one sanctioned reader. Without this rung a project keeping its
+# credentials in Bitwarden, Doppler, or AWS cannot authenticate the MCP at all,
+# and Sonar access degrades to "run `sonar auth login` in a browser" — dead in
+# cron, CI, and cloud sessions. See `credential-substrate-precedence`.
+read_sonar_secret() {
+  local name="$1"
+  [ -n "${!name:-}" ] && { echo "${!name}"; return; }
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get "$name" 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  return 1
+}
+
+# Exported into this process only. Writing it anywhere durable would create a
+# second live copy of a credential whose single store is the provider.
+SONARQUBE_CLI_TOKEN=$(read_sonar_secret SONARQUBE_CLI_TOKEN) && export SONARQUBE_CLI_TOKEN
+SONARQUBE_CLI_ORG=$(read_sonar_secret SONARQUBE_CLI_ORG) && export SONARQUBE_CLI_ORG
+```
+
+`sonar-secrets.sh` runs the same resolution with a longer search path (it also
+probes `.codex/skills/…` and `node_modules/@codyswann/lisa/plugins/lisa/…`,
+because a hook fires in checkouts that never installed an agent plugin) and with
+a timeout, because it sits in front of every prompt. Use its search order
+verbatim when this skill runs inside a hook.
+
 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
@@ -79,9 +122,22 @@ 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.
 
+## Mutation boundary
+
+Every operation in the map above is **read-only** — quality, coverage, and
+security data. So the `credential-substrate-precedence` guarded fallback for
+mutating operations (write, read back, assert the tenant from the response, roll
+back on mismatch) is not engaged here; with one substrate there is nothing to
+fall back to in any case. A future operation that mutates Sonar state — marking
+a hotspot safe, changing an issue's status — is a write and MUST reconcile by
+read-back before any retry.
+
 ## Invariants
 
 - The official SonarQube MCP is the only substrate; there is no REST fallback.
+- `SONARQUBE_CLI_*` values are resolved through `lisa-secrets-access` and
+  exported in-process, with the bare environment variables as the documented
+  fallback. Never write them to a dotfile or a `.env` on a local surface.
 - Auth is env-var only (`SONARQUBE_CLI_TOKEN` [+ `SONARQUBE_CLI_ORG` | `SONARQUBE_CLI_SERVER`]);
   never the interactive `sonar auth login` keychain flow inside a factory.
 - Sonar host access requires the host (`sonarcloud.io`, `sonarqube.us`, or the

package/scripts/install-claude-plugins.sh

@@ -177,7 +177,11 @@ if [ "$IS_LISA_SELF" != "true" ] && [ -z "${CI:-}" ]; then
   if [ "$HOST_HAS_LISA_POSTINSTALL" = "true" ]; then
     echo "Lisa apply deferred to the host project's own postinstall script."
   elif ! LISA_BOOTSTRAP=1 node "$LISA_DIR/dist/index.js" --yes --skip-git-check "$PROJECT_ROOT"; then
-    echo "⚠️  Warning: Lisa template application failed. Migration may be incomplete." >&2
+    # Loud but non-fatal, for the same reason as the host-side bootstrap: a
+    # postinstall that exits non-zero aborts the whole install. The durable
+    # signal is the apply receipt this failed run did NOT write, which
+    # `lisa doctor` reports (CodySwannGT/lisa#2467).
+    echo "⚠️  lisa: TEMPLATE APPLY FAILED (error above) - this project is NOT receiving Lisa template or guardrail updates. Diagnose with: node $LISA_DIR/dist/index.js doctor" >&2
   fi
 fi