@codyswann/lisa 2.251.1 → 2.253.0

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.251.1",
+  "version": "2.253.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.251.1",
+  "version": "2.253.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.251.1",
+  "version": "2.253.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

@@ -0,0 +1,61 @@
+# Automation Runbook Contract (load-bearing)
+
+**Every registered automation loop carries a checked-in runbook, and every run of that loop ends in
+exactly one of six run outcomes** with a one-line, operator-readable summary. A registered loop with
+no runbook, or a run that stops without naming its outcome, is a contract violation.
+
+**One vendor-neutral contract, to be cited by (wired in the loop-conformance ticket)
+`lisa-setup-automations`, `lisa-automation-status`, `lisa-tear-down-automations`, and every
+registered loop skill** (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug,
+never divergent per-loop prose).
+
+## Membership
+
+Membership is **registration, not skill-existence**: a loop is under this contract the moment it is
+registered as a scheduled automation, and registering a new one pulls it in automatically. There is
+no hardcoded roster of loops anywhere.
+
+## The six run outcomes
+
+Exactly one per run:
+**`nothing-needed | candidate-proposed | change-proved | approval-requested | recovery-required | policy-obsolete`**
+
+Health and operator action are **orthogonal** — a healthy run can still need an answer:
+
+- `nothing-needed` — the loop ran and found nothing to act on. **Healthy.** Operator action: none.
+- `candidate-proposed` — the loop proposed work (ticket, PRD, recommendation). **Healthy.** Operator
+  action: review the proposed item and flip it ready when you want it built.
+- `change-proved` — the loop made a change and proved it with evidence. **Healthy.** Operator
+  action: none (informational).
+- `approval-requested` — the loop reached a boundary it may not cross alone. **Healthy.** Operator
+  action: answer the approval question.
+- `recovery-required` — the loop itself could not complete (access, tooling, or substrate broken)
+  and escalated a decision-ready packet. **Not healthy.** Operator action: restore the named
+  capability, then close the escalation item.
+- `policy-obsolete` — the loop's own retirement policy (the retirement condition written in its
+  runbook) tripped, so it proposed its own teardown. **Healthy.** Operator action: approve the
+  teardown, decline it (close the proposal; the loop keeps running at cadence), or re-cadence it.
+
+## A run outcome is NOT a work-item lifecycle terminal state (CRITICAL)
+
+A **run outcome** describes the LOOP ITERATION. A **terminal state** describes a TICKET — Lisa
+already uses that phrase for work-item lifecycles (`lisa-intake`: "`Blocked` is a valid terminal
+state of the downstream lifecycles"). The two vocabularies never merge in an operator-facing report.
+A healthy cycle that routes a work item to `Blocked` with clarifying questions is
+`candidate-proposed` — it produced something — so it is **never `nothing-needed`**, which is
+reserved for runs that found nothing at all, and **never `recovery-required`**, which means the
+loop itself is broken, not that a work item was blocked.
+
+## No silent exit
+
+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.
+
+## Never block, always degrade
+
+A missing runbook, an unreadable record surface, or an absent optional dependency **degrades** the
+run — say so in the summary and finish with an outcome — it never crashes the loop, never blocks
+other work, and never leaves the run unreported.
+
+Full contract (template, outcome definitions, escalation packet, retirement): [reference/automation-runbook-contract.md](../reference/automation-runbook-contract.md).

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

@@ -0,0 +1,216 @@
+# Automation Runbook Contract
+
+Scheduled loops are the busiest machinery in the factory and historically the least explicitly
+contracted: what a loop maintains, what it may do on its own, what it must escalate, and when it
+should stop existing all lived implicitly in each loop's prose. The cost lands on the operator — a
+quiet run and a broken run look identical, and "what is this scheduled thing?" has a different
+answer shape for every loop. This contract writes the answer down once.
+
+It is a **single vendor-neutral contract** consumed by `lisa-setup-automations` (which scaffolds a
+runbook per registered loop), `lisa-automation-status` (which reads runbooks and run outcomes back
+to an operator), `lisa-tear-down-automations` (which acts on retirement proposals), and every
+registered loop skill (which conforms its own run to it). Each consumer cites this slug; none of
+them redefines it.
+
+**Membership is registration, not skill-existence.** A loop falls under this contract when it is
+registered as a scheduled automation on the host project's runtime scheduler — not when its skill
+file happens to exist in the plugin tree. Registering a new loop pulls it in automatically, and
+un-registering drops it. Nothing in this contract, in the scaffolder, or in the status surface may
+carry a hardcoded roster of loops; the worked example below names one loop as illustration only.
+
+## The runbook template
+
+Every registered loop's runbook has these ten sections, in this order. Each is answered in prose a
+non-technical operator can read (`factory-model` rule 5).
+
+| Section | What a good answer looks like |
+|---|---|
+| Intent | One sentence naming what this loop maintains, in outcome terms, not mechanism terms. |
+| Sources of truth | The exact surfaces the loop reads, each reachable through its access layer (`integration-access-layer`) — never a direct vendor API call. |
+| Candidate selection | The query or filter that decides what this run acts on, and the bound on how many. |
+| Scope/bounds | What the loop will never touch, and the cap that keeps one run finite. |
+| Proof | What the loop must observe before claiming it changed anything — the evidence it records. |
+| Autonomous-vs-approval boundary | The named line: what it does alone, and the first thing on the other side that requires a human. |
+| Escalation | What it files when it cannot proceed — always the decision-ready packet below. |
+| Recovery | What a human or the next run does to get the loop working again after `recovery-required`. |
+| Next-run state | What the next run can observe from this one, derived from durable surfaces (tracker, records) rather than in-process memory. |
+| Retirement condition | The stateless, tracker-derived condition under which this loop proposes its own teardown. |
+
+### Worked example — the `intake-tickets` loop
+
+```text
+Loop: intake-tickets
+
+Intent
+  Keeps the build queue moving: work items a human marked ready get built, reviewed, and shipped
+  without anyone having to hand them to an agent.
+
+Sources of truth
+  The configured tracker's build queue (the ready/claimed/done lanes from .lisa.config.json), read
+  through the tracker access layer; the item's own comments and linked PRs.
+
+Candidate selection
+  The oldest eligible leaf work item currently in the ready lane, one per run. Containers with open
+  children are repaired out of the queue, never built.
+
+Scope/bounds
+  Only items in this repo's configured queue. It never edits the ready lane's meaning, never
+  invents work items, and never processes more than its per-run cap.
+
+Proof
+  A merged pull request plus the project's own verification evidence posted back to the work item;
+  a claim of "done" without that evidence is not made.
+
+Autonomous-vs-approval boundary
+  Alone: claim, plan, implement, open the PR, drive it to merge. Requires a human: anything that
+  needs a protected deployment approval, and any item whose requirements it cannot resolve — that
+  becomes a blocked work item with clarifying questions, not a guess.
+
+Escalation
+  When the loop itself cannot proceed (tracker credentials revoked, queue unreadable), it files the
+  decision-ready packet below, labeled status:blocked + human-needed.
+
+Recovery
+  A human restores the named access, then flips the escalation item closed; the next scheduled run
+  resumes with no manual replay needed.
+
+Next-run state
+  Nothing in memory. The tracker lanes and the run records are the state: a claimed item that never
+  finished is visible as claimed, and the repair path picks it up.
+
+Retirement condition
+  Propose teardown when BOTH hold: no work item has entered this queue for 30 consecutive days, AND
+  this run proposed nothing. It files one teardown-proposal item and keeps running at its normal
+  cadence until someone approves, declines, or re-cadences it.
+```
+
+## The six run outcomes
+
+Exactly one per run. The one-line operator summary is not optional — it is what the status surface
+shows and what makes the outcome actionable.
+
+Health and operator action are **orthogonal**: several healthy outcomes still want an answer, and
+only `recovery-required` means the machinery itself is broken.
+
+| Outcome | Definition | Healthy? | Operator action? | One-line summary must contain |
+|---|---|---|---|---|
+| `nothing-needed` | The loop ran end to end and found nothing to act on. | Healthy — **no operator action** | None. | What was scanned, how much was seen, and "nothing to propose". |
+| `candidate-proposed` | The loop proposed work — a ticket, PRD, or recommendation — for a human or a downstream factory. | Healthy | Review the proposed item and flip it ready when you want it built. | What was proposed and where to find it (item refs). |
+| `change-proved` | The loop made a change and proved it with evidence. | Healthy | None — informational. | What changed and the evidence that proves it. |
+| `approval-requested` | The loop reached its autonomous/approval boundary and asked a human. | Healthy | Answer the approval question. | What is waiting, on whom, and what happens if nobody answers. |
+| `recovery-required` | The loop itself could not complete: access, tooling, or substrate is broken. | **Not healthy** — needs a human | Restore the named capability, then close the escalation item. | What broke, and the escalation item to act on. |
+| `policy-obsolete` | The loop's own retirement policy — the retirement condition written in its runbook — tripped, so it proposed its own teardown. | Healthy | Decide: approve the teardown, decline it (close the proposal; the loop continues at cadence), or re-cadence it. | Why it looks obsolete and the teardown-proposal item. |
+
+### Exemplar one-line summaries
+
+These set the register every conforming loop copies — plain, specific, and actionable without
+reading code:
+
+```text
+nothing-needed      Scanned 12 ready items; nothing to propose.
+candidate-proposed  Proposed #1810 to fix the failing checkout step; awaiting your flip to ready.
+change-proved       Merged #1811 raising coverage to 84%; CI green and evidence posted on the item.
+approval-requested  Deploy to production is waiting on your approval; nothing ships until you answer.
+recovery-required   Lost access to the tracker; filed #1812 with the one decision needed to restore it.
+policy-obsolete     No work has reached this queue in 30 days; proposed teardown in #1813.
+```
+
+**No silent exit.** Every run posts its outcome and its one-line summary before stopping —
+including the trivial early terminations (empty queue, nothing eligible, already-claimed) — so
+there is no silent exit for an operator to misread as health. A run that ends without a
+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.)
+
+## A run outcome is not a work-item lifecycle terminal state
+
+This is the highest-risk seam in the contract, so it is stated explicitly.
+
+- A **run outcome** describes the LOOP ITERATION — how this scheduled execution ended.
+- A **terminal state** describes a TICKET — Lisa already uses that phrase for work-item lifecycles
+  (`lisa-intake`: "`Blocked` is a valid terminal state of the downstream lifecycles"; see
+  `prd-lifecycle-rollup`).
+
+They never merge in an operator-facing report. A perfectly healthy cycle that routes a work item to
+`Blocked` — because the item's requirements are unresolvable and a human must answer — is
+`candidate-proposed`: the run produced something (a blocked item carrying clarifying questions), so
+it is **never `nothing-needed`**, which is reserved for runs that found nothing at all, and **never
+`recovery-required`**, which means the machinery is broken. Conflating a blocked work item with a
+broken loop would paint healthy intake cycles permanently red and train operators to ignore the
+fleet verdict.
+
+## Escalation — the decision-ready packet
+
+A loop that cannot proceed escalates by filing a tracker item (through `lisa-tracker-write`, per
+`tracked-work` and `integration-access-layer`) labeled **`status:blocked`** and **`human-needed`**,
+containing exactly these fields:
+
+| Field | Content |
+|---|---|
+| Current state | Where things stand right now, in plain terms — what is and is not working. |
+| Work already attempted | What the loop tried on its own before escalating, so nobody repeats it. |
+| Evidence | Links to the runs, items, logs, or records that show the problem (the evidence packet from the evidence PRD is the carrier; this contract names it and defines no evidence formats). |
+| Risk of inaction | What degrades or stops if nobody acts, and how soon. |
+| Smallest unresolved choice | The single smallest decision a human must make — one question, not a list — stated with **named options** (or as a yes/no), and what the loop will do with each answer. |
+| How to answer | The mechanical response path: comment on the item, flip a label, or close it — so the operator never has to guess how to reply. |
+
+The wording requirement is binding: a **non-technical operator must be able to act on the packet
+without reading code** (`factory-model` rule 5). A stack trace may be attached as evidence, but the
+packet must stand without it.
+
+## Retirement condition
+
+A loop that no longer earns its schedule should say so. The condition is **stateless — derived from
+the tracker, never from a counter or a state file** (there is no durable home for a run counter, and
+a tracker-derived condition is headless- and concurrent-safe by construction). This generalizes the
+*Retirement condition* section of `lisa-learnings-audit`, which already retires itself this way; its
+current wording still uses the older three-value "terminal states" vocabulary, and the
+loop-conformance ticket conforms it to the six run outcomes above. A loop proposes retirement when
+BOTH hold:
+
+1. **Quiet trailing window** — a date-filtered tracker search finds nothing this loop produced
+   within its trailing quiet window (sized to a small multiple of its cadence).
+2. **This run proposes nothing** — the current run yields zero candidates (it is otherwise ending
+   `nothing-needed`).
+
+When both hold, the run ends `policy-obsolete` and files **exactly ONE marker-deduped**
+teardown-proposal item — matched on the marker, never the title — carrying the date-filtered search
+result and this run's summary as evidence, and proposing either a longer cadence or
+`lisa-tear-down-automations`. The loop **keeps running at its normal cadence** until an operator
+flips that proposal one of three ways: **approve** it (`lisa-tear-down-automations` runs and the
+registration goes away), **decline** it (close the proposal — the loop simply continues), or
+**re-cadence** it (register it at the longer cadence instead of tearing it down). Retirement is a
+recommendation like any other, **never a self-executed exit**: a loop never deletes its own
+registration, and a proposal nobody answers changes nothing.
+
+## Never block, always degrade
+
+A loop degrades rather than blocking. Three triggers are expected and must never crash a run:
+
+- **A missing runbook** — the loop runs on the contract's defaults and says so.
+- **An unreadable record surface** — the loop still reports its outcome and summary in its own run
+  output, so the operator is never left with silence.
+- **An absent optional dependency** — a skill or surface that ships with a sibling ticket is not
+  yet installed; the loop skips that enrichment and continues.
+
+A degraded run still **reports its actual outcome from the same six values** — degradation does not
+mint a seventh token and, on its own, is not `recovery-required`. Its one-line summary **leads with
+the degradation**, then states the outcome:
+
+```text
+Runbook missing — ran on defaults; nothing to propose.
+```
+
+Degradation becomes `recovery-required` only when it prevents the loop from doing its actual job
+(the queue itself is unreadable, credentials are revoked) — and then it escalates the decision-ready
+packet above. A degraded run never blocks other work and never leaves the run unreported.
+
+## 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.

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

@@ -10,6 +10,11 @@
  */
 
 import { compareAutomationFleet } from "./automation-status-contract-drift.mjs";
+import {
+  assignToAutomationGroup,
+  createAutomationGroupBins,
+  renderAutomationGroups,
+} from "./automation-status-expected-fleet.mjs";
 
 const CLAUDE_RUNTIME_LABEL = "Claude /schedule";
 const CLAUDE_ACTIVE_STATUSES = new Set([
@@ -75,10 +80,7 @@ export function inspectClaudeAutomationFleet(input) {
     automationPrefix: expectedFleet.automationPrefix,
   });
 
-  const expectedGroups = new Map([
-    ["core", []],
-    ["exploratory", []],
-  ]);
+  const expectedGroups = createAutomationGroupBins();
 
   const comparisons = compareAutomationFleet({
     expectedAutomations: expectedFleet.expected,
@@ -87,7 +89,9 @@ export function inspectClaudeAutomationFleet(input) {
 
   for (const [index, expected] of expectedFleet.expected.entries()) {
     const comparison = comparisons[index];
-    expectedGroups.get(expected.group)?.push(
+    assignToAutomationGroup(
+      expectedGroups,
+      expected.group,
       createObservedStatusItem({
         expected,
         comparison,
@@ -97,7 +101,7 @@ export function inspectClaudeAutomationFleet(input) {
   }
 
   for (const unsupported of expectedFleet.unsupported) {
-    expectedGroups.get(unsupported.group)?.push({
+    assignToAutomationGroup(expectedGroups, unsupported.group, {
       id: unsupported.automationId,
       status: "UNSUPPORTED",
       summary: unsupported.reason,
@@ -109,18 +113,7 @@ export function inspectClaudeAutomationFleet(input) {
   return {
     runtime: `${CLAUDE_RUNTIME_LABEL} listing`,
     generatedAt: now.toISOString(),
-    groups: [
-      {
-        id: "1",
-        title: "Core automations",
-        items: expectedGroups.get("core") ?? [],
-      },
-      {
-        id: "2",
-        title: "Exploratory automations",
-        items: expectedGroups.get("exploratory") ?? [],
-      },
-    ],
+    groups: renderAutomationGroups(expectedGroups),
     observedAutomations,
   };
 }
@@ -487,6 +480,13 @@ function normalizeClaudeRRule(value) {
   ) {
     return "FREQ=DAILY;INTERVAL=1";
   }
+  if (
+    cadence === "once a week" ||
+    cadence === "every week" ||
+    cadence === "weekly"
+  ) {
+    return "FREQ=WEEKLY;INTERVAL=1";
+  }
 
   const everyMinutes = cadence.match(/every (\d+) minutes?/);
   if (everyMinutes?.[1]) {
@@ -503,6 +503,11 @@ function normalizeClaudeRRule(value) {
     return `FREQ=DAILY;INTERVAL=${everyDays[1]}`;
   }
 
+  const everyWeeks = cadence.match(/every (\d+) weeks?/);
+  if (everyWeeks?.[1]) {
+    return `FREQ=WEEKLY;INTERVAL=${everyWeeks[1]}`;
+  }
+
   return undefined;
 }
 
@@ -527,6 +532,9 @@ function humanizeClaudeCadence(value) {
   if (normalized === "every day") {
     return "once a day";
   }
+  if (normalized === "weekly" || normalized === "every week") {
+    return "once a week";
+  }
   return normalized;
 }
 
@@ -556,6 +564,11 @@ function humanizeRRule(rrule) {
     return Number(daily[1]) === 1 ? "once a day" : `every ${daily[1]} days`;
   }
 
+  const weekly = rrule.match(/^FREQ=WEEKLY;INTERVAL=(\d+)$/);
+  if (weekly?.[1]) {
+    return Number(weekly[1]) === 1 ? "once a week" : `every ${weekly[1]} weeks`;
+  }
+
   return rrule;
 }
 
@@ -574,6 +587,11 @@ function cadenceLabelToIntervalMs(label) {
     return 24 * 60 * 60_000;
   }
 
+  const oncePerWeek = new Set(["once a week", "weekly"]);
+  if (oncePerWeek.has(label)) {
+    return 7 * 24 * 60 * 60_000;
+  }
+
   return null;
 }