@toolu/opencode 6.8.0

package/plugins/jira/skills/jira/scripts/lib/issue.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# issue.sh — Jira issue operations: get, create, update, delete, comment,
+# transition(s), assign. Sourced; depends on http.sh (jira_curl/jira_lean) and
+# adf.sh (jira_text_to_adf). Comment/description bodies are version-gated (ADF
+# for v3, plain text for v2); assign/transition mutate live tickets.
+
+_jira_issue_path() { printf '/rest/api/%s/issue' "${_JIRA_VER:-3}"; }
+
+# Lean projection for one issue: keep the useful fields, drop null/empty ones.
+_JIRA_ISSUE_LEAN='{key,
+  summary: .fields.summary, status: .fields.status.name,
+  assignee: .fields.assignee.displayName, reporter: .fields.reporter.displayName,
+  priority: .fields.priority.name, type: .fields.issuetype.name,
+  project: .fields.project.key, created: .fields.created, updated: .fields.updated,
+  labels: .fields.labels}
+  | with_entries(select(.value != null and .value != [] and .value != ""))'
+
+# _jira_assignee_obj ID: compact JSON for an assignee value; "-" unassigns.
+# v3 uses accountId, v2 uses name.
+_jira_assignee_obj() {
+  local id="$1" field="accountId"
+  [[ "${_JIRA_VER:-3}" == "2" ]] && field="name"
+  if [[ "$id" == "-" ]]; then
+    jq -nc --arg f "$field" '{($f): null}'
+  else
+    jq -nc --arg f "$field" --arg i "$id" '{($f): $i}'
+  fi
+}
+
+jira_issue() {
+  local action="${1:-}"; [[ $# -gt 0 ]] && shift
+  case "$action" in
+    get)         _jira_issue_get "$@";;
+    create)      _jira_issue_create "$@";;
+    update)      _jira_issue_update "$@";;
+    delete)      _jira_issue_delete "$@";;
+    comment)     _jira_issue_comment "$@";;
+    transitions) _jira_issue_transitions "$@";;
+    transition)  _jira_issue_transition "$@";;
+    assign)      _jira_issue_assign "$@";;
+    *) echo "Usage: jira issue <get|create|update|delete|comment|transition|transitions|assign> ..." >&2; return 1;;
+  esac
+}
+
+_jira_issue_get() {
+  local key="${1:-}"
+  [[ -z "$key" ]] && { echo "Usage: jira issue get <KEY>" >&2; return 1; }
+  jira_curl GET "$(_jira_issue_path)/$key" | jira_lean "$_JIRA_ISSUE_LEAN"
+}
+
+_jira_issue_create() {
+  local project="" itype="" summary="" desc="" assignee=""
+  local fields=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -p|--project) project="$2"; shift 2;;
+      -t|--type)    itype="$2"; shift 2;;
+      -s|--summary) summary="$2"; shift 2;;
+      -d|--desc)    desc="$2"; shift 2;;
+      --assignee)   assignee="$2"; shift 2;;
+      -f|--field)   fields+=("$2"); shift 2;;
+      *) echo "issue create: unknown option '$1'" >&2; return 1;;
+    esac
+  done
+  [[ -z "$project" || -z "$itype" || -z "$summary" ]] && {
+    echo "Usage: jira issue create -p <PROJECT> -t <TYPE> -s <SUMMARY> [-d DESC] [--assignee ID] [-f field=val]..." >&2
+    return 1
+  }
+  local body
+  body=$(jq -nc --arg p "$project" --arg t "$itype" --arg s "$summary" \
+    '{fields:{project:{key:$p}, issuetype:{name:$t}, summary:$s}}')
+  if [[ -n "$desc" ]]; then
+    body=$(jq -c --argjson d "$(jira_text_to_adf "$desc")" '.fields.description=$d' <<<"$body")
+  fi
+  if [[ -n "$assignee" ]]; then
+    body=$(jq -c --argjson a "$(_jira_assignee_obj "$assignee")" '.fields.assignee=$a' <<<"$body")
+  fi
+  local kv k v
+  for kv in ${fields[@]+"${fields[@]}"}; do
+    k="${kv%%=*}"; v="${kv#*=}"
+    body=$(jq -c --arg k "$k" --arg v "$v" '.fields[$k]=$v' <<<"$body")
+  done
+  jira_curl POST "$(_jira_issue_path)" "$body" | jira_lean '.'
+}
+
+_jira_issue_update() {
+  local key="${1:-}"; [[ $# -gt 0 ]] && shift
+  [[ -z "$key" ]] && { echo "Usage: jira issue update <KEY> [-s SUMMARY] [-d DESC] [-f field=val]..." >&2; return 1; }
+  local summary="" desc="" fields=() body='{"fields":{}}'
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -s|--summary) summary="$2"; shift 2;;
+      -d|--desc)    desc="$2"; shift 2;;
+      -f|--field)   fields+=("$2"); shift 2;;
+      *) echo "issue update: unknown option '$1'" >&2; return 1;;
+    esac
+  done
+  [[ -n "$summary" ]] && body=$(jq -c --arg s "$summary" '.fields.summary=$s' <<<"$body")
+  [[ -n "$desc" ]] && body=$(jq -c --argjson d "$(jira_text_to_adf "$desc")" '.fields.description=$d' <<<"$body")
+  local kv k v
+  for kv in ${fields[@]+"${fields[@]}"}; do
+    k="${kv%%=*}"; v="${kv#*=}"
+    body=$(jq -c --arg k "$k" --arg v "$v" '.fields[$k]=$v' <<<"$body")
+  done
+  jira_curl PUT "$(_jira_issue_path)/$key" "$body"
+  echo "updated $key"
+}
+
+_jira_issue_delete() {
+  local key="${1:-}"
+  [[ -z "$key" ]] && { echo "Usage: jira issue delete <KEY>" >&2; return 1; }
+  jira_curl DELETE "$(_jira_issue_path)/$key"
+  echo "deleted $key"
+}
+
+_jira_issue_comment() {
+  local key="${1:-}" text="${2:-}"
+  [[ -z "$key" || -z "$text" ]] && { echo "Usage: jira issue comment <KEY> <TEXT>" >&2; return 1; }
+  local body
+  body=$(jq -nc --argjson b "$(jira_text_to_adf "$text")" '{body:$b}')
+  jira_curl POST "$(_jira_issue_path)/$key/comment" "$body" | jira_lean '.'
+}
+
+_jira_issue_transitions() {
+  local key="${1:-}"
+  [[ -z "$key" ]] && { echo "Usage: jira issue transitions <KEY>" >&2; return 1; }
+  jira_curl GET "$(_jira_issue_path)/$key/transitions" | jira_lean '{transitions: [.transitions[] | {id, name}]}'
+}
+
+_jira_issue_transition() {
+  local key="${1:-}" want="${2:-}"
+  [[ -z "$key" || -z "$want" ]] && { echo "Usage: jira issue transition <KEY> <NAME|ID>" >&2; return 1; }
+  local id
+  if [[ "$want" =~ ^[0-9]+$ ]]; then
+    id="$want"
+  else
+    local list matches n
+    list=$(jira_curl GET "$(_jira_issue_path)/$key/transitions") || return 1
+    matches=$(jq -c --arg w "$want" '[.transitions[] | select((.name|ascii_downcase)==($w|ascii_downcase)) | .id]' <<<"$list")
+    n=$(jq 'length' <<<"$matches")
+    if [[ "$n" -eq 0 ]]; then
+      echo "jira: no transition matches '$want'. Available: $(jq -r '[.transitions[].name]|join(", ")' <<<"$list")" >&2
+      return 1
+    elif [[ "$n" -gt 1 ]]; then
+      echo "jira: transition '$want' is ambiguous (matched ids: $(jq -r 'join(", ")' <<<"$matches"))" >&2
+      return 1
+    fi
+    id=$(jq -r '.[0]' <<<"$matches")
+  fi
+  jira_curl POST "$(_jira_issue_path)/$key/transitions" "$(jq -nc --arg i "$id" '{transition:{id:$i}}')"
+  echo "transitioned $key -> $id"
+}
+
+_jira_issue_assign() {
+  local key="${1:-}" who="${2:-}"
+  [[ -z "$key" || -z "$who" ]] && { echo "Usage: jira issue assign <KEY> <ACCOUNT_ID|->" >&2; return 1; }
+  jira_curl PUT "$(_jira_issue_path)/$key/assignee" "$(_jira_assignee_obj "$who")"
+  echo "assigned $key"
+}

package/plugins/jira/skills/jira/scripts/lib/paginate.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# paginate.sh — follow Jira's two pagination models and concatenate items.
+#   token  : v3 /search/jql — nextPageToken, no total; POST, carry the token.
+#   offset : v2 /search and all Agile endpoints — startAt/maxResults/total.
+# Emits a JSON array of every item under ITEMS_KEY across all pages. Sourced;
+# depends on jira_curl from http.sh.
+
+# jira_paginate MODE METHOD PATH ITEMS_KEY [BODY]
+#   MODE = token | offset ; ITEMS_KEY = issues | values ; BODY = JSON (default {})
+jira_paginate() {
+  local mode="$1" method="$2" path="$3" items="$4" body="${5:-}"
+  [[ -z "$body" ]] && body='{}'
+  local acc='[]' page req url max token="" start=0 total got last guard=0
+  max=$(jq -r '.maxResults // 50' <<<"$body")
+
+  while (( guard++ < 1000 )); do
+    req="$body"; url="$path"
+    if [[ "$mode" == "token" ]]; then
+      [[ -n "$token" ]] && req=$(jq -c --arg t "$token" '. + {nextPageToken:$t}' <<<"$body")
+      page=$(jira_curl "$method" "$url" "$req") || return 1
+    elif [[ "$method" == "GET" ]]; then
+      local sep="?"; [[ "$url" == *"?"* ]] && sep="&"
+      url="${url}${sep}startAt=${start}&maxResults=${max}"
+      page=$(jira_curl GET "$url") || return 1
+    else
+      req=$(jq -c --argjson s "$start" --argjson m "$max" '. + {startAt:$s, maxResults:$m}' <<<"$body")
+      page=$(jira_curl "$method" "$url" "$req") || return 1
+    fi
+
+    acc=$(jq -c --argjson acc "$acc" --arg k "$items" '$acc + (.[$k] // [])' <<<"$page")
+
+    if [[ "$mode" == "token" ]]; then
+      token=$(jq -r '.nextPageToken // empty' <<<"$page")
+      last=$(jq -r '.isLast // false' <<<"$page")
+      [[ "$last" == "true" || -z "$token" ]] && break
+    else
+      total=$(jq -r '.total // 0' <<<"$page")
+      got=$(jq -r --arg k "$items" '(.[$k] // []) | length' <<<"$page")
+      (( got == 0 )) && break
+      start=$(( start + got ))
+      (( start >= total )) && break
+    fi
+  done
+  printf '%s\n' "$acc"
+}

package/plugins/jira/skills/jira/scripts/lib/plan-parse.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Plan-doc parsing for the `plan` family: pull the machine-readable steps block
+# and the `**Issue:**` header key out of a jira plan doc. Pure functions, jq-only,
+# no command execution and no `set` (this is a sourced library).
+# Source via:   . "${BASH_SOURCE[0]%/*}/plan-parse.sh"
+#
+# The steps-block grammar mirrors toolu's plan-ledger-parse.sh so a jira plan doc
+# stays readable by the same tooling: an exact `## Steps (machine-readable)`
+# heading followed by the first ```json fence.
+
+# jira_plan_parse_steps PLAN_DOC
+# Print the normalized steps JSON array (jq-compacted) on stdout. Validates the
+# block is a non-empty array whose every element has non-empty string
+# id/title/check. Backfills the optional authored fields (activity -> null).
+# Missing heading/block, empty array, or malformed json -> stderr + non-zero.
+jira_plan_parse_steps() {
+  local doc="$1" block
+  if [ ! -f "$doc" ]; then
+    echo "jira plan: plan doc not found: $doc" >&2
+    return 1
+  fi
+  block=$(awk '
+    /^## Steps \(machine-readable\)[[:space:]]*$/ { in_steps = 1; next }
+    in_steps && !in_block && /^```json[[:space:]]*$/ { in_block = 1; next }
+    in_block && /^```[[:space:]]*$/ { exit }
+    in_block { print }
+  ' "$doc")
+  if [ -z "$block" ]; then
+    echo "jira plan: no '## Steps (machine-readable)' json block in $doc" >&2
+    return 1
+  fi
+  if ! jq -e '
+    type == "array"
+    and length > 0
+    and all(.[];
+      (.id    | type == "string" and length > 0) and
+      (.title | type == "string" and length > 0) and
+      (.check | type == "string" and length > 0))
+  ' <<< "$block" >/dev/null 2>&1; then
+    echo "jira plan: steps block in $doc is not a non-empty array of {id,title,check} strings" >&2
+    return 1
+  fi
+  jq -c 'map(.activity = (.activity // null))' <<< "$block"
+}
+
+# jira_plan_doc_field DOC FIELD
+# Print the trimmed value of an inline-bold `**<FIELD>:**` from a packed doc
+# header line, or empty string when absent. Never errors — a missing field is a
+# valid signal, not a failure. Same extraction as toolu's pl_doc_field.
+jira_plan_doc_field() {
+  local doc="$1" field="$2"
+  [ -n "$doc" ] && [ -f "$doc" ] || return 0
+  [ -n "$field" ] || return 0
+  grep -m1 -F "**${field}:**" "$doc" 2>/dev/null \
+    | sed -E "s/.*\\*\\*${field}:\\*\\*[[:space:]]*//; s/[[:space:]]+\\*\\*[^*]+:\\*\\*.*$//; s/^[[:space:]]+//; s/[[:space:]]+$//"
+}
+
+# jira_plan_issue_key DOC
+# Print the issue key declared by the doc's `**Issue:** <KEY>` header. A key must
+# look like a Jira key (LETTERS-DIGITS); anything else is rejected so a malformed
+# header can never steer the ledger filename.
+jira_plan_issue_key() {
+  local doc="$1" key
+  key=$(jira_plan_doc_field "$doc" "Issue")
+  if [[ ! "$key" =~ ^[A-Za-z][A-Za-z0-9_]*-[0-9]+$ ]]; then
+    echo "jira plan: doc is missing a valid '**Issue:** <KEY>' header: $doc" >&2
+    return 1
+  fi
+  printf '%s\n' "$key"
+}

package/plugins/jira/skills/jira/scripts/lib/plan-run.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Check runner for the `plan` family: probe Jira once, then execute each step's
+# `check` and record the verdict in the ledger. No `set` (sourced library).
+# Source via:   . "${BASH_SOURCE[0]%/*}/plan-run.sh"
+# Requires plan-parse.sh + plan-store.sh to be sourced first.
+#
+# A step is green iff its check exits 0. Because every check is a live Jira REST
+# assertion, green means "Jira agrees", not "the agent says so".
+#
+# Infra failure is NOT a Jira disagreement. A missing credential, an unreachable
+# host, or a broken jq pipe would each exit non-zero and land every step `red` --
+# flipping dashboard cards to Blocked for a reason that has nothing to do with
+# the ticket. So we probe once with `user whoami` and, on failure, abort before
+# writing anything: statuses are left exactly as they were.
+
+# jira_plan_cli
+# Resolve the jira CLI a check invokes as "$JIRA". JIRA_CLI overrides it, which
+# is how the bats sandbox points checks at its stubbed copy instead of the host's.
+jira_plan_cli() {
+  if [ -n "${JIRA_CLI:-}" ]; then
+    printf '%s\n' "$JIRA_CLI"
+  elif [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+    printf '%s/jira/jira.sh\n' "$TOOLU_CONFIG_DIR"
+  elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || {
+    [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ];
+  }; then
+    printf '%s/jira/jira.sh\n' "${CODEX_HOME:-$HOME/.codex}"
+  else
+    printf '%s/jira/jira.sh\n' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+  fi
+}
+
+# jira_plan_probe CLI
+# Confirm Jira is reachable and the credentials work. Zero on success.
+jira_plan_probe() {
+  "$1" user whoami >/dev/null 2>&1
+}
+
+# jira_plan_exec_check CLI CHECK ROOT
+# Run CHECK with $JIRA bound and cwd at ROOT. Prints combined output; returns the
+# check's exit code. Never aborts the caller under `set -e`.
+jira_plan_exec_check() {
+  local cli="$1" check="$2" root="$3" out code
+  if out=$(cd "$root" && JIRA="$cli" bash -c "$check" 2>&1); then code=0; else code=$?; fi
+  printf '%s' "$out"
+  return "$code"
+}
+
+# jira_plan_run KEY DOC [--step ID] [--activity LABEL]
+# Merge the doc's steps over the persisted ledger, probe Jira, then run either
+# one step (--step) or all of them, writing the ledger after each transition so
+# the dashboard sees `running` while a check is in flight.
+# Returns non-zero if any executed step ended red.
+jira_plan_run() {
+  local key="$1" doc="$2"; shift 2
+  local only="" activity="" cli root state steps prev ledger targets id check out code failed=0
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --step)     only="${2:-}"; shift 2 ;;
+      --activity) activity="${2:-}"; shift 2 ;;
+      *) echo "jira plan run: unknown option '$1'" >&2; return 1 ;;
+    esac
+  done
+
+  steps=$(jira_plan_parse_steps "$doc") || return 1
+  root=$(jira_plan_repo_root)
+  state=$(jira_plan_ledger_path "$key") || return 1
+  prev=$(jira_plan_read "$state" 2>/dev/null) || prev="null"
+  ledger=$(jira_plan_build "$key" "$doc" "$steps" "$prev") || return 1
+
+  if [ -n "$only" ] && ! jq -e --arg id "$only" 'any(.steps[]; .id == $id)' <<< "$ledger" >/dev/null; then
+    echo "jira plan run: no step '$only' in $doc" >&2
+    return 1
+  fi
+
+  cli=$(jira_plan_cli)
+  if [ ! -x "$cli" ] && [ ! -f "$cli" ]; then
+    echo "jira plan run: jira CLI not found at $cli (set JIRA_CLI)" >&2
+    return 1
+  fi
+  # Probe BEFORE the first write: an unreachable Jira must not manufacture reds.
+  if ! jira_plan_probe "$cli"; then
+    echo "jira plan run: cannot reach Jira (user whoami failed) — no step statuses were written" >&2
+    return 1
+  fi
+
+  if [ -n "$only" ]; then targets="$only"; else targets=$(jq -r '.steps[].id' <<< "$ledger"); fi
+
+  while IFS= read -r id; do
+    [ -n "$id" ] || continue
+    check=$(jq -r --arg id "$id" '.steps[] | select(.id==$id) | .check' <<< "$ledger")
+
+    # First write: running + started_at (+ activity), so the dashboard shows it in flight.
+    ledger=$(jira_plan_set_step "$ledger" "$id" "$(jq -n --arg now "$(jira_plan_now)" --arg a "$activity" \
+      '{status:"running", started_at:$now, exit_code:null, evidence_tail:null}
+       + (if $a == "" then {} else {activity:$a} end)')") || return 1
+    jira_plan_write "$state" "$ledger" || return 1
+
+    if out=$(jira_plan_exec_check "$cli" "$check" "$root"); then code=0; else code=$?; fi
+
+    # Second write: the verdict.
+    ledger=$(jira_plan_set_step "$ledger" "$id" "$(jq -n \
+      --arg st "$([ "$code" -eq 0 ] && echo green || echo red)" \
+      --argjson ec "$code" \
+      --arg now "$(jira_plan_now)" \
+      --argjson ev "$(jira_plan_evidence "$out")" \
+      '{status:$st, exit_code:$ec, last_run:$now, evidence_tail:$ev, started_at:null}')") || return 1
+    jira_plan_write "$state" "$ledger" || return 1
+
+    if [ "$code" -eq 0 ]; then echo "green  $id"; else echo "red    $id (exit $code)"; failed=1; fi
+  done <<< "$targets"
+
+  return "$failed"
+}

package/plugins/jira/skills/jira/scripts/lib/plan-store.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Ledger store for the `plan` family: resolve the ledger path, merge authored
+# steps over persisted status, recompute the summary, and write atomically.
+# Pure functions, jq-only, no command execution and no `set` (sourced library).
+# Source via:   . "${BASH_SOURCE[0]%/*}/plan-store.sh"
+#
+# Emits schema version 1, the same document plugins/toolu/dashboard/state.ts
+# reads. Two fields are deliberate and load-bearing:
+#   base_branch: ""   -> dashboard currentDiffSha() returns null, so no Jira step
+#                        is ever marked `stale` when unrelated code commits move
+#                        the repo diff (state.ts: `if (!base) return null`).
+#   diff_sha:    null -> a Jira step's freshness is not a function of the code diff.
+# The file is named jira-<KEY>.json, never <branch-slug>.json, so toolu's push
+# gate (which stats only "$ledger_dir/<branch-slug>.json") can never block a push
+# on Jira state.
+
+# jira_plan_repo_root
+# Print the repo root, or the cwd when not inside a git work tree.
+jira_plan_repo_root() {
+  git rev-parse --show-toplevel 2>/dev/null || pwd
+}
+
+# This skill is self-contained and cannot source the toolu plugin's host
+# adapter. Mirror only its host-native project directory decision here.
+jira_plan_project_dirname() {
+  if [ -n "${TOOLU_PROJECT_CONFIG_DIRNAME:-}" ]; then
+    printf '%s\n' "$TOOLU_PROJECT_CONFIG_DIRNAME"
+  elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+    printf '.codex\n'
+  else
+    printf '.claude\n'
+  fi
+}
+
+# jira_plan_require_key KEY
+# Accept only a well-formed Jira key (LETTERS-DIGITS). Both path builders below
+# interpolate the key into a filename, so anything else -- a slash, a `..`, an
+# absolute path -- must be rejected here rather than escaping the ledger dir.
+jira_plan_require_key() {
+  local key="${1:-}"
+  if [[ ! "$key" =~ ^[A-Za-z][A-Za-z0-9_]*-[0-9]+$ ]]; then
+    echo "jira plan: not a valid issue key: '${key}'" >&2
+    return 1
+  fi
+}
+
+# jira_plan_ledger_path KEY
+# Print <repo_root>/<host-dir>/tmp/plan-ledger/jira-<KEY>.json.
+jira_plan_ledger_path() {
+  local key="$1" project_dir
+  jira_plan_require_key "$key" || return 1
+  project_dir=$(jira_plan_project_dirname)
+  printf '%s\n' "$(jira_plan_repo_root)/${project_dir}/tmp/plan-ledger/jira-${key}.json"
+}
+
+# jira_plan_doc_path KEY
+# Print <repo_root>/<host-dir>/tmp/jira/plans/<KEY>.md.
+jira_plan_doc_path() {
+  local key="$1" project_dir
+  jira_plan_require_key "$key" || return 1
+  project_dir=$(jira_plan_project_dirname)
+  printf '%s\n' "$(jira_plan_repo_root)/${project_dir}/tmp/jira/plans/${key}.md"
+}
+
+# jira_plan_now — ISO-8601 UTC, second precision.
+jira_plan_now() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+# jira_plan_evidence COMBINED_OUTPUT
+# JSON-encode the last 10 lines of a check's combined stdout+stderr, capped to
+# ~2000 bytes. Prints a quoted JSON string. Mirrors toolu's pl_evidence.
+jira_plan_evidence() {
+  printf '%s' "$1" | tail -n 10 | head -c 2000 | jq -Rs .
+}
+
+# jira_plan_read STATE_FILE
+# Print the ledger json. Absent, empty, or unparseable -> non-zero, no output.
+jira_plan_read() {
+  local f="$1" content
+  [ -s "$f" ] || return 1
+  content=$(cat "$f" 2>/dev/null) || return 1
+  jq -e . <<< "$content" >/dev/null 2>&1 || return 1
+  printf '%s\n' "$content"
+}
+
+# jira_plan_write STATE_FILE JSON
+# Validate, then write atomically (temp + mv), creating the parent dir.
+jira_plan_write() {
+  local f="$1" json="$2" dir tmp
+  if ! jq -e . <<< "$json" >/dev/null 2>&1; then
+    echo "jira plan: refusing to write invalid ledger json to $f" >&2
+    return 1
+  fi
+  dir=$(dirname "$f")
+  mkdir -p "$dir" || { echo "jira plan: cannot create ledger dir: $dir" >&2; return 1; }
+  tmp="$f.tmp.$$"
+  if ! jq . <<< "$json" > "$tmp" 2>/dev/null; then
+    rm -f "$tmp"; echo "jira plan: failed to stage ledger to $tmp" >&2; return 1
+  fi
+  if ! mv "$tmp" "$f"; then
+    rm -f "$tmp"; echo "jira plan: atomic mv failed for $f" >&2; return 1
+  fi
+}
+
+# jira_plan_recompute LEDGER_JSON
+# Recompute summary{} and next from steps[]. `stale` is always 0 and
+# `fresh_green` equals `green`: Jira freshness does not depend on the code diff.
+# `next` is the first step that is not green. Note the dashboard derives its
+# status dot and progress from steps[] (aggregate.ts countSteps), not from this
+# summary — summary must simply agree with steps[].
+jira_plan_recompute() {
+  jq '
+    (.steps | length) as $total
+    | (.steps | map(select(.status=="green"))  | length) as $green
+    | (.steps | map(select(.status=="red"))    | length) as $red
+    | (.steps | map(select(.status=="pending"))| length) as $pending
+    | (.steps | map(select(.status=="running"))| length) as $running
+    | .summary = { total: $total, green: $green, red: $red, pending: $pending,
+                   running: $running, stale: 0, fresh_green: $green, retried: 0 }
+    | .next = ((.steps | map(select(.status != "green")) | first | .id) // null)
+  '
+}
+
+# jira_plan_build KEY PLAN_DOC STEPS_JSON [PREV_LEDGER_JSON]
+# Build the full ledger document. Authored fields (title/check/activity) come
+# from the doc; execution state (status/started_at/exit_code/last_run/
+# evidence_tail) is carried over from PREV by step id, defaulting to pending.
+# A step dropped from the doc disappears; a new one arrives pending.
+jira_plan_build() {
+  local key="$1" doc="$2" steps="$3" prev="${4:-null}" now
+  now=$(jira_plan_now)
+  jq -n \
+    --argjson steps "$steps" \
+    --argjson prev "$prev" \
+    --arg branch "jira-${key}" \
+    --arg doc "$doc" \
+    --arg now "$now" '
+    ((($prev.steps // []) | map({ (.id): . }) | add) // {}) as $old
+    | {
+        version: 1,
+        branch: $branch,
+        base_branch: "",
+        plan_doc: $doc,
+        updated_at: $now,
+        summary: {},
+        next: null,
+        steps: ($steps | map(
+          ($old[.id] // {}) as $p | {
+            id, title, check,
+            status:        ($p.status // "pending"),
+            started_at:    ($p.started_at // null),
+            activity:      (.activity // $p.activity // null),
+            exit_code:     ($p.exit_code // null),
+            diff_sha:      null,
+            last_run:      ($p.last_run // null),
+            evidence_tail: ($p.evidence_tail // null)
+          }))
+      }' | jira_plan_recompute
+}
+
+# jira_plan_set_step LEDGER_JSON ID FIELDS_JSON
+# Merge FIELDS_JSON into the step with the given id, then recompute + restamp.
+jira_plan_set_step() {
+  local ledger="$1" id="$2" fields="$3"
+  jq --arg id "$id" --argjson f "$fields" --arg now "$(jira_plan_now)" '
+    .steps = (.steps | map(if .id == $id then . + $f else . end))
+    | .updated_at = $now
+  ' <<< "$ledger" | jira_plan_recompute
+}

package/plugins/jira/skills/jira/scripts/lib/plan.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# `plan` family: scaffold a plan doc for a ticket, run its checks, and keep a
+# dashboard-readable ledger at <repo>/.claude/tmp/plan-ledger/jira-<KEY>.json.
+#
+# jira.sh sources only lib/<family>.sh, so this file pulls in its own deps —
+# including issue.sh, because `plan init` titles the doc from a live `issue get`.
+# Sourcing is relative to THIS file, not $LIB: $LIB is set by jira.sh alone, so a
+# test that sources plan.sh directly would otherwise expand to "/plan-parse.sh".
+_jira_plan_lib="${BASH_SOURCE[0]%/*}"
+# shellcheck source=/dev/null
+. "$_jira_plan_lib/plan-parse.sh"
+# shellcheck source=/dev/null
+. "$_jira_plan_lib/plan-store.sh"
+# shellcheck source=/dev/null
+. "$_jira_plan_lib/plan-run.sh"
+# shellcheck source=/dev/null
+. "$_jira_plan_lib/issue.sh"
+
+_jira_plan_usage() {
+  cat >&2 <<'EOF'
+jira plan — decompose ticket work into verifiable steps the dashboard renders
+
+  plan init <KEY>                                 scaffold the plan doc for a ticket
+  plan run <DOC> [--step <id>] [--activity <s>]   run checks, write the ledger
+  plan status <KEY>                               print the ledger summary
+  plan path <KEY>                                 print the ledger path
+
+Every step's `check` must be a live Jira assertion that exits 0 only when Jira
+itself reflects the change.
+EOF
+  return 1
+}
+
+# jira_plan_init KEY
+# Write <repo>/.claude/tmp/jira/plans/<KEY>.md, titled from a live `issue get`.
+# Refuses to clobber an existing doc.
+jira_plan_init() {
+  local key="${1:-}" doc summary
+  [ -n "$key" ] || { echo "jira plan init: needs an issue key" >&2; return 1; }
+  doc=$(jira_plan_doc_path "$key") || return 1
+  if [ -e "$doc" ]; then
+    echo "jira plan init: $doc already exists" >&2
+    return 1
+  fi
+  summary=$(jira_issue get "$key" | jq -r '.fields.summary // empty') || return 1
+  [ -n "$summary" ] || summary="$key"
+  mkdir -p "$(dirname "$doc")" || return 1
+  cat > "$doc" <<EOF
+# $key — $summary
+
+**Date:** $(date -u +%Y-%m-%d)   **Issue:** $key   **Topic:** $summary
+
+## Steps (machine-readable)
+
+\`\`\`json
+[]
+\`\`\`
+
+Fill the array with {"id","title","check"} objects. A \`check\` is a shell command
+that exits 0 **only when Jira itself reflects the change** — assert against a live
+read, e.g.
+
+    "\$JIRA" issue get $key --lean | jq -e '.status=="Done"' >/dev/null
+
+\`\$JIRA\` is bound to the jira CLI when the check runs. Then: jira.sh plan run $doc
+EOF
+  printf '%s\n' "$doc"
+}
+
+# jira_plan_status KEY — print the ledger summary and each step's status.
+jira_plan_status() {
+  local key="${1:-}" state ledger
+  [ -n "$key" ] || { echo "jira plan status: needs an issue key" >&2; return 1; }
+  state=$(jira_plan_ledger_path "$key") || return 1
+  if ! ledger=$(jira_plan_read "$state"); then
+    echo "jira plan status: no ledger for $key (run: jira.sh plan run <doc>)" >&2
+    return 1
+  fi
+  jq -r '
+    "\(.branch)  \(.summary.green)/\(.summary.total) green   next: \(.next // "-")",
+    (.steps[] | "  \(.status)\t\(.id)\t\(.title)")
+  ' <<< "$ledger"
+}
+
+# jira_plan_path KEY — print the ledger path. Needs no credentials.
+jira_plan_path() {
+  local key="${1:-}"
+  [ -n "$key" ] || { echo "jira plan path: needs an issue key" >&2; return 1; }
+  jira_plan_ledger_path "$key"
+}
+
+jira_plan() {
+  local action="${1:-}" doc key
+  [ $# -gt 0 ] && shift
+  case "$action" in
+    init)   jira_plan_init "$@" ;;
+    status) jira_plan_status "$@" ;;
+    path)   jira_plan_path "$@" ;;
+    run)
+      doc="${1:-}"
+      [ -n "$doc" ] || { echo "jira plan run: needs a plan doc path" >&2; return 1; }
+      shift
+      key=$(jira_plan_issue_key "$doc") || return 1
+      jira_plan_run "$key" "$doc" "$@"
+      ;;
+    *) _jira_plan_usage ;;
+  esac
+}