@codyswann/lisa 3.0.0 → 3.1.0

package/plugins/lisa/.codex-plugin/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/rules/eager/integration-access-layer.md

@@ -4,7 +4,11 @@ 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:
+Resolution order is the configured-provider token/CLI substrate first when its
+bootstrap credential is present and identity-matched, then the interactive MCP as
+fallback, then a loud error naming the exact credential to set. Identity-match is
+mandatory on every substrate — one authenticated as a different tenant is skipped,
+never used. The ordering itself is settled in
+[reference/credential-substrate-precedence.md](../reference/credential-substrate-precedence.md);
+full matrix and migration rules:
 [reference/integration-access-layer.md](../reference/integration-access-layer.md).

package/plugins/lisa/rules/reference/credential-substrate-precedence.md

@@ -0,0 +1,166 @@
+# Credential-Substrate Precedence
+
+**When more than one substrate can reach an external system, the configured credentials
+provider's token/CLI path goes first and the interactive MCP is the fallback — and
+identity-match verification is mandatory on every substrate, at every tier.**
+
+This is **one shared, vendor-neutral contract cited by every `*-access` skill** (the
+`leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent
+per-skill prose). An access skill states its per-vendor mechanics — which token, which
+CLI, which identity anchor — and cites this rule for the ordering. It never restates,
+narrows, or locally overrides the ordering.
+
+Settled by the decision record `2026-08-12-credential-substrate-precedence` (D6). It is
+a **settled decision** in the `settled-decisions` sense: re-arguing MCP-first inside a
+skill is out of scope for that skill's work.
+
+## The ladder
+
+### Tier 1 — configured-provider substrate
+
+The token or CLI path fed by `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 that makes this tier actionable rather
+than aspirational: it owns the one-store rule and the surface ladder, and its `tool:`
+note line already declares which CLI a given credential is expected to drive. An access
+skill resolves its credential through that chokepoint — never by reading an OS keychain
+a second time.
+
+Both halves of the gate are load-bearing. A present credential that identity-matches
+nothing is **not** tier 1; it is a failed tier, and the ladder moves on.
+
+### Tier 2 — interactive MCP
+
+Used when the tier 1 path is **genuinely unavailable**. The three genuine cases:
+
+- **No bootstrap** — the provider credential is absent or the project has not adopted a
+  credentials provider at all.
+- **No adapter for the operation** — the token/CLI substrate has no documented adapter
+  for the requested operation, and the MCP does (per-operation, not per-session: a skill
+  may resolve tier 1 for one operation and tier 2 for the next).
+- **Provider outage** — the provider path is present but failing for reasons the caller
+  cannot fix in-session.
+
+"The MCP happens to be authenticated" is not one of them. Neither is "tier 1 is slower."
+
+### Tier 3 — loud, actionable failure
+
+When no substrate is both available and identity-matched, fail with a message naming the
+exact credential to set and the exact remediation path. Never silently no-op, never
+blind-retry a failed or absent substrate, and never fall through to a substrate that
+failed identity-match.
+
+## Identity-match is mandatory on every substrate
+
+Verification runs **in both directions** before any operation: the substrate must claim
+the configured tenant, and the configured tenant must be one the substrate can actually
+reach. A substrate authenticated as a **different** account is **skipped, never used**,
+regardless of tier — including tier 1. A credential is not an identity claim; the
+identity claim is what the provider says when asked.
+
+| Vendor | Identity anchor | Probe |
+|---|---|---|
+| Atlassian | `atlassian.cloudId` / `atlassian.site` | `/rest/api/3/myself` email, acli `auth status` site, MCP accessible-resources contains the cloudId |
+| Notion | `notion.workspaceId` (+ `prdDatabaseId` reachability) | `GET /v1/users/me` → `bot.workspace_name`/`workspace_id` |
+| Linear | `linear.workspace` / `linear.teamKey` | `viewer`/`organization` on GraphQL; team list through the MCP |
+| Sentry / PostHog / Jam / Sonar | configured org + project | the substrate's own whoami/org listing |
+
+Skipping the check because "the user obviously meant this workspace" is forbidden. Silent
+cross-tenant operations are precisely the hazard this contract exists to prevent.
+
+## Why provider-first (and why it overturns a working default)
+
+MCP-first was defensible and is being overturned deliberately, not corrected as an
+oversight. Three reasons outweigh it.
+
+**Headless parity.** Cron runs, cloud sessions, CI, and subagent sessions have no
+browser. Under MCP-first an interactive session and a headless session resolve through
+*different* substrates and can therefore fail differently — and the failure surfaces only
+in the environment nobody is watching. Provider-first makes the primary path the same one
+everywhere, with MCP as the enhancement rather than the default.
+
+**Tenant safety — the generalized Atlassian write rule.** Substrates differ in *where
+their target comes from*:
+
+- **Per-invocation-bound.** The target is part of the call. A cloudId-scoped REST URL
+  (`https://api.atlassian.com/ex/jira/<CLOUDID>/…`) or a workspace-scoped API token
+  carries its tenant in the request itself, so nothing outside the call can redirect it.
+- **Ambient-bound.** The target comes from machine-global or session-global state a skill
+  does not own: acli's single active account, an MCP's browser OAuth session bound to
+  whatever account the human last used. Any other process — or the human — can change it
+  between the check and the call. That is a **TOCTOU** window, and a successful
+  pre-flight `auth status` does not close it.
+
+Prefer the per-invocation-bound substrate. This is exactly why Atlassian JIRA *writes*
+were already forced onto the cloudId-scoped curl adapter; the hazard is not specific to
+Atlassian and not specific to writes. A misrouted write is loud and often reversible; a
+**read through the wrong tenant silently returns wrong data**, which then propagates into
+tickets, PRDs, and verification claims — harder to detect and harder to unwind. Reads get
+the same ordering as writes.
+
+**Determinism.** A token path either has its bootstrap or does not, and says so. An MCP's
+readiness depends on session state a skill cannot inspect reliably — the same server
+registers under different prefixes depending on install path, and its data tools register
+only after OAuth completes.
+
+## MCP stays a first-class fallback
+
+This is a **re-ordering, not a removal.** The strongest argument for MCP-first — that an
+already-authenticated MCP is zero-setup and identity-verified — is preserved by keeping
+MCP as a genuine, fully supported tier rather than deleting it:
+
+- Every access skill keeps its MCP adapters in the dispatch table.
+- An operation with no tier 1 adapter routes to MCP **as the normal path**, not as an
+  error.
+- A project with no credentials provider is fully functional on MCP alone.
+- MCP failure messages stay actionable (how to enable and authenticate the plugin).
+
+Removing an MCP adapter is a separate decision requiring its own justification. Do not
+treat this contract as license to delete one.
+
+## Guarded fallback for ambient-bound substrates
+
+When the ladder does fall back to an ambient-bound substrate for a **mutating**
+operation, the fallback is guarded — never the normal path:
+
+1. Switch to the configured profile and assert the active identity matches config
+   immediately before the write.
+2. Execute the write.
+3. Re-read the affected object(s) immediately afterward.
+4. Perform a **post-write tenant assertion** on the response — the tenant is proven from
+   the response (self URL host, cloudId in the path, or response metadata), not assumed
+   from the pre-flight check.
+5. On mismatch: stop, report a cross-tenant hazard, and best-effort **roll back** the
+   write when a safe reversal exists (delete the created object, remove the created
+   comment/link, revert a reversible field edit). Never continue as if it succeeded.
+
+A successful pre-flight switch is not sufficient for tenant safety — another process can
+mutate global state between the check and the write.
+
+## Consequences to expect
+
+- **A stale or wrong token now fails identity-match instead of silently succeeding
+  through an authenticated MCP.** That is intended: it is the exact class of bug this
+  contract exists to surface. Fix the credential (`/lisa:setup:<vendor>`); do not
+  re-order the ladder to route around it.
+- Headless and interactive sessions take the same primary path, so a credential problem
+  reproduces on a laptop instead of only at 3am in cron.
+- The ordering is **not configurable per project**. A knob would let a project
+  reintroduce the headless divergence this contract removes. Revisit only with a concrete
+  need and a new decision record.
+
+## Adding or editing an access skill
+
+1. Cite this rule by name; do not restate the ordering.
+2. Document the tier 1 credential and the `lisa-secrets-access` resolution path.
+3. Document the identity anchor and its probe, and state that mismatch means skip.
+4. Keep MCP adapters and name the operations for which MCP is the only substrate.
+5. Make the terminal failure name the exact credential and remediation command.
+
+Single-substrate access skills are conformant when their one substrate is
+provider-credential-authenticated (`lisa-sonarcloud-access`: the official SonarQube MCP
+authenticates headlessly from `SONARQUBE_CLI_TOKEN`, so it *is* the tier 1 substrate and
+needs no separate REST tier). Reserve a multi-tier ladder for vendors whose MCP is
+browser-OAuth or keychain-bound and therefore dead headless.

package/plugins/lisa/rules/reference/integration-access-layer.md

@@ -4,24 +4,35 @@ Every Lisa skill or rule that consumes an external integration MUST route throug
 the integration's `*-access` skill instead of calling that vendor's MCP tools or
 REST API directly.
 
-The access skill owns substrate resolution:
+The access skill owns substrate resolution. **The ordering is not this rule's to
+define** — it is the single shared contract in `credential-substrate-precedence`,
+cited identically by every `*-access` skill:
 
-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.
+1. **Configured-provider token/CLI substrate** — the path fed by
+   `lisa-secrets-access` — when its bootstrap credential is present AND the
+   resolved substrate identity-matches the configured tenant/workspace/account.
+2. **Interactive MCP**, as a first-class fallback, when the provider path is
+   genuinely unavailable (no bootstrap, no adapter for the operation, provider
+   outage).
+3. Loud failure naming the exact credential 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.
+Identity-match verification is mandatory on **every** substrate, in both
+directions; one authenticated as a different tenant is skipped, never used. See the
+`credential-substrate-precedence` rule for the rationale (headless parity, tenant
+safety, determinism), the guarded-fallback protocol, and what "genuinely
+unavailable" means.
+
+Do not blind-retry a failed or absent substrate, and never silently no-op when no
+tier is available.
 
 Some MCPs authenticate headlessly from an env token and need no separate REST
-tier — the MCP **is** the headless substrate on both developer machines and cloud
-routines. The official SonarQube MCP is one such case (`SONARQUBE_CLI_TOKEN`
+tier — such an MCP **is** the configured-provider substrate on both developer
+machines and cloud routines, so a single-substrate access skill is conformant. The
+official SonarQube MCP is one such case (`SONARQUBE_CLI_TOKEN`
 [+ `SONARQUBE_CLI_ORG`/`SONARQUBE_CLI_SERVER`]): `lisa-sonarcloud-access` resolves it as a
-single substrate with no hand-rolled REST fallback. Reserve the two-tier
-MCP-then-REST shape for vendors whose MCP is browser-OAuth or keychain-bound and
-therefore dead headless.
+single substrate with no hand-rolled REST fallback. Reserve the multi-tier ladder
+for vendors whose MCP is browser-OAuth or keychain-bound and therefore dead
+headless.
 
 ## Access Skills
 
@@ -60,7 +71,8 @@ When editing any skill listed in the matrix:
   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.
+- Put the documented token/CLI substrate first and keep the MCP as an explicit,
+  fully supported fallback tier — `credential-substrate-precedence`. Preserving
+  the MCP adapters is required; re-ordering them is not the same as removing them.
 - 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/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.