@codyswann/lisa 2.253.0 → 2.254.0

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.253.0",
+  "version": "2.254.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

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

package/plugins/lisa/.codex-plugin/plugin.json

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

package/plugins/lisa/rules/eager/automation-runbook-contract.md

@@ -50,7 +50,10 @@ loop itself is broken, not that a work item was blocked.
 
 Every run — including a trivial early termination — ends by naming exactly one run outcome plus a
 one-line operator summary of what happened, recorded where the status surface can read it —
-there is no silent exit. Silence and health must never look identical to an operator.
+there is no silent exit. The shared local substrate is
+`plugins/src/base/scripts/automation-run-record.mjs`, which writes bounded JSONL records under
+`.lisa/automations/runs/<loop-id>.jsonl`. Silence and health must never look identical to an
+operator.
 
 ## Never block, always degrade
 

package/plugins/lisa/rules/reference/automation-runbook-contract.md

@@ -121,8 +121,17 @@ there is no silent exit for an operator to misread as health. A run that ends wi
 recorded outcome is indistinguishable from a crashed scheduler, which is exactly the ambiguity this
 contract removes. This generalizes `lisa-improve-harness`'s result-record discipline — every
 terminal step posts its result record before stopping, so there is no silent exit — from one flow to
-every registered loop. (The run-record substrate that stores outcomes and summaries is named here
-only; it ships with that ticket (#1797), do not assume its file is present in this branch.)
+every registered loop.
+
+The local storage substrate is `plugins/src/base/scripts/automation-run-record.mjs`. It writes one
+bounded JSONL file per loop at `.lisa/automations/runs/<loop-id>.jsonl`, with one object per line:
+`{ ts, loop_id, outcome, summary, runbook, refs[], run_id }`. The helper rejects any outcome outside
+the closed six-value vocabulary, requires a non-empty operator-readable summary, suppresses duplicate
+re-appends for the same `run_id`, skips corrupt/truncated lines on read, and trims to the newest
+configured records on write. The default bound is 50 records per loop, overridable via
+`.lisa.config.json` / `.lisa.config.local.json` `automations.runHistory.maxEntries`. These records
+are local scheduler observations, not project knowledge, so `.lisa/automations/runs/` is ignored;
+the runbooks under `.lisa/automations/*.runbook.md` remain checked-in knowledge.
 
 ## A run outcome is not a work-item lifecycle terminal state
 
@@ -209,8 +218,8 @@ packet above. A degraded run never blocks other work and never leaves the run un
 
 ## Citing adjacent work
 
-Cite these by name; each ships with its own ticket, do not assume its file is present in this
-branch: the runbook scaffolding that instantiates this template (#1796), the run-record substrate
-that stores outcomes and summaries (#1797), and the evidence packet defined by the evidence PRD
-(#1738) — named here, with no evidence format defined by this contract. Rejection memory
-extends `rejection-detection`; this contract neither restates nor overrides it.
+Cite these by name. The run-record substrate ships with that ticket (#1797), do not assume its file
+is present in older branches. The evidence packet ships with that ticket, do not assume its file is present in this branch. Other adjacent artifacts keep their own lifecycle: the runbook scaffolding
+that instantiates this template (#1796), and the evidence packet defined by the evidence PRD (#1738)
+— named here, with no evidence format defined by this contract. Rejection memory extends
+`rejection-detection`; this contract neither restates nor overrides it.

package/plugins/lisa/scripts/automation-run-record.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * Dependency-free run outcome recorder for registered Lisa automation loops.
+ *
+ * The file is local scheduler state, not project knowledge: one bounded JSONL
+ * file per loop under `.lisa/automations/runs/`.
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export const AUTOMATION_RUN_OUTCOMES = [
+  "nothing-needed",
+  "candidate-proposed",
+  "change-proved",
+  "approval-requested",
+  "recovery-required",
+  "policy-obsolete",
+];
+
+export const DEFAULT_AUTOMATION_RUN_HISTORY_MAX_ENTRIES = 50;
+
+/**
+ * @typedef {{
+ *   readonly ts: string
+ *   readonly loop_id: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ *   readonly runbook: string
+ *   readonly refs: readonly string[]
+ *   readonly run_id: string
+ * }} AutomationRunRecord
+ *
+ * @typedef {{
+ *   readonly projectRoot?: string
+ *   readonly loopId: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ *   readonly runbook: string
+ *   readonly refs?: readonly string[]
+ *   readonly runId?: string
+ *   readonly ts?: string | Date
+ *   readonly maxEntries?: number
+ * }} RecordAutomationRunInput
+ */
+
+/**
+ * Record one automation-loop outcome, suppressing duplicate re-appends for the
+ * same `run_id` and trimming the file to the configured history bound.
+ *
+ * @param {RecordAutomationRunInput} input
+ * @returns {Promise<{ readonly path: string, readonly record: AutomationRunRecord, readonly records: readonly AutomationRunRecord[], readonly appended: boolean, readonly skippedCorruptLines: number, readonly maxEntries: number }>}
+ */
+export async function recordAutomationRun(input) {
+  const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+  const maxEntries =
+    input.maxEntries ??
+    (await resolveAutomationRunHistoryMaxEntries(projectRoot));
+  const record = buildAutomationRunRecord(input);
+  const filePath = automationRunRecordPath(projectRoot, record.loop_id);
+  const readResult = await readAutomationRunRecords(filePath);
+
+  if (readResult.records.some(existing => existing.run_id === record.run_id)) {
+    return {
+      path: filePath,
+      record,
+      records: readResult.records,
+      appended: false,
+      skippedCorruptLines: readResult.skippedCorruptLines,
+      maxEntries,
+    };
+  }
+
+  const nextRecords = [...readResult.records, record].slice(-maxEntries);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeJsonlAtomically(filePath, nextRecords);
+
+  return {
+    path: filePath,
+    record,
+    records: nextRecords,
+    appended: true,
+    skippedCorruptLines: readResult.skippedCorruptLines,
+    maxEntries,
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<number>}
+ */
+export async function resolveAutomationRunHistoryMaxEntries(projectRoot) {
+  const globalConfig = await readJsonIfPresent(
+    path.join(projectRoot, ".lisa.config.json")
+  );
+  const localConfig = await readJsonIfPresent(
+    path.join(projectRoot, ".lisa.config.local.json")
+  );
+  const configured =
+    localConfig?.automations?.runHistory?.maxEntries ??
+    globalConfig?.automations?.runHistory?.maxEntries;
+
+  if (Number.isInteger(configured) && configured > 0) {
+    return configured;
+  }
+
+  return DEFAULT_AUTOMATION_RUN_HISTORY_MAX_ENTRIES;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} loopId
+ * @returns {string}
+ */
+export function automationRunRecordPath(projectRoot, loopId) {
+  return path.join(
+    path.resolve(projectRoot),
+    ".lisa",
+    "automations",
+    "runs",
+    `${normalizeLoopId(loopId)}.jsonl`
+  );
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<{ readonly records: readonly AutomationRunRecord[], readonly skippedCorruptLines: number }>}
+ */
+export async function readAutomationRunRecords(filePath) {
+  let content = "";
+  try {
+    content = await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { records: [], skippedCorruptLines: 0 };
+    }
+    throw error;
+  }
+
+  const records = [];
+  let skippedCorruptLines = 0;
+  for (const line of content.split(/\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(line);
+      records.push(validateStoredRecord(parsed));
+    } catch {
+      skippedCorruptLines += 1;
+    }
+  }
+
+  return { records, skippedCorruptLines };
+}
+
+/**
+ * @param {RecordAutomationRunInput} input
+ * @returns {AutomationRunRecord}
+ */
+function buildAutomationRunRecord(input) {
+  const loopId = normalizeLoopId(input.loopId);
+  const summary = String(input.summary ?? "").trim();
+  const runbook = String(input.runbook ?? "").trim();
+  const refs = Array.isArray(input.refs)
+    ? input.refs.map(ref => String(ref))
+    : [];
+  const ts =
+    input.ts instanceof Date
+      ? input.ts.toISOString()
+      : input.ts
+        ? new Date(input.ts).toISOString()
+        : new Date().toISOString();
+  const runId = String(input.runId ?? `${loopId}:${ts}`).trim();
+
+  if (!AUTOMATION_RUN_OUTCOMES.includes(input.outcome)) {
+    throw new Error(
+      `Invalid automation run outcome "${input.outcome}". Valid outcomes: ${AUTOMATION_RUN_OUTCOMES.join(", ")}.`
+    );
+  }
+  if (!summary) {
+    throw new Error("Automation run summary is required.");
+  }
+  if (!runbook) {
+    throw new Error("Automation runbook path is required.");
+  }
+  if (!runId) {
+    throw new Error("Automation run_id is required.");
+  }
+
+  return {
+    ts,
+    loop_id: loopId,
+    outcome: input.outcome,
+    summary,
+    runbook,
+    refs,
+    run_id: runId,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {AutomationRunRecord}
+ */
+function validateStoredRecord(value) {
+  if (!value || typeof value !== "object") {
+    throw new Error("Automation run record must be an object.");
+  }
+  return buildAutomationRunRecord({
+    ts: String(value.ts ?? ""),
+    loopId: String(value.loop_id ?? ""),
+    outcome: String(value.outcome ?? ""),
+    summary: String(value.summary ?? ""),
+    runbook: String(value.runbook ?? ""),
+    refs: Array.isArray(value.refs) ? value.refs.map(ref => String(ref)) : [],
+    runId: String(value.run_id ?? ""),
+  });
+}
+
+/**
+ * @param {string} loopId
+ * @returns {string}
+ */
+function normalizeLoopId(loopId) {
+  const normalized = String(loopId ?? "").trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(normalized)) {
+    throw new Error(
+      "Automation loop_id must be a non-empty slug containing only letters, numbers, dots, underscores, and hyphens."
+    );
+  }
+  return normalized;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<unknown | undefined>}
+ */
+async function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return undefined;
+    }
+    if (error instanceof SyntaxError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {readonly AutomationRunRecord[]} records
+ */
+async function writeJsonlAtomically(filePath, records) {
+  const content = `${records.map(record => JSON.stringify(record)).join("\n")}\n`;
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, content, "utf8");
+  await rename(tempPath, filePath);
+}

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/scripts/automation-run-record.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * Dependency-free run outcome recorder for registered Lisa automation loops.
+ *
+ * The file is local scheduler state, not project knowledge: one bounded JSONL
+ * file per loop under `.lisa/automations/runs/`.
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export const AUTOMATION_RUN_OUTCOMES = [
+  "nothing-needed",
+  "candidate-proposed",
+  "change-proved",
+  "approval-requested",
+  "recovery-required",
+  "policy-obsolete",
+];
+
+export const DEFAULT_AUTOMATION_RUN_HISTORY_MAX_ENTRIES = 50;
+
+/**
+ * @typedef {{
+ *   readonly ts: string
+ *   readonly loop_id: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ *   readonly runbook: string
+ *   readonly refs: readonly string[]
+ *   readonly run_id: string
+ * }} AutomationRunRecord
+ *
+ * @typedef {{
+ *   readonly projectRoot?: string
+ *   readonly loopId: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ *   readonly runbook: string
+ *   readonly refs?: readonly string[]
+ *   readonly runId?: string
+ *   readonly ts?: string | Date
+ *   readonly maxEntries?: number
+ * }} RecordAutomationRunInput
+ */
+
+/**
+ * Record one automation-loop outcome, suppressing duplicate re-appends for the
+ * same `run_id` and trimming the file to the configured history bound.
+ *
+ * @param {RecordAutomationRunInput} input
+ * @returns {Promise<{ readonly path: string, readonly record: AutomationRunRecord, readonly records: readonly AutomationRunRecord[], readonly appended: boolean, readonly skippedCorruptLines: number, readonly maxEntries: number }>}
+ */
+export async function recordAutomationRun(input) {
+  const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+  const maxEntries =
+    input.maxEntries ??
+    (await resolveAutomationRunHistoryMaxEntries(projectRoot));
+  const record = buildAutomationRunRecord(input);
+  const filePath = automationRunRecordPath(projectRoot, record.loop_id);
+  const readResult = await readAutomationRunRecords(filePath);
+
+  if (readResult.records.some(existing => existing.run_id === record.run_id)) {
+    return {
+      path: filePath,
+      record,
+      records: readResult.records,
+      appended: false,
+      skippedCorruptLines: readResult.skippedCorruptLines,
+      maxEntries,
+    };
+  }
+
+  const nextRecords = [...readResult.records, record].slice(-maxEntries);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeJsonlAtomically(filePath, nextRecords);
+
+  return {
+    path: filePath,
+    record,
+    records: nextRecords,
+    appended: true,
+    skippedCorruptLines: readResult.skippedCorruptLines,
+    maxEntries,
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<number>}
+ */
+export async function resolveAutomationRunHistoryMaxEntries(projectRoot) {
+  const globalConfig = await readJsonIfPresent(
+    path.join(projectRoot, ".lisa.config.json")
+  );
+  const localConfig = await readJsonIfPresent(
+    path.join(projectRoot, ".lisa.config.local.json")
+  );
+  const configured =
+    localConfig?.automations?.runHistory?.maxEntries ??
+    globalConfig?.automations?.runHistory?.maxEntries;
+
+  if (Number.isInteger(configured) && configured > 0) {
+    return configured;
+  }
+
+  return DEFAULT_AUTOMATION_RUN_HISTORY_MAX_ENTRIES;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} loopId
+ * @returns {string}
+ */
+export function automationRunRecordPath(projectRoot, loopId) {
+  return path.join(
+    path.resolve(projectRoot),
+    ".lisa",
+    "automations",
+    "runs",
+    `${normalizeLoopId(loopId)}.jsonl`
+  );
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<{ readonly records: readonly AutomationRunRecord[], readonly skippedCorruptLines: number }>}
+ */
+export async function readAutomationRunRecords(filePath) {
+  let content = "";
+  try {
+    content = await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { records: [], skippedCorruptLines: 0 };
+    }
+    throw error;
+  }
+
+  const records = [];
+  let skippedCorruptLines = 0;
+  for (const line of content.split(/\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(line);
+      records.push(validateStoredRecord(parsed));
+    } catch {
+      skippedCorruptLines += 1;
+    }
+  }
+
+  return { records, skippedCorruptLines };
+}
+
+/**
+ * @param {RecordAutomationRunInput} input
+ * @returns {AutomationRunRecord}
+ */
+function buildAutomationRunRecord(input) {
+  const loopId = normalizeLoopId(input.loopId);
+  const summary = String(input.summary ?? "").trim();
+  const runbook = String(input.runbook ?? "").trim();
+  const refs = Array.isArray(input.refs)
+    ? input.refs.map(ref => String(ref))
+    : [];
+  const ts =
+    input.ts instanceof Date
+      ? input.ts.toISOString()
+      : input.ts
+        ? new Date(input.ts).toISOString()
+        : new Date().toISOString();
+  const runId = String(input.runId ?? `${loopId}:${ts}`).trim();
+
+  if (!AUTOMATION_RUN_OUTCOMES.includes(input.outcome)) {
+    throw new Error(
+      `Invalid automation run outcome "${input.outcome}". Valid outcomes: ${AUTOMATION_RUN_OUTCOMES.join(", ")}.`
+    );
+  }
+  if (!summary) {
+    throw new Error("Automation run summary is required.");
+  }
+  if (!runbook) {
+    throw new Error("Automation runbook path is required.");
+  }
+  if (!runId) {
+    throw new Error("Automation run_id is required.");
+  }
+
+  return {
+    ts,
+    loop_id: loopId,
+    outcome: input.outcome,
+    summary,
+    runbook,
+    refs,
+    run_id: runId,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {AutomationRunRecord}
+ */
+function validateStoredRecord(value) {
+  if (!value || typeof value !== "object") {
+    throw new Error("Automation run record must be an object.");
+  }
+  return buildAutomationRunRecord({
+    ts: String(value.ts ?? ""),
+    loopId: String(value.loop_id ?? ""),
+    outcome: String(value.outcome ?? ""),
+    summary: String(value.summary ?? ""),
+    runbook: String(value.runbook ?? ""),
+    refs: Array.isArray(value.refs) ? value.refs.map(ref => String(ref)) : [],
+    runId: String(value.run_id ?? ""),
+  });
+}
+
+/**
+ * @param {string} loopId
+ * @returns {string}
+ */
+function normalizeLoopId(loopId) {
+  const normalized = String(loopId ?? "").trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(normalized)) {
+    throw new Error(
+      "Automation loop_id must be a non-empty slug containing only letters, numbers, dots, underscores, and hyphens."
+    );
+  }
+  return normalized;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<unknown | undefined>}
+ */
+async function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return undefined;
+    }
+    if (error instanceof SyntaxError) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {readonly AutomationRunRecord[]} records
+ */
+async function writeJsonlAtomically(filePath, records) {
+  const content = `${records.map(record => JSON.stringify(record)).join("\n")}\n`;
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, content, "utf8");
+  await rename(tempPath, filePath);
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.253.0",
+  "version": "2.254.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.253.0",
+  "version": "2.254.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.253.0",
+  "version": "2.254.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.253.0",
+  "version": "2.254.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.253.0",
+  "version": "2.254.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/lisa-copilot/rules/eager/automation-runbook-contract.md

@@ -50,7 +50,10 @@ loop itself is broken, not that a work item was blocked.
 
 Every run — including a trivial early termination — ends by naming exactly one run outcome plus a
 one-line operator summary of what happened, recorded where the status surface can read it —
-there is no silent exit. Silence and health must never look identical to an operator.
+there is no silent exit. The shared local substrate is
+`plugins/src/base/scripts/automation-run-record.mjs`, which writes bounded JSONL records under
+`.lisa/automations/runs/<loop-id>.jsonl`. Silence and health must never look identical to an
+operator.
 
 ## Never block, always degrade