@codyswann/lisa 4.83.2 → 4.84.0

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

@@ -9,6 +9,10 @@
  * `{complete, pages, items}`; anything but a literal `complete: true` is
  * refused with exit 2, because ordering a partial queue would dispatch the
  * wrong item with full confidence.
+ *
+ * With `sessionManager.backlogPickup` on, `queue` also ranks the backlog tier
+ * (open leaves in no lifecycle role) as `backlogOrdered`, under the same
+ * paging rule. The manager walks it only after the whole Ready queue.
  * @module session-manager/cli-queue
  */
 import { readFileSync } from "node:fs";
@@ -18,6 +22,7 @@ import {
   normalizeGithubIssue,
   normalizeJiraIssue,
   normalizeLinearIssue,
+  orderBacklogQueue,
   orderReadyQueue,
 } from "../../../scripts/ready-queue-order.mjs";
 import { resolveRole } from "../../../scripts/resolve-lifecycle-role.mjs";
@@ -61,12 +66,12 @@ export function readJsonFile(file) {
 }
 
 /**
- * Fetch every open GitHub issue carrying the ready label, all pages.
+ * The GitHub repo to read: `--github-repo`, else github.org/github.repo.
  * @param {object} ctx - CLI context
  * @param {ReturnType<typeof loadProject>} project - Loaded project
- * @returns {{ items: object[], pages: number }} Normalized items
+ * @returns {string} `owner/repo`
  */
-function fetchGithubQueue(ctx, project) {
+function githubRepo(ctx, project) {
   const merged = { ...project.global?.github, ...project.local?.github };
   const repo =
     ctx.values["github-repo"] ??
@@ -77,6 +82,68 @@ function fetchGithubQueue(ctx, project) {
       2
     );
   }
+  return repo;
+}
+
+/**
+ * Every string leaf of an object (label names, including env-keyed `done`).
+ * @param {unknown} value - Config subtree
+ * @returns {string[]} Leaves
+ */
+function stringLeaves(value) {
+  if (typeof value === "string") return value ? [value] : [];
+  if (!value || typeof value !== "object") return [];
+  return Object.values(value).flatMap(stringLeaves);
+}
+
+/**
+ * Fetch every open GitHub issue carrying no lifecycle label (build or PRD),
+ * all pages: the GitHub backlog tier.
+ * @param {object} ctx - CLI context
+ * @param {ReturnType<typeof loadProject>} project - Loaded project
+ * @returns {{ items: object[], pages: number }} Normalized items
+ */
+function fetchGithubBacklog(ctx, project) {
+  const repo = githubRepo(ctx, project);
+  const lifecycle = new Set(
+    [project.global?.github?.labels, project.local?.github?.labels]
+      .flatMap(labels => [
+        ...stringLeaves(labels?.build),
+        ...stringLeaves(labels?.prd),
+      ])
+      .map(label => label.toLowerCase())
+  );
+  const stdout = mustRun(
+    "gh",
+    [
+      "api",
+      "--paginate",
+      "--slurp",
+      `repos/${repo}/issues?state=open&per_page=100`,
+    ],
+    { env: scrubWorkerEnv(ctx.env) }
+  );
+  const pages = parseJson(stdout, "gh api output");
+  const rows = Array.isArray(pages) ? pages.flat() : [];
+  return {
+    items: rows
+      .map(row => normalizeGithubIssue(row, { repo }))
+      .filter(Boolean)
+      .filter(
+        item => !item.labels.some(label => lifecycle.has(label.toLowerCase()))
+      ),
+    pages: Array.isArray(pages) ? pages.length : 0,
+  };
+}
+
+/**
+ * Fetch every open GitHub issue carrying the ready label, all pages.
+ * @param {object} ctx - CLI context
+ * @param {ReturnType<typeof loadProject>} project - Loaded project
+ * @returns {{ items: object[], pages: number }} Normalized items
+ */
+function fetchGithubQueue(ctx, project) {
+  const repo = githubRepo(ctx, project);
   const role = resolveRole({
     role: "ready",
     vendor: "github",
@@ -101,24 +168,51 @@ function fetchGithubQueue(ctx, project) {
 }
 
 /**
- * Read a vendor-skill envelope and normalize its raw issues.
- * @param {object} ctx - CLI context
+ * Check one paged envelope and normalize its raw issues.
+ * @param {unknown} envelope - `{complete, pages, items}`
+ * @param {string} where - Where it came from, for messages
  * @param {"jira"|"linear"} tracker - Vendor
  * @returns {{ items: object[], pages: unknown }} Normalized items
  */
-function readEnvelopeQueue(ctx, tracker) {
+function normalizeEnvelope(envelope, where, tracker) {
+  asSetupError(() => assertPagedToCompletion(envelope));
+  if (!Array.isArray(envelope.items)) {
+    throw new CliError(`${where}: items must be an array.`, 2);
+  }
+  return {
+    items: envelope.items.map(NORMALIZERS[tracker]),
+    pages: envelope.pages ?? null,
+  };
+}
+
+/**
+ * Read a vendor-skill envelope and normalize its raw issues. With
+ * `withBacklog`, the envelope must also carry `backlog`, a second
+ * `{complete, pages, items}` envelope held to the same paging rule.
+ * @param {object} ctx - CLI context
+ * @param {"jira"|"linear"} tracker - Vendor
+ * @param {boolean} withBacklog - Whether the backlog tier is required
+ * @returns {{ items: object[], pages: unknown, backlog: { items: object[], pages: unknown } | null }} Normalized items
+ */
+function readEnvelopeQueue(ctx, tracker, withBacklog) {
   const file = ctx.values.input;
   if (!file) {
     throw new CliError(`queue --tracker ${tracker} needs --input <file>.`, 2);
   }
   const envelope = readJsonFile(file);
-  asSetupError(() => assertPagedToCompletion(envelope));
-  if (!Array.isArray(envelope.items)) {
-    throw new CliError(`${file}: items must be an array.`, 2);
+  const ready = normalizeEnvelope(envelope, file, tracker);
+  if (!withBacklog) return { ...ready, backlog: null };
+  if (!envelope.backlog) {
+    throw new CliError(
+      `${file}: sessionManager.backlogPickup is on, so the input needs a ` +
+        `"backlog" envelope {complete:true,pages,items} of open leaf items ` +
+        `in no lifecycle role.`,
+      2
+    );
   }
   return {
-    items: envelope.items.map(NORMALIZERS[tracker]),
-    pages: envelope.pages ?? null,
+    ...ready,
+    backlog: normalizeEnvelope(envelope.backlog, `${file} backlog`, tracker),
   };
 }
 
@@ -126,8 +220,12 @@ function readEnvelopeQueue(ctx, tracker) {
  * `queue --tracker <github|jira|linear>`: the Ready queue, the operator's
  * items first (`sessionManager.operatorIds`), then mine, then unassigned.
  * @param {object} ctx - CLI context
+ * With `sessionManager.backlogPickup` on it also returns the backlog tier,
+ * ordered the same way and always dispatched after every Ready item.
+ * @param {object} ctx - CLI context
  * @returns {Promise<{ json: object }>}
- *   `{tracker,me,operators,total,pages,ordered,excluded}`
+ *   `{tracker,me,operators,total,pages,ordered,excluded,backlogPickup[,
+ *   backlogTotal,backlogPages,backlogOrdered,backlogExcluded]}`
  */
 export async function queue(ctx) {
   const tracker = ctx.values.tracker;
@@ -136,19 +234,48 @@ export async function queue(ctx) {
   }
   const project = loadProject(ctx.root);
   const config = validOrAbsent(project);
-  const { items, pages } =
+  const backlogPickup = config?.backlogPickup === true;
+  const { items, pages, backlog } =
     tracker === "github"
-      ? fetchGithubQueue(ctx, project)
-      : readEnvelopeQueue(ctx, tracker);
-  const me = ctx.values.me ?? (await readLedger(ctx.root)).control.me ?? null;
+      ? {
+          ...fetchGithubQueue(ctx, project),
+          backlog: backlogPickup ? fetchGithubBacklog(ctx, project) : null,
+        }
+      : readEnvelopeQueue(ctx, tracker, backlogPickup);
+  const ledger = await readLedger(ctx.root);
+  const me = ctx.values.me ?? ledger.control.me ?? null;
   const operators = config?.operatorIds ?? [];
-  const order = orderReadyQueue(items, {
+  const policy = {
     me,
     operators,
     trustedAuthorIds: config?.trustedAuthorIds ?? undefined,
     humanNeededLabel: humanNeededLabel(project, tracker),
+  };
+  const order = orderReadyQueue(items, policy);
+  const json = {
+    tracker,
+    me,
+    operators,
+    total: items.length,
+    pages,
+    ...order,
+    backlogPickup,
+  };
+  if (!backlog) return { json };
+  // An item both Ready and in the backlog fetch is Ready work; never twice.
+  const readyRefs = new Set(items.map(item => item.ref));
+  const backlogItems = backlog.items.filter(item => !readyRefs.has(item.ref));
+  const tier = orderBacklogQueue(backlogItems, {
+    ...policy,
+    validationFailures: ledger.validationFailures,
   });
   return {
-    json: { tracker, me, operators, total: items.length, pages, ...order },
+    json: {
+      ...json,
+      backlogTotal: backlogItems.length,
+      backlogPages: backlog.pages,
+      backlogOrdered: tier.ordered,
+      backlogExcluded: tier.excluded,
+    },
   };
 }

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

@@ -117,6 +117,13 @@ Per cycle
       first, then to --me, then unassigned; each group by priority, then age.
       Items assigned to anyone else are excluded (assigned-to-other).
       --me defaults to the ledger's control.me.
+      With sessionManager.backlogPickup true, also prints backlogTotal,
+      backlogPages, backlogOrdered and backlogExcluded: open leaves in no
+      lifecycle role, same order, always after every ready item; excluded
+      also for blocked-by-open-item and failed-validation-unchanged (the
+      ledger's validationFailures entry matches the item's updatedAt).
+      GitHub fetches them itself; jira|linear need <file>.backlog =
+      {complete:true,pages,items}, else exit 2.
   ledger get [<ref>]
   ledger record-spawn <ref> --worker <name> [--session-id <id>] [--repo <key>]
   ledger set-question <ref> [--telegram-message-id <n>] [--sender <name>]
@@ -124,6 +131,12 @@ Per cycle
   ledger clear-question <ref>
   ledger finish <ref> --status DONE|FAILED [--sender <name>]  STDIN: reason
       --sender: exit 2 unless the ledger's worker for <ref> is exactly <name>.
+  ledger validation-failed <ref> --updated-at <ts>     STDIN: failing gates
+      Caches a backlog item's failed validation; queue skips it until the
+      item's updatedAt changes.
+  ledger validation-cleared <ref>
+      Forgets that failure: after a promotion, or by hand to have the next
+      cycle re-validate an item without editing it. stdout {cleared}.
   ledger control [--paused true|false] [--max-workers <n>|none] [--me <id>|none]
   route [--reply-to <telegram message id>] [--owner <name>] STDIN: message
       stdout {kind:"answer",ref,body[,message]} | {kind:"command",name,...}

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

@@ -67,6 +67,7 @@ export const SESSION_MANAGER_DEFAULTS = Object.freeze({
  *   notify: NotifyBlock,
  *   trustedAuthorIds: string[] | null,
  *   operatorIds?: string[] | null,
+ *   backlogPickup?: boolean,
  * }} SessionManagerConfig
  * @typedef {{
  *   name: string,

package/plugins/lisa-agy/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-agy/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-agy/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-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.83.2",
+  "version": "4.84.0",
   "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": "4.83.2",
+  "version": "4.84.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

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

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

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

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

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

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

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

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -735,6 +735,7 @@ have a `.lisa.config.json` and their own `.git` (written as `"root": "."`).
 | `sessionManager.notify.stateDir` | **yes** | — | This project's own Telegram state dir. Never the shared default `~/.claude/channels/telegram`, because one bot per state dir is how projects stay isolated. Setup writes `~/.claude/channels/telegram-<project>`. |
 | `sessionManager.trustedAuthorIds` | no | — | Optional list of **stable tracker user ids**, as strings: the GitHub numeric user id (`gh api users/<login> --jq .id`), the Jira `accountId`, or the Linear user id. Not logins or display names: matching compares ids, so a login silently matches no one and excludes every item. When set, the manager takes only items authored by these people. |
 | `sessionManager.operatorIds` | no | — | Optional, non-empty list of the people the manager works for, as tracker user ids matched against the **assignee** the same way "me" is: the GitHub **login**, the Jira `accountId`, or the Linear user id, spelled exactly as the tracker API returns it (matching is case-sensitive, so look the OPERATOR up rather than typing from memory: `gh api users/<operator-login> --jq .login` returns the canonical GitHub spelling. Do not use `gh api user`, which returns whoever the credential belongs to — the agent account, when that is the case this key exists for). Dispatch order is assigned to an operator, then to "me" (the tracker credential's identity), then unassigned; items assigned to anyone else are skipped. Set it whenever the tracker credential is not the operator's own (an agent account), or the operator's Ready items are never dispatched. |
+| `sessionManager.backlogPickup` | no | `false` | Opt-in lowest dispatch tier. When the Ready queue is exhausted and capacity remains, the manager considers backlog items (open leaves in no lifecycle role) with the Ready exclusions plus any unfinished blocker; each one that passes the tracker validator (all gates, including the stateless-pickup dry-run) is assigned to the first `operatorIds` entry, moved to Ready in one write, read back and dispatched. A failed validation is cached against the item's `updatedAt`, so it is re-judged only after the item changes. Requires `operatorIds`. |
 
 - **Non-secret only.** The bot token lives in `<stateDir>/.env` (directory 0700, file 0600),
   written by setup. A credential-named field or a token-shaped value anywhere in this block is a