@codyswann/lisa 2.254.0 → 2.255.0

package/plugins/src/base/scripts/automation-run-record.mjs

@@ -260,3 +260,113 @@ async function writeJsonlAtomically(filePath, records) {
   await writeFile(tempPath, content, "utf8");
   await rename(tempPath, filePath);
 }
+
+const CLI_USAGE = `Usage: node automation-run-record.mjs \\
+  --loop-id <slug> --outcome <${AUTOMATION_RUN_OUTCOMES.join("|")}> \\
+  --summary "<operator-readable one-liner>" --runbook <path> \\
+  [--ref <url>]... [--run-id <id>] [--project-root <dir>]`;
+
+/**
+ * Translate a repeatable-flag argv into a {@link RecordAutomationRunInput}.
+ *
+ * Every flag takes a following value; `--ref` may repeat and accumulates into
+ * `refs`. Unknown flags and value-less flags throw so a typo never silently
+ * records the wrong thing.
+ *
+ * @param {readonly string[]} argv
+ * @returns {RecordAutomationRunInput}
+ */
+function parseAutomationRunRecordArgv(argv) {
+  /** @type {Record<string, string>} */
+  const single = {};
+  /** @type {string[]} */
+  const refs = [];
+  const flags = {
+    "--loop-id": "loopId",
+    "--outcome": "outcome",
+    "--summary": "summary",
+    "--runbook": "runbook",
+    "--run-id": "runId",
+    "--project-root": "projectRoot",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const eq = token.indexOf("=");
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
+    const takeValue = () => {
+      if (inlineValue !== undefined) {
+        return inlineValue;
+      }
+      index += 1;
+      if (index >= argv.length) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      return argv[index];
+    };
+
+    if (flag === "--ref") {
+      refs.push(takeValue());
+      continue;
+    }
+    const key = flags[flag];
+    if (!key) {
+      throw new Error(`Unknown flag "${flag}".`);
+    }
+    single[key] = takeValue();
+  }
+
+  return { ...single, refs };
+}
+
+/**
+ * Argv-driven CLI wrapper so registered loop skills can record an outcome with
+ * one portable `node …/automation-run-record.mjs --outcome …` call. Delegates
+ * validation to {@link recordAutomationRun}; surfaces its errors verbatim.
+ *
+ * @param {readonly string[]} argv
+ * @returns {Promise<number>} process exit code
+ */
+export async function runAutomationRunRecordCli(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${CLI_USAGE}\n`);
+    return 0;
+  }
+  let input;
+  try {
+    input = parseAutomationRunRecordArgv(argv);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${CLI_USAGE}\n`);
+    return 2;
+  }
+  try {
+    const result = await recordAutomationRun(input);
+    process.stdout.write(
+      `${JSON.stringify({
+        path: result.path,
+        appended: result.appended,
+        outcome: result.record.outcome,
+        loop_id: result.record.loop_id,
+        run_id: result.record.run_id,
+      })}\n`
+    );
+    return 0;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}
+
+// CLI entrypoint.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runAutomationRunRecordCli(process.argv.slice(2)).then(
+    code => {
+      process.exitCode = code;
+    },
+    error => {
+      process.stderr.write(`${error?.message ?? error}\n`);
+      process.exitCode = 1;
+    }
+  );
+}

package/plugins/src/base/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/src/base/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/src/base/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/src/base/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/src/base/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

package/plugins/src/base/skills/lisa-repair-intake/SKILL.md

@@ -975,6 +975,40 @@ Report outcomes in these buckets:
 State every item repaired this cycle and the action taken. If the output would be long, group by
 bucket and show compact refs plus counts.
 
+## Run outcome
+
+As the registered `intake-repair` automation loop, each cycle conforms to the
+`automation-runbook-contract` rule: it ends in **exactly one** of the six run outcomes and records it,
+so a cycle that found nothing stuck and a cycle where the repair machinery itself broke never look
+alike. A run outcome describes this *cycle*; the Summary-report buckets above describe *what happened
+to each item* — the two never merge in the one-line summary.
+
+| This cycle's exit path | Run outcome |
+|---|---|
+| Nothing actionable — the idle case (walk step 5): examined N, all active or in backoff | `nothing-needed` |
+| Repairs applied **and confirmed** this cycle — `resumed` / `resynced` / `recovered` / `unblocked` / `closed_out` / `rolled_up` / `relinked` / `normalized_ready` | `change-proved` |
+| Repair produced new work for a human to pick up — e.g. an unmergeable PR or failed deploy filed as a **build-ready fix ticket** and left `blocked` | `candidate-proposed` |
+| A repair reached an autonomy boundary needing a human (a protected-deploy approval before it can proceed) | `approval-requested` |
+| The loop itself could not run — the queue is unreadable or tracker credentials are revoked | `recovery-required` |
+
+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. `Examined 14 items; all active or in backoff — nothing to repair.` for
+`nothing-needed`):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/automation-run-record.mjs" \
+  --loop-id intake-repair --outcome change-proved \
+  --summary "Recovered 3 stalled builds and closed out 2 rollups; all confirmed." \
+  --runbook .lisa/automations/intake-repair.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