@codyswann/lisa 4.86.1 → 4.87.0

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

@@ -202,11 +202,17 @@ Per cycle
       unset); trustedHumanActorIds in the input is ignored. stdout
       {action:release|keep|escalate|skip-human-gate,reason,edges,gate}.
       --ref fills pendingQuestion from the ledger.
-  mark-plan <ref> --kind <kind>                 STDIN: question or reason
+  mark-plan <ref> --kind <kind> [--cause <cause>] STDIN: question or reason
       Plans marking an item that needs a human; writes nothing. kind:
-      worker-question | repo-route | exhausted | decision. stdout {ref,kind,
-      marker:{type:"label"|"role",value},[move:{role:"blocked",value},]
-      comment,answerWith:{item,cli,channel}}. marker is the tracker's
+      worker-question | repo-route | exhausted | decision. cause: planning
+      (default) | environment (outage, expired credential, flaky tool) |
+      human-gate (a decision planning flagged as a human gate). stdout
+      {ref,kind,marker:{type:"label"|"role",value},[move:{role:"blocked",
+      value},]comment,answerWith:{item,cli,channel},planningMiss:{counts,
+      reason[,stageHint,candidate]}}. planningMiss.counts is true for a
+      worker-question, decision or repo-route with cause planning; never
+      for exhausted. candidate is the persist-learning skeleton (signal,
+      triggering_issue, provenance, scope_hint, kind, missing). marker is the tracker's
       configured human-needed label, else the configured blocked role;
       exhausted also moves to the blocked role. comment starts with
       [lisa-session-manager-question] and says, in plain words, how to
@@ -214,7 +220,7 @@ Per cycle
       answerWith.item is null otherwise), with the answerCommand that status
       lists, or on Telegram when it is the channel. Exit 2 for an unknown
       kind, empty or credential-shaped text, no marker configured, or
-      exhausted with no blocked role.
+      exhausted with no blocked role, or an unknown cause.
   answer <ref>                                  STDIN: the answer
       Queues an operator's answer (source "cli") for the next cycle to
       deliver. stdout {queued:true,ref,source}. Exit 2 when <ref> has no

package/plugins/src/base/skills/lisa-session-manager/scripts/human-needed.mjs

@@ -27,6 +27,103 @@ export const HUMAN_NEEDED_KINDS = Object.freeze([
   "decision",
 ]);
 
+/**
+ * Why a stop needed a human, as far as the planning-miss signal cares
+ * (CodySwannGT/lisa#4569). `planning` is the default: the item passed the
+ * ready gate and still needed a person. `environment` is an outage, an
+ * expired credential or a flaky tool; `human-gate` is a decision planning
+ * flagged as a human gate on the item. Neither of those two is a planning
+ * miss.
+ */
+export const PLANNING_MISS_CAUSES = Object.freeze([
+  "planning",
+  "environment",
+  "human-gate",
+]);
+
+/**
+ * Each kind that counts as a planning miss, with the planning stage most
+ * likely to have let it through. A hint for the judge, never its verdict:
+ * `learning-judge` names the stage it can prove.
+ */
+const PLANNING_MISS_STAGES = Object.freeze({
+  // The stateless-pickup dry-run (S18) exists to find the question first.
+  "worker-question": "ready-gate",
+  // How the product should behave is the PRD's to decide.
+  decision: "prd",
+  // A leaf the router cannot place should have been split per repo-scope-split.
+  // Raised before the claim, but after the item passed the ready gate and was
+  // picked for dispatch: the operator ruled it a planning miss (#4569), and
+  // the planning-miss rate's denominator counts these routing holds too.
+  "repo-route": "decomposition",
+});
+
+/** Why a stop does not count, keyed by what ruled it out. */
+const NOT_A_PLANNING_MISS = Object.freeze({
+  exhausted:
+    "repeated failed attempts are a build or environment problem, not a gap in the plan",
+  environment:
+    "an outage, an expired credential or a flaky tool is not a gap in the plan",
+  "human-gate":
+    "planning flagged this decision as a human gate, so asking was the plan working",
+});
+
+/**
+ * Whether a human-needed stop is a planning miss: the PRD, decomposition or
+ * ready gate let through an item a dispatched worker could not finish without
+ * a person. Throws on an unknown cause.
+ * @param {{kind: string, cause?: string}} input - The `--kind` and `--cause`
+ * @returns {{counts: boolean, reason: string, stageHint?: string}} Verdict
+ */
+export function planningMissFor({ kind, cause = "planning" }) {
+  if (!PLANNING_MISS_CAUSES.includes(cause)) {
+    throw new Error(
+      `--cause must be one of: ${PLANNING_MISS_CAUSES.join(", ")}.`
+    );
+  }
+  if (cause !== "planning") {
+    return { counts: false, reason: NOT_A_PLANNING_MISS[cause] };
+  }
+  // Own keys only: an inherited name such as `toString` is not a kind.
+  const stageHint = Object.hasOwn(PLANNING_MISS_STAGES, kind)
+    ? PLANNING_MISS_STAGES[kind]
+    : undefined;
+  if (!stageHint) {
+    return { counts: false, reason: NOT_A_PLANNING_MISS.exhausted };
+  }
+  return {
+    counts: true,
+    stageHint,
+    reason:
+      "the item passed the ready gate and a dispatched worker still needed a human, so planning let a gap through",
+  };
+}
+
+/**
+ * The planning-miss verdict for `planMark`, plus the fields of the
+ * `lisa-persist-learning` candidate the manager can fill in without judgment.
+ * The rule and its why are the manager's to draft: they name the check
+ * planning should have run, which no script can know.
+ * @param {{ref: string, kind: string, cause?: string, question: string}}
+ *   input - The item, why, the cause and the question text
+ * @returns {object} `{counts, reason, stageHint?, candidate?}`
+ */
+function planningMissPlan({ ref, kind, cause, question }) {
+  const verdict = planningMissFor({ kind, cause });
+  if (!verdict.counts) return verdict;
+  return {
+    ...verdict,
+    candidate: {
+      signal: "planning-miss",
+      triggering_issue: ref,
+      provenance: [ref],
+      scope_hint: "project",
+      kind,
+      missing: question,
+    },
+  };
+}
+
 /** Marks the manager's question comment, so its answer can be found after it. */
 export const QUESTION_MARKER = "[lisa-session-manager-question]";
 
@@ -134,13 +231,16 @@ function chooseMarker(label, blocked) {
  * unknown kind, empty or credential-shaped text, no marker, or an `exhausted`
  * item with no `blocked` role to move it to.
  * @param {{ref: string, kind: string, text: string, label?: string,
- *   blocked?: string, channel?: boolean, answerers?: boolean}} input - The
- *   item, why, the question, the configured human-needed label and `blocked`
- *   role value, whether a notification channel exists, and whether anyone
- *   (operatorIds / trustedAuthorIds) may answer on the item
+ *   blocked?: string, channel?: boolean, answerers?: boolean, cause?: string}}
+ *   input - The item, why, the question, the configured human-needed label
+ *   and `blocked` role value, whether a notification channel exists, whether
+ *   anyone (operatorIds / trustedAuthorIds) may answer on the item, and the
+ *   cause the planning-miss signal needs (default `planning`)
  * @returns {{ref: string, kind: string, marker: {type: string, value: string},
  *   move?: {role: "blocked", value: string}, comment: string,
- *   answerWith: {item: string|null, cli: string, channel: string|null}}} Plan
+ *   answerWith: {item: string|null, cli: string, channel: string|null},
+ *   planningMiss: {counts: boolean, reason: string, stageHint?: string,
+ *   candidate?: object}}} Plan
  */
 export function planMark({
   ref,
@@ -150,10 +250,16 @@ export function planMark({
   blocked,
   channel = false,
   answerers = true,
+  cause = "planning",
 }) {
   if (!HUMAN_NEEDED_KINDS.includes(kind)) {
     throw new Error(`--kind must be one of: ${HUMAN_NEEDED_KINDS.join(", ")}.`);
   }
+  if (!PLANNING_MISS_CAUSES.includes(cause)) {
+    throw new Error(
+      `--cause must be one of: ${PLANNING_MISS_CAUSES.join(", ")}.`
+    );
+  }
   const question = String(text ?? "").trim();
   if (question === "") throw new Error("the question or reason is empty");
   const shape = findCredentialShape(question);
@@ -194,5 +300,6 @@ export function planMark({
       cli: `the answerCommand that session-manager.mjs status lists for ${ref} (answer on stdin)`,
       channel: channel ? `Answer with: ${short} <your answer>` : null,
     },
+    planningMiss: planningMissPlan({ ref, kind, cause, question }),
   };
 }

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

@@ -111,7 +111,11 @@ const COMMANDS = {
     options: { input: text, ref: text },
     positionals: 0,
   },
-  "mark-plan": { run: markPlan, options: { kind: text }, positionals: 1 },
+  "mark-plan": {
+    run: markPlan,
+    options: { kind: text, cause: text },
+    positionals: 1,
+  },
   answer: { run: answer, options: {}, positionals: 1 },
   "item-answer": { run: itemAnswer, options: {}, positionals: 1 },
   "record-cycle": {

package/plugins/src/base/skills/lisa-task-decomposition/SKILL.md

@@ -9,6 +9,24 @@ Break work into ordered, well-scoped tasks that can be independently implemented
 
 ## Decomposition Process
 
+### 0. Load the learned planning checks
+
+Every time a dispatched worker had to stop for a human, or file a new ticket mid-build, because planning let a gap through, `learning-judge` may have persisted the check planning should have run as a `planning-miss` learning (CodySwannGT/lisa#4569). Those checks only help if planning reads them back. Before decomposing, load them through the learnings contract's **bounded projection** — never by reading the ledger file wholesale:
+
+```bash
+node -e 'import("@codyswann/lisa/learnings").then(async m => { const { readFile } = await import("node:fs/promises"); const file = m.resolveProjectLearningsFile(await m.readProjectConfig(process.cwd())); const raw = await readFile(file, "utf8").catch(() => null); if (raw === null) return; const { entries, omittedCount } = m.projectLearnings(m.parseLearningsFile(raw)); const checks = entries.filter(e => /^Planning \((prd|decomposition|ready-gate)\):/.test(e.rule)).map(e => ({ id: e.id, rule: e.rule, confidence: e.confidence })); console.log(JSON.stringify({ checks, omittedCount })); }).catch(error => console.error(`learned planning checks unavailable: ${error.message}`))' || true
+```
+
+Run it from the project root. No output means there is no ledger yet: carry on. A malformed ledger prints one warning and yields nothing: carry on without it. Never let this step block planning.
+
+Each check names the stage that owns it, and binds there:
+
+- **`Planning (prd): …`** — a requirement the PRD must settle. In PRD intake (`*-to-tracker` Phase 1.45) a register entry that fails one is a `product-clarity` item, like any other requirement-quality failure.
+- **`Planning (decomposition): …`** — binds in this skill: apply each as an extra obligation on every work unit it concerns, alongside steps 1–6 below. A unit that cannot meet it is split, re-scoped or given its missing dependency now, not left for the worker to discover.
+- **`Planning (ready-gate): …`** — binds in the validator's S18 stateless-pickup dry-run (`lisa-jira-validate-ticket`, `lisa-github-validate-issue`, `lisa-linear-validate-issue`): each becomes a question the dry-run must be able to answer from the item and the links it can resolve.
+
+A check is a learned heuristic, not a new gate number: cite its `id` where it changed a decision, so `last_confirmed` can be advanced at claim time (`project-learnings`). When a check plainly does not apply to this work, skip it silently.
+
 ### 1. Identify Units of Work
 
 - Break the work into the smallest units that are independently valuable