@codyswann/lisa 4.49.0 → 4.50.1

package/plugins/lisa-cursor/rules/automation-runbook-contract-reference.mdc

@@ -5,6 +5,103 @@ alwaysApply: false
 
 # Automation Runbook Contract
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Automation Runbook Contract (load-bearing)
+
+**Every registered automation loop carries a checked-in runbook, and every run of that loop ends in
+exactly one of six run outcomes** with a one-line, operator-readable summary. A registered loop with
+no runbook, or a run that stops without naming its outcome, is a contract violation.
+
+**One vendor-neutral contract, to be cited by (wired in the loop-conformance ticket)
+`lisa-setup-automations`, `lisa-automation-status`, `lisa-tear-down-automations`, and every
+registered loop skill** (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug,
+never divergent per-loop prose).
+
+## Membership
+
+Membership is **registration, not skill-existence**: a loop is under this contract the moment it is
+registered as a scheduled automation, and registering a new one pulls it in automatically. There is
+no hardcoded roster of loops anywhere.
+
+### Interactive flows are members too
+
+The outcome vocabulary is **not cron-specific** — it answers "did this need me?", which an operator
+asks of an interactive run exactly as often as of a scheduled one. Every Lisa flow that terminates
+is a member: `lisa-implement`, `lisa-verify`, `lisa-plan`, `lisa-git-submit-pr`,
+`lisa-drive-pr-to-merge`, `lisa-research`, and any skill invoked as a slash command.
+
+For an interactive flow the required run record is the **final user-facing message**, not a JSONL
+row written by `automation-run-record.mjs`. Interactive flows may also record local JSONL telemetry
+when a specific skill owns that surface, but this contract's mandatory record is the final answer.
+It opens with the outcome and the operator action, before any narrative:
+
+```
+change-proved — nothing for you. PR #6393 open, auto-merge on, CI running.
+approval-requested — need a decision: ship the 135 Regular→Bold flips, or hold for design sign-off?
+recovery-required — need you: staging E2E gate red for congestion; rerun or admin-merge.
+```
+
+The operator must learn whether they are needed **from the first line**, without reading the report.
+Findings, evidence and caveats follow; they never replace the action line and never precede it.
+
+An interactive flow that ends in prose with the action buried — or absent — is the same contract
+violation as a silent cron exit. "I flagged X, I noticed Y, worth knowing Z" is narrative, not an
+outcome. If nothing is needed, say **"nothing for you"** in those words and stop.
+
+## The six run outcomes
+
+Exactly one per run:
+**`nothing-needed | candidate-proposed | change-proved | approval-requested | recovery-required | policy-obsolete`**
+
+Health and operator action are **orthogonal** — a healthy run can still need an answer:
+
+- `nothing-needed` — the loop ran and found nothing to act on. **Healthy.** Operator action: none.
+  A queue scanner's `nothing-needed` summary must name the lanes it swept and the total open — a dry
+  queue and a wrong denominator are otherwise indistinguishable. See the reference body.
+- `candidate-proposed` — the loop proposed work (ticket, PRD, recommendation). **Healthy.** Operator
+  action: review the proposed item and flip it ready when you want it built.
+- `change-proved` — the loop made a change and proved it with evidence. **Healthy.** Operator
+  action: none (informational).
+- `approval-requested` — the loop reached a boundary it may not cross alone. **Healthy.** Operator
+  action: answer the approval question.
+- `recovery-required` — the loop itself could not complete (access, tooling, or substrate broken)
+  and escalated a decision-ready packet. **Not healthy.** Operator action: restore the named
+  capability, then close the escalation item.
+- `policy-obsolete` — the loop's own retirement policy (the retirement condition written in its
+  runbook) tripped, so it proposed its own teardown. **Healthy.** Operator action: approve the
+  teardown, decline it (close the proposal as **Not planned**; the loop keeps running at cadence),
+  or re-cadence it.
+
+## A run outcome is NOT a work-item lifecycle terminal state (CRITICAL)
+
+A **run outcome** describes the LOOP ITERATION. A **terminal state** describes a TICKET — Lisa
+already uses that phrase for work-item lifecycles (`lisa-intake`: "`Blocked` is a valid terminal
+state of the downstream lifecycles"). The two vocabularies never merge in an operator-facing report.
+A healthy cycle that routes a work item to `Blocked` with clarifying questions is
+`candidate-proposed` — it produced something — so it is **never `nothing-needed`**, which is
+reserved for runs that found nothing at all, and **never `recovery-required`**, which means the
+loop itself is broken, not that a work item was blocked.
+
+## No silent exit
+
+Every run — including a trivial early termination — ends by naming exactly one run outcome plus a
+one-line operator summary of what happened, recorded where the status surface can read it —
+there is no silent exit. The shared local substrate is
+`plugins/src/base/scripts/automation-run-record.mjs`, which writes bounded JSONL records under
+`.lisa/automations/runs/<loop-id>.jsonl`. Silence and health must never look identical to an
+operator.
+
+## Never block, always degrade
+
+A missing runbook, an unreadable record surface, or an absent optional dependency **degrades** the
+run — say so in the summary and finish with an outcome — it never crashes the loop, never blocks
+other work, and never leaves the run unreported.
+
+---
+
 Scheduled loops are the busiest machinery in the factory and historically the least explicitly
 contracted: what a loop maintains, what it may do on its own, what it must escalate, and when it
 should stop existing all lived implicitly in each loop's prose. The cost lands on the operator — a

package/plugins/lisa-cursor/rules/base-rules.mdc

@@ -7,6 +7,16 @@ alwaysApply: true
 
 These are mandatory disciplines that apply to every session. Full prose, JIRA dev-status query, ADF templates, etc. live in [reference/base-rules.md](base-rules-reference.mdc).
 
+## Factory Operating Mode
+
+You are factory machinery, not a chat assistant. Three consequences bind every session:
+
+- **Do not pause mid-flow to ask a human whether to proceed.** Handoff happens at the gates — the ready-role flips and intake's adversarial validation — never in the middle of a flow.
+- **Every flow must work headless**: no interactive prompts, idempotent re-runs, clean exits on empty queues. Flows run under native schedulers as often as under a human.
+- **Never weaken a gate to get work through it — fix the work.**
+
+The model these follow from (the four factories, the gate, the loops, the brownfield on-ramp) is [reference/factory-model.md](factory-model-reference.mdc); read it when you need the shape rather than the obligations.
+
 ## Requirement Verification
 
 Treat every request as potentially underspecified. Before starting any work:

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

@@ -5,6 +5,62 @@ alwaysApply: false
 
 # BDD Behavior Contract & E2E Coverage
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## BDD Behavior Contract & E2E Coverage (load-bearing)
+
+**Every frontend work item ships its behavior as Gherkin scenarios with stable IDs, and seals each required scenario-platform obligation with aligned e2e automation in the project's configured runner for that platform.** A frontend change that adds no scenario, or a required scenario-platform obligation with neither a mapped test nor a dated waiver, is a contract violation.
+
+**One vendor-neutral contract, cited by** `lisa-research`, `lisa-acceptance-criteria`, `lisa-task-decomposition`, `lisa-test-strategy`, `lisa-tdd-implementation`, `lisa-implement`, `lisa-codify-verification`, `lisa-verification-lifecycle`, `lisa-spec-conformance`, and `lisa-verify` (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-skill prose).
+
+## Membership
+
+Membership is **surface, not repo name or ticket label**: a work item is frontend-type the moment it adds or changes something a user can observe — a screen, route, component, interaction, visual state, empty/error/loading state, navigation path, or copy a user reads. It applies on every platform the project ships. Backend-only, infrastructure, docs, tooling, and refactors with no user-observable delta are out; a refactor that changes what the user sees is in.
+
+## The contract lives in the repo
+
+Default locations (a project that already has an equivalent contract keeps its own paths and records them in `.lisa.config.json`):
+
+| 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, 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 |
+
+## Scenario shape
+
+Every scenario carries **one stable `@BDD-<DOMAIN>-<NNN>` ID**, the platforms it requires (`@web`, `@ios`, `@android`, … as the project declares them), provenance (design node, ratified decision), and a tracker tag tying it to the work item that introduced or changed it. IDs are never renumbered or reused: behavior that stays user-observably the same keeps its ID through a rewrite; genuinely different behavior gets a new ID and the old one is marked `@superseded`.
+
+Lifecycle tag, exactly one or none:
+
+- **no tag** — ratified and required; it is in the coverage denominator.
+- **`@blocked`** — specified but awaiting a decision or dependency; the *product* does not do this yet.
+- **`@reference-only`** — intentionally not authoritative.
+- **`@superseded`** — replaced by a ratified rule or a newer scenario.
+
+The last three are out of the denominator. Deleting a committed capability to make coverage look better is a violation; mark it, do not drop it.
+
+## What seals a scenario
+
+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
+
+A frontend work item is not done until: (1) every user-facing behavior it adds or changes exists as a Gherkin scenario with a stable ID in the project's behavior contract, traceable to the work item; (2) every required scenario-platform obligation it introduces is either mapped to aligned e2e automation in the project's configured runner for that platform, or carries a dated waiver naming the runner limitation; and (3) the coverage gate passes and the generated matrix and burndown are regenerated and committed in the same PR. **Missing BDD coverage is a verification failure, not a warning** — it blocks completion exactly as a `PARTIAL` spec-conformance verdict does, and it is never demoted to "optional", "if cheap", or a follow-up without a linked build-ready ticket created before merge.
+
+## Bootstrap and degradation
+
+A project with no `bdd/` contract yet is not exempt — the first frontend work item scaffolds the minimum (features dir, coverage map with the project's detected runner→platform mapping, gate + matrix scripts) and covers **its own** behavior. It never backfills the whole app: pre-existing uncovered behavior is recorded as burndown, not treated as this item's blocker. If no e2e runner exists for a required platform at all, record the checked locations and the absence as the reason, exactly as the regression-spec absence path in `verification` does — a silent skip is never one of the exits.
+
+---
+
 Frontend behavior has historically been specified twice and owned nowhere: once as prose acceptance
 criteria on a ticket that closes and disappears, and once as whatever e2e tests someone had time to
 write. Neither survives the work item. The cost lands at verification time — nobody can answer "what

package/plugins/lisa-cursor/rules/blocker-containment-reference.mdc

@@ -5,6 +5,64 @@ alwaysApply: false
 
 # Blocker Containment
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Blocker Containment (load-bearing)
+
+**An `is blocked by` dependency is cleared by one fact only: the blocker's code is present on the branch the dependent will be built from.** A lifecycle status name — `done`, `on-stg`, `on-dev`, `code-review`, or any configured equivalent — is never that fact. It is a label that correlates with the fact in a single-trunk workflow and comes apart from it in a promotion workflow.
+
+**One vendor-neutral contract, cited by** `lisa-repair-intake` (Class A dependency clearing), `lisa-intake-explain` (dependency hold gate), and `lisa-ticket-triage` (Phase 1.5 open-blocker gate) — the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never divergent per-consumer prose.
+
+## Why a status name is the wrong test
+
+Where promotion runs `dev → staging → main`, `main` is the **trailing** branch. A blocker at `On Stg` is merged to `staging` and absent from `main`, so a dependent that builds from `main` does not have it. A blocker in `Code Review` is merged to nothing at all. The two failures are symmetric and both are live in the tree:
+
+- Test too **loosely** (any env-staged `done` clears) and a dependent is dispatched into work whose prerequisite is not on its branch. Nothing goes red; the item moves to `ready`, which is indistinguishable from a repair that worked.
+- Test too **strictly** (only the production terminal clears) and every dependent strands behind a blocker that is already merged where it matters.
+
+Containment is the one predicate that gets both right, because it asks the question the status name was standing in for.
+
+## The predicate
+
+1. **Resolve the dependent's base branch.** Take the dependent's `## Target Backend Environment` and map that exact key forward through `.lisa.config.json` `deploy.branches`, per `derived-branch-plan` and `config-resolution`. **Never read the rendered `Branch Plan` section as input** — `derived-branch-plan` forbids it; a surface needing the base branch derives it again.
+2. **Resolve the blocker's merge commit** — the commit that landed the blocker's PR.
+3. **Test ancestry on the remote:** is that commit an ancestor of the resolved base branch (`git merge-base --is-ancestor <sha> origin/<base>`)?
+4. **Cleared** iff the answer is yes. Otherwise **still blocking**.
+
+## Fail closed
+
+**Never fail open on an unresolvable ancestry check.** Any step that cannot be positively resolved leaves the dependency **blocking**, and the run record says which step failed:
+
+- no linked PR, or a PR that is not merged;
+- the blocker is inaccessible (deleted, cross-org, permission denied) — containment across repositories is not defined;
+- the dependent's environment is not derivable, maps non-uniquely, or maps to a branch absent from the remote;
+- the ancestry query itself fails.
+
+A false negative (left blocked) costs a cycle and is visible. A false positive (dispatched into a missing prerequisite) is invisible and surfaces days later as work begun before its dependency existed. Prefer the visible failure.
+
+## The one carve-out: a blocker with no code
+
+A dependency need not deliver code. A blocker **closed as completed** that positively declares no code deliverable — `Target Backend Environment: None — no runtime behavior change` (doc-only / config-only / type-only), no linked PR, no merge commit — is **cleared**, because there is no artifact whose location could matter.
+
+This requires a **positive determination**, never an absence. "I could not find a PR" is fail-closed under the rule above; "the item declares it ships no code" is this carve-out. Collapsing the two turns the carve-out into a universal bypass.
+
+## Ancestry answers a development question, not a deployment one
+
+This rule requires an ancestry test. `deployed-state-readback` says ancestry is **never** evidence of deployment. Both are correct — they answer different questions:
+
+- **Here:** *is the blocker's code on the branch I will build from?* An `is blocked by` link is a **development** dependency, satisfied once the code is on your base branch. Ancestry is the right test, and waiting for production strands dependents.
+- **There:** *is this thing live?* A commit can be an ancestor of the default branch and never have shipped — a discarded pipeline execution leaves it merged and undeployed. Ancestry is provably insufficient.
+
+Never use this rule's test to answer a "does it already exist in the environment?" question.
+
+## Human override
+
+A human statement on the item that the dependency is satisfied clears it, and outranks a failed containment check. Record it as the reason in the run record. This is the escape hatch for cross-repo and untracked dependencies, and it is the only one. An automation may never synthesize one on its own behalf.
+
+---
+
 An `is blocked by` link is a **development** dependency. It asks one question: *does the dependent have the blocker's code on the branch it will be built from?* This rule makes that the test, replacing the lifecycle-status-name checks that three Lisa surfaces had each grown independently.
 
 It is a **single vendor-neutral contract** consumed by `lisa-repair-intake` (Class A dependency clearing), `lisa-intake-explain` (dependency hold gate), and `lisa-ticket-triage` (Phase 1.5 open-blocker gate). Each cites this slug rather than re-implementing the test, exactly as they cite `leaf-only-lifecycle` and `repo-scope-split`. That is what keeps the three from drifting apart again.

package/plugins/lisa-cursor/rules/claim-archaeology-reference.mdc

@@ -5,6 +5,48 @@ alwaysApply: false
 
 # Claim-Time Archaeology
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Claim-Time Archaeology (load-bearing)
+
+Lisa lifecycles are one-way — a done issue never reopens, so a residual failure comes back as a **new** issue with no visible link to the issue that shipped it. Archaeology recovers that link at claim time: the claiming agent learns it is working on round 2 of a past failure, and what specifically went wrong the first time.
+
+**One vendor-neutral contract, cited by every build-intake arm** (the `leaf-only-lifecycle` / `repo-scope-split` / `rejection-detection` precedent: one shared slug, never three divergent implementations).
+
+## When it runs
+
+In build-intake step 3b, **AFTER the rejection-detection classification and BEFORE the relabel/transition** `$READY → $CLAIMED`. Rejection detection runs first; its classification is an **input** to archaeology — a detected `rejection-reclaim` passes straight through, never re-derived.
+
+## Classify the claimed item
+
+Return exactly one of:
+
+- **`rejection-reclaim`** — taken directly from the `rejection-detection` result. Reuse it; do not re-derive.
+- **`retry-of-done-issue`** — an ancestry signal names a closed done issue whose shipped work this issue exists to fix.
+- **`fresh`** — no ancestor found, signals weak/inconclusive, budget exhausted, or the pass errored. The default and the safe degrade.
+
+## Ancestry signals (summary — full bindings in the reference body)
+
+1. **Tracker metadata** — the typed relations the read skills already parse (Blocks / Blocked by / Relates to / Duplicates / Cloned from, `closingIssuesReferences`, cross-references).
+2. **Text similarity** — tracker search primitives over recently-closed issues touching the same implicated files, ranked by title/label overlap. Lexical only; no embedding machinery exists.
+3. **Git ancestry** — deterministic `git log --follow` / `git blame` / merge-commit queries yielding a parseable `{file, sha, pr, date}` result. Never delegate this to the prose-report `git-history-analyzer` agent.
+
+## Learning-loop exclusion (scan-side)
+
+An artifact this flow produced is **never** an ancestor. Exclude anything carrying `[lisa-learning-drop]`, `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]`, `[lisa-rejection-candidate]`, or `[lisa-archaeology-candidate]` markers, or the `learning:needs-triage` label.
+
+## Cost budget — never block the claim
+
+The pass runs inside a hard budget: `.lisa.config.json` `archaeology.maxSteps` (default **8** tracker/git queries; optional `archaeology.maxSeconds`). Budget exhausted, weak signals, or an exception → classify `fresh` and proceed. Archaeology is a bonus layered on the claim; it **never blocks the claim**. Exceeding the budget degrades to `fresh` — a normal outcome, not an error.
+
+## On `retry-of-done-issue`
+
+Reconstruct what the ancestor's PR shipped (merged PR, review threads, evidence comments) and derive **ONE** candidate learning citing the **delta** between what was done and what this issue proves was needed — routed to `lisa-persist-learning` exactly like the rejection-reflection path. Fallback when that skill is absent: a comment with a visible prose line plus `<!-- [lisa-archaeology-candidate] key=<issue>::<ancestor> -->` (marker-dedupe; re-claims produce no duplicate). `fresh` → no candidate, zero comments.
+
+---
+
 Lisa lifecycles are ONE-WAY — a done issue never reopens, so residual failures come back as NEW issues, and the causal link "issue B exists because issue A was done wrong" is invisible unless someone digs. Reopening terminal issues is out of scope, so claim-time archaeology is the only way to recover that link: at claim time, determine whether the item being claimed is round 2 of a past failure, and if so, what specifically went wrong the first time.
 
 It is a **single vendor-neutral contract** consumed by all three build-intake skills (`lisa-jira-build-intake`, `lisa-github-build-intake`, `lisa-linear-build-intake`). Each vendor arm cites this slug in its claim step rather than growing its own archaeology, exactly as the arms cite `leaf-only-lifecycle`, `repo-scope-split`, and `rejection-detection`. One slug is what keeps an ancestor found on JIRA from being missed on Linear.

package/plugins/lisa-cursor/rules/claim-evidence-mapping-reference.mdc

@@ -5,6 +5,89 @@ alwaysApply: false
 
 # Claim → Evidence Mapping Contract
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## Claim → Evidence Mapping Contract (load-bearing)
+
+**Every claim about the software declares a boundary, and a claim is established only by evidence of
+a kind that reaches that boundary.** Unit tests are a quality prerequisite, not a claim discharger:
+a passing unit `test-run-log` reaches only the **code-unit** boundary. Citing evidence whose *kind*
+does not reach a claim's *boundary* — a unit log offered as proof that a button works in the browser
+— is a contract violation, and a review-rejectable defect.
+
+## The claim-boundary taxonomy (closed set)
+
+Every claim binds to exactly one boundary, and each boundary is discharged only by evidence of the
+kind(s) that reach it. The boundaries and their establishing evidence kinds are seeded verbatim from
+the `verification` rule's artifact-type taxonomy — no new vocabulary is invented here:
+
+- **`code-unit`** — pure-logic behavior in isolation → unit `test-run-log`. Reaches no boundary
+  below it.
+- **`browser`** — user-visible UI behavior → `screenshot`, `recording`. **Never** a unit
+  `test-run-log`.
+- **`http-api`** — request/response contract → `http-transcript`. **Never** a unit `test-run-log`.
+- **`cli`** — command behavior → `cli-output`.
+- **`data`** — persisted state → `db-query-output`, `state-dump`.
+- **`deploy-health`** — a healthy running deployment → `deploy-log`. **Never** any pre-deploy
+  artifact.
+- **`performance`** — latency/throughput/frame timing → `perf-trace` (with methodology).
+- **`standards-compat`** — conformance to an external standard → `cli-output` / `test-run-log` from
+  the compat runner.
+
+## The core inequality
+
+**unit tests ≠ browser behavior ≠ healthy deployment ≠ standards compatibility.** Each is a distinct
+boundary; evidence at one never discharges a claim at another. "Verified" must name the boundary its
+evidence actually reaches, so a report read at the gate states its own limits (`factory-model`
+rule 5).
+
+## Field names (fixed here, made executable later)
+
+A claim carries three fields — `claim_id`, `boundary`, and `required_evidence_kinds` — named here so
+every downstream surface uses one spelling. This ticket only writes the contract down; the schema and
+gate that make these fields executable ship with **BCE-2 (#1836)** — do not assume that surface is
+present in this branch.
+
+## Security buckets (conservative by default)
+
+A security finding is **proven** only with both a reproducer of a reaching kind and a bounded
+impact/exploitability statement; missing either, it renders **unproven** with its reason and **stays
+in the security section** — never auto-demoted to maintenance. The label is one policy point,
+`security.review.unprovenBucket` (default `security-unproven`); the procedure lives in the
+`lisa-security-review` skill.
+
+## Artifact identity (pinned, never assumed)
+
+A claim applies only to the artifact its evidence was collected against. Every verdict pins
+`artifact.head_sha` — the commit the run observed — and every evidence entry pins the
+`artifact_head_sha` in force when it was captured, its `sha256` content digest, and `captured_at`.
+Evidence collected on a pre-merge head is valid for the merge commit **only** when that head is a
+parent of the merge, per the ancestry + deploy-run definition of "what shipped" that
+`lisa-drive-pr-to-merge` already owns — cite it, never write a second one. A mismatched SHA or a
+recomputed digest that disagrees fails loudly, naming both SHAs / the evidence id, and verification
+re-runs against the merged head before completion is declared. Full definition: the reference body.
+
+## Not established (required, never omitted)
+
+A claim with no reaching evidence is **Not established**, and every report says so out loud. Each
+evidence comment and verdict carries a `Not established` section listing what was *not* proved —
+boundaries not exercised, environments not tested, behavior consciously out of scope. It is never
+omitted and never blank: with nothing outstanding it still renders `None outstanding — reviewed`, and
+`not_established_reviewed` attests the list was reviewed even when the list itself is empty. This
+generalizes the required, never-empty `Known limits` field of `lisa-improve-harness`. Full definition
+and operator-voice exemplars: the reference body.
+
+## No behavior change; degrade, never block
+
+This rule is documentation, not a gate: it changes no schema, no skill, and no check. Where a later
+surface it names is not yet installed, cite the boundary a claim reaches and continue — never block
+on the absent surface. Read the contract to someone who has never seen Lisa and they should be able
+to say why a unit-test log does not prove a button works in the browser.
+
+---
+
 Lisa's verification machinery already proves outcomes empirically, but nothing states *which kind of
 evidence establishes which kind of claim*. So a claim about browser-visible behavior, supported only
 by a unit-test log, currently reads as "verified" — the report never names the boundary its evidence

package/plugins/lisa-cursor/rules/claim-time-guards-reference.mdc

@@ -5,6 +5,43 @@ alwaysApply: false
 
 # Claim-Time Guards
 
+> 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 `rules/eager/00-rule-index.md`.
+
+## 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> measures=<work|machine> -->` (match on the marker, never the title). A cron holds no memory between cycles, so the item carries the count.
+
+**Two filters before counting.** Count a marker only when it is `measures=work` — a run terminated by a signal, or whose outcome was `recovery-required`, measures the box and not the item — and only when it was recorded **after the item most recently entered the ready lane**. An unlabelled marker counts as `work`; an unreadable lane history falls back to counting every `work` marker. Both defaults keep the valve shut rather than open (CodySwannGT/lisa#3854).
+
+With **two or more** surviving 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 and it works — a human or a `lisa-repair-intake` cycle with the blocker provably cleared returns it to the queue, which ends the period the old markers describe without deleting them.
+
+---
+
 Two guards that run when build-intake claims a ready item. Both come from acmeorgb'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.

package/plugins/lisa-cursor/rules/config-resolution-reference.mdc

@@ -7,6 +7,103 @@ alwaysApply: false
 
 Lisa is vendor-agnostic. PRDs can be sourced from Notion, Confluence, Linear, GitHub Issues, or JIRA. Tickets can be written to JIRA, GitHub Issues, or Linear. Per-project configuration lives in `.lisa.config.json` at the repo root, with optional `.lisa.config.local.json` overriding on a per-key basis.
 
+
+> The sections between here and the horizontal rule were demoted out of the
+> always-on eager head by CodySwannGT/lisa#3992, verbatim. They are tracker-write
+> and provider mechanics: needed when a flow writes to a tracker or resolves a
+> deploy target, not on every session. The eager head keeps the resolution
+> pointer, the Atlassian identity switch, tracker selection, and repo identity.
+
+## Tracker status vocabulary
+
+**A status transition may target only a status named in the project's configured workflow map** (`jira.workflow.*` for JIRA; the equivalent label/state map for GitHub and Linear). The configured map is the COMPLETE authorized vocabulary — not a starting point.
+
+- **Never adopt statuses discovered from the tracker's live workflow metadata** — transition lists (`getTransitionsForJiraIssue` targets), board columns, status descriptions, or statuses seen on other tickets. A tracker workflow usually contains more statuses than the config names; those extra statuses are not lisa's to use. The live workflow is consulted only to find the transition *id* that reaches a config-named status.
+- **A lifecycle stage with no configured status gets no transition.** If the flow reaches a stage the map does not name (e.g. "PR open awaiting review" when `jira.workflow.review` is unset, or a QA-ready stage with no `qa` mapping), leave the status where it is and record the stage in a comment. Do not pick the nearest-sounding tracker status.
+- **This binds every actor that writes to the tracker** — the lead as much as any subagent. In runtimes where interactively-authenticated MCPs are lead-only, the lead performs the tracker writes for the whole flow; loading an implement/sync skill without the agent definition does not relax this rule.
+
+This is the shared slug for the config-bound-transitions policy (the `leaf-only-lifecycle` precedent: one slug, never divergent per-surface prose). Skills and agent definitions cite it rather than restating it.
+
+## Project rules and learnings
+
+Host-authored project rules live in the fixed, agent-neutral directory
+`.agents/rules/` — not a configurable file. Every agent reaches it through the
+Lisa-managed pointer block in `AGENTS.md`, so it is read once, on demand. A
+project that still carries the retired `.claude/rules/PROJECT_RULES.md` keeps
+it, untouched and authoritative; the pointer names it too. Automated
+learnings never append to host rules: they use the separate machine-managed
+ledger resolved from `.lisa.config.json` — the optional `learnings.file`
+override, else the default `.lisa/PROJECT_LEARNINGS.md`. The ledger lives in the
+cold `.lisa/` tree (never an auto-loaded rules directory) and is consumed only
+through the contract's bounded projection, never read raw wholesale. Both
+writers and budget checks import the executable contract from
+`@codyswann/lisa/learnings`; they must not copy its numeric limits.
+
+## Optional Kane browser provider
+
+Kane is selected only through `verification.browser.kane`: require `enabled: true`, exact version
+`0.6.3`, `cloudUploadApproved: true`, an explicit non-production `allowedEnvironments` entry, a
+Test Manager `projectId`, and a resolved `exploration` mutation policy of `full`. Credentials never
+live in Lisa config. Run `lisa kane probe` before use and invoke only through `lisa-kane-browser`;
+provider/auth/upload/schema failures are tooling failures, not product failures. Kane supplies
+empirical evidence only—native Playwright/Cypress/Maestro remains the regression authority.
+
+## Env → base branch
+
+The `## Target Backend Environment` grammar is durable: human-confirmed values
+are a bare configured key or `Confirmed: <env>`; automation writes either
+`Inferred: <env> — evidence: <title|body|reproduction|hostname>` or
+`Assumption: <env> — remote default branch <branch>`. When no unique environment
+maps to the default branch, use `Assumption: remote default branch <branch>`.
+Human confirmation replaces an automated annotation with a bare key or
+`Confirmed: <env>`. For legacy bare values, use managed draft markers and current
+ticket content only; provider edit history is not required. A marker proves
+automation and requires re-annotation; otherwise unknown provenance with
+conflicting evidence stops for confirmation.
+
+Resolution order is human-confirmed value; validated `Inferred:` evidence; then
+one unambiguous signal from the human-authored title, body, and reproduction
+steps or a URL hostname. Exclude the complete `Target Backend Environment`
+section and other machine-authored metadata/draft blocks from the scan so an
+annotation cannot validate or conflict with itself. Evidence supersedes only an
+`Assumption:`. A signal must be an exact
+`deploy.branches` key as a complete token/hostname label. The sole normalization
+is `prod` ↔ `production` when exactly one is configured; no other aliases exist.
+Conflicting signals stop. Never infer from arbitrary branch text, URL paths or
+query strings, or substrings. With no signals, use the remote default branch and
+record an assumption: include `<env>` only for a unique reverse-map, otherwise
+use the branch-only form without inventing an environment or blocking. Require
+any selected environment mapping and its remote branch to exist.
+A non-integration environment bug is fixed, merged, and verified on that
+environment branch first, then
+forward cherry-picked down to the integration branch via a linked follow-up.
+
+## Env-keyed `done` — promotion completeness
+
+A merged PR's base branch names the environment a change **entered**, never the environments it has
+**reached**. Before writing an env-keyed `done`, walk `deploy.order` from its lowest rung and write
+the highest **contiguously reached** rung at or below the resolved env. A rung is reached only when
+the merge commit is an ancestor of its `deploy.branches` branch
+(`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at or
+below the resolved one, not only the PR's base) **and** that branch's most recent deploy
+**concluded `success`** — read the `conclusion`, never the `status`, because an in-flight deploy has
+a null conclusion and looks identical to a pass. Only a concluded `success` promotes: a null
+conclusion and every other conclusion (`failure`, `cancelled`, `timed_out`, `neutral`, `skipped`,
+`stale`, `action_required`) leave the rung unreached. Where `deploy.order` is absent the ladder is
+the single resolved env; where a branch exposes no deploy surface at all, ancestry alone decides
+that rung.
+
+A hotfix straight to `main` that skipped `staging` therefore resolves to the rung below the gap and
+stays open; the terminal value, and provider-native closure with it, is earned only by a
+promotion-complete merge. The recorded reason always carries all three fields —
+`<first unreached env> (<its branch>) — <condition>`, where the condition is `missing ancestry`,
+`deploy unknown: <run URL or "no concluded run">`, or `deploy concluded <conclusion>: <run URL>`. A
+failing run named without its environment and branch is an incomplete reason. An open back-fill PR
+against a skipped environment branch is outstanding delivery, not branch hygiene.
+
+
+---
+
 This rule is the single source of truth for the `.lisa.config.json` schema, the resolution algorithm, and the dispatch tables every vendor-neutral skill follows.
 
 ## File location and precedence