@codyswann/lisa 4.11.2 → 4.12.0

package/plugins/src/base/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/src/base/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/src/base/rules/eager/leaf-only-lifecycle.md

@@ -26,6 +26,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/src/base/rules/reference/config-resolution.md

@@ -462,11 +462,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`.
 
@@ -475,9 +476,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.

package/plugins/src/base/rules/reference/leaf-only-lifecycle.md

@@ -74,12 +74,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.