@codyswann/lisa 2.353.0 → 3.1.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/.codex-plugin/skills/lisa-tracker-build-intake/SKILL.md

@@ -83,4 +83,5 @@ If the canonical fix is merged but not yet on the production branch, the close c
 - **Leaf-only dispatch, every vendor.** Per the `leaf-only-lifecycle` rule, each vendor scanner dispatches leaf work units only and moves or safe-blocks a container (open child work, or a childless Epic) carrying a stale build-ready role according to its lifecycle semantics. This shim does not re-implement the gate — it relies on the vendor scanner's Phase 3a — but the contract is uniform across `jira`, `github`, and `linear` so behavior never drifts by tracker.
 - **Terminal native closure, every capable vendor.** Per the same rule, each vendor scanner finalizes native open/closed state only at the true terminal `done` value. This shim never performs native closure itself, but callers can rely on the dispatched vendor scanner to apply the contract.
 - **Duplicate already fixed, every vendor.** Auto-close without a PR is allowed only for `DUPLICATE_ALREADY_FIXED` with canonical reference and empirical base-branch evidence. Do not conflate this with `BLOCKED`.
+- **Claim-time guards, every vendor.** Per the `claim-time-guards` rule, each vendor scanner runs both guards inside its Phase 3b before the claim transition: an item whose own key already appears in git history or an open/merged PR routes to **verify-and-close** rather than being built twice, and the **`two-failed-attempts`** valve moves an item with two `[lisa-build-attempt]` markers to the configured blocked role and stops the cycle. This shim does not re-implement either guard; it forwards the contract so behavior never drifts by tracker.
 - Never run two intake cycles concurrently against overlapping queues — the scheduling layer is responsible for serialization.

package/plugins/lisa/.codex-plugin/skills/lisa-tracker-create/SKILL.md

@@ -24,4 +24,5 @@ See the `config-resolution` rule for configuration and dispatch table.
 ## Rules
 
 - All vendor skills delegate every individual ticket write through `lisa-tracker-write`. They never call vendor-specific write tools directly.
+- **Declare readiness on every leaf write.** Per the `ready-role-filing` rule an omitted `build_ready` is **not build-ready** on any tracker, so pass `build_ready: true` on each Sub-task (the leaf work units this skill plans) and never on the Epic or Stories, which are containers per `leaf-only-lifecycle`. A leaf that is deliberately held instead passes `human_gate: "<why a human must judge this first>"`. Filing a leaf with neither is an incomplete handoff and `lisa-tracker-write` rejects it.
 - This shim is for ad-hoc creation from code files / descriptions. PRD-driven creation goes through the `*-to-tracker` skills (notion / confluence / linear / github).

package/plugins/lisa/.codex-plugin/skills/lisa-tracker-write/SKILL.md

@@ -52,3 +52,4 @@ See the `config-resolution` rule for the full configuration schema and skill-map
 - Never accept a tracker value outside `{jira, github, linear}`.
 - Never mutate `$ARGUMENTS` between layers. The vendor skills define their own input contract.
 - Never inline gate logic here. All validation rules live in the vendor skills (`lisa-jira-validate-ticket` / `lisa-github-validate-issue` / `lisa-linear-validate-issue`); this skill only routes.
+- **Readiness is the caller's explicit claim, not this shim's default.** Per the `ready-role-filing` rule, an omitted `build_ready` is **not build-ready** on every vendor, so a caller filing work it expects build-intake to pick up must pass `build_ready: true`, and a caller deliberately holding work outside the queue must pass a `human_gate` reason. This shim normalizes nothing — it forwards `$ARGUMENTS` verbatim and the vendor writers enforce the contract — which is exactly why the caller cannot rely on a vendor default here.

package/plugins/lisa/.codex-plugin/skills/lisa-verify/SKILL.md

@@ -35,7 +35,7 @@ Treat the first successful lead-spawn request (or, on the Codex fallback, the fi
 
 Execute the **Verify** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The flow includes:
 
-1. **Pre-flight: codification gate** — confirm that every passing local empirical verification on this branch was codified as a regression test (the Implement flow's codify step). If any verification has no committed test and no allowed skip reason (PR / Documentation / Deploy / Investigate-Only), invoke `codify-verification` now and amend the PR before shipping. For frontend work the gate additionally enforces the `bdd-e2e-coverage` rule: the shipped behavior exists as a Gherkin scenario with a stable ID, every required scenario-platform obligation has aligned automation in the project's configured runner for that platform or a dated waiver, and the project's coverage gate passes with the matrix regenerated. A missing runner is never a bare recorded absence — it needs a dated `platformWaivers` entry (per the rule) and, where the runner could reasonably be added, a linked build-ready follow-up ticket referenced from it; never a silent skip. Missing BDD coverage is a verification failure that blocks the ship, not a warning. A change cannot ship until its verifications are guarded. For work that adds or changes persistent state the gate additionally enforces the `reset-seed-coverage` rule: every entity the work introduces or changes is classified in the project's state contract, anything `fixture-owned` has an ownership predicate and a sweep, and the state-classification check passes — an unclassified entity fails closed and blocks the ship exactly as missing BDD coverage does.
+1. **Pre-flight: codification gate** — confirm that every passing local empirical verification on this branch was codified as a regression test (the Implement flow's codify step). If any verification has no committed test and no allowed skip reason (PR / Documentation / Deploy / Investigate-Only), invoke `codify-verification` now and amend the PR before shipping. For frontend work the gate additionally enforces the `bdd-e2e-coverage` rule: the shipped behavior exists as a Gherkin scenario with a stable ID, every required scenario-platform obligation has aligned automation in the project's configured runner for that platform or a dated waiver, and the project's coverage gate passes with the matrix regenerated. A missing runner is never a bare recorded absence — it needs a dated `platformWaivers` entry (per the rule) and, where the runner could reasonably be added, a linked build-ready follow-up ticket referenced from it — filed through `lisa-tracker-write` with explicit `build_ready: true` per `ready-role-filing`, since an omitted flag is NOT build-ready on any tracker and the waiver would then point at work nothing claims; never a silent skip. Missing BDD coverage is a verification failure that blocks the ship, not a warning. A change cannot ship until its verifications are guarded. For work that adds or changes persistent state the gate additionally enforces the `reset-seed-coverage` rule: every entity the work introduces or changes is classified in the project's state contract, anything `fixture-owned` has an ownership predicate and a sweep, and the state-classification check passes — an unclassified entity fails closed and blocks the ship exactly as missing BDD coverage does.
 2. **Commit** any pending changes via `lisa-git-commit`
 3. **Push and PR** via `lisa-git-submit-pr`
 4. **PR Watch Loop** — drive the PR to MERGED via `lisa-drive-pr-to-merge`, the single source of truth for clearing every blocker: auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot review-comment handling with thread resolution (it invokes `lisa-pull-request-review` itself), stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification. Do not re-implement the loop or its terminal conditions.

package/plugins/lisa/rules/eager/bdd-e2e-coverage.md

@@ -15,7 +15,7 @@ Default locations (a project that already has an equivalent contract keeps its o
 | Artifact | Default path | What it is |
 |---|---|---|
 | Scenarios | `bdd/features/*.feature` | Gherkin, the product-level behavior contract |
-| Coverage map | `bdd/coverage-map.json` | scenario → runner/platform/file/evidence mappings, plus waivers |
+| Coverage map | `bdd/coverage-map.json` | scenario → runner/platform/file/evidence mappings, plus waivers, per-runner test-discovery roots, and exclusions |
 | Generated matrix | `docs/bdd-scenario-matrix.md` | regenerated, never hand-edited |
 | Burndown | `docs/e2e-bdd-coverage.md` | current coverage per platform |
 
@@ -36,6 +36,8 @@ The last three are out of the denominator. Deleting a committed capability to ma
 
 Coverage is counted per **required scenario-platform obligation**, and an obligation is sealed only by **aligned e2e automation in the project's configured runner for that platform** — the runner→platform mapping is project configuration (e.g. a web runner covering `web`, a device runner covering `ios`/`android`), never named by this contract. A unit test, a route boot, a screenshot, a fixture, an API test, or a passing test on a *different* platform never seals an obligation: they prove something else. Each mapping names the runner, the platforms, the file, and the evidence string inside it, so the gate can prove the mapping still resolves.
 
+**The gate reads in both directions.** It also walks the test roots the project declares per runner, so an e2e test that exists but that the contract never mentions is a violation — map it to a scenario, or record an exclusion stating why it aligns to no product behavior. Roots are configuration: a subflow or helper directory left undeclared is structurally invisible, which is the same failure as having no gate for it.
+
 **Waivers are dated IOUs, never coverage.** An obligation whose runner genuinely cannot decide it today (no camera on the simulator, no request interception, no provisioned provider credential) is recorded with scenario, platforms, reason, and `recordedAt`. It leaves the denominator; it never counts as covered, and nothing about it asserts the behavior works. A waiver is invalid — and fails the gate — when it names a nonexistent scenario or an undeclared platform, covers an already-excluded scenario, or masks a scenario-platform that already has a mapping. Revisit a waiver when its reason dies.
 
 ## Definition of done

package/plugins/lisa/rules/eager/claim-time-guards.md

@@ -0,0 +1,30 @@
+# Claim-Time Guards (load-bearing)
+
+Two guards that run when build-intake claims a ready item, both from failures observed in the fleet: an item built twice because it had already shipped, and a loop burning cycles re-attempting an item that was never going to succeed.
+
+**One vendor-neutral contract, cited by every build-intake arm** (the `leaf-only-lifecycle` / `repo-scope-split` / `rejection-detection` / `claim-archaeology` precedent: one shared slug, never three divergent implementations).
+
+## When they run
+
+Inside build-intake step `3b`, after `rejection-detection` and `claim-archaeology`, still before the `$READY → $CLAIMED` transition. The `two-failed-attempts` valve runs first — it is cheaper and it is the only pass that can stop the claim outright.
+
+## `already-implemented` → `verify-and-close`
+
+A ready item may already be implemented, because agents ship without transitioning. Before implementing, probe for the item's **own** key:
+
+```bash
+git log --all --grep "<key>" --format='%H %aI %s' -n 10
+gh pr list --repo <org>/<repo> --state all --search "<key>" --json number,state,mergedAt,url
+```
+
+On a hit, do not build it twice — switch `3c` to **verify-and-close**: verify what shipped against this item's acceptance criteria, post evidence naming the shipping PR/commit, then run the ordinary `3d` transition and rollup. If the shipped change only partially satisfies the criteria, implement the remaining gap instead of closing.
+
+Distinct from `claim-archaeology` (finds a **different** ancestor issue) and from `DUPLICATE_ALREADY_FIXED` (a **different** canonical issue). Unreadable history degrades to "no hit"; the guard never blocks the claim.
+
+## `two-failed-attempts` → blocked
+
+Every non-success terminal outcome records a durable marker on the item — a visible line plus `<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->` (match on the marker, never the title). A cron holds no memory between cycles, so the item carries the count.
+
+With **two or more** markers at claim time: do not claim. Move the item to the configured `blocked` role (resolved per `config-resolution`, never hardcoded), post an operator-readable comment naming both attempts and what a human must decide or supply, and **stop the loop** for this cycle. Recovery is deliberate — a human or a `lisa-repair-intake` cycle with the blocker provably cleared returns it to the queue.
+
+Full contract (probe bounds, verify-and-close steps, partial-hit handling, marker mechanics): [reference/claim-time-guards.md](../reference/claim-time-guards.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/eager/ready-role-filing.md

@@ -0,0 +1,22 @@
+# Ready-Role Filing (load-bearing)
+
+Filing a work item without the ready role is an **incomplete handoff** — build-intake scans the ready lane and nothing else, so the item is never picked up. A correct write plus a missing role still loses the work.
+
+## Omitted means NOT ready — on every tracker
+
+**An omitted `build_ready` is NOT build-ready on JIRA, GitHub, and Linear alike.** Ready is an explicit claim, never an accident of which tracker a project configured. This is a **breaking change** for GitHub and Linear callers, which previously treated omission as ready; `lisa-github-validate-issue` F4's compensating omitted → `true` normalization is removed with it.
+
+## Every filing declares one of two things
+
+- **`build_ready: true`** — complete enough to build; enters the ready lane for auto-pickup. Required for any complete defect found during other work, so it is claimable next cycle with no human flipping status.
+- **`human_gate: "<why a human must judge this first>"`** — deliberately held outside the queue. The writer stamps a visible line plus `<!-- [lisa-human-gate] reason=<short-slug> -->` so the hold is auditable.
+
+Filed, not ready, and no `human_gate` is the **incomplete handoff** case — writers reject it and name both ways to resolve it. `build_ready: false` with no reason is the same omission with a value attached. `build_ready` stays subordinate to `leaf-only-lifecycle`: a container is never build-ready and needs no gate.
+
+## The named exception
+
+`lisa-exploratory-qa` files findings not-ready **by design** — its findings are candidate defects whose product significance a human should judge. It is the named human-gate exception, not drift: it pairs `ready=false` with an explicit `human_gate` reason. The sibling `e2e-coverage-gaps` skills are the contrast (a missing test is not a product question, so they file build-ready).
+
+`lisa-repair-intake` sweeps for open items that are neither in the ready role nor marked `[lisa-human-gate]`, and surfaces them rather than promoting them.
+
+Full contract (the per-vendor before/after table, marker format, and recovery sweep): [reference/ready-role-filing.md](../reference/ready-role-filing.md).

package/plugins/lisa/rules/reference/automation-runbook-contract.md

@@ -159,7 +159,14 @@ fleet verdict.
 
 A loop that cannot proceed escalates by filing a tracker item (through `lisa-tracker-write`, per
 `tracked-work` and `integration-access-layer`) labeled **`status:blocked`** and **`human-needed`**,
-containing exactly these fields:
+containing exactly these fields.
+
+Every escalation is a **declared human gate** under `ready-role-filing`: it passes
+`human_gate: "<the smallest unresolved choice>"` so the writer stamps the auditable
+`[lisa-human-gate]` marker. An escalation is precisely a filing whose readiness a human owns, so
+omitting the flag and relying on a tracker default would make a deliberate gate indistinguishable
+from the accidental non-ready filing that rule exists to catch.
+
 
 | Field | Content |
 |---|---|

package/plugins/lisa/rules/reference/bdd-e2e-coverage.md

@@ -68,16 +68,43 @@ platforms it requires and that each named platform has a configured runner.
       "level": "behavioral"
     }
   ],
+  "testDiscovery": {
+    "<runner>": {
+      "roots": ["<repo-relative directory>", "..."],
+      "extensions": [".<suffix>", "..."],
+      "ignore": ["<optional repo-relative path prefix>"],
+      "evidence": { "kind": "call-title", "functions": ["test", "it"] }
+    }
+  },
   "exclusions": [
-    { "file": "<path>", "reason": "why this test aligns to no product behavior" }
+    {
+      "file": "<path>",
+      "evidence": "<optional exact title; omit to excuse the whole file>",
+      "reason": "why this test aligns to no product behavior"
+    }
   ]
 }
 ```
 
 `evidence` is what makes a mapping falsifiable: the gate reads the mapped file and confirms the
 string is still there, so renaming or deleting a test breaks the map loudly instead of leaving a
-scenario silently unguarded. `exclusions` records tests that deliberately map to nothing — starter
-templates, source-level corroboration — so "unmapped test" stays a meaningful signal.
+scenario silently unguarded.
+
+`testDiscovery` closes the other direction. Validating only what the map DECLARES can never see a
+test file nobody declared, so the gate walks the project's own roots and requires **every test it
+finds to be named by a mapping or excused by an exclusion**. Roots and the evidence grammar are
+per-runner configuration — list every directory, including subflow and helper directories, because
+a directory omitted here is structurally invisible to the gate. Evidence grammars are an allowlist
+of two (`call-title` reads `test("…")`-style declarations; `line-field` reads a leading `name:`
+field), never a project-supplied regular expression, and a template-literal title is used verbatim
+from the source rather than rewritten. A missing block is a defect in enforced mode
+(`discovery-missing`); a malformed one is refused in **every** state (`discovery-invalid`), because
+discovery that silently finds nothing looks exactly like a clean repo.
+
+`exclusions` records tests that deliberately map to nothing — starter templates, source-level
+corroboration — so "unmapped test" stays a meaningful signal. Each entry states a `reason`, and an
+exclusion whose file is gone, whose title was renamed, or that no discovery root covers is
+`exclusion-stale`: a standing claim about nothing, never a permanent excuse.
 
 ## The gate
 
@@ -94,8 +121,14 @@ Two commands, wired into the project's script surface and into CI:
    - an invalid waiver (nonexistent scenario, undeclared platform, already-excluded scenario, a
      `runner` that does not cover the waived platform under `runnerPlatforms`, or one that masks an
      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.
 
+   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
+   documents it.
+
 The percentage measures **aligned automation inventory, not the latest run result**. A mapped test
 that currently fails is a red CI check, a separate signal; the map only asserts the automation
 exists and still says what it claimed. Both facts are required — a green gate over a red suite is
@@ -157,9 +190,12 @@ A repo with no contract yet, taking its first frontend work item:
 
 1. **Detect runners.** Find the e2e harnesses the project actually has, per the Tool Discovery
    Process in `verification-lifecycle`. Record which platforms each covers.
-2. **Scaffold the minimum** — `bdd/features/`, `bdd/coverage-map.json` (with `runnerPlatforms` from
-   step 1 and a coverage floor of the current, honest number), the regenerate + check scripts wired
-   into the project's script surface, and the CI invocation of the check.
+2. **Scaffold the minimum** — `bdd/features/`, `bdd/coverage-map.json` (with `runnerPlatforms` and
+   `testDiscovery` from step 1 — every root each runner's tests actually live in, subflow and helper
+   directories included — and a coverage floor of the current, honest number), the regenerate +
+   check scripts wired into the project's script surface, and the CI invocation of the check.
+   Pre-existing tests that align to no product behavior are recorded as `exclusions` with reasons
+   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.

package/plugins/lisa/rules/reference/claim-time-guards.md

@@ -0,0 +1,69 @@
+# Claim-Time Guards
+
+Two guards that run when build-intake claims a ready item. Both come from geminisportsai's hand-rolled `sprint-loop` and both address failures actually observed there — an item built twice because it had already shipped, and a loop burning cycles re-attempting an item that was never going to succeed.
+
+It is a **single vendor-neutral contract** consumed by all three build-intake skills (`lisa-github-build-intake`, `lisa-jira-build-intake`, `lisa-linear-build-intake`). Each arm cites this slug in its claim step rather than growing its own copy, exactly as the arms cite `leaf-only-lifecycle`, `repo-scope-split`, `rejection-detection`, and `claim-archaeology`. One slug is what keeps a guard that fires on GitHub from being absent on Linear.
+
+## Sequencing
+
+The shared claim phase is `3a.0` repo-scope gate → `3a` leaf-only claim gate → `3b` Claim → `3c` run lifecycle → `3d` transition to done. Inside `3b`, the pre-transition window now runs four passes in a fixed order:
+
+1. **`rejection-detection`** — needs the current-lane signal the relabel destroys.
+2. **`claim-archaeology`** — consumes the rejection classification.
+3. **`two-failed-attempts` valve** (this rule) — may end the cycle before any claim happens.
+4. **`already-implemented` check** (this rule) — decides whether `3c` implements or verifies.
+
+The valve runs before the already-implemented probe because it is cheaper and it is the only one of the four that can stop the claim outright: there is no point spending git and PR queries on an item that is about to be blocked.
+
+## Guard 1 — already-implemented → verify-and-close
+
+**Why it exists.** A ready item may already be implemented. Agents ship without transitioning: the PR merges, the work is done, and the item sits in the ready lane looking untouched. Claiming it normally means building the same change a second time — at best a no-op PR, at worst a conflicting reimplementation of work that already landed.
+
+**The probe.** Two deterministic searches for the item's **own** canonical key (the ref carried by the `Work-Item:` trailer), bounded and never interactive:
+
+```bash
+# Commits anywhere in history — branches and merged work included — that carry the key.
+git log --all --grep "<key>" --format='%H %aI %s' -n 10
+
+# Open and merged PRs referencing the key (GitHub shown; JIRA and Linear use the
+# equivalent search through their access layers, never a direct vendor API call).
+gh pr list --repo <org>/<repo> --state all --search "<key>" --json number,state,mergedAt,url
+```
+
+A hit counts only when it names **this** key. Branch-name coincidence, a similar title, or a reference from an unrelated item is not a hit — that is `claim-archaeology`'s job, not this one.
+
+**The outcome.** On a hit, do not implement. Switch `3c` to **verify-and-close**:
+
+1. Read the referenced commits/PR and establish what actually shipped.
+2. Verify the shipped change against this item's acceptance criteria — the ordinary verification path, not a fresh build.
+3. On a pass: post evidence naming the shipping PR/commit, then run the normal `3d` transition (which still gates on the PR being merged) and the `3d.1` rollup.
+4. On a fail — the shipped change does not satisfy the criteria — record that the item is only **partially** implemented, and proceed with the ordinary implement path for the remaining gap. A partial hit must never close an item whose criteria are unmet.
+
+**What this is not.** Three nearby behaviors it must not be conflated with:
+
+- **`claim-archaeology`** answers "is this item round 2 of a *different* past failure?" — it looks for an **ancestor** issue. This guard looks for **this same item** already having shipped. Different question, different key, different outcome.
+- **`DUPLICATE_ALREADY_FIXED`** (from `lisa-ticket-triage`) is about a **different canonical issue** whose fix covers this one; it closes as a duplicate. This guard finds work done **under this item's own key** and closes it as completed, not as a duplicate.
+- **Rejection reclaim** is about work that shipped and was pushed back. Verify-and-close applies to work that shipped and nobody noticed.
+
+**Never block.** An unreadable history, an absent `gh`, or a failed search degrades to "no hit" and the ordinary implement path proceeds. A speculative probe must never strand a ready item.
+
+## Guard 2 — two-failed-attempts → blocked
+
+**Why it exists.** Without a valve, a scheduled loop re-claims the same failing item every cycle forever. Each attempt costs a full build flow, and the third attempt is not more likely to succeed than the second — what changed between them was nothing.
+
+**The counter.** Attempts are counted from durable markers on the item itself, not from session memory (a cron process holds no state between cycles). On every **non-success terminal outcome** for a claimed item — errored, blocked by a gate, PR abandoned unmerged — the intake arm records a visible comment plus a marker:
+
+```text
+Build attempt <N> did not complete: <one-line operator-readable reason>.
+<!-- [lisa-build-attempt] n=<N> outcome=<outcome> -->
+```
+
+The marker line is verbatim; the count is the number of `[lisa-build-attempt]` markers on the item. Match on the **marker, never the title**. A successful build records no marker, so an item that shipped after one bad attempt starts clean if it is ever re-filed.
+
+**The threshold is two.** At the top of the claim, count existing markers. With **two or more**, do not claim:
+
+1. Move the item to the configured `blocked` role (`build.blocked` / `workflow.blocked`, resolved per `config-resolution` — never a hardcoded lane).
+2. Post an operator-readable comment naming both prior attempts, what each one hit, and what a human would need to decide or supply. Written for a non-technical operator, per `report-actionability`.
+3. **Stop the loop** — end the cycle without claiming anything else. Stopping is the point: the next scheduled invocation should not immediately pick up the next item as though nothing happened.
+
+**Recovery is deliberate.** A blocked item returns to the queue only when a human (or `lisa-repair-intake`, once the named blocker is provably cleared) moves it back. The attempt markers stay on the item as history; re-entering the ready lane after a real fix is a fresh claim whose markers describe why it was hard, not a silent reset of the counter.

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.