@codyswann/lisa 4.86.1 → 4.87.1

package/plugins/lisa-copilot/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/lisa-copilot/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/lisa-copilot/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

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

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

package/plugins/lisa-cursor/agents/learning-judge.md

@@ -1,6 +1,6 @@
 ---
 name: learning-judge
-description: Skeptical judgment gate for candidate learnings. Classifies each candidate as durable-learning, one-off, misunderstanding/spec-gap, or lisa-upstream with mandatory evidence citation. Hostile default — most candidates are DROPPED; only durable-learning ever persists. Use whenever a failure signal or debrief produces a claimed learning that something wants to write to the project learnings surface.
+description: Skeptical judgment gate for candidate learnings. Classifies each candidate as durable-learning, planning-miss, one-off, misunderstanding/spec-gap, or lisa-upstream with mandatory evidence citation. Hostile default — most candidates are DROPPED; only durable-learning and planning-miss (a dispatched item that needed a human because planning let a gap through) persist. Use whenever a failure signal or debrief produces a claimed learning that something wants to write to the project learnings surface.
 ---
 
 # Learning Judge Agent
@@ -30,6 +30,7 @@ Each candidate you evaluate is a single object:
 | `evidence_links[]` | string[] | Concrete evidence URLs/refs available for citation (failure logs, rejection comments, prior incidents). |
 | `scope_hint` | `project` \| `upstream` | The submitter's guess at where the learning belongs. A hint only — attribution below decides. |
 | `triggering_issue` | string | The issue/work item whose failure produced this candidate. |
+| `signal` | `planning-miss` \| absent | Set by a caller that saw a dispatched item stop for a human or file a new ticket mid-build (`lisa-session-manager`, `lisa-implement`). A hint only — Step 2.5 decides. |
 | `fingerprint` | string | Stable dedupe key for this candidate (computed by the caller, e.g. `lisa-persist-learning`). Echo it back unchanged. |
 
 A candidate missing `triggering_issue` or with an empty evidence set can still be evaluated — but it can never reach `durable-learning`, because the mandatory citations below would be impossible.
@@ -51,27 +52,41 @@ Determine what actually caused the failure. If the root cause is a Lisa-shipped
 Only candidates that survive Steps 0–1 continue. Answer both questions, each with **cited** concrete evidence (from `evidence_links`, `provenance`, or your own tracker/repo lookup):
 
 1. **Prevention** — Would this exact rule, had it existed, have prevented the triggering failure? Re-walk the failure with the rule in force. If the failure would have happened anyway, the rule is a superstition: not durable.
-2. **Recurrence** — Does the failure **class** recur? Cite concrete references: a prior issue, PR, revert, rejection comment, or incident showing the same class of mistake on a different occasion. **No recurrence evidence ⇒ never `durable-learning`.** A single occurrence, however painful, is `one-off` — the class may prove itself later, and the candidate can return with evidence.
+2. **Recurrence** — Does the failure **class** recur? Cite concrete references: a prior issue, PR, revert, rejection comment, or incident showing the same class of mistake on a different occasion. **No recurrence evidence ⇒ never `durable-learning`.** A single occurrence, however painful, is `one-off` — the class may prove itself later, and the candidate can return with evidence. The one exception is a requirement gap that reached a dispatched worker: judge it under Step 2.5 before concluding `one-off`.
 
 Do not accept the candidate's own `why` as evidence — it is the claim under test.
 
-### Step 3: Classify (4-way taxonomy)
+### Step 2.5: Planning miss (a gap planning let through)
+
+A missing, ambiguous, contradictory or undecided requirement is not always a one-ticket problem. PRD intake, decomposition and the ready gate (`work-item-definition-of-ready`, the S18 stateless-pickup dry-run) exist so a dispatched worker never needs a human. When one does, the item's own question gets answered on the item, but the process that let it through is unchanged — dropping the signal guarantees the next PRD repeats it. So a requirement gap is a `planning-miss`, not a drop, when **all** of these hold, each established by cited evidence rather than the candidate's word. (The planning skills are Lisa-shipped, but that alone does not make the miss `lisa-upstream` in Step 1: a check about this project's domain — its report formats, its repos, its integrations — belongs here. Only a domain-free check every project's planning would miss is a Lisa gate defect.)
+
+1. **It was dispatched.** The item had passed the ready gate — it was in the ready role and was picked up for dispatch — claimed by a worker, or held by the dispatcher while routing it to a repository (a `repo-route` hold: the item is past the ready gate and mid-dispatch, and `repo-scope-split` at decomposition should have made the route unambiguous) — before the gap surfaced. Cite the claim, the dispatch, or the ready-role history. A gap found at PRD intake, during validation, or before the ready flip is the gate **working**: that is `misunderstanding/spec-gap`.
+2. **The information really was missing.** Quote what the worker could not find, and confirm it is absent from the item and the links it resolves. If the answer was on the item and the worker misread it, it is `misunderstanding/spec-gap` (the worker's defect, not planning's).
+3. **It is not environmental or planned.** An outage, an expired credential, a flaky tool, missing tool access (`tool-access-gate`), or a decision planning **flagged as a human gate** on the item (`human_gate`, `[lisa-human-gate]`) is not a planning miss: asking there was the plan working. Neither is an item that exhausted its attempts.
+4. **A planning check would have caught it.** This is Step 2's prevention question, asked of planning instead of the build. Name the stage that should have caught it — `prd` (the requirement was never decided), `decomposition` (the work was mis-scoped, mis-split, or depended on something nobody filed, including a leaf the router could not place in one repo per `repo-scope-split`), or `ready-gate` (the item looked ready but S18 should have asked the question) — and re-walk it: with the check in force, the item would not have reached Ready with this gap.
+
+**The rule is the check planning should have run, never the answer.** Rewrite the candidate's `rule` as `Planning (<stage>): <check>` — e.g. `Planning (decomposition): an export ticket must name its report format before it is Ready.` — never `Exports use CSV.`, which only answers the one ticket and belongs on the item. A rule that only makes sense for this one item is not a check: drop it as `misunderstanding/spec-gap`. The `why` names the stage that let it through and quotes what the worker could not find. The prefix is load-bearing: planning skills select these entries from the bounded projection by it (`lisa-task-decomposition` step 0).
+
+**Recurrence never blocks a first occurrence.** A first-occurrence planning miss persists at `low` confidence, so its persistence PR waits for a human to merge it. That is a deliberate, bounded exception to Step 2's recurrence requirement. The hostile default exists because a plausible-but-wrong rule would reach every future session unattended; a `low` rule never does, because a human reads it at the gate first. Meanwhile the signal is unusually strong and unusually rare: each occurrence already cost the human interruption the gate exists to prevent, so waiting for a second occurrence costs a second interruption and teaches nothing new. And the rule only adds a check to planning — a wrong one costs a planning question, not changed build behaviour. With recurrence evidence (another dispatched item that stopped on the same class of gap), Step 4 may grant `high`.
+
+### Step 3: Classify (5-way taxonomy)
 
 Exactly one of:
 
-- **`durable-learning`** — both falsification questions pass with cited evidence. The only classification that persists. Disposition `persist`.
+- **`durable-learning`** — both falsification questions pass with cited evidence. Disposition `persist`.
+- **`planning-miss`** — every Step 2.5 condition holds: the item was dispatched past the ready gate, the information really was missing, the cause is not an outage, an expired credential, a flaky tool or a decision flagged as a human gate, and a named planning check would have caught it. Disposition `persist`, with `planning_stage` set and `rule` rewritten as the check.
 - **`one-off`** — a genuine typo, transient fluke, or single-occurrence mistake with no recurrence evidence. Disposition `drop`.
-- **`misunderstanding/spec-gap`** — the failure traces to an ambiguous or missing requirement, not an agent defect. The fix is a better spec (raise it on the work item), not a rule. Disposition `drop`.
+- **`misunderstanding/spec-gap`** — the failure traces to an ambiguous or missing requirement caught **before** the item was dispatched (the gate worked), or to information the item did hold that was misread. The fix is a better spec (raise it on the work item), not a rule. Disposition `drop`.
 - **`lisa-upstream`** — set in Step 1. Disposition `handoff-upstream`; never persisted locally.
 
-When multiple classifications seem defensible, choose the one that does **not** persist — the hostile default.
+When multiple classifications seem defensible, choose the one that does **not** persist — the hostile default. Dispatch is a fact, not a judgement call: if you cannot cite that the item passed the ready gate and was dispatched, it is not `planning-miss`.
 
-### Step 4: Confidence (durable-learning only)
+### Step 4: Confidence (durable-learning and planning-miss)
 
 - **`high`** — the causal story is unambiguous and the recurrence citations are directly on point. The persistence PR may merge through the project's normal gates unattended.
 - **`low`** — durable on the evidence, but the causal chain has an inferential step or the recurrence evidence is indirect. The persistence PR must wait for a human (auto-merge off + triage label).
 
-If you cannot justify `high` in one sentence a non-engineer would accept, it is `low`.
+If you cannot justify `high` in one sentence a non-engineer would accept, it is `low`. A `planning-miss` with no recurrence citation is always `low`.
 
 ## Verdict Output Schema
 
@@ -79,11 +94,13 @@ Return exactly one verdict object per candidate:
 
 | Field | Type | Meaning |
 |-------|------|---------|
-| `classification` | `durable-learning` \| `one-off` \| `misunderstanding/spec-gap` \| `lisa-upstream` | The Step 3 outcome. |
+| `classification` | `durable-learning` \| `planning-miss` \| `one-off` \| `misunderstanding/spec-gap` \| `lisa-upstream` | The Step 3 outcome. |
 | `cited_evidence[]` | string[] | The concrete refs you actually relied on for this call — prevention and recurrence citations for durable; attribution citations for upstream; the decisive absence/counter-evidence for drops. Never empty. This is what makes a wrong call auditable. |
 | `rationale` | string | 1–3 sentences readable by product, engineering, and QA alike (a non-technical operator stands at the gate). |
-| `confidence` | `high` \| `low` | Present **only** when `classification` is `durable-learning`. |
-| `disposition` | `persist` \| `drop` \| `handoff-upstream` | `persist` iff durable-learning; `handoff-upstream` iff lisa-upstream; otherwise `drop`. |
+| `confidence` | `high` \| `low` | Present **only** when `classification` is `durable-learning` or `planning-miss`. |
+| `planning_stage` | `prd` \| `decomposition` \| `ready-gate` | Present **only** when `classification` is `planning-miss`: the stage that let the gap through. |
+| `rule` | string | Present **only** when `classification` is `planning-miss`: the candidate's rule rewritten as the `Planning (<stage>): <check>` check, within the contract's caps. The caller persists this text, not the submitted one. |
+| `disposition` | `persist` \| `drop` \| `handoff-upstream` | `persist` iff durable-learning or planning-miss; `handoff-upstream` iff lisa-upstream; otherwise `drop`. |
 
 Also echo back the candidate's `fingerprint` and `triggering_issue` so the caller can route without re-deriving them.
 
@@ -102,9 +119,12 @@ Also echo back the candidate's `fingerprint` and `triggering_issue` so the calle
 | Attribution (Lisa vs project) | project/lisa-upstream | [refs] |
 | Prevention (would the rule have prevented it?) | yes/no | [refs] |
 | Recurrence (does the class recur?) | yes/no | [refs] |
+| Planning miss (dispatched, really missing, not environmental or a flagged gate, planning check named) | yes/no/n-a | [refs] |
 
-**Classification**: durable-learning | one-off | misunderstanding/spec-gap | lisa-upstream
-**Confidence**: high | low   (durable-learning only)
+**Classification**: durable-learning | planning-miss | one-off | misunderstanding/spec-gap | lisa-upstream
+**Planning stage**: prd | decomposition | ready-gate   (planning-miss only)
+**Rule**: Planning (<stage>): <check>   (planning-miss only — the rewritten rule the caller persists)
+**Confidence**: high | low   (durable-learning and planning-miss only)
 **Disposition**: persist | drop | handoff-upstream
 **Rationale**: [1–3 plain-language sentences]
 ```
@@ -112,7 +132,7 @@ Also echo back the candidate's `fingerprint` and `triggering_issue` so the calle
 ## Important Reminders
 
 1. **Most candidates DROP** — a session where you persist everything you saw is a failed gate, not a productive one.
-2. **No recurrence citation, no durable-learning** — this is absolute; there are no exceptions for "obviously true" rules.
+2. **No recurrence citation, no durable-learning** — this is absolute; there are no exceptions for "obviously true" rules. A `planning-miss` is not a durable-learning: without recurrence it persists only at `low`, behind a human merge, and the recurrence requirement never blocks a first occurrence of it.
 3. **Cite what you relied on** — a verdict without `cited_evidence` is invalid; re-run the evaluation.
 4. **`lisa-upstream` never becomes a local rule** — classify and hand off; filing the upstream ticket is the caller's flow, not yours.
 5. **You classify; you do not write** — never touch the learnings surface, post comments, or open PRs. The caller (`lisa-persist-learning`) owns all side effects.

package/plugins/lisa-cursor/rules/ready-role-filing-reference.mdc

@@ -105,6 +105,10 @@ Any defect discovered while doing something else, which is complete enough to bu
 
 The same explicitness applies in the other direction. A filing that is genuinely a human product call declares `human_gate`; it does not simply omit the flag and hope the tracker default is the merciful one.
 
+## Mid-build filings are a planning signal
+
+A ticket a worker has to file **while building** a dispatched item, because that item was mis-scoped, mis-split, or depends on work nobody filed, is filed exactly as above. It is also evidence that planning let a gap through, and it is routed as such: the filer sends one `planning-miss` candidate through `lisa-persist-learning`, with the item being built (never the new ticket) as `triggering_issue` and the check planning should have run as the rule. `lisa-implement` owns the step and its exclusions (outages, credentials, tool access, flaky tools, and decisions planning flagged as human gates); the judge decides whether it really was a miss. The signal never delays or changes the filing.
+
 ## The named exception: `lisa-exploratory-qa`
 
 `lisa-exploratory-qa` files its findings **not** build-ready by default, and that is **correct** — it is the named human-gate exception under this rule, not drift to be repaired.

package/plugins/lisa-cursor/rules/work-item-definition-of-ready-reference.mdc

@@ -167,6 +167,14 @@ the caller posts to the source. This is the enforcement of the intake
 contract's core promise, and of TASC AC8.6: *ready means zero-clarification
 executable.*
 
+The dry-run also asks the **learned planning checks**: `planning-miss`
+learnings, the check planning should have run, persisted by `learning-judge`
+each time a dispatched worker still had to stop for a human or file a ticket
+mid-build (CodySwannGT/lisa#4569). They are read through the learnings
+contract's bounded projection (`lisa-task-decomposition` step 0), never the raw
+ledger. A worker that stops anyway is the signal this gate missed something,
+and the loop turns that stop into the next item's question.
+
 ## Relationship to the lifecycle
 
 - **Write time** — `*-write-*` runs the applicable pre-write gates; a spec

package/plugins/lisa-cursor/skills/lisa-confluence-to-tracker/SKILL.md

@@ -240,6 +240,11 @@ planning proceeds. Per atom:
   requirement.
 - **Pattern shape (SHOULD)** — an EARS pattern (ubiquitous / When / While / If-then / Where) or an
   equivalent single-behavior sentence; conforming shapes decompose into Gherkin mechanically.
+- **Learned planning checks** — load the `Planning (...)` checks through the bounded projection
+  (`lisa-task-decomposition` step 0). Test the register against every `Planning (prd)` check; an
+  atom or a missing atom that fails one is a `product-clarity` item quoting the check, exactly
+  like the failures above. Carry the `Planning (decomposition)` checks into Phases 3–5. Each is
+  a gap a dispatched worker once had to stop and ask about, so catching it here is the point.
 
 Failures here are **requirement-level product clarifications**, not internal errors: report each in
 the dry-run report as a `product-clarity` item quoting the atom verbatim, naming the defect, and

package/plugins/lisa-cursor/skills/lisa-delivery-effectiveness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-delivery-effectiveness
-description: "Measure whether the work the factory delivers was worth shipping — gate rejection, rework, escape, first-pass yield and cost per delivered item — so autonomy rate cannot stand alone as a success measure."
+description: "Measure whether the work the factory delivers was worth shipping — gate rejection, rework, escape, first-pass yield, cost per delivered item and planning-miss rate — so autonomy rate cannot stand alone as a success measure."
 allowed-tools: ["Read", "Grep", "Glob", "Bash"]
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: ["Read", "Grep", "Glob", "Bash"]
 
 Autonomy rate answers how much ran without a human. It says nothing about whether any of it should have shipped, and on its own it rewards exactly the wrong thing: a factory that produces rejected work faster scores better.
 
-## The five measures
+## The six measures
 
 Each needs a stated numerator, denominator and window, or it is a number-shaped opinion.
 
@@ -19,8 +19,11 @@ Each needs a stated numerator, denominator and window, or it is a number-shaped
 | **Escape rate** | Defects reaching production, over items released | What the gates did not catch |
 | **First-pass yield** | Items reaching terminal state with no rework, over items started | The one number that moves only when the whole line works |
 | **Cost per delivered item** | Metered spend, over items reaching terminal state | What a unit of accepted output actually costs |
+| **Planning-miss rate** | Items carrying a `[lisa-planning-miss]` note, over items picked up for dispatch (entered the claimed role, or were held by the dispatcher at repository routing) | How often planning let through work a worker could not finish without a human |
 
-First-pass yield is the summary measure worth watching, because every other failure shows up in it. The other four exist to tell you *where* it went.
+First-pass yield is the summary measure worth watching, because every other failure shows up in it. The other five exist to tell you *where* it went.
+
+The planning-miss rate is the one that points upstream of the build. Its numerator is the `[lisa-planning-miss]` note `lisa-persist-learning` leaves on an item when `learning-judge` confirms that a dispatched worker had to stop for a human, or file a new ticket mid-build, because planning let a gap through. Count distinct items, not notes. The note is posted only on a confirmed miss, so outages, expired credentials, flaky tools and decisions planning flagged as human gates are already out of it. Both halves come from the tracker. Each persisted miss also becomes a planning check that PRD intake, decomposition and the ready gate read back, so better planning shows up as this number falling.
 
 ## Where the numbers come from
 
@@ -55,6 +58,7 @@ Report both, together, always. The pairing is the point:
 | Escape rate | | | | | |
 | First-pass yield | | | | | |
 | Cost per delivered item | | | | | |
+| Planning-miss rate | | | | | |
 
 **Reading:** which of the four autonomy/yield quadrants this window sits in
 **Uncollected:** any measure not gathered, and why — never an estimate in its place

package/plugins/lisa-cursor/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -391,15 +391,16 @@ declared, arm normally (the scope rule above). Where one IS declared, absent a
 description that positively states a review ran, treat the context as vacuous.
 Fail closed: absence of evidence is not evidence of a review.
 
-#### Vacuous and transient are different properties
+#### Vacuous, transient or standing: the response is the same
 
-A vacuous context is not automatically something to wait out, and this is the
-distinction a naive wait-and-arm gets wrong — it waits forever on a repository
-where the state never clears. **Only the rate limit has both properties.**
+A vacuous context is never something to wait out. Waiting looks like progress
+but it is a stall, and on a repository where the state never clears it waits
+forever. Some vacuities clear on their own and some do not. **That changes what
+the report says, not what you do:**
 
 | description | vacuous? | clears on its own? |
 | --- | --- | --- |
-| `Review rate limited` | yes | **yes** — a throughput window |
+| `Review rate limited` (and decorated forms such as `Review rate limited (retry in 12m)`) | yes | eventually — a throughput window of unknown length |
 | `Review skipped: manual review required for this OSS repository` | yes | **no** — a standing vendor policy for public repositories |
 | `Review skipped: N files exceed the limit of M` | yes | **no** — not without splitting the pull request |
 | `Review skipped` (bare, no stated reason) | yes | **unknown — treat as standing** |
@@ -408,17 +409,33 @@ A bare skip carries no machine-readable reason, so nothing distinguishes it from
 the standing forms. Requiring a stated reason before treating a skip as vacuous
 is how the commonest form gets missed.
 
-- **Transient (the rate limit, and only the rate limit)** — do not arm yet. Wait
-  the window out and re-request the review **at most once**, then re-classify.
-  If it now proves work, arm. If it does not, stop and treat it as standing.
-  **Never loop**: a retry loop re-triggers the very limit it is escaping, and
-  measured on #3220 a single explicit re-request in this repository was
-  acknowledged, went `Review in progress`, and settled back at
-  `Review rate limited` two seconds later having reviewed nothing — minting a
-  second hollow green. One attempt, then report.
-- **Standing** — do not wait at all, and do not re-request. There is no window
-  to wait out, so waiting produces a stall that reads as progress. Go straight
-  to the watch loop and let step (d) adjudicate the merge in the open.
+**Every row, the rate limit included: do not wait, and do not re-request.** Do
+not arm. Go straight to the watch loop, run the local adversarial review over the
+PR diff at the current head **now**, post it with the substitute marker (step
+(d), "In case 3, substitute"), and keep driving. Fix what it finds, substitute
+again on each new head, and let step (d) merge when the vacuous context is the
+sole remaining gate.
+
+The rate limit used to get a wait-the-window-out-and-re-request-once exception.
+That exception is removed, for three reasons:
+
+- **The window is not short.** Agents waiting it out stalled for an hour or more
+  per pull request, across a whole portfolio of repositories, and nothing about
+  the wait made the merge safer than a substitute review would.
+- **Re-requesting does not work under a throttle.** Measured on #3220, a single
+  explicit re-request was acknowledged, went `Review in progress`, and settled
+  back at `Review rate limited` two seconds later having reviewed nothing. That
+  minted a second hollow green.
+- **Re-requesting destroys evidence.** It overwrites the existing status (see
+  "Never re-request a review to 'refresh' it" in step (d)), so the exception
+  contradicted a rule this file states with no exceptions.
+
+If the reviewer later reviews on its own, nothing special happens. Its threads
+are review threads like any other, and step (d) handles them. A `CHANGES_REQUESTED`
+it leaves is a real blocker (step (e)), and the substitute never overrides it.
+If it now proves work, arm, per the table above. That is a re-classification
+the watch loop makes on what it reads anyway. It is never a reason to wait or
+re-request.
 
 #### A latch somebody else armed
 
@@ -1046,10 +1063,11 @@ configured reviewed-when phrase says what "did work" looks like for this
 project.
 
 Prove the signal from the commit status API as above; a merely pending or queued
-check is not proof of anything and must keep polling. **A transient vacuity is not adjudicated here until the arm gate's
-single wait-and-re-request has been spent** (section 1): a rate limit has a
-window, and merging past one you never waited out is a choice you did not have
-to make. A standing vacuity has no window, so it arrives here immediately.
+check is not proof of anything and must keep polling. **A settled vacuity, the
+rate limit included, arrives here immediately.** There is no wait to spend first
+and no re-request to try: a rate limit's window is of unknown length, and
+waiting it out stalls the pull request without reading a line of the diff. The
+substitute is what makes the merge safe, not the passage of time.
 
 Once the signal is explicit, merge directly with `gh pr merge <pr>
 --<merge_method>` (pass `--admin` only if branch protection lists the vacuous
@@ -1170,6 +1188,34 @@ Deleting the fallback outright would over-correct: it is the only remedy a lane
 without dismissal permission has, and that permission is not universal. This
 narrows it to the case that costs nothing.
 
+**A stale bot verdict under a rate limit: substitute, then stop and report.**
+Under a rate limit or an exhausted review allowance, a bot's old
+`CHANGES_REQUESTED` on an outdated head can end up as the only thing blocking
+the merge. The bot cannot post a fresh review to replace it, so the verdict
+will not clear by itself while the throttle lasts. This was measured on a
+caller repo in the portfolio: every check green, zero unresolved threads, and
+the bot's verdict from an earlier head as the only blocker. In that case:
+
+1. **Do not wait for the window to reset, and do not re-request.** Waiting
+   leaves the pull request wedged for an hour or more. A re-request under the
+   throttle settles hollow and can take away the bot's standing review (see
+   above).
+2. Post the local adversarial review substitute for the **current** head, as
+   step (d) case 3 describes, if one is not already there.
+3. **Then stop** with `blocked:stale-bot-verdict` (section 4). Report exactly
+   that blocker: the bot reviewer, the review id, the outdated head it reviewed
+   and the current head, the unresolved thread count, and that the substitute
+   is posted for the current head. Name the decision that is needed: a human
+   with dismissal rights dismisses that review, or decides it must stand.
+
+Do not dismiss it on the strength of your own substitute. Here the bot's review
+is the only third-party review on the pull request. Dismissing it because of a
+review this run wrote would make the agent both author and judge of the change.
+That is the escalation the bullet above requires, reached right away instead of
+after a wait. A stranded verdict that is **not** the only substantive review, or
+one left by a reviewer that is not throttled, is still handled by the
+dismissal rule above.
+
 **Unverified, and stated as such rather than asserted:** that a bot's re-review
 REPLACES its predecessor in the effective set is inferred from the observed
 consequence, not measured against the vendor. It has not been tested here, and
@@ -1453,7 +1499,7 @@ Loop until one of:
   the mode forbids acting on them: `on_blocker=report`). The latch is
   deliberately not armed, so the PR sits OPEN rather than merging on a review
   nothing performed. Report the PR URL, the review context's settled
-  description, whether it is transient or standing, and which sole-gate
+  description, whether it clears on its own (a rate limit) or is standing, and which sole-gate
   condition failed. This is an outcome that needs an operator, stated in one
   line a non-technical reader can act on — for example: *"PR #123 is ready to
   merge but nobody reviewed it: the review tool says it skips public
@@ -1483,6 +1529,16 @@ Loop until one of:
   — but a review asked for changes and that is still on record, so it will sit
   there forever. Someone needs to clear that review or resolve the open
   comments."* Never report this PR as merging.
+- **`blocked:stale-bot-verdict`** — the only thing blocking the merge is a
+  bot's `CHANGES_REQUESTED` on an outdated head, the bot is rate limited or out
+  of review allowance so it cannot replace that verdict, and the local
+  adversarial review substitute is posted for the current head (step (e)).
+  Report the reviewer, the review id, both heads, the unresolved thread count,
+  and the dismissal decision a human needs to make. For example: *"PR #123 is
+  ready except for an old review from the review bot on an earlier version. The
+  bot is rate limited and cannot re-review, and I posted my own review of the
+  current version. Someone with dismissal rights needs to dismiss review 456,
+  or decide it should stand."* Do not wait for the bot's window to reset.
 - **`CLOSED`** → report (PR was closed without merge).
 - **Hard block needing a human**: an unresolvable conflict, a failing check that
   needs design input, or genuine unresolved human objection (not a bot gate). Stop
@@ -1591,7 +1647,8 @@ declare none, one, or several, and each shows its own evidence.
 
 Quote the description that was actually read. A report that says "rate limited"
 on a policy skip is a wrong record, and the two call for different operator
-actions: one clears itself, the other never will.
+actions: one clears itself, the other never will. Neither changes what this
+skill does in the meantime: it substitutes and keeps driving in both cases.
 
 `NOT REVIEWED` is reporting, and on a merged PR it is never a terminal state of
 its own: it does not turn a merged PR into a blocked one. What it does gate is

package/plugins/lisa-cursor/skills/lisa-github-to-tracker/SKILL.md

@@ -227,6 +227,11 @@ planning proceeds. Per atom:
   requirement.
 - **Pattern shape (SHOULD)** — an EARS pattern (ubiquitous / When / While / If-then / Where) or an
   equivalent single-behavior sentence; conforming shapes decompose into Gherkin mechanically.
+- **Learned planning checks** — load the `Planning (...)` checks through the bounded projection
+  (`lisa-task-decomposition` step 0). Test the register against every `Planning (prd)` check; an
+  atom or a missing atom that fails one is a `product-clarity` item quoting the check, exactly
+  like the failures above. Carry the `Planning (decomposition)` checks into Phases 3–5. Each is
+  a gap a dispatched worker once had to stop and ask about, so catching it here is the point.
 
 Failures here are **requirement-level product clarifications**, not internal errors: report each in
 the dry-run report as a `product-clarity` item quoting the atom verbatim, naming the defect, and

package/plugins/lisa-cursor/skills/lisa-github-validate-issue/SKILL.md

@@ -345,6 +345,8 @@ Without a baseline and a target an Improvement has no verifiable terminal state
 
 The autonomy gate, run last, on every build-ready leaf (use the S15 classification; `N/A` for containers and non-build-ready items). Simulate a stateless agent reading only this item and the links it can resolve — session knowledge about the codebase does not count, because the next claimant will not have it. List every question that agent would have to ask a human before starting work, before choosing between materially different implementations, or before declaring the work done.
 
+**Learned planning checks.** Questions that past dispatched workers actually had to stop and ask are the best predictor of the next one. Load the `Planning (...)` checks through the bounded projection exactly as `lisa-task-decomposition` step 0 does, and add each one that applies to this item as a question the simulated agent must be able to answer from the item and the links it can resolve, the same reach S18 already allows. One it cannot answer is a FAIL question like any other, quoting the check's rule. No ledger, or a malformed one, adds nothing and never fails this gate.
+
 Zero questions → PASS. Any question → FAIL, with each question listed verbatim as its own remediation line — these are exactly the clarifying comments the caller posts to the source. The structure gates are proxies; this gate checks the readiness property itself: `ready` means a stateless agent can drive this item to its terminal state with zero human clarification (see `work-item-definition-of-ready`).
 
 #### S19 — Branch Plan derivation

package/plugins/lisa-cursor/skills/lisa-implement/SKILL.md

@@ -345,6 +345,8 @@ Before shutting down the team, execute the Verify flow:
     - **Actionable blocker** — an unresolved dependency or fixable technical gap that some team or repository could build (a missing or changed schema field, an unbuilt sibling work item, a required upstream fix), **including cross-repo dependencies**. Before writing the blocked verdict you MUST (1) file a build-ready fix/dependency ticket capturing the diagnosis — in the dependency's own repository/tracker when it is cross-repo (e.g. a `[<repo>] …` ticket in the shared project, or the sibling tracker) — and (2) link the current work item to it as `is blocked by`. Only then write the verdict. This is the same discipline as the regression-spec blocker and the remote-verification-fail exits above, and it is what makes the block machine-recoverable: `repair-intake` re-dispatches a blocked item once its linked `is blocked by` dependency closes, but it cannot act on a prose-only comment. Recommending the ticket "as a human follow-up" without filing and linking it is **not** a permitted exit.
     - **Human-only blocker** — an input the agent genuinely cannot obtain or produce no matter what it does: credentials, secrets, or **tool access** it does not have (AWS/CloudWatch, Figma, Jam, Sentry, SonarCloud, a database, a protected deploy target, …), or a product/design decision only a human can make. For missing tool access, follow the `tool-access-gate` rule's break-out protocol: post the "Access Needed" comment naming the exact credential/role/env var to grant and the probe that must pass — never work around the gap by substituting weaker verification, mocking the inaccessible system, or narrowing scope. Record the blocked verdict, mark it `human_needed` (the marker `repair-intake` recognizes, so it won't churn re-dispatching it), and surface or reassign to a human; do **not** fabricate a build-ready ticket, because there is no build-ready work.
 
+    **Planning-miss signal.** Either exit can mean planning let a gap through, and that signal is worth more than the one ticket (CodySwannGT/lisa#4569). It is a planning miss when you file a new ticket mid-build because this item was mis-scoped, mis-split, or depends on work nobody filed, or when you mark it `human_needed` because a requirement was missing, unclear, contradictory or undecided. It is **not** one when the cause is an outage, an expired credential, missing tool access, a flaky tool, or a decision the item itself flagged as a human gate. For a planning miss, route one candidate through `lisa-persist-learning` with `signal: planning-miss`, `triggering_issue` = **this** item (never the new ticket), `rule` = the check planning should have run, as `Planning (<prd|decomposition|ready-gate>): <check>` (not this item's answer), `why` = the stage that let it through plus a quote of what you could not find, and `evidence_links` = the new ticket or the blocked-verdict comment. Run it as a background subagent where the runtime has one, otherwise after the blocked verdict is recorded; it is headless-safe, never blocks the exit, and its failure is one line in the final summary. Under `managedBy=`, the manager routes a human-needed stop itself when it marks the item, so route only the mid-build ticket case there; routing both would double-count one miss.
+
     **Harnesses that do not fire a Stop hook enforce the same discipline by convention.** The
     `enforce-verification-gate.sh` Stop hook is a **Claude-only** surface — Codex, Cursor, Antigravity,
     Copilot, and OpenCode carry the skills, agents, and (where the runtime has a rules surface) the

package/plugins/lisa-cursor/skills/lisa-jira-validate-ticket/SKILL.md

@@ -347,6 +347,8 @@ Without a baseline and a target an Improvement has no verifiable terminal state
 
 The autonomy gate, run last, on every build-ready leaf (use the S15 classification; `N/A` for containers and non-build-ready items). Simulate a stateless agent reading only this item and the links it can resolve — session knowledge about the codebase does not count, because the next claimant will not have it. List every question that agent would have to ask a human before starting work, before choosing between materially different implementations, or before declaring the work done.
 
+**Learned planning checks.** Questions that past dispatched workers actually had to stop and ask are the best predictor of the next one. Load the `Planning (...)` checks through the bounded projection exactly as `lisa-task-decomposition` step 0 does, and add each one that applies to this item as a question the simulated agent must be able to answer from the item and the links it can resolve, the same reach S18 already allows. One it cannot answer is a FAIL question like any other, quoting the check's rule. No ledger, or a malformed one, adds nothing and never fails this gate.
+
 Zero questions → PASS. Any question → FAIL, with each question listed verbatim as its own remediation line — these are exactly the clarifying comments the caller posts to the source. The structure gates are proxies; this gate checks the readiness property itself: `ready` means a stateless agent can drive this item to its terminal state with zero human clarification (see `work-item-definition-of-ready`).
 
 #### S19 — Branch Plan derivation

package/plugins/lisa-cursor/skills/lisa-learnings-audit/SKILL.md

@@ -83,6 +83,15 @@ a `last_confirmed` bump), **RETIRE** (provably redundant/stale — proof, not
 vibes), or leave alone. No evidence ⇒ no candidate; the gardener never files
 a recommendation it cannot evidence.
 
+**Learned planning checks.** A ledger entry whose rule begins
+`Planning (prd|decomposition|ready-gate):` is a `planning-miss` learning: the
+check planning should have run before a dispatched worker had to stop for a
+human (CodySwannGT/lisa#4569). When Recurrence shows the same class of gap
+stopping workers on more than one item, it is a PROMOTE candidate into the
+ready gate itself — the `work-item-definition-of-ready` rule or the validators'
+S18 dry-run — rather than one more ledger entry competing for the projection.
+A recurring miss counts once per `[lisa-planning-miss]` note on distinct items.
+
 **The eager tier is audited every run** — including
 **Lisa's own shipped eager rules**, not just host additions. Admission is demotion-biased and
 earned only by repeated-miss evidence (see the `promotion-contract` rule);