@codyswann/lisa 4.83.2 → 4.84.1

package/plugins/lisa/skills/lisa-session-manager/scripts/ledger.mjs

@@ -81,6 +81,17 @@ const FINISH_STATUSES = new Set(["DONE", "FAILED"]);
  * @property {number} version - Shape version
  * @property {Record<string, LedgerItem>} items - Items keyed by ref
  * @property {{paused: boolean, maxWorkers: number|null, me: string|null}} control - Operator controls
+ * @property {Record<string, ValidationFailure>} validationFailures - Backlog
+ *   items that failed validation, keyed by ref, so an unchanged item is not
+ *   re-validated every cycle
+ */
+
+/**
+ * A backlog item's last failed validation.
+ * @typedef {object} ValidationFailure
+ * @property {string} updatedAt - The item's tracker `updatedAt` when it failed
+ * @property {string} at - When the failure was recorded (ISO)
+ * @property {string|null} reason - Short summary of the failing gates
  */
 
 /**
@@ -119,6 +130,7 @@ function emptyLedger() {
     version: LEDGER_VERSION,
     items: {},
     control: { paused: false, maxWorkers: null, me: null },
+    validationFailures: {},
   };
 }
 
@@ -159,6 +171,7 @@ export async function readLedger(projectRoot, seams) {
     version: parsed.version ?? empty.version,
     items: parsed.items ?? {},
     control: { ...empty.control, ...parsed.control },
+    validationFailures: parsed.validationFailures ?? {},
   };
 }
 
@@ -384,6 +397,63 @@ export function recordFinish(projectRoot, { ref, status, reason }, seams) {
   });
 }
 
+/**
+ * Remember that a backlog item failed validation at its current tracker
+ * `updatedAt`. The backlog queue skips it until the item changes, so an
+ * unready item costs one validation per edit, not one per cycle.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string, updatedAt: string, reason?: string|null}} failure - What failed
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<ValidationFailure>} The stored record
+ */
+export function recordValidationFailure(
+  projectRoot,
+  { ref, updatedAt, reason = null },
+  seams
+) {
+  if (typeof ref !== "string" || ref === "") {
+    return Promise.reject(new Error("validation failure needs a ref"));
+  }
+  if (typeof updatedAt !== "string" || updatedAt === "") {
+    return Promise.reject(
+      new Error(
+        "validation failure needs the item's updatedAt; without it the cache could never expire"
+      )
+    );
+  }
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const entry = { updatedAt, at, reason: reason || null };
+    return {
+      ledger: {
+        ...ledger,
+        validationFailures: { ...ledger.validationFailures, [ref]: entry },
+      },
+      result: entry,
+    };
+  });
+}
+
+/**
+ * Forget a backlog item's validation failure (it was promoted, or a human
+ * asked for it to be judged again).
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string}} target - Item to forget
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<{cleared: boolean}>} Whether a record existed
+ */
+export function clearValidationFailure(projectRoot, { ref }, seams) {
+  return updateLedger(projectRoot, seams, ledger => {
+    if (!Object.hasOwn(ledger.validationFailures, ref)) {
+      return { ledger, result: { cleared: false } };
+    }
+    const { [ref]: _removed, ...rest } = ledger.validationFailures;
+    return {
+      ledger: { ...ledger, validationFailures: rest },
+      result: { cleared: true },
+    };
+  });
+}
+
 /**
  * Check a control patch before it is written.
  * @param {{paused?: unknown, maxWorkers?: unknown, me?: unknown}} patch - Patch

package/plugins/lisa/skills/lisa-session-manager/scripts/session-manager.mjs

@@ -130,6 +130,8 @@ const LEDGER_SPECS = {
   },
   "clear-question": { options: {}, positionals: 1 },
   finish: { options: { status: text, sender: text }, positionals: 1 },
+  "validation-failed": { options: { "updated-at": text }, positionals: 1 },
+  "validation-cleared": { options: {}, positionals: 1 },
   control: {
     options: { paused: text, "max-workers": text, me: text },
     positionals: 0,

package/plugins/lisa/skills/lisa-setup-session-manager/SKILL.md

@@ -68,7 +68,14 @@ writes `$SM`, and pass `--project-root "$ROOT"` (the absolute project root) on e
    "me", spelled as the tracker API returns it: the GitHub **login** (`gh api users/<login> --jq
    .login`), the Jira `accountId`, or the Linear user id (the operator's entry in the team's member
    list, or `viewer.id` only when the operator runs the lookup with their own credential).
-5. `node "$SM/session-manager.mjs" validate --project-root "$ROOT"` must print `valid: true`.
+5. Ask whether to set `sessionManager.backlogPickup` to `true` (default off). When the Ready queue
+   is exhausted and a worker slot is still free, the manager then looks at backlog items (open
+   leaves in no lifecycle role) that nobody else is assigned to, that are not human-held and have
+   no unfinished blocker. Each one that passes the full tracker validation, including the
+   stateless-pickup check, is assigned to the first `operatorIds` entry, moved to Ready and
+   dispatched. Say plainly that this lets the manager start work nobody marked Ready, so it needs
+   `operatorIds` and should go with `trustedAuthorIds` on any tracker outsiders can write to.
+6. `node "$SM/session-manager.mjs" validate --project-root "$ROOT"` must print `valid: true`.
 
 ## Step 3: Store the bot token
 

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/scripts/ready-queue-order.mjs

@@ -29,6 +29,12 @@
  *
  * Held items are judged by {@link isHumanGated}, the one shared answer to "is
  * a person holding this?", rather than by a local label check (#3805).
+ *
+ * {@link orderBacklogQueue} ranks a second, lower tier: open leaf items in no
+ * lifecycle role, which the session manager may promote to Ready when
+ * `sessionManager.backlogPickup` is on. It applies every Ready exclusion plus
+ * two of its own (an unfinished blocker, an unchanged validation failure), and
+ * its list is always walked after the whole Ready queue.
  * @module ready-queue-order
  */
 
@@ -67,6 +73,9 @@ const LINEAR_NO_PRIORITY = 4;
 /** Linear workflow state types that leave a child finished. */
 const LINEAR_FINISHED_STATE_TYPES = new Set(["completed", "canceled"]);
 
+/** Jira link types whose inward side reads as "this item is blocked by". */
+const JIRA_BLOCKED_BY = /blocked by/i;
+
 /**
  * @param {unknown} value
  * @returns {string}
@@ -88,6 +97,26 @@ function idOrNull(value) {
   return Number.isSafeInteger(value) ? String(value) : null;
 }
 
+/**
+ * A non-negative integer count, 0 for anything else.
+ * @param {unknown} value
+ * @returns {number}
+ */
+function count(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : 0;
+}
+
+/**
+ * The rows of an array or a GraphQL `{nodes}` connection.
+ * @param {unknown} list
+ * @returns {any[]}
+ */
+function nodesOf(list) {
+  if (Array.isArray(list)) return list;
+  return Array.isArray(list?.nodes) ? list.nodes : [];
+}
+
 /**
  * Label names from strings, `{name}` objects or a GraphQL `{nodes}` connection.
  * @param {unknown} labels
@@ -160,11 +189,14 @@ export function normalizeGithubIssue(issue, options = {}) {
     assigneeId: idOrNull(assignee?.login),
     priorityRank: ranks.length > 0 ? Math.min(...ranks) : GITHUB_NO_PRIORITY,
     createdAt: text(issue.created_at),
+    updatedAt: text(issue.updated_at),
     labels,
     body: text(issue.body),
     // Authors are trusted by stable id, never by login (ready-role-filing).
     authorId: idOrNull(issue.user?.id),
     isContainer: Number(summary?.total ?? 0) > Number(summary?.completed ?? 0),
+    // `blocked_by` in the dependency summary counts only OPEN blockers.
+    openBlockers: count(issue.issue_dependencies_summary?.blocked_by),
   });
 }
 
@@ -182,6 +214,12 @@ export function normalizeJiraIssue(issue) {
   const openSubtasks = (Array.isArray(fields.subtasks) ? fields.subtasks : [])
     .map(sub => sub?.fields?.status?.statusCategory?.key)
     .filter(category => category !== "done");
+  const openBlockers = nodesOf(fields.issuelinks).filter(
+    link =>
+      link?.inwardIssue &&
+      JIRA_BLOCKED_BY.test(text(link.type?.inward)) &&
+      link.inwardIssue.fields?.status?.statusCategory?.key !== "done"
+  ).length;
 
   return shape({
     ref: text(issue?.key),
@@ -189,6 +227,7 @@ export function normalizeJiraIssue(issue) {
     assigneeId: idOrNull(fields.assignee?.accountId),
     priorityRank: JIRA_PRIORITY_RANKS[priority] ?? JIRA_UNKNOWN_PRIORITY,
     createdAt: text(fields.created),
+    updatedAt: text(fields.updated),
     labels,
     body: adfText(fields.description),
     authorId: idOrNull(fields.reporter?.accountId ?? fields.creator?.accountId),
@@ -196,6 +235,7 @@ export function normalizeJiraIssue(issue) {
       Number(type.hierarchyLevel ?? 0) > 0 ||
       text(type.name).toLowerCase() === "epic" ||
       openSubtasks.length > 0,
+    openBlockers,
   });
 }
 
@@ -213,6 +253,13 @@ export function normalizeLinearIssue(issue) {
       ? issue.children
       : [];
   const labels = labelNames(issue?.labels);
+  // Linear has no "blocked by" relation type: B blocked by A is A's `blocks`
+  // relation, read from B as an inverse relation.
+  const openBlockers = nodesOf(issue?.inverseRelations).filter(
+    relation =>
+      relation?.type === "blocks" &&
+      !LINEAR_FINISHED_STATE_TYPES.has(relation.issue?.state?.type)
+  ).length;
 
   return shape({
     ref: text(issue?.identifier),
@@ -223,18 +270,22 @@ export function normalizeLinearIssue(issue) {
         ? native - 1
         : LINEAR_NO_PRIORITY,
     createdAt: text(issue?.createdAt),
+    updatedAt: text(issue?.updatedAt),
     labels,
     body: text(issue?.description),
     authorId: idOrNull(issue?.creator?.id),
     isContainer: children.some(
       child => !LINEAR_FINISHED_STATE_TYPES.has(child?.state?.type)
     ),
+    openBlockers,
   });
 }
 
 /**
  * The one item shape every normalizer returns, in a fixed key order.
- * @param {{ ref: string, title: string, assigneeId: string | null, priorityRank: number, createdAt: string, labels: string[], body: string, authorId: string | null, isContainer: boolean }} input
+ * `updatedAt` keys the backlog tier's validation cache; `openBlockers` counts
+ * dependencies whose blocker is not finished. The Ready tier ignores both.
+ * @param {{ ref: string, title: string, assigneeId: string | null, priorityRank: number, createdAt: string, updatedAt: string, labels: string[], body: string, authorId: string | null, isContainer: boolean, openBlockers: number }} input
  */
 function shape(input) {
   return {
@@ -243,10 +294,12 @@ function shape(input) {
     assigneeId: input.assigneeId,
     priorityRank: input.priorityRank,
     createdAt: input.createdAt,
+    updatedAt: input.updatedAt,
     labels: input.labels,
     body: input.body,
     authorId: input.authorId,
     isContainer: input.isContainer,
+    openBlockers: input.openBlockers,
     repoLabels: repoLabelsOf(input.labels),
   };
 }
@@ -320,7 +373,50 @@ function compareWithinGroup(left, right) {
  * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
  */
 export function orderReadyQueue(items, options = {}) {
-  const context = {
+  const context = orderingContext(options);
+  return rank(items, item => exclusionReason(item, context), context);
+}
+
+/**
+ * Order normalized backlog items — open leaves in no lifecycle role — for
+ * promotion, the tier walked only after the whole Ready queue.
+ *
+ * Every Ready exclusion applies, then two more: an item with an unfinished
+ * blocker (`blocked-by-open-item`) cannot be taken to completion, and an item
+ * that already failed validation at its current `updatedAt`
+ * (`failed-validation-unchanged`, from `validationFailures`) would only fail
+ * again, so it waits until someone edits it. Grouping and ordering match
+ * {@link orderReadyQueue}.
+ * @param {readonly Record<string, any>[]} items - Normalized items
+ * @param {{ me?: string | null, operators?: readonly unknown[], trustedAuthorIds?: readonly unknown[], humanNeededLabel?: string, validationFailures?: Readonly<Record<string, { updatedAt?: string }>> }} [options]
+ * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
+ */
+export function orderBacklogQueue(items, options = {}) {
+  const context = orderingContext(options);
+  const failures = options.validationFailures ?? {};
+  return rank(
+    items,
+    item => {
+      const reason = exclusionReason(item, context);
+      if (reason !== null) return reason;
+      if (count(item.openBlockers) > 0) return "blocked-by-open-item";
+      const failed = Object.hasOwn(failures, item.ref)
+        ? failures[item.ref]
+        : null;
+      return failed && text(failed.updatedAt) === text(item.updatedAt)
+        ? "failed-validation-unchanged"
+        : null;
+    },
+    context
+  );
+}
+
+/**
+ * The identities and policy every ordering judges against.
+ * @param {{ me?: string | null, operators?: readonly unknown[], trustedAuthorIds?: readonly unknown[], humanNeededLabel?: string }} options
+ */
+function orderingContext(options) {
+  return {
     me: idOrNull(options.me),
     operators: new Set((options.operators ?? []).map(idOrNull).filter(Boolean)),
     trusted: new Set(
@@ -328,10 +424,17 @@ export function orderReadyQueue(items, options = {}) {
     ),
     humanNeededLabel: options.humanNeededLabel ?? DEFAULT_HUMAN_NEEDED_LABEL,
   };
-  const judged = (items ?? []).map(item => ({
-    item,
-    reason: exclusionReason(item, context),
-  }));
+}
+
+/**
+ * Split items into ordered eligible ones and excluded ones with reasons.
+ * @param {readonly Record<string, any>[] | undefined} items
+ * @param {(item: Record<string, any>) => string | null} judge - Exclusion reason, or null
+ * @param {ReturnType<typeof orderingContext>} context
+ * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
+ */
+function rank(items, judge, context) {
+  const judged = (items ?? []).map(item => ({ item, reason: judge(item) }));
   const eligible = judged
     .filter(one => one.reason === null)
     .map(one => one.item);

package/plugins/lisa-agy/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -819,10 +819,38 @@ export function validateSessionManager(block) {
         ]
       : []),
     ...validateOperatorIds(block.operatorIds),
+    ...validateBacklogPickup(block.backlogPickup, block.operatorIds),
     ...findCredentials(block, "sessionManager"),
   ];
 }
 
+/**
+ * Validate `sessionManager.backlogPickup`: opt-in promotion of validated
+ * backlog items to Ready, assigned to `operatorIds[0]`. Without an operator
+ * there is nobody to assign the promoted item to, so it is refused rather
+ * than promoting work into the agent's own name.
+ * @param {unknown} value The value, if present.
+ * @param {unknown} operatorIds `sessionManager.operatorIds`, if present.
+ * @returns {string[]} Problems found.
+ */
+function validateBacklogPickup(value, operatorIds) {
+  if (value === undefined) return [];
+  if (typeof value !== "boolean") {
+    return [
+      `sessionManager.backlogPickup must be true or false (absent means false).`,
+    ];
+  }
+  const hasOperator =
+    Array.isArray(operatorIds) &&
+    operatorIds.some(id => typeof id === "string" && id.trim() !== "");
+  return value && !hasOperator
+    ? [
+        `sessionManager.backlogPickup needs sessionManager.operatorIds: a ` +
+          `promoted backlog item is assigned to the first operator.`,
+      ]
+    : [];
+}
+
 /**
  * Validate every block this plan introduced.
  * @param {object} cfg Parsed `.lisa.config.json`.

package/plugins/lisa-agy/skills/lisa-session-manager/SKILL.md

@@ -214,6 +214,17 @@ Skip while `capacity` reports `paused`. Otherwise:
      createdAt, assignee, labels, description, creator and children with their state type.
    - `ordered` is the dispatch order: assigned to an operator, then to "me", then unassigned; each
      group by priority, then age. `excluded` needs no action.
+   - **Backlog tier** (only when `sessionManager.backlogPickup` is `true`). GitHub: `queue` fetches
+     it itself (open issues with no build or PRD lifecycle label). Jira / Linear: also fetch the
+     open leaf items in **no** lifecycle role — Linear workflow state type `backlog` or `unstarted`
+     other than the configured `ready` state; Jira status category "To Do" other than the configured
+     `ready` status — paged to completion, including each item's `updatedAt` / `updated` and its
+     blockers (Linear `inverseRelations` with `type` and the blocking issue's `state.type`; Jira
+     `issuelinks`). Put them in the same input file as
+     `"backlog":{"complete":true,"pages":<n>,"items":[...]}`; `queue` refuses a missing or partial
+     backlog envelope while the key is on. It returns `backlogOrdered` (same grouping and order,
+     minus items with an unfinished blocker and items whose cached validation failure still matches
+     their `updatedAt`) and `backlogExcluded`.
 2. **While `capacity` says `can_spawn`** and items remain, take the next item that has no pending
    question in the ledger:
    1. Read it fully (`lisa-tracker-read`): title, description, labels, project, parent, comments.
@@ -244,6 +255,34 @@ Skip while `capacity` reports `paused`. Otherwise:
         `recovery-required` with that message as the summary. It is not a failed attempt; do not
         dispatch to that repo again until the operator fixes it.
       - any other exit: move the item back to the `ready` role, notify Telegram, continue.
+3. **Backlog tier, lowest priority.** Only when `backlogPickup` is on, every `ordered` item has been
+   taken or skipped, and `capacity` still says `can_spawn`. Ready work always wins: never promote a
+   backlog item while a dispatchable Ready item remains. For the next `backlogOrdered` item with no
+   pending question in the ledger:
+   1. Read it fully (`lisa-tracker-read`). If it gained an assignee who is neither "me" nor an
+      operator, a lifecycle role, open child work, a human hold or an unfinished blocker since the
+      queue was listed, skip it.
+   2. **Validate it** with `lisa-tracker-validate` against the live item (identifier mode, all
+      gates, including the stateless-pickup dry-run). This is what "can be taken to completion"
+      means. On a definitive `FAIL`, record
+      `ledger validation-failed <ref> --updated-at <the item's updatedAt>` with a one-line summary
+      of the failing gates on STDIN, and skip it; the queue leaves it out until the item changes.
+      On could-not-validate (an outage or unreadable item, not a verdict), skip it WITHOUT
+      recording, so the next cycle retries it. Either way, post nothing to Telegram: backlog
+      grooming is not the operator's inbox.
+   3. **Route the repo** as in step 2.2, but never ask: an ambiguous or multi-repo backlog item is
+      skipped.
+   4. **Promote** in ONE `lisa-tracker-write` update: assignee = the first `operatorIds` entry, move
+      to the `ready` role, comment
+      `[lisa-session-manager] Promoted from backlog: validation passed; assigned to the operator.`
+      Read it back with `lisa-tracker-read` and continue only when the role is `ready` and the
+      assignee is that operator. Then `ledger validation-cleared <ref>`.
+   5. Continue with steps 2.3 and 2.4 (claim in the child repo, re-read, spawn, handle the exit)
+      exactly as for a Ready item, with one change: on exit 0, post
+      `[<REF>] promoted from backlog and started in <repo> (<name>)` in place of the plain start
+      notice. Every other exit keeps its step 2.4 handling.
+   A promotion written and read back counts as a state change for the run outcome; a spawn that
+   then fails follows step 2.4's exits (the item stays in Ready, assigned to the operator).
 
 ### 3. Report and record
 

package/plugins/lisa-agy/skills/lisa-session-manager/references/runbook-template.md

@@ -23,6 +23,12 @@ then to the manager's own tracker identity, then unassigned; within each, by pri
 Items assigned to someone else, containers, human-held items and (when configured) items by
 untrusted authors are skipped. As many as the machine has capacity for.
 
+When `sessionManager.backlogPickup` is on and capacity remains after every Ready item, a lowest tier
+follows: backlog items (open leaves in no lifecycle role) in the same order, minus those with an
+unfinished blocker and those that already failed validation and have not changed since. Each one
+must pass the full tracker validation before it is assigned to the first operator, moved to Ready
+and dispatched like any other item.
+
 ## Scope/bounds
 
 Only the repos listed in `sessionManager.repos` (or this repo). It never writes code itself, never

package/plugins/lisa-agy/skills/lisa-session-manager/scripts/cli-cycle.mjs

@@ -24,9 +24,11 @@ import {
 import { parseJson, readJsonFile } from "./cli-queue.mjs";
 import {
   clearPendingQuestion,
+  clearValidationFailure,
   readLedger,
   recordFinish,
   recordSpawn,
+  recordValidationFailure,
   setControl,
   setPendingQuestion,
 } from "./ledger.mjs";
@@ -130,6 +132,14 @@ const LEDGER_ACTIONS = {
       reason: stdinText(ctx, "reason", { required: false }),
     });
   },
+  "validation-failed": ctx =>
+    recordValidationFailure(ctx.root, {
+      ref: requirePositional(ctx, "ref"),
+      updatedAt: requireValue(ctx, "updated-at"),
+      reason: stdinText(ctx, "reason", { required: false }),
+    }),
+  "validation-cleared": ctx =>
+    clearValidationFailure(ctx.root, { ref: requirePositional(ctx, "ref") }),
   control: ctx =>
     setControl(
       ctx.root,