@codyswann/lisa 3.0.0 → 3.2.0

package/plugins/lisa/.codex-plugin/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/.codex-plugin/skills/lisa-sentry-access/SKILL.md

@@ -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/.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/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/rules/eager/credential-substrate-precedence.md

@@ -0,0 +1,52 @@
+# 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](../reference/credential-substrate-precedence.md).

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/bdd-e2e-coverage.md

@@ -48,7 +48,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",
@@ -123,7 +123,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
@@ -134,12 +136,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`
 
@@ -198,7 +208,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/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.