@codyswann/lisa 2.254.0 → 2.256.0

package/plugins/lisa/scripts/automation-status-codex-adapter.mjs

@@ -22,6 +22,10 @@ import {
   createAutomationGroupBins,
   renderAutomationGroups,
 } from "./automation-status-expected-fleet.mjs";
+import {
+  resolveAutomationRunDisplay,
+  resolveRecoveryEscalation,
+} from "./automation-status-run-history.mjs";
 
 const CODEx_RUNTIME_LABEL = "Codex automations";
 const RUN_TIMESTAMP_PATTERN = /20\d{2}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z/;
@@ -132,6 +136,7 @@ async function execGitWithRetry(args, options, attempts = 4) {
  * @param {{
  *   readonly expectedFleet: ExpectedFleet
  *   readonly automationsDir?: string
+ *   readonly projectRoot?: string
  *   readonly now?: string | Date
  * }} input
  * @returns {Promise<{
@@ -147,6 +152,10 @@ async function execGitWithRetry(args, options, attempts = 4) {
  *       readonly expectedCadence?: string
  *       readonly expectedCommand?: string
  *       readonly observed?: string
+ *       readonly runbook?: string
+ *       readonly lastOutcome?: { readonly ts: string, readonly outcome: string, readonly summary: string }
+ *       readonly outcomeHistory?: readonly string[]
+ *       readonly olderRecordCount?: number
  *       readonly remediation?: string
  *     }[]
  *   }[]
@@ -156,11 +165,14 @@ async function execGitWithRetry(args, options, attempts = 4) {
 export async function inspectCodexAutomationFleet(input) {
   const expectedFleet = input.expectedFleet;
   const now = normalizeDate(input.now);
+  const projectRoot = input.projectRoot ?? process.cwd();
   const observedAutomations = await listCodexAutomations({
     automationsDir: input.automationsDir,
     automationPrefix: expectedFleet.automationPrefix,
   });
 
+  const runDisplays = await resolveFleetRunDisplays(projectRoot, expectedFleet);
+
   const expectedGroups = createAutomationGroupBins();
 
   const comparisons = compareAutomationFleet({
@@ -177,17 +189,23 @@ export async function inspectCodexAutomationFleet(input) {
         expected,
         comparison,
         now,
+        runDisplay: runDisplays.get(expected.id),
       })
     );
   }
 
   for (const unsupported of expectedFleet.unsupported) {
+    const runDisplay = runDisplays.get(unsupported.id);
     assignToAutomationGroup(expectedGroups, unsupported.group, {
       id: unsupported.automationId,
       status: "UNSUPPORTED",
       summary: unsupported.reason,
       expectedCadence: unsupported.expectedCadence,
       observed: "No automation is expected for this repo/runtime combination.",
+      runbook: runDisplay?.runbook,
+      lastOutcome: runDisplay?.lastOutcome,
+      outcomeHistory: runDisplay?.outcomeHistory,
+      olderRecordCount: runDisplay?.olderRecordCount,
     });
   }
 
@@ -374,15 +392,43 @@ async function readCodexAutomation(automationDir) {
   };
 }
 
+/**
+ * Read the read-only run-history display for every expected and unsupported
+ * loop up front, keyed by the loop's short id, so the per-entry item builder
+ * stays synchronous.
+ *
+ * @param {string} projectRoot
+ * @param {ExpectedFleet} expectedFleet
+ * @returns {Promise<Map<string, import("./automation-status-run-history.mjs").AutomationRunDisplay>>}
+ */
+async function resolveFleetRunDisplays(projectRoot, expectedFleet) {
+  const entries = [...expectedFleet.expected, ...expectedFleet.unsupported];
+  const displays = await Promise.all(
+    entries.map(entry =>
+      resolveAutomationRunDisplay({
+        projectRoot,
+        loopId: entry.id,
+        runbookPath: entry.runbookPath,
+      })
+    )
+  );
+  return new Map(entries.map((entry, index) => [entry.id, displays[index]]));
+}
+
 function createObservedStatusItem(input) {
   const expected = input.expected;
   const comparison = input.comparison;
   const observed = comparison.observedAutomation;
+  const runDisplay = input.runDisplay;
   const runSignal = classifyAutomationRunSignal({
     expected,
     observedAutomation: observed,
     now: input.now,
   });
+  // Three or more consecutive recorded recovery-required runs flip the loop to
+  // FAILING even when the scheduler entry looks fine — the fleet-health signal
+  // the raw backing store cannot see. It wins over the scheduler run-signal.
+  const escalation = resolveRecoveryEscalation(runDisplay);
 
   const observedDetails = [comparison.observed];
   if (observed?.status) {
@@ -401,20 +447,30 @@ function createObservedStatusItem(input) {
   }
 
   const status =
+    escalation?.status ??
     runSignal?.status ??
     /** @type {"HEALTHY" | "MISSING" | "DRIFTED"} */ (comparison.status);
 
   return {
     id: expected.automationId,
     status,
-    summary: composeAutomationSummary({
-      comparison,
-      runSignal,
-    }),
+    summary: escalation
+      ? escalation.summary
+      : composeAutomationSummary({
+          comparison,
+          runSignal,
+        }),
     expectedCadence: expected.expectedCadence,
     expectedCommand: expected.expectedCommand,
     observed: observedDetails.join(" "),
-    remediation: runSignal?.remediation ?? comparison.remediation,
+    runbook: runDisplay?.runbook,
+    lastOutcome: runDisplay?.lastOutcome,
+    outcomeHistory: runDisplay?.outcomeHistory,
+    olderRecordCount: runDisplay?.olderRecordCount,
+    remediation:
+      escalation?.remediation ??
+      runSignal?.remediation ??
+      comparison.remediation,
   };
 }
 

package/plugins/lisa/scripts/automation-status-report.mjs

@@ -26,12 +26,22 @@ export const AUTOMATION_FLEET_VERDICTS = [
  * @typedef {"HEALTHY" | "PARTIAL_SUPPORT" | "ATTENTION_NEEDED"} AutomationFleetVerdict
  *
  * @typedef {{
+ *   readonly ts: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ * }} AutomationLastOutcome
+ *
+ * @typedef {{
  *   readonly id: string
  *   readonly status: AutomationHealthStatus
  *   readonly summary: string
  *   readonly expectedCadence?: string
  *   readonly expectedCommand?: string
  *   readonly observed?: string
+ *   readonly runbook?: string
+ *   readonly lastOutcome?: AutomationLastOutcome
+ *   readonly outcomeHistory?: readonly string[]
+ *   readonly olderRecordCount?: number
  *   readonly remediation?: string
  * }} AutomationStatusItem
  *
@@ -130,6 +140,26 @@ export function renderAutomationStatusReport(input) {
       if (item.observed) {
         lines.push(`  Observed: ${item.observed}`);
       }
+      // Contract + run-history block: observable facts about where the runbook
+      // lives and how recent runs ended, kept between Observed and Remediation
+      // so operators read the state before the fix. Every line degrades
+      // explicitly — an absent runbook or empty history is stated, never blank.
+      if (item.runbook !== undefined) {
+        lines.push(`  Runbook: ${item.runbook}`);
+        lines.push(
+          item.lastOutcome
+            ? `  Last run: ${item.lastOutcome.outcome} — ${item.lastOutcome.summary} (${item.lastOutcome.ts})`
+            : "  Last run: no recorded runs yet"
+        );
+        if (item.outcomeHistory && item.outcomeHistory.length > 0) {
+          const historyLine = `  History: ${item.outcomeHistory.join(", ")} (newest first)`;
+          lines.push(
+            item.olderRecordCount && item.olderRecordCount > 0
+              ? `${historyLine}; … and ${item.olderRecordCount} older records`
+              : historyLine
+          );
+        }
+      }
       if (item.remediation) {
         lines.push(`  Remediation: ${item.remediation}`);
       }

package/plugins/lisa/scripts/automation-status-run-history.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Shared read-only run-history projection for `/lisa:automation-status`.
+ *
+ * The durable run-outcome substrate (RBC-3, `automation-run-record.mjs`) stores
+ * one bounded JSONL file per registered loop under `.lisa/automations/runs/`.
+ * This module turns that substrate — plus the checked-in per-loop runbook
+ * (`automation-runbook-contract`) — into the per-item display fields both
+ * runtime adapters attach to their status rows, so the Codex and Claude
+ * adapters never diverge on how the contract, last outcome, and bounded history
+ * are rendered.
+ *
+ * STRICTLY READ-ONLY: it stats the runbook and reads the run-record file. It
+ * never creates the runs directory, a runbook, or a run record — a status read
+ * must leave the fleet byte-identical.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  automationRunRecordPath,
+  readAutomationRunRecords,
+} from "./automation-run-record.mjs";
+
+/**
+ * Inline history cap: the newest N outcomes are listed, the remainder is only
+ * counted. A bounded view of an already-bounded file, with the trim stated in
+ * the output rather than applied silently.
+ */
+export const AUTOMATION_RUN_HISTORY_DISPLAY_LIMIT = 5;
+
+/** The recorded outcome that signals a loop could not finish its own work. */
+export const RECOVERY_REQUIRED_OUTCOME = "recovery-required";
+
+/**
+ * How many trailing `recovery-required` runs in a row flip a loop to `FAILING`.
+ * The RBC-5 acceptance criteria pin "last three runs" as the escalation
+ * trigger; that wins over the ticket prose's looser "five in a row" pattern.
+ */
+export const RECOVERY_REQUIRED_ESCALATION_THRESHOLD = 3;
+
+const RUNBOOK_NOT_SCAFFOLDED_LINE =
+  "not scaffolded — run /lisa:setup-automations";
+const NO_RECORDED_RUNS_LINE = "no recorded runs yet";
+
+/**
+ * @typedef {{
+ *   readonly ts: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ * }} AutomationLastOutcome
+ *
+ * @typedef {{
+ *   readonly runbook: string
+ *   readonly lastOutcome?: AutomationLastOutcome
+ *   readonly outcomeHistory: readonly string[]
+ *   readonly olderRecordCount: number
+ *   readonly recoveryRequiredStreak: number
+ *   readonly recoverySummaries: readonly string[]
+ *   readonly skippedCorruptLines: number
+ * }} AutomationRunDisplay
+ */
+
+/**
+ * Resolve the read-only run-history display fields for one registered loop.
+ *
+ * @param {{
+ *   readonly projectRoot?: string
+ *   readonly loopId: string
+ *   readonly runbookPath?: string
+ * }} input
+ * @returns {Promise<AutomationRunDisplay>}
+ */
+export async function resolveAutomationRunDisplay(input) {
+  const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+  const runbook = await resolveRunbookLine(projectRoot, input.runbookPath);
+  const { records, skippedCorruptLines } = await readAutomationRunRecords(
+    automationRunRecordPath(projectRoot, input.loopId)
+  );
+
+  const newestFirst = records.toReversed();
+  const latest = records.at(-1);
+  const lastOutcome = latest
+    ? { ts: latest.ts, outcome: latest.outcome, summary: latest.summary }
+    : undefined;
+  const outcomeHistory = newestFirst
+    .slice(0, AUTOMATION_RUN_HISTORY_DISPLAY_LIMIT)
+    .map(record => record.outcome);
+  const olderRecordCount = Math.max(
+    0,
+    records.length - AUTOMATION_RUN_HISTORY_DISPLAY_LIMIT
+  );
+  const trailingRecovery = collectTrailingRecoveryRuns(records);
+
+  return {
+    runbook,
+    lastOutcome,
+    outcomeHistory,
+    olderRecordCount,
+    recoveryRequiredStreak: trailingRecovery.length,
+    recoverySummaries: trailingRecovery.map(record => record.summary),
+    skippedCorruptLines,
+  };
+}
+
+/**
+ * Force a `FAILING` verdict when a loop has recorded three or more consecutive
+ * `recovery-required` runs — the fleet-health signal the scheduler surface
+ * cannot see on its own. Returns a run-signal-shaped escalation, or null when
+ * the streak is below the threshold.
+ *
+ * @param {AutomationRunDisplay | undefined} runDisplay
+ * @returns {{ readonly status: "FAILING", readonly summary: string, readonly remediation: string } | null}
+ */
+export function resolveRecoveryEscalation(runDisplay) {
+  if (
+    !runDisplay ||
+    runDisplay.recoveryRequiredStreak < RECOVERY_REQUIRED_ESCALATION_THRESHOLD
+  ) {
+    return null;
+  }
+
+  // Number the citations rather than joining on a delimiter: recorded summaries
+  // carry their own `;` and `.`, so a `; `-separated list is ambiguous. `(1) …
+  // (2) …` stays legible no matter what punctuation a summary contains.
+  const citations = runDisplay.recoverySummaries
+    .map((summary, index) => `(${index + 1}) ${summary}`)
+    .join(" ");
+  return {
+    status: "FAILING",
+    summary: `the last ${runDisplay.recoveryRequiredStreak} recorded runs all required recovery`,
+    remediation: `Repeated recovery-required runs — ${citations} Inspect the loop's runbook and the cited runs, fix the recurring failure, then let the next scheduled run confirm recovery.`,
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string | undefined} runbookPath
+ * @returns {Promise<string>}
+ */
+async function resolveRunbookLine(projectRoot, runbookPath) {
+  if (!runbookPath) {
+    return RUNBOOK_NOT_SCAFFOLDED_LINE;
+  }
+  const scaffolded = await runbookIsScaffolded(
+    path.join(projectRoot, runbookPath)
+  );
+  return scaffolded ? runbookPath : RUNBOOK_NOT_SCAFFOLDED_LINE;
+}
+
+/**
+ * Read-only existence check for a checked-in runbook. Any stat failure — the
+ * file is absent, unreadable, or not a regular file — degrades to "not
+ * scaffolded" so the status read never implies health it could not confirm and
+ * never throws mid-report.
+ *
+ * @param {string} runbookAbsolutePath
+ * @returns {Promise<boolean>}
+ */
+async function runbookIsScaffolded(runbookAbsolutePath) {
+  try {
+    const stat = await fs.stat(runbookAbsolutePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {readonly import("./automation-run-record.mjs").AutomationRunRecord[]} records
+ * @returns {readonly import("./automation-run-record.mjs").AutomationRunRecord[]} trailing recovery-required runs, newest first
+ */
+function collectTrailingRecoveryRuns(records) {
+  const trailing = [];
+  for (let index = records.length - 1; index >= 0; index -= 1) {
+    if (records[index].outcome !== RECOVERY_REQUIRED_OUTCOME) {
+      break;
+    }
+    trailing.push(records[index]);
+  }
+  return trailing;
+}
+
+export { RUNBOOK_NOT_SCAFFOLDED_LINE, NO_RECORDED_RUNS_LINE };

package/plugins/lisa/skills/lisa-automation-status/SKILL.md

@@ -53,8 +53,13 @@ For each expected automation, report:
 4. Any detected drift in name, cadence, command shape, or queue arguments.
 5. Any available recent-run health signal such as stale last-run timing or repeated failure status.
 6. A concise remediation hint when attention is needed.
+7. Where the loop's checked-in runbook lives (`automation-runbook-contract`), or `not scaffolded — run /lisa:setup-automations` when it is absent.
+8. How the last recorded run ended — its outcome, one-line summary, and timestamp — or `no recorded runs yet` when the loop has never recorded one.
+9. A bounded run history: the five most recent outcomes newest first, plus a count of how many older records exist when the file holds more.
 
-Emit an overall grouped fleet verdict such as `HEALTHY`, `ATTENTION_NEEDED`, or `PARTIAL_SUPPORT`, plus the runtime surface inspected.
+The last-run and history facts come from the durable run-outcome substrate recorded by each loop (the RBC-3 records under `.lisa/automations/runs/<loop-id>.jsonl`, read through `readAutomationRunRecords`). That directory is local scheduler state, not project knowledge — read it, never write it.
+
+Emit an overall grouped fleet verdict such as `HEALTHY`, `ATTENTION_NEEDED`, or `PARTIAL_SUPPORT`, plus the runtime surface inspected. **Repeated recovery is a fleet-health signal the scheduler cannot see**: when a loop's last three or more consecutive recorded runs are all `recovery-required`, report that loop `FAILING` — and therefore the overall verdict `ATTENTION_NEEDED` — even when its scheduler entry itself looks healthy, and point the remediation at the recorded run summaries.
 
 ## Operator usage
 
@@ -89,7 +94,7 @@ Status-specific remediation guidance:
 - `MISSING`: tell the operator which job is absent and recommend rerunning `/lisa:setup-automations` or recreating the missing job with the expected cadence and command.
 - `DRIFTED`: show the expected versus observed cadence/command mismatch and recommend aligning the scheduler entry with Lisa's current setup contract, usually by rerunning `/lisa:setup-automations`.
 - `STALE`: explain that the job exists but has not run recently enough for its cadence. Recommend inspecting the runtime's recent-run history or failure logs before changing queue state.
-- `FAILING`: surface the failure signal directly and recommend checking the latest runtime error plus the affected queue command (`/lisa:intake`, `/lisa:repair-intake`, or exploratory job) after the scheduler issue is resolved.
+- `FAILING`: surface the failure signal directly and recommend checking the latest runtime error plus the affected queue command (`/lisa:intake`, `/lisa:repair-intake`, or exploratory job) after the scheduler issue is resolved. A loop also reports `FAILING` when its last three or more consecutive recorded runs are all `recovery-required` — even with a healthy scheduler entry — in which case cite the recorded run summaries and point the operator at the loop's runbook.
 - `UNSUPPORTED`: explain why the job is intentionally absent and say that no remediation is required unless the project stack or runtime support changed.
 
 Render the report in grouped sections using the shared `scripts/automation-status-report.mjs` contract:
@@ -104,10 +109,13 @@ Generated at: <ISO timestamp>
 - <STATUS> <automation-id>: <summary>
   Expected: <cadence> -> <command>
   Observed: <what the runtime exposed>
+  Runbook: <.lisa/automations/<loop-id>.runbook.md, or "not scaffolded — run /lisa:setup-automations">
+  Last run: <outcome> — <summary> (<ts>), or "no recorded runs yet"
+  History: <outcome>, <outcome>, … (newest first); … and <N> older records
   Remediation: <next step when attention is needed>
 ```
 
-Keep observable runtime facts separate from remediation guidance so operators can distinguish drift, unsupported jobs, and actual failures quickly.
+The Runbook, Last run, and History lines are observable facts and sit between Observed and Remediation. Keep observable runtime facts separate from remediation guidance so operators can distinguish drift, unsupported jobs, and actual failures quickly.
 
 ## Rules
 

package/plugins/lisa/skills/lisa-exploratory-qa/SKILL.md

@@ -85,6 +85,36 @@ No report file. Emit a concise in-session summary:
 - **Findings filed**, bucketed by type — each with its **created or referenced ticket ref** and **build-ready state**.
 - **Observed but not filed:** anything noticed but intentionally not ticketed (including forbidden-mutation blocks), with why.
 
+## Run outcome
+
+As the registered `exploratory-bugs` automation loop, this pass conforms to the
+`automation-runbook-contract` rule: every invocation ends in **exactly one** of the six run outcomes
+and records it, so a quiet run and a broken run are never mistaken for each other.
+
+| This cycle's exit path | Run outcome |
+|---|---|
+| Findings filed — one or more `Bug` / `Improvement` tickets created or referenced (§6) | `candidate-proposed` |
+| Clean pass — explored the personas and surfaces, nothing worth filing | `nothing-needed` |
+| Tracker unconfigured — the §1 stop path; findings cannot be filed | `recovery-required` |
+| A degradation that still let the pass explore (e.g. Kane unavailable, one persona unreachable) | the outcome it actually reached above, with the summary **leading with the degradation** — degradation never mints a seventh token |
+
+Record **exactly one** outcome per invocation through the run-record CLI, naming this loop's runbook
+(the `--summary` is the operator-readable one-liner in the contract's exemplar voice — plain,
+specific, actionable, e.g. `Explored 4 personas; nothing confusing to file.` for `nothing-needed`):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id exploratory-bugs --outcome candidate-proposed \
+  --summary "Explored 4 personas; filed 3 findings from the checkout flow — awaiting your flip to ready." \
+  --runbook .lisa/automations/exploratory-bugs.runbook.md [--ref <ticket-url>]...
+```
+
+If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
+`plugins/lisa/scripts/automation-run-record.mjs` or the source
+`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
+abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
+the cycle — a recording failure is a degradation to report, never a reason to block the loop.
+
 ## Quality bar
 
 - Explore as a true first-time user — judge clarity, not whether you (who can read the code) can figure it out.

package/plugins/lisa/skills/lisa-intake/SKILL.md

@@ -116,6 +116,46 @@ The single-item skills (`lisa-plan`, `lisa-implement`) and the per-vendor batch
 5. **Stop after one item** — a claimed Ready item, a safe-blocked container, or a per-item error ends the *ready-claim* portion of the cycle. The per-vendor PRD scanner still runs its rollup and one verify-prd dispatch. Remaining Ready items stay untouched for later scheduler invocations.
 6. **Summary report** — the single processed/skipped/error item, total processed, total errors. Before returning, record intake usage on the persisted cycle-summary artifact via `lisa-usage-accounting` so the summary carries a direct `lisa-intake` entry in the canonical `## Lisa Usage` section. If the claimed / skipped work item's parent-child graph is already known, prefer `record_and_rollup` so ancestor totals refresh in the same cycle; otherwise still write the direct entry, and if runtime usage is unavailable, use `source: unavailable` with nullable token/cost fields instead of skipping the row.
 
+## Run outcome
+
+As a registered automation loop, each Intake cycle conforms to the `automation-runbook-contract`
+rule: it ends in **exactly one** of the six run outcomes and records it, so a quiet queue and a
+broken loop never look alike. Intake backs **two** registered loop-ids — record under the one that
+matches the mode this cycle ran in: **`intake-prd`** (PRD-side dispatch) or **`intake-tickets`**
+(build-queue dispatch).
+
+| This cycle's exit path | Run outcome |
+|---|---|
+| Empty `Ready` set — the idle case (step 3), nothing to claim | `nothing-needed` |
+| A PRD routed to `Blocked` (clarifying questions) or `Ticketed`; a build ticket claimed and dispatched | `candidate-proposed` |
+| A build cycle that shipped and verified (merged PR + evidence), or a shipped PRD moved to `verified` | `change-proved` |
+| A protected deployment (or other autonomy boundary the lifecycle hits) waiting on a human approval | `approval-requested` |
+| The queue itself is misconfigured or unreadable — missing required input (step 1) or an unreachable Status/workflow (step 2/`3` misconfig) so the cycle could not run | `recovery-required` |
+
+**Seam warning (the #1 misread in this ticket).** A run outcome describes this *cycle*; `Blocked` is
+a *work item's* lifecycle terminal state — the two never merge in the summary. When Intake correctly
+routes to `Blocked` (an item whose requirements are unresolvable, carrying clarifying questions), the
+cycle **produced something**, so it is a successful run — `candidate-proposed`, and **never
+`recovery-required`** (the machinery is not broken) and **never `nothing-needed`** (the run did not
+find nothing). The summary must say both plainly: the item was blocked *and* the run succeeded.
+
+Record **exactly one** outcome per invocation through the run-record CLI, naming this loop's runbook
+(the `--summary` is the operator-readable one-liner in the contract's exemplar voice — plain,
+specific, actionable, e.g. `Scanned 12 ready items; nothing to propose.` for `nothing-needed`):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id intake-tickets --outcome candidate-proposed \
+  --summary "Routed PRD #1810 to Blocked with clarifying questions; the run succeeded." \
+  --runbook .lisa/automations/intake-tickets.runbook.md [--ref <item-url>]...
+```
+
+If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
+`plugins/lisa/scripts/automation-run-record.mjs` or the source
+`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
+abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
+the cycle — a recording failure is a degradation to report, never a reason to block the loop.
+
 ## Schedule examples
 
 ```text

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

@@ -124,7 +124,10 @@ audits the auditor without re-running it.
    `drafted_artifact`; the gardener decides whether the evidence clears the
    filing bar and attaches the router's draft to the ticket.
 4. **Emit** (see Ticket emission).
-5. **Report** the terminal state and one-line summary.
+5. **Report and record** the run outcome and one-line summary — post the
+   outcome, then record **exactly one** run-record line through the CLI (see
+   Run outcomes), including the escalation path when it ends
+   `recovery-required`.
 
 ## Ticket emission
 
@@ -280,17 +283,50 @@ marker-recoverable per-item tickets and a missing (not half-filled) batch:
 the most recoverable state. Never attempt to "roll back" filed tickets —
 close-out decisions belong to humans.
 
-## Terminal states
+## Run outcomes
+
+Exactly one per run, from the closed six-value vocabulary of the
+`automation-runbook-contract` rule:
+**`nothing-needed | candidate-proposed | change-proved | approval-requested | recovery-required | policy-obsolete`**.
+
+This section supersedes the gardener's earlier three-value *terminal states*
+vocabulary (`nothing-needed | candidates-proposed | blocked`); the mapping is
+exact so nothing regresses:
+
+- `candidates-proposed` → **`candidate-proposed`** — per-item and/or batch
+  tickets filed. Report each ticket URL, its recommendation (PROMOTE/DEMOTE +
+  rung), and the batch ticket URL with its row count.
+- `nothing-needed` → **`nothing-needed`** (unchanged) — no candidate met any
+  recommendation threshold. Report one line: surfaces scanned, entries seen,
+  "nothing to propose".
+- `blocked` → **`recovery-required`** when the loop itself could not complete
+  (tracker unreachable, contradictory config, a ledger-contract parse error) —
+  escalated per Escalation with the operator-readable reason; **or**
+  **`approval-requested`** when the run finished and is waiting on a human gate
+  rather than being broken.
+
+The gardener also newly reaches **`policy-obsolete`** — the Retirement
+condition below tripped and it filed its own teardown proposal. It never
+produces **`change-proved`**: the gardener only files tickets and ships no
+change itself, so proving a change is the implementing factory run's job.
+
+Record exactly one outcome per run through the run-record CLI, naming this
+loop's runbook (the `--summary` is the operator-readable one-liner in the
+contract's exemplar voice — plain, specific, actionable):
 
-Exactly one per run: **`nothing-needed | candidates-proposed | blocked`**
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id learnings-audit --outcome candidate-proposed \
+  --summary "Proposed 2 promotions and 1 batch confirm; awaiting your flip to ready." \
+  --runbook .lisa/automations/learnings-audit.runbook.md [--ref <ticket-url>]...
+```
 
-- `nothing-needed` — no candidate met any recommendation threshold. Healthy.
-  Report one line: surfaces scanned, entries seen, "nothing to propose".
-- `candidates-proposed` — tickets filed. Report each ticket URL, its
-  recommendation (PROMOTE/DEMOTE + rung), and the batch ticket URL with its
-  row count.
-- `blocked` — could not complete; escalated per Escalation with the
-  operator-readable reason.
+If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory
+directly — the built copy `plugins/lisa/scripts/automation-run-record.mjs` or
+the source `plugins/src/base/scripts/automation-run-record.mjs`. If recording
+still fails, **degrade, never abort** (per `automation-runbook-contract`): note
+the recording failure in the run output and finish the run — a recording
+failure is a degradation to report, never a reason to block the loop.
 
 ## Retirement condition
 

package/plugins/lisa/skills/lisa-monitor/SKILL.md

@@ -139,3 +139,39 @@ After report, file what was found — **only when run standalone**, never under
 ## Output
 
 A single report: the health/anomaly summary (failures, warnings, no-issue confirmations) + the observability audit table (each in-scope dimension as `OK` / `WARN` / `MISSING` / `PRESENT (unverified)`) + the filing summary (tickets filed with refs + fingerprints, duplicates skipped, dropped count if the cap truncated; or would-file tickets under `--dry-run`). For post-deploy verification (when called from `lisa-verify`), the report-only summary becomes evidence on the originating work item.
+
+## Run outcome
+
+As the registered `monitor` automation loop, the **standalone** cron run conforms to the
+`automation-runbook-contract` rule: it ends in **exactly one** of the six run outcomes and records it,
+so a quiet monitoring run and a broken one never look identical.
+
+| This cycle's exit path | Run outcome |
+|---|---|
+| Anomalies or in-scope gaps filed — one or more `Bug` / `Task` / `Improvement` leaves created or referenced | `candidate-proposed` |
+| Clean sweep — health/audit ran end to end, nothing over the bar and no in-scope gaps | `nothing-needed` |
+| Provider/threshold resolution failure — threshold collection fails (a present-but-uninspectable config, an invalid configured threshold) or a signal provider is unreachable so the sweep could not run | `recovery-required` |
+| A degradation that still let the sweep run (an optional `ops-specialist` overlay absent, Kane unavailable) | the outcome it actually reached above, with the summary **leading with the degradation** — degradation never mints a seventh token |
+
+Only the **standalone** run records. The nested report-only modes do their own job and do not file or
+record: `--report-only` (including the `lisa-verify` post-deploy call, whose summary is evidence on
+the originating item) and `--dry-run` (a preview that creates nothing) are not registered-loop
+invocations.
+
+Record **exactly one** outcome per standalone invocation through the run-record CLI, naming this
+loop's runbook (the `--summary` is the operator-readable one-liner in the contract's exemplar voice —
+plain, specific, actionable, e.g. `Health green; audit clean — nothing to propose.` for
+`nothing-needed`):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id monitor --outcome candidate-proposed \
+  --summary "Filed #1810 for the p99 latency spike; awaiting your flip to ready." \
+  --runbook .lisa/automations/monitor.runbook.md [--ref <ticket-url>]...
+```
+
+If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
+`plugins/lisa/scripts/automation-run-record.mjs` or the source
+`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
+abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
+the cycle — a recording failure is a degradation to report, never a reason to block the loop.

package/plugins/lisa/skills/lisa-project-ideation/SKILL.md

@@ -275,6 +275,42 @@ Emit two distinct in-session sections (do not write a report file):
 Always include the **Personas**, **What Already Exists**, **Discovery Spikes**, and **Rejected**
 sections (even if empty) so the user sees what was considered and filtered out.
 
+## Run outcome
+
+As the registered `exploratory-prds` automation loop, this run conforms to the
+`automation-runbook-contract` rule: it ends in **exactly one** of the six run outcomes and records it,
+so a quiet ideation run and a broken one are never confused.
+
+| This run's exit path | Run outcome |
+|---|---|
+| PRD(s) created or reused this run (Step 6/7 **PRDs Created**) | `candidate-proposed` |
+| Nothing to ideate — no Practical Idea cleared the bar; nothing created | `nothing-needed` |
+| The Step 5.5 **PRD-queue-pressure gate** blocked auto-ready creation — a human must drain the queue before another auto-ready PRD is added | `approval-requested` |
+| The loop itself could not run — the PRD source reader failed or the queue is misconfigured (a source-reader failure snapshot, not queue pressure) | `recovery-required` |
+| A degradation that still let ideation run (optional Codex automation memory unavailable, an inspiration source unreachable) | the outcome it actually reached above, with the summary **leading with the degradation** — degradation never mints a seventh token |
+
+The pressure gate is `approval-requested`, **not** `recovery-required`: the loop ran fine and
+correctly declined to add queue pressure — it is asking a human to drain the queue, not reporting a
+broken machine. `recovery-required` is reserved for the loop failing to run at all.
+
+Record **exactly one** outcome per invocation through the run-record CLI, naming this loop's runbook
+(the `--summary` is the operator-readable one-liner in the contract's exemplar voice — plain,
+specific, actionable, e.g. `Reviewed evidence; no practical idea cleared the bar — nothing to
+propose.` for `nothing-needed`):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id exploratory-prds --outcome candidate-proposed \
+  --summary "Created PRD #1810 for offline export; awaiting your flip to ready." \
+  --runbook .lisa/automations/exploratory-prds.runbook.md [--ref <prd-url>]...
+```
+
+If `${CLAUDE_PLUGIN_ROOT}` is unset, resolve the plugin scripts directory directly — the built copy
+`plugins/lisa/scripts/automation-run-record.mjs` or the source
+`plugins/src/base/scripts/automation-run-record.mjs`. If recording still fails, **degrade, never
+abort** (per `automation-runbook-contract`): note the recording failure in the run output and finish
+the run — a recording failure is a degradation to report, never a reason to block the loop.
+
 ## Out of scope (hard rules)
 
 - **No fabricated personas.** No evidence citation → no persona; generic roles banned without