@codyswann/lisa 4.11.2 → 4.12.0

package/plugins/lisa-copilot/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-copilot/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.

package/plugins/lisa-copilot/skills/lisa-linear-sync/SKILL.md

@@ -125,7 +125,7 @@ When the caller passes `--rollup`, this skill **derives a parent/container's wor
 | else any child has **started** (`In Progress` / `In 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 state |
 
-- **Blocked dominates** — one blocked child surfaces `Blocked` on the parent even while siblings progress.
+- **Blocked dominates** — one 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. Native completion (moving the workflow `state` to Done) fires only when the resolved env is the production `Done`, never at `On Dev`/`On Stg`.
 - **"Required" children only** — won't-do / optional (e.g. `Canceled`) children do not hold the parent open.
 - **Recursive** — a Project reaches an env only when its Issues have themselves rolled up to at least that env. Evaluate bottom-up.

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

@@ -687,11 +687,41 @@ left in a status it should not carry, including a stale build-ready `ready`).
    them (e.g. all `On Stg` → `On Stg`); else any child started → `claimed`; else unchanged.
    Optional / won't-do / not-planned children are terminal-but-dropped and do not hold the parent
    open.
+2a. **When the derived state is `blocked`, classify the holds before writing anything.** A bare
+   `blocked` on a container is a single bit, and it cannot tell a hold that waits on an external
+   event from one that waits on a person rewriting an acceptance criterion — the second never
+   clears on its own, so rendering them alike lets it accumulate silently (`leaf-only-lifecycle` →
+   **Classifying a hold**; #3045). Feed the resolved child graph to the shared classifier:
+
+```bash
+ROLLUP_DIR="$(mktemp -d)"
+# children[]: { ref, state, labels[], blockedBy[{ref, open}], children[] } — the graph
+# step 1 already resolved, nested as deep as it was read. The script probes nothing.
+jq -n --slurpfile g "$ROLLUP_DIR/graph.json" \
+      '{container: $g[0].container, children: $g[0].children, readError: $g[0].readError}' \
+  > "$ROLLUP_DIR/input.json"
+
+node "${CLAUDE_PLUGIN_ROOT}/scripts/rollup-blocker-classification.mjs" \
+  --input="$ROLLUP_DIR/input.json" --since="<last recorded fingerprint>"
+```
+
+   It **exits non-zero and classifies nothing** when the tracker could not be read, the container
+   has no children, or no child was readable. That is a repair failure to report, never an
+   all-clear: do not fall through to "no blocked children" on a non-zero exit. On success its
+   report names, per class, the blocking leaf, the path to it, and **who must act** — those lines
+   are what goes in the rollup note, verbatim. Never set the `spec_defect` marker yourself and
+   never infer a class from prose; a hold with nothing recorded classifies `unknown`, and the
+   report already asks a person to decide.
+
 3. **If the derived state differs from the parent's current state, apply it** via the vendor's
    lifecycle write (JIRA transition, GitHub/Linear label swap keeping exactly one `status:*`),
    removing any conflicting stale build lifecycle role — **including a stale `ready`** the parent
    should never carry. Post an idempotent `[lisa-repair-intake]` rollup note naming the derived
-   state and the child tally (honor the backoff window + fingerprint).
+   state and the child tally (honor the backoff window + fingerprint). **When the derived state is
+   `blocked`, the note carries the classifier's per-class report** — the blocking leaf, its path,
+   and its actor — so an operator never descends the tree by hand to find out which item and which
+   kind. Use the classifier's `change.summary` as the dedupe test: an unchanged verdict has nothing
+   new to say and the note is **not** re-posted.
 4. **Perform native closure only at the true terminal `done`.** When — and only when — the derived
    env is the production/terminal value, finalize through the provider-native mechanism (GitHub
    `gh issue close --reason completed`, Linear move to Done state, JIRA resolved/closed verified at

package/plugins/lisa-copilot/skills/lisa-tracker-sync/SKILL.md

@@ -38,7 +38,7 @@ The state machine (first match wins, evaluated over the **required** leaves only
 | else any leaf has **started** (claimed or in review, or shipped while a sibling has not) | active / in-progress | `claimed` (or `review` where supported) |
 | else (leaves exist, none started) | unchanged | — |
 
-- **Blocked dominates** — one blocked leaf surfaces blocked on the parent even while others progress.
+- **Blocked dominates** — one blocked leaf surfaces blocked on the parent even while others 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** — a parent reaches an env only once all required leaves have reached at least that env (all `On Stg` → `On Stg`; mixed dev/staging → the dev value). Native terminal closure fires only at the production `done`, never at an intermediate env.
 - **The parent never carries `ready`** — `ready` is a human "claim this leaf" signal; rollup only moves a parent between non-ready container states.
 - **Rollup is recursive** — an Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up.

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

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

package/plugins/lisa-cursor/hooks/failure-signature-index.mjs

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+/**
+ * Make a hazard reachable from its EFFECT, not only from its cause.
+ *
+ * ## The defect this exists against
+ *
+ * A hazard recorded in a comment beside the code that causes it is invisible to
+ * the person who meets its effect. They search where it *surfaced*; the note
+ * lives where it *originates*, in a different file owned by a different
+ * concern. Knowing to open that file requires already knowing the cause, which
+ * is the one thing they do not have. Measured on one hazard in this repository:
+ * three independent discoveries, two of them already correctly documented, and
+ * the third still cost a wrong hypothesis carried for hours plus instrumentation
+ * written from scratch to measure what was already written down
+ * (CodySwannGT/lisa#3054, CodySwannGT/lisa#3060, CodySwannGT/lisa#3061).
+ *
+ * A fourth sighting is the same shape one turn further on: the hazard was not
+ * merely documented but GUARDED, and the guard was equally unreachable, so the
+ * proposed remedy was a second control for a condition one control already
+ * covered. Two checks for one condition, drifting apart, each making the other
+ * look redundant — worse than the wasted diagnosis. Hence `guard` on an entry.
+ *
+ * ## Why an index and not more prose
+ *
+ * The natural fix — "search harder", or "record cross-cutting hazards
+ * centrally" — is a retrieval strategy that requires already knowing the
+ * answer, and this repository's own measurement is that prose rules land at
+ * roughly zero adoption while executable controls land at 100%.
+ *
+ * So this stores no knowledge. Every entry is a **routing table row**: the text
+ * a person actually sees, and a pointer to the record that already explains it.
+ * The records are not moved, copied, or rewritten — they stay next to the cause,
+ * where they are correct and useful to the reader who is already in that file.
+ *
+ * ## How it gets read
+ *
+ * By the person standing in the symptom, without them going to look:
+ *
+ *   1. `--hook` runs as a PostToolUse hook on every Bash result. When a
+ *      command's output matches a signature, the notice arrives attached to the
+ *      failure itself. Nobody has to know this file exists.
+ *   2. `--match` accepts any transcript on stdin, so a gate runner or a person
+ *      can ask the same question of any output.
+ *
+ * That is deliberately the whole reader set. An index with a browsing surface
+ * is an index nobody reads.
+ *
+ * ## Why it cannot rot into a decoration
+ *
+ * `--check` refuses three ways, and each one is a way this could otherwise
+ * report all-clear while indexing nothing:
+ *
+ *   - an entry whose cited record no longer contains its anchor — the pointer
+ *     rotted, which is exactly what happened to the reference that named
+ *     `src/cli/doctor-learnings-merge-driver.ts` before it was renamed;
+ *   - an entry whose `signature` does not match its own recorded `sample` — a
+ *     regex typo silently disables an entry, the same way a malformed ERE
+ *     silently disabled a project safety rule in `parity-safety-net.sh`;
+ *   - an index that resolves ZERO entries — an empty routing table is a broken
+ *     one, never a clean one.
+ *
+ * ## What deliberately does NOT belong here
+ *
+ * A hazard with no machine-recognisable symptom. `grep` answering three ways so
+ * a `printf | grep -q` guard permits a catastrophic delete
+ * (CodySwannGT/lisa#3054, CodySwannGT/lisa#3188) has no signature at all — its
+ * symptom is silence. There is nothing for this to match, and an entry
+ * pretending otherwise would be a row that can never fire. Such hazards belong
+ * on the learnings ladder as executable controls, not here.
+ *
+ * The ledger at `.lisa/PROJECT_LEARNINGS.md` is also not this. It is capped at
+ * twenty entries and rotates by design; a routing table that evicts rows is a
+ * routing table that stops routing.
+ * @module failure-signature-index
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Repository-root filename holding the index. */
+export const INDEX_FILENAME = "failure-signatures.json";
+
+/**
+ * Longest transcript tail examined, in bytes.
+ *
+ * Bounded because this parses arbitrary command output inside a hook on every
+ * Bash call. The tail rather than the head: a build that fails after printing
+ * ten megabytes of progress puts the sentence that matters last.
+ */
+const MAX_SCAN_BYTES = 512 * 1024;
+
+/** Most entries reported for one output, so a match is a notice and not a wall. */
+const MAX_REPORTED = 2;
+
+/** Fields every entry must carry, with a non-empty string in each. */
+const REQUIRED_TEXT_FIELDS = Object.freeze([
+  "id",
+  "symptom",
+  "sample",
+  "signature",
+  "cause",
+]);
+
+/**
+ * One row of the routing table.
+ * @typedef {object} SignatureEntry
+ * @property {string} id Stable slug naming the hazard.
+ * @property {string} symptom One line: what the person actually sees.
+ * @property {string} sample Verbatim excerpt of real output, which `signature`
+ *   must match — the proof that the row can ever fire.
+ * @property {string} signature `RegExp` source matched against command output.
+ * @property {string} cause One line: what is really happening.
+ * @property {readonly {file: string, anchor: string}[]} records Where the
+ *   explanation already lives. Never moved here; only pointed at.
+ * @property {{file: string, anchor: string, name: string}} [guard] The control
+ *   that already covers this, when one exists, so nobody builds a second.
+ */
+
+/**
+ * The repository root, falling back to the working directory outside git.
+ * @param {string} [cwd] Directory to resolve from.
+ * @returns {string} An absolute path.
+ */
+export function repoRoot(cwd = process.cwd()) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+/**
+ * Read and parse the index.
+ * @param {string} root Repository root.
+ * @returns {{entries: readonly SignatureEntry[], error: string|null}} The rows,
+ *   or the reason there are none.
+ */
+export function loadIndex(root) {
+  const file = path.join(root, INDEX_FILENAME);
+  if (!fs.existsSync(file)) {
+    return { entries: [], error: `${INDEX_FILENAME} does not exist` };
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    const entries = Array.isArray(parsed) ? parsed : parsed?.entries;
+    if (!Array.isArray(entries)) {
+      return { entries: [], error: `${INDEX_FILENAME} has no entries array` };
+    }
+    return { entries, error: null };
+  } catch (cause) {
+    return {
+      entries: [],
+      error: `${INDEX_FILENAME} is not valid JSON: ${cause}`,
+    };
+  }
+}
+
+/**
+ * Compile an entry's signature.
+ * @param {SignatureEntry} entry The row.
+ * @returns {RegExp|null} The pattern, or null when it does not compile.
+ */
+function compile(entry) {
+  try {
+    return new RegExp(entry.signature);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The 1-based line an anchor sits on.
+ * @param {string} root Repository root.
+ * @param {{file: string, anchor: string}} record The pointer.
+ * @returns {number|null} The line, or null when the anchor is not present.
+ */
+export function anchorLine(root, record) {
+  const file = path.join(root, record.file);
+  if (!fs.existsSync(file)) return null;
+  const lines = fs.readFileSync(file, "utf8").split("\n");
+  const found = lines.findIndex(line => line.includes(record.anchor));
+  return found === -1 ? null : found + 1;
+}
+
+/**
+ * Every complaint one entry earns.
+ * @param {SignatureEntry} entry The row.
+ * @param {string} root Repository root.
+ * @returns {string[]} Human-readable problems, empty when the row resolves.
+ */
+function entryProblems(entry, root) {
+  const label = entry?.id ?? "<entry with no id>";
+  const missing = REQUIRED_TEXT_FIELDS.filter(
+    field => typeof entry?.[field] !== "string" || entry[field].length === 0
+  ).map(field => `${label}: "${field}" is missing or empty`);
+  const pattern = compile(entry ?? {});
+  const patternProblems =
+    pattern === null
+      ? [`${label}: "signature" is not a valid regular expression`]
+      : pattern.test(String(entry.sample ?? ""))
+        ? []
+        : [
+            `${label}: "signature" does not match its own "sample", so this row can never fire`,
+          ];
+  const records = Array.isArray(entry?.records) ? entry.records : [];
+  const recordProblems =
+    records.length === 0
+      ? [`${label}: has no "records", so it points at no existing explanation`]
+      : records
+          .filter(record => anchorLine(root, record) === null)
+          .map(
+            record =>
+              `${label}: record ${record.file} no longer contains "${record.anchor}" — the pointer rotted`
+          );
+  const guardProblems =
+    entry?.guard && anchorLine(root, entry.guard) === null
+      ? [
+          `${label}: guard ${entry.guard.file} no longer contains "${entry.guard.anchor}" — the pointer rotted`,
+        ]
+      : [];
+  return [...missing, ...patternProblems, ...recordProblems, ...guardProblems];
+}
+
+/**
+ * Check every row, and refuse an index that routes nothing.
+ * @param {readonly SignatureEntry[]} entries The rows.
+ * @param {string} root Repository root.
+ * @returns {{problems: string[], resolved: number}} What is wrong, and how many
+ *   rows survived.
+ */
+export function validateIndex(entries, root) {
+  const duplicated = entries
+    .map(entry => entry?.id)
+    .filter((id, at, all) => all.indexOf(id) !== at)
+    .map(id => `${id}: duplicate id`);
+  const perEntry = entries.flatMap(entry => entryProblems(entry, root));
+  const resolved = entries.filter(
+    entry => entryProblems(entry, root).length === 0
+  ).length;
+  const empty =
+    resolved === 0
+      ? [
+          `${INDEX_FILENAME} resolves ZERO entries — an index that indexes nothing is broken, not clean`,
+        ]
+      : [];
+  return {
+    problems: [...duplicated, ...perEntry, ...empty],
+    resolved,
+  };
+}
+
+/**
+ * The rows whose signature appears in some output.
+ * @param {string} text Command output.
+ * @param {readonly SignatureEntry[]} entries The rows.
+ * @returns {SignatureEntry[]} Matches, in index order, capped.
+ */
+export function matchEntries(text, entries) {
+  const scanned =
+    text.length > MAX_SCAN_BYTES ? text.slice(-MAX_SCAN_BYTES) : text;
+  return entries
+    .filter(entry => {
+      const pattern = compile(entry);
+      return pattern !== null && pattern.test(scanned);
+    })
+    .slice(0, MAX_REPORTED);
+}
+
+/**
+ * The notice a matched row prints.
+ *
+ * Worded to stop a rediscovery rather than to start one: it names the cause
+ * outright, cites the record with a line number so it is one click away, and
+ * says explicitly that the diagnosis is already done.
+ * @param {SignatureEntry} entry The matched row.
+ * @param {string} root Repository root.
+ * @returns {string} An operator-readable block.
+ */
+export function formatNotice(entry, root) {
+  const records = entry.records.map(record => {
+    const line = anchorLine(root, record);
+    return `    - ${record.file}${line === null ? "" : `:${line}`}`;
+  });
+  const guard =
+    entry.guard === undefined
+      ? []
+      : [
+          `  ALREADY GUARDED by ${entry.guard.name} (${entry.guard.file}) — do NOT build a second control for this.`,
+        ];
+  return [
+    `  ${entry.id}`,
+    `  Symptom: ${entry.symptom}`,
+    `  Cause:   ${entry.cause}`,
+    `  This is already written down, next to the cause:`,
+    ...records,
+    ...guard,
+    `  Read those before diagnosing this yourself.`,
+  ].join("\n");
+}
+
+/**
+ * The whole report for one output.
+ * @param {readonly SignatureEntry[]} matched Rows that fired.
+ * @param {string} root Repository root.
+ * @returns {string} The report, empty when nothing fired.
+ */
+export function formatReport(matched, root) {
+  if (matched.length === 0) return "";
+  return [
+    "Lisa failure-signature index — this output matches a KNOWN hazard whose",
+    "explanation already exists in this repository:",
+    "",
+    ...matched.map(entry => formatNotice(entry, root)),
+  ].join("\n");
+}
+
+/**
+ * Everything a Bash PostToolUse payload said, as one string.
+ *
+ * Shallow and string-only on purpose: the payload shape differs between agents
+ * and between tools, and a matcher that walks arbitrary nesting would start
+ * matching on file contents a command merely read.
+ * @param {object} payload The parsed hook stdin.
+ * @returns {string} Output text, empty when there is none.
+ */
+export function outputText(payload) {
+  const response = payload?.tool_response;
+  if (typeof response === "string") return response;
+  return ["stdout", "stderr", "error", "output"]
+    .map(field => response?.[field])
+    .filter(value => typeof value === "string")
+    .join("\n");
+}
+
+/**
+ * Whether a command is about the index itself.
+ *
+ * A `cat failure-signatures.json` contains every sample by construction, so
+ * without this the index fires on anyone reading it. One noisy false positive
+ * teaches people to ignore the notice, which is the whole failure mode.
+ * @param {object} payload The parsed hook stdin.
+ * @returns {boolean} Whether to stay silent.
+ */
+export function isSelfReferential(payload) {
+  const command = payload?.tool_input?.command;
+  return typeof command === "string" && command.includes("failure-signature");
+}
+
+/**
+ * Read all of stdin.
+ * @returns {Promise<string>} What was piped in.
+ */
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * The `--check` mode: prove the index still routes.
+ * @param {string} root Repository root.
+ * @returns {number} An exit code.
+ */
+export function runCheck(root) {
+  const { entries, error } = loadIndex(root);
+  if (error !== null) {
+    process.stderr.write(`failure-signature index: ${error}\n`);
+    return 1;
+  }
+  const { problems, resolved } = validateIndex(entries, root);
+  if (problems.length > 0) {
+    process.stderr.write(
+      `failure-signature index: ${problems.length} problem(s)\n` +
+        problems.map(problem => `  - ${problem}\n`).join("")
+    );
+    return 1;
+  }
+  process.stdout.write(
+    `failure-signature index: ${resolved} entr${resolved === 1 ? "y resolves" : "ies resolve"} to a live record\n`
+  );
+  return 0;
+}
+
+/**
+ * The `--hook` mode: teach at the moment of failure.
+ *
+ * Advisory by construction — always exit 0. The hazard has already happened;
+ * blocking the agent here would punish it for meeting a symptom.
+ * @param {string} raw The hook's stdin.
+ * @param {string} root Repository root.
+ * @returns {number} An exit code.
+ */
+export function runHook(raw, root) {
+  const payload = (() => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  })();
+  if (payload === null || isSelfReferential(payload)) return 0;
+  const { entries } = loadIndex(root);
+  const report = formatReport(matchEntries(outputText(payload), entries), root);
+  if (report.length === 0) return 0;
+  process.stderr.write(`${report}\n`);
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: report,
+      },
+    })}\n`
+  );
+  return 0;
+}
+
+/**
+ * The `--match` mode: ask the same question of any transcript.
+ * @param {string} text The transcript.
+ * @param {string} root Repository root.
+ * @returns {number} An exit code.
+ */
+export function runMatch(text, root) {
+  const { entries } = loadIndex(root);
+  const report = formatReport(matchEntries(text, entries), root);
+  if (report.length === 0) return 0;
+  process.stdout.write(`${report}\n`);
+  return 0;
+}
+
+/**
+ * Dispatch on the requested mode.
+ * @param {readonly string[]} argv Command-line arguments.
+ * @param {string} raw Piped stdin, when the mode needs it.
+ * @param {string} root Repository root.
+ * @returns {number} An exit code.
+ */
+export function main(argv, raw, root) {
+  if (argv.includes("--hook")) return runHook(raw, root);
+  if (argv.includes("--match")) return runMatch(raw, root);
+  return runCheck(root);
+}
+
+/**
+ * Whether this module is the process entry point.
+ *
+ * Both sides are realpath'd. Comparing `fileURLToPath(import.meta.url)` against
+ * `path.resolve(process.argv[1])` disagrees whenever the checkout is reached
+ * through a symlink — a git worktree, or any `/tmp` path on macOS, `/tmp` being
+ * a symlink to `/private/tmp` — because `import.meta.url` is the REAL path
+ * while `argv[1]` is whatever the caller typed. For a CHECK that is a
+ * fail-OPEN: no output, exit 0, the npm script "succeeds", and the gate
+ * silently stops having an opinion.
+ *
+ * The one implementation lives at `scripts/lib/invoked-as-script.mjs`. This
+ * file cannot import it: it is materialized into every plugin payload, where
+ * there is no `./lib/` to import from — the same accommodation
+ * `threshold-ratchet.mjs` makes, for the same reason.
+ * @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 fs.realpathSync(argv1) === fs.realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const needsStdin = argv.includes("--hook") || argv.includes("--match");
+  const raw = needsStdin ? await readStdin() : "";
+  process.exitCode = main(argv, raw, repoRoot());
+}

package/plugins/lisa-cursor/hooks/failure-signature-index.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# PostToolUse hook for Bash: the failure-signature index.
+#
+# A hazard recorded beside its cause is unreachable from its effect — the
+# searcher does not yet know which concern owns the cause, so "search harder"
+# is a retrieval strategy that requires already knowing the answer
+# (CodySwannGT/lisa#3061). This hook closes that gap from the only direction
+# that works: it reads the output of the command that just ran and, when that
+# output matches a known hazard, names the record that already explains it.
+#
+# Advisory by construction — ALWAYS exit 0. The hazard has already happened;
+# blocking an agent here would punish it for meeting a symptom. Every
+# infrastructure gap (no node, no git repo, unreadable stdin, no index) is also
+# exit 0: a broken hook must never wedge a session, and `check:failure-signatures`
+# is what guarantees the index still routes.
+set -uo pipefail
+
+input="$(cat)"
+
+command -v node >/dev/null 2>&1 || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+printf '%s' "$input" | node "$script_dir/failure-signature-index.mjs" --hook || true
+exit 0

package/plugins/lisa-cursor/hooks/hooks.json

@@ -11,6 +11,10 @@
         "command": "${CURSOR_PLUGIN_ROOT}/hooks/shell-write-nudge.sh",
         "matcher": "Bash"
       },
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/hooks/failure-signature-index.sh",
+        "matcher": "Bash"
+      },
       {
         "command": "${CURSOR_PLUGIN_ROOT}/hooks/threshold-ratchet.sh",
         "matcher": "Edit|Write|NotebookEdit|Bash"

package/plugins/lisa-cursor/rules/config-resolution-reference.mdc

@@ -467,11 +467,12 @@ Every lifecycle skill operates on a fixed set of **roles** (`ready`, `claimed`,
 
 #### Build markers (additive labels, not lifecycle roles)
 
-A **marker** is an additive label applied *alongside* a lifecycle role, not a state the item transitions *to*. Markers carry no rollup or transition semantics — they annotate an item that is already in some role. The build lifecycle defines one marker:
+A **marker** is an additive label applied *alongside* a lifecycle role, not a state the item transitions *to*. Markers carry no rollup or transition semantics — they annotate an item that is already in some role, and the rollup reads them to say *which kind* of hold a `blocked` item is (`rollup-blocker-classification`). The build lifecycle defines two markers:
 
 | Marker | What it means | JIRA default | GitHub/Linear default |
 |---|---|---|---|
 | `human_needed` | Applied with `blocked` when — **after the agent has drafted every authorable missing section via the `pre-flight-autofill` procedure** — the block still requires a human to confirm the drafted assumptions or supply something no agent can invent: real missing credentials, access/permissions, or an irreducible product/scoping decision. | `Human Needed` (label) | `human-needed` (label) |
+| `spec_defect` | Applied with `blocked` when the thing holding the item is the item's **own specification** — an acceptance criterion that cannot be satisfied as written, a field naming an environment or surface the project does not have, a validation journey demanding something the project cannot produce. **Human-applied only.** No agent sets it, because judging a criterion unbuildable is a product call, and the agent that wrote a bad criterion is the least likely to know it did. | `Spec Defect` (label) | `blocked:spec-defect` (label) |
 
 Markers are labels on **every** vendor, Linear included — that is the one place the Linear build lane still touches `linear.labels`.
 
@@ -480,9 +481,14 @@ Resolution keys:
 - JIRA: `jira.labels.human_needed` (default `Human Needed`). Applied as a JIRA **label** — not a workflow status — because an item holds exactly one status but any number of labels. The `blocked` status still drives the lifecycle; `human_needed` is the additive marker on top of it.
 - GitHub: `github.labels.build.human_needed` (default `human-needed`). Added next to the `blocked` label.
 - Linear: `linear.labels.build.human_needed` (default `human-needed`). Applied as a Linear **label**, for the same reason as JIRA — an Issue holds exactly one workflow state but any number of labels, so an additive marker cannot be a state. The `blocked` **state** still drives the lifecycle; `human_needed` is the marker on top of it. This is the only build-lane key left in `linear.labels`.
+- `spec_defect` resolves the same way on each vendor — `jira.labels.spec_defect` (default `Spec Defect`), `github.labels.build.spec_defect` and `linear.labels.build.spec_defect` (default `blocked:spec-defect`).
 
 **When to apply it.** Apply `human_needed` only when a human must act before the item can move — the pre-flight gate failures that bounce a ticket back to its reporter are exactly this case, but **only after** the agent has run the `pre-flight-autofill` draft-then-block procedure (drafting the authorable gaps — acceptance criteria, validation journey, repository, relationship search, etc. — into the ticket as labeled assumptions). What then remains for the human is to **confirm those assumptions** or supply a genuinely human-only input (real missing credentials, an irreducible product/scoping decision). The marker means "a human must confirm or decide," not "a human must author from scratch."
 
+**Why `spec_defect` is separate from `human_needed`.** Both name a hold a person must clear, but they are different asks and the rollup must not merge them. `human_needed` waits on an input from *outside* the item — a credential, an access grant, a product decision — and the item's own text is fine. `spec_defect` waits on the item's text being *rewritten*, and no external event will ever supply that. An item carrying `spec_defect` will sit forever until somebody edits it; that is exactly the class that accumulated silently when the rollup rendered both as plain `blocked` (issue #3045: 32 identical hold comments over six weeks on one Epic). Where both markers are present, `spec_defect` wins — it is the more specific record, and the only one carrying a judgment nothing else can supply.
+
+**Nothing infers `spec_defect`.** It is never derived from prose, a title, or a failed gate. A `blocked` item carrying neither marker and no open `is blocked by` link classifies as **`unknown`**, and the rollup says so and asks a person to decide — an honest `unknown` beats a confident wrong answer, and auto-reclassifying would turn a human product call into a guess.
+
 **When NOT to apply it.** Do **not** apply `human_needed` to a block that an automated cycle can clear on its own: a block whose `is blocked by` dependency is another tracked ticket that will build and close (for example a `repair-intake`-filed build-ready fix ticket for an unmergeable PR or a failed deploy), or any block waiting only on a retry. Those self-heal; flagging them for a human is noise. If such an item already carries a stale `human_needed` marker, clear it when the block becomes auto-recoverable.
 
 The marker is **best-effort and additive**: it never replaces the `blocked` role and never gates a transition. A project that does not define the label name inherits the defaults above; a project that does not want the marker at all can leave the label absent in its tracker, in which case the add is a no-op the agent records and moves on.