@codyswann/lisa 2.253.0 → 2.255.0

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.253.0",
+  "version": "2.255.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.255.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.255.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/.codex-plugin/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/lisa/.codex-plugin/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

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.