@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-devin/skills/lisa-jira-read-ticket/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: lisa-jira-read-ticket
+description: "Fetches the full scope of a JIRA ticket — metadata, description, acceptance criteria, all comments, remote links (PRs, Confluence, dashboards), issue links (blocks/is blocked by/relates to/duplicates/clones), epic parent with siblings, and subtasks. Produces a consolidated context bundle that downstream agents consume so they never act on a single ticket in isolation."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Read JIRA Ticket: $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa-atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Fetch the full scope of the ticket AND its related graph. Downstream agents must never act on a ticket in isolation — always call this skill first so they see blockers, epic siblings, linked PRs, and historical comments.
+
+Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.
+
+## Phase 1 — Resolve Context
+
+1. Invoke `lisa-atlassian-access` via the Skill tool with `operation: list-sites` to confirm the configured site is reachable and resolve the cloud ID.
+2. If $ARGUMENTS is not a ticket key (e.g. `PROJ-123`), stop and report. Do NOT guess.
+
+## Phase 2 — Fetch Primary Ticket
+
+Invoke `lisa-atlassian-access` via the Skill tool with `operation: read-ticket key: <TICKET-KEY>` for the target ticket. The access layer MUST request an explicit full JIRA field set for this operation (`acli jira workitem view --fields '*all'`, REST `fields=*all`, or an equivalent substrate-specific field list). Do not accept or re-use a default `acli workitem view` payload; its default six-field response omits parent, components, labels, priority, and custom fields, which makes leaf-only, relationship-search, build-ready, and required-custom-field gates read false-empty data. Extract and preserve:
+
+### Metadata
+
+- Key, summary, issue type, status, resolution
+- Priority, assignee, reporter, creator
+- Labels, components, fix versions, affects versions
+- Sprint, story points, original/remaining estimate
+- Created, updated, resolved dates
+- Parent (epic link or parent issue)
+- Custom fields relevant to the project (read every custom field — do not filter)
+
+### Body
+
+- Full description (preserve formatting)
+- Acceptance criteria section if separately structured
+- **Validation Journey** section if present (pass verbatim to downstream)
+- Attachments list — capture `id`, `filename`, `mimeType`, `size`, and `content` URL for each. Do not download unless a downstream task needs the bytes (see "Downloading attachments" below).
+
+#### Downloading attachments (opt-in)
+
+The Atlassian MCP exposes attachment metadata but no binary-fetch tool ([JRACLOUD-97830](https://jira.atlassian.com/browse/JRACLOUD-97830), [ECO-1265](https://jira.atlassian.com/browse/ECO-1265)). Fetch attachment bytes only when a downstream task explicitly needs them — e.g., a design-fidelity check on an image, log-file analysis, PDF text extraction. For everything else, keep the URL reference and move on.
+
+```bash
+bash .claude/skills/jira-read-ticket/scripts/download-attachment.sh <id-or-content-url> <output-path>
+```
+
+Requires `python3` and `JIRA_API_TOKEN`. `JIRA_SERVER` and `JIRA_LOGIN` prefer environment values, then the project's `.lisa/jira-cli/.config.yml`, then the announced home config fallback. Missing credentials produce exit code 2 — record the URL only and continue. The server must be a bare HTTPS origin without userinfo, path prefix, query, or fragment. A full attachment URL must use that same origin; invalid destinations are rejected before Basic authorization is constructed. Signed external downloads receive no Basic credentials and use HTTPS only.
+
+After download, branch on `mimeType`:
+- `image/*` — pass the local path to image-aware downstream tools
+- `text/*`, `application/json`, `application/xml`, `application/x-yaml` — read inline as text
+- `application/pdf` — extract text via downstream tooling if needed
+- everything else — record path only; do not attempt to inline binary content
+
+### Comments
+
+Fetch ALL comments in chronological order via `lisa-atlassian-access` `operation: comments key: <TICKET-KEY>`, which pages until every comment is read — the comments embedded in `read-ticket` are only the first page. Do not truncate. If the result reports `comments_complete: false` (a failed page, or an MCP-only read that could not page), say so at the top of the bundle's Comments section with the fetched-versus-total counts, so no downstream agent mistakes a partial set for the whole. For each:
+- Author, timestamp, body
+- Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers like `[repo-name]`
+
+## Phase 3 — Fetch Remote Links
+
+The primary ticket payload returned by `lisa-atlassian-access` `operation: read-ticket` includes the issue's remote links. If the substrate returns remote links separately, request them via `lisa-atlassian-access` with `operation: read-ticket key: <K>` (the operation MUST return remote links — extend `atlassian-access` if it doesn't). For each remote link:
+
+- **GitHub PR or commit** (`github.com/.../(pull|commit)/...`): run `gh pr view <url> --json title,state,body,mergedAt,reviewDecision,comments,reviews` (for PRs) or `gh api repos/<owner>/<repo>/commits/<sha>` (for commits). Capture title, state, body, unresolved review comments, merge status.
+- **Confluence page**: capture title and URL. Do not fetch body unless a downstream task explicitly needs it.
+- **Dashboard, log link, or external URL**: capture title and URL only.
+
+If `gh` is not authenticated, note "gh auth required" and continue — do not abort.
+
+## Phase 4 — Fetch Issue Links (Relationships)
+
+Every linked ticket must be fetched. Do not skip any link type. For each link in the primary ticket's `issuelinks` field, group by type:
+
+- `blocks` / `is blocked by`
+- `relates to`
+- `duplicates` / `is duplicated by`
+- `clones` / `is cloned by`
+- Any other custom link types configured in the project
+
+For each linked ticket, invoke `lisa-atlassian-access` with `operation: read-ticket key: <LINKED-KEY>` and capture:
+
+- Key, summary, type, status, resolution
+- Description (full, unless closed with resolution `Won't Do`/`Duplicate` — then summary only)
+- Acceptance criteria
+- Last 10 comments (chronological)
+- Remote links (PR URLs and state only — skip deep fetch unless the link is `blocks` or `is blocked by`)
+
+**Special handling for `is blocked by`:** fetch the full PR/commit details via `gh` for each blocker's remote links so the agent knows whether the blocker is actually shipped.
+
+## Phase 5 — Fetch Epic Context
+
+If the primary ticket has an epic parent (or IS an epic):
+
+1. Fetch the epic itself via `lisa-atlassian-access` `operation: read-ticket key: <EPIC-KEY>` — full description, acceptance criteria, Validation Journey — and its comments, all of them, via `lisa-atlassian-access` `operation: comments key: <EPIC-KEY>`.
+2. Find epic siblings via JQL:
+   ```jql
+   "Epic Link" = <EPIC-KEY> AND key != <TICKET-KEY>
+   ```
+   Invoke `lisa-atlassian-access` with `operation: search-issues jql: "<above-JQL>"`. For each sibling capture: key, summary, type, status, assignee, priority.
+3. Read each sibling's description at a SUMMARY level (first paragraph only) — the goal is to surface related in-flight work, not duplicate full content. If a sibling is `In Progress` or `In Review` with an assignee different from the current ticket, flag it prominently.
+
+If the primary ticket IS an epic, also fetch all children via the JQL above.
+
+## Phase 6 — Fetch Subtasks
+
+If the primary ticket has subtasks, fetch each via `lisa-atlassian-access` `operation: read-ticket key: <SUBTASK-KEY>`: key, summary, type, status, assignee, description (first paragraph), acceptance criteria.
+
+## Phase 7 — Assemble Context Bundle
+
+Produce a single structured output that the caller can pass verbatim to downstream agents. Use this format:
+
+```text
+# Ticket Context: <KEY>
+
+## Primary Ticket
+- Key: <KEY>
+- Type: <type>
+- Status: <status>
+- Priority: <priority>
+- Assignee: <name>
+- Epic: <epic-key> — <epic-summary>
+- Sprint: <sprint>
+- Labels: <labels>
+- Components: <components>
+
+### Description
+<full description>
+
+### Acceptance Criteria
+<criteria>
+
+### Validation Journey
+<section or "None">
+
+### Comments (<fetched> of <total>; comments_complete: <true|false>)
+<when incomplete: "INCOMPLETE — <fetched> of <total> comments read via <substrate>">
+<chronological comments, flagged items called out>
+
+### Attachments
+<list with id, filename, mimeType, size, content URL — note any that were downloaded and their local paths>
+
+## Remote Links
+### Pull Requests (<count>)
+- <url> — <title> — <state> — <reviewDecision>
+  <body summary + unresolved review comments>
+
+### Confluence
+- <title> — <url>
+
+### Other
+- <title> — <url>
+
+## Issue Links
+### Blocks (<count>)
+<per-ticket block>
+
+### Is Blocked By (<count>)
+<per-ticket block with PR state>
+
+### Relates To (<count>)
+<per-ticket block>
+
+### Duplicates / Clones
+<per-ticket block>
+
+## Epic Context
+### Epic <EPIC-KEY> — <summary>
+- Status: <status>
+- Description: <full>
+- Comments: <chronological>
+- Validation Journey: <section or None>
+
+### Siblings In-Flight (<count>)
+- <KEY> — <status> — <assignee> — <summary>  **[FLAG: in progress by other assignee]**
+
+### Other Siblings (<count>)
+- <KEY> — <status> — <summary>
+
+## Subtasks (<count>)
+- <KEY> — <status> — <assignee> — <summary>
+
+## Summary for Downstream
+- Full ticket count pulled: <N>
+- Blockers still open: <list>
+- Related in-flight work: <list>
+- Relevant PRs: <list with state>
+```
+
+## Rules
+
+- Never summarize or truncate the primary ticket's description or Validation Journey.
+- Never skip a link type, even if it seems unrelated — the agent downstream decides relevance.
+- If a linked ticket returns an access error, capture the error and continue. Do not abort the read.
+- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
+- If the ticket has no epic parent, state this explicitly — do not silently skip Phase 5.
+- Output is pure context. This skill never modifies the ticket.

package/plugins/lisa-devin/skills/lisa-jira-read-ticket/scripts/download-attachment.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# download-attachment.sh — Download a JIRA attachment to a local file.
+#
+# Usage:
+#   bash download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>
+#
+# Why this helper exists:
+#   The Atlassian MCP server (mcp__atlassian__*) returns attachment metadata
+#   (id, filename, mimeType, size, content URL) on getJiraIssue but provides
+#   no tool to fetch the binary content. This script closes the gap by
+#   hitting the Jira REST API directly with Basic auth, mirroring the
+#   env-var contract already used by jira-evidence/scripts/post-evidence.sh.
+#
+#   See https://jira.atlassian.com/browse/JRACLOUD-97830 for the upstream
+#   gap; remove this helper once Atlassian ships a download tool in the MCP.
+#
+# Requires python3 for destination validation.
+#
+# Required env vars:
+#   JIRA_SERVER     - https://<your-tenant>.atlassian.net
+#   JIRA_LOGIN      - login email
+#   JIRA_API_TOKEN  - API token (https://id.atlassian.com/manage-profile/security/api-tokens)
+#
+#   JIRA_SERVER and JIRA_LOGIN each fall back to a jira-cli config when unset:
+#   ${PROJECT_DIR}/.lisa/jira-cli/.config.yml (written by the setup-jira-cli
+#   SessionStart hook) first, then ${HOME}/.config/.jira/.config.yml, with the
+#   fallback announced on stderr. When BOTH env vars are set, no config file is
+#   opened at all. JIRA_API_TOKEN has no config fallback — it is a secret and
+#   is never written to the jira-cli config.
+#
+# Exit codes:
+#   0  success
+#   1  download failed (HTTP error)
+#   2  missing required env var
+#   3  invalid arguments
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>" >&2
+  exit 3
+fi
+ID_OR_URL="$1"
+OUTPUT_PATH="$2"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Resolve credentials: prefer env, fall back to a jira-cli config for
+# server/login.
+#
+# The env-first arm is load-bearing and unchanged: a headless environment that
+# exports JIRA_SERVER and JIRA_LOGIN never opens a config file at all. The
+# resolution below is therefore gated on actually needing it.
+#
+# What changed (CodySwannGT/lisa#2767): the fallback looked only at the
+# developer's own ~/.config/.jira/.config.yml. The setup-jira-cli SessionStart
+# hook writes ${PROJECT_DIR}/.lisa/jira-cli/.config.yml, which nothing read —
+# so on a headless JIRA project with the JIRA_* vars absent, the file Lisa had
+# just written was ignored and this script exited 2. The Lisa-written config is
+# now preferred, with the developer config kept as an announced fallback.
+#
+# PROJECT_DIR uses the same rule as the hook that writes the file:
+# CLAUDE_PROJECT_DIR, then the git toplevel, then pwd. Resolving from the
+# process working directory instead would reintroduce #2768 on the read side.
+#
+# Nothing here writes to ~/.config/.jira — it is read, never created.
+# ─────────────────────────────────────────────────────────────────────────────
+JIRA_CONFIG=""
+if [[ -z "${JIRA_SERVER:-}" || -z "${JIRA_LOGIN:-}" ]]; then
+  PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+  if [[ -z "${PROJECT_DIR}" || ! -d "${PROJECT_DIR}" ]]; then
+    PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  fi
+  PROJECT_JIRA_CONFIG="${PROJECT_DIR}/.lisa/jira-cli/.config.yml"
+  HOME_JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+
+  if [[ -f "$PROJECT_JIRA_CONFIG" ]]; then
+    JIRA_CONFIG="$PROJECT_JIRA_CONFIG"
+  elif [[ -f "$HOME_JIRA_CONFIG" ]]; then
+    # Announced, never silent — a quiet fall-through to the developer's own
+    # file is how the Lisa-written config stayed unconsumed unnoticed.
+    echo "NOTE: no Lisa-written jira-cli config at $PROJECT_JIRA_CONFIG" >&2
+    echo "      falling back to the developer config at $HOME_JIRA_CONFIG" >&2
+    JIRA_CONFIG="$HOME_JIRA_CONFIG"
+  else
+    echo "NOTE: no jira-cli config at $PROJECT_JIRA_CONFIG" >&2
+    echo "      or $HOME_JIRA_CONFIG; relying on the environment alone." >&2
+  fi
+fi
+
+if [[ -z "${JIRA_SERVER:-}" && -n "$JIRA_CONFIG" ]]; then
+  JIRA_SERVER=$(sed -n 's/^server:[[:space:]]*//p' "$JIRA_CONFIG")
+fi
+if [[ -z "${JIRA_LOGIN:-}" && -n "$JIRA_CONFIG" ]]; then
+  JIRA_LOGIN=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+
+for VAR in JIRA_SERVER JIRA_LOGIN JIRA_API_TOKEN; do
+  if [[ -z "${!VAR:-}" ]]; then
+    echo "ERROR: $VAR is not set." >&2
+    echo "Required env vars: JIRA_SERVER, JIRA_LOGIN, JIRA_API_TOKEN." >&2
+    echo "Generate an API token: https://id.atlassian.com/manage-profile/security/api-tokens" >&2
+    exit 2
+  fi
+done
+
+# Validate before constructing credentials; use only the approved HTTPS origin.
+JIRA_SERVER=$(python3 - "$JIRA_SERVER" <<'PY_ORIGIN'
+import ipaddress
+import re
+import sys
+from urllib.parse import urlsplit
+
+raw = sys.argv[1]
+try:
+    if not raw or any(c <= " " or c >= "\x7f" for c in raw):
+        raise ValueError()
+    url = urlsplit(raw)
+    if (url.scheme != "https" or "@" in url.netloc or "?" in raw
+            or "#" in raw or url.path not in ("", "/") or not url.hostname):
+        raise ValueError()
+    host = url.hostname
+    if url.netloc.startswith("["):
+        host = f"[{ipaddress.IPv6Address(host).compressed}]"
+    elif not re.fullmatch(r"[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*", host):
+        raise ValueError()
+    port = url.port
+    if port == 0:
+        raise ValueError()
+    suffix = f":{port}" if port is not None and port != 443 else ""
+    print(f"https://{host}{suffix}")
+except ValueError:
+    sys.exit("ERROR: JIRA_SERVER must be a bare HTTPS origin without userinfo, path, query or fragment.")
+PY_ORIGIN
+)
+
+OUTPUT_DIR=$(dirname "$OUTPUT_PATH")
+if [[ ! -d "$OUTPUT_DIR" ]]; then
+  echo "ERROR: Output directory does not exist: $OUTPUT_DIR" >&2
+  exit 3
+fi
+
+if [[ "$ID_OR_URL" =~ ^[0-9]+$ ]]; then
+  ATTACHMENT_URL="$JIRA_SERVER/rest/api/3/attachment/content/$ID_OR_URL"
+else
+  ATTACHMENT_URL="$ID_OR_URL"
+fi
+
+# A supplied URL receives Basic auth only when it names the configured origin.
+ATTACHMENT_URL=$(python3 - "$JIRA_SERVER" "$ATTACHMENT_URL" <<'PY_ATTACHMENT'
+import sys
+from urllib.parse import urlsplit, urlunsplit
+
+try:
+    origin, raw = sys.argv[1:]
+    if not raw or any(c <= " " or c >= "\x7f" for c in raw):
+        raise ValueError()
+    base, target = urlsplit(origin), urlsplit(raw)
+    if (target.scheme != "https" or "@" in target.netloc or "#" in raw
+            or target.hostname != base.hostname
+            or (target.port if target.port is not None else 443) != (base.port or 443)):
+        raise ValueError()
+    print(urlunsplit(("https", base.netloc, target.path, target.query, "")))
+except ValueError:
+    sys.exit("ERROR: Attachment must be an ID or an HTTPS URL on the configured Jira origin.")
+PY_ATTACHMENT
+)
+
+JIRA_AUTH=$(printf '%s' "$JIRA_LOGIN:$JIRA_API_TOKEN" | base64 | tr -d '\n')
+
+# Atlassian responds 302 to a signed URL on media.atlassian.com that has its
+# own auth and rejects Basic. Two-step: capture Location, then GET unauthed.
+HEADERS_FILE=$(mktemp)
+trap 'rm -f "$HEADERS_FILE"' EXIT
+
+HTTP_CODE=$(curl -sS -o /dev/null -w '%{http_code}' \
+  --max-redirs 0 \
+  -D "$HEADERS_FILE" \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Accept: */*" \
+  "$ATTACHMENT_URL" || true)
+
+case "$HTTP_CODE" in
+  302|303|307)
+    SIGNED_URL=$(awk '/^[Ll]ocation:/{sub(/^[Ll]ocation:[ \t]*/,""); sub(/\r$/,""); print; exit}' "$HEADERS_FILE")
+    if [[ -z "$SIGNED_URL" ]]; then
+      echo "ERROR: Got HTTP $HTTP_CODE but no Location header in response." >&2
+      exit 1
+    fi
+    curl --proto '=https' -sSf -o "$OUTPUT_PATH" --url "$SIGNED_URL" || { echo "ERROR: Download from signed URL failed." >&2; exit 1; }
+    ;;
+  200)
+    curl -sSf -o "$OUTPUT_PATH" \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "Accept: */*" \
+      "$ATTACHMENT_URL" || { echo "ERROR: Direct download from $ATTACHMENT_URL failed." >&2; exit 1; }
+    ;;
+  401|403)
+    echo "ERROR: Authentication failed (HTTP $HTTP_CODE). Verify JIRA_LOGIN and JIRA_API_TOKEN." >&2
+    exit 1
+    ;;
+  404)
+    echo "ERROR: Attachment not found at $ATTACHMENT_URL (HTTP 404). Verify the ID and your access." >&2
+    exit 1
+    ;;
+  *)
+    echo "ERROR: Unexpected HTTP $HTTP_CODE from $ATTACHMENT_URL" >&2
+    exit 1
+    ;;
+esac
+
+echo "  ✓ Downloaded -> $OUTPUT_PATH"

package/plugins/lisa-devin/skills/lisa-jira-sync/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: lisa-jira-sync
+description: "Syncs plan progress to a linked JIRA ticket. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep tickets in sync."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# JIRA Ticket Sync
+
+All Atlassian operations in this skill go through `lisa-atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Sync current plan progress to JIRA ticket: $ARGUMENTS
+
+If no argument provided, search for a ticket URL in the active plan file (most recently modified `.md` in `plans/`).
+
+Optional arguments include `pr_url=<url>` for the live pull request and `merge_sha=<sha>` once merged.
+
+## Workflow
+
+### Step 1: Identify Ticket and Context
+
+1. **Parse ticket ID** from `$ARGUMENTS` or extract from the active plan file
+2. **Fetch current ticket state** by invoking `lisa-atlassian-access` via the Skill tool with `operation: read-ticket key: <TICKET-ID>`
+3. **Determine current milestone** by checking:
+   - Does a plan file exist? → Plan created
+   - Is there a working branch? → Implementation started
+   - Are tasks in progress? → Active implementation
+   - Is there an open PR? → PR ready for review
+   - Is the PR merged? → Complete
+
+### Step 2: Gather Update Content
+
+Based on the current milestone:
+
+| Milestone | Content to Post |
+|-----------|-----------------|
+| **Plan created** | Plan summary, branch name, link to PR (if draft exists) |
+| **Implementation in progress** | Task completion summary (X of Y tasks done), any blockers |
+| **PR ready** | PR link, summary of changes, test results |
+| **PR merged** | Final summary, suggest moving ticket to "Done" |
+
+### Step 3: Post Update
+
+Before adding a comment, check for an existing milestone comment to avoid duplicates (idempotency):
+
+1. **Fetch existing comments** by invoking `lisa-atlassian-access` with `operation: search-issues jql: "..."` or by reading the ticket's comments. Look for a comment whose body contains a stable milestone marker (e.g., the heading `## Plan Created`, `## Implementation in Progress`, `## PR Ready`, or `## PR Merged`) that matches the current milestone.
+2. **If a matching comment already exists**, skip posting and proceed to field updates — idempotent re-runs must not create duplicates.
+3. **If no matching comment exists**, add a new comment by invoking `lisa-atlassian-access` with `operation: comment key: <TICKET-ID> body: "..."`.
+4. **Update ticket fields** if applicable:
+   - Add branch name to a custom field or comment
+   - Add PR link to a custom field or comment
+5. **Report** what was synced to the user
+
+### Step 3b: Ensure PR Backlink
+
+When `$ARGUMENTS` includes `pr_url=<url>` for `PR ready` or `PR merged`, ensure the JIRA ticket has a durable ticket -> PR link:
+
+1. Prefer the JIRA development-link surface when the site's GitHub/JIRA integration or remote-link API is available through `lisa-atlassian-access`; verify by re-reading the ticket's remote links / development metadata.
+2. Establish the managed backlink comment by running the command that owns it — never by hand, and never by describing the procedure here:
+
+   ```bash
+   node scripts/lisa-work-item.mjs backlink --ref <work-item> --pr-url <url>
+   ```
+
+   It creates the `[lisa-pr-link]` comment or updates the one already present, instead of appending duplicates, so it is safe to run on every milestone. This is **unconditional** — run it whether or not native linkage exists or cannot be verified, because the required Work-Item Traceability check reads this comment and nothing else guarantees one. The comment carries the marker and the PR URL only; the milestone (`pr-ready` / `pr-merged`) and merge SHA belong in the milestone progress note, so that a rerun at a new milestone still converges on one backlink comment.
+
+The PR body/branch issue key is the PR -> ticket side. This step is the required ticket -> PR side.
+
+### Step 4: Suggest Status Transition
+
+Based on the milestone, suggest (but don't automatically perform) a status transition:
+
+| Milestone | Suggested Status |
+|-----------|-----------------|
+| Plan created | configured `jira.workflow.claimed` status |
+| PR ready | configured `jira.workflow.review` status, or no transition when unconfigured |
+| PR merged | configured `jira.workflow.done` status for the PR's target environment (env-keyed `done` resolved via `deploy.branches`), or no transition when unconfigured |
+
+Every suggested transition is bound by the **Tracker status vocabulary** section of `lisa-tracker-sync` — cite it, do not restate the policy. It is shared by all three vendor arms so the bar cannot drift between them, and it carries the two consequences that matter here: a milestone whose role is unset gets a comment rather than a transition, and a fallback may inform a read but never supply a write target.
+
+`review` is optional on JIRA and has no default. Resolve it through the shared resolver rather than an inlined helper — `lisa-jira-evidence/scripts/post-evidence.sh` already models the correct behaviour (empty default, explicit skip branch, `leaving <ID> in its current (claimed) status`).
+
+### Step 5: Parent Status Rollup (`--rollup`)
+
+When invoked with `--rollup`, this skill **derives a parent/container ticket's status from the roll-up of its children** (Stories under an Epic; Sub-tasks under a Story/Task) instead of posting a milestone update on a leaf. This implements the JIRA child/subtask-status arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy.
+
+**Resolve the child set the same way `lisa-jira-read-ticket` does** — the native Epic → Story → Sub-task hierarchy (Epic link / parent field for Stories, the subtask relationship for Sub-tasks), each with its current status. Fetch via `lisa-atlassian-access` (`operation: read-ticket` / `search-issues` with the parent's `"Epic Link" = <KEY>` or `parent = <KEY>` JQL). If the ticket has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
+
+**Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the JIRA env-keyed `done` map, e.g. `On Dev < On Stg < Done`) and take the first match** (canonical roles from `config-resolution`; the JIRA status map defaults to `Blocked`, `In Progress`, `Code Review`, env-keyed `done`):
+
+| If among the required child leaves… | Derived parent role | JIRA status |
+|---|---|---|
+| any child is **blocked** | `blocked` | `Blocked` |
+| else **every** required child has shipped to some env (each at a `done`-map value, e.g. `On Dev`/`On Stg`/`Done`) | `done[min-env]` | the **least-advanced** env status among them (all `On Stg` → `On Stg`; mixed `On Dev`+`On Stg` → `On Dev`; all production → `Done`) |
+| else any child has **started** (`In Progress` / `Code Review`, or shipped to an env while a sibling has not) | `claimed` | `In Progress` |
+| else (children exist, none started) | — | unchanged — parent keeps its non-ready container status |
+
+- **Blocked dominates** — a single blocked child surfaces `Blocked` on the parent even while siblings progress. It never says *which* child or *which kind* of hold; resolve and run the shared classifier exactly as `lisa-tracker-sync` specifies, then carry its per-class report — blocking leaf, path, and who must act — into the rollup note. A missing classifier or non-zero exit is a strict **no-write** result: do not transition the parent and do not post/update a rollup comment; report the failure, never an all-clear. See `leaf-only-lifecycle` → **Classifying a hold**.
+- **Least-advanced env wins** — the parent reaches an env only when every required child has reached at least that env; it never sits ahead of its laggard child. Apply native terminal resolution (the `leaf-only-lifecycle` Terminal native closure) only when the resolved env is the production `Done`, never at `On Dev`/`On Stg`.
+- **"Required" children only** — won't-do / optional children do not hold the parent open.
+- **Recursive** — an Epic reaches an env only when its Stories have themselves rolled up to at least that env; a Story reaches it only when its Sub-tasks have. Evaluate bottom-up.
+- **Never set the parent to the build-ready status** — `ready` is leaf-only. Rollup only moves the parent between non-ready container statuses.
+- **`review` is optional for JIRA** (`config-resolution`) — a project that omits `Code Review` keeps the parent in `In Progress` until it shifts to an env; skip the intermediate review hop rather than forcing a non-existent status (a `leaf-only-lifecycle` "vendor support varies" note).
+
+**Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to a single status, the only env rung is production, and the lifecycle is `Ready → In Progress → Code Review → Done` with **no** dev/staging promotion hops; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to intermediate env statuses (`On Dev`/`On Stg`).
+
+**Apply the derived status** (only when it differs from the parent's current status) via `lisa-atlassian-access` `operation: transition`, and post an idempotent rollup comment naming the derived state and the child tally. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's status untouched.
+
+## Important Notes
+
+- **Never auto-transition ticket status** — always suggest and let the user confirm. The one exception is the explicit `--rollup` parent derivation (Step 5), which transitions a *parent's* status per the `leaf-only-lifecycle` rule — never a leaf's, and never to the build-ready status.
+- **Idempotent updates** — running sync multiple times at the same milestone should not create duplicate comments
+- **Comment format** — use JIRA markdown with clear headers and bullet points
+- **Rollup cites the rule by slug** — parent state derivation follows the `leaf-only-lifecycle` rule's state machine; this skill does not restate the policy.
+
+## Execution
+
+Sync the ticket now.