@codyswann/lisa 4.83.2 → 4.84.1

package/package.json

@@ -189,7 +189,7 @@
     "qs": "^6.16.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.83.2",
+  "version": "4.84.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -347,7 +347,7 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "6809a93684222beb7b41faf8a2a6a873597eeeeb",
-  "gitHead": "6809a93684222beb7b41faf8a2a6a873597eeeeb",
-  "lisaReleaseTag": "v4.83.2"
+  "lisaReleaseCommit": "f2b00d3c6cbe98a9095d41b62cdd0993b3b8ae67",
+  "gitHead": "f2b00d3c6cbe98a9095d41b62cdd0993b3b8ae67",
+  "lisaReleaseTag": "v4.84.1"
 }

package/plugins/lisa/.claude-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/skills/lisa-session-manager/SKILL.md

@@ -216,6 +216,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.
@@ -246,6 +257,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/.codex-plugin/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/.codex-plugin/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,

package/plugins/lisa/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/skills/lisa-setup-session-manager/SKILL.md

@@ -70,7 +70,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/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