@codyswann/lisa 3.0.0 → 3.2.0

package/plugins/lisa-cursor/hooks/threshold-ratchet-families.mjs

@@ -10,6 +10,30 @@
  * File families the ratchet watches. `kind` selects the extractor;
  * `direction` applies to numeric-leaf kinds ("min" values may only rise,
  * "max" values may only fall).
+ *
+ * PER-FAMILY POLICY, reviewed 2026-08-12. A family keeps its ratchet unless a
+ * NAMED deterministic non-regression invariant replaces the property the
+ * ratchet was providing — deleting a ratchet deletes that property with it, so
+ * "this generates churn" is a reason to find a replacement, never a reason to
+ * delete on its own:
+ *
+ *   coverage / simplecov / e2e   KEPT. Here the ratchet IS the non-regression
+ *     invariant, and no per-item equivalent exists short of committing a
+ *     per-file coverage baseline — an artifact that only ever accumulates.
+ *     Revisit if one appears.
+ *   stryker                      KEPT. `thresholds.break` is an absolute floor,
+ *     kept outright; the mutate-list comparison detects EXEMPTION ADDITIONS
+ *     rather than creep, and has no number for a pull request to nudge.
+ *   eslint / rubocop / k6 / lisa-config   KEPT, unchanged.
+ *
+ * Exactly one family was replaced, and it is not watched here and never was:
+ * the BDD traceability floor, whose numeric ratchet gave way to per-obligation
+ * checks. See `expo/copy-overwrite/scripts/bdd/baseline.mjs`.
+ *
+ * Retiring a family is SEQUENCED: the replacement invariant lands, then a
+ * `thresholdRatchet.allow` entry merges from the base side, then the mechanism
+ * changes. Never the reverse — this checker is precisely what stops a change
+ * granting itself the exception that permits it.
  */
 export const FAMILIES = [
   {

package/plugins/lisa-cursor/rules/bdd-e2e-coverage-reference.mdc

@@ -53,7 +53,7 @@ platforms it requires and that each named platform has a configured runner.
   "schemaVersion": 1,
   "asOf": "<ISO date>",
   "runnerPlatforms": { "<runner>": ["<platform>", "..."] },
-  "coverageFloor": { "<platform>": "<0-100, the committed floor — may rise, never falls>" },
+  "coverageFloor": { "<platform>": "<0-100, an absolute bar checked in enforced mode — not a ratchet, set once and left alone>" },
   "platformWaivers": [
     {
       "scenario": "BDD-DOMAIN-NNN",
@@ -128,7 +128,9 @@ Two commands, wired into the project's script surface and into CI:
      existing mapping);
    - a discovered test named by no mapping and no exclusion, or an exclusion that no longer excuses
      anything;
-   - a regression against the project's committed `coverageFloor` per platform.
+   - a platform sitting below its committed `coverageFloor`;
+   - coverage given back: an obligation mapped at the base revision that nothing maps here;
+   - new behavior nobody mapped or waived.
 
    Regeneration is never blocked by the check: `--write` rewrites the report and burndown whenever a
    report can be built at all, so a stale evidence string can never hold hostage the paperwork that
@@ -139,12 +141,20 @@ that currently fails is a red CI check, a separate signal; the map only asserts
 exists and still says what it claimed. Both facts are required — a green gate over a red suite is
 not coverage.
 
-### Coverage floor, not coverage target
+### Coverage floor, not coverage target — and not a ratchet
 
-Projects adopting this contract mid-life start below 100% and must not be blocked by that. The gate
-enforces a **ratchet**: the committed floor per platform may rise and may never fall. Recorded in
-`coverageFloor`, it is bumped by regenerating the matrix after a frontend work item raises it by the
-obligations it seals; it is never asked to clear the whole backlog.
+Projects adopting this contract mid-life start below 100% and must not be blocked by that. The
+committed `coverageFloor` per platform is an **absolute bar** answering "is this platform below it
+right now". Set it once at adoption to the honest measured number (or `0`) and leave it: nothing
+forces it upward, and lowering it needs no ceremony.
+
+What stops coverage sliding backwards is checked directly, per obligation, against the base
+revision — **an obligation that was mapped may not stop being mapped, and new behavior arrives
+mapped or waived**. Giving coverage back is legitimate but takes two artifacts one author cannot
+produce alone: a recorded route (a `retirements` record or a `platformWaivers` entry) plus the
+maintainer-applied `bdd-floor-baseline` label. Gaps that predate the change are burndown, never a
+gate failure — which is what lets a brownfield project adopt `enforced` without first backfilling
+its whole history.
 
 ## Waivers versus `@blocked`
 
@@ -203,7 +213,8 @@ A repo with no contract yet, taking its first frontend work item:
    during this step, never left undisclosed.
 3. **Write only this item's scenarios.** The first item is not a backfill project. Pre-existing
    uncovered behavior becomes burndown in `docs/e2e-bdd-coverage.md`, and the floor starts where the
-   repo actually is.
+   repo actually is. That is a one-time act, not a recurring one: from here on the floor stays put
+   and what protects each new obligation is the per-obligation check, not the number.
 4. **Seal this item's obligations** and commit the regenerated matrix and burndown with the change.
 
 If a required platform has **no** e2e runner at all, that obligation is never left as a bare `N/A` —

package/plugins/lisa-cursor/rules/credential-substrate-precedence-reference.mdc

@@ -0,0 +1,171 @@
+---
+description: "Credential-Substrate Precedence"
+alwaysApply: false
+---
+
+# 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-cursor/rules/credential-substrate-precedence.mdc

@@ -0,0 +1,57 @@
+---
+description: "Credential-Substrate Precedence (load-bearing)"
+alwaysApply: true
+---
+
+# Credential-Substrate Precedence (load-bearing)
+
+**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.**
+
+**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 that ordering.
+
+Settled by decision record `2026-08-12-credential-substrate-precedence` (D6), and
+settled in the `settled-decisions` sense: re-arguing MCP-first inside a skill is out of
+scope for that skill's work.
+
+## The ladder
+
+1. **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 — never read an OS keychain a second
+   time.
+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
+   **not** qualifying reasons.
+3. **Tier 3 — loud, actionable failure** naming the exact credential to set and the exact
+   remediation. Never silently no-op, never blind-retry a failed or absent substrate,
+   never fall through to one that failed identity-match.
+
+## Identity-match is mandatory on every substrate
+
+Verified **in both directions** before any operation: the substrate must claim the
+configured tenant, and the configured tenant must be one the substrate can reach. A
+substrate authenticated as a different account is **skipped, never used — including at
+tier 1**. A credential is not an identity claim; the identity claim is what the provider
+says when asked. Skipping the check because "the user obviously meant this workspace" is
+forbidden.
+
+## Mutating operations: fallback is guarded, never routine
+
+Falling back to an ambient-bound substrate for a **write** requires: switch profile and
+assert identity immediately before the write → write → re-read the affected objects →
+assert the tenant **from the response** (self URL host, cloudId in the path, response
+metadata), not from the pre-flight check → on mismatch, stop, report a cross-tenant
+hazard, and best-effort roll back. A successful pre-flight switch is not sufficient:
+another process can mutate global state between the check and the write.
+
+Full contract (per-vendor identity anchors and probes, the provider-first rationale, MCP's
+first-class fallback role, consequences, and the checklist for adding or editing an access
+skill): [reference/credential-substrate-precedence.md](credential-substrate-precedence-reference.mdc).

package/plugins/lisa-cursor/rules/integration-access-layer-reference.mdc

@@ -9,24 +9,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
 
@@ -65,7 +76,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-cursor/rules/integration-access-layer.mdc

@@ -9,7 +9,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](credential-substrate-precedence-reference.mdc);
+full matrix and migration rules:
 [reference/integration-access-layer.md](integration-access-layer-reference.mdc).

package/plugins/lisa-cursor/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: