@codyswann/lisa 2.252.0 → 2.254.0

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.252.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.252.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.252.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/skills/lisa-automation-status/SKILL.md

@@ -16,14 +16,20 @@ Do **not** ask for confirmation once invoked. This skill inspects scheduler stat
 
 ## Scope
 
-Inspect only the Lisa automation fleet for the current project:
-
-- `intake-repair`
-- `intake-prd`
-- `intake-tickets`
-- `exploratory-bugs` when the current stack supports `exploratory-qa`
-- `exploratory-prds`
-- `monitor`
+Inspect only the Lisa automation fleet for the current project. Derive that fleet from
+`scripts/automation-status-expected-fleet.mjs` (`resolveExpectedAutomationFleet`), which resolves
+exactly what `setup-automations` registers for this repo — including the stack-guarded
+`exploratory-bugs` and the opt-in `learnings-audit` gardener. **Membership is registration, not a
+roster** (`automation-runbook-contract`): carry no fixed list of loop names here, so a loop added to
+or removed from the registration set flows through without editing this skill.
+
+The gardener is opted into at registration time and has no config key, so **infer it from the
+scheduler**: list the project's automations first, then call
+`inferLearningsAuditRegistration({ automationPrefix, observedAutomationIds })` and pass the result
+as `learningsAudit` when resolving the fleet. A `lisa-auto-<project>-learnings-audit` entry on the
+scheduler means the project opted in, so the gardener is compared like any other loop; no such entry
+means it is reported `UNSUPPORTED` (opted out), never `MISSING`. This skill stays read-only — it
+infers, it never writes the flag anywhere.
 
 Resolve the expected project identifier, fleet naming prefix, queue arguments, cadence, and stack-support rules from the same contract used by `setup-automations` and `tear-down-automations`. Do **not** invent a second source of truth for fleet naming or queue resolution.
 

package/plugins/lisa/.codex-plugin/skills/lisa-setup-automations/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lisa-setup-automations
 description: "Set up the recurring Lisa…"
-allowed-tools: ["Skill", "Bash", "Read"]
+allowed-tools: ["Skill", "Bash", "Read", "Write", "Edit"]
 ---
 
 # Set up Lisa automations: $ARGUMENTS
@@ -105,6 +105,19 @@ the scheduled commands (for example `/lisa:intake acme/frontend intake_mode=prd`
 config/read-context failure cannot silently redirect the cron. A short queueRepo is normalized to
 `github.org` before writing the automation.
 
+**Registration prompt shape (so status can read the command back).** Whatever prose the prompt
+carries, it must contain the **literal Lisa command on a line of its own**, exactly as scheduled and
+with every `owner/repo` already baked in:
+
+```text
+/lisa:intake acme/planning intake_mode=build
+```
+
+This holds for loops that take **no arguments** too — `/lisa:monitor` and `/lisa:learnings:audit`
+are written the same way, on their own line, with nothing after them. `/lisa:automation-status`
+reads that line back to compare the live registration against this contract; a loop whose command
+cannot be read back reports as drifted even though it is registered correctly.
+
 **Naming + scope (so teardown is precise).** Name each automation with the stable prefix
 `lisa-auto-<project>-` (e.g. `lisa-auto-<project>-intake-tickets`), where `<project>` identifies this
 repo, and scope each Codex automation to the durable project automation checkout described above.
@@ -115,6 +128,91 @@ repos (don't rely on a bare repo basename when it could collide; qualify it, e.g
 **Idempotent.** Re-running this skill updates the existing `lisa-auto-<project>-*` automations in
 place (same names) rather than creating duplicates.
 
+## Runbook scaffolding
+
+Registration is what pulls a loop under the `automation-runbook-contract` rule, so registration is
+what must produce its runbook. For **every automation actually registered above** — including the
+conditionally-guarded `exploratory-bugs` and the opt-in `learnings-audit` — write a checked-in
+runbook at:
+
+```text
+.lisa/automations/<loop-id>.runbook.md
+```
+
+`<loop-id>` is the automation's suffix, not its full name: `intake-tickets`, not
+`lisa-auto-<project>-intake-tickets`. These files are **project knowledge and belong in git**, like
+`.lisa/PROJECT_LEARNINGS.md` — commit them; they are not scratch output. Derive the set of runbooks
+from what was registered on this run: a loop that was **skipped gets no runbook**, and a loop
+registered later gets one when this skill next runs. Never write a runbook from a fixed list of
+loop names.
+
+Follow the `automation-runbook-contract` rule for the runbook's shape: its ten sections, in its
+order, in its prose register. **Do not restate the template, the run outcomes, or the escalation
+packet here** — cite the rule and instantiate it.
+
+**File shape — two halves with different owners.**
+
+1. A **machine-resolved header block**, delimited exactly by
+   `<!-- lisa:machine-resolved:start -->` and `<!-- lisa:machine-resolved:end -->`, written first
+   in the file. Lisa owns it: on every run it is **rewritten wholesale** from the values resolved
+   above. It carries the project identity (`<owner>/<repo>` and the `<project>` token), the loop
+   id, the full automation name, the exact scheduled command with every `owner/repo` already baked
+   in (never a placeholder), the human cadence and its `rrule`, the resolved queue arguments, and
+   the resolved flag values that shaped the command (`auto-start-prds` / `auto-start-tickets` /
+   `learnings-audit`). Its **first line inside the delimiters is a visible sentence**, so the
+   ownership boundary survives rendering to markdown where HTML comments disappear:
+
+   ```text
+   Lisa rewrites this section on every /lisa:setup-automations run — edits here are lost. Your prose
+   belongs in the sections below.
+   ```
+
+   Immediately **below** the closing delimiter, write one more visible line — `Everything below is
+   yours.` — so an operator reading the rendered page knows where their half starts.
+2. The **ten contract sections** below it. Lisa owns them **only on first write**, then they belong
+   to the operator. Seed them deterministically, never improvised:
+   - **Intent, Sources of truth, Candidate selection, Scope/bounds, Retirement condition** come
+     from the per-loop seed table below.
+   - **Proof, Autonomous-vs-approval boundary, Escalation, Recovery, Next-run state** are derived
+     from **that loop's own SKILL.md** — named per loop in the table's last column — so the runbook
+     describes what the loop actually does rather than a generic paraphrase. Quote its behavior in
+     the operator's voice; if the skill file is unreadable, write one sentence saying the section
+     was not derivable and which file to read, and continue.
+
+   Every seeded sentence is written for a non-technical operator (`factory-model` rule 5).
+
+### Per-loop seed defaults
+
+One line each; expand them into the operator's voice, keep the meaning.
+
+| Loop | Intent | Sources of truth | Candidate selection | Scope/bounds | Retirement condition | Derive the other five from |
+|---|---|---|---|---|---|---|
+| **intake-repair** | Keeps the queues unstuck: work that stalled mid-flight gets diagnosed and moved again. | The PRD and build queues for this project, read through the tracker access layer. | Stuck or half-closed items — stalled in an in-progress role, terminal-labeled but still open, rollups whose children are all done — up to the `max_candidates` cap. | Only this project's configured queues; it repairs lifecycle state, never invents or closes real work. | Propose teardown when nothing has needed repair for a long quiet window AND this run found nothing. | `lisa-repair-intake/SKILL.md` |
+| **intake-prd** | Keeps PRDs moving: a PRD a human marked ready gets validated and decomposed into work items. | The configured PRD queue and its lifecycle roles, read through the source access layer. | The oldest PRD in the ready role, one per run. | Only this project's PRD queue; it never authors product intent, only validates and decomposes it. | Propose teardown when no PRD has entered the queue for a long quiet window AND this run proposed nothing. | `lisa-intake/SKILL.md` |
+| **intake-tickets** | Keeps the build queue moving: work items a human marked ready get built, reviewed, and shipped. | The configured tracker's build queue lanes plus each item's comments and linked PRs. | The oldest eligible leaf work item in the ready lane, one per run. | Only this repo's configured queue; containers with open children are repaired out, never built. | Propose teardown when no work item has entered this queue for a long quiet window AND this run proposed nothing. | `lisa-intake/SKILL.md` |
+| **monitor** | Keeps production honest: observability regressions become tracked work instead of silent decay. | The connected observability providers, each through its access layer, plus this project's `monitor.gapTiers` config. | The regressions and coverage gaps this cycle surfaced, capped per run. | Only this project's own services and dashboards; it files findings, it never changes production. | Propose teardown when the project has no connected observability surfaces AND this run found nothing. | `lisa-monitor/SKILL.md` |
+| **exploratory-prds** | Keeps the idea pipeline fed: the product's own gaps become PRDs when the PRD queue has room. | The PRD queue's pressure roles (the same ones `/lisa:queue-status` reports) and the project's own product surfaces. | One ideated PRD per run, and only when the pressure gate says the queue has capacity. | Never more than one PRD per run, and nothing at all while unresolved PRD pressure exists. | Propose teardown when the queue has been at pressure — or the project has shipped no new surface — across a long quiet window AND this run proposed nothing. | `lisa-project-ideation/SKILL.md` |
+| **exploratory-bugs** | Keeps quality visible: bugs and usability problems get found by using the product, before a customer does. | The running application through its exploratory-qa surface, plus this project's existing bug queue for dedupe. | The findings of one exploratory session, capped per run and deduped against already-filed items. | Only this project's own app; it files tickets, it never changes product code. | Propose teardown when no session has produced a finding across a long quiet window AND this run found nothing. | `lisa-exploratory-qa/SKILL.md` (the stack's own copy) |
+| **learnings-audit** | Keeps the project's knowledge true: stale, duplicated, or contradicted knowledge gets proposed for promotion, demotion, or retirement. | The learnings ledger, the rules trees, the skills, and the wiki — the project's knowledge surfaces. | The knowledge entries this audit judged stale, duplicated, or contradicted, capped per run. | It only proposes; every promote/demote/retire decision is a human-gated tracker ticket. | Propose teardown when the audit has proposed nothing across a long quiet window AND this run proposed nothing. | `lisa-learnings-audit/SKILL.md` |
+
+A loop not in this table — one registered later — seeds all ten sections from its own SKILL.md the
+same way. The table is seed prose for first write only; it is **not** a roster and never decides
+which automations exist.
+
+**Re-run rule (idempotent, never clobber).** When the file already exists: rewrite the
+machine-resolved block in place and **leave every one of the ten sections exactly as found** — an
+operator's edited Intent paragraph survives verbatim. If a contract section is **missing** from an
+existing file, insert it **at its position in the contract's ten-section order** (never merely
+appended at the end, which would leave the file permanently out of order) with its seeded default.
+Never overwrite, reorder, reword, or delete prose already on disk. If the machine-resolved
+delimiters are absent (a hand-written file), insert the block at the top and touch nothing else.
+
+**Never a precondition.** A runbook that cannot be written is a **degradation, not a blocker**:
+report the failure and continue registering automations. A loop with a missing runbook still runs —
+on the contract's defaults, saying so in its one-line summary — per the contract's
+never-block-always-degrade rule. Scaffolding failure never aborts setup and never leaves an
+automation unregistered.
+
 ## Conditions / guards
 
 - **exploratory-bugs** is created only when the project ships an `exploratory-qa` command (the
@@ -134,3 +232,20 @@ place (same names) rather than creating duplicates.
 
 List each automation created or updated (name, the command it runs, cadence, and the resolved
 `auto-start-prds` / `auto-start-tickets` values), plus any automation skipped and why.
+
+Then list each runbook written, by path (`.lisa/automations/<loop-id>.runbook.md`), saying for each
+whether it was **created** (seeded fresh) or **refreshed** (machine-resolved block rewritten,
+operator prose left untouched). Name every skipped loop again here and state plainly that it has no
+runbook because it was not registered, and why — for example, "exploratory-bugs was skipped because
+this project ships no exploratory-qa command, so no runbook was written for it."
+
+Close with the two lines that tell the operator what to do next:
+
+- When any runbook was newly created: "N new files were written under `.lisa/automations/` — commit
+  them so the whole team sees them."
+- When a runbook could not be written: name which one and what failed, then the consequence and the
+  fix — "that loop runs on defaults and its summaries will lead with 'Runbook missing' — re-run
+  `/lisa:setup-automations` to fix." The automation itself is still registered and still runs.
+
+Every line states the consequence and the action, in words a non-technical operator can act on
+without reading code.

package/plugins/lisa/.codex-plugin/skills/lisa-tear-down-automations/SKILL.md

@@ -21,14 +21,34 @@ removes them with its **native** scheduling mechanism.
 
 ## Scope (remove only what setup created)
 
-- Remove the six automations `/setup-automations` creates for the current project, matched by the
-  stable `lisa-auto-<project>-` name prefix: `intake-repair`, `intake-prd`, `intake-tickets`,
-  `exploratory-bugs`, `exploratory-prds`, `monitor`.
+- Remove **every** automation `/setup-automations` registered for the current project — the whole
+  set found under the stable `lisa-auto-<project>-` name prefix, whatever it currently contains.
+  **Membership is registration, not a roster** (`automation-runbook-contract`): sweep the prefix and
+  remove what is there. Do **not** work from a fixed list of loop names — a list drifts the moment a
+  loop is added, which is exactly how the opt-in gardener came to be orphaned.
+- This explicitly includes the opt-in **`learnings-audit`** gardener when it is registered:
+  `/setup-automations learnings-audit=true` registers it under the same prefix, so teardown removes
+  it with the rest. A conditionally-skipped loop (e.g. `exploratory-bugs` on a stack without
+  `exploratory-qa`) simply is not in the sweep.
 - **Never** remove automations for a different project, or any non-Lisa automation (e.g. unrelated
   crawlers/ingestors). Match strictly on the `lisa-auto-<project>-` prefix for THIS project; when in
   doubt about an automation's ownership, leave it and report it rather than deleting it.
-- **Idempotent** — an automation that is already absent is a no-op, not an error.
+- **Idempotent** — an automation that is already absent is a no-op, not an error. Re-running when
+  the prefix sweep finds nothing is a clean, successful no-op.
+- **Leave the runbooks alone.** The checked-in `.lisa/automations/<loop-id>.runbook.md` files that
+  `/setup-automations` scaffolded are project knowledge and the historical record of what these
+  loops did. Teardown removes scheduler registrations only; it never deletes, edits, or moves a
+  runbook file. An operator who wants them gone removes them deliberately, in git.
 
 ## Report
 
-List each automation removed, and any in the expected set that were already absent.
+List each automation removed by name. For "already absent", compare against the one source of truth
+— the fleet `scripts/automation-status-expected-fleet.mjs` (`resolveExpectedAutomationFleet`)
+resolves for this project — and name anything it expects that the sweep did not find; that is a
+no-op, not an error. Do not invent an expected set of your own.
+
+Then state, in the operator's words, that the runbook files under `.lisa/automations/` were left on
+disk **and why**: they are the written record of what those jobs did, kept on purpose, and if you
+do not want them you delete them yourself in git. Finally, confirm that nothing outside this
+project's `lisa-auto-<project>-` prefix was touched. Write it so a non-technical operator can
+confirm what happened without reading code.

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);
+}