@codyswann/lisa 3.33.8 → 3.35.0

package/plugins/lisa-copilot/scripts/intake-prework-denominator.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * Pre-work denominator for build-queue intake scanners.
+ *
+ * A build-intake cycle that reports an empty lane is only as trustworthy as the
+ * set of lanes it swept. Sweeping by lane NAME (`Backlog`, `Todo`, `Ready`)
+ * omits every pre-work lane a team invented — most commonly a `Blocked` lane,
+ * which is not a distinct Linear state type at all: teams model it as
+ * `unstarted`, i.e. work that was never started. Items parked there carry a
+ * written blocker that nothing ever re-reads, so the lane reads as terminal
+ * while it is in fact a queue.
+ *
+ * This module fixes both halves: lanes are selected by TYPE, never by name, and
+ * the swept set is reported alongside the total so a wrong denominator is
+ * visible on inspection instead of silent forever.
+ */
+
+/** Lane types that hold work which has not started. Both belong to intake. */
+export const PRE_WORK_LANE_TYPES = Object.freeze(["backlog", "unstarted"]);
+
+/** Loop ids whose `nothing-needed` runs must state their denominator. */
+export const DENOMINATOR_REQUIRED_LOOP_IDS = Object.freeze(["intake-tickets"]);
+
+/**
+ * Vendor lane-type vocabularies normalized onto Linear's five-value type set.
+ * JIRA exposes the same idea as `statusCategory` (key or display name); GitHub
+ * has no type field at all, so its callers pass a type explicitly.
+ */
+const LANE_TYPE_ALIASES = Object.freeze({
+  backlog: "backlog",
+  unstarted: "unstarted",
+  started: "started",
+  completed: "completed",
+  canceled: "canceled",
+  cancelled: "canceled",
+  new: "unstarted",
+  indeterminate: "started",
+  done: "completed",
+  "to do": "unstarted",
+  "in progress": "started",
+});
+
+/**
+ * Map a vendor lane type onto the normalized vocabulary.
+ *
+ * @param {unknown} type
+ * @returns {string | null} normalized type, or null when unrecognized
+ */
+export function normalizeLaneType(type) {
+  if (typeof type !== "string") {
+    return null;
+  }
+  return LANE_TYPE_ALIASES[type.trim().toLowerCase()] ?? null;
+}
+
+/**
+ * @param {unknown} type
+ * @returns {boolean} whether this lane holds not-yet-started work
+ */
+export function isPreWorkLaneType(type) {
+  const normalized = normalizeLaneType(type);
+  return normalized !== null && PRE_WORK_LANE_TYPES.includes(normalized);
+}
+
+/**
+ * @param {unknown} lane
+ * @returns {{ name: string, type: string | null, count: number, position: number } | null}
+ */
+function normalizeLane(lane) {
+  if (!lane || typeof lane !== "object") {
+    return null;
+  }
+  const name = String(lane.name ?? "").trim();
+  if (name.length === 0) {
+    return null;
+  }
+  const rawCount = Number(lane.count ?? 0);
+  const rawPosition = Number(lane.position ?? Number.POSITIVE_INFINITY);
+
+  return {
+    name,
+    type: normalizeLaneType(lane.type ?? lane.statusCategory),
+    count: Number.isFinite(rawCount) && rawCount > 0 ? Math.trunc(rawCount) : 0,
+    position: Number.isFinite(rawPosition)
+      ? rawPosition
+      : Number.POSITIVE_INFINITY,
+  };
+}
+
+/**
+ * @param {{ position: number, name: string }} left
+ * @param {{ position: number, name: string }} right
+ * @returns {number}
+ */
+function compareLanes(left, right) {
+  if (left.position !== right.position) {
+    return left.position - right.position;
+  }
+  return left.name.localeCompare(right.name);
+}
+
+/**
+ * Select every lane holding not-yet-started work, by type.
+ *
+ * Deliberately name-blind: a team that adds `Blocked`, `Triaged`, or `Icebox`
+ * as an `unstarted` state gets it swept without a code change, and no hardcoded
+ * roster can fall behind the board.
+ *
+ * @param {readonly unknown[]} lanes
+ * @returns {readonly {name: string, type: string, count: number, position: number}[]}
+ */
+export function selectPreWorkLanes(lanes) {
+  return (Array.isArray(lanes) ? lanes : [])
+    .map(normalizeLane)
+    .filter(lane => lane !== null && isPreWorkLaneType(lane.type))
+    .sort(compareLanes);
+}
+
+/**
+ * Build the denominator a scanner must report with its verdict.
+ *
+ * `totalOpen` is the count of open items on the queue, independent of lanes —
+ * supplying it is what makes an omitted lane arithmetically visible.
+ *
+ * @param {{ lanes?: readonly unknown[], totalOpen?: number }} input
+ * @returns {{
+ *   swept: readonly {name: string, type: string, count: number}[]
+ *   omitted: readonly {name: string, type: string | null, count: number}[]
+ *   sweptCount: number
+ *   totalOpen: number
+ *   unsweptCount: number
+ * }}
+ */
+export function buildIntakeDenominator(input = {}) {
+  const normalized = (Array.isArray(input.lanes) ? input.lanes : [])
+    .map(normalizeLane)
+    .filter(lane => lane !== null)
+    .sort(compareLanes);
+  const swept = normalized.filter(lane => isPreWorkLaneType(lane.type));
+  const omitted = normalized.filter(lane => !isPreWorkLaneType(lane.type));
+  const sweptCount = swept.reduce((total, lane) => total + lane.count, 0);
+  const laneTotal = normalized.reduce((total, lane) => total + lane.count, 0);
+  const rawTotalOpen = Number(input.totalOpen);
+  const totalOpen =
+    Number.isFinite(rawTotalOpen) && rawTotalOpen >= 0
+      ? Math.trunc(rawTotalOpen)
+      : laneTotal;
+
+  return {
+    swept: swept.map(({ name, type, count }) => ({ name, type, count })),
+    omitted: omitted.map(({ name, type, count }) => ({ name, type, count })),
+    sweptCount,
+    totalOpen,
+    unsweptCount: Math.max(totalOpen - sweptCount, 0),
+  };
+}
+
+/**
+ * Render the denominator for a non-technical operator.
+ *
+ * @param {ReturnType<typeof buildIntakeDenominator>} denominator
+ * @returns {string}
+ */
+export function formatIntakeDenominator(denominator) {
+  const lanes = denominator?.swept ?? [];
+  const listed =
+    lanes.length > 0
+      ? lanes.map(lane => `${lane.name} (${lane.count})`).join(", ")
+      : "no pre-work lanes found";
+
+  return `Looked in every lane holding work that has not started — ${listed} — ${denominator.sweptCount} items checked out of ${denominator.totalOpen} still open.`;
+}
+
+/**
+ * Render the full operator-readable one-liner for a dry build lane.
+ *
+ * @param {ReturnType<typeof buildIntakeDenominator>} denominator
+ * @param {{ queue?: string }} [context]
+ * @returns {string}
+ */
+export function summarizeDryLane(denominator, context = {}) {
+  const queue =
+    typeof context.queue === "string" && context.queue.trim().length > 0
+      ? ` on ${context.queue.trim()}`
+      : "";
+
+  return `Nothing ready to build${queue}. ${formatIntakeDenominator(denominator)}`;
+}
+
+/**
+ * @param {unknown} loopId
+ * @param {unknown} outcome
+ * @returns {boolean} whether this run must carry a denominator
+ */
+export function requiresDenominator(loopId, outcome) {
+  return (
+    outcome === "nothing-needed" &&
+    DENOMINATOR_REQUIRED_LOOP_IDS.includes(String(loopId ?? "").trim())
+  );
+}
+
+/**
+ * @param {unknown} denominator
+ * @returns {string | null} the reason it is unusable, or null when valid
+ */
+function findDenominatorDefect(denominator) {
+  if (!denominator || typeof denominator !== "object") {
+    return "no denominator was supplied";
+  }
+  if (!Array.isArray(denominator.swept) || denominator.swept.length === 0) {
+    return "it names no swept lanes";
+  }
+  if (!Number.isInteger(denominator.sweptCount)) {
+    return "its swept count is not a whole number";
+  }
+  if (!Number.isInteger(denominator.totalOpen)) {
+    return "its open-item total is not a whole number";
+  }
+  if (denominator.sweptCount > denominator.totalOpen) {
+    return "it claims to have swept more items than are open";
+  }
+  return null;
+}
+
+/**
+ * Refuse to record a dry build lane that does not say what it looked at.
+ *
+ * Thirty-one consecutive cycles reported an empty lane against a queue holding
+ * unswept pre-work rows. Every record was honest and every conclusion was
+ * false, because none of them stated a denominator. This turns that silent
+ * wrong answer into a loud one.
+ *
+ * @param {{ loopId?: unknown, outcome?: unknown, denominator?: unknown }} input
+ * @throws {Error} when a denominator is required and missing or malformed
+ */
+export function assertDenominatorReported(input = {}) {
+  if (!requiresDenominator(input.loopId, input.outcome)) {
+    return;
+  }
+  const defect = findDenominatorDefect(input.denominator);
+  if (defect === null) {
+    return;
+  }
+
+  throw new Error(
+    `A "nothing-needed" run for loop "${String(input.loopId).trim()}" must state the lanes it swept, and ${defect}. ` +
+      `Pass a denominator built by buildIntakeDenominator() so an omitted lane is visible instead of silent.`
+  );
+}

package/plugins/lisa-copilot/skills/lisa-github-build-intake/SKILL.md

@@ -110,7 +110,7 @@ The only legitimate reasons to stop early:
 
 - Missing repo or required configuration. Surface the missing value and exit.
 - Label namespace not adopted (no issue carries any of `$READY` / `$CLAIMED` / `$DONE`). Surface a label-convention error and exit (this is setup, not a normal idle cycle — see "Adoption" at the bottom).
-- Empty ready set. Exit cleanly with `"No GitHub issues labeled $READY in <org>/<repo>. Nothing to do."`
+- Empty pre-work set. Exit cleanly on the denominator-stated summary from `summarizeDryLane` — which names every lane swept, its count, and the open total. A bare "nothing to do" is not an acceptable exit: it is indistinguishable from a wrong denominator (#2657).
 
 ## Lifecycle assumed
 
@@ -166,7 +166,57 @@ gh label list --repo <org>/<repo> --json name \
       '[.[] | .name | select(. == $r or . == $c or (. as $n | $d | index($n)))] | length'
 ```
 
-If none of the configured role labels exist on the repo → label convention not adopted, surface a setup error and exit. If the role labels exist but none are `$READY` on any open issue matching the resolved assignee filter (or any open issue when the filter is empty) → genuinely empty queue, exit cleanly with `"No GitHub issues labeled $READY. Nothing to do."`
+If none of the configured role labels exist on the repo → label convention not adopted, surface a setup error and exit.
+
+#### 2a. Sweep every pre-work lane, and state the denominator
+
+GitHub Issues has no state-type field, so labels are the only lane available here — a constraint of
+GitHub's data model, not a preference (see "Why labels" above). That makes the omission risk
+*higher*, not lower: there is no `type` to fall back on, so the pre-work set must be derived from
+**configured roles**, never from a hardcoded roster of label names. The pre-work lanes are:
+
+- the configured `$READY` label — the human-flipped lane, worked first;
+- the configured `$BLOCKED` label (`github.labels.build.blocked`) — items that were *never started*,
+  each carrying a written blocker that nothing re-read until Phase 2.5;
+- open issues carrying **no** build role label — which this scanner must see anyway in order to
+  determine and stamp their repo.
+
+Count each lane and the repo's **total open** count (`gh issue list --state open --limit 1000 --json
+number | jq length`), then build the denominator with the shared helper — GitHub callers pass the
+lane type explicitly, since there is none to read:
+
+```text
+buildIntakeDenominator({ lanes: [{name: "$READY", type: "unstarted", count: <n>},
+                                 {name: "$BLOCKED", type: "unstarted", count: <n>},
+                                 {name: "(no role label)", type: "backlog", count: <n>},
+                                 {name: "$CLAIMED", type: "started", count: <n>}, …],
+                         totalOpen: <open issue count> })
+summarizeDryLane(denominator, { queue: "<org>/<repo>" })
+```
+
+Every candidate outside `$READY` must clear Phase 2.5 before it is treated as a candidate at all. If
+nothing survives, exit on the denominator-stated summary from `summarizeDryLane` — never a bare
+"nothing to do". The run recorder rejects a dry build-intake run that does not name what it swept
+(see `automation-runbook-contract`).
+
+#### 2a.1 Re-probe the blockers instead of inheriting them
+
+A blocker is a **claim with a timestamp, not a fact** — it goes stale the moment its condition comes
+true, and nothing re-read one before this phase. For each `$BLOCKED` candidate:
+
+1. **Human gate first, and it is absolute.** An issue carrying the configured human-needed label
+   (`github.labels.build.human_needed`, default `human-needed`) or a `[lisa-human-gate]` marker in
+   its body is **never** auto-selected, whatever any probe says.
+2. **Extract the stated discharge condition**, then **probe it**. Machine-testable conditions — a
+   version on trunk, a published package, a CI run history, an advisory's patched status — rot
+   fastest and are cheapest to check. A human decision is not machine-testable; leave it.
+3. **Classify with `classifyPreWorkCandidate(...)`** from `scripts/intake-blocker-reprobe.mjs`. A
+   discharge with no recorded evidence is not a discharge, and neither is a candidate nothing
+   probed this cycle — the helper refuses both.
+4. **Record the result on the issue either way** via `formatReprobeNote(...)` as a comment, so the
+   next cycle reads the answer rather than re-deriving it. Keep it idempotent.
+5. **On `selectable: true`**, relabel `$BLOCKED → $READY` with the discharging evidence in the same
+   comment, and treat it as an ordinary candidate. On anything else, leave it where it is.
 
 #### 2b. Lifecycle-label trust resolution (bot-authored labels are not signals)
 
@@ -251,7 +301,7 @@ GitHub Issues live in one repo by definition, so the scanned repo's issues are u
    - **Container visibility is allowed.** A multi-repo Epic / Story / Spike may legitimately carry multiple `repo:<name>` labels for operator visibility. Do not split or claim it here; leave the repo markers intact and fall through to the leaf-only gate, which repairs the stale build-ready label instead of dispatching the container.
    - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
    - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
-4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the ready set is exhausted — exit cleanly with `"No ready issues for repo <current>. Nothing to do."`.
+4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the candidate set is exhausted — exit cleanly on the denominator-stated summary, naming the current repo alongside the swept lanes.
 
 #### 3a. Leaf-only claim gate (repair containers)
 

package/plugins/lisa-copilot/skills/lisa-intake/SKILL.md

@@ -126,7 +126,7 @@ matches the mode this cycle ran in: **`intake-prd`** (PRD-side dispatch) or **`i
 
 | This cycle's exit path | Run outcome |
 |---|---|
-| Empty `Ready` set — the idle case (step 3), nothing to claim | `nothing-needed` |
+| Empty pre-work set — the idle case (step 3), nothing to claim. **Must state its denominator** (see below) | `nothing-needed` |
 | A PRD routed to `Blocked` (clarifying questions) or `Ticketed`; a build ticket claimed and dispatched | `candidate-proposed` |
 | A build cycle that shipped and verified (merged PR + evidence), or a shipped PRD moved to `verified` | `change-proved` |
 | A protected deployment (or other autonomy boundary the lifecycle hits) waiting on a human approval | `approval-requested` |
@@ -151,6 +151,22 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
   --runbook .lisa/automations/intake-tickets.runbook.md [--ref <item-url>]...
 ```
 
+**A dry build lane must say what it looked in.** A `nothing-needed` run on `intake-tickets`
+additionally passes `--denominator` — the JSON from `buildIntakeDenominator()` in
+`scripts/intake-prework-denominator.mjs` — and the recorder **refuses the row without it**. This is
+not decoration: 31 consecutive cycles reported a dry lane against a queue holding 61 unswept
+pre-work rows, and every one of those records was honest. A missing row is noisy on inspection; a
+wrong denominator is silent forever and looks exactly like a healthy dry queue. Stating the swept
+set is what turns the silent wrong answer into an inspectable one (#2657).
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id intake-tickets --outcome nothing-needed \
+  --summary "Nothing ready to build on team ENG. Looked in every lane holding work that has not started — Backlog (20), Todo (17), Ready (2), Blocked (61) — 100 items checked out of 343 still open." \
+  --denominator "$DENOMINATOR_JSON" \
+  --runbook .lisa/automations/intake-tickets.runbook.md
+```
+
 If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
 `plugins/lisa/scripts/automation-run-record.mjs` or the source
 `plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never

package/plugins/lisa-copilot/skills/lisa-jira-build-intake/SKILL.md

@@ -85,7 +85,7 @@ The only legitimate reasons to stop early:
 
 - Missing project key / JQL or required configuration. Surface the missing value and exit.
 - Workflow misconfigured (pre-flight check finds `$CLAIMED` or `$DONE` not reachable, or `$READY` status absent). Surface and exit.
-- Empty ready set. Exit cleanly with `"No tickets with Status=$READY. Nothing to do."`
+- Empty pre-work set. Exit cleanly on the denominator-stated summary from `summarizeDryLane` — which names every lane swept, its count, and the open total. A bare "nothing to do" is not an acceptable exit: it is indistinguishable from a wrong denominator (#2657).
 
 ## Lifecycle assumed
 
@@ -130,11 +130,59 @@ JQL="${BASE_JQL} ORDER BY priority DESC, created ASC"
 
 4. Confirm the configured Atlassian site by invoking `lisa-atlassian-access` `operation: list-sites` (it enforces connection match against `.lisa.config.json`).
 
-### Phase 2 — Find ready tickets
+### Phase 2 — Sweep every pre-work status by CATEGORY
 
-Invoke `lisa-atlassian-access` `operation: search-issues jql: "<JQL>"`. Capture each ticket's: key, summary, issue type, priority, assignee, parent (epic), labels, components.
+**Sweep by `statusCategory`, never by a roster of status names.** JIRA groups statuses into three
+categories — `To Do` (`new`), `In Progress` (`indeterminate`), `Done` (`done`) — and a `Blocked`
+status is not a fourth category: a project that wants one models it under **`To Do`**, i.e. work
+that was never started. Keying the candidate set on status *names* therefore omits every pre-work
+lane a project invented, and the scanner reports an empty queue over a full one. The same defect on
+the Linear side produced 31 consecutive false "dry lane" cycles (#2657).
 
-If empty, report `"No tickets with Status=$READY. Nothing to do."` and exit. This is the common idle case.
+1. Run the ready query first: `lisa-atlassian-access` `operation: search-issues jql: "<JQL>"`. This
+   is the human-flipped lane and it is worked first.
+2. Then sweep the rest of pre-work with the same base JQL, swapping the status clause for
+   `statusCategory = "To Do"`, and read the **total open** count (`statusCategory != Done`). The
+   open total is what makes an omitted lane arithmetically visible.
+3. Page to exhaustion — a single unpaged `search-issues` call is not a count.
+
+Capture each ticket's: key, summary, issue type, priority, assignee, parent (epic), status (with
+its category), labels, components.
+
+Build the denominator with the shared helper, which owns the pre-work vocabulary so no two
+scanners can disagree about what counts:
+
+```text
+buildIntakeDenominator({ lanes: [{name: "<status>", type: "<statusCategory>", count: <rows>}, …],
+                         totalOpen: <statusCategory != Done count> })
+summarizeDryLane(denominator, { queue: "<project key>" })
+```
+
+The helper accepts JIRA's category vocabulary directly (`new` / `To Do` normalize to pre-work).
+
+**Every candidate outside `$READY` must clear Phase 2.5 before it is treated as a candidate at
+all.** If nothing survives, exit on the denominator-stated summary from `summarizeDryLane` — never a
+bare "nothing to do". The run recorder rejects a dry build-intake run that does not name what it
+swept (see `automation-runbook-contract`).
+
+### Phase 2.5 — Re-probe the blockers instead of inheriting them
+
+A blocker is a **claim with a timestamp, not a fact** — it goes stale the moment its condition comes
+true, and nothing re-read one before this phase. For each pre-work candidate outside `$READY`:
+
+1. **Human gate first, and it is absolute.** A ticket carrying the configured human-needed label
+   (`jira.labels.human_needed`, default `Human Needed`) or a `[lisa-human-gate]` marker in its
+   description is **never** auto-selected, whatever any probe says.
+2. **Extract the stated discharge condition**, then **probe it**. Machine-testable conditions — a
+   version on trunk, a published package, a CI run history, an advisory's patched status — rot
+   fastest and are cheapest to check. A human decision is not machine-testable; leave it.
+3. **Classify with `classifyPreWorkCandidate(...)`** from
+   `scripts/intake-blocker-reprobe.mjs`. A discharge with no recorded evidence is not a discharge,
+   and neither is a candidate nothing probed this cycle — the helper refuses both.
+4. **Record the result on the ticket either way** via `formatReprobeNote(...)` as a comment, so the
+   next cycle reads the answer rather than re-deriving it. Keep it idempotent.
+5. **On `selectable: true`**, transition the ticket to `$READY` with the discharging evidence in the
+   same comment, and treat it as an ordinary candidate. On anything else, leave it where it is.
 
 ### Phase 3 — Process the first eligible ready ticket
 
@@ -149,7 +197,7 @@ A JIRA project can oversee multiple repos (`frontend` / `backend` / `infrastruct
    - **Unlabeled** → determine the target repo(s) from the ticket (description, AC, technical approach) confirmed against the code surfaces, then **stamp** `repo:<name>` via `lisa-atlassian-access` `operation: write-ticket` (add the label / set the component) so later cycles filter cheaply; re-apply with the now-known repo.
    - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure to break it into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
    - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
-4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the ready set is exhausted — exit cleanly with `"No ready tickets for repo <current>. Nothing to do."`.
+4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the candidate set is exhausted — exit cleanly on the denominator-stated summary, naming the current repo alongside the swept lanes.
 
 #### 3a. Leaf-only claim gate (skip / safe-block containers)
 

package/plugins/lisa-copilot/skills/lisa-linear-build-intake/SKILL.md

@@ -99,7 +99,7 @@ The only legitimate reasons to stop early:
 
 - Missing team key or required configuration. Surface and exit.
 - Workflow states not yet adopted (the `ready` state does not exist on the team). Surface and exit with an Adoption hint pointing at `/lisa:setup:linear`.
-- Empty ready set. Exit cleanly with `"No Linear Issues in state $READY. Nothing to do."`
+- Empty pre-work set. Exit cleanly on the denominator-stated summary from `summarizeDryLane` — which names every lane swept, its count, and the open total. A bare "nothing to do" is not an acceptable exit: it is indistinguishable from a wrong denominator (#2657).
 
 ## Lifecycle assumed
 
@@ -112,7 +112,7 @@ ready → claimed → review → done(env-keyed) (downstream)
 
 (Defaults: `Ready` / `In Progress` / `In Review` / `On Dev`/`On Stg`/`Done`.)
 
-This skill ONLY transitions `$READY → $CLAIMED` on claim, and `$CLAIMED → $DONE` on completion. It never touches the terminal production `done`, `$REVIEW` (owned by the lifecycle / `lisa-linear-evidence`), or `$BLOCKED` (owned by the pre-flight gate).
+This skill ONLY transitions `$READY → $CLAIMED` on claim, and `$CLAIMED → $DONE` on completion. It never touches the terminal production `done` or `$REVIEW` (owned by the lifecycle / `lisa-linear-evidence`). It never *sets* `$BLOCKED` either — that stays owned by the pre-flight gate — but Phase 2.5 does move an Issue **out** of a pre-work blocked lane back to `$READY` when it re-probes the Issue's own stated discharge condition and finds it no longer holds, recording the discharging evidence on the Issue.
 
 **Pre-flight check**: at start of each cycle, confirm `$READY`, `$CLAIMED`, and the relevant `$DONE` variants exist on the team via `lisa-linear-access operation: list-workflow-states`. If `$READY` is missing, stop and report adoption needed. **Unlike labels, a missing state cannot be created on demand here** — a workflow state is team configuration with a `type` and a board position, and guessing either would put an Issue somewhere a human did not sanction. Any missing state is a setup defect: report it, name the role and the expected state, and point at `/lisa:setup:linear`.
 
@@ -125,15 +125,56 @@ This skill ONLY transitions `$READY → $CLAIMED` on claim, and `$CLAIMED → $D
    - Literal `linear` → fall back to `linear.teamKey` from config.
 2. Resolve team ID via `lisa-linear-access operation: list-teams({query: <teamKey>})`.
 
-### Phase 2 — Find ready Issues
+### Phase 2 — Sweep every pre-work lane by state TYPE
 
-Query: `lisa-linear-access operation: list-issues({team: <teamId>, state: "$READY"})`.
+**Sweep by `type`, never by a roster of state names.** Linear state types are `backlog | unstarted | started | completed | canceled`, and there is no `blocked` type — a team that wants a `Blocked` lane models it as **`unstarted`**, i.e. work that was *never started*. Selecting candidates from a hardcoded `Backlog / Todo / Ready` name list therefore omits an entire pre-work lane and reports an empty queue over a full one. Measured on one team: the name sweep saw **39 of 343 open rows**; the type sweep sees **100**, and the 61-row difference produced 31 consecutive false "dry lane" cycles (#2657).
 
-Capture each Issue's: identifier, title, type label, priority, assignee, project, state, labels, description summary.
+1. List the team's workflow states via `lisa-linear-access operation: list-workflow-states`.
+2. Keep every state whose `type` is `backlog` or `unstarted` — that is the pre-work set. `$READY` is one member of it, not the whole of it.
+3. Query each pre-work state: `lisa-linear-access operation: list-issues({team: <teamId>, state: "<state>"})`, paging to `hasNextPage=false`. Linear's GraphQL complexity ceiling silently truncates at `first: 250`, so a single unpaged call is not a count.
+4. Also read the **total open** count for the team (every state whose `type` is not `completed` / `canceled`). This number is what makes an omitted lane arithmetically visible.
+
+Capture each Issue's: identifier, title, type label, priority, assignee, project, state (with its `type`), labels, description summary.
+
+Build the denominator with the shared helper, which owns the type vocabulary so no two scanners can disagree about what counts as pre-work:
+
+```bash
+node -e '
+import("'"${CLAUDE_PLUGIN_ROOT:-plugins/src/base}"'/scripts/intake-prework-denominator.mjs").then(m => {
+  const d = m.buildIntakeDenominator({ lanes: JSON.parse(process.argv[1]), totalOpen: Number(process.argv[2]) });
+  console.log(JSON.stringify(d));
+  console.log(m.summarizeDryLane(d, { queue: process.argv[3] }));
+});' "$LANES_JSON" "$TOTAL_OPEN" "team $TEAM_KEY"
+```
+
+`$LANES_JSON` is `[{"name":"<state>","type":"<state.type>","position":<state.position>,"count":<open rows>}, …]` for **every** state on the team, pre-work and not — the helper does the selecting.
+
+**Candidate order.** Work `$READY` first (it is the human-flipped signal), then the remaining pre-work lanes oldest-first. Every candidate outside `$READY` must clear Phase 2.5 before it is treated as a candidate at all.
 
 > **No query-time repo pre-filter here (by design).** Unlike `lisa-jira-build-intake`, which narrows its JQL with `AND (labels = "repo:<current>" OR labels IS EMPTY)` (the query-time arm of `repo-scope-split`), the Linear `list_issues` label filter is an AND-of-labels and cannot express "current-repo **or** unlabeled" in one query. Adding `repo:<current>` to this query would strand unlabeled Issues the determine + stamp path must see. So the Linear scanner keeps this query broad and relies on the per-candidate 3a.0 gate below for repo scoping. (The `state` filter above is orthogonal to that — it narrows the lifecycle lane, not the repo, and is a single-valued equality so it has none of the AND-of-labels problem.)
 
-If empty, report `"No Linear Issues in state $READY. Nothing to do."` and exit. Common idle case.
+If every pre-work lane is empty, or nothing survives Phase 2.5, exit on the **denominator-stated** summary from `summarizeDryLane` — never a bare "nothing to do". See "Run outcome" below; the run recorder rejects a dry build-intake run that does not name what it swept.
+
+### Phase 2.5 — Re-probe the blockers instead of inheriting them
+
+A blocker is a **claim with a timestamp, not a fact**. It is written once and goes stale the moment its condition comes true — a dependency lands on trunk, an advisory gets patched, a package publishes. Nothing re-read one before this phase, so a discharged blocker held its Issue out of the queue indefinitely. Measured: one Issue's stated condition went true ~15 hours before anything noticed.
+
+For each pre-work candidate that is **not** in `$READY`:
+
+1. **Human gate first, and it is absolute.** An Issue carrying the configured human-needed label (`linear.labels.build.human_needed`, default `human-needed`) or a `[lisa-human-gate]` marker in its description is **never** auto-selected, whatever any probe says. Skip it and move on.
+2. **Extract the stated discharge condition** from the description or the most recent blocking comment — the sentence naming what has to become true.
+3. **Probe it.** Machine-testable conditions are the ones that rot fastest and are cheapest to check: a version on trunk (`git show origin/<trunk>:<manifest>`), a published package, a run history (`gh run list`), an advisory's patched status. A condition that is a human decision is not machine-testable — leave it and move on.
+4. **Classify with the shared helper** so the ordering and the evidence requirement cannot drift per vendor:
+
+```text
+classifyPreWorkCandidate({ laneType, labels, body, humanNeededLabel, statedBlocker, probe })
+  → { selectable, reason, humanGated, evidence }
+```
+
+   A discharge with **no recorded evidence is not a discharge** — the helper refuses it. So is a candidate nothing probed this cycle.
+
+5. **Record the result on the Issue either way**, via `lisa-linear-access operation: save-comment` using `formatReprobeNote(...)`, so the next cycle reads the answer rather than re-deriving it. Keep it idempotent — skip the post when an identical note already exists.
+6. **On `selectable: true`**, move the Issue to `$READY` (recording the discharging evidence in the same comment) and treat it as an ordinary candidate from Phase 3 onward. On anything else, leave the Issue exactly where it is.
 
 ### Phase 3 — Process the first eligible ready Issue
 
@@ -148,7 +189,7 @@ A Linear team can oversee multiple repos (`frontend` / `backend` / `infrastructu
    - **Unlabeled** → determine the target repo(s) from the Issue + code surfaces, then **stamp** `repo:<name>` via `lisa-linear-access operation: save-issue` (resolve/create the label via `list_issue_labels`/`create_issue_label`) so later cycles filter cheaply; re-apply with the now-known repo.
    - **Multi-repo leaf → split, never claim.** Run the `repo-scope-split` work-time procedure into single-repo siblings, each created **build-ready** (`build_ready: true`) and stamped with its own `repo:<name>`; the current repo's sibling becomes a normal candidate.
    - **Single-repo leaf for the current repo** → fall through to 3a (leaf-only gate) and 3b (claim).
-4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the ready set is exhausted — exit cleanly with `"No ready Issues for repo <current>. Nothing to do."`.
+4. Continue until a claimable current-repo leaf is found (claim it; one per cycle) or the candidate set is exhausted — exit cleanly on the denominator-stated summary, naming the current repo alongside the swept lanes.
 
 #### 3a. Leaf-only claim gate (skip / safe-block containers)
 

package/plugins/lisa-copilot/skills/lisa-tracker-build-intake/SKILL.md

@@ -42,6 +42,30 @@ This is the claim-time arm of the rule. Its siblings are the write-time labeling
 
 The shim never needs to inspect the item itself — it forwards `$ARGUMENTS` verbatim and the resolved vendor scanner runs its Phase 3a gate before any claim.
 
+## Pre-work denominator contract (forwarded to every vendor)
+
+Also part of the build-intake API, and the reason a dry queue can be believed. Two obligations,
+uniform across `jira`, `github`, and `linear`:
+
+1. **Sweep every pre-work lane by its machine-readable category, never by a roster of lane names.**
+   No tracker has a `blocked` category: Linear models a `Blocked` state as `unstarted`, JIRA models
+   a `Blocked` status under `To Do`, and GitHub has no category at all, so its lanes come from
+   configured roles. In every case a `Blocked` lane is *pre-work* — items that were never started,
+   each carrying a written blocker. Keying selection on names omits it silently.
+2. **A `nothing-needed` run states its denominator** — which lanes were swept, how many rows each
+   held, and the total open. This is enforced, not requested: `automation-run-record.mjs` refuses a
+   `nothing-needed` row for `intake-tickets` without a `--denominator`.
+
+Shared helpers own both, so the vocabulary cannot drift per vendor:
+`scripts/intake-prework-denominator.mjs` (`buildIntakeDenominator`, `summarizeDryLane`) and
+`scripts/intake-blocker-reprobe.mjs` (`classifyPreWorkCandidate`, `formatReprobeNote`). The
+blocker re-probe carries an absolute human gate: an item carrying the configured human-needed label
+or a `[lisa-human-gate]` marker is never auto-selected, whatever a probe returns.
+
+Measured: sweeping one team by lane name saw 39 of 343 open rows; by category it sees 100. The
+61-row gap produced 31 consecutive false "dry lane" cycles, every record honest and every
+conclusion wrong (#2657).
+
 ## Repo-scope claim contract (forwarded to every vendor)
 
 Equally part of the build-intake API, and forwarded identically: when the tracker oversees multiple repos, each vendor scanner claims only tickets for the repo it is running in. Per the `repo-scope-split` rule's "Claim-time repo scoping" section, before the leaf-only gate each scanner (Phase 3a.0) resolves the current repo (`config-resolution` "Repo scoping": `repo` → `github.repo` → git remote basename), then for each ready candidate: skips a ticket labeled `repo:<other>`, determines + stamps `repo:<name>` on an unlabeled one, splits a multi-repo leaf into single-repo build-ready siblings, and claims only a single-repo leaf for the current repo. This shim does not re-implement the gate — it relies on the vendor scanner's Phase 3a.0 — but the contract is uniform across `jira`, `github`, and `linear` so behavior never drifts by tracker. It is the claim-time complement to the write-time S10 scope gate (`lisa-tracker-validate`) and `task-decomposition` step 1.5; all cite `repo-scope-split`.

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.33.8",
+  "version": "3.35.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -125,6 +125,25 @@ recovery-required   Lost access to the tracker; filed #1812 with the one decisio
 policy-obsolete     No work has reached this queue in 30 days; proposed teardown in #1813.
 ```
 
+### `nothing-needed` states its denominator
+
+A queue-scanning loop that reports nothing is only as trustworthy as the set it looked at, and a
+summary of the form "scanned N items" hides the one thing worth checking: **which lanes N came
+from.** So a `nothing-needed` summary from a queue scanner names the lanes it swept, the count in
+each, and the total open — `Looked in every lane holding work that has not started — Backlog (20),
+Todo (17), Ready (2), Blocked (61) — 100 items checked out of 343 still open.`
+
+This is a measured requirement, not a style preference. One build lane reported 31 consecutive dry
+cycles over a queue holding 61 unswept rows, at least one of them buildable for ~15 hours. Every
+one of the 31 records was honest and every conclusion was false, because the scanner never said
+what its denominator was. **A missing run record is noisy on inspection; a wrong denominator is
+silent forever and looks exactly like a healthy dry queue.** Stating the swept set is what makes
+the second failure mode visible at all.
+
+The build-intake loop enforces this rather than requesting it: `automation-run-record.mjs` refuses
+a `nothing-needed` row for `intake-tickets` unless the call carries a `--denominator` built by
+`scripts/intake-prework-denominator.mjs`.
+
 **No silent exit.** Every run posts its outcome and its one-line summary before stopping —
 including the trivial early terminations (empty queue, nothing eligible, already-claimed) — so
 there is no silent exit for an operator to misread as health. A run that ends without a

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

@@ -53,6 +53,8 @@ Exactly one per run:
 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