@codyswann/lisa 2.237.0 → 2.239.0

package/plugins/lisa/.codex-plugin/skills/lisa-persist-learning/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: lisa-persist-learning
+description: "a candidate learning (from a…"
+---
+
+# Persist Learning
+
+Route ONE candidate learning through the judgment gate and act on the verdict. Candidate: $ARGUMENTS
+
+Most candidates are dropped — that is the gate working, not a failure. Nothing is ever silent (every drop leaves a visible note), and no learning content ever reaches the learnings surface outside a pull request.
+
+## Candidate Input
+
+Accept the candidate as JSON or `key=value` fields:
+
+- `rule` — the proposed learning (must fit the executable contract: ≤240 chars, ≤2 lines)
+- `why` — the causal claim
+- `provenance` — stable refs (issues/PRs/commits/comments), ≤20
+- `evidence_links` — concrete evidence refs available for citation
+- `scope_hint` — `project` | `upstream` (a hint; the judge decides)
+- `triggering_issue` — the issue/work item whose failure produced this candidate (required)
+- `fingerprint` — optional; computed below when absent
+
+## Phase 0 — Fingerprint (stable dedupe key)
+
+Every marker and branch below keys off one deterministic fingerprint:
+
+```text
+fingerprint = "sll4-" + first 12 hex chars of sha1(normalized_rule + "\n" + triggering_issue)
+normalized_rule = rule lowercased, all whitespace runs collapsed to single spaces, trimmed
+```
+
+```bash
+NORM=$(printf '%s' "$RULE" | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ' | sed 's/^ *//; s/ *$//')
+FP="sll4-$(printf '%s\n%s' "$NORM" "$TRIGGERING_ISSUE" | shasum -a 1 | cut -c1-12)"
+```
+
+(Use `sha1sum` where `shasum` is unavailable.) The same rule for the same triggering issue always produces the same fingerprint, so re-runs dedupe instead of duplicating comments, PRs, or branches.
+
+## Phase 1 — Judge (mandatory, never skipped)
+
+Invoke the `learning-judge` agent (via the Agent/Task tool with `subagent_type: "learning-judge"` — the same invoke pattern `learner` uses for `skill-evaluator`) with the full candidate including the fingerprint. It returns a verdict: `classification`, `cited_evidence[]`, `rationale`, `confidence` (durable only), `disposition`.
+
+**Respect the verdict — do not override it.** Never re-run the judge hoping for a different answer, and never persist anything the judge did not classify `durable-learning`.
+
+## Phase 2 — Route by disposition
+
+All issue/PR comments below follow the marker-dedupe discipline from `lisa-github-write-prd` Phase 2, each with its own producer tag: match on the **marker, never the title or text**; **exactly one marker per body**; **never write a markerless body** (it breaks all future dedupe); include the eventual-consistency guard — when the `gh` search index is stale, also enumerate the bodies directly (`gh issue view <n> --json comments --jq '.comments[].body'` or `gh pr list --json number,body`) and grep for the marker before deciding to create.
+
+### `drop` (classification `one-off` or `misunderstanding/spec-gap`)
+
+Post **one** comment on the triggering issue and write **nothing** — zero bytes — to the learnings surface (not a stub, not a placeholder):
+
+```markdown
+<!-- [lisa-learning-drop] key=<fingerprint> -->
+Dropped (<classification> — <plain-language gloss>): <reason>.
+```
+
+The note is one line naming the classification (with its fixed plain-language gloss) and the reason, readable by a non-technical operator. Use exactly these glosses per class:
+
+| Classification | Gloss |
+|----------------|-------|
+| `one-off` | a one-time fluke, not a recurring pattern |
+| `misunderstanding/spec-gap` | traced to an unclear requirement, not a durable lesson |
+| `lisa-upstream` | root cause is Lisa itself; routed upstream |
+
+(The `lisa-upstream` gloss is used by the handoff note below, not by a drop note.) Dedupe before posting: if any comment on the triggering issue already carries `[lisa-learning-drop] key=<fingerprint>`, do not post again — report the existing note.
+
+### `handoff-upstream` (classification `lisa-upstream`)
+
+Emit the handoff marker only — file **nothing** (no upstream issue, no local rule; the upstream filing flow [SLL-5] consumes this marker later):
+
+```markdown
+<!-- [lisa-learning-upstream-handoff] key=<fingerprint> -->
+Upstream handoff (lisa-upstream — root cause is Lisa itself; routed upstream): <reason>. Nothing persisted locally; upstream filing is a separate flow.
+```
+
+Same one-comment marker dedupe on the triggering issue.
+
+### `persist` (classification `durable-learning`)
+
+Continue to Phase 3.
+
+## Phase 3 — Persist via PR (durable-learning only)
+
+No learning content is ever committed without a PR — there is no other write path, and the PR must touch **only** the learnings surface (any other changed file is a bug).
+
+1. **PR dedupe.** Search all PRs for the marker `[lisa-learning-pr] key=<fingerprint>` in the body (`gh pr list --state all --search '"<marker>" in:body' --json number,url`), with the stale-index guard above. If one exists, reference it and stop — never open a duplicate.
+2. **Resolve the learnings surface path — never hardcode it.** The canonical path is `resolveProjectLearningsFile` from `@codyswann/lisa/learnings`: the `PROJECT_LEARNINGS.md` sibling of the configured `.lisa.config.json` `projectRulesFile` (default `.claude/rules/PROJECT_LEARNINGS.md`):
+
+   ```bash
+   LEARNINGS_FILE=$(node -e 'import("@codyswann/lisa/learnings").then(async m => { const c = await m.readProjectConfig(process.cwd()); console.log(m.resolveProjectLearningsFile(c)); })')
+   ```
+
+3. **Consolidation check (mandatory before writing).** Parse the existing entries (`parseLearningsFile` from `@codyswann/lisa/learnings`) and look for entries related to the new rule (same failure class, overlapping topic, or near-duplicate wording). Then write through the executable contract — **never hand-edit the markdown**:
+   - **Related entry found** → consolidate via `persistConsolidatedLearning(projectRoot, entry, { supersede: [<related ids>] })`, merging the old entry's still-true content into the new rule. Never append a near-duplicate sibling — a sibling is a bug that fails review.
+   - **No related entry** → append via `persistLearningEntry(projectRoot, entry)` and state in the PR body why appending was correct.
+   - Entry mapping: `id` = the fingerprint; `rule`/`why`/`provenance` from the candidate; `first_learned` = `last_confirmed` = today (ISO date; on consolidation keep the superseded entry's earliest `first_learned`); `confidence` = the judge's `high`/`low`. The writer re-asserts the entry and token budgets — an over-budget failure means consolidate harder or drop, never truncate by hand.
+4. **Branch + commit.** Work on branch `learning/<fingerprint>`. Commit only the learnings file; verify with `git diff --name-only` that the diff touches nothing else.
+5. **PR body.** Exactly one marker line plus the reviewable story:
+
+   ```markdown
+   <!-- [lisa-learning-pr] key=<fingerprint> -->
+
+   ## Learning
+   <rule> — <judge rationale>
+
+   ## Provenance
+   - Triggering issue: <ref>
+   - Ancestor issue/PR (the past failure this is round 2 of): <ref or none found>
+   - Rejection comments that produced the candidate: <refs or none>
+   - Cited evidence (from the judge): <refs>
+
+   ## Consolidation decision
+   <"Superseded entry id(s) X, Y: <why they merged>" | "Appended: no related entry exists — <one-line search summary>">
+   ```
+
+   For a **low-confidence** PR, the body must additionally end with this fixed decision-framing line so the human at the gate knows exactly what merging means:
+
+   ```markdown
+   **Merge** to adopt this rule into every future session for all six coding agents; **close** to discard it.
+   ```
+
+6. **Confidence routing.**
+   - **`high`** → submit through `lisa-git-submit-pr` with its defaults: auto-merge ON, merging through the project's normal gates.
+   - **`low`** → submit through `lisa-git-submit-pr` with `auto_merge=false` (drives the PR to green-and-open `awaiting-human`, never merging — even on repos that disallow auto-merge). Then apply the human-triage label, creating it idempotently first (the `lisa-drive-pr-to-merge` label pattern — `|| true` tolerates only already-exists, so verify):
+
+     ```bash
+     gh label create "learning:needs-triage" \
+       --description "Low-confidence learning PR awaiting human triage" \
+       --color FBCA04 || true
+     gh label list --search "learning:needs-triage" --json name \
+       --jq '[.[].name] | contains(["learning:needs-triage"])'   # must print true
+     gh pr edit <pr> --add-label "learning:needs-triage"
+     ```
+
+     A low-confidence PR sitting OPEN with green checks and `autoMergeRequest: null` is this mode's **success** state — a human merges or closes it. All pending low-confidence learning PRs are findable by filtering on the `learning:needs-triage` label (`gh pr list --label "learning:needs-triage"`).
+
+## Rules
+
+- **Headless-safe**: no interactive prompts; must run identically under an intake cron.
+- **Never block the build**: if judging or persistence fails, report the failure and let the primary flow continue — shipping the triggering issue always outranks recording a learning about it.
+- **No learning loops about learning**: never feed this skill a candidate whose triggering artifact is itself learning machinery (a `[lisa-learning-*]`-marked comment, learning PR, or handoff); the judge's Step 0 guard backstops this.
+- **Idempotent**: re-running with the same candidate posts no duplicate comment, opens no duplicate PR, and writes no duplicate entry — the fingerprint and markers guarantee it.
+- **One write path**: the learnings surface changes only through `persistLearningEntry` / `persistConsolidatedLearning` inside a PR. Never hand-edit the file, never commit it to the default branch directly.

package/plugins/lisa/.codex-plugin/skills/lisa-persist-learning/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Persist Learning"
+short_description: "a candidate learning (from a…"
+default_prompt:
+  - "Use $lisa-persist-learning: a candidate learning (from a…."

package/plugins/lisa/agents/learning-judge.md

@@ -0,0 +1,119 @@
+---
+name: learning-judge
+description: Skeptical judgment gate for candidate learnings. Classifies each candidate as durable-learning, one-off, misunderstanding/spec-gap, or lisa-upstream with mandatory evidence citation. Hostile default — most candidates are DROPPED; only durable-learning ever persists. Use whenever a failure signal or debrief produces a claimed learning that something wants to write to the project learnings surface.
+---
+
+# Learning Judge Agent
+
+You are the quality bar between a claimed learning and the project learnings surface. That surface is loaded eagerly in every session by every agent, so a wrong or trivial entry poisons every future session. Your primary responsibility is to **prevent rule pollution** by dropping most candidates.
+
+## Core Philosophy
+
+**Learnings should be rare and provably durable.** Most candidate learnings are wrong — a one-off fluke, a misread requirement, or Lisa's own fault dressed up as project knowledge. Persisting a plausible-but-untrue rule costs every future session; dropping a true-but-minor one costs almost nothing.
+
+- Most candidates DROP.
+- **If in doubt, drop.**
+- Dropping is a valid, successful outcome — not a failure of the gate.
+- You judge the **truth and durability** of a claimed learning, not its plausibility. Plausibility without evidence is a drop.
+
+This gate is independent of (and composes with) `skill-evaluator`: that agent judges whether knowledge is skill-worthy; this agent judges whether a claimed learning is true, caused the failure, and will recur. Callers must respect your verdict — the same contract `learner` holds with `skill-evaluator`: do not override it.
+
+## Candidate Input Schema
+
+Each candidate you evaluate is a single object:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `rule` | string | The proposed learning, phrased as an actionable rule. Must satisfy the executable learnings contract (`LEARNINGS_CONTRACT`: at most 240 characters and 2 lines). An over-cap rule cannot persist — either tighten it as part of judging or drop. |
+| `why` | string | Why the rule allegedly holds — the causal claim to falsify. |
+| `provenance[]` | string[] | Stable refs (issues, PRs, commits, comments) behind the candidate. At most 20 per the contract. |
+| `evidence_links[]` | string[] | Concrete evidence URLs/refs available for citation (failure logs, rejection comments, prior incidents). |
+| `scope_hint` | `project` \| `upstream` | The submitter's guess at where the learning belongs. A hint only — attribution below decides. |
+| `triggering_issue` | string | The issue/work item whose failure produced this candidate. |
+| `fingerprint` | string | Stable dedupe key for this candidate (computed by the caller, e.g. `lisa-persist-learning`). Echo it back unchanged. |
+
+A candidate missing `triggering_issue` or with an empty evidence set can still be evaluated — but it can never reach `durable-learning`, because the mandatory citations below would be impossible.
+
+## Evaluation Process
+
+Work the steps in order; earlier steps short-circuit to a drop or handoff.
+
+### Step 0: No learning loops about learning (short-circuit)
+
+If the triggering issue or its evidence chain is itself part of the learning machinery — a learning-persistence PR, a dropped-with-reason note, an upstream handoff, or anything carrying a `[lisa-learning-*]` marker — the flow must not treat its own output as a failure signal. Classify `one-off`, disposition `drop`, rationale "learning-loop guard".
+
+### Step 1: Attribution (short-circuit to upstream)
+
+Determine what actually caused the failure. If the root cause is a Lisa-shipped template, rule, skill, hook, or workflow — not this project's code or knowledge — classify `lisa-upstream`, disposition `handoff-upstream`. A Lisa defect must be fixed once upstream so every host project benefits; it must **never** become a local rule that papers over the harness. Cite the evidence that pins the cause on Lisa (e.g. the shipped file, the doctor upstream-history attribution). `scope_hint` informs but never decides this step.
+
+### Step 2: Falsification (the evidence requirement)
+
+Only candidates that survive Steps 0–1 continue. Answer both questions, each with **cited** concrete evidence (from `evidence_links`, `provenance`, or your own tracker/repo lookup):
+
+1. **Prevention** — Would this exact rule, had it existed, have prevented the triggering failure? Re-walk the failure with the rule in force. If the failure would have happened anyway, the rule is a superstition: not durable.
+2. **Recurrence** — Does the failure **class** recur? Cite concrete references: a prior issue, PR, revert, rejection comment, or incident showing the same class of mistake on a different occasion. **No recurrence evidence ⇒ never `durable-learning`.** A single occurrence, however painful, is `one-off` — the class may prove itself later, and the candidate can return with evidence.
+
+Do not accept the candidate's own `why` as evidence — it is the claim under test.
+
+### Step 3: Classify (4-way taxonomy)
+
+Exactly one of:
+
+- **`durable-learning`** — both falsification questions pass with cited evidence. The only classification that persists. Disposition `persist`.
+- **`one-off`** — a genuine typo, transient fluke, or single-occurrence mistake with no recurrence evidence. Disposition `drop`.
+- **`misunderstanding/spec-gap`** — the failure traces to an ambiguous or missing requirement, not an agent defect. The fix is a better spec (raise it on the work item), not a rule. Disposition `drop`.
+- **`lisa-upstream`** — set in Step 1. Disposition `handoff-upstream`; never persisted locally.
+
+When multiple classifications seem defensible, choose the one that does **not** persist — the hostile default.
+
+### Step 4: Confidence (durable-learning only)
+
+- **`high`** — the causal story is unambiguous and the recurrence citations are directly on point. The persistence PR may merge through the project's normal gates unattended.
+- **`low`** — durable on the evidence, but the causal chain has an inferential step or the recurrence evidence is indirect. The persistence PR must wait for a human (auto-merge off + triage label).
+
+If you cannot justify `high` in one sentence a non-engineer would accept, it is `low`.
+
+## Verdict Output Schema
+
+Return exactly one verdict object per candidate:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `classification` | `durable-learning` \| `one-off` \| `misunderstanding/spec-gap` \| `lisa-upstream` | The Step 3 outcome. |
+| `cited_evidence[]` | string[] | The concrete refs you actually relied on for this call — prevention and recurrence citations for durable; attribution citations for upstream; the decisive absence/counter-evidence for drops. Never empty. This is what makes a wrong call auditable. |
+| `rationale` | string | 1–3 sentences readable by product, engineering, and QA alike (a non-technical operator stands at the gate). |
+| `confidence` | `high` \| `low` | Present **only** when `classification` is `durable-learning`. |
+| `disposition` | `persist` \| `drop` \| `handoff-upstream` | `persist` iff durable-learning; `handoff-upstream` iff lisa-upstream; otherwise `drop`. |
+
+Also echo back the candidate's `fingerprint` and `triggering_issue` so the caller can route without re-deriving them.
+
+## Output Format
+
+```
+## Learning Judgment
+
+**Candidate**: [rule text]
+**Fingerprint**: [fingerprint]
+**Triggering issue**: [ref]
+
+| Check | Result | Cited evidence |
+|-------|--------|----------------|
+| Learning-loop guard | pass/short-circuit | [refs] |
+| Attribution (Lisa vs project) | project/lisa-upstream | [refs] |
+| Prevention (would the rule have prevented it?) | yes/no | [refs] |
+| Recurrence (does the class recur?) | yes/no | [refs] |
+
+**Classification**: durable-learning | one-off | misunderstanding/spec-gap | lisa-upstream
+**Confidence**: high | low   (durable-learning only)
+**Disposition**: persist | drop | handoff-upstream
+**Rationale**: [1–3 plain-language sentences]
+```
+
+## Important Reminders
+
+1. **Most candidates DROP** — a session where you persist everything you saw is a failed gate, not a productive one.
+2. **No recurrence citation, no durable-learning** — this is absolute; there are no exceptions for "obviously true" rules.
+3. **Cite what you relied on** — a verdict without `cited_evidence` is invalid; re-run the evaluation.
+4. **`lisa-upstream` never becomes a local rule** — classify and hand off; filing the upstream ticket is the caller's flow, not yours.
+5. **You classify; you do not write** — never touch the learnings surface, post comments, or open PRs. The caller (`lisa-persist-learning`) owns all side effects.
+6. **When in doubt, drop** — the surface is a shared, budgeted resource read by every future session.

package/plugins/lisa/commands/persist-learning.md

@@ -0,0 +1,6 @@
+---
+description: "Route a candidate learning through the hostile-default learning-judge gate and act on the verdict: leave a dropped-with-reason note on the triggering issue (drop), emit an upstream handoff marker (lisa-upstream), or persist a durable learning via a confidence-routed PR that touches only the learnings surface — auto-merge on for high confidence, auto-merge off plus the learning:needs-triage label for low confidence. Idempotent via marker dedupe."
+argument-hint: "<candidate-json-or-fields>"
+---
+
+Use the /lisa-persist-learning skill to fingerprint, judge, and route the candidate learning. $ARGUMENTS

package/plugins/lisa/rules/eager/rejection-detection.md

@@ -0,0 +1,40 @@
+# Rejection Detection at Claim Time (load-bearing)
+
+A QA rejection — an item that reached a `review`/`done`-ward state and is now back in the build-ready lane — is a **teaching signal**, not fresh work. Detect it at claim time so the re-claim can reflect on the rejection instead of repeating it.
+
+**One vendor-neutral contract, cited by every build-intake arm** (the `leaf-only-lifecycle` / `repo-scope-split` precedent: one shared slug, never three divergent implementations).
+
+## When it runs
+
+At the **top of build-intake step 3b (Claim), BEFORE the relabel** `$READY → $CLAIMED`. After the relabel the current-lane signal is gone, so detection must read history first. Detection is a pure read — idempotent, headless-safe, no side effects.
+
+## Classify the claimed item
+
+Return exactly one of:
+
+- **`rejection-reclaim`** — history shows the item reached a `review`/`done`-ward lane and is now back in `$READY`.
+- **`forward-only`** — history shows only forward moves (never returned to `$READY` from a later lane).
+- **`never-left-ready`** — history shows the item never left `$READY`.
+- **`unknown`** — the vendor history query failed, was inconclusive, or is absent.
+
+## Vendor history sources (through the access layers only — `integration-access-layer`)
+
+- **GitHub** — `LABELED` / `UNLABELED` timeline events on the configured **ready** label (the Label-Event History surface from `lisa-github-read-issue`).
+- **JIRA** — the `changelog` operation on `lisa-atlassian-access` (`?expand=changelog`, status items).
+- **Linear** — the `history` operation on `lisa-linear-access`, keyed on `status:*` label history (`addedLabelIds`/`removedLabelIds` resolved against `list-issue-labels`).
+
+**Lane names ALWAYS come from `.lisa.config.json` lanes** (`github.labels.build.{ready,claimed,done}` and the JIRA/Linear equivalents; `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS`). **Never hardcode** `status:ready`, `Ready`, etc.
+
+## Never block the build
+
+`unknown` is a first-class result, not an error. A failing/absent history yields `unknown` and **the build proceeds** to implement the item. Detection never stops a claim.
+
+## Learning-loop exclusion (no learning about learning)
+
+An artifact this flow produced is **never** a rejection-reflection trigger, no matter how it moves. Before classifying as `rejection-reclaim`, exclude items carrying any learning marker — `[lisa-learning-drop]`, `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]` — or the `learning:needs-triage` label. Such items short-circuit to `forward-only` (treated as normal work) so the detector never fires on the flow's own learning PRs/issues.
+
+## Reflect on a `rejection-reclaim`
+
+On `rejection-reclaim` only, before re-implementing: read the rejection evidence (comments after the backward transition, review threads on the rejected PR) through the access layers, assemble **one** candidate learning with the rejection linked as provenance, and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate as a comment that carries a **visible prose line** plus the marker (a bare marker renders as an empty comment bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` followed by `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. **Marker-dedupe** on `<issue>-<backward-transition-timestamp>`: re-claiming twice produces no duplicate. Unreadable/absent evidence → proceed without a candidate, never block.
+
+Full contract (classification table, per-vendor bindings, reflection & evidence handoff): [reference/rejection-detection.md](../reference/rejection-detection.md).

package/plugins/lisa/rules/reference/rejection-detection.md

@@ -0,0 +1,103 @@
+# Rejection Detection at Claim Time
+
+When QA rejects an item, it moves the item **backward** — from a `review`/`done`-ward lane back to the build-ready lane — usually with a comment naming the defect. Today the re-claiming agent treats that bounced item as fresh work and repeats the rejected approach. This rule turns the backward move into a detectable, teachable signal.
+
+It is a **single vendor-neutral contract** consumed by all three build-intake skills (`lisa-jira-build-intake`, `lisa-github-build-intake`, `lisa-linear-build-intake`). Each vendor arm cites this slug at its claim step rather than re-implementing detection, exactly as the vendor arms cite `leaf-only-lifecycle` and `repo-scope-split`. That is what keeps a rejection detected on JIRA from being missed on Linear.
+
+## Seam — where detection runs
+
+The three build-intake skills share a uniform claim phase: `3a.0` repo-scope gate → `3a` leaf-only claim gate → `3b` Claim → `3c` run lifecycle (culminating in `lisa-implement`) → `3d` transition to done.
+
+Detection runs at the **top of `3b`, BEFORE the relabel** `$READY → $CLAIMED`. The relabel is what makes the claim idempotent, but it also overwrites the current lane — after it, "the item is currently in `$READY`" is no longer observable, and part of the rejection signal (reached-a-later-lane AND now-back-in-ready) depends on reading the current lane against history. So detection reads history first, classifies, and only then does `3b` perform the relabel.
+
+**`lisa-implement` is NOT the seam** — it never sees the claim. Detection belongs to the build-intake claim phase.
+
+## Classification
+
+Detection is a pure read of the item's transition history (via the vendor access layers). It returns exactly one classification:
+
+| Classification | Condition |
+|---|---|
+| `rejection-reclaim` | History shows the item reached a `review`/`done`-ward lane, then returned to the ready lane; it is now in the ready lane being claimed. |
+| `forward-only` | History shows only forward lane moves — the item never returned to the ready lane from a later lane. |
+| `never-left-ready` | History shows the item never left the ready lane. |
+| `unknown` | The vendor history query failed, was inconclusive, or returned nothing usable. |
+
+Running detection twice on the same item yields the same classification and produces no side effects (idempotent, headless-safe — safe under intake crons with no interactive prompts).
+
+## Vendor history bindings
+
+History is always obtained through the vendor access layer — never a direct vendor API call from a build-intake skill (`integration-access-layer`).
+
+- **GitHub** — read the issue via `lisa-github-read-issue`, whose Label-Event History surface returns chronological `LabeledEvent` / `UnlabeledEvent` entries. A backward move is: the configured **ready** label was removed (item advanced) and later re-added (item bounced back). Non-status label churn is ignored for classification.
+- **JIRA** — call `lisa-atlassian-access operation: changelog key:<K>`. A backward move is a status changelog entry whose `to` is the configured ready status, following an earlier entry that reached a `review`/`done`-ward status.
+- **Linear** — call `lisa-linear-access operation: history id:<ID>`, keyed on `status:*` **label** history (Linear build lanes are label-driven — `lisa-linear-build-intake` keys the queue on `status:*` labels). Resolve `addedLabelIds` / `removedLabelIds` against `list-issue-labels`; a backward move is the configured ready label re-added after a later-lane label was applied. Linear workflow-state moves (`fromState`/`toState`) are a secondary corroborating signal where the project maps lanes to states.
+
+### Lane names are configuration, never literals
+
+The ready / claimed / done lane names ALWAYS come from `.lisa.config.json` lanes:
+
+- `github.labels.build.{ready,claimed,done}` (GitHub),
+- the JIRA status equivalents, and
+- the Linear label equivalents,
+
+resolved per the `config-resolution` rule with the `src/sync/registry.ts` `BUILD_LABEL_DEFAULTS` (`ready: status:ready`, `claimed: status:in-progress`, `done: {dev: status:on-dev, staging: status:on-stg, production: status:done}`) as the fallback. **Never hardcode** a lane string in the detection logic — a project that renames its ready lane must still detect rejections.
+
+## Never block the build
+
+`unknown` is a **first-class result**, not an error. If the history query fails (network, revoked credentials, missing substrate), is inconclusive, or the vendor returns nothing usable, detection returns `unknown` and the build **proceeds** to implement the item normally. Reflection is a bonus signal layered on top of the claim; it never gates it. A history failure, an unreadable history, or an absent history all degrade gracefully to "implement the item anyway".
+
+## Learning-loop exclusion (no learning about learning)
+
+This flow persists learnings via PRs and files upstream issues, so its own artifacts are themselves rejectable. If a learning PR or an auto-filed upstream issue is ever moved backward, a naive detector would fire `rejection-reclaim` on it and reflect on the flow's own output — a learning about learning, recursively.
+
+The trigger is therefore **suppressed at the source**. Before an item is classified `rejection-reclaim`, exclude it if it carries any of the learning producer markers — `[lisa-learning-drop]`, `[lisa-learning-pr]`, `[lisa-learning-upstream-handoff]` (embedded in the artifact body/PR the same way other Lisa markers are) — or the `learning:needs-triage` label. An excluded item is treated as `forward-only` (normal work); the rejection-reflection path never fires on it, no matter how the artifact moved. (These markers ship with the learning-persistence flow; reference them by name — do not assume their files are present in this branch.)
+
+This is the **trigger-side** half of the no-learning-loops guard. The claim-time archaeology path carries the symmetric **scan-side** exclusion ("a learning PR is never treated as an ancestor").
+
+## Reflection at re-claim (`rejection-reclaim` only)
+
+When detection returns `rejection-reclaim`, the build-intake claim phase reflects on the rejection **before re-implementing** — the QA comment describing the defect, the review threads, and any linked failure output are the teaching material. This runs in the `3b`/`3c` claim seam, not in `lisa-implement` (which never sees the claim). On any other classification (`forward-only`, `never-left-ready`, `unknown`) there is nothing to reflect on — proceed to the normal claim.
+
+1. **Read the rejection evidence — through the access layers only** (`integration-access-layer`): the issue/ticket comments posted **after** the backward transition (the QA rejection comment), the review threads on the rejected PR, and any linked failure output. Read via `lisa-github-read-issue` / `lisa-atlassian-access` / `lisa-linear-access` as the vendor dictates — never a direct vendor API call.
+2. **Assemble ONE candidate learning** from that evidence:
+
+   | Field | Content |
+   |---|---|
+   | `rule` | The candidate rule/lesson the rejection teaches. |
+   | `why` | Why it matters — the defect the rejection named. |
+   | `provenance` | The rejection linked as provenance: the issue, the backward transition, the QA comment link, the rejected PR. |
+   | `evidence_links` | The comment / review-thread / failure-output URLs. |
+   | `scope_hint` | Where the learning applies (repo / stack / global). |
+   | `triggering_issue` | The re-claimed item's ref. |
+   | `fingerprint` | `sll4-` + `sha1(<normalized-rule> + "\n" + <triggering_issue>)` truncated to 12 chars (the learning-persistence flow's formula). |
+
+3. **Route the candidate into the judgment gate** via the `lisa-persist-learning` skill (the learning-persistence flow — cite it by name; it ships with that flow, so do not assume its file is present in this branch). Pass the candidate with the rejection as provenance.
+
+### Graceful degrade — `lisa-persist-learning` unavailable
+
+If `lisa-persist-learning` is not installed when reflection runs (e.g. the learning-persistence flow has not merged yet), do **not** fail. Record the candidate as a marked comment on the item and proceed. The comment MUST carry a **visible prose line** as well as the marker — a bare HTML marker renders as an empty comment bubble on GitHub/Linear, defeating the "visible paper trail" this reflection exists to create:
+
+```text
+Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.
+<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->
+```
+
+so a human sees the paper trail, a later run (once the skill exists) can pick it up, and the build still proceeds to implement the item. The marker line is verbatim — the dedupe contract keys on it, not on the prose.
+
+### Idempotency — marker dedupe
+
+The candidate marker key is `<issue>-<backward-transition-timestamp>` (the ISO timestamp of the backward transition that produced the rejection). Reuse the marker-dedupe discipline from `lisa-github-write-prd` Phase 2 — search for an existing candidate carrying this exact key before producing one; **match on the marker, never the title**. Re-claiming the same rejected item twice must **not** produce a duplicate candidate: the second run finds the existing marker and short-circuits. The backward-transition timestamp (not "now") makes the key stable across re-claims of the same rejection.
+
+### Never block the build
+
+Unreadable or absent rejection evidence (no comment, deleted PR) ends with **no candidate produced and the item still implemented** — degraded, not stopped. Reflection is layered on top of the claim; it never gates it.
+
+## Evidence handoff into implementation (`rejection-reclaim` only)
+
+Mining a learning is not enough — if the agent then rebuilds the same rejected thing, the item is re-bounced. So the same rejection evidence read in reflection is **also** handed into the implementation, so the re-implementation consumes it instead of repeating the rejected approach.
+
+- **The handoff is at claim time.** `lisa-implement` never sees the claim and cannot fetch this itself; the build-intake `3c` lifecycle dispatch passes the rejection evidence summary into `lisa-implement` as part of the context bundle. Reuse the evidence already read in the reflection step — do not fetch it twice.
+- **The evidence summary** names: what was rejected, why (the defect the QA comment named), and the specific approach the rejection named as wrong.
+- **The plan must reckon with it.** On a `rejection-reclaim`, the re-implementation plan MUST explicitly address the rejection evidence and MUST NOT re-propose the specific approach the rejection named as wrong.
+- **Absence never blocks.** If the rejection evidence is unreadable or absent, the agent still implements the item — degraded, not stopped.

package/plugins/lisa/skills/lisa-atlassian-access/SKILL.md

@@ -291,7 +291,8 @@ Substrate column meanings:
 | `write-ticket payload:<P>` (create) | guarded fallback only: `acli jira workitem create --from-json <P>` + response tenant assertion | `mcp__plugin_atlassian_atlassian__createJiraIssue` | `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issue` body=`<P>` |
 | `write-ticket payload:<P>` (edit) | guarded fallback only: `acli jira workitem edit <K> --from-json <P>` + response tenant assertion | `mcp__plugin_atlassian_atlassian__editJiraIssue` | `PUT https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issue/<K>` body=`<P>` |
 | `transition key:<K> to:<S>` | guarded fallback only: `acli jira workitem transition --key <K> --status "<S>" --yes` + post-read tenant assertion | `mcp__plugin_atlassian_atlassian__transitionJiraIssue` | resolve transition id then `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issue/<K>/transitions` |
-| `transitions key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getTransitionsForJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>/transitions` |
+| `transitions key:<K>` — **false friend:** available transitions from current status, **NOT** past history; for history use `changelog` | (not exposed) | `mcp__plugin_atlassian_atlassian__getTransitionsForJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>/transitions` |
+| `changelog key:<K>` (read; ordered past status transitions) | (not exposed) | (not exposed) | `GET https://<SITE>/rest/api/3/issue/<K>?expand=changelog` |
 | `comment key:<K> body:<B>` | guarded fallback only: `acli jira workitem comment add --key <K> --body "<B>"` + post-read tenant assertion | `mcp__plugin_atlassian_atlassian__addCommentToJiraIssue` | `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issue/<K>/comment` |
 | `link from:<K> to:<K2> type:<T>` | guarded fallback only: `acli jira workitem link create --in <K> --out <K2> --type "<T>" --yes` + direction and tenant assertion (see direction note) | `mcp__plugin_atlassian_atlassian__createJiraIssueLink` | `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issueLink` |
 | `remote-links key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getJiraIssueRemoteIssueLinks` | `GET https://<SITE>/rest/api/3/issue/<K>/remotelink` |
@@ -338,6 +339,16 @@ Operations not in this table are unsupported — add an adapter row before using
 - `write-page` payload: supports a label-only mutation form — `{ "id": "<I>", "labels": { "add": [...], "remove": [...] } }` — so callers transitioning PRD lifecycle labels do not need to resend the page body. Full create/update payloads also accepted.
 - `comment-page` `kind: inline` requires `anchor` (the highlighted text the comment attaches to). `kind: footer` ignores `anchor`.
 
+### `changelog` — transition history (read-only)
+
+`changelog key:<K>` returns the ordered past status transitions of a JIRA issue — the raw material for rejection detection (an issue that reached `review`/`done`-ward and is now back in `ready`). It is distinct from `transitions`, which is a false friend: `transitions` lists the *available* next transitions from the current status, never past ones. `read-ticket` uses `fields=*all`, which does **not** include the changelog — the expansion must be requested explicitly with `?expand=changelog`.
+
+- **Substrate.** The only substrate that exposes the changelog is JIRA REST via the `?expand=changelog` query parameter (a read, so the `<SITE>` gateway is allowed after the token account check). Neither `acli jira workitem view` (a field-projection tool; the changelog is an `expand`, not a field) nor the Atlassian MCP surfaces a changelog expansion, so both are marked `(not exposed)` — do not invent a separate transport, and do not try to reconstruct history from `transitions`.
+- **Shape.** Walk `changelog.histories[].items[]` and keep entries where `field == "status"`; for each emit `{ from, to, when, author }` — `items[].fromString` → `items[].toString`, `histories[].created` (ISO timestamp), `histories[].author.displayName`/`accountId`. Preserve JIRA's oldest→newest ordering.
+- **Empty is valid.** An issue that never transitioned returns an **empty** history — an empty history is a valid result, not an error. Callers treat empty as "never left its initial status".
+- **Pagination / truncation.** The issue-resource changelog (`?expand=changelog`) truncates busy issues (`changelog.maxResults`/`total`/`startAt`). When `total` exceeds what the issue resource returned, page the dedicated endpoint `GET https://<SITE>/rest/api/3/issue/<K>/changelog?startAt=<n>` until `startAt + maxResults >= total`, preserving order across pages. A silently truncated history is a correctness bug for detection.
+- **Graceful degrade — never block the build.** A failed changelog fetch (network, auth, missing substrate) returns the substrate contract's `Error:` result. Callers MUST treat that as **unknown** history and proceed — a history read failure never blocks the build.
+
 ### Step 4 — Return result
 
 Emit either:

package/plugins/lisa/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -19,17 +19,28 @@ merges" loop. Other skills delegate here instead of re-implementing it. Runs
   `chore(release): X.Y.Z [skip ci]` commits and breaks release promotion detection.
 - `verify_commit=<sha>` — the commit that MUST end up in the merged base (for the
   ancestry check). Default: the PR head at the time this skill starts.
+- `auto_merge=<true|false>` — whether this skill is allowed to merge the PR at
+  all. Default `true` (existing behavior, byte-identical for every current
+  caller). With `auto_merge=false` the PR is deliberately left for a human:
+  skip the **entire** "## 1. Enable auto-merge" step — including its
+  direct-merge capability fallback — and never run any `gh pr merge` variant.
+  Still drive every blocker per `on_blocker` (green checks, resolved reviews,
+  synced branch), then stop at the `awaiting-human` terminal state below. A
+  green, open, un-merged PR is the *success* outcome of this mode, not a hang.
+  Used by learning-persistence flows whose low-confidence PRs must wait for a
+  human (`lisa-persist-learning`).
 - `on_blocker=<fix|report>` — what to do when a blocker needs code or review work.
   Default `fix`.
   - **`fix`** (the full loop): resolve conflicts, fix failing checks, address +
     resolve review comments, dismiss stale review gates — drive until merged.
   - **`report`** (diagnose & mechanically nudge only): perform just the safe,
-    idempotent, non-destructive actions — ensure auto-merge is enabled and, if the
+    idempotent, non-destructive actions — ensure auto-merge is enabled (when
+    `auto_merge=true`) and, if the
     PR is `BEHIND` but otherwise clean, run `gh pr update-branch` only when the
     base branch requires strict up-to-date checks. For **anything** that would
     require editing code, resolving threads, or dismissing a review, **do not
     act** — stop and return a structured blocker classification
-    (`merged` / `will-merge-after-resync` / `blocked:<conflict|checks|changes_requested|deploy>`)
+    (`merged` / `will-merge-after-resync` / `blocked:<conflict|checks|changes_requested|deploy|pending-auto-fix>`)
     so the caller applies its own policy. This is the mode `repair-intake` and the
     build-intake skills use to diagnose-and-route without fixing in place.
 
@@ -75,6 +86,31 @@ releases is why the TTL exists; do not rely on it as the normal release path.
 
 ## 1. Enable auto-merge
 
+**Gate: only when `auto_merge=true` (the default).** When `auto_merge=false`,
+skip the enable step and its capability fallback — do not enable auto-merge,
+and do **not** use the capability fallback below: on a repo that disallows
+auto-merge, an `auto_merge=false` PR must stay OPEN for human triage, never be
+silently direct-merged.
+
+With `auto_merge=false`, also **disarm any pre-existing auto-merge latch**
+before entering the watch loop — skipping the enable step is not enough when a
+prior session (or `lisa-git-submit-pr`'s default path) already armed the PR,
+because an armed latch would still merge the instant checks go green:
+
+```bash
+armed=$(gh pr view <pr> --json autoMergeRequest -q .autoMergeRequest)
+if [ "$armed" != "null" ] && [ -n "$armed" ]; then
+  gh pr merge <pr> --disable-auto
+fi
+gh pr view <pr> --json autoMergeRequest -q .autoMergeRequest   # must print null
+```
+
+If the disarm fails or the re-read still shows an armed `autoMergeRequest`,
+**fail closed**: treat the PR as a hard block (section 4) and report that the
+`awaiting-human` state was NOT reached — never proceed to a state in which the
+PR could merge without a human. Once disarmed (or already unarmed), proceed
+straight to the watch loop (section 2).
+
 Before enabling auto-merge, capture the live PR head and compare it to
 `verify_commit`:
 
@@ -98,9 +134,11 @@ started, then re-enable auto-merge. Do not leave auto-merge armed while a
 required fix, CodeRabbit follow-up, generated artifact update, or CI auto-fix is
 still in flight.
 
-- **Capability fallback**: if the repo disallows auto-merge, do not fail. Keep
-  watching; once checks are green, the review gate is clear, and `mergeable == MERGEABLE`,
-  run `gh pr merge <pr> --<merge_method>` directly.
+- **Capability fallback** (`auto_merge=true` only): if the repo disallows
+  auto-merge, do not fail. Keep watching; once checks are green, the review gate
+  is clear, and `mergeable == MERGEABLE`, run `gh pr merge <pr> --<merge_method>`
+  directly. This fallback lives inside the gated section above — with
+  `auto_merge=false` it never fires; the PR remains open awaiting a human.
 
 ## 2. The watch loop
 
@@ -114,9 +152,17 @@ Handle every blocker class; after any fix, re-poll and continue. Do not stop whi
 the PR is still open and progress is possible. On each iteration, refresh the
 babysitter lease if its last stamp is older than ~30 minutes (section 0).
 
+With **`auto_merge=false`**, the loop's goal changes from "merged" to "clean and
+waiting": drive blockers exactly the same, but exit successfully at
+`awaiting-human` (section 4) once the PR is open with green checks, a clear
+review gate, and `mergeable == MERGEABLE`. Never enable auto-merge or merge
+directly in this mode.
+
 In **`on_blocker=report`** mode, only the mechanical step (a) and auto-merge enabling
-apply; for any of (b)–(e) do not act — classify the blocker and return per the input
-contract above.
+(when `auto_merge=true`) apply; for any of (b)–(f) do not act — classify the blocker
+and return per the input contract above. That includes (f): adjudicating a pending
+auto-fix PR (merging, closing, or deleting its branch) is destructive work, not
+diagnosis — return its classification (`blocked:pending-auto-fix`) instead.
 
 ### a. Branch behind base (`mergeStateStatus == BEHIND`)
 Before proactively syncing a clean `BEHIND` PR, check whether the base branch
@@ -196,7 +242,9 @@ needed, otherwise close it and delete the side branch. Never leave it dangling
 — it represents a competing writer's pending work. Merging it mutates the
 driven branch, so treat it like any other push: disarm auto-merge first,
 re-read `headRefOid`, reset `verify_commit` to the merged head, wait for that
-head's checks to start, then re-enable auto-merge (section 1).
+head's checks to start, then re-enable auto-merge (section 1). In
+`on_blocker=report` mode this whole step is off-limits (diagnose-only): do not
+merge, close, or delete anything — return `blocked:pending-auto-fix`.
 
 ## 3. Merge and verify it actually shipped (ancestry check)
 
@@ -220,6 +268,12 @@ failed drive-to-merge outcome, not a successful closeout.
 Loop until one of:
 
 - **`MERGED`** and the ancestry check passes → success.
+- **`awaiting-human`** (`auto_merge=false` only) → success. The PR is `OPEN`,
+  required checks are green, the review gate is clear, and
+  `mergeable == MERGEABLE`, with auto-merge deliberately not enabled
+  (`gh pr view <pr> --json autoMergeRequest` shows `null`). Report the PR URL
+  and state — a human decides whether it merges. This is the intended outcome
+  of auto-merge-off mode, not a stall; do not keep looping for `MERGED`.
 - **`CLOSED`** → report (PR was closed without merge).
 - **Hard block needing a human**: an unresolvable conflict, a failing check that
   needs design input, or genuine unresolved human objection (not a bot gate). Stop

package/plugins/lisa/skills/lisa-git-submit-pr/SKILL.md

@@ -14,6 +14,7 @@ Recognized optional hints:
 - `target_branch=<branch>` or `base=<branch>` — intended PR base branch, used to decide whether a GitHub closing keyword is safe.
 - `tracker_provider=<github|linear|jira|none>` — explicit provider when the ref shape is ambiguous.
 - `pr_url=<url>` — live pull request URL, only needed when updating tracker backlinks from an existing PR context.
+- `auto_merge=<true|false>` — whether the PR should merge automatically. Default `true` (existing behavior for every current caller). With `auto_merge=false`, skip step 5 entirely (never run `gh pr merge --auto`) and pass `auto_merge=false` through to the `drive-pr-to-merge` delegation in step 6 so the PR is driven to a clean, green, OPEN state and then left awaiting a human.
 
 ## Workflow
 
@@ -34,10 +35,10 @@ Recognized optional hints:
    - Include native development linkage for the source work item when `work_item_ref` can be inferred from `$ARGUMENTS`, the current branch name, an existing PR body, or the issue/ticket context passed by the caller.
    - After the PR exists, ensure the source work item has a backlink to the PR: invoke `lisa-tracker-sync` with the work item, milestone `pr-ready`, the live `pr_url`, and `tracker_provider` when known. This makes ticket -> PR linkage mandatory, not just a best-effort milestone comment.
    - After the PR exists, re-resolve the live Pull Request node id and, when `github.projects.v2` is enabled, invoke `lisa-github-project-v2` with `operation: ensure-item` and `content_node_id: <pull-request-node-id>` so linked pull requests join the configured shared Project without replacing the PR as the durable review/merge surface.
-5. **Auto-merge**: Choose merge strategy by PR type:
+5. **Auto-merge** (only when `auto_merge=true`, the default — with `auto_merge=false` skip this step entirely): Choose merge strategy by PR type:
    - **Promotion PRs** (env → env, e.g. `dev` → `staging`): use `gh pr merge --auto --merge` (never squash). Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into one commit titled with the PR title, stripping the `[skip ci]` markers and breaking the release workflow's promotion-detection regex — the destination branch then double-bumps its version. `--merge` keeps each `chore(release)` commit (and its `[skip ci]` marker) intact under a clean merge commit subject the workflow can recognize.
    - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --merge`.
-6. **Drive to merge**: Opening the PR and enabling auto-merge is not terminal. Delegate the full mergeability loop to the `drive-pr-to-merge` skill — invoke it with the PR number and `merge_method=merge` (and `verify_commit=<pushed head sha>` for the ancestry check). That skill is the single source of truth for clearing every blocker: auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot (CodeRabbit) review-comment handling with GraphQL thread resolution, stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification. It runs inline and uses plain `gh`/`git` so Claude and Codex behave identically. Do not re-implement the loop here.
+6. **Drive to merge**: Opening the PR and enabling auto-merge is not terminal. Delegate the full mergeability loop to the `drive-pr-to-merge` skill — invoke it with the PR number and `merge_method=merge` (and `verify_commit=<pushed head sha>` for the ancestry check). When the caller passed `auto_merge=false`, also pass `auto_merge=false` so the delegated loop drives the PR to green-and-open (`awaiting-human`) instead of merged — never merging it, even on repos that disallow auto-merge. That skill is the single source of truth for clearing every blocker: auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot (CodeRabbit) review-comment handling with GraphQL thread resolution, stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification. It runs inline and uses plain `gh`/`git` so Claude and Codex behave identically. Do not re-implement the loop here.
 
 ### Native Development Linkage