@codyswann/lisa 4.11.2 → 4.12.0

package/plugins/lisa-cursor/rules/leaf-only-lifecycle-reference.mdc

@@ -79,12 +79,33 @@ The middle two rungs are the same idea seen at two resolutions: a parent reaches
 Notes:
 
 - **Blocked dominates.** A single blocked leaf surfaces blocked/attention on the parent even if other leaves are progressing, so a human sees the parent needs attention.
+- **Blocked must name its leaf and its class.** "Blocked" alone is a single bit, and it is lossy in the one dimension that decides what the operator does next. Two holds that render identically are not the same problem: one waits on an external event and may clear with nobody touching it; the other waits on a person rewriting an acceptance criterion and will never clear on its own. Rendered the same, the second class accumulates silently — measured on one Epic at two occurrences, 32 identical hold comments and six weeks, while the initiative was two-thirds complete both times (#3045). See **Classifying a hold** below.
 - **"Required" leaves.** Optional or won't-do children do not hold a parent open; only the leaves that must ship for the parent to be complete are counted toward the env-rollup check.
 - **Least-advanced env wins.** The parent reflects the env the whole required set has collectively reached — never an env ahead of its laggard leaf. Native closure (below) fires only when the resolved env is the production/terminal value, never at an intermediate env (`On Dev`/`On Stg`).
 - **Rollup is recursive.** An Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up: a Story reaches an env only when its leaves have all reached at least that env; an Epic reaches it only when its Stories have.
 - **Vendor support varies.** Apply the rollup state the vendor can express. Where a vendor has no native intermediate state, use the nearest configured role or a metadata/comment signal rather than forcing a non-existent status (PRD #522 non-goal: vendors need not expose identical states).
 - **The parent never carries `ready`.** `ready` is a *human* "this is buildable, claim it" signal and only ever lives on leaves. Rollup moves a parent between non-ready container states (in-progress / per-env / blocked / terminal); it never sets the parent to `ready`. A container found carrying `ready` is a leaf-only-invariant violation — recompute its rolled state from its children and apply that (see `repair-intake`).
 
+### Classifying a hold
+
+`rollup-blocker-classification` (`plugins/src/base/scripts/rollup-blocker-classification.mjs`) is the single implementation. It takes the child graph the vendor reader already produced and returns, per held leaf, a class and the actor who must clear it:
+
+| Class | Recorded signal on the leaf | Who must act | Clears on its own? |
+|---|---|---|---|
+| `spec-defect` | the `spec_defect` marker (`config-resolution` → Build markers) | a person rewrites the acceptance criteria | never |
+| `human-input` | the `human_needed` marker | a person supplies the input — access, a credential, a product decision | no |
+| `hard-blocker` | at least one **open** `is blocked by` link | nobody | yes, when that work closes |
+| `unknown` | none of the above | a person says which kind it is, then records it | no |
+
+Four properties are load-bearing:
+
+1. **Recorded signals only.** A class comes from a marker or a link somebody wrote, never from reading the item's prose. There is no heuristic to drift.
+2. **It never reclassifies.** Deciding an acceptance criterion is unbuildable is a human product call. The tool makes the distinction *recordable and visible*; it does not make it. `unknown` is the honest answer, and it names the person who must resolve it rather than guessing.
+3. **A transparent parent is not the blocker.** A held item whose own children include a held one is reported *through*: the rollup names the leaf at the bottom of the chain and the path to it (`#1495 -> #1515 -> #1547`), which is what turns a five-level descent into one read.
+4. **It fails rather than reporting all-clear.** An unreadable tracker, a container with no children, and children none of which could be read each return a refusal, not `not-blocked`. A rollup that examined nothing and reported clean would be the same defect one level up.
+
+The report is **composed per class**: a class with nothing in it produces no text, so the summary and the per-item lines cannot disagree (the `#3101` shape). It also carries a fingerprint of `container + held refs + classes`, so a cycle whose verdict is unchanged has nothing new to post and stays quiet — the 32 identical hold comments were one verdict restated on a schedule.
+
 ### The rollup env states are the configured "done" map — multi-env capable
 
 The env rungs are whatever the project configures for `done` — which is **env-keyed** (`config-resolution` "Env-keyed `done`"): a `done` map keyed by environment (`dev`, `staging`, `production`), each leaf's env resolved from its merged PR's base branch. This rule does **not** hardcode a `dev → staging → prod` promotion chain as required — that is a project-specific deploy topology; the ladder is simply the ordered keys of the project's `done` map. A downstream project with dev/staging/prod environments rolls a parent up to the least-advanced env value its required leaves have collectively reached (an intermediate-env parent state, e.g. `On Stg`), and only to the production `done` value once every required leaf is at production. The rule stays generic and multi-env capable.

package/plugins/lisa-cursor/rules/leaf-only-lifecycle.mdc

@@ -31,6 +31,17 @@ Evaluate over the env ladder `in-progress < dev < staging < production` (the ord
 3. Else any leaf has **started** (claimed/in review, or shipped while a sibling has not) → parent is **in-progress** (`claimed`).
 4. Else (leaves exist but none started) → parent unchanged.
 
+**Blocked dominates — but it must say which leaf and which kind.** A parent that rolls up to `blocked` names the blocking leaf (with the path to it) and the **class** of the hold, derived by `rollup-blocker-classification` from recorded signals only:
+
+| Class | Recorded signal on the leaf | Who must act |
+|---|---|---|
+| `spec-defect` | the `spec_defect` marker (human-applied only) | a person rewrites the acceptance criteria — nothing external will ever clear it |
+| `human-input` | the `human_needed` marker | a person supplies the input (access, credential, product decision) |
+| `hard-blocker` | an open `is blocked by` link | nobody — it clears when that work closes |
+| `unknown` | none of the above | a person says which kind it is, and records it |
+
+Never infer a class from prose, and never auto-apply `spec_defect`: judging a criterion unbuildable is a human call, and `unknown` is the honest answer. A rollup that examined nothing — unreadable tracker, no children, no readable child — **fails**; it never reports not-blocked.
+
 **Blocked dominates.** A parent reaches an env only once all required leaves have reached at least that env. Intermediate-env rollup (`On Dev`/`On Stg`) happens, but native closure fires only at production `done`. Optional/won't-do children do not hold a parent open. Rollup is recursive — bottom-up. The parent never carries `ready`; a container found in `ready` is reconciled by rolling it up from its children.
 
 ## Terminal native closure

package/plugins/lisa-cursor/scripts/rollup-blocker-classification.mjs

@@ -0,0 +1,592 @@
+#!/usr/bin/env node
+/**
+ * Blocker classification for the parent status rollup.
+ *
+ * The `leaf-only-lifecycle` rollup propagates "blocked dominates" faithfully:
+ * one blocked leaf anywhere under a container puts the container in `blocked`.
+ * What it propagates is a single bit. It cannot say which leaf, and it cannot
+ * say what kind of hold it is — and those are two different asks:
+ *
+ * - a **hard blocker** waits on an external event and may clear with nobody
+ *   touching it;
+ * - a **bad acceptance criterion** waits on a person rewriting it, and will
+ *   never clear on its own.
+ *
+ * Rendered identically, the second class accumulates silently. Measured on one
+ * Epic: two occurrences, 32 identical hold comments, six weeks — while the
+ * initiative was two-thirds complete both times.
+ *
+ * This module classifies from **recorded signals only** — the markers and the
+ * `is blocked by` links a writer already put on the item. It never reads prose
+ * to guess, and it never decides that a criterion is bad: judging that is a
+ * human call, and `unknown` is the honest answer when nothing recorded says.
+ * Its job is to make the distinction recordable and visible, not to make it.
+ *
+ * It probes nothing itself. The caller reads the tracker and hands back the
+ * child graph, which keeps the decision auditable and testable apart from the
+ * network — same contract as `intake-blocker-reprobe`.
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Classes a hold can carry, most specific first. */
+export const BLOCKER_CLASSES = Object.freeze([
+  "spec-defect",
+  "human-input",
+  "hard-blocker",
+  "unknown",
+]);
+
+/** Default marker naming a hold a person must rewrite the spec to clear. */
+export const DEFAULT_SPEC_DEFECT_MARKER = "blocked:spec-defect";
+
+/** Default marker naming a hold only a person can supply the input for. */
+export const DEFAULT_HUMAN_NEEDED_MARKER = "human-needed";
+
+/** Lifecycle values that mean "held", across the three trackers. */
+const DEFAULT_BLOCKED_STATES = Object.freeze([
+  "blocked",
+  "status:blocked",
+  "Blocked",
+]);
+
+/**
+ * Who must act, per class. One actor per class, never a shared line: the whole
+ * point is that "waits on an external event" and "waits on a person rewriting
+ * it" are different asks and must not be rendered the same way.
+ */
+export const BLOCKER_ACTOR = Object.freeze({
+  "spec-defect": "a person rewrites the acceptance criteria",
+  "human-input": "a person supplies the input",
+  "hard-blocker": "nobody — it waits on other work",
+  unknown: "a person says which kind of hold this is",
+});
+
+/** Operator-readable heading and body, per class. Composed, never asserted. */
+export const BLOCKER_COPY = Object.freeze({
+  "spec-defect": {
+    heading: "Waiting on a rewrite",
+    line: "A person must rewrite this item's acceptance criteria. Nothing external will ever clear it, so it will sit here until someone edits it.",
+  },
+  "human-input": {
+    heading: "Waiting on a person",
+    line: "A person must supply something no agent can invent — access, a credential, or a product decision. It will not clear on its own.",
+  },
+  "hard-blocker": {
+    heading: "Waiting on other work",
+    line: "Nobody has to act. This clears by itself when the work it names below closes.",
+  },
+  unknown: {
+    heading: "Nobody is assigned",
+    line: `Nothing recorded on this item says which kind of hold it is, so nobody is assigned to it and it will sit. A person must decide, then record it: add \`${DEFAULT_SPEC_DEFECT_MARKER}\` if the acceptance criteria are the problem, or an \`is blocked by\` link if it is waiting on other work.`,
+  },
+});
+
+/** Why a classification run refuses to report. */
+export const CLASSIFICATION_FAILURES = Object.freeze({
+  CONTAINER_UNREADABLE: "container-unreadable",
+  NO_CHILDREN: "rollup-has-no-children",
+  NOTHING_EXAMINED: "no-child-could-be-examined",
+});
+
+const FAILURE_COPY = Object.freeze({
+  "container-unreadable":
+    "The tracker could not be read, so nothing was examined. This is not an all-clear.",
+  "rollup-has-no-children":
+    "This container has no children, so there was nothing to roll up. A container with no children is a decomposition gap, not a clear rollup.",
+  "no-child-could-be-examined":
+    "Children were listed but none could be examined, so nothing was classified. This is not an all-clear.",
+});
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function trimmedString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * @param {unknown} labels
+ * @returns {readonly string[]}
+ */
+function normalizeMarkers(labels) {
+  return (Array.isArray(labels) ? labels : [])
+    .map(label =>
+      typeof label === "string" ? label : trimmedString(label?.name)
+    )
+    .map(label => trimmedString(label).toLowerCase())
+    .filter(label => label.length > 0);
+}
+
+/**
+ * @param {unknown} states
+ * @returns {readonly string[]}
+ */
+function normalizeBlockedStates(states) {
+  const configured = (Array.isArray(states) ? states : DEFAULT_BLOCKED_STATES)
+    .map(state => trimmedString(state).toLowerCase())
+    .filter(state => state.length > 0);
+
+  return configured.length > 0
+    ? configured
+    : DEFAULT_BLOCKED_STATES.map(state => state.toLowerCase());
+}
+
+/**
+ * A child's own lifecycle value, taken from whichever field the vendor reader
+ * filled: a JIRA/Linear `state`, or the single `status:*` GitHub label.
+ *
+ * @param {{ state?: unknown, status?: unknown, role?: unknown }} node
+ * @returns {string}
+ */
+function nodeState(node) {
+  return (
+    trimmedString(node?.state) ||
+    trimmedString(node?.status) ||
+    trimmedString(node?.role)
+  );
+}
+
+/**
+ * Open `is blocked by` dependencies recorded on the item. A dependency the
+ * caller resolved as closed is dropped: it no longer holds anything.
+ *
+ * @param {unknown} blockedBy
+ * @returns {readonly string[]}
+ */
+function openDependencies(blockedBy) {
+  return (Array.isArray(blockedBy) ? blockedBy : [])
+    .map(entry =>
+      typeof entry === "string"
+        ? { ref: entry, open: true }
+        : { ref: trimmedString(entry?.ref), open: entry?.open !== false }
+    )
+    .filter(entry => entry.open && entry.ref.length > 0)
+    .map(entry => entry.ref);
+}
+
+/**
+ * Classify one held item from its recorded signals.
+ *
+ * Order is load-bearing and runs most-deliberate first. A marker is something
+ * a person chose to write; a dependency link is something a flow wrote. Where
+ * both are present the human's record wins, because the marker is the only
+ * signal that carries a judgment nothing else can supply.
+ *
+ * @param {{
+ *   ref?: unknown
+ *   labels?: unknown
+ *   markers?: unknown
+ *   blockedBy?: unknown
+ * }} node
+ * @param {{ specDefect?: unknown, humanNeeded?: unknown }} [markerNames]
+ * @returns {{ class: string, actor: string, signals: readonly string[] }}
+ */
+export function classifyHeldItem(node = {}, markerNames = {}) {
+  const specDefect = (
+    trimmedString(markerNames.specDefect) || DEFAULT_SPEC_DEFECT_MARKER
+  ).toLowerCase();
+  const humanNeeded = (
+    trimmedString(markerNames.humanNeeded) || DEFAULT_HUMAN_NEEDED_MARKER
+  ).toLowerCase();
+  const markers = normalizeMarkers(node.markers ?? node.labels);
+  const dependencies = openDependencies(node.blockedBy);
+
+  if (markers.includes(specDefect)) {
+    return {
+      class: "spec-defect",
+      actor: BLOCKER_ACTOR["spec-defect"],
+      signals: [`marked \`${specDefect}\``],
+    };
+  }
+  if (markers.includes(humanNeeded)) {
+    return {
+      class: "human-input",
+      actor: BLOCKER_ACTOR["human-input"],
+      signals: [`marked \`${humanNeeded}\``],
+    };
+  }
+  if (dependencies.length > 0) {
+    return {
+      class: "hard-blocker",
+      actor: BLOCKER_ACTOR["hard-blocker"],
+      signals: [`blocked by ${dependencies.join(", ")}`],
+    };
+  }
+
+  return { class: "unknown", actor: BLOCKER_ACTOR.unknown, signals: [] };
+}
+
+/**
+ * @param {unknown} children
+ * @returns {readonly object[]}
+ */
+function childArray(children) {
+  return Array.isArray(children) ? children.filter(Boolean) : [];
+}
+
+/**
+ * Walk the container's descendants, collecting every held item that is itself
+ * the bottom of a chain of holds.
+ *
+ * A held parent whose own children include a held one is *transparent*: it is
+ * blocked because of them, so reporting it would name the wrong item. Its path
+ * is kept instead, which is what turns a five-level descent into one read.
+ *
+ * @param {readonly object[]} children
+ * @param {{ blockedStates: readonly string[], markerNames: object }} context
+ * @param {readonly string[]} path
+ * @param {Set<string>} seen
+ * @param {{ examined: number, unexaminable: string[] }} tally
+ * @returns {object[]}
+ */
+function collectHolds(children, context, path, seen, tally) {
+  return childArray(children).flatMap(child => {
+    const ref = trimmedString(child.ref) || trimmedString(child.key);
+    const state = nodeState(child);
+    if (ref.length === 0 || state.length === 0) {
+      tally.unexaminable.push(ref || "(child with no reference)");
+      return [];
+    }
+    if (seen.has(ref)) {
+      return [];
+    }
+    seen.add(ref);
+    tally.examined += 1;
+
+    const here = [...path, ref];
+    const descendants = collectHolds(
+      child.children,
+      context,
+      here,
+      seen,
+      tally
+    );
+    if (!context.blockedStates.includes(state.toLowerCase())) {
+      return descendants;
+    }
+    if (descendants.length > 0) {
+      return descendants;
+    }
+
+    return [
+      {
+        ref,
+        path: here,
+        ...classifyHeldItem(child, context.markerNames),
+      },
+    ];
+  });
+}
+
+/**
+ * Classify every hold under a container and derive the rollup from it.
+ *
+ * Refuses rather than reports when it examined nothing: an unreadable tracker,
+ * a container with no children, and children none of which could be read all
+ * return `ok: false`. Reporting all-clear on any of them would be the same
+ * defect this module exists to fix, one level up.
+ *
+ * @param {{
+ *   container?: { ref?: unknown, type?: unknown }
+ *   readError?: unknown
+ *   children?: unknown
+ *   blockedStates?: unknown
+ *   markerNames?: { specDefect?: unknown, humanNeeded?: unknown }
+ * }} input
+ * @returns {object}
+ */
+export function classifyRollupBlockers(input = {}) {
+  const container = {
+    ref: trimmedString(input.container?.ref) || "(unnamed container)",
+    type: trimmedString(input.container?.type) || "container",
+  };
+  const readError = trimmedString(input.readError);
+  if (readError.length > 0) {
+    return failure(container, CLASSIFICATION_FAILURES.CONTAINER_UNREADABLE, {
+      detail: readError,
+    });
+  }
+
+  const children = childArray(input.children);
+  if (children.length === 0) {
+    return failure(container, CLASSIFICATION_FAILURES.NO_CHILDREN);
+  }
+
+  const tally = { examined: 0, unexaminable: [] };
+  const blockers = collectHolds(
+    children,
+    {
+      blockedStates: normalizeBlockedStates(input.blockedStates),
+      markerNames: input.markerNames ?? {},
+    },
+    [container.ref],
+    new Set([container.ref]),
+    tally
+  );
+
+  if (tally.examined === 0) {
+    return failure(container, CLASSIFICATION_FAILURES.NOTHING_EXAMINED, {
+      detail: `${children.length} listed, none readable`,
+    });
+  }
+
+  const byClass = Object.fromEntries(
+    BLOCKER_CLASSES.map(name => [
+      name,
+      blockers.filter(blocker => blocker.class === name),
+    ]).filter(([, group]) => group.length > 0)
+  );
+
+  return {
+    ok: true,
+    container,
+    verdict: blockers.length > 0 ? "blocked" : "not-blocked",
+    examined: tally.examined,
+    blockers,
+    byClass,
+    unexaminable: tally.unexaminable,
+  };
+}
+
+/**
+ * @param {{ ref: string, type: string }} container
+ * @param {string} reason
+ * @param {{ detail?: string }} [extra]
+ * @returns {object}
+ */
+function failure(container, reason, extra = {}) {
+  return {
+    ok: false,
+    container,
+    verdict: "unclassified",
+    examined: 0,
+    reason,
+    message: FAILURE_COPY[reason] ?? reason,
+    detail: trimmedString(extra.detail),
+  };
+}
+
+/**
+ * @param {{ ref: string, path: readonly string[], signals: readonly string[] }} blocker
+ * @returns {string}
+ */
+function renderBlockerLine(blocker) {
+  const via =
+    blocker.path.length > 2 ? ` (via ${blocker.path.join(" -> ")})` : "";
+  const signals =
+    blocker.signals.length > 0 ? ` — ${blocker.signals.join("; ")}` : "";
+
+  return `  - ${blocker.ref}${via}${signals}`;
+}
+
+/**
+ * Render the rollup for an operator.
+ *
+ * Every sentence is composed from the per-class grouping rather than asserted
+ * over all blockers, so the summary and the per-item lines cannot disagree. A
+ * class with nothing in it produces no text at all.
+ *
+ * @param {object} result - A {@link classifyRollupBlockers} result.
+ * @returns {string}
+ */
+export function renderRollupBlockerReport(result) {
+  if (!result?.ok) {
+    return [
+      `${result?.container?.ref ?? "(unnamed container)"} — NOT CLASSIFIED (${result?.reason ?? "unknown"}).`,
+      result?.message ?? "",
+      trimmedString(result?.detail).length > 0
+        ? `Detail: ${result.detail}`
+        : "",
+    ]
+      .filter(line => line.length > 0)
+      .join("\n");
+  }
+
+  if (result.verdict === "not-blocked") {
+    return `${result.container.ref} — not blocked. ${result.examined} item(s) examined, none held.`;
+  }
+
+  const held = result.blockers.length;
+  const sections = BLOCKER_CLASSES.filter(
+    name => (result.byClass[name] ?? []).length > 0
+  ).map(name => {
+    const group = result.byClass[name];
+    const copy = BLOCKER_COPY[name];
+
+    return [
+      `${copy.heading} (${group.length}) — who must act: ${BLOCKER_ACTOR[name]}.`,
+      `  ${copy.line}`,
+      ...group.map(renderBlockerLine),
+    ].join("\n");
+  });
+
+  return [
+    `${result.container.ref} — blocked. ${held} of ${result.examined} item(s) examined are held.`,
+    "",
+    ...sections.flatMap(section => [section, ""]),
+  ]
+    .join("\n")
+    .trimEnd();
+}
+
+/**
+ * A stable identity for a rollup verdict: the container, plus every held item
+ * and its class, sorted.
+ *
+ * This is what lets a repeat cycle stay quiet. 32 identical hold comments over
+ * six weeks was the same verdict restated on a schedule; comparing this string
+ * to the last one tells a caller whether it has anything new to say.
+ *
+ * @param {object} result - A {@link classifyRollupBlockers} result.
+ * @returns {string}
+ */
+export function rollupBlockerFingerprint(result) {
+  if (!result?.ok) {
+    return `container=${result?.container?.ref ?? "?"};unclassified=${result?.reason ?? "?"}`;
+  }
+  const pairs = [...result.blockers]
+    .map(blocker => `${blocker.ref}:${blocker.class}`)
+    .sort((left, right) => left.localeCompare(right));
+
+  return `container=${result.container.ref};verdict=${result.verdict};examined=${result.examined};holds=${pairs.join(",")}`;
+}
+
+/**
+ * Decide whether this cycle has anything new to say, and say what changed.
+ *
+ * @param {string | null | undefined} previousFingerprint
+ * @param {object} result - A {@link classifyRollupBlockers} result.
+ * @returns {{ changed: boolean, fingerprint: string, summary: string }}
+ */
+export function describeRollupBlockerChange(previousFingerprint, result) {
+  const fingerprint = rollupBlockerFingerprint(result);
+  const previous = trimmedString(previousFingerprint);
+  if (previous.length === 0) {
+    return {
+      changed: true,
+      fingerprint,
+      summary: "First classification of this container.",
+    };
+  }
+  if (previous === fingerprint) {
+    return {
+      changed: false,
+      fingerprint,
+      summary:
+        "Unchanged since the last cycle — same items held, same classes. Nothing new to post.",
+    };
+  }
+
+  return {
+    changed: true,
+    fingerprint,
+    summary: `Changed since the last cycle: ${describeDelta(previous, fingerprint)}.`,
+  };
+}
+
+/**
+ * @param {string} previous
+ * @param {string} current
+ * @returns {string}
+ */
+function describeDelta(previous, current) {
+  const parse = fingerprint =>
+    new Map(
+      (fingerprint.split(";holds=")[1] ?? "")
+        .split(",")
+        .filter(pair => pair.length > 0)
+        .map(pair => {
+          const cut = pair.lastIndexOf(":");
+          return [pair.slice(0, cut), pair.slice(cut + 1)];
+        })
+    );
+  const before = parse(previous);
+  const after = parse(current);
+  const cleared = [...before.keys()].filter(ref => !after.has(ref));
+  const added = [...after.keys()].filter(ref => !before.has(ref));
+  const reclassified = [...after.entries()]
+    .filter(([ref, name]) => before.has(ref) && before.get(ref) !== name)
+    .map(([ref, name]) => `${ref} is now ${name} (was ${before.get(ref)})`);
+  const parts = [
+    cleared.length > 0 ? `${cleared.join(", ")} no longer held` : "",
+    added.length > 0 ? `${added.join(", ")} newly held` : "",
+    ...reclassified,
+  ].filter(part => part.length > 0);
+
+  return parts.length > 0 ? parts.join("; ") : "the rollup verdict itself";
+}
+
+/**
+ * @param {readonly string[]} argv
+ * @returns {number}
+ */
+export function runCli(argv) {
+  const args = new Map(
+    argv
+      .filter(arg => arg.startsWith("--"))
+      .map(arg => {
+        const eq = arg.indexOf("=");
+        return eq === -1
+          ? [arg.slice(2), "true"]
+          : [arg.slice(2, eq), arg.slice(eq + 1)];
+      })
+  );
+
+  const inputPath = args.get("input");
+  if (!inputPath) {
+    process.stderr.write(
+      "usage: rollup-blocker-classification.mjs --input=<file.json> [--since=<fingerprint>] [--json]\n"
+    );
+    return 2;
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(inputPath, "utf8"));
+  } catch (error) {
+    process.stderr.write(
+      `rollup-blocker-classification: NOT CLASSIFIED — could not read ${inputPath}: ${String(error?.message ?? error)}\n`
+    );
+    return 1;
+  }
+
+  const result = classifyRollupBlockers(payload);
+  const change = describeRollupBlockerChange(args.get("since"), result);
+  process.stdout.write(
+    args.get("json") === "true"
+      ? `${JSON.stringify({ ...result, change }, null, 2)}\n`
+      : `${renderRollupBlockerReport(result)}\n\n${change.summary}\n`
+  );
+
+  return result.ok ? 0 : 1;
+}
+
+/**
+ * True when `moduleUrl` names the module node was asked to run.
+ *
+ * Both sides are realpath'd. Reached through a symlinked checkout, a git
+ * worktree, or a `/tmp` path on macOS the naive comparisons disagree, the body
+ * never runs, and the process exits 0 having done nothing — and every
+ * Lisa-driven agent runs in a worktree, so that is the routine path.
+ *
+ * Written out rather than imported: this ships inside a plugin payload, which
+ * has no `./lib/` to resolve against.
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+export function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)));
+}

package/plugins/lisa-cursor/skills/lisa-github-sync/SKILL.md

@@ -108,7 +108,13 @@ If the `subIssues` field is unavailable (older GHES), fall back to body parentag
 | else any child has **started** (`status:in-progress`, or shipped to an env while a sibling has not) | `claimed` | `status:in-progress` |
 | else (children exist, none started) | — | unchanged — parent keeps its non-ready container label |
 
-- **Blocked dominates** — a single blocked child surfaces `status:blocked` on the parent even while siblings progress, so a human sees the parent needs attention.
+- **Blocked dominates — and the rollup must say which child and which kind** — a single blocked child surfaces `status:blocked` on the parent even while siblings progress, so a human sees the parent needs attention. `status:blocked` alone is a single bit and cannot tell a child waiting on an external event from one whose acceptance criteria are unbuildable; the second never clears on its own. Run the shared classifier over the resolved child graph before writing the label or the comment:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/rollup-blocker-classification.mjs" --input=<graph.json>
+```
+
+  Its report names, per class, the blocking leaf, the path to it (`#1495 -> #1515 -> #1547`) and **who must act** — that text goes in the rollup comment verbatim. It exits non-zero when it classified nothing (unreadable graph, no children, no readable child): treat that as a rollup that could not be derived and fall through to the **Safe default** below, never to "no blocked children". Never infer a class from prose and never apply the `spec_defect` marker from a flow — see `leaf-only-lifecycle` → **Classifying a hold**.
 - **Least-advanced env wins** — the parent reaches an env only when every required child has reached at least that env; it never sits ahead of its laggard child. Native closure (`gh issue close --reason completed`) fires only when the resolved env is the production `status:done`, never at `status:on-dev`/`status:on-stg`.
 - **"Required" children only** — a child labelled won't-do / optional does not hold the parent open; only leaves that must ship count toward the env-rollup check.
 - **Recursive** — a parent reaches an env only when its children have all reached at least that env; an Epic reaches it only when its Stories have themselves rolled up to it. Evaluate bottom-up.
@@ -116,7 +122,7 @@ If the `subIssues` field is unavailable (older GHES), fall back to body parentag
 
 **Single-environment collapse (this repo).** `.lisa.config.json` `deploy.branches` declares only `production: main`, so the env-keyed `done` resolves to the single label `status:done` — there is no `status:on-dev` / `status:on-stg` and **no dev → staging → prod promotion chain**. Resolve the env rungs via the env-keyed `done` logic in `config-resolution`, but in the single-environment case the only rung is production and it collapses to the one `status:done` value; the rollup never attempts to resolve a dev or staging `done`. Projects that DO have multiple environments keep the env-keyed map and roll the parent up to whichever `done` (including intermediate `status:on-dev`/`status:on-stg`) its leaves have collectively reached.
 
-**Apply the derived label** (only when it differs from the parent's current `status:*`): remove the parent's existing `status:*` label and add the derived one, keeping exactly one `status:*` label so the build-queue invariant holds. Post an idempotent `[claude-sync] rollup` comment naming the derived state and the child tally (e.g. `3/4 leaves terminal, 1 blocked → status:blocked`); skip the comment if an identical one is already the most recent rollup comment.
+**Apply the derived label** (only when it differs from the parent's current `status:*`): remove the parent's existing `status:*` label and add the derived one, keeping exactly one `status:*` label so the build-queue invariant holds. Post an idempotent `[claude-sync] rollup` comment naming the derived state and the child tally (e.g. `3/4 leaves terminal, 1 blocked → status:blocked`); when the derived state is `status:blocked` the comment also carries the classifier's per-class section, so the blocking child and its actor are one read rather than a descent. Skip the comment if an identical one is already the most recent rollup comment — the classifier's fingerprint is the dedupe key, and an unchanged verdict is not re-posted.
 
 ```bash
 gh issue edit <parent-number> --repo <org>/<repo> \

package/plugins/lisa-cursor/skills/lisa-jira-sync/SKILL.md

@@ -92,7 +92,7 @@ When invoked with `--rollup`, this skill **derives a parent/container ticket's s
 | else any child has **started** (`In Progress` / `Code Review`, or shipped to an env while a sibling has not) | `claimed` | `In Progress` |
 | else (children exist, none started) | — | unchanged — parent keeps its non-ready container status |
 
-- **Blocked dominates** — a single blocked child surfaces `Blocked` on the parent even while siblings progress.
+- **Blocked dominates** — a single blocked child surfaces `Blocked` on the parent even while siblings progress. It never says *which* child or *which kind* of hold; run `scripts/rollup-blocker-classification.mjs` over the resolved child graph and carry its per-class report — blocking leaf, path, and who must act — into the rollup note. A non-zero exit means it classified nothing; that is a failure to report, never an all-clear. See `leaf-only-lifecycle` → **Classifying a hold**.
 - **Least-advanced env wins** — the parent reaches an env only when every required child has reached at least that env; it never sits ahead of its laggard child. Apply native terminal resolution (the `leaf-only-lifecycle` Terminal native closure) only when the resolved env is the production `Done`, never at `On Dev`/`On Stg`.
 - **"Required" children only** — won't-do / optional children do not hold the parent open.
 - **Recursive** — an Epic reaches an env only when its Stories have themselves rolled up to at least that env; a Story reaches it only when its Sub-tasks have. Evaluate bottom-up.