@codyswann/lisa 4.74.9 → 4.75.1

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

@@ -0,0 +1,157 @@
+---
+name: lisa-jira-create
+description: This skill should be used when creating JIRA epics, stories, and tasks from code files or descriptions. It analyzes the provided input, determines the appropriate issue hierarchy, and creates issues with comprehensive quality requirements including test-first development and documentation.
+allowed-tools: ["Read", "Glob", "LS", "Skill"]
+---
+
+# Create JIRA Issues from $ARGUMENTS
+
+All Atlassian operations in this skill go through `lisa-atlassian-access`. Do not call MCP tools or `acli` directly.
+
+Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans structure only — every individual ticket write is delegated to `lisa-jira-write-ticket`.** Do not invoke `lisa-atlassian-access` write operations directly from this skill — all writes go through `lisa-jira-write-ticket`.
+
+## Process
+
+1. **Analyze**: Read $ARGUMENTS to understand scope.
+2. **Extract source artifacts**: invoke the `lisa-tracker-source-artifacts` skill, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain per its rules. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `lisa-product-walkthrough` skill to capture current behavior, design-vs-product divergence, and reuse candidates. Skip when the work is purely backend or affects a screen that does not yet exist. See "Live Product Walkthrough" below.
+4. **Determine structure**:
+   - Epic needed if: multiple features, major changes, >3 related files
+   - Direct tasks if: bug fix, single file, minor change
+5. **Plan hierarchy**:
+   ```text
+   Epic → User Story → Tasks (test, implement, document, cleanup)
+   ```
+6. **Delegate every write to `lisa-jira-write-ticket`** in dependency order (epic first, then stories with the epic as parent, then sub-tasks with their story as parent). Pass the artifacts (filtered by domain per `lisa-tracker-source-artifacts` inheritance rules) and the walkthrough findings (under `## Current Product`). See "Delegation to jira-write-ticket" below.
+7. **Run the artifact preservation gate** (`lisa-tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created tickets. Fail loudly if anything was dropped.
+
+## Mandatory for Every Code Issue
+
+**Test-First**: Write tests before implementation
+**Quality Gates**: All tests/checks must pass, no SonarCloud violations
+**Documentation**: Check existing, update/create new, remove obsolete
+**Cleanup**: Remove temporary code, scripts, dev configs
+
+## Validation Journey
+
+Tickets that change runtime behavior should include a `Validation Journey` section in the description. This section is consumed by the `lisa-jira-journey` skill to automate verification.
+
+### When to Include
+
+Include a Validation Journey when the ticket involves:
+- API endpoint changes (new, modified, or removed routes)
+- Database schema changes (migrations, new columns, index changes)
+- Background job or queue processing changes
+- Library or utility function changes that affect exports
+- Security fixes (authentication, authorization, input validation)
+- Performance-critical changes requiring measurement
+
+### When to Skip
+
+Skip the Validation Journey for:
+- Documentation-only changes
+- Config-only changes (env vars, CI/CD, feature flags with no code)
+- Type-definition-only changes (interfaces, types, no runtime effect)
+
+### How to Write
+
+Design the journey based on the **change type**. The agent executing the journey determines how to verify each step using patterns from the project's `verfication.md`. Place typed `[EVIDENCE: <artifact-type>: <name>]` markers at key verification points (types: `screenshot`, `recording`, `http-transcript`, `cli-output`, `log-snippet`, `db-query-output`, `perf-trace`, `test-run-log`, `deploy-log`, `state-dump` — see the `verification` rule).
+
+Add this section to the ticket description:
+
+```text
+h2. Validation Journey
+
+h3. Prerequisites
+- Local dev server running
+- Database accessible
+- Required environment variables set
+
+h3. Steps
+1. Verify the current state before changes
+2. Apply the change (run migration, deploy, etc.)
+3. Verify the expected new state [EVIDENCE: http-transcript: state-after-change]
+4. Test error/edge cases [EVIDENCE: screenshot: error-state-rendered]
+5. Verify rollback or cleanup if applicable [EVIDENCE: db-query-output: rows-restored-after-rollback]
+
+h3. Assertions
+- Describe what must be true after verification
+- Each assertion is verified against the captured evidence
+```
+
+### Guidelines
+
+1. **Steps must be concrete and verifiable** — "Run `curl -s localhost:3000/health`" not "Check the API"
+2. **Evidence markers at verification points** — Place typed `[EVIDENCE: <artifact-type>: <name>]` at states that prove the change works. The type names HOW the proof is captured, the kebab-case name WHAT it proves (e.g., `[EVIDENCE: http-transcript: api-response-200]`, `[EVIDENCE: screenshot: error-state-rendered]`). An untyped assertion label like `[EVIDENCE: works-gracefully]` fails validation gate S14
+   - To point at evidence owned by another work item, use exactly `[EVIDENCE-REF: <work-item-ref> | <artifact-type>: <kebab-case-name>]`. It is non-claiming and cannot satisfy S14; never paste or quote the sibling's `[EVIDENCE: ...]` marker into this ticket.
+3. **Include 2-5 evidence markers** — Enough to prove the change works across happy path and error cases
+4. **Assertions are testable statements** — "Health check returns 200 with status ok" not "API works"
+5. **Prerequisites include environment setup** — Database connection, env vars, running services
+
+## Source Artifacts
+
+If $ARGUMENTS includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as remote links on the created tickets. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke the `lisa-tracker-source-artifacts` skill** for the canonical rules: domains, per-tool classification (Figma `/proto/` vs design, Lovable, Loom, screenshots), source precedence, conflict handling under `## Open Questions`, inheritance from epic → story → sub-task, and the existing-component reuse expectation. Do not restate the rules here — invoke the skill so any rule change propagates uniformly.
+
+When delegating actual writes to `lisa-jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke the `lisa-product-walkthrough` skill before drafting tickets. The walkthrough findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the ticket plan and surface under `## Current Product` on the resulting tickets. Skip only when the work is purely backend or affects a screen that does not yet exist.
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default project: from jira-cli config (override via arguments)
+Exclude unless requested: migration plans, performance tests
+
+## Delegation to jira-write-ticket
+
+**Mandatory.** Every ticket created by this skill MUST go through `lisa-jira-write-ticket`. This skill never invokes `lisa-atlassian-access` write operations itself — all writes are delegated so the gate cannot be bypassed.
+
+`lisa-jira-write-ticket` enforces things this skill does not, and which determine ticket quality:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation (non-bug, non-epic types)
+- Explicit link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Remote links (PRs, Confluence, dashboards)
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+**Declare readiness on every leaf write.** Per the `ready-role-filing` rule an omitted `build_ready` is **not build-ready** on any tracker, so pass `build_ready: true` on each Sub-task (the leaf work units this skill plans) and never on the Epic or Stories, which are containers per `leaf-only-lifecycle`. A leaf that is deliberately held instead passes `human_gate: "<why a human must judge this first>"`. Filing a leaf with neither is an incomplete handoff and `lisa-jira-write-ticket` rejects it.
+
+### Invocation order
+
+Tickets must be created in parent-before-child order so each child can be passed its parent key:
+
+1. Invoke `lisa-jira-write-ticket` for the epic. Capture the returned key.
+2. For each story, invoke `lisa-jira-write-ticket` with the epic key as the epic parent. Capture each story key.
+3. For each sub-task, invoke `lisa-jira-write-ticket` with the parent story key.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, project key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent key (epic key for stories; story key for sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules — `lisa-jira-write-ticket` Phase 4c attaches them as remote links
+- For tickets that change runtime behavior: the Validation Journey draft (or instruct it to call `lisa-jira-add-journey` after create)
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's an epic vs. story vs. sub-task)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent keys through subsequent writes
+- Running the Phase 5.5-style preservation check after all writes complete
+
+It does not own the actual JIRA write — that's `lisa-jira-write-ticket`'s job.

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

@@ -0,0 +1,106 @@
+---
+name: lisa-jira-evidence
+description: "Upload text evidence to GitHub pr-assets release, update PR description, post JIRA comment with code blocks, and move ticket to the configured review status only when `jira.workflow.review` is set (otherwise leave it in `claimed`). Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/comment.md."
+---
+
+# JIRA Evidence Posting
+
+## Workflow resolution
+
+The post-build review status is read from `.lisa.config.json` `jira.workflow.review` (or `jira.workflow.code_review`). `review` is optional; when unset, the ticket stays in `claimed` until `done` and this skill skips the transition. Never transition to a status that is not named in `config.jira.workflow`. If the configured status is not a valid transition from the current state, log a warning and skip.
+
+```bash
+REVIEW=""
+if [ -f .lisa.config.json ]; then
+  _cfg=$(jq -r '.jira.workflow.review // .jira.workflow.code_review // empty' .lisa.config.json 2>/dev/null)
+  [ -n "$_cfg" ] && REVIEW="$_cfg"
+fi
+if [ -f .lisa.config.local.json ]; then
+  _local=$(jq -r '.jira.workflow.review // .jira.workflow.code_review // empty' .lisa.config.local.json 2>/dev/null)
+  [ -n "$_local" ] && REVIEW="$_local"
+fi
+```
+
+
+Upload captured evidence and generated templates to GitHub PR description and JIRA ticket. This skill is the posting step — it assumes evidence files and comment templates already exist in the evidence directory.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `EVIDENCE_DIR` (required): Directory containing evidence and templates (e.g., `./evidence`)
+- `PR_NUMBER` (required): GitHub PR number to update description
+
+## Prerequisites
+
+- `python3` for destination validation. Configure `server` as a bare HTTPS origin:
+  no userinfo, path prefix, query, or fragment. Invalid destinations are rejected
+  before Basic authorization is constructed.
+- `JIRA_API_TOKEN` environment variable set
+- a jira-cli config — `.lisa/jira-cli/.config.yml` if the `setup-jira-cli`
+  SessionStart hook wrote one, otherwise `~/.config/.jira/.config.yml`. `server`
+  and `login` are read from whichever is used, and the fallback is announced on
+  stderr rather than taken silently.
+- `gh` CLI authenticated
+- Evidence directory containing:
+  - `NN-name.txt` or `NN-name.json` text evidence files (e.g., `01-health-check.json`)
+  - `comment.txt` — JIRA wiki markup (generated by `generate-templates.py`)
+  - `comment.md` — GitHub markdown (generated by `generate-templates.py`)
+
+## Comment-body preflight (required)
+
+Before posting or updating anything, check the evidence body (`comment.md`, and `comment.txt` where this skill uses it):
+
+- It contains a `## Not established` heading. That heading is **never omitted and never blank** — when nothing is outstanding it still renders `None outstanding — reviewed`; otherwise it names, in plain operator language, what the verification did not prove.
+- The accompanying verdict carries `not_established_reviewed: true` (the list may be empty; the flag may never be omitted).
+- It contains a `## Artifact identity` heading carrying **values, not placeholders** — the repository, the `head_sha` the verification observed, the `environment`, and per artifact its `sha256` digest and `captured_at`. **Refuse to post** a body whose identity heading is absent or unpopulated, or whose recorded `artifact_head_sha` disagrees with the verdict's `artifact.head_sha` — report the evidence id and **both SHAs**. Definition: the `claim-evidence-mapping` rule.
+
+If either is missing, **refuse to post**: stop and report the missing Not-established review to the caller instead of publishing. Composing the body is `lisa-tracker-evidence`'s job (see its UI Evidence Checklist); this skill only refuses to publish one that omits the section. The section is defined by the `claim-evidence-mapping` rule and generalizes `lisa-improve-harness`'s required, never-empty `Known limits` field.
+
+## Usage
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+```
+
+### Example
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh PROJ-123 ./evidence 42
+```
+
+## What It Does
+
+1. **Read JIRA config** — Resolves the jira-cli config (`$PROJECT_DIR/.lisa/jira-cli/.config.yml` first, then `~/.config/.jira/.config.yml`, announcing the fallback) and reads `server` and `login` from it dynamically — no hardcoded values. Exits 1 naming both paths when neither exists. The same resolved path is then passed to `jira issue move` as `--config`, so the CLI cannot end up on a different config than the one this script parsed.
+2. **Upload to GitHub `pr-assets` release** — Uploads evidence files via `gh release upload --clobber`
+3. **Update PR description** — Replaces or appends the `## Evidence` section in the PR body
+4. **Post JIRA comment** — Posts `comment.txt` as a new comment (wiki markup with code blocks)
+5. **Move ticket to the configured review status** — Transitions the JIRA ticket to `$REVIEW` (default: `Code Review`).
+
+## Evidence Naming Convention
+
+Text evidence files are named: `{NN}-{evidence-name}.txt` or `{NN}-{evidence-name}.json`
+
+```text
+evidence/
+  01-health-check.json          uploaded
+  02-schema-after-migration.txt uploaded
+  03-rate-limit-response.txt    uploaded
+  comment.txt                   used for JIRA comment
+  comment.md                    used for PR description
+```
+
+## Troubleshooting
+
+### Evidence not appearing in GitHub PR
+
+Evidence files must be in the `pr-assets` GitHub release. If the release does not exist:
+
+```bash
+gh release create pr-assets --title "PR Assets" --notes "CDN for PR evidence"
+```
+
+### JIRA API returns 403
+
+Ensure `JIRA_API_TOKEN` is set and `login` in the resolved jira-cli config (`.lisa/jira-cli/.config.yml`, else `~/.config/.jira/.config.yml`) matches your Atlassian account email.

package/plugins/lisa-devin/skills/lisa-jira-evidence/scripts/post-evidence.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# post-evidence.sh — Upload evidence and post to JIRA + GitHub PR description
+#
+# Usage:
+#   bash post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+#
+# Prerequisites:
+#   - JIRA_API_TOKEN env var set
+#   - a jira-cli config, resolved in this order (see "CONFIG RESOLUTION" below):
+#       1. ${PROJECT_DIR}/.lisa/jira-cli/.config.yml  (written by the
+#          setup-jira-cli SessionStart hook from the JIRA_* environment)
+#       2. ~/.config/.jira/.config.yml                (a developer's own
+#          `jira init` config; announced on stderr when it is used)
+#   - gh CLI authenticated
+#
+# What it does:
+#   1. Uploads evidence files to the 'pr-assets' GitHub release
+#   2. Updates the GitHub PR description with evidence/comment.md
+#   3. Uploads image evidence as JIRA attachments
+#   4. Posts/updates the JIRA comment with evidence/comment.txt
+#   5. Moves the JIRA ticket to the configured jira.workflow.review status
+#      (skipped entirely when review is unconfigured — stays in claimed)
+
+set -euo pipefail
+
+TICKET_ID="${1:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+EVIDENCE_DIR="${2:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+PR_NUMBER="${3:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CONFIG RESOLUTION
+#
+# The setup-jira-cli SessionStart hook writes ${PROJECT_DIR}/.lisa/jira-cli/
+# .config.yml. Nothing read it — this script looked only at the developer's own
+# ~/.config/.jira/.config.yml and exited 1 telling the operator to run
+# `jira init`, so on a headless JIRA project the hook was an inert control.
+# See CodySwannGT/lisa#2767.
+#
+# PROJECT_DIR is resolved with the same rule as the hook that writes the file,
+# deliberately character-for-character: CLAUDE_PROJECT_DIR (the harness's own
+# declaration of the root, inert on harnesses that never set it), then the git
+# toplevel, then pwd. A session launched from a subdirectory otherwise reads a
+# directory it never wrote — the #2768 defect, on the read side.
+#
+# Nothing here writes to ~/.config/.jira. That file is a developer's personal
+# jira-cli state; it is read as a fallback and never created or modified.
+#
+# NOTE: the `.lisa.config.json` reads in Step 5 below are still resolved from
+# the process working directory. That is pre-existing and out of scope here.
+# ─────────────────────────────────────────────────────────────────────────────
+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 silent fall-through to the developer's own file
+  # is precisely how the Lisa-written config stayed unconsumed without anyone
+  # noticing, and on a headless runner there is no such file to fall back to.
+  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 "ERROR: jira-cli config not found." >&2
+  echo "  Lisa-written config (expected): $PROJECT_JIRA_CONFIG" >&2
+  echo "  developer config (fallback):    $HOME_JIRA_CONFIG" >&2
+  echo "  Fix: export JIRA_SERVER, JIRA_LOGIN (and JIRA_INSTALLATION," >&2
+  echo "  JIRA_PROJECT) and start a new session so the setup-jira-cli hook" >&2
+  echo "  writes the project config — or run 'jira init' locally." >&2
+  exit 1
+fi
+JIRA_SERVER=$(sed -n 's/^server:[[:space:]]*//p' "$JIRA_CONFIG")
+JIRA_USER=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+# 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
+)
+
+GH_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+RELEASE_TAG="pr-assets"
+
+if [[ -z "${JIRA_API_TOKEN:-}" ]]; then
+  echo "ERROR: JIRA_API_TOKEN environment variable is not set" >&2
+  exit 1
+fi
+
+# Collect numbered evidence files (images + text)
+SCREENSHOTS=()
+while IFS= read -r -d '' f; do
+  SCREENSHOTS+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 -name '[0-9][0-9]-*.png' -print0 | sort -z)
+
+TEXT_EVIDENCE=()
+while IFS= read -r -d '' f; do
+  TEXT_EVIDENCE+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 \( -name '[0-9][0-9]-*.txt' -o -name '[0-9][0-9]-*.json' \) ! -name 'comment.txt' -print0 | sort -z)
+
+# Bash 3.2 treats an empty array as unset under nounset.
+ALL_EVIDENCE=(${SCREENSHOTS[@]+"${SCREENSHOTS[@]}"} ${TEXT_EVIDENCE[@]+"${TEXT_EVIDENCE[@]}"})
+
+if [[ ${#ALL_EVIDENCE[@]} -eq 0 ]]; then
+  echo "ERROR: No numbered evidence files found in $EVIDENCE_DIR (expected NN-*.png, NN-*.txt, or NN-*.json)" >&2
+  exit 1
+fi
+
+echo "Found ${#SCREENSHOTS[@]} screenshots and ${#TEXT_EVIDENCE[@]} text evidence files to upload"
+
+# Compute JIRA auth early (used in steps 3 and 4)
+JIRA_AUTH=$(printf '%s' "$JIRA_USER:$JIRA_API_TOKEN" | base64 | tr -d '\n')
+
+# ── Step 1: Upload to GitHub pr-assets release ──────────────────────────────
+echo ""
+echo "==> Uploading to GitHub release '$RELEASE_TAG'..."
+
+for FILE in "${ALL_EVIDENCE[@]}"; do
+  FILENAME=$(basename "$FILE")
+  echo "  ↑ $FILENAME"
+  gh release upload "$RELEASE_TAG" "$FILE" --repo "$GH_REPO" --clobber
+done
+
+echo "  ✓ GitHub release assets uploaded"
+
+# ── Step 2: Update GitHub PR description with evidence ──────────────────────
+COMMENT_MD="$EVIDENCE_DIR/comment.md"
+if [[ ! -f "$COMMENT_MD" ]]; then
+  echo "ERROR: $COMMENT_MD not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Updating GitHub PR #$PR_NUMBER description..."
+
+CURRENT_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+
+# Replace or append the Evidence section
+if echo "$CURRENT_BODY" | grep -q "^## Evidence"; then
+  # Replace from "## Evidence" to end of file
+  NEW_BODY=$(echo "$CURRENT_BODY" | sed '/^## Evidence/,$d')
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${NEW_BODY}
+${EVIDENCE_SECTION}"
+else
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${CURRENT_BODY}
+
+${EVIDENCE_SECTION}"
+fi
+
+gh pr edit "$PR_NUMBER" --body "$UPDATED_BODY"
+echo "  ✓ PR description updated with evidence"
+
+# ── Step 3: Upload image evidence as JIRA attachments ───────────────────────
+if [[ ${#SCREENSHOTS[@]} -gt 0 ]]; then
+  echo ""
+  echo "==> Uploading image attachments to JIRA $TICKET_ID..."
+
+  for IMG in "${SCREENSHOTS[@]}"; do
+    FILENAME=$(basename "$IMG")
+    echo "  ↑ $FILENAME"
+    RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+      -X POST \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "X-Atlassian-Token: no-check" \
+      -F "file=@$IMG" \
+      "$JIRA_SERVER/rest/api/3/issue/$TICKET_ID/attachments")
+    HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+    if [[ "$HTTP_CODE" != "200" ]]; then
+      echo "  WARNING: Failed to upload $FILENAME (HTTP $HTTP_CODE)" >&2
+    fi
+  done
+
+  echo "  ✓ JIRA attachments uploaded"
+fi
+
+# ── Step 4: Post JIRA comment ────────────────────────────────────────────────
+COMMENT_TXT="$EVIDENCE_DIR/comment.txt"
+if [[ ! -f "$COMMENT_TXT" ]]; then
+  echo "ERROR: $COMMENT_TXT not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Posting JIRA comment on $TICKET_ID..."
+
+COMMENT_BODY=$(cat "$COMMENT_TXT")
+COMMENT_JSON=$(python3 -c "import sys, json; print(json.dumps(sys.stdin.read()))" <<< "$COMMENT_BODY")
+
+RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+  -X POST \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Content-Type: application/json" \
+  "$JIRA_SERVER/rest/api/2/issue/$TICKET_ID/comment" \
+  -d "{\"body\": $COMMENT_JSON}")
+HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+
+if [[ "$HTTP_CODE" == "201" ]]; then
+  echo "  ✓ JIRA comment posted"
+else
+  echo "  WARNING: JIRA comment returned HTTP $HTTP_CODE" >&2
+  echo "$RESP" | grep -v "HTTP_CODE:" | head -3
+fi
+
+# ── Step 5: Move ticket to the configured review status (if any) ────────────
+# A transition may target only a status named in .lisa.config.json jira.workflow.
+# `review` is OPTIONAL: when it is not configured, the build lifecycle stays in
+# `claimed` until `done` — do NOT invent a transition. (See config-resolution.md.)
+REVIEW=""
+if [ -f .lisa.config.json ]; then
+  _cfg=$(jq -r '.jira.workflow.review // .jira.workflow.code_review // empty' .lisa.config.json 2>/dev/null)
+  [ -n "$_cfg" ] && REVIEW="$_cfg"
+fi
+if [ -f .lisa.config.local.json ]; then
+  _local=$(jq -r '.jira.workflow.review // .jira.workflow.code_review // empty' .lisa.config.local.json 2>/dev/null)
+  [ -n "$_local" ] && REVIEW="$_local"
+fi
+echo ""
+if [ -n "$REVIEW" ]; then
+  echo "==> Moving $TICKET_ID to $REVIEW..."
+  # --config pins jira-cli to the same file this script parsed above.
+  # jira-cli resolves --config > JIRA_CONFIG_FILE > ~/.config/.jira/
+  # .config.yml, and a --config path that does not exist fails closed
+  # rather than falling back (measured against jira-cli v1.7.0). The flag
+  # needs no environment export, so this works identically on every
+  # harness — see the harness note in the setup-jira-cli hook.
+  jira --config "$JIRA_CONFIG" issue move "$TICKET_ID" "$REVIEW" 2>&1 && echo "  ✓ Ticket moved to $REVIEW" || echo "  WARNING: Could not move ticket to $REVIEW (not a valid transition?); leaving in current status" >&2
+else
+  echo "==> No jira.workflow.review configured; leaving $TICKET_ID in its current (claimed) status per config-resolution."
+fi
+
+echo ""
+echo "==> Done!"
+echo "    JIRA:   $JIRA_SERVER/browse/$TICKET_ID"
+echo "    GitHub: https://github.com/$GH_REPO/pull/$PR_NUMBER"