@codyswann/lisa 3.0.0 → 3.2.0

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

@@ -1,6 +1,6 @@
 ---
 name: lisa-atlassian-access
-description: "Vendor-neutral access layer for Atlassian (JIRA + Confluence). Every jira-* and confluence-* skill MUST delegate through this skill rather than calling Atlassian directly. Resolves a substrate per operation, binding JIRA writes to the configured cloudId via Atlassian REST whenever token auth is available and using acli only for reads or as a guarded fallback. For non-write acli operations, acli is used when installed and switchable to a profile matching the configured site; mismatched active profiles are skipped only after switch plus re-verification fails."
+description: "Vendor-neutral access layer for Atlassian (JIRA + Confluence). Every jira-* and confluence-* skill MUST delegate through this skill rather than calling Atlassian directly. Per the credential-substrate-precedence contract, resolves a substrate per operation with the ATLASSIAN_API_TOKEN curl path first for reads and writes alike whenever the token is present and identity-matched — binding JIRA writes to the configured cloudId — then acli, then the Atlassian MCP as fallbacks. acli is used when installed and switchable to a profile matching the configured site; mismatched active profiles are skipped only after switch plus re-verification fails, and acli writes are a guarded fallback with post-write tenant assertions."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -35,46 +35,17 @@ EMAIL=$(jq -r '.atlassian.email // empty' .lisa.config.local.json 2>/dev/null)
 [ -z "$CLOUDID" ] && { echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian." >&2; exit 1; }
 ```
 
-Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. Identity-match is verified before any operation; substrates authenticated as a different Atlassian account are switched to the configured profile when one exists, then skipped only if the switch fails or re-verification still mismatches.
+Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. The ordering is the shared `credential-substrate-precedence` contract — the configured-provider token substrate leads for **reads and writes alike**, with acli and the MCP as identity-matched fallbacks — not an Atlassian-local choice. Identity-match is verified before any operation; substrates authenticated as a different Atlassian account are switched to the configured profile when one exists, then skipped only if the switch fails or re-verification still mismatches.
 
 ```bash
 substrate=""
 
-# Tier 1: acli for reads and non-write operations only.
-#
-# Do not choose acli for JIRA writes when curl/token auth is available. acli stores
-# one machine-global active account and workitem writes cannot pin a cloudId per
-# invocation, so switch-then-write is a TOCTOU risk in multi-account or concurrent
-# sessions. Write operations prefer the cloudId-scoped REST URL below.
-if [ "$OP_KIND" != "jira-write" ] && command -v acli >/dev/null 2>&1 && acli auth status >/dev/null 2>&1; then
-  current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
-  if [ "$current_site" != "$SITE" ]; then
-    # acli installed but pointing at a different site. Try switching profiles.
-    acli auth switch --site "$SITE" ${EMAIL:+--email "$EMAIL"} >/dev/null 2>&1 || true
-    current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
-  fi
-  if [ "$current_site" = "$SITE" ]; then
-    substrate="acli"
-  fi
-fi
-
-# Tier 2: Atlassian MCP (if acli not ready OR the operation isn't acli-covered)
-# $OP_REQUIRES is a conceptual variable set by the dispatch table to "non-acli" for
-# operations that have no acli adapter (e.g. read-page-descendants). It is not a real
-# shell variable initialized here — the condition is illustrative pseudo-code.
-if [ -z "$substrate" ] || [ "$OP_REQUIRES" = "non-acli" ]; then
-  # Probe via mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources.
-  # (Pseudo-code; actual call is the MCP tool invocation, not a bash command.)
-  # If the MCP returns a list and $CLOUDID is in it, MCP is identity-matched.
-  # If the MCP is unauthenticated or $CLOUDID is NOT in the list, MCP is skipped.
-  if mcp_atlassian_authenticated_and_matches_cloudid "$CLOUDID"; then
-    : ${substrate:=mcp}
-    # Mark MCP as available even if acli already won tier 1 — used for ops acli can't do.
-    mcp_available=true
-  fi
-fi
-
-# Tier 3: curl + API token (headless / multi-account / scoped-token path)
+# Tier 1: curl + API token — the configured-provider substrate, resolved through
+# lisa-secrets-access. Leads for every operation because it is per-invocation-bound:
+# the cloudId-scoped gateway URL and the token's own account carry the tenant inside
+# the request, so no ambient machine-global state can redirect it. acli (one global
+# active account) and the MCP (browser OAuth session) are ambient-bound and therefore
+# TOCTOU-exposed — see credential-substrate-precedence, "tenant safety".
 read_atlassian_token() {
   local email="$1"
   [ -n "$ATLASSIAN_API_TOKEN" ] && { echo "$ATLASSIAN_API_TOKEN"; return; }
@@ -136,13 +107,50 @@ public static class LisaCred {
   esac
 }
 TOKEN=$(read_atlassian_token "$EMAIL")
-[ -n "$TOKEN" ] && curl_available=true && {
-  if [ "$OP_KIND" = "jira-write" ]; then
+if [ -n "$TOKEN" ]; then
+  # Identity-match before use: /rest/api/3/myself must report the configured account
+  # (Step 2). A present-but-wrong token fails the gate loudly instead of quietly
+  # deferring to an acli profile or MCP session authenticated somewhere else — that
+  # silent success is the bug class the precedence contract exists to surface.
+  if atlassian_token_matches_config "$TOKEN" "$EMAIL" "$CLOUDID"; then
+    curl_available=true
     substrate="curl"
   else
-    : ${substrate:=curl}
+    echo "Warning: ATLASSIAN_API_TOKEN does not match the configured account/site. Skipping curl tier." >&2
   fi
-}
+fi
+
+# Tier 2: acli — identity-matched fallback. Used when no token is available, or for
+# operations with no curl adapter. Never the primary path for JIRA writes when token
+# auth is available: acli stores one machine-global active account and workitem writes
+# cannot pin a cloudId per invocation, so switch-then-write is a TOCTOU risk in
+# multi-account or concurrent sessions. When a write does land here it is the *guarded*
+# fallback documented in the dispatch table (assert, write, re-read, assert, roll back).
+if command -v acli >/dev/null 2>&1 && acli auth status >/dev/null 2>&1; then
+  current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
+  if [ "$current_site" != "$SITE" ]; then
+    # acli installed but pointing at a different site. Try switching profiles.
+    acli auth switch --site "$SITE" ${EMAIL:+--email "$EMAIL"} >/dev/null 2>&1 || true
+    current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
+  fi
+  if [ "$current_site" = "$SITE" ]; then
+    acli_available=true
+    # Mark acli available even if curl already won tier 1 — used for ops curl can't do.
+    : ${substrate:=acli}
+  fi
+fi
+
+# Tier 3: Atlassian MCP — first-class interactive fallback, for when neither tier above
+# is available or covers the operation (e.g. an op with no curl and no acli adapter).
+# Probe via mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources.
+# (Pseudo-code; actual call is the MCP tool invocation, not a bash command.)
+# If the MCP returns a list and $CLOUDID is in it, MCP is identity-matched.
+# If the MCP is unauthenticated or $CLOUDID is NOT in the list, MCP is skipped.
+if mcp_atlassian_authenticated_and_matches_cloudid "$CLOUDID"; then
+  : ${substrate:=mcp}
+  # Mark MCP as available even if an earlier tier won — used for ops they can't do.
+  mcp_available=true
+fi
 
 # Fail loudly with actionable remediation if nothing works.
 if [ -z "$substrate" ]; then
@@ -154,15 +162,25 @@ if [ -z "$substrate" ]; then
   cat >&2 <<EOF
 Error: no Atlassian access substrate available for site $SITE.
 
-Attempted:
+Attempted (in credential-substrate-precedence order):
+  curl   — no ATLASSIAN_API_TOKEN found for $EMAIL (env, slug-suffixed env, or keychain) OR the token does not match the configured account/site
   acli   — $(command -v acli >/dev/null && echo "installed but identity mismatch or unauthenticated" || echo "not installed")
   MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cloudId $CLOUDID not in accessible resources" || echo "plugin not enabled in any settings.json scope")
-  curl   — no ATLASSIAN_API_TOKEN found for $EMAIL (env, slug-suffixed env, or keychain)
 
-Remediation paths (pick one):
+Remediation paths (the first is the contract's primary path):
+
+1. Provision an API token — works headless, in CI, in subagents, and in
+   multi-account setups, and is the substrate this project resolves first.
+
+     Run /lisa:setup:atlassian — guided flow with clipboard-piped keychain store.
+
+2. Install acli and authenticate (identity-matched fallback for multi-account developers).
 
-1. Install the Atlassian MCP plugin (local scope — per-developer, gitignored).
-   This is the simplest path for single-account developers.
+     brew tap atlassian/homebrew-acli && brew install acli
+     acli auth login   # OAuth as the account matching $EMAIL
+
+3. Install the Atlassian MCP plugin (local scope — per-developer, gitignored).
+   The supported fallback when no credentials provider is configured.
 
    Run in your terminal:
 
@@ -174,25 +192,16 @@ Remediation paths (pick one):
    Then restart Claude Code (or run /restart-mcp) to load the plugin, and
    invoke 'mcp__plugin_atlassian_atlassian__authenticate' to complete OAuth.
 
-2. Install acli and authenticate (best for multi-account developers).
-
-     brew tap atlassian/homebrew-acli && brew install acli
-     acli auth login   # OAuth as the account matching $EMAIL
-
-3. Provision an API token (headless / CI / scoped-token environments).
-
-     Run /lisa:setup:atlassian — guided flow with clipboard-piped keychain store.
-
 EOF
   exit 1
 fi
 ```
 
-Operation dispatch then uses `$substrate` for the primary route. If the operation has no `acli` adapter and `$substrate=acli`, fall through to `$mcp_available` then `$curl_available` for the actual call. The fall-through stops at the first available tier that can perform the operation.
+Operation dispatch then uses `$substrate` for the primary route. If the operation has no adapter for the selected substrate, fall through in contract order — `$curl_available`, then `$acli_available`, then `$mcp_available` — skipping the tier already tried. The fall-through stops at the first available tier that can perform the operation. A tier that failed identity-match is never in the fall-through set.
 
 ### Step 2 — Connection-match check
 
-The active connection MUST point at the cloudId/site declared in `.lisa.config.json`. Step 1's substrate selection already tries to switch mismatched acli profiles and verifies the result before selection. This step repeats the assertion before any operation runs — defensive in case the substrate state changed since selection.
+The active connection MUST point at the cloudId/site declared in `.lisa.config.json`. Identity-match is mandatory on **every** substrate, tier 1 included (`credential-substrate-precedence`); the "curl mode check" below *is* the tier-1 gate referenced as `atlassian_token_matches_config` in Step 1. Step 1's substrate selection already validates the token account and tries to switch mismatched acli profiles before selection. This step repeats the assertion before any operation runs — defensive in case the substrate state changed since selection.
 
 Read configured site:
 
@@ -291,12 +300,12 @@ Rules:
 
 ### Step 3 — Operation dispatch
 
-Substrate column meanings:
+Substrate column meanings (ordering per `credential-substrate-precedence`):
 
-- **`acli`**: routes through `acli`. Preferred when available and identity-matched.
-- **`MCP`**: routes through the Atlassian MCP. Preferred when acli can't do the op and the MCP is identity-matched (cloudId in `getAccessibleAtlassianResources`).
-- **`curl`**: routes through curl + Basic auth + `ATLASSIAN_API_TOKEN`. Used when neither acli nor MCP is available.
-- Multiple cells filled means tier ordering applies — try acli, then MCP, then curl, taking the first that has an adapter for the op AND is identity-matched.
+- **`curl`**: routes through curl + Basic auth + `ATLASSIAN_API_TOKEN` — the configured-provider substrate. Preferred for every operation, read or write, whenever the token is present and identity-matched.
+- **`acli`**: routes through `acli`. Identity-matched fallback — used when no token is available or the op has no curl adapter. For JIRA writes it is the *guarded* fallback (see the tenant-safety rule below).
+- **`MCP`**: routes through the Atlassian MCP. First-class fallback for ops neither tier above covers, when identity-matched (cloudId in `getAccessibleAtlassianResources`).
+- Multiple cells filled means tier ordering applies — try curl, then acli, then MCP, taking the first that has an adapter for the op AND is identity-matched.
 - One cell means only that substrate can perform the op.
 
 `<SITE>` = `.atlassian.site` (e.g. `acme.atlassian.net`). `<CLOUDID>` = `.atlassian.cloudId`. `<AUTH>` = `Basic $(printf '%s:%s' "$email" "$ATLASSIAN_API_TOKEN" | base64)`. JIRA curl writes use the cloudId-bound Atlassian gateway `https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/...`; JIRA curl reads may use either that gateway or `https://<SITE>/rest/api/3/...` after the token account check. Confluence uses `/wiki/rest/api/...` (v1) or `/api/v2/...` (v2).
@@ -334,7 +343,7 @@ Substrate column meanings:
 
 **acli flag note:** acli's `--output` flag does not exist; the correct flag is `--json`. List commands require `--paginate` or `--limit` (no implicit fetch-all). `acli jira workitem view` defaults to a restricted field set (`key,issuetype,summary,status,assignee,description`), so `read-ticket` MUST pass `--fields '*all'` or an explicit equivalent that includes every downstream dependency: parent, subtasks, issue links, components, labels, priority, status, issue type, summary, description, fix versions, affected versions, attachments, comments, estimates, sprint/story-point fields, and project-required custom fields. Never rely on the default view fields; they hide parent/components/labels and corrupt leaf-only, relationship-search, build-ready, and required-custom-field gates. Several documented adapters are nominal — verify against `acli <subcmd> --help` before relying on them. When acli's adapter is broken or missing for a specific op, fall through to MCP (if identity-matched) then curl per the tier ordering.
 
-**JIRA write tenant-safety rule:** create, edit, transition, comment, and link are write operations. They MUST prefer the curl adapter whenever token auth is available because the URL includes `<CLOUDID>` and cannot be redirected by the user-global acli active account. If the flow must fall back to acli for a write, it is a guarded fallback, not the normal path:
+**JIRA write tenant-safety rule** — the Atlassian instance of the shared guarded-fallback protocol in `credential-substrate-precedence` (which states the general rule: prefer the per-invocation-bound substrate over the ambient-bound one, for reads and writes alike; the rationale is not restated here). Create, edit, transition, comment, and link are write operations. They MUST use the curl adapter whenever token auth is available because the URL includes `<CLOUDID>` and cannot be redirected by the user-global acli active account. If the flow must fall back to acli for a write, it is a guarded fallback, not the normal path:
 
 1. Switch and assert the active `acli auth status` site/email matches config immediately before the write.
 2. Execute the write.
@@ -378,15 +387,17 @@ Do not paraphrase substrate output beyond JSON normalization.
 ## Invariants
 
 - Caller skills never invoke `acli` or `curl` against Atlassian directly. They only invoke this skill.
+- Tier order is the shared `credential-substrate-precedence` contract — token curl first (reads **and** writes), then acli, then the Atlassian MCP. Do not restate or locally override the ordering here.
+- acli and the Atlassian MCP remain first-class **fallbacks**, not removed tiers: every adapter stays in the dispatch table, and a project with no credentials provider is fully functional on them.
 - Substrate is decided once per skill invocation and never switches mid-operation.
-- Connection match is mandatory. Operations that bypass it (because "the user obviously meant the configured site") are forbidden.
+- Connection match is mandatory on every tier, including the token tier. Operations that bypass it (because "the user obviously meant the configured site") are forbidden. A present-but-wrong token fails the gate rather than deferring to another substrate.
 - Profile mutations (`acli auth switch`) are allowed when acli is the active substrate. The curl substrate never mutates the token — if `ATLASSIAN_API_TOKEN` doesn't match the configured account, fail loud rather than silently substituting.
 - JIRA writes are cloudId-bound by default. `acli` write adapters are fallback-only and must perform post-write tenant assertions plus safe rollback on mismatch.
 - `.lisa.config.local.json` overrides `.lisa.config.json` per-key — the same precedence rule as every other consumer of project config.
 
 ## Headless behavior
 
-In a headless / non-interactive context, the MCP tier is unavailable (its OAuth flow needs a browser). The substrate ladder collapses to: acli (if pre-authenticated, e.g., a CI image baked with a service-account token) → curl + `ATLASSIAN_API_TOKEN`. Never block on interactive prompts. If both fail readiness checks, exit non-zero with a deterministic error.
+In a headless / non-interactive context, the MCP tier is unavailable (its OAuth flow needs a browser). The ladder collapses to: curl + `ATLASSIAN_API_TOKEN` → acli (if pre-authenticated, e.g., a CI image baked with a service-account token). Because curl is already tier 1 interactively, headless and interactive sessions take the **same primary path** — that is the "headless parity" arm of `credential-substrate-precedence`, and it is why a credential problem reproduces on a laptop instead of only in cron. Never block on interactive prompts. If both fail readiness checks, exit non-zero with a deterministic error.
 
 Treat all four of these as headless:
 

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

@@ -1,6 +1,6 @@
 ---
 name: lisa-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 the JAM_PAT-authenticated Jam CLI for headless routines."
+description: "Vendor-neutral access layer for Jam. Jam triage rules and skills MUST delegate through this skill rather than calling Jam MCP tools directly. Per the credential-substrate-precedence contract, resolves the JAM_PAT-authenticated Jam CLI first when the PAT is present and identity-matched, then falls back to the Jam MCP."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -21,13 +21,20 @@ Return parsed JSON or a concise structured summary in a `<result>` block.
 
 ## Substrate Selection
 
-Probe in order:
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a Jam-local choice. The first tier that is ready **and**
+identity-matches the configured Jam account is used; one authenticated elsewhere
+is skipped, never used.
 
-1. Jam MCP, if the tool is available and authenticated.
-2. Jam CLI authenticated with `JAM_PAT`.
+1. **Tier 1 — configured-provider substrate: Jam CLI authenticated with `JAM_PAT`**,
+   resolved through `lisa-secrets-access`.
+2. **Tier 2 — interactive MCP fallback: Jam MCP**, if the tool is available and
+   authenticated. Used when tier 1 is genuinely unavailable: no `JAM_PAT`, no CLI
+   adapter for the operation, or a Jam outage.
 
 Jam documents a PAT-authenticated CLI that is cleaner for remote routines than
-editing `.mcp.json` headers. The headless tier uses:
+editing `.mcp.json` headers, and it is the same substrate interactively and
+headlessly — which is why it leads. The CLI tier uses:
 
 ```bash
 curl -fsSL https://native.jam.dev/install | bash
@@ -44,7 +51,8 @@ Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PA
 
 ## Invariants
 
-- Fallback is gated on `JAM_PAT`; do not retry Jam MCP failures blindly.
+- 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.
 - 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/lisa/skills/lisa-linear-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-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."
+description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Per the credential-substrate-precedence contract, resolves LINEAR_API_KEY + Linear GraphQL first — ahead of the Linear MCP — whenever the key is present and identity-matches the configured workspace/team, and falls back to the Linear MCP when the token path is unavailable. Identity-match is mandatory on both substrates."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -46,15 +46,27 @@ 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`).
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a Linear-local choice. The first tier that is ready **and**
+identity-matches wins; a substrate authenticated against a different
+workspace/team is **skipped, never used**, at either tier.
+
+1. **Tier 1 — configured-provider substrate: `LINEAR_API_KEY` with Linear GraphQL**
+   (`https://api.linear.app/graphql`), resolved through `lisa-secrets-access`.
+   Identity-match by querying `viewer { organization { urlKey } }` (plus
+   `teams` when `linear.teamKey` is configured) and comparing to
+   `.lisa.config.json`. A key that resolves to a different organization fails the
+   gate — warn, skip the tier, and continue down the ladder.
+2. **Tier 2 — interactive MCP fallback: Linear MCP**, if
+   `mcp__linear-server__list_teams` is available and can list the configured
+   workspace/team (that listing *is* the identity match). Used when tier 1 is
+   genuinely unavailable: no `LINEAR_API_KEY`, no GraphQL adapter for the
+   operation, or a Linear API outage.
 
 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:
+with an `Authorization: <API_KEY>` header, so the token tier works identically on
+a developer laptop, in CI, in a cloud routine, and in a subagent — which is why it
+leads. If neither tier works, fail with:
 
 ```text
 Error: no Linear access substrate available. Authenticate the Linear MCP or set LINEAR_API_KEY.
@@ -204,8 +216,16 @@ query($id:String!){
 
 ## 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`.
+- Tier order is the shared `credential-substrate-precedence` contract:
+  `LINEAR_API_KEY` + GraphQL first when present and identity-matched, then the
+  Linear MCP. Do not restate or locally override the ordering here.
+- The Linear MCP remains a first-class **fallback**, not a removed tier: it stays
+  the substrate whenever `LINEAR_API_KEY` is absent, the operation has no GraphQL
+  adapter, or the token path is failing.
+- Identity-match is mandatory on **both** substrates. A substrate authenticated
+  against a different Linear organization or team is skipped, never used — that
+  includes a present-but-wrong `LINEAR_API_KEY`, which fails the gate loudly
+  instead of silently deferring to an authenticated MCP.
+- Missing token plus missing MCP 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/lisa/skills/lisa-notion-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-notion-access
-description: "Vendor-neutral access layer for Notion. Every notion-* skill MUST delegate through this skill rather than invoking the Notion REST API or any Notion MCP directly. Resolves a substrate per operation in this order: (1) Notion MCP if authenticated and the configured prdDatabaseId is fetchable through it (identity-match), (2) curl + Bearer auth + internal-integration token. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Notion workspace are skipped, not used."
+description: "Vendor-neutral access layer for Notion. Every notion-* skill MUST delegate through this skill rather than invoking the Notion REST API or any Notion MCP directly. Per the credential-substrate-precedence contract, resolves a substrate per operation in this order: (1) curl + Bearer auth + internal-integration token when the token is present and identity-matches the configured workspace, (2) Notion MCP as fallback if authenticated and the configured prdDatabaseId is fetchable through it. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Notion workspace are skipped, not used."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -38,20 +38,15 @@ DB_ID=$(jq -r '.notion.prdDatabaseId // empty' .lisa.config.json)
 [ -z "$DB_ID" ]     && { echo "Error: notion.prdDatabaseId not set. Run /lisa:setup:notion." >&2; exit 1; }
 ```
 
-Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. Identity-match is verified before any operation; substrates authenticated as a different workspace are skipped, not used.
+Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. The ordering is the shared `credential-substrate-precedence` contract — the configured-provider token substrate leads, the interactive MCP is the fallback — not a Notion-local choice. Identity-match is verified before any operation; substrates authenticated as a different workspace are skipped, not used, at **every** tier.
 
 ```bash
 substrate=""
 
-# Tier 1: Notion MCP (identity-matched by fetching the configured PRD database)
-# Pseudo-code; actual call is the MCP tool invocation.
-# Try to fetch DB_ID through the MCP. Success → MCP is authed to the right workspace.
-# 404 / object_not_found → MCP is authed elsewhere (or unauthenticated). Skip.
-if mcp_notion_can_fetch_database "$DB_ID"; then
-  substrate="mcp"
-fi
-
-# Tier 2: curl + API token
+# Tier 1: curl + API token — the configured-provider substrate, resolved through
+# lisa-secrets-access. Leads because it is identical on a laptop, in CI, in a cloud
+# routine, and in a subagent, and because its workspace binding travels with the
+# request instead of coming from ambient browser-session state.
 read_notion_token() {
   local workspace="$1"
   [ -n "$NOTION_API_TOKEN" ] && { echo "$NOTION_API_TOKEN"; return; }
@@ -120,12 +115,28 @@ if [ -n "$TOKEN" ]; then
               "https://api.notion.com/v1/users/me")
   me_workspace=$(echo "$me" | jq -r '.bot.workspace_name // .bot.workspace_id // empty')
   if [ -n "$me_workspace" ] && [ "$me_workspace" = "$WORKSPACE" ]; then
-    : ${substrate:=curl}
+    substrate="curl"
   elif [ -n "$me_workspace" ]; then
+    # A present-but-wrong token fails the gate rather than deferring to the MCP.
+    # Silently succeeding through an MCP authenticated elsewhere is the exact bug
+    # the precedence contract exists to surface.
     echo "Warning: Notion token belongs to workspace '$me_workspace' but config declares '$WORKSPACE'. Skipping curl tier." >&2
   fi
 fi
 
+# Tier 2: Notion MCP — first-class fallback, used when tier 1 is genuinely
+# unavailable (no token, no curl adapter for the operation, or Notion API outage).
+# Identity-matched by fetching the configured PRD database.
+# Pseudo-code; actual call is the MCP tool invocation.
+# Try to fetch DB_ID through the MCP. Success → MCP is authed to the right workspace.
+# 404 / object_not_found → MCP is authed elsewhere (or unauthenticated). Skip.
+if mcp_notion_can_fetch_database "$DB_ID"; then
+  : ${substrate:=mcp}
+  # Mark the MCP available even when curl already won tier 1 — the dispatch table
+  # falls through to it for operations curl has no adapter for.
+  mcp_available=true
+fi
+
 # Fail loudly with actionable remediation if nothing works.
 if [ -z "$substrate" ]; then
   # Detect plugin enablement state for the suggestion.
@@ -136,14 +147,19 @@ if [ -z "$substrate" ]; then
   cat >&2 <<EOF
 Error: no Notion access substrate available for workspace '$WORKSPACE'.
 
-Attempted:
-  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cannot fetch configured prdDatabaseId" || echo "plugin not enabled in any settings.json scope")
+Attempted (in credential-substrate-precedence order):
   curl   — no NOTION_API_TOKEN found for $WORKSPACE (env, slug-suffixed env, or keychain) OR token belongs to a different workspace
+  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cannot fetch configured prdDatabaseId" || echo "plugin not enabled in any settings.json scope")
+
+Remediation paths (the first is the contract's primary path):
 
-Remediation paths (pick one):
+1. Provision an internal-integration API token — works headless, in CI, and in
+   multi-workspace setups, and is the substrate this project resolves first.
 
-1. Install the Notion MCP plugin (local scope — per-developer, gitignored).
-   This is the simplest path for single-workspace developers.
+     Run /lisa:setup:notion — guided flow with clipboard-piped keychain store.
+
+2. Install the Notion MCP plugin (local scope — per-developer, gitignored).
+   The supported fallback when no credentials provider is configured.
 
    Run in your terminal:
 
@@ -157,10 +173,6 @@ Remediation paths (pick one):
    Also share the configured prdDatabaseId with the integration via
    the page's '•••' menu → Connections.
 
-2. Provision an internal-integration API token (headless / CI / multi-workspace).
-
-     Run /lisa:setup:notion — guided flow with clipboard-piped keychain store.
-
 EOF
   exit 1
 fi
@@ -225,14 +237,15 @@ exec_op() {
 ## Invariants
 
 - Caller skills never call `curl https://api.notion.com/...` or any `mcp__*notion*` tool directly. They invoke this skill via the Skill tool with an operation name and arguments.
-- Substrate is selected per skill invocation following the tier ladder. The first tier that's available AND identity-matches `notion.workspaceId` wins.
-- The connection-match check is mandatory at every tier. Skipping it (because "the user obviously meant this workspace") is forbidden — silent cross-workspace operations are exactly the multi-account hazard this design exists to prevent.
+- Substrate is selected per skill invocation following the tier ladder defined by the shared `credential-substrate-precedence` contract — internal-integration token first, Notion MCP as fallback. The first tier that's available AND identity-matches `notion.workspaceId` wins. Do not restate or locally override the ordering here.
+- The Notion MCP stays a first-class fallback, not a removed tier: it is the substrate whenever no token is configured, the operation has no curl adapter, or the Notion API is failing.
+- The connection-match check is mandatory at every tier. Skipping it (because "the user obviously meant this workspace") is forbidden — silent cross-workspace operations are exactly the multi-account hazard this design exists to prevent. A present-but-wrong token fails the gate rather than deferring to an MCP authenticated somewhere else.
 - API tokens never mutate. If the configured workspace's token is wrong or missing, fail loudly and tell the user to run `/lisa:setup:notion`.
 - `Notion-Version` is pinned to `2022-06-28` — the version every existing notion-* skill targets. Bumping it is a coordinated change across the access skill and all callers.
 
 ## Headless behavior
 
-In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser). The ladder collapses to curl + `NOTION_API_TOKEN`. Same skill code runs identically; only the substrate changes.
+In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser) and the ladder collapses to curl + `NOTION_API_TOKEN` — which is already tier 1 interactively. That is the point of the ordering: headless and interactive sessions take the **same primary path**, so a credential problem reproduces on a laptop instead of only in cron (`credential-substrate-precedence`, "headless parity"). Same skill code runs identically; only the availability of the fallback changes.
 
 ## Per-page sharing prerequisite
 

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

@@ -1,6 +1,6 @@
 ---
 name: lisa-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."
+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. Per the credential-substrate-precedence contract, resolves POSTHOG_PERSONAL_API_KEY bearer auth first when present and identity-matched to the configured project, then falls back to the PostHog MCP."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -22,13 +22,21 @@ Return parsed JSON in a `<result>` block.
 
 ## Substrate Selection
 
-Probe in order:
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a PostHog-local choice. The first tier that is ready **and**
+identity-matches the configured project is used; a substrate authenticated against
+a different project is skipped, never used.
 
-1. PostHog MCP, if available and authenticated.
-2. `POSTHOG_PERSONAL_API_KEY` bearer token against the configured PostHog host.
+1. **Tier 1 — configured-provider substrate: `POSTHOG_PERSONAL_API_KEY`** bearer
+   token against the configured PostHog host, resolved through
+   `lisa-secrets-access`.
+2. **Tier 2 — interactive MCP fallback: PostHog MCP**, if available and
+   authenticated. Used when tier 1 is genuinely unavailable: no
+   `POSTHOG_PERSONAL_API_KEY`, no REST adapter for the operation, or a PostHog
+   outage.
 
-PostHog documents personal API keys and bearer authentication. The headless REST
-tier uses:
+PostHog documents personal API keys and bearer authentication, and the same key
+works interactively and headlessly — which is why it leads. The REST tier uses:
 
 ```bash
 POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
@@ -54,7 +62,9 @@ Error: no PostHog access substrate available. Authenticate the PostHog MCP or se
 
 ## Invariants
 
-- Fallback is gated on `POSTHOG_PERSONAL_API_KEY`.
+- 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.
 - `POSTHOG_HOST` defaults to PostHog Cloud but can point at a self-hosted
   deployment.
 - Consumer skills do not embed PostHog REST paths.

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

@@ -10,6 +10,14 @@ Single chokepoint for reading credentials. Caller skills MUST go through this
 
 The rule this exists to enforce: **a secret lives in exactly one store.** Every local cache is a copy that will eventually drift from its source, and a drifted copy is indistinguishable from a valid one until something fails in production.
 
+This skill is also the chokepoint that feeds **tier 1** of the shared
+`credential-substrate-precedence` contract: every `*-access` skill resolves its
+configured-provider token or CLI credential here, ahead of any interactive MCP. That
+is what makes "provider-first" actionable rather than aspirational — including the
+`tool:` note line below, which declares which CLI a given credential is expected to
+drive. This skill decides *where a credential comes from*; it never decides substrate
+ordering, which is settled once in that contract.
+
 ## Two axes, not one
 
 A **provider** is where secrets live. A **surface** is where the running code lives, and it determines how secrets reach that code. These are independent: the same Bitwarden project serves a laptop, a CI runner, and a remote agent container, but each obtains its values differently.

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

@@ -1,6 +1,6 @@
 ---
 name: lisa-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."
+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. Per the credential-substrate-precedence contract, resolves SENTRY_AUTH_TOKEN (REST, or sentry-cli authenticated from the same token) first when present and identity-matched to the configured org/project, then falls back to the Sentry MCP."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -22,13 +22,21 @@ Return parsed JSON in a `<result>` block.
 
 ## Substrate Selection
 
-Probe in order:
+Probe in order — the ordering is the shared `credential-substrate-precedence`
+contract, not a Sentry-local choice. The first tier that is ready **and**
+identity-matches the configured org/project is used; a substrate authenticated
+against a different org is skipped, never used.
 
-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.
+1. **Tier 1 — configured-provider substrate: `SENTRY_AUTH_TOKEN`** bearer token
+   against Sentry REST, resolved through `lisa-secrets-access`.
+2. **Tier 1a — `sentry-cli`**, if installed and authenticated to the requested
+   org/project from that same token (the CLI arm of the provider substrate).
+3. **Tier 2 — interactive MCP fallback: Sentry MCP**, if available and
+   authenticated. Used when tier 1 is genuinely unavailable: no
+   `SENTRY_AUTH_TOKEN`, no REST/CLI adapter for the operation, or a Sentry outage.
 
-Sentry documents API auth tokens for REST API calls. The headless REST tier uses:
+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
 sentry_api() {
@@ -50,7 +58,9 @@ Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set
 
 ## Invariants
 
-- Fallback is gated on `SENTRY_AUTH_TOKEN`.
+- 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.
 - 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/lisa/skills/lisa-sonarcloud-access/SKILL.md

@@ -15,7 +15,13 @@ this skill owns the tool selection.
 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:
+so it is the same substrate on a developer machine and in a headless cloud routine.
+
+That makes this skill conformant with `credential-substrate-precedence` as a
+single-substrate access layer: this MCP **is** the configured-provider substrate
+(it is token-authenticated, not browser-OAuth), so there is no interactive tier to
+demote and no second REST tier to add. Identity-match against the configured org
+remains mandatory, as on every substrate.
 
 - `SONARQUBE_CLI_TOKEN` — required (Sonar user/analysis token).
 - `SONARQUBE_CLI_ORG` — required for SonarQube Cloud.

package/plugins/lisa-agy/plugin.json

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