@codyswann/lisa 4.48.0 → 4.50.0

package/plugins/src/base/hooks/block-direct-issue-create.sh

@@ -494,6 +494,82 @@ project_dir = os.environ.get("LISA_GUARD_PROJECT_DIR", "")
 OVERRIDE_NAME = "LISA_ALLOW_DIRECT_ISSUE_CREATE"
 HUMAN_GATE_MARKER = "[lisa-human-gate]"
 
+# Decoration a hold declaration may sit behind, and nothing more: whitespace,
+# blockquote arrows, list bullets or numbers, emphasis, an opening HTML
+# comment. One character class plus two optional groups, deliberately not a
+# nested quantifier — this runs over untrusted issue bodies.
+HUMAN_GATE_DECORATION = re.compile(r"^[ \t>*_+#-]*(?:\d+[.)][ \t]*)?(?:<!--[ \t]*)?[ \t]*")
+HUMAN_GATE_FENCE = re.compile(r"```.*?```", re.DOTALL)
+HUMAN_GATE_CODE_SPAN = re.compile(r"`[^`\n]*`")
+
+
+def declares_human_gate(text):
+    """Whether a text DECLARES a hold rather than mentioning one.
+
+    The comment this replaces said the marker is matched anywhere because it
+    "has no other meaning, so its presence in the title or body IS the
+    declaration". That was true when written and is false now: the marker
+    acquired a second meaning -- being discussed -- the moment the feature
+    became something people file tickets about, and a ticket about the marker
+    then declares a hold on itself (CodySwannGT/lisa#3815).
+
+    A declaration is POSITIONAL: the marker leads its line, behind at most the
+    decoration above, with fenced blocks and inline code spans removed first
+    because that is how the marker is written ABOUT. The same rule the intake
+    matcher applies, so the two surfaces cannot disagree about one body.
+
+    NOTE the direction here differs from the intake matcher's. There a match
+    HOLDS an item, so a false positive parks work. Here a match ADMITS a
+    filing, so a false positive is a hole -- which makes this the tightening
+    direction on both sides at once.
+
+    Args:
+        text: Any candidate text -- one argv value, a body file, a payload.
+
+    Returns:
+        True when some line of the text declares a hold.
+    """
+    if not text:
+        return False
+    body = HUMAN_GATE_CODE_SPAN.sub("", HUMAN_GATE_FENCE.sub("", str(text)))
+    for line in body.split("\n"):
+        if HUMAN_GATE_DECORATION.sub("", line, count=1).startswith(
+            HUMAN_GATE_MARKER
+        ):
+            return True
+        if _comment_carries_marker(line):
+            return True
+    return False
+
+
+def _comment_carries_marker(line):
+    """Whether an HTML comment on this line carries the marker.
+
+    The second accepted form, and the one this guard needs most: its inputs
+    are not markdown documents. A `--body` value is a single line, and a shell
+    script writes its declaration as `# <!-- ... -->`, so a purely
+    line-leading rule would refuse two declarations people have already
+    written -- both of which are in this repository's own test corpus.
+
+    It is not a loosening. An HTML comment is invisible when rendered, so
+    nobody wraps one around the marker in order to TALK about it; a quotation
+    has to be visible to be a quotation. Measured over this repository's 42
+    matching issue bodies, adding this branch changes not one verdict.
+
+    Args:
+        line: One line of text.
+
+    Returns:
+        True when some comment on the line contains the marker.
+    """
+    segments = line.split("<!--")
+    for segment in segments[1:]:
+        close = segment.find("-->")
+        inside = segment if close == -1 else segment[:close]
+        if HUMAN_GATE_MARKER in inside:
+            return True
+    return False
+
 # ---------------------------------------------------------------------------
 # WHY THIS IS A TOKEN SCAN AND NOT A PROGRAM RESOLVER
 #
@@ -580,7 +656,7 @@ LABEL_FLAGS = {"--label", "--labels", "--add-label", "--status", "--state"}
 #   None — container: state rolls up from children
 #
 # It is a marker with no other meaning, so it is matched wherever the payload
-# reaches — exactly the asymmetry `HUMAN_GATE_MARKER` gets, and for the same
+# reaches — the asymmetry `HUMAN_GATE_MARKER` gets, and for the related
 # reason. Reading the declaration the writer already emits is also what keeps
 # the guard and the skill from drifting apart a second time: there is one
 # string, defined in one rule, and both read it.
@@ -1223,7 +1299,7 @@ def text_declares_readiness(text):
     Returns:
         True when the text declares build-ready or a human gate.
     """
-    if HUMAN_GATE_MARKER in text:
+    if declares_human_gate(text):
         return True
     for role in (ready_role, upstream_ready_role, default_ready_role):
         if not role:
@@ -1267,7 +1343,7 @@ def scope_declaration(text, state_role_ok):
     Returns:
         True when the text carries a whole-scope declaration.
     """
-    if HUMAN_GATE_MARKER in text:
+    if declares_human_gate(text):
         return True
     return bool(state_role_ok and LIFECYCLE_ROLE_READY.search(text))
 
@@ -1497,20 +1573,23 @@ def declares_readiness(raw_args, roles, extra="", state_role_ok=False):
             candidates = [part.strip().strip("'\"") for part in raw.split(",")]
             if role in candidates:
                 return True
-    # The human-gate marker is matched anywhere, and that asymmetry is
-    # deliberate: it is a marker with no other meaning, so its presence in the
-    # title or body IS the declaration. The build-ready role is an ordinary
-    # string that appears in prose about the queue all the time.
-    if HUMAN_GATE_MARKER in " ".join(args):
+    # Checked per ARGV VALUE rather than against `" ".join(args)`, and that is
+    # what makes the positional rule mean anything here. Joining first destroys
+    # position: after a join, no value's line start survives except the first
+    # argument's, so "the marker leads its line" would be decided by argument
+    # order. A `--title` value is its own single line, which is exactly the
+    # unit the rule is about -- and titles must keep being read, since this
+    # guard reads them and the intake matcher does not.
+    if any(declares_human_gate(value) for value in args):
         return True
     for path in body_file_paths(args):
         try:
             with open(path, encoding="utf-8", errors="replace") as handle:
-                if HUMAN_GATE_MARKER in handle.read():
+                if declares_human_gate(handle.read()):
                     return True
         except OSError:
             continue
-    if extra and HUMAN_GATE_MARKER in extra:
+    if declares_human_gate(extra):
         return True
     # The state-based path. Scoped by `state_role_ok` rather than checked
     # unconditionally, so this adds a compliant command where none existed and

package/plugins/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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