@codyswann/lisa 2.129.5 → 2.129.7

package/plugins/lisa/skills/linear-build-intake/SKILL.md

@@ -203,22 +203,28 @@ Invoke `lisa:linear-agent` (per-Issue lifecycle agent) with the Issue identifier
 - Posting evidence via `lisa:linear-evidence`
 
 Wait for the agent to return. Capture its outcome:
-- **Success** — PR is ready (open or merged); evidence posted; ready for next status.
+- **Success** — the build flow completed and a PR exists; evidence posted. The PR may already be **merged** or still **open** (auto-merge enabled, awaiting checks/merge). "Success" means the build work is sound — it does **not** assert the change reached an environment. The env transition in 3d gates on the PR actually being merged; an open PR does not advance the Issue to a `done` env status.
 - **Blocked by linear-verify pre-flight gate** — `lisa:linear-agent` itself relabels to `status:blocked` and assigns to creator. Let it stand. Record and move on.
 - **Blocked by ticket-triage ambiguities** — agent posts findings and stops. The Issue stays at `$CLAIMED`. Surface to human; do not auto-transition. Record under "Errors".
 - **Errored** — exception, missing config, etc. Leave at `$CLAIMED`. Record with exception summary.
 
-#### 3d. Relabel to $DONE (only on Success)
+#### 3d. Relabel to $DONE (only after the PR is merged)
+
+A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) asserts that the code has actually reached that environment. Never set it for a PR that is merely open: auto-merge can be blocked indefinitely (a required rebase / `BEHIND` branch, failing checks, an unaddressed review), and the change may never land. Relabeling an Issue `status:on-stg` on an open PR makes it *claim* a deploy that never happened. Transition only after confirming the PR merged.
 
 If `lisa:linear-agent` returned Success:
-1. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
-2. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
+1. **Confirm the PR merged.** Read the live state of the Issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before relabeling; a still-running deploy is treated like an open PR (leave at `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the Issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it at `$CLAIMED`, and stop. A later `lisa:repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or change the native state.
+   - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the Issue at `$CLAIMED`.
+2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `linear.labels.build.done` is a string, that string is terminal.
    - If `linear.labels.build.done` is an object, only the production/final environment value is terminal (default: `status:done`). Intermediate env values such as `status:on-dev` and `status:on-stg` are not terminal and must keep the native Issue open.
    - If the project uses a different final environment name, resolve it from the configured deployment topology; if ambiguous, record an Error and do not change the native state.
-3. Update labels via `mcp__linear-server__save_issue`: remove `$CLAIMED` (or `$REVIEW` if `lisa:linear-evidence` already moved it forward), add `$DONE`.
-4. If `$DONE` is terminal, move the native Linear Issue state to the configured Done / Completed state. Resolve that state from project configuration if present; otherwise inspect the team workflow for a terminal state with `state.type = "completed"` and a name such as `Done` or `Completed`. If no terminal state can be resolved, record an Error and leave the labels as the source of truth — do not invent a state name.
-5. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. Transitioned to $DONE."` Include whether native closure was applied, already satisfied, skipped for an intermediate env, or unavailable for setup reasons.
+4. Update labels via `mcp__linear-server__save_issue`: remove `$CLAIMED` (or `$REVIEW` if `lisa:linear-evidence` already moved it forward), add `$DONE`.
+5. If `$DONE` is terminal, move the native Linear Issue state to the configured Done / Completed state. Resolve that state from project configuration if present; otherwise inspect the team workflow for a terminal state with `state.type = "completed"` and a name such as `Done` or `Completed`. If no terminal state can be resolved, record an Error and leave the labels as the source of truth — do not invent a state name.
+6. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL> merged. Transitioned to $DONE."` Include whether native closure was applied, already satisfied, skipped for an intermediate env, or unavailable for setup reasons.
 
 For any non-Success outcome, do NOT transition. The Issue sits where the agent left it — humans take it from there.
 
@@ -236,8 +242,10 @@ Cycle started: <ISO timestamp>
 Cycle completed: <ISO timestamp>
 
 Issues processed: <n>
-- $DONE (build complete, PR ready): <n>
+- $DONE (build complete, PR merged): <n>
   - <ID> <title> → PR <URL>
+- PR open — awaiting merge (left at $CLAIMED for repair-intake): <n>
+  - <ID> <title> → PR <URL> (mergeStateStatus: <state>)
 - Skipped (container — leaf-only-lifecycle): <n>
   - <ID> <title> — build-ready on a parent with open child work; lifecycle-repair comment posted
 - status:blocked (pre-flight verify failed): <n>

package/plugins/lisa/skills/linear-to-tracker/SKILL.md

@@ -233,10 +233,12 @@ Capture each returned story key — Phase 5 needs it as the parent for sub-tasks
 
 **Auto-split cross-repo work before delegation.** For each candidate sub-task, apply `lisa:task-decomposition` step 1.5: if the work touches more than one repo, split it into one sub-task per repo under the same parent Story (e.g., `[backend-api] Add field` + `[mobile-app] Display field`), and encode the producer-before-consumer ordering via dependencies. Work units that may span repos (Epic, Story, Spike) stay as planned; work units that must be single-repo (Bug, Task, Sub-task, Improvement) are split now. Splitting is this skill's responsibility — the validator's S10 gate is `product_relevant: false` because cross-repo failures are decomposition errors caught here, not product questions sent back to the PRD.
 
+**S10 hard gate repair loop.** Dry-run validation is not advisory. Before any Phase 5 write, every planned leaf spec MUST pass `lisa:tracker-validate --spec-only` for S10 Single-repo scope. If any Bug / Task / Sub-task / Improvement fails S10 (missing `Repository`, more than one repo, or cross-repo AC), stop the write path, auto-split or restamp the spec using `lisa:task-decomposition` step 1.5, add the repo bracket and `## Repository` / `h2. Repository` section, then re-run `lisa:tracker-validate --spec-only`. If S10 still fails after repair, abort the ticket write and record an internal Error in the dry-run report; do not create the ticket, do not bypass with direct vendor writes, and do not surface the `product_relevant: false` failure as a product clarification.
+
 Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:tracker-write` for each sub-task — no agent may call `createJiraIssue` directly.**
 
 Each sub-task MUST:
-1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]` and in the description's `## Repository` / `h2. Repository` section
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
 
 **Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa:tracker-write` applies `status:ready` here so downstream build intake (`lisa:tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa:tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
@@ -308,7 +310,7 @@ For each sub-task, invoke `lisa:tracker-write` with:
 - parent: the parent story key
 - project_key: [PROJECT]
 - summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
-- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria)
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo
 - gherkin_acceptance_criteria: derived from the story's functional requirements
 - sign_in_account: [test user credentials from config — name + role + how to obtain]
 - target_environment: "dev"
@@ -317,7 +319,7 @@ For each sub-task, invoke `lisa:tracker-write` with:
   NOT unit tests, linting, or typechecking.
 
 Each sub-task must:
-1. Be scoped to ONE repo only — repo named in brackets in the summary
+1. Be scoped to ONE repo only — repo named in brackets in the summary and in `h2. Repository`
 2. Include the Empirical Verification Plan in the description
 3. Be created via `lisa:tracker-write`, not via direct MCP calls
 

package/plugins/lisa/skills/notion-to-tracker/SKILL.md

@@ -237,10 +237,12 @@ When classification is ambiguous, err on the side of inclusion — a developer c
 
 **Auto-split cross-repo work before delegation.** For each candidate sub-task, apply `lisa:task-decomposition` step 1.5: if the work touches more than one repo, split it into one sub-task per repo under the same parent Story (e.g., `[backend-api] Add field` + `[mobile-app] Display field`), and encode the producer-before-consumer ordering via dependencies. Work units that may span repos (Epic, Story, Spike) stay as planned; work units that must be single-repo (Bug, Task, Sub-task, Improvement) are split now. Splitting is this skill's responsibility — the validator's S10 gate is `product_relevant: false` because cross-repo failures are decomposition errors caught here, not product questions sent back to the PRD.
 
+**S10 hard gate repair loop.** Dry-run validation is not advisory. Before any Phase 5 write, every planned leaf spec MUST pass `lisa:tracker-validate --spec-only` for S10 Single-repo scope. If any Bug / Task / Sub-task / Improvement fails S10 (missing `Repository`, more than one repo, or cross-repo AC), stop the write path, auto-split or restamp the spec using `lisa:task-decomposition` step 1.5, add the repo bracket and `## Repository` / `h2. Repository` section, then re-run `lisa:tracker-validate --spec-only`. If S10 still fails after repair, abort the ticket write and record an internal Error in the dry-run report; do not create the ticket, do not bypass with direct vendor writes, and do not surface the `product_relevant: false` failure as a product clarification.
+
 Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:tracker-write` for each sub-task — no agent may call `createJiraIssue` directly.** This is non-negotiable; see the Agent Prompt Template at the bottom of this skill for the exact instructions to pass.
 
 Each sub-task MUST:
-1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`. `lisa:tracker-write` enforces single-repo scope on Sub-task; cross-repo sub-tasks will be rejected and must be split before delegation.
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]` and in the description's `## Repository` / `h2. Repository` section. `lisa:tracker-write` enforces single-repo scope on Sub-task; cross-repo or unscoped sub-tasks will be rejected and must be split/restamped before delegation.
 2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
 
 **Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa:tracker-write` applies `status:ready` here so downstream build intake (`lisa:tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa:tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
@@ -328,7 +330,7 @@ For each sub-task, invoke `lisa:tracker-write` with:
 - parent: the parent story key
 - project_key: [PROJECT]
 - summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
-- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria)
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria) plus `h2. Repository` naming exactly one repo
 - gherkin_acceptance_criteria: derived from the story's functional requirements
 - sign_in_account: [test user credentials from config — name + role + how to obtain]
 - target_environment: "dev"
@@ -337,7 +339,7 @@ For each sub-task, invoke `lisa:tracker-write` with:
   NOT unit tests, linting, or typechecking.
 
 Each sub-task must:
-1. Be scoped to ONE repo only — repo named in brackets in the summary
+1. Be scoped to ONE repo only — repo named in brackets in the summary and in `h2. Repository`
 2. Include the Empirical Verification Plan in the description
 3. Be created via `lisa:tracker-write`, not via direct MCP calls
 

package/plugins/lisa/skills/repair-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: repair-intake
-description: "Vendor-agnostic repair scanner — the recovery counterpart to lisa:intake. Where intake claims `ready` work, repair-intake finds work that got stuck or was left half-closed: items left in `blocked`, stalled in an in-progress role (build `claimed`, PRD `in_review`), terminal-labeled items that are still natively open, and rollup/container items whose children are all terminal but whose parent is not closed out. Scans the same queues lisa:intake serves (Notion / Confluence / Linear / GitHub PRD databases; JIRA / GitHub / Linear build queues), enumerates candidates up to `max_candidates`, and repairs every materially actionable one in that bounded set: resumes stalled in-progress work IN PLACE (build → the vendor agent + the scanner's post-agent transition; PRD → the source `*-to-tracker` dry-run validate→route pipeline) — but for a stalled build it first diagnoses the PR/deploy state and, if the PR cannot merge (conflict, rebase-required, failing checks, unaddressed CodeRabbit/changes-requested) or a deploy failed, files a build-ready leaf fix ticket and moves the item to `blocked` (blocked by that ticket) rather than re-dispatching, re-validates blocked PRDs when new clarifying answers exist, re-dispatches blocked build items whose `is blocked by` dependencies have since closed, performs terminal native closure for terminal-labeled items, reconciles parent rollups to their derived state per leaf-only-lifecycle — including the intermediate-env case (e.g. all children at `On Stg` → parent `On Stg`) and a container wrongly stuck in `ready` — and closes out rollups whose associated child work is fully terminal. Idempotent, loop-protected via a [lisa-repair-intake] marker + state fingerprint + backoff. Never mutates product-owned states (`draft`, `verified`) and never touches `ready` leaves (a container wrongly carrying `ready` is the one exception — it is rolled up from its children, since `ready` on a parent is an invariant violation, not intake's claim signal). Designed as a /schedule cron target running alongside lisa:intake."
+description: "Vendor-agnostic repair scanner — the recovery counterpart to lisa:intake. Where intake claims `ready` work, repair-intake finds work that got stuck or was left half-closed: items left in `blocked`, stalled in an in-progress role (build `claimed`, PRD `in_review`), terminal-labeled items that are still natively open, and rollup/container items whose children are all terminal but whose parent is not closed out. Scans the same queues lisa:intake serves (Notion / Confluence / Linear / GitHub PRD databases; JIRA / GitHub / Linear build queues), enumerates candidates up to `max_candidates`, and repairs every materially actionable one in that bounded set: resumes stalled in-progress work IN PLACE (build → the vendor agent + the scanner's post-agent transition; PRD → the source `*-to-tracker` dry-run validate→route pipeline) — but for a stalled build it first diagnoses the PR/deploy state: a PR that already merged is recovered by applying the env transition build-intake never got to (no re-dispatch); a PR that is merely behind its base is re-synced in place via `gh pr update-branch` so the already-enabled auto-merge can land (a clean rebase needs no human); and only a PR that cannot merge for a non-mechanical reason (true conflict, failing checks, unaddressed CodeRabbit/changes-requested) or a failed deploy gets a build-ready leaf fix ticket with the item moved to `blocked` (blocked by that ticket) rather than re-dispatching, re-validates blocked PRDs when new clarifying answers exist, re-dispatches blocked build items whose `is blocked by` dependencies have since closed OR whose validation/quality-gate self-block now re-validates PASS (re-running `lisa:tracker-validate` against current content — the build mirror of PRD re-validation), performs terminal native closure for terminal-labeled items, reconciles parent rollups to their derived state per leaf-only-lifecycle — including the intermediate-env case (e.g. all children at `On Stg` → parent `On Stg`) and a container wrongly stuck in `ready` — and closes out rollups whose associated child work is fully terminal. Idempotent, loop-protected via a [lisa-repair-intake] marker + state fingerprint + backoff. Never mutates product-owned states (`draft`, `verified`) and never touches `ready` leaves (a container wrongly carrying `ready` is the one exception — it is rolled up from its children, since `ready` on a parent is an invariant violation, not intake's claim signal). Designed as a /schedule cron target running alongside lisa:intake."
 allowed-tools: ["Skill", "Bash", "Read", "Write", "Edit", "mcp__linear-server__list_teams", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label"]
 ---
 
@@ -15,13 +15,24 @@ close-out** roles and moves work *unstuck* or *fully closed*:
   happening, so it sits ignored forever. (The vendor PRD intakes explicitly leave an errored PRD
   in `in_review` "for the human to investigate from there" — that orphan is exactly what this
   skill recovers.) For a stalled **build**, repair-intake first diagnoses *why* it stalled by
-  inspecting its PRs and deploys: if the PR cannot merge (conflict / rebase-required / failing
-  checks / unaddressed CodeRabbit or `CHANGES_REQUESTED` review) or a deploy failed, it files a
-  build-ready leaf fix ticket and moves the item to `blocked` (blocked by that ticket) instead of
-  blindly re-dispatching the agent — which would just churn against an unmergeable PR.
-- **Recoverable blocked** — an item in `blocked` whose blocker may now be gone: an
-  `is blocked by` dependency has since closed, clarifying questions have been answered, or
-  research/waiting resolves the ambiguity that stopped it.
+  inspecting its PRs and deploys. A PR that **already merged** is recovered by applying the env
+  transition build-intake never got to (its merge gate left the item `claimed` when the merge landed
+  after its agent returned) — no re-dispatch. A PR that is merely **behind its base** (`BEHIND`, no
+  conflict) is **re-synced in place** with `gh pr update-branch` so the already-enabled auto-merge can
+  finally land — a clean rebase needs no human, and leaving it stranded is the exact gap that lets an
+  auto-merge PR sit unmerged forever. Only a PR that cannot merge for a non-mechanical reason (true
+  conflict / failing checks / unaddressed CodeRabbit or `CHANGES_REQUESTED` review) or a failed deploy
+  gets a build-ready leaf fix ticket with the item moved to `blocked` (blocked by that ticket) instead
+  of blindly re-dispatching the agent — which would just churn against an unmergeable PR.
+- **Recoverable blocked** — an item in `blocked` whose blocker may now be gone. The blocker is
+  one of three classes, and repair re-checks **all** of them, not just dependencies: (a) an
+  `is blocked by` **dependency** has since closed; (b) a **validation / quality-gate self-block** —
+  the item was bounced to `blocked` by its own pre-flight `verify`/`validate` gate (missing
+  Validation Journey, Sign-in Required, Acceptance Criteria, etc.) with **no dependency at all**,
+  and a human has since edited the item to add what the gate demanded; or (c) **clarifying
+  questions answered** / an **ambiguity** research can now settle. A self-block (b) is the common
+  one missed by dependency-only re-checks: nothing else is blocking it, so re-running the same gate
+  against its current content is the only way to know it is now passable.
 - **Terminal-open drift** — an item already carrying its true terminal lifecycle role (for
   example GitHub `status:done`) but still open/active in the provider's native state.
 - **Rollup drift** — a parent/container item (Epic, Story, PRD, Linear Project, or equivalent)
@@ -251,14 +262,24 @@ deploys (see "Stuck-cause diagnosis" below). A stalled build usually stalled for
 reason, and re-dispatching the agent at it will not fix a PR that cannot merge or a deploy that
 failed — it just churns.
 
-0. **Diagnose PR & deploy blockers.** If a real external blocker is found (PR cannot merge — merge
-   conflict / rebase-required / failing checks / `CHANGES_REQUESTED` / unaddressed CodeRabbit; or a
-   failed deploy), **do not dispatch the agent**. Instead file a build-ready leaf fix ticket for the
-   blocker, move this item `claimed → blocked` with an `is blocked by` link to that ticket, and
-   record it. The existing "Build `blocked` → unblock if cleared" path resumes this item on a later
-   cycle once the fix ticket is terminal — a self-healing loop. Skip the resume steps below.
-
-If no external blocker is found, the work simply died mid-flight — run the **same per-item sequence
+0. **Diagnose PR & deploy state.** Run "Stuck-cause diagnosis" below. It resolves, in order:
+   - **PR already merged** → the build effectively completed; the vendor build-intake's merge gate
+     left the item `claimed` because the merge landed after its agent returned. Do **not** re-dispatch
+     or file anything — apply the scanner's post-agent env-resolved `claimed → done` transition
+     directly (step 2 below, env-resolved), and record it. This is the recovery arm for build-intake
+     leaving merged-but-unadvanced items in `claimed`.
+   - **PR only behind its base (a needed rebase)** → mechanically resolvable, **not** a human blocker.
+     Re-sync the branch in place so the already-enabled auto-merge can land (see diagnosis step 3).
+     Keep the item `claimed`; a later cycle confirms the merge and transitions. Do **not** file a fix
+     ticket for a clean rebase.
+   - **A real external blocker** (PR cannot merge for a non-mechanical reason — true merge conflict /
+     failing checks / `CHANGES_REQUESTED` / unaddressed CodeRabbit; or a failed deploy) → **do not
+     dispatch the agent**. File a build-ready leaf fix ticket for the blocker, move this item
+     `claimed → blocked` with an `is blocked by` link to that ticket, and record it. The existing
+     "Build `blocked` → unblock if cleared" path resumes this item on a later cycle once the fix
+     ticket is terminal — a self-healing loop. Skip the resume steps below.
+
+If the PR is healthy in-flight and no blocker is found, the work simply died mid-flight — run the **same per-item sequence
 the vendor build-intake runs**, skipping the claim transition (the item is already `claimed`):
 
 1. Dispatch the item to the vendor agent — `lisa:jira-agent` / `lisa:github-agent` /
@@ -287,12 +308,38 @@ external state that resuming the agent cannot fix."
 links and `gh pr list --search <issue-ref>`; JIRA: dev-status / remote links; Linear: attachments
 and git-branch links) and the deploy(s) for the resulting merge (the env-keyed `deploy.branches`
 mapping from `config-resolution`). Read each PR with the vendor's native state, e.g. GitHub
-`gh pr view <n> --json mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,comments,reviews`.
+`gh pr view <n> --json state,mergedAt,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,comments,reviews`.
+
+**2. PR already merged → recover, don't re-dispatch.** If `state == MERGED`, the build is effectively
+complete and the only thing missing is the env transition the build-intake never applied (its merge
+gate left the item `claimed` because the merge landed after its agent returned). Do **not** re-dispatch
+or file anything: apply the scanner's post-agent env-resolved `claimed → done` transition (the
+resume-sequence step 2, env-resolved from the merged PR's base branch) and record it as a repair
+write. Where the env deploy is observable, confirm it did not fail first; a failed post-merge deploy
+falls through to the blocker path (step 4).
+
+**3. PR only behind its base → re-sync in place (mechanical, not a blocker).** If the PR is clean but
+behind its base — `mergeStateStatus == BEHIND` while `mergeable != CONFLICTING` and no required check
+is failing — it does **not** need a human. This is exactly the case that strands a PR forever: GitHub
+auto-merge will not advance a `BEHIND` branch on its own, so a PR opened with `--auto` sits unmerged
+until something rebases it. Re-sync it in place and let the existing auto-merge land it:
+
+```bash
+gh pr update-branch <n>          # rebase/merge the base into the PR head; reruns required checks
+```
 
-**2. Classify as a blocker.** Treat any of these as a real external blocker:
+Record this as a repair write (`resynced`), keep the item `claimed`, and move on — a later cycle sees
+the now-`CLEAN` (or merged) PR and either lets auto-merge finish or applies the merged-PR recovery in
+step 2. Only if `gh pr update-branch` itself reports a conflict it cannot apply does the PR become a
+true conflict (step 4). Honor the backoff window so repeated cycles don't re-issue `update-branch` on
+an unchanged head (Loop prevention). For JIRA/Linear items the PR is still the GitHub PR backing the
+branch — operate on it the same way.
 
-- **Merge conflict / rebase required** — `mergeable = CONFLICTING`, or `mergeStateStatus` in
-  `DIRTY` / `BEHIND`.
+**4. Classify as a blocker.** Treat any of these as a real external blocker:
+
+- **True merge conflict** — `mergeable = CONFLICTING` or `mergeStateStatus = DIRTY` (overlapping
+  changes a plain rebase cannot resolve), or `gh pr update-branch` (step 3) reported a conflict. A
+  merely `BEHIND` branch is **not** here — it was re-synced in step 3.
 - **Failing required checks** — `statusCheckRollup` has a `FAILURE`/`ERROR`/`TIMED_OUT` conclusion,
   or `mergeStateStatus = UNSTABLE`/`BLOCKED` due to checks.
 - **Change requests outstanding** — `reviewDecision = CHANGES_REQUESTED`, or unresolved CodeRabbit
@@ -306,7 +353,7 @@ A check that is still **queued/in progress**, or a `CLEAN`/`HAS_HOOKS` mergeable
 outstanding change request, is **not** a blocker — that is normal in-flight state. (Such a PR with
 recent check/commit activity would already have been caught as `active` by the staleness gate.)
 
-**3. On a blocker found → file a leaf fix ticket + block the item.**
+**5. On a blocker found → file a leaf fix ticket + block the item.**
 
 1. **File one build-ready leaf fix ticket** per distinct blocker via `lisa:tracker-write` (the
    vendor-neutral leaf writer + validation gate; never a vendor `*-write-*` skill directly),
@@ -332,14 +379,31 @@ window and state fingerprint (Loop prevention) so re-runs over the same unchange
 
 ### Build `blocked` → re-evaluate, unblock if cleared
 
-1. Read the block reason and dependencies (see Dependency clearing).
-2. If every parsed blocker is **cleared** → move `blocked → claimed`, then run the same
-   agent-dispatch + post-agent `claimed → done` sequence as the stalled-`claimed` path above
-   (one-cycle recovery). If the agent re-blocks, move back to `blocked` — a valid outcome.
-3. If the block was an **ambiguity** research can settle and no dependency remains → run the
+1. Read the block reason and classify the blocker (see Blocker classification & clearing). An item
+   may be held by a **dependency**, by a **validation / quality-gate self-block**, by an
+   **ambiguity**, or by more than one at once. Re-check **every** class present — do not stop at
+   "no `is blocked by` links, therefore nothing to do." A self-block has zero dependencies by
+   definition, yet is fully re-checkable.
+2. **Dependency cleared** — if every parsed `is blocked by` dependency is **cleared** → move
+   `blocked → claimed`, then run the same agent-dispatch + post-agent `claimed → done` sequence as
+   the stalled-`claimed` path above (one-cycle recovery). If the agent re-blocks, move back to
+   `blocked` — a valid outcome.
+3. **Validation / quality-gate self-block re-check** — if the block reason is a pre-flight
+   `verify`/`validate` gate failure (its `[lisa-*]` block note carries a gate marker + a "Missing
+   requirements" list and there is **no** open `is blocked by` dependency), re-run the **same gate**
+   against the item's **current** content via `lisa:tracker-validate` (read-only; the vendor-neutral
+   gate `lisa:<tracker>-build-intake` and `lisa:<tracker>-write-*` already use). This is the build
+   mirror of the PRD `blocked → re-validate` path below.
+   - **PASS now** (the human added what was missing) → move `blocked → claimed` and resume exactly
+     as in (2): agent-dispatch + post-agent `claimed → done`.
+   - **Still FAIL** → stay `blocked`, but refresh the note with the **current** (usually smaller)
+     missing-requirement set so the human sees what remains. Because the fingerprint includes the
+     gate verdict + missing-requirement set (Loop prevention), a partial human fix changes the
+     fingerprint and re-checks next cycle, while a truly-unchanged gate result stays in backoff.
+4. If the block was an **ambiguity** research can settle and no dependency remains → run the
    research needed (`lisa:codebase-research` / `lisa:product-walkthrough`); if resolved, proceed
    as in (2).
-4. Else → still blocked. Refresh the note with the current reason (Loop prevention) and leave it
+5. Else → still blocked. Refresh the note with the current reason (Loop prevention) and leave it
    `blocked`.
 
 ### Build terminal-open → native close / complete / resolve
@@ -460,7 +524,13 @@ work is fully terminal:
 5. If generated work is missing, ambiguous, or partially incomplete, leave the PRD open and report
    the incomplete child set. Never close a PRD on partial completion.
 
-## Dependency clearing (conservative, vendor-specific extraction)
+## Blocker classification & clearing (conservative, vendor-specific extraction)
+
+A `blocked` build item is held by one or more of three blocker classes. Identify which are present
+from the item's block note(s) and links, then clear-check **each present class** — an item with no
+dependency is not automatically un-actionable; it may be a self-block that now passes.
+
+### Class A — dependency blockers
 
 `lisa:tracker-read` is a thin dispatcher that returns each vendor's bundle **verbatim** — there
 is no normalized `is blocked by` field. Read the bundle, then extract blockers per vendor:
@@ -485,6 +555,38 @@ Only re-dispatch when **every** parsed blocker is cleared. When in doubt, stay b
 false-negative (left blocked) is cheap; a false-positive (re-dispatched into a real blocker)
 wastes a build cycle.
 
+### Class B — validation / quality-gate self-block
+
+A self-block has **no** `is blocked by` dependency: the build-intake/agent flow claimed the item,
+its pre-flight `verify`/`validate` gate failed (missing Validation Journey, Sign-in Required,
+Target Backend Environment, Repository, Out of Scope, Evidence manifest, weak Acceptance Criteria,
+etc.), and the item was bounced to `blocked` carrying that gate's `[lisa-*]` note + "Missing
+requirements" list. Detect it by: (1) the block note bears a known gate marker (e.g.
+`Pre-flight verify gate: BLOCKED`, `jira-verify` / `*-validate-*`), **and** (2) there is no open
+`is blocked by` dependency. (If both a dependency and a self-block are present, clear the
+dependency via Class A first; the self-block re-check still gates the eventual re-dispatch.)
+
+Clear-check by **re-running the same gate against current content** — `lisa:tracker-validate`
+(read-only; never writes), which dispatches to `lisa:<tracker>-validate-*` exactly as the write
+path and build-intake do, so the bar cannot drift:
+
+- **PASS** → cleared. Proceed to re-dispatch (decision tree step 2).
+- **FAIL** → still self-blocked. Refresh the note with the current missing set (Loop prevention).
+
+Conservative, same as Class A: a still-failing gate is a real blocker — never re-dispatch a build
+whose own gate has not yet passed. This is intentionally symmetric with the PRD `blocked →
+re-validate` path: PRDs re-run their dry-run `validate→route` when source content changes; builds
+re-run `tracker-validate` when item content changes. The asymmetry where build `blocked` checked
+only dependencies — leaving verify-gate self-blocks stranded forever after a human filled in the
+missing sections — is the gap this class closes.
+
+### Class C — ambiguity / clarifying answers
+
+A block that research or a human answer can settle (no dependency, no failing gate). Re-check by
+running the needed research (`lisa:codebase-research` / `lisa:product-walkthrough`) or detecting a
+human comment/edit newer than the last `[lisa-repair-intake]` note. Resolved → proceed to
+re-dispatch; else stay blocked.
+
 ## Loop prevention
 
 A `blocked` item with a permanently unresolved problem must not be "repaired" and re-noted every
@@ -492,7 +594,10 @@ cron tick.
 
 - Every note this skill writes is prefixed `[lisa-repair-intake]` and carries a compact **state
   fingerprint**: the lifecycle role, the set of blocker refs + their observed states, the
-  validation verdict (PASS/FAIL), terminal/open state, rollup child tally, and a timestamp.
+  validation verdict (PASS/FAIL) **plus the current missing-requirement set for a Class-B
+  self-block** (so a human filling in one of several missing sections changes the fingerprint and
+  triggers a re-check next cycle, rather than being suppressed as a no-op), terminal/open state,
+  rollup child tally, and a timestamp.
 - Before writing a note or re-attempting a `blocked` item, compute the current fingerprint. If
   an identical fingerprint was already posted within the **backoff window**, skip the item
   silently (record as `still_blocked` / `active`, no write).
@@ -548,8 +653,10 @@ It MUST NOT:
       containers, that need their derived state applied (status-only reconciliation, no native
       close),
    4. `blocked` items whose dependencies are now **cleared** (safe, high-value, one-cycle wins),
-   5. `blocked` items with **new clarifying answers**,
-   6. **stalled** in-progress items, oldest activity first.
+   5. `blocked` items whose **validation / quality-gate self-block now re-validates PASS** —
+      a human filled in the missing sections (Class B; equally safe and high-value),
+   6. `blocked` items with **new clarifying answers**,
+   7. **stalled** in-progress items, oldest activity first.
 4. **Walk the ordered list**, evaluating each candidate (terminal close-out, rollup child tally,
    staleness, dependency, answer checks), and repair **every** candidate that is actionable inside
    the `max_candidates` cap. Continue after successful writes and after per-item errors.
@@ -568,6 +675,11 @@ often consists of cheap close-out reconciliation that should drain in one cron p
 Report outcomes in these buckets:
 
 - `resumed` — stalled in-progress work re-dispatched in place.
+- `resynced` — a stalled build whose PR was merely behind its base, re-synced via
+  `gh pr update-branch` so the already-enabled auto-merge can land; the item stays `claimed` for a
+  later cycle to confirm the merge and transition.
+- `recovered` — a stalled build whose PR had already merged, advanced by applying the env-resolved
+  `claimed → done` transition build-intake never got to (no re-dispatch).
 - `unblocked` — blocker cleared (or answers resolved); re-dispatched or transitioned to
   `ticketed`.
 - `closed_out` — terminal-labeled items whose native open/active state was closed, completed,
@@ -606,6 +718,10 @@ stuck work accumulates), or interleaved on a longer cadence.
   child work is terminal.
 - Apply build `done` ONLY via the env-resolution rules, and trigger native closure only at the
   true terminal `done` value (`leaf-only-lifecycle`).
+- A `blocked` build item's blocker may be a dependency, a validation/quality-gate self-block (no
+  dependency — re-check by re-running `lisa:tracker-validate` against current content), or an
+  ambiguity. Re-check every class present; do not treat "no `is blocked by` links" as "nothing to
+  do."
 - Never re-dispatch a `blocked` build item unless every parsed blocker is cleared (conservative
   dependency clearing).
 - Repair every materially actionable candidate inside the `max_candidates` cap; default cap is 100.

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.129.5",
+  "version": "2.129.7",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -217,6 +217,36 @@ fi
 
 If validation fails, never silently proceed — abort and instruct the user to fix env.
 
+### Step 2.5 — JIRA description normalization
+
+For `write-ticket` create/edit operations, normalize any Lisa-authored JIRA description before dispatching to a substrate. JIRA Cloud stores descriptions as Atlassian Document Format (ADF). `acli` does not convert Markdown or JIRA wiki markup to ADF; if plain text is passed to `--description` / `--description-file`, JIRA stores one literal paragraph containing strings like `## Repository` or `h2. Repository`. That breaks `jira-validate-ticket` heading checks and renders poorly for humans.
+
+Use the shared converter at `scripts/markdown-to-adf.mjs` from this skill for every write path that carries a string description:
+
+```bash
+normalize_jira_description_payload() {
+  local payload_file="$1"
+  local converter="$(dirname "$0")/scripts/markdown-to-adf.mjs"
+
+  jq -e '.fields.description | type == "string"' "$payload_file" >/dev/null 2>&1 || return 0
+
+  local markdown_file adf_file
+  markdown_file=$(mktemp)
+  adf_file=$(mktemp)
+  jq -r '.fields.description' "$payload_file" > "$markdown_file"
+  node "$converter" < "$markdown_file" > "$adf_file"
+  jq --slurpfile adf "$adf_file" '.fields.description = $adf[0]' "$payload_file" > "$payload_file.tmp"
+  mv "$payload_file.tmp" "$payload_file"
+}
+```
+
+Rules:
+
+- Convert Markdown headings (`#` / `##` / `###`) and JIRA wiki headings (`h1.` / `h2.` / `h3.`) to ADF `heading` nodes.
+- Convert fenced code blocks, bullet lists, numbered lists, paragraphs, inline code, and bold text to their ADF equivalents.
+- Run this for acli, curl, and MCP writes unless the caller already supplied an ADF object (`description.type == "doc"`). Do not double-convert existing ADF.
+- For acli, pass the normalized JSON through `--from-json`; do not use `--description` or `--description-file` with raw Markdown/wiki text.
+
 ### Step 3 — Operation dispatch
 
 Substrate column meanings:
@@ -232,7 +262,7 @@ Substrate column meanings:
 | Operation | acli adapter | MCP adapter | curl adapter |
 |---|---|---|---|
 | **JIRA ops** | | | |
-| `read-ticket key:<K>` | `acli jira workitem view <K> --json` | `mcp__plugin_atlassian_atlassian__getJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>` |
+| `read-ticket key:<K>` | `acli jira workitem view <K> --fields '*all' --json` | `mcp__plugin_atlassian_atlassian__getJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>?fields=*all` |
 | `write-ticket payload:<P>` (create) | `acli jira workitem create --from-json <P>` | `mcp__plugin_atlassian_atlassian__createJiraIssue` | `POST https://<SITE>/rest/api/3/issue` body=`<P>` |
 | `write-ticket payload:<P>` (edit) | `acli jira workitem edit <K> --from-json <P>` | `mcp__plugin_atlassian_atlassian__editJiraIssue` | `PUT https://<SITE>/rest/api/3/issue/<K>` body=`<P>` |
 | `transition key:<K> to:<S>` | `acli jira workitem transition --key <K> --status "<S>" --yes` | `mcp__plugin_atlassian_atlassian__transitionJiraIssue` | resolve transition id then `POST .../issue/<K>/transitions` |
@@ -259,7 +289,7 @@ Substrate column meanings:
 
 **Confluence v1 vs v2:** every Confluence curl path above uses **v1** (`/wiki/rest/api/...`). v1 is deprecated by Atlassian but as of writing remains functional for API-token Basic auth. The v2 API (`/api/v2/...`) requires *granular* OAuth scopes that aren't issued to Basic-auth API tokens consistently — so v1 is the safer path for now. When Atlassian fully retires v1, this table must move to v2 (the dispatch is the only thing that changes; the substrate-selection logic is unaffected).
 
-**acli flag note:** acli's `--output` flag does not exist; the correct flag is `--json`. List commands require `--paginate` or `--limit` (no implicit fetch-all). Several documented adapters are nominal — verify against `acli <subcmd> --help` before relying on them. When acli's adapter is broken or missing for a specific op, fall through to MCP (if identity-matched) then curl per the tier ordering.
+**acli flag note:** acli's `--output` flag does not exist; the correct flag is `--json`. List commands require `--paginate` or `--limit` (no implicit fetch-all). `acli jira workitem view` defaults to a restricted field set (`key,issuetype,summary,status,assignee,description`), so `read-ticket` MUST pass `--fields '*all'` or an explicit equivalent that includes every downstream dependency: parent, subtasks, issue links, components, labels, priority, status, issue type, summary, description, fix versions, affected versions, attachments, comments, estimates, sprint/story-point fields, and project-required custom fields. Never rely on the default view fields; they hide parent/components/labels and corrupt leaf-only, relationship-search, build-ready, and required-custom-field gates. Several documented adapters are nominal — verify against `acli <subcmd> --help` before relying on them. When acli's adapter is broken or missing for a specific op, fall through to MCP (if identity-matched) then curl per the tier ordering.
 
 **JIRA terminal-resolution note:** when a caller marks a transition as terminal per `leaf-only-lifecycle`, the substrate must not treat a Done-named status as sufficient by name alone. After `transition key:<K> to:<S>`, re-read the issue and verify `statusCategory = Done`; if the workflow requires a resolution, verify `resolution` is set. If the transition screen requires a resolution value, pass the configured default resolution when available; otherwise return a setup error so the build-intake skill can report the workflow gap instead of silently leaving an unresolved ticket in a Done-looking status.