@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/rules/eager/withdrawn-rulings.md

@@ -0,0 +1,102 @@
+# Withdrawn Rulings — a Retraction Travels by the Same Mechanism as the Finding (load-bearing)
+
+**A session is a snapshot, and nothing reaches back into it.** Rules are injected once at session
+start. The plugin version a session executes is resolved once at startup. A fix merged to the
+default branch is not in effect for anything already running. So guidance that is **added** after a
+session starts can at least be found on disk — `settled-decisions` sends you to re-read the
+instruction file at the escalation boundary. Guidance that is **withdrawn** cannot be found at all:
+deleting the source is a push, and a push reaches no existing reader.
+
+The result is one-directional propagation. **New guidance travels; corrections do not.**
+
+## The test for any correction
+
+> Through which channel did the original claim reach its audience, and has the withdrawal gone
+> through that same channel?
+
+- Written to a durable file → the retraction is written to that file.
+- Posted as a work-item comment → edit the original comment, do not only append. A reader who
+  arrives later and forms a conclusion never scrolls to the reply.
+- Relayed in a message → it reaches the same recipients, which requires knowing who they were.
+  You usually do not, which is why the ledger below exists.
+
+## Mandatory
+
+- **Record every withdrawal in the ledger, with one command.** Retracting a claim you circulated,
+  wrote down, or published is not done until this has run:
+
+  ```sh
+  node "$CLAUDE_PLUGIN_ROOT/hooks/withdrawn-rulings.mjs" --withdraw "<id>" \
+    --claim "<the withdrawn claim, verbatim>" \
+    --because "<what disproved it>" \
+    --derived "<an artifact you left standing on it>"
+  ```
+
+  If the audit found no surviving derived artifact, use this alternative:
+
+  ```sh
+  node "$CLAUDE_PLUGIN_ROOT/hooks/withdrawn-rulings.mjs" --withdraw "<id>" \
+    --claim "<the withdrawn claim, verbatim>" \
+    --because "<what disproved it>" \
+    --derived none
+  ```
+
+  Repeat `--derived "<artifact>"` for additional artifacts. Either form may also
+  include `--superseded-by "<id>"` and repeated `--reached "<channel>"` arguments.
+
+  The verbatim claim is required and the command refuses without it: **a tombstone the holder of the
+  claim cannot recognise reaches them without reaching them.**
+
+- **`--derived` is required too, because correcting a premise leaves every inference standing.**
+  Updating the fact is the easy half. The conclusions you already drew from it are the half that
+  reached other agents and the human, and they do not retract themselves. Before you can record the
+  withdrawal you must name what you asserted, filed, or relayed while you believed the claim —
+  tracker state you set, a statement you made to your operator, a message you sent a peer session.
+
+  **The obligation is to produce the list, not to find something wrong in it.** `--derived none` is
+  a complete answer when you checked and nothing survives, and the record keeps it as an empty list
+  so a later reader can tell "audited, nothing standing" from "never audited". An absent answer is
+  refused; an empty one is not.
+
+  Measured instance: a session disproved a false claim that a credential CLI was unavailable,
+  updated the fact, and **two hours later still relayed to its human that a work item was blocked**
+  for a reason resting on the retracted claim. Three facts sat in one context and were never joined.
+
+  It binds here because nowhere else can carry it. Outside the learnings ledger's `provenance` refs,
+  **no artifact Lisa writes records the premise it rests on** — a blocked label, a relayed sentence,
+  a peer message carry no back-pointer. Nothing can go looking afterwards for what rested on a
+  retracted claim. You are the only party still holding that, at the only moment it is being
+  written down.
+
+- **The ledger is the retraction path, precisely because it is cheap.** Writing a finding feels
+  productive; writing a retraction is a chore produced mid-task, after being corrected, when
+  attention has moved on. A rule saying "always record retractions durably" is a discipline, and
+  disciplines do not reach that moment. One command does.
+
+- **Check it at the escalation boundary**, alongside the instruction-file re-read
+  `settled-decisions` already requires: `node "$CLAUDE_PLUGIN_ROOT/hooks/withdrawn-rulings.mjs"
+  --list`. This is what harnesses with no PostToolUse hook rely on.
+
+- **Verify before propagating.** Every retraction is a claim that was relayed before it was checked.
+  Relaying a finding makes you a publisher of it, and a publisher owes the correction.
+
+## What arrives on its own
+
+On Claude Code the ledger is read for you: it is stamped at session start and re-checked after every
+tool call, so a ruling withdrawn **while you are running** arrives attached to your next tool result
+— naming the claim, why it fell, and what replaced it. Two `stat` calls when nothing changed.
+
+It announces only what was withdrawn **since this session started**, and only once each. An
+un-withdrawn ruling is never flagged; a mechanism that made you distrust everything would be worse
+than the gap it closes.
+
+## The failure mode that makes this urgent
+
+**A technique that never works can still look like it worked**, because the condition it was
+supposed to create arrives later on its own. That is worse than intermittency: an intermittent
+technique has a success rate an observer can become suspicious of; this has none, only a delayed
+coincidence that reads as confirmation. Such a claim will not retract itself, and everyone holding
+it believes they have seen it succeed.
+
+Full prose, the two measured instances, and the ledger's two tiers:
+[reference/withdrawn-rulings.md](../reference/withdrawn-rulings.md).

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

@@ -0,0 +1,355 @@
+# Automation Runbook Contract
+
+> Demoted from the always-on eager tier by CodySwannGT/lisa#3992. The
+> section below is the former eager head, preserved verbatim; the full
+> contract follows it. Reachable on demand via [the rule index](../eager/00-rule-index.md).
+
+## 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.
+
+### Interactive flows are members too
+
+The outcome vocabulary is **not cron-specific** — it answers "did this need me?", which an operator
+asks of an interactive run exactly as often as of a scheduled one. Every Lisa flow that terminates
+is a member: `lisa-implement`, `lisa-verify`, `lisa-plan`, `lisa-git-submit-pr`,
+`lisa-drive-pr-to-merge`, `lisa-research`, and any skill invoked as a slash command.
+
+For an interactive flow the required run record is the **final user-facing message**, not a JSONL
+row written by `automation-run-record.mjs`. Interactive flows may also record local JSONL telemetry
+when a specific skill owns that surface, but this contract's mandatory record is the final answer.
+It opens with the outcome and the operator action, before any narrative:
+
+```
+change-proved — nothing for you. PR #6393 open, auto-merge on, CI running.
+approval-requested — need a decision: ship the 135 Regular→Bold flips, or hold for design sign-off?
+recovery-required — need you: staging E2E gate red for congestion; rerun or admin-merge.
+```
+
+The operator must learn whether they are needed **from the first line**, without reading the report.
+Findings, evidence and caveats follow; they never replace the action line and never precede it.
+
+An interactive flow that ends in prose with the action buried — or absent — is the same contract
+violation as a silent cron exit. "I flagged X, I noticed Y, worth knowing Z" is narrative, not an
+outcome. If nothing is needed, say **"nothing for you"** in those words and stop.
+
+## 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.
+  A queue scanner's `nothing-needed` summary must name the lanes it swept and the total open — a dry
+  queue and a wrong denominator are otherwise indistinguishable. See the reference body.
+- `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 as **Not planned**; 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. 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
+
+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.
+
+---
+
+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.
+```
+
+That example's 30-day retirement row is **illustration of the shape, not the shipped default**: the
+seed `lisa-setup-automations` writes declares the three `intake-*` loops structural to the factory,
+whose runbooks state plainly that they do not retire. The mechanism below is normative; the numbers
+above are only a filled-in example.
+
+## 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 as **Not planned**; 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.
+```
+
+### `nothing-needed` states its denominator
+
+A queue-scanning loop that reports nothing is only as trustworthy as the set it looked at, and a
+summary of the form "scanned N items" hides the one thing worth checking: **which lanes N came
+from.** So a `nothing-needed` summary from a queue scanner names the lanes it swept, the count in
+each, and the total open — `Looked in every lane holding work that has not started — Backlog (20),
+Todo (17), Ready (2), Blocked (61) — 100 items checked out of 343 still open.`
+
+This is a measured requirement, not a style preference. One build lane reported 31 consecutive dry
+cycles over a queue holding 61 unswept rows, at least one of them buildable for ~15 hours. Every
+one of the 31 records was honest and every conclusion was false, because the scanner never said
+what its denominator was. **A missing run record is noisy on inspection; a wrong denominator is
+silent forever and looks exactly like a healthy dry queue.** Stating the swept set is what makes
+the second failure mode visible at all.
+
+The build-intake loop enforces this rather than requesting it: `automation-run-record.mjs` refuses
+a `nothing-needed` row for `intake-tickets` unless the call carries a `--denominator` built by
+`scripts/intake-prework-denominator.mjs`.
+
+**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 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
+
+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.
+
+Every escalation is a **declared human gate** under `ready-role-filing`: it passes
+`human_gate: "<the smallest unresolved choice>"` so the writer stamps the auditable
+`[lisa-human-gate]` marker. An escalation is precisely a filing whose readiness a human owns, so
+omitting the flag and relying on a tracker default would make a deliberate gate indistinguishable
+from the accidental non-ready filing that rule exists to catch.
+
+
+| 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 as **Not planned** — closing it as
+**Completed** leaves a later re-file open, per `rejection-detection`'s proposal rejection memory;
+either way 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. 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-devin/rules/reference/base-rules.md

@@ -0,0 +1,136 @@
+Intent Routing (FIRST — before anything else):
+
+Before starting any work in a session, classify the user's initial request using the Intent Routing rule. Determine which flow applies (Research, Plan, Implement, Verify, or None) and check its readiness gate. Once a flow is established, all subsequent messages operate within it. Do not skip this step — even if the request seems simple. See the `intent-routing` rule for the full protocol.
+
+Orchestration Selection (SECOND — immediately after classifying the flow):
+
+After echoing the chosen flow and BEFORE doing any work, state the orchestration mode explicitly — either `Orchestration: agent team` or `Orchestration: single agent` — with a one-sentence justification. This echo is mandatory and must appear in the same message as the flow classification.
+
+Default to an agent team for Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), and any flow that invokes the Review sub-flow. Use a single agent only for Verify (standalone) and Monitor (standalone). See the `intent-routing` rule's Orchestration section for the full decision matrix.
+
+When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST establish team orchestration before any content-gathering work. Use the team tool for the current runtime: modern Claude Code uses the implicit team model, where the first `Agent` spawn establishes the team; older Claude Code may still expose `TeamCreate` and that path is accepted. Codex must not call `TeamCreate` because Codex does not expose that Claude tool. In Codex, use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation and treat the first successful `spawn_agent` call as establishing team orchestration. Other runtimes should use their current tool-discovery mechanism to discover and call the appropriate multi-agent/team tool. If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Apart from the initial Claude `Agent` spawn that establishes the team, do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists, the first Codex teammate has been spawned, or the no-team fallback has been declared — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before orchestration exists. If you ARE already operating inside an agent team, do NOT create a second team and do NOT collapse into inline single-agent work; instead request the existing team lead add the specialist agent(s) this flow needs to the current team — on Claude, teammates cannot add named teammates (teams are flat), so message the lead with the teammate(s), assignments, and completion criteria; on Codex, ask the addressable lead/root to `multi_agent_v1.spawn_agent` them, or if no lead handle exists spawn the bounded specialists yourself, `wait_agent`, and relay results upward — then coordinate through the shared task state.
+
+Requirement Verification:
+
+Never assume the person providing instructions has given you complete, correct, or technically precise requirements. Treat every request as potentially underspecified. Before starting any work:
+
+1. Identify any ambiguities in the request that would prevent you from completing the work. If any exist, stop and ask for clarification.
+2. Identify any open questions whose answers would change your approach. If any exist, stop and ask.
+3. Define how you will empirically verify the work is complete — not by running tests or linters, but by using the resulting software the way a user would. If you cannot define this, stop and ask for clarification.
+4. If a request contradicts existing code, architecture, or conventions, do not silently comply. Raise the contradiction and confirm intent before proceeding.
+
+DO NOT START WORK if any of the above are unclear. Asking a clarifying question is always cheaper than implementing the wrong thing.
+
+Do not begin a task if there are any blockers, ambiguities, access requirements, unanswered questions, or unknowns that would prevent you from completing it. Identify these before starting — not during implementation. If you cannot confirm that you have everything needed to finish the work end-to-end, stop and surface what is missing.
+
+Project Discovery:
+- Determine the project's package manager before installing or running anything.
+- Read the project manifest (e.g. package.json, pyproject.toml, Cargo.toml, go.mod) to understand available scripts and dependencies.
+- Before defining a verification approach, check the `scripts` section of the project manifest for existing commands to start servers, run tests, seed databases, etc. Use existing scripts rather than inventing ad-hoc commands.
+- Read the project's linting and formatting configuration to understand its standards.
+- Regenerate the lockfile after adding, removing, or updating dependencies.
+- Ignore build output directories (dist, build, out, target, etc.) unless specified otherwise.
+- Ignore configuration linter hints/warnings — only fix actual unused exports/dependencies reported as errors.
+
+Code Quality:
+- Make atomic commits with clear conventional commit messages.
+- Create clear documentation preambles for new code. Update preambles when modifying existing code.
+- Document the "why", not the "what". Code explains what it does; documentation explains why it exists.
+- Always add new imports and their first usage in the same edit. The lint-on-edit hook verifies changed files after every Edit, so unused-import diagnostics should be fixed in the same edit that introduced them.
+- Add language specifiers to fenced code blocks in Markdown.
+- Use project-relative paths rather than absolute paths in documentation and Markdown.
+- Delete old code completely when replacing it. No deprecation unless specifically requested.
+- Fix bugs and issues properly. Never cover them up or work around them.
+- When a tool or build step fails, never assume the failure is pre-existing and work around it. Investigate the root cause first — check git history, find when it broke and why — before deciding how to proceed.
+- Test empirically to confirm something worked. Never assume.
+- Never assume test expectations before verifying actual implementation behavior. Run tests to learn the behavior, then adjust expectations to match.
+- Always provide a solution. Never dismiss something as "not related to our changes" or "not relevant to this task".
+
+Git Discipline:
+- Prefix git push with `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"`.
+- Never commit directly to an environment branch (dev, staging, main).
+- Never use --no-verify or attempt to bypass a git hook.
+- When a pre-commit, pre-push, CI, or other quality gate fails, fix the root cause first: upgrade the vulnerable dependency, fix the lint/type/test failure, remove the secret, or repair the failing check. If a fix is genuinely impossible, ask the user to make the risk-acceptance decision and add a narrow, documented ignore for the specific failing rule or advisory. Never use `--no-verify`, hook environment switches, blanket ignores, or threshold reductions as a substitute for fixing the gate.
+- Never bypass branch protection. Never use `--admin`, `--force`, or any other flag to merge a PR that has failing CI checks. If CI fails, fix it. If you cannot fix it, escalate to the human. There are zero exceptions. "Green in CI" is the definition of done — not "green locally." A PR is not complete until CI passes on the actual PR branch.
+- **Never use plain `git push --force`.** When a history rewrite is explicitly approved, use `--force-with-lease`; prefer the explicit SHA-bound form `--force-with-lease=<ref>:<sha>`, such as `git push --force-with-lease=refs/heads/<branch>:<approved-sha> origin HEAD:refs/heads/<branch>`, where `<approved-sha>` is the exact remote tip the approval covered.
+- **History-rewrite approval is SHA-scoped, not durable.** Record the remote ref and exact SHA the authorization covers. If the remote ref moves or the lease rejects, the approval is void: stop and obtain fresh confirmation for the new remote state. Never re-derive consent from the earlier approval or treat a fresh fetch as renewing authorization for a different SHA; do not retry with an updated implicit lease or plain `--force`.
+- Never stash changes you cannot commit. Either fix whatever is preventing the commit or fail out and let the human know why.
+- Never add "BREAKING CHANGE" to a commit message unless there is actually a breaking change.
+- When opening a PR, watch the PR. If any status checks fail, fix them. For all bot code reviews, if the feedback is valid, implement it and push the change to the PR. Then resolve the feedback. If the feedback is not valid, reply to the feedback explaining why it's not valid and then resolve the feedback. Do this in a loop until the PR is able to be merged and then merge it.
+- When merging a PR into an environment branch (dev, staging, main), watch the resultant deploy until it fully succeeds. If it fails for any reason, fix the failure and then open a new PR with the fix.
+- When referencing a PR in a response, always include the url
+- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use a regular merge commit (`gh pr merge --merge`) as well.
+
+Testing Discipline:
+- Never skip or disable any tests or quality checks.
+- Never add skip directives to a test unless explicitly asked to.
+- Never lower thresholds to pass a pre-push hook. Increase test coverage to make it pass.
+- Never duplicate test helper functions without appropriate lint suppression when duplication is intentional for test isolation.
+
+JIRA Discipline:
+- If working on a JIRA issue, make sure the branch you're working on references and is added to the JIRA issue.
+- If working on a JIRA issue, update the issue as you work through it. For example, if working on a Bug Triage, update the issue with your questions/feedback/suggestions.
+- When reading a JIRA issue, always read ALL comments on the ticket — not just the description. Comments contain critical context: stakeholder decisions, scope changes, blockers, triage findings from other repos, and implementation notes. Use the Atlassian MCP or first resolve the project root from `$CLAUDE_PROJECT_DIR` or `git rev-parse --show-toplevel`. When `$PROJECT_ROOT/.lisa/jira-cli/.config.yml` exists, run both `jira --config "$PROJECT_ROOT/.lisa/jira-cli/.config.yml" issue view <TICKET_ID>` and `jira --config "$PROJECT_ROOT/.lisa/jira-cli/.config.yml" issue comment list <TICKET_ID>`; the dedicated comment-list command returns the complete comment collection instead of a fixed recent-comment window. If that project config is absent, omit `--config` from both commands to use the machine's own `~/.config/.jira/.config.yml`.
+- When requesting clarification on a JIRA issue, post the question as a comment using ADF (Atlassian Document Format) and @mention the Reporter so they receive a notification.
+- When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked. Relationship discovery is mandatory on every create and update — search BOTH the local git history (`git log --all --grep=<keyword>`, `git log -- <path>`) AND Jira (JQL by component, keyword, label, epic siblings) before declaring "no related work." Record the searches you ran and their outcomes in the description (or a comment) so a reviewer can see the search was real.
+- Ticket scope by type: Bug, Task, and Sub-task tickets MUST be single-repo (one work unit, one repo). Epic, Spike, and Story tickets MAY span multiple repos. If a Bug/Task/Sub-task crosses repos, split it per the `repo-scope-split` rule — at PRD-decomposition time via `task-decomposition` step 1.5 (parent Story + per-repo children); at work-time (an existing ticket an agent is about to implement) via the work-time split procedure (narrow the original to one repo, spin off a sibling per additional repo cloning its metadata, link the producer→consumer dependency, then proceed). A cross-repo work unit is a decomposition error the agent fixes by splitting, not a reason to bounce the ticket to the reporter.
+- Ticket descriptions MUST contain everything an implementer needs to start work without asking the reporter. In particular:
+  - **Target backend environment** (`dev` / `staging` / `prod`) when the ticket has runtime behavior. QA/product report against a deployed env; the implementer verifies locally first against that backend before CI/CD. Skip only for doc-only, config-only, type-only, or Epic tickets.
+  - **Sign-in account / credentials** when the work requires being signed in. Name the account (or the source — 1Password item, env var, seeded fixture) and the role. Omit entirely when sign-in is not required.
+  - **Gherkin acceptance criteria** (Given/When/Then) so the implementer can verify behavior without guessing.
+  - **Relationship discovery evidence** — either an issue link to a related ticket, or a documented search showing none was found (see Relationship Discovery in jira-verify).
+- Ticket metadata MUST include an **epic parent** for non-bug, non-epic tickets so every Story/Task/Sub-task is traceable to a strategic goal.
+- Pre-flight gate before starting work on any ticket: if the description is missing target backend environment (when applicable), sign-in credentials (when applicable), Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence, first **draft** the authorable missing sections into the ticket as clearly-labeled assumptions (the `pre-flight-autofill` draft-then-block procedure — the agent writes spec, never code, here), then transition the ticket to Blocked, reassign to the **Reporter**, and post a **confirmation** comment asking them to confirm the drafted assumptions (not a bare "go write all this" checklist). Do not start work. This is the one place where auto-transitioning status is allowed.
+- When checking for associated pull requests on a JIRA issue, check the **Development panel** — not just comments or description text. The Development panel shows PRs, commits, branches, and builds linked via the GitHub-Jira integration. Query it via the dev-status API:
+  ```bash
+  ISSUE_ID=$(curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \
+    "${JIRA_SERVER}/rest/api/2/issue/${TICKET_ID}?fields=id" | jq -r '.id')
+  curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \
+    "${JIRA_SERVER}/rest/dev-status/1.0/issue/detail?issueId=${ISSUE_ID}&applicationType=GitHub&dataType=pullrequest" \
+    | jq '.detail[].pullRequests[] | {title, status, url, source: .source.branch}'
+  ```
+
+Agent Behavior:
+- Never handle tasks yourself when working in a team of agents. Always delegate to a specialized agent.
+
+Pace:
+- Never rush. There is no pressure to finish quickly. Speed is not a measure of quality, and a fast wrong answer is worse than a slow correct one.
+- Take the time to read the relevant code in full, verify assumptions empirically, ask clarifying questions when something is ambiguous, and check your work before declaring it done.
+- Do not skip steps to save time — quality gates, verification, reading existing code, asking the user — these exist because shortcuts cost more than they save.
+- If a task feels like it's taking "too long," that is almost always a sign that the task is harder than it first appeared, not a sign that you should cut corners. Surface the difficulty to the user instead of compressing the work.
+- Optimize for being correct, thorough, and reversible. Time spent doing the work right is never wasted; time spent recovering from a rushed answer often is.
+
+NEVER:
+- Modify this file directly. To add a memory or learning, use the project's rules file or create a skill.
+- Directly modify files inside dependency directories (e.g. node_modules, .venv, vendor, target).
+- Delete anything that is not tracked in git.
+- Delete anything outside of this project's directory.
+- Create placeholder implementations.
+- Create TODOs.
+- Create versioned copies of files or functions (e.g. V2, Optimized, processNew, handleOld).
+- Write migration code unless explicitly requested.
+- Write functions or methods unless they are needed.
+- Write unhelpful comments like "removed code" or "old implementation".
+- Update CHANGELOG.
+
+ASK FIRST:
+- Before adding a lint or formatter suppression comment (e.g. eslint-disable, biome-ignore, prettier-ignore, noqa, #[allow(...)], @SuppressWarnings). These should be a last resort.
+- Before adding a type-checking suppression comment (e.g. ts-ignore, ts-expect-error, ts-nocheck, type: ignore).
+- Lint suppression in test files is acceptable without asking only when comprehensive test coverage requires it (e.g. file length limits) or when intentional duplication improves test isolation. Include matching re-enable comments where applicable.
+
+Multi-Repository Awareness:
+
+When working in a microservices architecture, the code you need may span multiple repositories. Watch for these signals that you're missing context:
+
+1. Import paths or package references that don't resolve in the current repository
+2. API calls to internal services where you can't find the contract, schema, or handler
+3. Shared libraries, SDKs, or proto/OpenAPI definitions referenced but not present
+4. Environment variables or config referencing service names you don't have code for
+5. Error messages or stack traces pointing to code outside the current repo
+6. JIRA issues or documentation referencing components in other repositories
+
+When you detect any of the above:
+1. Do NOT guess or make assumptions about what the external code does
+2. Identify which repository contains the missing code
+3. Add that repository to your current session before proceeding
+4. If you cannot determine which repository contains the code, ask — do not proceed without it