@codyswann/lisa 4.74.8 → 4.75.0

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

@@ -0,0 +1,301 @@
+# 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 [the rule index](../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/` | per-source-file leaves, regenerated, never hand-edited; static navigation at `docs/bdd-scenario-matrix.md` |
+| Burndown | `docs/e2e-bdd-coverage/` | per-source-file mapping gaps and waivers; static navigation at `docs/e2e-bdd-coverage.md` |
+| Feature JSON | `bdd/reports/v1/features/` | versioned local declarations/evidence; full aggregate remains in runtime `--report` and CI |
+
+## 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
+is this app supposed to do?" without re-reading a year of closed tickets, and "is that behavior
+guarded?" has a different answer shape per platform and per runner. This contract writes both
+answers down once, in the repo, next to the code.
+
+It is a **single vendor-neutral contract** consumed by `lisa-research` (PRDs express frontend
+behavior in a BDD-convertible shape), `lisa-acceptance-criteria` and `lisa-task-decomposition`
+(the contract update and the e2e sealing are explicit obligations on the work item, not implied
+work), `lisa-test-strategy` and `lisa-tdd-implementation` and `lisa-implement` (building a frontend
+item includes both), `lisa-codify-verification` (the verified journey is codified into every runner
+the scenario's platforms require), and `lisa-verification-lifecycle` / `lisa-spec-conformance` /
+`lisa-verify` (the gate is checked, and a miss fails the item). Those skills cite this slug; they do
+not restate it.
+
+## Vendor neutrality is the point
+
+This contract never names a test runner. Projects use Playwright, Cypress, Maestro, Detox, Appium,
+WebdriverIO, XCUITest, Espresso, an in-house harness, or several at once, and that choice is
+project configuration that changes without touching this contract. What the contract fixes is the
+*obligation*: a required scenario-platform pair is sealed by aligned automation **in whatever runner
+the project has configured for that platform**. Any tool named anywhere downstream is an example,
+never a mandate.
+
+The runner→platform mapping is declared once, in the coverage map, and is the only place a tool name
+is authoritative:
+
+```json
+"runnerPlatforms": {
+  "<web-runner>": ["web"],
+  "<device-runner>": ["ios", "android"]
+}
+```
+
+Platform vocabulary is the project's own — a project that ships only web declares only `web`; one
+that ships a desktop or TV surface declares those. The contract cares that each scenario names the
+platforms it requires and that each named platform has a configured runner.
+
+## Coverage map schema
+
+`bdd/coverage-map.json` is the machine-readable half of the contract. Minimum shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "asOf": "<ISO date>",
+  "runnerPlatforms": { "<runner>": ["<platform>", "..."] },
+  "coverageFloor": { "<platform>": "<0-100, an absolute bar checked in enforced mode — not a ratchet, set once and left alone>" },
+  "platformWaivers": [
+    {
+      "scenario": "BDD-DOMAIN-NNN",
+      "platforms": ["<platform>"],
+      "runner": "<runner>",
+      "reason": "why this runner cannot decide this behavior today",
+      "owner": "verification-team",
+      "ticket": "gh-123",
+      "recordedAt": "2026-09-12",
+      "expiresAt": "2026-10-12"
+    }
+  ],
+  "mappings": [
+    {
+      "scenario": "BDD-DOMAIN-NNN",
+      "runner": "<runner>",
+      "platforms": ["<platform>", "..."],
+      "file": "<path to the spec/flow>",
+      "evidence": "<exact string inside that file — the test title or flow name>",
+      "level": "behavioral"
+    }
+  ],
+  "testDiscovery": {
+    "<runner>": {
+      "roots": ["<repo-relative directory>", "..."],
+      "extensions": [".<suffix>", "..."],
+      "ignore": ["<optional repo-relative path prefix>"],
+      "evidence": { "kind": "call-title", "functions": ["test", "it"] }
+    }
+  },
+  "exclusions": [
+    {
+      "file": "<path>",
+      "evidence": "<optional exact title; omit to excuse the whole file>",
+      "reason": "why this test aligns to no product behavior"
+    }
+  ]
+}
+```
+
+The waiver's owner, ticket, and dates are illustrative values: substitute the responsible person
+or team, the real follow-up reference (`gh-123` or `PROJ-123` shape), and a current, bounded
+`YYYY-MM-DD` review window. Name a runner from `runnerPlatforms`; it is required when more than
+one runner covers the waived platform. An expired waiver is rejected, and a waiver is never coverage.
+
+`evidence` is what makes a mapping falsifiable: the gate reads the mapped file and confirms the
+string is still there, so renaming or deleting a test breaks the map loudly instead of leaving a
+scenario silently unguarded.
+
+One behavior may have multiple aligned tests in the same runner. Record each distinct file/evidence
+pair as a mapping; the obligation counts once for traceability, while every test remains separately
+falsifiable and can join to its own execution result. Only an exact repeated mapping is a duplicate.
+
+`testDiscovery` closes the other direction. Validating only what the map DECLARES can never see a
+test file nobody declared, so the gate walks the project's own roots and requires **every test it
+finds to be named by a mapping or excused by an exclusion**. Roots and the evidence grammar are
+per-runner configuration — list every directory, including subflow and helper directories, because
+a directory omitted here is structurally invisible to the gate. Evidence grammars are an allowlist
+of two (`call-title` reads `test("…")`-style declarations and known test modifiers while ignoring
+suite/helper calls such as `test.describe` and `test.step`, and reads titles from curried
+parameterized declarations such as `test.each(table)("title")` and `it.each`; `line-field` reads a leading `name:`
+field), never a project-supplied regular expression, and a template-literal title is used verbatim
+from the source rather than rewritten. A missing block is a defect in enforced mode
+(`discovery-missing`); a malformed one is refused in **every** state (`discovery-invalid`), because
+discovery that silently finds nothing looks exactly like a clean repo.
+
+`exclusions` records tests that deliberately map to nothing — starter templates, source-level
+corroboration — so "unmapped test" stays a meaningful signal. Each entry states a `reason`, and an
+exclusion whose file is gone, whose title was renamed, or that no discovery root covers is
+`exclusion-stale`: a standing claim about nothing, never a permanent excuse.
+
+## The gate
+
+Two commands, wired into the project's script surface and into CI:
+
+1. **Regenerate** — recompute coverage from features + map and write the feature-local matrix,
+   burndown and JSON under `docs/bdd-scenario-matrix/`, `docs/e2e-bdd-coverage/` and
+   `bdd/reports/v1/features/`. Shared entry points contain static guidance. Reportable coverage
+   defects still produce paperwork; the coverage CLI keeps its original failing exit.
+2. **Check** — the CI gate. It fails on contract defects, not on ambition:
+   - a duplicate or malformed scenario ID;
+   - a scenario declaring a platform with no configured runner;
+   - a mapping whose file is missing or whose `evidence` string is gone (stale mapping);
+   - a mapping claiming a platform the scenario does not declare;
+   - an invalid waiver (nonexistent scenario, undeclared platform, already-excluded scenario, a
+     `runner` that does not cover the waived platform under `runnerPlatforms`, or one that masks an
+     existing mapping);
+   - a discovered test named by no mapping and no exclusion, or an exclusion that no longer excuses
+     anything;
+   - a platform sitting below its committed `coverageFloor`;
+   - coverage given back: an obligation mapped at the base revision that nothing maps here;
+   - new behavior nobody mapped or waived.
+
+   Regeneration is never blocked by a reportable coverage defect: `--write` rewrites feature reports whenever a
+   report can be built at all, so a stale evidence string can never hold hostage the paperwork that
+   documents it.
+
+The percentage measures **aligned automation inventory, not the latest run result**. A mapped test
+that currently fails is a red CI check, a separate signal; the map only asserts the automation
+exists and still says what it claimed. Both facts are required — a green gate over a red suite is
+not coverage.
+
+### Coverage floor, not coverage target — and not a ratchet
+
+Projects adopting this contract mid-life start below 100% and must not be blocked by that. The
+committed `coverageFloor` per platform is an **absolute bar** answering "is this platform below it
+right now". Set it once at adoption to the honest measured number (or `0`) and leave it: nothing
+forces it upward, and lowering it needs no ceremony.
+
+What stops coverage sliding backwards is checked directly, per obligation, against the base
+revision — **an obligation that was mapped may not stop being mapped, and new behavior arrives
+mapped or waived**. Giving coverage back is legitimate but takes a recorded route: a complete `retirements`
+record (for a behavior the product no longer has) or a `platformWaivers` entry (for a runner
+that cannot decide it). Gaps that predate the change are burndown, never a
+gate failure — which is what lets a brownfield project adopt `enforced` without first backfilling
+its whole history.
+
+## Waivers versus `@blocked`
+
+These are different failures and must never be conflated:
+
+| | Means | Recorded as |
+|---|---|---|
+| `@blocked` | The **product** does not do this yet — undesigned, undecided, or unbuilt. | Lifecycle tag on the scenario |
+| Waiver | The product may well do it, but this **runner** cannot decide it on this platform today. | Dated entry in `platformWaivers` |
+
+Both leave the denominator, and neither is ever counted as covered: a waiver is a dated IOU, never
+coverage. A waiver names a runner limitation — no camera on
+the simulator, no request interception, a provider sign-in needing a real credential nobody
+provisioned, a backend with no seedable row for the required state — and it carries a date so it can
+be audited for age. When the limitation dies, the waiver is deleted and the automation is written;
+a waiver that outlives its reason is a defect the burndown should surface.
+
+## Scenario identity and change
+
+A stable ID is a promise about *behavior*, not about text:
+
+- The user-observable behavior is unchanged → **keep the ID**, however much the wording, the
+  implementation, or the design node changed.
+- The behavior is genuinely different → **new ID**; mark the old one `@superseded` and leave it in
+  the file. Superseded scenarios are the audit trail for why the product changed.
+- The capability is committed but not yet designed or built → write it now and tag it `@blocked`.
+  Omitting a committed capability makes coverage look better by describing less of the product,
+  which is exactly the failure this contract exists to prevent.
+- IDs are never renumbered or reused. Gaps in the sequence are normal and harmless.
+
+Provenance tags tie a scenario back to its authority (design node, ratified decision, wiki
+requirement) and to the tracker item that introduced or changed it, so `spec-conformance` can walk
+from a requirement to a scenario to a test without guessing.
+
+## Per-flow obligations
+
+| Flow | Obligation |
+|---|---|
+| **Research / PRD** | For frontend scope, user-facing behavior is written as — or in a shape directly convertible to — Given/When/Then scenarios, with the platforms each behavior must hold on. A PRD that describes frontend behavior only as narrative forces the shape to be invented later, inconsistently. |
+| **Plan / decomposition / acceptance criteria** | Each frontend work item's acceptance criteria and Validation Journey name the contract update *and* the e2e sealing as explicit deliverables, with the scenario IDs it will add or change once known. They are line items, not implied work. |
+| **Implement / TDD / test strategy** | Building the item updates `bdd/features` and the coverage map and writes the aligned automation, in the same PR as the behavior. The scenario is the RED test's specification for user-facing behavior. |
+| **Codify verification** | The verified journey is codified into **every runner the scenario's platforms require** — one runner is never a substitute for another, because they guard different platforms of the same behavior. |
+| **Verify / verification-lifecycle / spec-conformance** | Verification confirms scenarios exist for the shipped behavior and the coverage gate passes. A shipped frontend behavior with no scenario, or a required obligation with neither mapping nor waiver, is a verification **failure** — not a warning, not a nit. |
+
+## Bootstrap
+
+A repo with no contract yet, taking its first frontend work item:
+
+1. **Detect runners.** Find the e2e harnesses the project actually has, per the Tool Discovery
+   Process in `verification-lifecycle`. Record which platforms each covers.
+2. **Scaffold the minimum** — `bdd/features/`, `bdd/coverage-map.json` (with `runnerPlatforms` and
+   `testDiscovery` from step 1 — every root each runner's tests actually live in, subflow and helper
+   directories included — and a coverage floor of the current, honest number), the regenerate +
+   check scripts wired into the project's script surface, and the CI invocation of the check.
+   Pre-existing tests that align to no product behavior are recorded as `exclusions` with reasons
+   during this step, never left undisclosed.
+3. **Write only this item's scenarios.** The first item is not a backfill project. Pre-existing
+   uncovered behavior becomes feature-local burndown under `docs/e2e-bdd-coverage/`, and the floor starts where the
+   repo actually is. That is a one-time act, not a recurring one: from here on the floor stays put
+   and what protects each new obligation is the per-obligation check, not the number.
+4. **Seal this item's obligations** and commit the regenerated matrix and burndown with the change.
+
+If a required platform has **no** e2e runner at all, that obligation is never left as a bare `N/A` —
+record it exactly like any other unsealable obligation: a dated `platformWaivers` entry naming the
+locations checked and "no runner configured" as the reason, so the absence is dated, audited for age,
+and visible in the same place every other IOU lives — the same recorded-absence exit the
+regression-spec rule in `verification` allows, made falsifiable. Where the runner could reasonably be
+added, additionally file a linked build-ready follow-up ticket before merge and reference it from the
+waiver's reason. Silence is never an exit.
+
+## Degradation
+
+Missing scaffolding degrades the run, it does not crash it: a project with no contract gets the
+bootstrap path, an unreadable coverage map is reported as a blocker on the work item rather than
+swallowed, and an absent optional runner is recorded as an absence with the locations checked. What
+never degrades is the reporting — an agent that could not evaluate the contract says so explicitly
+and does not report the item as done.

package/plugins/lisa-devin/rules/reference/blocker-containment.md

@@ -0,0 +1,165 @@
+# 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 [the rule index](../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` reading `None — no runtime behavior change: <kind>` (`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.
+
+## The failure this replaces
+
+Before this rule, all three surfaces tested a **status name** and each picked a different threshold, so the same dependency could be simultaneously cleared by one surface and held by another.
+
+`lisa-repair-intake` tested too loosely — any env-staged `done` role cleared the dependency, on the stated reasoning that `On Dev`, `On Stg` and production `Done` all mean *"the blocker's code is merged and deployed to ≥1 environment"*, and that an `is blocked by` link *"is satisfied once the blocker's code is in trunk."* The first clause names the right idea. The second substitutes a weaker one for it: in a `dev → staging → main` promotion workflow, "deployed to ≥1 environment" and "in trunk" are different facts. `main` is the trailing branch, so a blocker at `On Stg` is on `staging` and absent from `main`. A dependent building from `main` was dispatched without it. That surface also cleared on a post-build `review` role, where the code is merged to no branch at all.
+
+`lisa-ticket-triage` tested too strictly — a blocker not at the production terminal raised an automatic `BLOCKED` verdict, stranding dependents behind work already merged where they needed it.
+
+Both are the same defect. **A lifecycle status name is never the test** — not `status:done`, not `status:on-stg`, not `status:on-dev`, and least of all `status:code-review`, where the code is merged to no branch at all. The status name is a **proxy** for branch containment that holds in a single-trunk workflow and breaks in a promotion workflow, and the two surfaces broke in opposite directions because they picked opposite ends of the same bad proxy. Correcting either one alone by moving its threshold re-opens the other's bug — which is why this is one predicate rather than three tuned lists.
+
+Notably, the correct predicate was already in the tree. `lisa-ticket-triage`'s own `DUPLICATE_ALREADY_FIXED` bullet, four lines below its defective gate, already required *"empirical evidence that the canonical fix is present on the relevant base branch. Never emit this verdict from a name/label match alone."* This rule generalizes that sentence to the gate above it.
+
+## The predicate
+
+### 1. Resolve the dependent's base branch
+
+Take the **dependent's** `## Target Backend Environment`, resolve it under the existing grammar (`config-resolution`, `pre-flight-autofill` — human-confirmed wins, then validated `Inferred:`, then `Assumption:`), and map that exact key forward through `.lisa.config.json` `deploy.branches`.
+
+**Never read the rendered `Branch Plan` section as input.** `derived-branch-plan` is explicit that the rendered branches exist for humans and are recomputed for machines: *"The rendered branches are never read as input by any flow, at any phase — a surface that needs the base branch derives it again from the environment."* Reading the rendered section would make a hand-edited ticket able to redirect the containment test.
+
+The key must map uniquely, and the mapped branch must exist on the remote. Neither condition is assumed.
+
+### 2. Resolve the blocker's merge commit
+
+The commit that landed the blocker's PR, obtained through the vendor access layer (`integration-access-layer`), never a direct vendor API call:
+
+- **GitHub** — the merge commit of the PR linked from the blocker issue.
+- **JIRA** — the merge commit of the PR on the blocker's development panel / linked PR records.
+- **Linear** — the merge commit of the PR attached to the blocker Issue.
+
+An unmerged PR has no merge commit and is not a candidate. A blocker with several merged PRs requires **all** of them contained.
+
+### 3. Test ancestry against the remote
+
+```bash
+git fetch origin <base> --quiet
+git merge-base --is-ancestor <blocker-merge-sha> origin/<base>
+```
+
+Exit `0` → contained. Exit `1` → not contained. Any other exit → not computable, which is **not** the same as not contained; both block, but the run record distinguishes them so an operator can tell a genuine dependency from a broken lookup.
+
+### 4. Verdict
+
+**Cleared** iff every resolved merge commit is an ancestor of the resolved base branch. Otherwise **still blocking**.
+
+## Fail closed
+
+**Never fail open on an unresolvable ancestry check.** Each of these leaves the dependency blocking, and each is named distinctly in the run record:
+
+| Condition | Verdict | Run-record reason |
+|---|---|---|
+| Blocker has no linked PR | still blocking | `no-pr` |
+| Linked PR is open or closed unmerged | still blocking | `pr-not-merged` |
+| Blocker inaccessible (deleted, cross-org, permission denied) | still blocking | `blocker-inaccessible` |
+| Dependent's environment not derivable or non-unique | still blocking | `base-branch-underivable` |
+| Mapped branch absent from the remote | still blocking | `base-branch-missing` |
+| Ancestry query errored | still blocking | `containment-not-computable` |
+| Merge commit resolved, not an ancestor | still blocking | `not-contained` |
+
+The asymmetry is deliberate and is the same one the consuming surfaces already state: a false negative (left blocked) costs one cycle and an operator can see it sitting there. A false positive (re-dispatched into a prerequisite that is not on the branch) is **invisible** — the item moves to `ready`, which looks exactly like a repair that worked, and the failure surfaces days later as work that began before its dependency existed. Prefer the visible failure. When in doubt, stay blocked.
+
+## The one carve-out: a blocker that ships no code
+
+Not every dependency delivers code. A decision, a doc change, or a config-only item can legitimately block work and will never have a merge commit on any branch. Requiring containment of a non-existent artifact would strand those dependents permanently — the same bug, in a new place.
+
+A blocker is cleared under this carve-out when **all** of the following hold:
+
+1. it is **closed as completed** (not `not planned` — see `rejection-detection`, where *not planned* is a durable decline);
+2. it **positively declares no code deliverable** — `## Target Backend Environment` reading `None — no runtime behavior change: doc-only` (or `config-only` / `type-only`), per the grammar `derived-branch-plan` already defines;
+3. it has **no linked PR and no merge commit**. Any linked PR requires the normal containment test regardless of what the section declares; an open or unmerged PR remains blocking — the code is the authority over the prose.
+
+This is a **positive determination, never an absence.** "I could not find a PR" is `no-pr` in the fail-closed table above. "The item declares that it ships no code" is this carve-out. Collapsing the two converts a narrow carve-out into a universal bypass, and it is the single most likely way for this rule to be implemented wrongly.
+
+An Epic or container blocker declaring `None — container: state rolls up from children` is **not** covered: resolve containment against its children, or treat it as `blocker-inaccessible` if the children cannot be enumerated.
+
+## Human override
+
+An explicit human statement on the dependent — in the body or in a comment — that the dependency is satisfied clears it, and outranks a failed containment check. The run record names the override and the comment it came from.
+
+This is the sanctioned escape hatch for the cases the predicate genuinely cannot reach: a cross-repository blocker (two repositories have no shared ancestry, so containment is undefined), a dependency on work tracked outside any connected system, or a vendor whose PR linkage is unreadable. It is the **only** escape hatch. An automation may never synthesize one on its own behalf.
+
+## Ancestry here, but never for a deployment question
+
+`deployed-state-readback` states that git ancestry, a merge check and `cdk synth` are never evidence that something is deployed. That is not a contradiction of the predicate above; the two rules answer different questions and each uses the test appropriate to its own.
+
+| Rule | Question | Ancestry |
+|---|---|---|
+| this rule | **Development** — is the blocker's code on the branch I will build from? | Correct and sufficient |
+| `deployed-state-readback` | **Deployment** — is this live? | Provably insufficient |
+
+An `is blocked by` link is satisfied once the code you need is on your base branch; whether it has reached production is irrelevant to whether you can build against it — that is the whole point of the #1112 case this rule preserves. A "this already exists, do not build it" claim is satisfied only by reading the running system back, because a discarded pipeline execution leaves a commit merged and unshipped while `git log` still reports it present.
+
+**Neither test may be used to answer the other's question.** A surface that needs both runs both.
+
+## What this rule does not do
+
+It does not decide **when** a dependency edge should exist, dissolve an edge once satisfied, or govern what a surface does after clearing — re-dispatch, re-validation, and lifecycle transitions remain the consuming skill's business. It governs exactly one question: given an edge, is it satisfied.
+
+**What follows from a verdict now has an owner**, because for a while nothing did and the gap was live: a repair pass ruled a dependency satisfied, moved the state, and left the edge, recording the ruling as a comment — which the next reader never sees, because it parses relations rather than prose. The block re-formed on the next cycle (CodySwannGT/lisa#3472). Measured on this repository: of 11 open `status:blocked` items carrying a parsable `Blocked by #N`, 5 were held behind blockers that were all closed. Feed this rule's verdict to `scripts/blocker-edge-resolution.mjs`, which returns `dissolve` / `keep` / `escalate`; it consumes the containment verdict and never re-derives it.
+
+It also carries no memory of its own prior verdicts. A surface that re-runs this predicate after a human reversed a transition it produced will reach the same answer from the same facts; making that reversal durable is a separate concern belonging to the consuming skill's loop-prevention contract, not to this predicate.