@codyswann/lisa 2.96.0 → 2.97.1

package/README.md

@@ -79,6 +79,10 @@ Most users only ever call `/lisa:research`, `/lisa:plan`, and `/lisa:implement`.
 | Command | What it does |
 | --- | --- |
 | `/lisa:intake <queue-url>` | Scans a Ready queue (Notion PRD database, JIRA project, GitHub repo, Linear team, Confluence space) and dispatches each item through the right lifecycle command. Designed as the cron target for unattended runs. |
+| `/lisa:queue-status [queue=prd|queue=build]` | Read-only queue inspection for the current repo. Distinguishes idle vs misconfigured queues, highlights the most actionable item, and points operators to `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, or `/lisa:verify-prd`. |
+| `/lisa:repair-intake <queue-url>` | Read/write recovery scan for blocked, stale, or inconsistent queue state when normal intake is not the right next move. |
+| `/lisa:automation-status` | Read-only inspection of the repo's expected Lisa automation fleet so operators can distinguish empty queues from stale, drifted, or failing scheduler jobs. |
+| `/lisa:verify-prd <prd>` | Initiative-level acceptance pass for shipped PRDs. Verifies the shipped surface against the PRD and reopens to ticketed with fix work on failure. |
 
 PRD intake records generated work with native hierarchy where the source and tracker support it, and with a durable generated-work fallback everywhere else. The vendor matrix for GitHub, Linear, JIRA/Atlassian, Confluence, Notion, and cross-vendor queues lives in `plugins/src/base/rules/prd-lifecycle-rollup.md`.
 

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

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

package/plugins/lisa/.codex-plugin/plugin.json

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

package/plugins/lisa/commands/queue-status.md

@@ -10,4 +10,25 @@ Common operator usage:
 - `/lisa:queue-status queue=prd`
 - `/lisa:queue-status queue=build`
 
-This surface is read-only in v1. Use it to understand whether the repo's PRD and build queues are idle, healthy, attention-needed, or misconfigured before deciding whether to run `/lisa:intake`, `/lisa:repair-intake`, or deeper tracker-native investigation.
+Use this when you need to answer:
+
+- Is the queue actually idle, or is Lisa misconfigured?
+- Which queue item is the most actionable next?
+- Should the next command be `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, or `/lisa:verify-prd`?
+
+This surface is read-only in v1. Use it to understand whether the repo's PRD and build queues are idle, healthy, attention-needed, or misconfigured before deciding whether to run `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, `/lisa:verify-prd`, or deeper tracker-native investigation.
+
+Quick interpretation guide:
+
+- `IDLE`: the queue resolved correctly and nothing actionable is waiting. No immediate Lisa action is required.
+- `HEALTHY`: the queue resolved correctly and normal work is present. Follow the highlighted next step, usually `/lisa:intake`.
+- `ATTENTION_NEEDED`: blocked, stalled, or aging work needs operator follow-up. Use the highlighted item and remediation hint to choose the next command, usually `/lisa:repair-intake`.
+- `MISCONFIGURED`: queue resolution or lifecycle adoption is broken. Fix config, labels/statuses, or scheduler drift before trusting queue state.
+
+Highlighted-item semantics:
+
+- A highlighted item is the single oldest or most actionable queue item for that section, not a full dump of all matching work.
+- `ready` highlights usually point to `/lisa:intake`.
+- `blocked`, stalled, or long-claimed highlights usually point to `/lisa:repair-intake`.
+- Shipped PRD highlights usually point to `/lisa:verify-prd`.
+- If queue behavior looks wrong for both PRD and build lanes, inspect `/lisa:automation-status` before assuming the queue itself is the problem.

package/plugins/lisa/scripts/queue-status-prd-readers.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * Shared PRD-side queue readers for `/lisa:queue-status`.
+ *
+ * These helpers normalize vendor-specific PRD lifecycle items into a common
+ * snapshot shape so queue-status can report lifecycle counts, actionable
+ * highlights, and queue-health verdict inputs without drifting from Lisa's PRD
+ * lifecycle contract.
+ */
+
+import { classifyQueueHealth } from "./queue-health-classification.mjs";
+
+export const PRD_LIFECYCLE_ORDER = [
+  "draft",
+  "ready",
+  "in_review",
+  "blocked",
+  "ticketed",
+  "shipped",
+  "verified",
+];
+
+const ACTIONABLE_ROLE_ORDER = [
+  "blocked",
+  "in_review",
+  "shipped",
+  "ready",
+  "ticketed",
+];
+
+const HIGHLIGHT_COPY = {
+  blocked: {
+    summary: "Oldest blocked PRD",
+    nextStep: "Run /lisa:repair-intake <queue> after clarifying the blocker.",
+  },
+  in_review: {
+    summary: "Oldest PRD still in review",
+    nextStep:
+      "Inspect the active intake run or resume it with /lisa:repair-intake <queue>.",
+  },
+  shipped: {
+    summary: "Oldest shipped PRD awaiting verification",
+    nextStep: "Run /lisa:verify-prd <item-url> to close the shipped loop.",
+  },
+  ready: {
+    summary: "Oldest ready PRD awaiting intake",
+    nextStep: "Run /lisa:intake <queue> to ticket the next PRD.",
+  },
+  ticketed: {
+    summary: "Oldest ticketed PRD still waiting on downstream delivery",
+    nextStep:
+      "Monitor downstream build work or inspect the build queue with /lisa:queue-status queue=build.",
+  },
+};
+
+/**
+ * Read a GitHub-backed PRD queue snapshot from issue payloads.
+ *
+ * @param {{
+ *   readonly issues?: readonly Record<string, any>[]
+ *   readonly roles?: Record<string, string>
+ *   readonly namespaceAdopted?: boolean
+ *   readonly queueResolved?: boolean
+ *   readonly queueArgument?: string
+ *   readonly resolutionError?: string | null
+ * }} input
+ */
+export function readGithubPrdQueueSnapshot(input = {}) {
+  const roles = input.roles ?? {};
+  const normalizedItems = (input.issues ?? [])
+    .map(issue => normalizeGithubPrdIssue(issue, roles))
+    .filter(Boolean);
+
+  return createPrdQueueSnapshot({
+    source: "github",
+    items: normalizedItems,
+    roles,
+    namespaceAdopted: input.namespaceAdopted,
+    queueResolved: input.queueResolved,
+    queueArgument: input.queueArgument,
+    resolutionError: input.resolutionError,
+  });
+}
+
+/**
+ * Build a vendor-agnostic PRD queue snapshot from normalized lifecycle items.
+ *
+ * @param {{
+ *   readonly source?: string
+ *   readonly items?: readonly Record<string, any>[]
+ *   readonly roles?: Record<string, string>
+ *   readonly namespaceAdopted?: boolean
+ *   readonly queueResolved?: boolean
+ *   readonly queueArgument?: string
+ *   readonly resolutionError?: string | null
+ * }} input
+ */
+export function createPrdQueueSnapshot(input = {}) {
+  const rawRoles = input.roles ?? {};
+  const roles = normalizeRoles(rawRoles);
+  const items = normalizeItems(input.items);
+  const counts = buildLifecycleCounts(items);
+  const highlights = buildActionableHighlights(items, input.queueArgument);
+  const queueResolved =
+    input.queueResolved ?? typeof input.resolutionError !== "string";
+  const namespaceAdopted =
+    input.namespaceAdopted ?? inferNamespaceAdopted(items, rawRoles);
+
+  const health = classifyQueueHealth({
+    queueResolved,
+    namespaceAdopted,
+    readyCount: counts.ready,
+    activeCount: counts.in_review + counts.ticketed,
+    blockedCount: counts.blocked,
+    stalledCount: counts.shipped,
+    resolutionError: input.resolutionError ?? null,
+  });
+
+  return {
+    source: input.source ?? "unknown",
+    queueResolved,
+    namespaceAdopted,
+    roles,
+    counts,
+    highlights,
+    health,
+    resolutionError: input.resolutionError ?? null,
+  };
+}
+
+/**
+ * @param {Record<string, any>} issue
+ * @param {Record<string, string>} roles
+ * @returns {Record<string, any> | null}
+ */
+function normalizeGithubPrdIssue(issue, roles) {
+  if (!issue || typeof issue !== "object") {
+    return null;
+  }
+
+  const role = resolveGithubPrdRole(issue.labels, roles);
+
+  return normalizeItem({
+    id: String(issue.id ?? issue.number ?? issue.url ?? issue.title ?? ""),
+    ref:
+      issue.number !== undefined && issue.number !== null
+        ? `#${issue.number}`
+        : String(issue.url ?? issue.title ?? ""),
+    title: String(issue.title ?? "").trim(),
+    url: typeof issue.url === "string" ? issue.url : null,
+    createdAt: issue.createdAt ?? null,
+    updatedAt: issue.updatedAt ?? null,
+    role,
+  });
+}
+
+/**
+ * @param {readonly any[] | undefined} labels
+ * @param {Record<string, string>} roles
+ * @returns {string | null}
+ */
+function resolveGithubPrdRole(labels, roles) {
+  if (!Array.isArray(labels)) {
+    return null;
+  }
+
+  const labelNames = new Set(
+    labels
+      .map(label =>
+        typeof label === "string"
+          ? label
+          : typeof label?.name === "string"
+            ? label.name
+            : null
+      )
+      .filter(Boolean)
+  );
+
+  for (const role of PRD_LIFECYCLE_ORDER) {
+    const configuredName = roles[role];
+    if (configuredName && labelNames.has(configuredName)) {
+      return role;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {Record<string, string> | undefined} roles
+ * @returns {Record<string, string>}
+ */
+function normalizeRoles(roles) {
+  const normalized = {};
+
+  for (const role of PRD_LIFECYCLE_ORDER) {
+    normalized[role] =
+      typeof roles?.[role] === "string" && roles[role].trim().length > 0
+        ? roles[role].trim()
+        : role;
+  }
+
+  return normalized;
+}
+
+/**
+ * @param {readonly Record<string, any>[] | undefined} items
+ * @returns {readonly Record<string, any>[]}
+ */
+function normalizeItems(items) {
+  return (items ?? []).map(normalizeItem).filter(Boolean);
+}
+
+/**
+ * @param {Record<string, any>} item
+ * @returns {Record<string, any> | null}
+ */
+function normalizeItem(item) {
+  if (!item || typeof item !== "object") {
+    return null;
+  }
+
+  const role =
+    typeof item.role === "string" && PRD_LIFECYCLE_ORDER.includes(item.role)
+      ? item.role
+      : null;
+
+  const createdAt = normalizeTimestamp(item.createdAt);
+  const updatedAt = normalizeTimestamp(item.updatedAt);
+
+  return {
+    id: String(item.id ?? item.ref ?? item.title ?? ""),
+    ref: String(item.ref ?? item.id ?? item.title ?? ""),
+    title: String(item.title ?? "").trim(),
+    url: typeof item.url === "string" ? item.url : null,
+    role,
+    createdAt,
+    updatedAt,
+  };
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ */
+function buildLifecycleCounts(items) {
+  const counts = Object.fromEntries(PRD_LIFECYCLE_ORDER.map(role => [role, 0]));
+
+  for (const item of items) {
+    if (item.role && counts[item.role] !== undefined) {
+      counts[item.role] += 1;
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ * @param {string | undefined} queueArgument
+ */
+function buildActionableHighlights(items, queueArgument) {
+  const highlights = [];
+
+  for (const role of ACTIONABLE_ROLE_ORDER) {
+    const oldest = findOldestItemForRole(items, role);
+    if (!oldest) {
+      continue;
+    }
+
+    const copy = HIGHLIGHT_COPY[role];
+    highlights.push({
+      role,
+      ref: oldest.ref,
+      title: oldest.title,
+      url: oldest.url,
+      createdAt: oldest.createdAt,
+      summary: copy.summary,
+      nextStep: expandHighlightNextStep(
+        copy.nextStep,
+        queueArgument,
+        oldest.url
+      ),
+    });
+  }
+
+  return highlights;
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ * @param {string} role
+ */
+function findOldestItemForRole(items, role) {
+  return (
+    items
+      .filter(item => item.role === role)
+      .sort(compareQueueItemsByCreatedAt)[0] ?? null
+  );
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ * @param {Record<string, string>} roles
+ * @returns {boolean}
+ */
+function inferNamespaceAdopted(items, roles) {
+  if (items.some(item => item.role)) {
+    return true;
+  }
+
+  return Object.values(roles).some(
+    value => typeof value === "string" && value.trim().length > 0
+  );
+}
+
+/**
+ * @param {string} template
+ * @param {string | undefined} queueArgument
+ * @param {string | null} itemUrl
+ * @returns {string}
+ */
+function expandHighlightNextStep(template, queueArgument, itemUrl) {
+  return template
+    .replace("<queue>", queueArgument ?? "queue")
+    .replace("<item-url>", itemUrl ?? "item URL");
+}
+
+/**
+ * @param {Record<string, any>} left
+ * @param {Record<string, any>} right
+ * @returns {number}
+ */
+function compareQueueItemsByCreatedAt(left, right) {
+  const leftMs = left.createdAt
+    ? Date.parse(left.createdAt)
+    : Number.POSITIVE_INFINITY;
+  const rightMs = right.createdAt
+    ? Date.parse(right.createdAt)
+    : Number.POSITIVE_INFINITY;
+
+  if (leftMs !== rightMs) {
+    return leftMs - rightMs;
+  }
+
+  return String(left.ref).localeCompare(String(right.ref));
+}
+
+/**
+ * @param {string | null | undefined} value
+ * @returns {string | null}
+ */
+function normalizeTimestamp(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}

package/plugins/lisa/skills/queue-status/SKILL.md

@@ -29,6 +29,24 @@ Support a repo-scoped queue selector when requested:
 - `queue=prd`: inspect only the PRD queue
 - `queue=build`: inspect only the build queue
 
+## Operator usage
+
+Typical entrypoints:
+
+```text
+/lisa:queue-status
+/lisa:queue-status queue=prd
+/lisa:queue-status queue=build
+```
+
+Use this command when an operator needs to answer one of these questions for the current repo:
+
+- "Is this queue truly idle, or is it misconfigured?"
+- "Which item is the most actionable next?"
+- "Should I run `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, or `/lisa:verify-prd` next?"
+
+Keep the report terminal-first and immediately actionable: observable queue facts first, then the smallest useful next command.
+
 ## What to report
 
 Render the report in **grouped sections** so operators can scan it top-down without reading raw tracker dumps:
@@ -48,6 +66,19 @@ For each inspected queue, report:
 
 The report should stay terminal-first and immediately actionable: observable queue facts first, then the smallest useful next step.
 
+## Highlight semantics
+
+Each queue section may include one or more highlighted items. A highlight is not a raw dump of every issue in that role; it is the single oldest or otherwise most actionable item Lisa can justify surfacing without mutating work.
+
+Interpret highlights by role:
+
+- `ready`: work is waiting to be claimed. The usual next step is `/lisa:intake <queue>`.
+- `blocked`: work is stuck behind an explicit blocker or failed pre-flight. The usual next step is `/lisa:repair-intake <queue>` after validating the blocker context.
+- `claimed` or in-review/review states: work is in motion but may be aging. The usual next step is to inspect the active implementation or review path before escalating to `/lisa:repair-intake <queue>`.
+- `shipped`: PRD work looks ready for initiative-level acceptance. The usual next step is `/lisa:verify-prd <prd-ref>`.
+
+If both queues look unexpectedly quiet or stale, mention `/lisa:automation-status` as the scheduler-health follow-up before implying the queues themselves are empty or broken.
+
 ## Output shape
 
 Use a stable terminal-friendly shape:
@@ -86,6 +117,13 @@ Status-specific remediation guidance:
 - `ATTENTION_NEEDED`: identify the most actionable blocked or stalled items and suggest the next Lisa or tracker-native command to investigate.
 - `MISCONFIGURED`: show which queue contract is missing or unresolved and recommend fixing `.lisa.config.json`, adopting the lifecycle namespace, or rerunning the relevant setup flow.
 
+Command handoff expectations:
+
+- Prefer `/lisa:intake <queue>` when the actionable highlight is `ready` work.
+- Prefer `/lisa:repair-intake <queue>` when the actionable highlight is blocked, stalled, or suspiciously old claimed/review work.
+- Prefer `/lisa:verify-prd <prd-ref>` when the PRD side surfaces shipped work that appears ready for initiative-level verification.
+- Prefer `/lisa:automation-status` when queue output suggests scheduler drift, stale unattended execution, or a mismatch between expected and observed queue activity.
+
 ## Rules
 
 - Stay **read-only**. Never create, update, claim, relabel, repair, transition, or comment on queue items from this skill.

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.96.0",
+  "version": "2.97.1",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/commands/queue-status.md

@@ -10,4 +10,25 @@ Common operator usage:
 - `/lisa:queue-status queue=prd`
 - `/lisa:queue-status queue=build`
 
-This surface is read-only in v1. Use it to understand whether the repo's PRD and build queues are idle, healthy, attention-needed, or misconfigured before deciding whether to run `/lisa:intake`, `/lisa:repair-intake`, or deeper tracker-native investigation.
+Use this when you need to answer:
+
+- Is the queue actually idle, or is Lisa misconfigured?
+- Which queue item is the most actionable next?
+- Should the next command be `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, or `/lisa:verify-prd`?
+
+This surface is read-only in v1. Use it to understand whether the repo's PRD and build queues are idle, healthy, attention-needed, or misconfigured before deciding whether to run `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, `/lisa:verify-prd`, or deeper tracker-native investigation.
+
+Quick interpretation guide:
+
+- `IDLE`: the queue resolved correctly and nothing actionable is waiting. No immediate Lisa action is required.
+- `HEALTHY`: the queue resolved correctly and normal work is present. Follow the highlighted next step, usually `/lisa:intake`.
+- `ATTENTION_NEEDED`: blocked, stalled, or aging work needs operator follow-up. Use the highlighted item and remediation hint to choose the next command, usually `/lisa:repair-intake`.
+- `MISCONFIGURED`: queue resolution or lifecycle adoption is broken. Fix config, labels/statuses, or scheduler drift before trusting queue state.
+
+Highlighted-item semantics:
+
+- A highlighted item is the single oldest or most actionable queue item for that section, not a full dump of all matching work.
+- `ready` highlights usually point to `/lisa:intake`.
+- `blocked`, stalled, or long-claimed highlights usually point to `/lisa:repair-intake`.
+- Shipped PRD highlights usually point to `/lisa:verify-prd`.
+- If queue behavior looks wrong for both PRD and build lanes, inspect `/lisa:automation-status` before assuming the queue itself is the problem.

package/plugins/src/base/scripts/queue-status-prd-readers.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * Shared PRD-side queue readers for `/lisa:queue-status`.
+ *
+ * These helpers normalize vendor-specific PRD lifecycle items into a common
+ * snapshot shape so queue-status can report lifecycle counts, actionable
+ * highlights, and queue-health verdict inputs without drifting from Lisa's PRD
+ * lifecycle contract.
+ */
+
+import { classifyQueueHealth } from "./queue-health-classification.mjs";
+
+export const PRD_LIFECYCLE_ORDER = [
+  "draft",
+  "ready",
+  "in_review",
+  "blocked",
+  "ticketed",
+  "shipped",
+  "verified",
+];
+
+const ACTIONABLE_ROLE_ORDER = [
+  "blocked",
+  "in_review",
+  "shipped",
+  "ready",
+  "ticketed",
+];
+
+const HIGHLIGHT_COPY = {
+  blocked: {
+    summary: "Oldest blocked PRD",
+    nextStep: "Run /lisa:repair-intake <queue> after clarifying the blocker.",
+  },
+  in_review: {
+    summary: "Oldest PRD still in review",
+    nextStep:
+      "Inspect the active intake run or resume it with /lisa:repair-intake <queue>.",
+  },
+  shipped: {
+    summary: "Oldest shipped PRD awaiting verification",
+    nextStep: "Run /lisa:verify-prd <item-url> to close the shipped loop.",
+  },
+  ready: {
+    summary: "Oldest ready PRD awaiting intake",
+    nextStep: "Run /lisa:intake <queue> to ticket the next PRD.",
+  },
+  ticketed: {
+    summary: "Oldest ticketed PRD still waiting on downstream delivery",
+    nextStep:
+      "Monitor downstream build work or inspect the build queue with /lisa:queue-status queue=build.",
+  },
+};
+
+/**
+ * Read a GitHub-backed PRD queue snapshot from issue payloads.
+ *
+ * @param {{
+ *   readonly issues?: readonly Record<string, any>[]
+ *   readonly roles?: Record<string, string>
+ *   readonly namespaceAdopted?: boolean
+ *   readonly queueResolved?: boolean
+ *   readonly queueArgument?: string
+ *   readonly resolutionError?: string | null
+ * }} input
+ */
+export function readGithubPrdQueueSnapshot(input = {}) {
+  const roles = input.roles ?? {};
+  const normalizedItems = (input.issues ?? [])
+    .map(issue => normalizeGithubPrdIssue(issue, roles))
+    .filter(Boolean);
+
+  return createPrdQueueSnapshot({
+    source: "github",
+    items: normalizedItems,
+    roles,
+    namespaceAdopted: input.namespaceAdopted,
+    queueResolved: input.queueResolved,
+    queueArgument: input.queueArgument,
+    resolutionError: input.resolutionError,
+  });
+}
+
+/**
+ * Build a vendor-agnostic PRD queue snapshot from normalized lifecycle items.
+ *
+ * @param {{
+ *   readonly source?: string
+ *   readonly items?: readonly Record<string, any>[]
+ *   readonly roles?: Record<string, string>
+ *   readonly namespaceAdopted?: boolean
+ *   readonly queueResolved?: boolean
+ *   readonly queueArgument?: string
+ *   readonly resolutionError?: string | null
+ * }} input
+ */
+export function createPrdQueueSnapshot(input = {}) {
+  const rawRoles = input.roles ?? {};
+  const roles = normalizeRoles(rawRoles);
+  const items = normalizeItems(input.items);
+  const counts = buildLifecycleCounts(items);
+  const highlights = buildActionableHighlights(items, input.queueArgument);
+  const queueResolved =
+    input.queueResolved ?? typeof input.resolutionError !== "string";
+  const namespaceAdopted =
+    input.namespaceAdopted ?? inferNamespaceAdopted(items, rawRoles);
+
+  const health = classifyQueueHealth({
+    queueResolved,
+    namespaceAdopted,
+    readyCount: counts.ready,
+    activeCount: counts.in_review + counts.ticketed,
+    blockedCount: counts.blocked,
+    stalledCount: counts.shipped,
+    resolutionError: input.resolutionError ?? null,
+  });
+
+  return {
+    source: input.source ?? "unknown",
+    queueResolved,
+    namespaceAdopted,
+    roles,
+    counts,
+    highlights,
+    health,
+    resolutionError: input.resolutionError ?? null,
+  };
+}
+
+/**
+ * @param {Record<string, any>} issue
+ * @param {Record<string, string>} roles
+ * @returns {Record<string, any> | null}
+ */
+function normalizeGithubPrdIssue(issue, roles) {
+  if (!issue || typeof issue !== "object") {
+    return null;
+  }
+
+  const role = resolveGithubPrdRole(issue.labels, roles);
+
+  return normalizeItem({
+    id: String(issue.id ?? issue.number ?? issue.url ?? issue.title ?? ""),
+    ref:
+      issue.number !== undefined && issue.number !== null
+        ? `#${issue.number}`
+        : String(issue.url ?? issue.title ?? ""),
+    title: String(issue.title ?? "").trim(),
+    url: typeof issue.url === "string" ? issue.url : null,
+    createdAt: issue.createdAt ?? null,
+    updatedAt: issue.updatedAt ?? null,
+    role,
+  });
+}
+
+/**
+ * @param {readonly any[] | undefined} labels
+ * @param {Record<string, string>} roles
+ * @returns {string | null}
+ */
+function resolveGithubPrdRole(labels, roles) {
+  if (!Array.isArray(labels)) {
+    return null;
+  }
+
+  const labelNames = new Set(
+    labels
+      .map(label =>
+        typeof label === "string"
+          ? label
+          : typeof label?.name === "string"
+            ? label.name
+            : null
+      )
+      .filter(Boolean)
+  );
+
+  for (const role of PRD_LIFECYCLE_ORDER) {
+    const configuredName = roles[role];
+    if (configuredName && labelNames.has(configuredName)) {
+      return role;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {Record<string, string> | undefined} roles
+ * @returns {Record<string, string>}
+ */
+function normalizeRoles(roles) {
+  const normalized = {};
+
+  for (const role of PRD_LIFECYCLE_ORDER) {
+    normalized[role] =
+      typeof roles?.[role] === "string" && roles[role].trim().length > 0
+        ? roles[role].trim()
+        : role;
+  }
+
+  return normalized;
+}
+
+/**
+ * @param {readonly Record<string, any>[] | undefined} items
+ * @returns {readonly Record<string, any>[]}
+ */
+function normalizeItems(items) {
+  return (items ?? []).map(normalizeItem).filter(Boolean);
+}
+
+/**
+ * @param {Record<string, any>} item
+ * @returns {Record<string, any> | null}
+ */
+function normalizeItem(item) {
+  if (!item || typeof item !== "object") {
+    return null;
+  }
+
+  const role =
+    typeof item.role === "string" && PRD_LIFECYCLE_ORDER.includes(item.role)
+      ? item.role
+      : null;
+
+  const createdAt = normalizeTimestamp(item.createdAt);
+  const updatedAt = normalizeTimestamp(item.updatedAt);
+
+  return {
+    id: String(item.id ?? item.ref ?? item.title ?? ""),
+    ref: String(item.ref ?? item.id ?? item.title ?? ""),
+    title: String(item.title ?? "").trim(),
+    url: typeof item.url === "string" ? item.url : null,
+    role,
+    createdAt,
+    updatedAt,
+  };
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ */
+function buildLifecycleCounts(items) {
+  const counts = Object.fromEntries(PRD_LIFECYCLE_ORDER.map(role => [role, 0]));
+
+  for (const item of items) {
+    if (item.role && counts[item.role] !== undefined) {
+      counts[item.role] += 1;
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ * @param {string | undefined} queueArgument
+ */
+function buildActionableHighlights(items, queueArgument) {
+  const highlights = [];
+
+  for (const role of ACTIONABLE_ROLE_ORDER) {
+    const oldest = findOldestItemForRole(items, role);
+    if (!oldest) {
+      continue;
+    }
+
+    const copy = HIGHLIGHT_COPY[role];
+    highlights.push({
+      role,
+      ref: oldest.ref,
+      title: oldest.title,
+      url: oldest.url,
+      createdAt: oldest.createdAt,
+      summary: copy.summary,
+      nextStep: expandHighlightNextStep(
+        copy.nextStep,
+        queueArgument,
+        oldest.url
+      ),
+    });
+  }
+
+  return highlights;
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ * @param {string} role
+ */
+function findOldestItemForRole(items, role) {
+  return (
+    items
+      .filter(item => item.role === role)
+      .sort(compareQueueItemsByCreatedAt)[0] ?? null
+  );
+}
+
+/**
+ * @param {readonly Record<string, any>[]} items
+ * @param {Record<string, string>} roles
+ * @returns {boolean}
+ */
+function inferNamespaceAdopted(items, roles) {
+  if (items.some(item => item.role)) {
+    return true;
+  }
+
+  return Object.values(roles).some(
+    value => typeof value === "string" && value.trim().length > 0
+  );
+}
+
+/**
+ * @param {string} template
+ * @param {string | undefined} queueArgument
+ * @param {string | null} itemUrl
+ * @returns {string}
+ */
+function expandHighlightNextStep(template, queueArgument, itemUrl) {
+  return template
+    .replace("<queue>", queueArgument ?? "queue")
+    .replace("<item-url>", itemUrl ?? "item URL");
+}
+
+/**
+ * @param {Record<string, any>} left
+ * @param {Record<string, any>} right
+ * @returns {number}
+ */
+function compareQueueItemsByCreatedAt(left, right) {
+  const leftMs = left.createdAt
+    ? Date.parse(left.createdAt)
+    : Number.POSITIVE_INFINITY;
+  const rightMs = right.createdAt
+    ? Date.parse(right.createdAt)
+    : Number.POSITIVE_INFINITY;
+
+  if (leftMs !== rightMs) {
+    return leftMs - rightMs;
+  }
+
+  return String(left.ref).localeCompare(String(right.ref));
+}
+
+/**
+ * @param {string | null | undefined} value
+ * @returns {string | null}
+ */
+function normalizeTimestamp(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}

package/plugins/src/base/skills/queue-status/SKILL.md

@@ -29,6 +29,24 @@ Support a repo-scoped queue selector when requested:
 - `queue=prd`: inspect only the PRD queue
 - `queue=build`: inspect only the build queue
 
+## Operator usage
+
+Typical entrypoints:
+
+```text
+/lisa:queue-status
+/lisa:queue-status queue=prd
+/lisa:queue-status queue=build
+```
+
+Use this command when an operator needs to answer one of these questions for the current repo:
+
+- "Is this queue truly idle, or is it misconfigured?"
+- "Which item is the most actionable next?"
+- "Should I run `/lisa:intake`, `/lisa:repair-intake`, `/lisa:automation-status`, or `/lisa:verify-prd` next?"
+
+Keep the report terminal-first and immediately actionable: observable queue facts first, then the smallest useful next command.
+
 ## What to report
 
 Render the report in **grouped sections** so operators can scan it top-down without reading raw tracker dumps:
@@ -48,6 +66,19 @@ For each inspected queue, report:
 
 The report should stay terminal-first and immediately actionable: observable queue facts first, then the smallest useful next step.
 
+## Highlight semantics
+
+Each queue section may include one or more highlighted items. A highlight is not a raw dump of every issue in that role; it is the single oldest or otherwise most actionable item Lisa can justify surfacing without mutating work.
+
+Interpret highlights by role:
+
+- `ready`: work is waiting to be claimed. The usual next step is `/lisa:intake <queue>`.
+- `blocked`: work is stuck behind an explicit blocker or failed pre-flight. The usual next step is `/lisa:repair-intake <queue>` after validating the blocker context.
+- `claimed` or in-review/review states: work is in motion but may be aging. The usual next step is to inspect the active implementation or review path before escalating to `/lisa:repair-intake <queue>`.
+- `shipped`: PRD work looks ready for initiative-level acceptance. The usual next step is `/lisa:verify-prd <prd-ref>`.
+
+If both queues look unexpectedly quiet or stale, mention `/lisa:automation-status` as the scheduler-health follow-up before implying the queues themselves are empty or broken.
+
 ## Output shape
 
 Use a stable terminal-friendly shape:
@@ -86,6 +117,13 @@ Status-specific remediation guidance:
 - `ATTENTION_NEEDED`: identify the most actionable blocked or stalled items and suggest the next Lisa or tracker-native command to investigate.
 - `MISCONFIGURED`: show which queue contract is missing or unresolved and recommend fixing `.lisa.config.json`, adopting the lifecycle namespace, or rerunning the relevant setup flow.
 
+Command handoff expectations:
+
+- Prefer `/lisa:intake <queue>` when the actionable highlight is `ready` work.
+- Prefer `/lisa:repair-intake <queue>` when the actionable highlight is blocked, stalled, or suspiciously old claimed/review work.
+- Prefer `/lisa:verify-prd <prd-ref>` when the PRD side surfaces shipped work that appears ready for initiative-level verification.
+- Prefer `/lisa:automation-status` when queue output suggests scheduler drift, stale unattended execution, or a mismatch between expected and observed queue activity.
+
 ## Rules
 
 - Stay **read-only**. Never create, update, claim, relabel, repair, transition, or comment on queue items from this skill.