@codyswann/lisa 4.49.0 → 4.50.0

package/plugins/lisa-copilot/hooks/discharge-work-item-gates.sh

@@ -31,8 +31,14 @@ COMMAND="$(printf '%s' "$JSON_INPUT" | jq -r '.tool_input.command // empty' 2>/d
 
 # `gh pr create` opens one; `gh pr edit` is the other way a body comes to carry
 # — or lose — its declaration. Both change the answer to gate 4.
+#
+# `gh pr reopen` is here because a work item can hold more than one pull
+# request, and a reopened one is a named case: it was closed, so nothing has
+# discharged its gates since, and it is now live again with no CI run to reveal
+# that. Its backlink no longer displaces anyone else's, so re-running the
+# discharge for it is free (CodySwannGT/lisa#3916).
 case "$COMMAND" in
-  *"gh pr create"* | *"gh pr edit"*) ;;
+  *"gh pr create"* | *"gh pr edit"* | *"gh pr reopen"*) ;;
   *) exit 0 ;;
 esac
 

package/plugins/lisa-copilot/hooks/parity-safety-net.sh

@@ -26,6 +26,11 @@
 #     divergence: upstream blocks unconditionally; Lisa allows clean-tree resets.
 #     Residual risk (documented, accepted): the dirty check runs in the hook's
 #     cwd at hook time, so a `cd elsewhere && git reset --hard` evades it.
+#   - `git read-tree` with an update flag AND `--reset` while the working tree
+#     is dirty (issue #3978): the plumbing spelling of the same discard, on the
+#     same condition, printing the same remedy. Index-only `read-tree`, and
+#     `read-tree -m -u` without `--reset` (which git itself refuses rather than
+#     clobber a modified file), stay allowed. Lisa-only guard.
 #   - `git rebase --abort`/`--quit` while the in-progress rebase holds
 #     human-made conflict resolutions (AUTO_MERGE discriminator; issue #1956).
 #     Clean or untouched rebase state stays abortable; the apply backend and a
@@ -1819,6 +1824,45 @@ $DESTRUCTIVE_GUIDANCE"
   fi
 fi
 
+# 3a. `git read-tree` with BOTH an update flag and `--reset`, on the same dirty
+#     tree — the plumbing spelling of guard 3 (issue #3978). It resets the index
+#     and writes the result into the working tree, discarding tracked
+#     modifications: the identical destruction, reached through a command that
+#     carries no `--hard` and no `reset` subcommand, so every pattern in
+#     guard 3 misses it. A guard an agent can walk around is a guard that stops
+#     the honest caller and not the one looking for a way through, and this
+#     spelling is strictly worse than the blocked one — it discards WITHOUT
+#     preserving, which is exactly the property guard 3's remedy supplies. Both
+#     refusals therefore print the same $PRESERVE_GUIDANCE, so what they teach
+#     cannot drift apart.
+#
+#     `--reset` is the discriminator, not `-u`, and the pairing is deliberate:
+#
+#     - `read-tree` with no update flag touches the INDEX only and destroys
+#       nothing in the working tree, so a blanket `read-tree` block would be
+#       over-broad.
+#     - `read-tree -m -u` (a merge without `--reset`) is safe by git's own
+#       construction: it REFUSES rather than overwrite a locally modified file
+#       ("entry would be overwritten by merge"). `--reset` is precisely the flag
+#       that switches that refusal off.
+#
+#     So the destructive combination is an update flag AND `--reset` together,
+#     in either order. The update flag is matched in the checkout guard's idiom
+#     so a bundled short option (`-iu`) cannot dodge the anchor, with leading
+#     whitespace required so a `--index-output=/tmp/out-u` style value cannot
+#     read as the flag. Same conditional dirty-tree shape and same accepted
+#     residual risk as guard 3: the probe runs in the hook's cwd at hook time.
+readonly GIT_READ_TREE="${GIT_CMD}read-tree"
+if matches "${GIT_READ_TREE}"'[^;&|]*[[:space:]]--reset([[:space:]]|$)' \
+  && matches "${GIT_READ_TREE}"'[^;&|]*[[:space:]](-[[:alnum:]]*u[[:alnum:]]*|--update)([[:space:]]|=|$)'; then
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1 \
+    && [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+    block "git read-tree -u --reset on a dirty working tree would discard uncommitted changes (commit first, or preserve as below)" "$PRESERVE_GUIDANCE
+
+$DESTRUCTIVE_GUIDANCE"
+  fi
+fi
+
 # 3b. `git rebase --abort` / `--quit` ONLY while human/agent conflict
 #     resolutions exist (issue #1956). `--abort` restores the pre-rebase branch
 #     and discards every resolution; `--quit` deletes the rebase bookkeeping

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

@@ -72,6 +72,18 @@ export const FAMILIES = [
     match: /(^|\/)\.github\/k6\/thresholds\/[^/]+\.json$/,
     kind: "k6",
   },
+  {
+    // #3992. The always-on eager rule tier is concatenated into every session
+    // AND every subagent start, so its byte ceiling is a quality threshold like
+    // any other. `max` because the number is a ceiling: lowering it tightens the
+    // gate and is free, raising it re-authorises context the cleanup removed and
+    // is the change a human has to see. The tier was cut to 26,540 bytes once
+    // and regrew to 201,083 in fourteen weeks with nothing watching it.
+    id: "eager-rules",
+    match: /(^|\/)eager-rules\.thresholds\.json$/,
+    kind: "json-num",
+    direction: "max",
+  },
   {
     id: "lisa-config",
     match: /(^|\/)\.lisa\.config\.json$/,

package/plugins/lisa-copilot/rules/eager/00-rule-index.md

@@ -0,0 +1,79 @@
+# Rule Index — What Exists, and Where to Read It
+
+The rules below are **not loaded**. Each is a full contract that other rules,
+skills, and work items cite **by slug** ("per the `bdd-e2e-coverage` rule").
+When you meet a slug and need the contract behind it, read that file — do not
+re-derive the contract, and do not restate it where you cite it.
+
+Read one when you are doing the thing it governs. Reading none of them is the
+normal case for a session, which is why they are here rather than in your
+context: the eager tier was cut to 26,540 bytes in May 2026 and had regrown to
+201,083 by September, at which point every session and **every subagent** paid
+~50,000 tokens before its first tool call (CodySwannGT/lisa#3992).
+
+Paths are relative to this file.
+
+## Work-item authoring, validation, and lifecycle
+
+| Slug | Read it when | Body |
+|---|---|---|
+| `work-item-definition-of-ready` | authoring or validating a leaf; gates S1–S16 | [../reference/work-item-definition-of-ready.md](../reference/work-item-definition-of-ready.md) |
+| `leaf-only-lifecycle` | applying a lifecycle role, or rolling a parent up | [../reference/leaf-only-lifecycle.md](../reference/leaf-only-lifecycle.md) |
+| `ready-role-filing` | filing any work item (enforced by `block-direct-issue-create.sh`) | [../reference/ready-role-filing.md](../reference/ready-role-filing.md) |
+| `repo-scope-split` | a leaf spans repos; gate S10, decomposition step 1.5 | [../reference/repo-scope-split.md](../reference/repo-scope-split.md) |
+| `derived-branch-plan` | rendering or validating a Branch Plan; gate S19 | [../reference/derived-branch-plan.md](../reference/derived-branch-plan.md) |
+| `control-reachability` | an item names an existing test as a red-before-green control; gate S20 | [../reference/control-reachability.md](../reference/control-reachability.md) |
+| `pre-flight-autofill` | the pre-flight gate returned FAIL on ticket quality | [../reference/pre-flight-autofill.md](../reference/pre-flight-autofill.md) |
+| `blocker-containment` | deciding whether an `is blocked by` dependency is cleared | [../reference/blocker-containment.md](../reference/blocker-containment.md) |
+| `deployed-state-readback` | authoring a ticket asserting something is missing from a running system | [../reference/deployed-state-readback.md](../reference/deployed-state-readback.md) |
+| `prd-definition-of-ready` | authoring or validating a PRD's requirement atoms | [../reference/prd-definition-of-ready.md](../reference/prd-definition-of-ready.md) |
+| `prd-lifecycle-rollup` | rolling a PRD up from its generated top-level work | [../reference/prd-lifecycle-rollup.md](../reference/prd-lifecycle-rollup.md) |
+| `usage-accounting` | writing the managed `## Lisa Usage` section on an artifact | [../reference/usage-accounting.md](../reference/usage-accounting.md) |
+
+## Build-intake claim time
+
+| Slug | Read it when | Body |
+|---|---|---|
+| `rejection-detection` | claiming a ready item (step 3b, before the relabel) | [../reference/rejection-detection.md](../reference/rejection-detection.md) |
+| `claim-archaeology` | claiming a ready item, after rejection detection | [../reference/claim-archaeology.md](../reference/claim-archaeology.md) |
+| `claim-time-guards` | claiming a ready item: already-implemented, two-failed-attempts | [../reference/claim-time-guards.md](../reference/claim-time-guards.md) |
+
+## Coverage and evidence contracts
+
+| Slug | Read it when | Body |
+|---|---|---|
+| `bdd-e2e-coverage` | the work item adds or changes a user-observable surface | [../reference/bdd-e2e-coverage.md](../reference/bdd-e2e-coverage.md) |
+| `reset-seed-coverage` | the work item adds or changes persistent state | [../reference/reset-seed-coverage.md](../reference/reset-seed-coverage.md) |
+| `claim-evidence-mapping` | citing evidence for a claim, or reviewing evidence someone cited | [../reference/claim-evidence-mapping.md](../reference/claim-evidence-mapping.md) |
+| `observability-audit` | running the `lisa-monitor` audit-and-file arm | [../reference/observability-audit.md](../reference/observability-audit.md) |
+| `readiness-rubric` | judging whether an unattended fleet may run in a repository | [../reference/readiness-rubric.md](../reference/readiness-rubric.md) |
+
+## Design
+
+| Slug | Read it when | Body |
+|---|---|---|
+| `design-value-binding` | implementing a UI surface in a project with a configured design source | [../reference/design-value-binding.md](../reference/design-value-binding.md) |
+| `design-source-of-truth` | a change touches any UI surface | [../reference/design-source-of-truth.md](../reference/design-source-of-truth.md) |
+
+## Dependencies
+
+| Slug | Read it when | Body |
+|---|---|---|
+| `dependency-trust-classes` | adding or major-upgrading a material dependency | [../reference/dependency-trust-classes.md](../reference/dependency-trust-classes.md) |
+| `dependency-decision-records` | adding, upgrading, or removing a material dependency | [../reference/dependency-decision-records.md](../reference/dependency-decision-records.md) |
+| `dependency-internalization-kit` | removing, replacing, or internalizing a dependency | [../reference/dependency-internalization-kit.md](../reference/dependency-internalization-kit.md) |
+
+## Process, review, and access
+
+| Slug | Read it when | Body |
+|---|---|---|
+| `automation-runbook-contract` | registering a loop, or ending any flow with its run outcome | [../reference/automation-runbook-contract.md](../reference/automation-runbook-contract.md) |
+| `convergent-review` | reviewing a PR or resolving review findings | [../reference/convergent-review.md](../reference/convergent-review.md) |
+| `credential-substrate-precedence` | writing or editing an `*-access` skill | [../reference/credential-substrate-precedence.md](../reference/credential-substrate-precedence.md) |
+| `promotion-contract` | implementing a learnings-ladder promotion ticket | [../reference/promotion-contract.md](../reference/promotion-contract.md) |
+| `documentation-source-paths` | moving, absorbing, or deleting a docs-like directory | [../reference/documentation-source-paths.md](../reference/documentation-source-paths.md) |
+| `project-learnings` | you need the learnings ledger's entry schema and field semantics | [../reference/project-learnings.md](../reference/project-learnings.md) |
+| `factory-model` | you need the shape of the factory model, not its obligations | [../reference/factory-model.md](../reference/factory-model.md) |
+
+The obligations that follow from `factory-model` are in `base-rules`, which is
+eager. This entry is the exposition behind them.

package/plugins/lisa-copilot/rules/eager/base-rules.md

@@ -2,6 +2,16 @@
 
 These are mandatory disciplines that apply to every session. Full prose, JIRA dev-status query, ADF templates, etc. live in [reference/base-rules.md](../reference/base-rules.md).
 
+## 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](../reference/factory-model.md); 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-copilot/rules/eager/config-resolution.md

@@ -30,95 +30,8 @@ This applies before declaring connection state, before running any `acli jira *`
 
 Project tracker (`jira` / `github` / `linear`) is read from `.lisa.config.json` `tracker`. Vendor-neutral skills MUST dispatch through the configured tracker, never infer it from arguments. Missing `tracker` → stop and instruct the user to run the matching `/lisa:setup:*` skill.
 
-## 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.
-
 ## Repo identity
 
 `repo:<name>` is the canonical label for which repo a work item belongs to. Resolve current-repo identity in this priority order: `.lisa.config.local.json` `repo` → `.lisa.config.json` `repo` → `.lisa.config.json` `github.repo` → `basename -s .git "$(git remote get-url origin)"`. If none resolve, stop with a clear error.
 
-## 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.
-
-Full reference: [reference/config-resolution.md](../reference/config-resolution.md).
+Full reference (tracker status vocabulary, project rules and learnings, the optional Kane provider, the `Target Backend Environment` grammar, and env-keyed `done` promotion completeness): [reference/config-resolution.md](../reference/config-resolution.md).

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

@@ -1,5 +1,102 @@
 # 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-copilot/rules/reference/bdd-e2e-coverage.md

@@ -1,5 +1,61 @@
 # 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-copilot/rules/reference/blocker-containment.md

@@ -1,5 +1,63 @@
 # 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-copilot/rules/reference/claim-archaeology.md

@@ -1,5 +1,47 @@
 # 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.