@codyswann/lisa 2.119.1 → 2.121.0

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

@@ -0,0 +1,452 @@
+#!/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";
+import { resolvePrdLifecycleRoles } from "./queue-contract-resolution.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 RAW_PRD_READER_SOURCES = new Set(["github"]);
+
+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.",
+  },
+};
+
+/**
+ * Decide whether a PRD queue snapshot has open lifecycle pressure that should
+ * pause automatic PRD promotion or ideation work.
+ *
+ * @param {{
+ *   readonly counts?: Record<string, number>
+ *   readonly highlights?: readonly Record<string, any>[]
+ * }} snapshot
+ */
+export function evaluatePrdQueuePressure(snapshot = {}) {
+  if (
+    snapshot.queueResolved === false ||
+    snapshot.health?.verdict === "MISCONFIGURED"
+  ) {
+    return {
+      allowed: false,
+      decisiveRole: "misconfigured",
+      blockerItem: null,
+      nextStep: snapshot.resolutionError
+        ? `Fix PRD source queue configuration: ${snapshot.resolutionError}`
+        : "Fix PRD source queue configuration before creating auto-ready PRDs.",
+    };
+  }
+
+  const decisiveRole = ACTIONABLE_ROLE_ORDER.find(
+    role => normalizeCount(snapshot.counts?.[role]) > 0
+  );
+
+  if (!decisiveRole) {
+    return {
+      allowed: true,
+      decisiveRole: null,
+      blockerItem: null,
+      nextStep: null,
+    };
+  }
+
+  const blockerItem =
+    snapshot.highlights?.find(highlight => highlight.role === decisiveRole) ??
+    null;
+
+  return {
+    allowed: false,
+    decisiveRole,
+    blockerItem,
+    nextStep: blockerItem?.nextStep ?? HIGHLIGHT_COPY[decisiveRole].nextStep,
+  };
+}
+
+/**
+ * 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 ?? resolvePrdLifecycleRoles({}, "github").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 source = normalizeSource(input.source);
+  const unsupportedReaderError = resolveUnsupportedReaderError(input, source);
+  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 ??
+    (unsupportedReaderError
+      ? false
+      : typeof input.resolutionError !== "string");
+  const namespaceAdopted =
+    input.namespaceAdopted ?? inferNamespaceAdopted(items, rawRoles);
+  const resolutionError =
+    unsupportedReaderError ?? input.resolutionError ?? null;
+
+  const health = classifyQueueHealth({
+    queueResolved,
+    namespaceAdopted,
+    readyCount: counts.ready,
+    activeCount: counts.in_review + counts.ticketed,
+    blockedCount: counts.blocked,
+    stalledCount: counts.shipped,
+    resolutionError,
+  });
+
+  return {
+    source,
+    queueResolved,
+    namespaceAdopted,
+    roles,
+    counts,
+    highlights,
+    health,
+    resolutionError,
+  };
+}
+
+/**
+ * @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 {string | undefined} source
+ * @returns {string}
+ */
+function normalizeSource(source) {
+  return typeof source === "string" && source.trim().length > 0
+    ? source.trim().toLowerCase()
+    : "unknown";
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {string} source
+ * @returns {string | null}
+ */
+function resolveUnsupportedReaderError(input, source) {
+  if (
+    source === "unknown" ||
+    RAW_PRD_READER_SOURCES.has(source) ||
+    Object.hasOwn(input, "items")
+  ) {
+    return null;
+  }
+
+  return `vendor reader not implemented for PRD source '${source}'`;
+}
+
+/**
+ * @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;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function normalizeCount(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}

package/plugins/lisa-agy/skills/acceptance-criteria/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: acceptance-criteria
+description: "Acceptance criteria definition. Gherkin user flows (Given/When/Then), error states, UX concerns, and empirical verification from the user perspective."
+---
+
+# Acceptance Criteria
+
+Evaluate changes from a non-technical user's perspective. Define acceptance criteria and verify behavior matches requirements.
+
+## Analysis Process
+
+1. **Understand the user goal** -- what problem does this solve for the end user?
+2. **Define user flows** -- step-by-step paths through the feature, including happy path and error paths
+3. **Write acceptance criteria** -- testable conditions from the user's perspective
+4. **Identify UX concerns** -- confusing interactions, missing feedback, accessibility issues
+5. **Map error states** -- what happens when things go wrong, and what the user sees
+6. **Run the feature** -- execute scripts, call APIs, or trigger the described behavior to verify empirically
+7. **Compare output to requirements** -- does actual behavior match expectations?
+
+## Output Format
+
+Structure findings as:
+
+```
+## Product Analysis
+
+### User Goal
+[1-2 sentence summary of what the user wants to accomplish]
+
+### User Flows (Gherkin)
+
+#### Happy Path
+Given [precondition]
+When [action]
+Then [expected outcome]
+
+#### Error Path: [description]
+Given [precondition]
+When [action that fails]
+Then [error handling behavior]
+
+### Acceptance Criteria
+- [ ] [criterion from user perspective]
+
+### UX Concerns
+- [concern] -- impact on user experience
+
+### Error Handling Requirements
+| Error Condition | User Sees | User Can Do |
+|----------------|-----------|-------------|
+
+### Verification Results
+For each acceptance criterion:
+- **Criterion:** [what was expected]
+- **Result:** Pass / Fail / Not Yet Testable
+- **Evidence:** [what was observed]
+
+### Out of Scope
+- [thing that might be expected but is not part of this work]
+```
+
+## Rules
+
+- Write acceptance criteria from the user's perspective, not the developer's
+- Every user flow must include at least one error path
+- Use Gherkin format (Given/When/Then) for user flows to enable direct translation into test cases
+- When verifying, always run the feature -- never review by only reading code
+- If you cannot run the feature (missing dependencies, services unavailable), report as a blocker -- do not guess
+- If the changes are purely internal (refactoring, config, tooling), report "No user-facing impact" and explain why
+- Do not propose UX changes beyond what was described -- flag scope concerns instead
+- Assume the reviewer has no technical background