@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/rules/reference/control-reachability.md

@@ -0,0 +1,166 @@
+# Control Reachability — reference
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Control Reachability — A Prescribed Control Must Reach the Changed Path (load-bearing)
+
+A work item may hand the implementer a falsifiable stopping rule: *"make the change; `<named existing test>` must go red. If it still passes, the fix did nothing."* That is good practice — it replaces eyeballing with an observation. It is also **only valid if that test's fixture exercises the path the change touches.**
+
+When it does not, the test stays green **for a reason unrelated to the change**: execution never reached the changed code. The stopping rule then instructs the implementer to revert a correct fix, and the more faithfully the implementer follows the item, the more reliably it happens. Measured once in the portfolio: a pinned test's fixture omitted the field the fix read, execution fell through to a default branch, the test stayed green, and the fix had worked.
+
+This is the specification-side sibling of `falsifiable-checks`, which governs a check *you authored*. Here the check is **prescribed by the work item** and the defect is in the prose, not the code.
+
+## Authoring obligation — checkable, not advisory
+
+**A work item that names an existing test as a red-before-green control must say what makes that test reach the code the change touches.** Naming the code is not enough; the item names the *input*.
+
+Declare it in `## Validation Journey`, one marker per named control:
+
+```text
+[CONTROL: <test-identifier> | reaches: <input-or-field>]
+```
+
+- `<test-identifier>` — non-empty: the test file path, the test name, or both.
+- `reaches:` — the literal key, then the **input, field, fixture key, argument, or state** that carries execution into the changed code. `reaches: the fix` and `reaches: the changed code` restate the assertion and do not satisfy it.
+
+Enforced by gate **S20** in `lisa-jira-validate-ticket`, `lisa-github-validate-issue`, and `lisa-linear-validate-issue`; rendered by `lisa-jira-write-ticket`, `lisa-github-write-issue`, and `lisa-linear-write-issue`; read at claim time by `lisa-ticket-triage` and `lisa-implement`.
+
+**An item that prescribes no existing-test control is exempt.** Introducing a *new* test carries no reachability obligation — the gate is `N/A` and the item is never reported as incomplete on this basis.
+
+## Implementer obligation — a green control is two facts, not one
+
+`lisa-tdd-implementation` and `lisa-reproduce-bug` bind this arm: **when a prescribed control does not change state as the item predicted, stop. Establish which cause holds before acting on the stopping rule.**
+
+| Cause | Correct action |
+|---|---|
+| The change had no effect on behaviour | Revisit the change |
+| The fixture never reaches the changed code path | Fix or extend the control — do **not** revert |
+
+They demand opposite actions, and the cheaper reading ("the fix did nothing") wins by default when nothing forces the distinction. So force it: **prove reachability by execution, never by reading the fixture.** Put a temporary throw, log line, or counter in the changed code and run that one test; or run coverage scoped to it and read whether the changed lines were hit. Reasoning that the fixture *looks like* it reaches the path is the same move `falsifiable-checks` rejects as "mentally reverting".
+
+**Never revert on an unexplained green.** An unexplained control is a blocked observation, not a verdict — and a reachable-but-still-green control is the only form of it that licenses revisiting the change.
+
+---
+
+The full body behind the `control-reachability` eager head. It defines one vendor-neutral contract consumed by the three tracker writers (`lisa-jira-write-ticket`, `lisa-github-write-issue`, `lisa-linear-write-issue`), the three validators (`lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`) via gate **S20**, and the implementer surfaces `lisa-ticket-triage`, `lisa-tdd-implementation`, `lisa-reproduce-bug` and `lisa-implement`. Each surface cites this slug rather than growing its own prose, exactly as the vendor arms cite `leaf-only-lifecycle`, `repo-scope-split` and `derived-branch-plan`. One slug is what keeps a control rejected on JIRA from being accepted on Linear.
+
+## The measured instance
+
+A work item in a consumer lane named a real, existing test, stated a real expectation about it, and prescribed a stopping rule in substance:
+
+> Make the change; that pinned test must go red. If it still passes, the fix did nothing.
+
+On its face this is exemplary. It hands the implementer a falsifiable stopping condition instead of asking it to judge the result by eye, and it is the shape Lisa's own `falsifiable-checks` rule asks for everywhere else.
+
+**The test still passed, and the fix had worked.** The pinned test's fixture omitted the field the fix reads, so execution fell through to a default branch. The test stayed green **for an entirely new reason** — not because behaviour was unchanged, but because the fixture never reached the changed path. Following the item's own stopping rule would have reverted a correct fix. A human noticed; an unattended agent following the written rule would not have.
+
+## Why this failure mode is distinct
+
+Lisa already carries a family of rules about controls that do not bite. This one is the mirror image, and the difference is what makes it worth its own slug.
+
+| | The familiar family (`falsifiable-checks`) | This rule |
+|---|---|---|
+| Where the defect lives | The check the author wrote | The **specification** that prescribes the check |
+| Failure mode | The control **fails to bite** — passes something it should catch | The control **bites in the wrong direction** |
+| Cost | A defect ships | A **correct fix is reverted** |
+| How it looks | A green check nobody questions | Diligence — the agent followed the written stopping rule |
+| Who it hits hardest | Careless implementers | **Disciplined** implementers |
+
+It sits in the layer everyone treats as the thing that catches implementation error, which is exactly why nothing was watching it.
+
+Related, at other layers: a gate that blocks a slow reviewer but only reports a hollow one is a gate mis-weighting two real signals; a gate that declares a merge condition nothing verifies is an unverified assertion in config. Here the signal itself is uninterpretable, and it is verified by an agent — incorrectly.
+
+## Why the checkable form, and why a marker
+
+The obvious fix is a sentence of guidance: *"make sure the fixture reaches the path."* That is the wrong instrument, and it is worth being explicit about why, because it will look like the simple answer every time someone revisits this.
+
+**This failure is itself an instance of advisory guidance being insufficient.** A thoughtful author wrote a thoughtful stopping rule and it was still wrong. Prose asking for more thoughtfulness is the same class of artifact that failed. So the obligation is expressed as a **parseable declaration** a validator either finds or does not, in the same family as the `[EVIDENCE: <type>: <name>]` manifest markers — which exist for the same reason, and which turned "attach proof" from a discipline into a property.
+
+The marker also moves the check **earlier**. A prose instruction can only be evaluated at the moment the stopping rule misfires, by the one agent least able to see past it. A marker is checked before work begins, by a validator that has no stake in the outcome.
+
+## The marker
+
+```text
+[CONTROL: <test-identifier> | reaches: <input-or-field>]
+```
+
+Placed in `## Validation Journey`, one per named control. Parse by the exact `[CONTROL:` prefix and split on the single `|`.
+
+| Field | Requirement |
+|---|---|
+| `<test-identifier>` | Non-empty. The test file path, the test name, or both. It must be enough to run the test. |
+| `reaches:` | The literal key, then a non-empty description of the **input, field, fixture key, argument, or state** that carries execution into the changed code. |
+
+Worked examples:
+
+```text
+[CONTROL: tests/unit/pricing/discount.test.ts "applies tier discount" | reaches: fixture sets tier="gold", which is the field the resolver newly reads]
+[CONTROL: spec/models/invoice_spec.rb#late_fee | reaches: seeded invoice has due_on in the past, entering the overdue branch]
+```
+
+Rejected, with the reason:
+
+| Marker | Why it fails |
+|---|---|
+| `[CONTROL: discount.test.ts]` | No `reaches:` half — names the control without saying what makes it observe the change |
+| `[CONTROL: | reaches: tier field]` | Empty identifier — nobody can run it |
+| `[CONTROL: discount.test.ts \| reaches: the fix]` | Restates the assertion instead of naming an input |
+| `[CONTROL: discount.test.ts \| reaches: the changed code path]` | Same — names the code, not what gets execution there |
+
+**The marker answers one question: what in this fixture gets execution to the changed lines?** Anything that does not answer it is a control whose reachability cannot be stated, and a control whose reachability cannot be stated is not a control.
+
+## Gate S20 — when it applies, and when it must stay silent
+
+S20 applies when the body — Acceptance Criteria, Technical Approach, or Validation Journey — names an **existing** test AND predicts a state change for it when the work lands. Signals: "must go red", "currently passes and must fail", "fails before the fix and passes after", "if it still passes the fix did nothing", or any equivalent stopping rule.
+
+It is `N/A` otherwise, and that half of the contract is load-bearing. **An item that introduces a new test rather than pinning an existing one carries no reachability obligation** and must never be reported as incomplete on this basis. A gate that fires on every work item is a gate teams learn to route around; the value of S20 is that a FAIL means something specific.
+
+The remediation names the input, not the discipline:
+
+> Name the input or field that makes `<test>` reach the code this work changes, as `[CONTROL: <test> | reaches: <field>]`. If the fixture does not reach it, the test cannot observe this change — extend the fixture or specify a new test instead.
+
+`product_relevant: true`. An unfalsifiable stopping rule is a specification defect, and the person who wrote the item is the person who can fix it.
+
+## The implementer arm — a green control is two facts
+
+The authoring gate catches what it can see before work starts. It cannot see the actual test outcome, and only the implementer can. So the contract has a second arm, bound by `lisa-tdd-implementation` (RED phase) and `lisa-reproduce-bug` (when an existing test is reused as the reproduction):
+
+**When a prescribed control does not change state as the item predicted, stop. Establish which of the two causes holds before acting on the stopping rule.**
+
+| Cause | Correct action |
+|---|---|
+| The change had no effect on behaviour | Revisit the change |
+| The fixture never reaches the changed code path | Fix or extend the control — do **not** revert |
+
+Two properties of this make it worth writing down rather than trusting to judgement:
+
+1. **The actions are opposite.** Getting the cause wrong does not degrade the outcome, it inverts it.
+2. **One reading is cheaper than the other.** "The fix did nothing" requires no further work and closes the question; "the fixture never got there" requires an investigation. Left to default, the cheap reading wins — and it is the one that reverts working code.
+
+### How to establish it
+
+**Prove reachability by execution, never by reading the fixture.** Reasoning that the fixture *looks like* it reaches the path is exactly the "mentally reverting" move `falsifiable-checks` rejects, and for the same reason: the person doing the reasoning already believes the answer.
+
+Two sound methods, in order of preference:
+
+- **Instrument the changed code.** Put a temporary `throw` — not a log line, which can be swallowed by a reporter — at the top of the changed block, run that one test, and read whether it errors. Then remove it. A throw is preferred because its absence is unambiguous.
+- **Coverage, scoped to the single test.** Run the project's coverage tool over that test alone and read whether the changed lines were executed. Whole-suite coverage does not answer this: some *other* test reaching those lines tells you nothing about this control.
+
+Then report which method was used and what it showed. "The control stayed green because the fixture never set `tier`, confirmed by a throw at the resolver that the test did not hit" is a finding. "The control stayed green" is not.
+
+### Never revert on an unexplained green
+
+An unexplained control is a **blocked observation**, not a verdict. The only state that licenses revisiting the change is a control proven to reach the changed path and still not move. If reachability cannot be established at all — the harness will not run, the code path is unreachable from any fixture — that is a finding to report, and the work item's stopping rule is void until someone repairs the control.
+
+Fixing the control is ordinary work, not scope creep: extend the fixture with the field that carries execution to the change, or write the test the item should have named. Either way the control ends the work able to observe the change, which is what the item asked for in the first place.
+
+## What this rule does not claim
+
+Stated plainly so nobody reads more into it than the evidence supports.
+
+- **Frequency.** One measured instance. No count exists of how many work items name an existing test as a red-before-green control, so the rate could be rare or routine. The gate is cheap and `N/A` by default, which is the right shape for an unknown denominator.
+- **Detectability by tooling.** Whether any existing gate could *automatically* detect a fixture that does not reach the changed code path is unexamined. Coverage-diff and per-test path instrumentation are plausible and would strengthen this rule into a machine check rather than a declaration; so is the possibility that nothing available does it cheaply. This contract deliberately requires a **declaration** an author writes and a validator parses, which is checkable today.
+- **Blast radius of the observed instance.** The fix was not reverted, because a human noticed. That an unattended agent would have reverted it is inferred from the written stopping rule, not observed.
+- **That an advisory rule would not have helped.** Untested. It is a reason to prefer the checkable form, not a measured finding.

package/plugins/lisa-devin/rules/reference/convergent-review.md

@@ -0,0 +1,145 @@
+# Convergent Review
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## Convergent Review
+
+Review exists to get correct work merged, not to keep a PR in review orbit.
+
+- Block only concrete correctness, security, data-loss, or contract-violation
+  failures. Lint-owned style, formatting, taste, and speculative improvements
+  are non-blocking unless the work item or repository rules make them release
+  criteria.
+- Every finding must state severity, blocking yes/no, a concrete failure
+  scenario, evidence, and the smallest actionable fix — plus
+  `invariant_violated` (the property at risk) and `machinery_to_remove` (what
+  becomes deletable, or `none`), required for `readiness-rubric` findings and
+  recommended elsewhere.
+- Present findings highest-consequence first, by severity and blast radius, not
+  by discovery order. Report section order stays stable.
+- A blocking finding without a concrete failure scenario is malformed by
+  contract; downgrade it to non-blocking and ask for evidence.
+- Resolve each finding as `fixed`, `deferred`, or `pushed-back`. If the reviewer
+  cannot refute a pushback with fresh evidence, the author's disposition stands.
+- After suggestion implementation completes and gates pass, review does not
+  reopen absent new evidence: a relevant new commit, a failed gate, a newly cited
+  failure scenario, or a scope change.
+- Irreconcilable blocking disagreement becomes a blocked work item with both
+  positions summarized for the operator, not an endless loop.
+
+---
+
+Review exists to get correct work merged, not to keep a PR in review orbit.
+Apply this contract to every product, quality, local, bot-parity, and suggestion
+implementation pass.
+
+## Severity Bar
+
+Findings block only when they name a concrete failure scenario in one of these
+classes:
+
+- Correctness: shipped behavior violates the work item, breaks an existing
+  contract, or loses required data.
+- Security: the change creates or preserves an exploitable auth, input,
+  secret-handling, permission, or data-exposure flaw.
+- Data loss: a realistic path can delete, corrupt, overwrite, or strand user or
+  operational state.
+- Contract violation: the change breaks a public API, workflow, generated
+  artifact contract, tracker lifecycle, or documented factory invariant.
+
+Lint-owned style, formatting, taste, general maintainability preferences, and
+speculative improvements are non-blocking unless the repository rule or work
+item explicitly makes them release criteria.
+
+## Required Finding Shape
+
+Every finding must state:
+
+- Severity: `critical`, `major`, `minor`, or `nit`.
+- Blocking: `yes` or `no`.
+- Failure scenario: the concrete user, operator, security, or factory outcome
+  that occurs if the change ships as-is.
+- Evidence: the file, command output, observed behavior, ticket text, or
+  external constraint proving the scenario is reachable.
+- Fix: the smallest actionable correction, or the reason no code change is
+  needed. The correction belongs at the **owning boundary** that permitted the
+  failure, not at the symptom site.
+- `invariant_violated`: the named property the system is supposed to hold that
+  this finding puts at risk — for example "the artifact that ships is the
+  artifact CI validated". The invariant is the property; the failure scenario is
+  the outcome when it breaks. State both; they are not interchangeable.
+- `machinery_to_remove`: the redundant checks, workarounds, or scaffolding that
+  become deletable once the correction lands, or explicitly `none`. This is a
+  **scaffolding-subtraction candidate** — it is surfaced for a human or the
+  implementer to act on and is never auto-deleted by any review pass.
+
+A finding marked blocking without a concrete failure scenario is malformed by
+contract. Downgrade it to non-blocking and ask for evidence instead of treating
+it as a merge blocker.
+
+### Compatibility
+
+`invariant_violated` and `machinery_to_remove` are **required for findings
+emitted under the `readiness-rubric`** and **recommended everywhere else**. A
+finding from an existing product, quality, local, bot-parity, or suggestion
+implementation pass that omits them is still well-formed by contract — this
+extension is additive and never retroactively malforms a shipped review surface.
+
+### Readiness findings map onto this shape
+
+A readiness finding names five fields. All five bind to this contract, so there
+is no second findings format anywhere in the repository:
+
+| Readiness field | Contract field |
+|---|---|
+| the at-risk invariant | `invariant_violated` (above) |
+| `evidence` | `Evidence` |
+| `why_proof_missed` | `Evidence`, extended with a required proof-gap clause: why the existing proof machinery did not catch this |
+| `root_correction` | `Fix`, qualified: the correction goes at the owning boundary, not the symptom site |
+| redundant machinery | `machinery_to_remove` (above) |
+
+Anything that needs a sixth field extends this section rather than starting a
+parallel format.
+
+### Consequence Ordering
+
+Findings are presented **highest-consequence first**. Consequence is determined
+by severity and blast radius — how much of the system, how many users, and how
+irreversible the outcome — not by discovery order, file order, or the order a
+tool happened to emit them in. Two reviewers ordering the same finding set
+differently is a defect, not a preference.
+
+This governs the order of findings **within** a section only. Report section
+order stays stable and is unaffected: never reorder, merge, or silently omit a
+section to surface a finding earlier.
+
+## Dispositions
+
+The implementer resolves each finding with exactly one disposition:
+
+- `fixed`: code, tests, docs, or generated artifacts changed to remove the
+  failure scenario.
+- `deferred`: the issue is real but non-blocking; record the rationale and, when
+  useful, the follow-up work item.
+- `pushed-back`: the finding is not valid for this work because evidence,
+  scope, or existing project rules refute it; reply with that rationale.
+
+If a reviewer cannot refute a `pushed-back` disposition with fresh evidence, the
+author's disposition stands.
+
+## Stopping Rule
+
+After suggestion implementation completes and the required quality and
+verification gates pass, review does not reopen unless new evidence appears:
+
+- a new commit changes the reviewed behavior,
+- a gate fails,
+- a reviewer supplies a previously uncited failure scenario, or
+- the work item scope changes.
+
+Irreconcilable blocking disagreement is not an endless review loop. Move the
+work item to the configured blocked state, add the human-needed marker when the
+decision is human-only, and summarize both positions in operator-readable
+language.

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

@@ -0,0 +1,249 @@
+# Credential-Substrate Precedence
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## 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. The two legacy OS-keychain rungs that remain (`lisa-atlassian-access`,
+   `lisa-notion-access`) are a dated migration ramp with a **removal date of
+   2026-11-01**, not a standing exemption; no new access skill may add one.
+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.
+
+---
+
+**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.
+
+## Legacy OS-keychain fallback — removal date 2026-11-01
+
+Two access skills (`lisa-atlassian-access`, `lisa-notion-access`) still read an
+OS keychain as a last rung below the chokepoint, because the guided
+`/lisa:setup:atlassian` and `/lisa:setup:notion` flows wrote credentials there
+before `lisa-secrets-access` existed. That rung is a **migration ramp with a
+removal date, not a standing exemption**: it is a second reader of the same
+credential, which is exactly how one credential ends up living in two places and
+drifting, and a keychain entry is machine-local ambient state that no headless
+surface can reach — so a project resting on it has no working tier 1 in cron, CI,
+or a cloud session.
+
+**Both rungs are deleted on 2026-11-01.** Before then, projects still on the
+keychain path move the credential into their configured provider — re-running
+`/lisa:setup:<vendor>` stores it through the chokepoint. After removal, a
+keychain-only project fails loudly with the exact variable named (tier 3), which
+is the intended outcome: it can never silently resolve through a substrate
+authenticated elsewhere. No new access skill may add a keychain rung; a credential
+the chokepoint cannot answer for is a setup gap to fix, not a store to add.
+
+## 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.
+
+An access skill whose MCP is provider-credential-authenticated has no interactive
+tier to demote — that MCP *is* the tier 1 substrate (`lisa-sonarcloud-access`: the
+official SonarQube MCP authenticates headlessly from `SONARQUBE_CLI_TOKEN`).
+Reserve a browser-OAuth demotion for vendors whose MCP is keychain-bound and
+therefore dead headless.
+
+That is a claim about tier ORDER and never about exclusivity. "Tier 1 needs no
+demotion" does not license "there is no other substrate": where the vendor exposes
+a token-authenticated Web API, it remains a sanctioned read-only fallback for a
+surface on which the MCP is not wired, and a missing MCP there is a demotion rather
+than a terminal tool-access failure.