@codyswann/lisa 2.237.0 → 2.239.0

package/plugins/lisa-cursor/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-cursor/commands/lisa/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-cursor/rules/rejection-detection-reference.mdc

@@ -0,0 +1,108 @@
+---
+description: "Rejection Detection at Claim Time"
+alwaysApply: false
+---
+
+# 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-cursor/rules/rejection-detection.mdc

@@ -0,0 +1,45 @@
+---
+description: "Rejection Detection at Claim Time (load-bearing)"
+alwaysApply: true
+---
+
+# 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](rejection-detection-reference.mdc).

package/plugins/lisa-cursor/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-cursor/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-cursor/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
 

package/plugins/lisa-cursor/skills/lisa-github-build-intake/SKILL.md

@@ -252,6 +252,10 @@ A blocker is active if it is open and has no cleared status label. Treat `status
 
 #### 3b. Claim
 
+**Rejection detection runs first — before the relabel below.** Per the vendor-neutral `rejection-detection` rule (cite the slug; do not restate its classification table), classify this item at the **top of 3b, BEFORE** the `$READY → $CLAIMED` relabel — after the relabel the current-lane signal is gone. Read the item's Label-Event History from `lisa-github-read-issue` (chronological `LabeledEvent` / `UnlabeledEvent` on the configured `$READY` label) and classify it `rejection-reclaim | forward-only | never-left-ready | unknown`. Lane names come from `.lisa.config.json` (`github.labels.build.*`), never hardcoded. A failing/absent history yields `unknown` and the claim proceeds — detection never blocks the build. Items carrying a learning marker (`[lisa-learning-drop]` / `[lisa-learning-pr]` / `[lisa-learning-upstream-handoff]`) or the `learning:needs-triage` label are never rejection triggers (no learning-about-learning). Carry the classification into the relabel and lifecycle below.
+
+**On `rejection-reclaim`, reflect before re-implementing** (per `rejection-detection`): read the rejection evidence through the access layer — the issue comments posted after the backward transition (the QA rejection comment) and the review threads on the rejected PR via `lisa-github-read-issue` — assemble ONE candidate learning (rule, why, provenance linking the rejection comment + rejected PR, evidence links, scope hint, triggering issue, fingerprint `sll4-sha1(rule\ntriggering_issue)[:12]`), and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate as a comment carrying a **visible prose line plus** the marker (a bare marker renders as an empty bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` then `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. Dedupe on `<issue>-<backward-transition-timestamp>` — a second re-claim produces no duplicate. Unreadable/absent evidence → no candidate, still implement.
+
 ```bash
 gh issue edit <number> --repo <org>/<repo> --remove-label "$READY" --add-label "$CLAIMED"
 # Assign to the authenticated user ONLY when the issue is currently unassigned (attributable claim;
@@ -274,7 +278,7 @@ After the claim succeeds, run the per-issue lifecycle defined by the `github-age
    - `lisa-github-verify` — pre-flight quality gate, including the draft-then-block procedure on FAIL
    - `lisa-ticket-triage` — analytical triage gate (a `BLOCKED` verdict stops the cycle with findings posted)
    - Intent determination from the `type:` label
-2. **Dispatch the flow in-session:** when the gates pass, invoke the lifecycle skill via the Skill tool — `lisa-implement <org>/<repo>#<number>` for Build / Fix / Improve / Investigate-Only (or `lisa-plan` for an Epic) — passing the full context bundle from the read step. `lisa-implement`'s own orchestration preamble then creates the per-item agent team (input-resolver, Roster Decision, specialist fanout) exactly as a direct invocation would.
+2. **Dispatch the flow in-session:** when the gates pass, invoke the lifecycle skill via the Skill tool — `lisa-implement <org>/<repo>#<number>` for Build / Fix / Improve / Investigate-Only (or `lisa-plan` for an Epic) — passing the full context bundle from the read step. **When 3b classified this item `rejection-reclaim`, the context bundle passed to `lisa-implement` MUST include the rejection evidence summary** (what was rejected, the defect the QA comment named, the approach named as wrong) — reuse the evidence already read in 3b, do not fetch it twice — so the plan can address it per `rejection-detection`; absence of evidence never blocks. `lisa-implement`'s own orchestration preamble then creates the per-item agent team (input-resolver, Roster Decision, specialist fanout) exactly as a direct invocation would.
 3. **Milestone sync and evidence** (`lisa-github-sync`, `lisa-github-evidence`) happen at the milestones the `github-agent` workflow defines, within the dispatched flow.
 
 If you are somehow running this skill as a spawned teammate inside an existing team (nested misrouting — Intake keeps this chain in the lead session), do NOT run the lifecycle inline and do NOT spawn named peers. Return this payload to the lead so the lead session can run this Phase 3c in-session:

package/plugins/lisa-cursor/skills/lisa-implement/SKILL.md

@@ -49,6 +49,8 @@ The team lead does NOT read the input directly. The first task on the team's pla
 
 The input resolver is the only teammate that may be spawned before the Roster Decision exists. After it returns the resolved input, do not spawn any lifecycle, research, implementation, review, verification, or learning teammate until the Roster Decision has been recorded.
 
+**Rejection evidence in the claim handoff.** When this flow was dispatched from a build-intake claim that classified the item as a `rejection-reclaim` (per the `rejection-detection` rule), the context bundle carries a **rejection evidence summary** (what was rejected, the defect the QA comment named, the approach named as wrong). The plan MUST explicitly address that rejection evidence and MUST NOT re-propose the specific approach the rejection named as wrong — a bounced item must come back fixed, not re-bounced. `lisa-implement` cannot fetch this itself (it never sees the claim); it consumes what the handoff carries. Absence of rejection evidence never blocks — plan and implement normally.
+
 ## Select the agent roster
 
 Before spawning any teammate beyond the bounded input resolver, record a **Roster Decision** artifact. It must enumerate every agent or specialist type exposed by the current runtime's delegation tool and record one line per type:

package/plugins/lisa-cursor/skills/lisa-jira-build-intake/SKILL.md

@@ -196,6 +196,10 @@ This gate never blocks a legitimate flat Task/Bug: those have no open children a
 
 #### 3b. Claim
 
+**Rejection detection runs first — before the transition below.** Per the vendor-neutral `rejection-detection` rule (cite the slug; do not restate its classification table), classify this ticket at the **top of 3b, BEFORE** the `$READY → $CLAIMED` transition — after the transition the current-status signal is gone. Read the ticket's status changelog via `lisa-atlassian-access operation: changelog key: <TICKET>` and classify it `rejection-reclaim | forward-only | never-left-ready | unknown` (a `rejection-reclaim` is a changelog entry whose `to` is the configured `$READY` status following an earlier `review`/`done`-ward status). Status names come from `.lisa.config.json`, never hardcoded. A failing/absent changelog yields `unknown` and the claim proceeds — detection never blocks the build. Tickets carrying a learning marker (`[lisa-learning-drop]` / `[lisa-learning-pr]` / `[lisa-learning-upstream-handoff]`) or the `learning:needs-triage` label are never rejection triggers (no learning-about-learning). Carry the classification into the transition and lifecycle below.
+
+**On `rejection-reclaim`, reflect before re-implementing** (per `rejection-detection`): read the rejection evidence through the access layer — the ticket comments posted after the backward transition (the QA rejection comment) via `lisa-atlassian-access operation: read-ticket` / `comment` reads and the review threads on the rejected PR — assemble ONE candidate learning (rule, why, provenance linking the rejection comment + rejected PR, evidence links, scope hint, triggering issue, fingerprint `sll4-sha1(rule\ntriggering_issue)[:12]`), and route it to the `lisa-persist-learning` skill. If that skill is absent, record the candidate via `lisa-atlassian-access operation: comment` as a comment carrying a **visible prose line plus** the marker (a bare marker renders as an empty bubble) — `Recorded a candidate learning from this rejection (queued for the judgment gate): <one-line candidate rule>.` then `<!-- [lisa-rejection-candidate] key=<issue>-<transition-ts> -->` — and proceed. Dedupe on `<issue>-<backward-transition-timestamp>` — a second re-claim produces no duplicate. Unreadable/absent evidence → no candidate, still implement.
+
 Transition the ticket from `$READY` to `$CLAIMED` by invoking `lisa-atlassian-access` `operation: transition key: <TICKET> to: "$CLAIMED"`.
 - **Assign to the authenticated user when the ticket is unassigned.** A claim must be attributable. If the ticket has no assignee, assign it to the authenticated account — prefer acli `--assignee @me` (resolves server-side to the authenticated user, which avoids the federated-`accountId` mis-assignment), or `write-ticket` with the `accountId` from the `/rest/api/3/myself` identity probe the access skill already documents. Leave an already-assigned ticket's assignee untouched — never reassign work that already has an owner.
 - Post a `[claude-build-intake]` comment via `lisa-atlassian-access` `operation: comment key: <TICKET> body: "Claimed by Claude. Starting build."`
@@ -212,7 +216,7 @@ After the claim succeeds, run the per-ticket lifecycle defined by the `jira-agen
    - `lisa-jira-verify` — pre-flight quality gate, including the draft-then-block procedure on FAIL
    - `lisa-ticket-triage` — analytical triage gate (a `BLOCKED` verdict stops the cycle with findings posted)
    - Intent determination from the issue type
-2. **Dispatch the flow in-session:** when the gates pass, invoke the lifecycle skill via the Skill tool — `lisa-implement <TICKET>` for Build / Fix / Improve / Investigate-Only (or `lisa-plan` for an Epic) — passing the full context bundle from the read step. `lisa-implement`'s own orchestration preamble then creates the per-item agent team (input-resolver, Roster Decision, specialist fanout) exactly as a direct invocation would.
+2. **Dispatch the flow in-session:** when the gates pass, invoke the lifecycle skill via the Skill tool — `lisa-implement <TICKET>` for Build / Fix / Improve / Investigate-Only (or `lisa-plan` for an Epic) — passing the full context bundle from the read step. **When 3b classified this ticket `rejection-reclaim`, the context bundle passed to `lisa-implement` MUST include the rejection evidence summary** (what was rejected, the defect the QA comment named, the approach named as wrong) — reuse the evidence already read in 3b, do not fetch it twice — so the plan can address it per `rejection-detection`; absence of evidence never blocks. `lisa-implement`'s own orchestration preamble then creates the per-item agent team (input-resolver, Roster Decision, specialist fanout) exactly as a direct invocation would.
 3. **Milestone sync and evidence** (`lisa-jira-sync`, `lisa-jira-evidence`) happen at the milestones the `jira-agent` workflow defines, within the dispatched flow.
 
 If you are somehow running this skill as a spawned teammate inside an existing team (nested misrouting — Intake keeps this chain in the lead session), do NOT run the lifecycle inline and do NOT spawn named peers. Return this payload to the lead so the lead session can run this Phase 3c in-session:

package/plugins/lisa-cursor/skills/lisa-linear-access/SKILL.md

@@ -23,6 +23,7 @@ operation: get-issue id:<ID>
 operation: save-issue payload:{...}
 operation: list-comments issue_id:<ID>
 operation: save-comment issue_id:<ID> body:"..."
+operation: history id:<ID>
 operation: list-issue-labels [team:<ID>]
 operation: create-issue-label payload:{...}
 operation: list-project-labels
@@ -81,6 +82,59 @@ linear_graphql() {
 Map operation names to Linear GraphQL queries/mutations in this access skill.
 Consumers pass business-shaped arguments only; they do not embed GraphQL.
 
+## `history` — transition history (read-only)
+
+`history id:<ID>` returns an Issue's ordered past state changes — the raw
+material for rejection detection (an Issue that reached a `review`/`done`-ward
+state and is now back in `ready`). `IssueHistory` is reachable today through the
+existing `linear_graphql` adapter but was **not** in the documented contract; an
+undocumented-but-reachable capability is not exposed, so it now appears in the
+Invocation Contract above. Reuse the existing adapter — this is a
+contract/surface change, not a new transport (the `integration-access-layer`
+rule forbids consumers from reaching around the layer).
+
+Query through `linear_graphql` (oldest→newest; page `history(first:…, after:…)`
+via `pageInfo` for busy Issues so history never silently truncates):
+
+```graphql
+query($id:String!){
+  issue(id:$id){
+    history(first:100){
+      pageInfo{hasNextPage endCursor}
+      nodes{
+        createdAt
+        fromState{name type}
+        toState{name type}
+        actor{name}
+        addedLabelIds
+        removedLabelIds
+      }
+    }
+  }
+}
+```
+
+- **Shape.** For each node emit `{ from, to, when, who }` — `fromState.name` →
+  `toState.name`, `createdAt` (ISO timestamp), `actor.name`. Nodes with no
+  `fromState`/`toState` are non-state edits (label-only, assignee, etc.); keep
+  them for the label stream, skip them for workflow-state ordering.
+- **Label history (honest caveat).** Linear's build lanes are **label-driven**
+  (`lisa-linear-build-intake` keys the queue on `status:*` labels), so label
+  moves matter as much as workflow-state moves. `IssueHistory` carries label
+  changes as `addedLabelIds` / `removedLabelIds` — arrays of label **IDs**, not
+  names. It does **not** inline label names, and it does not carry the label's
+  full prior/next set — only the per-event deltas. Resolve IDs → names by
+  cross-referencing `list-issue-labels`. Do not overclaim: a caller that needs
+  `status:*` label transitions reconstructs them from the ID deltas plus the
+  label catalog, not from an inline name on the history node.
+- **Empty is valid.** An Issue that never changed state returns an **empty**
+  history — an empty history is a valid result, not an error.
+- **Graceful degrade — never block the build.** A failed history fetch returns
+  the layer's `Error:` result. Callers MUST treat that as **unknown** history
+  and proceed — a history read failure never blocks the build. MCP cannot reach
+  `IssueHistory`, so the `history` operation resolves only through the
+  `LINEAR_API_KEY` GraphQL substrate; without it, the result is unknown.
+
 ## Invariants
 
 - MCP is preferred when it is present and already authenticated.