@cxi-lmai/ci-agent-platform 3.0.0

package/payload/ci-templates/scripts/lib/issue-loop.sh

@@ -0,0 +1,430 @@
+# shellcheck shell=bash
+# Source-only library. Platform abstraction for the issue -> code loop, so the
+# orchestrate.sh and code.sh runners read the same functions on GitLab and
+# GitHub. It complements platform.sh (which covers the MR/PR review loop).
+#
+# Selection: $PIPE_PLATFORM ("gitlab" or "github"), set by pipe_detect_platform.
+# Runtime variables expected (set by each platform's CI template):
+#
+#   GitLab:
+#     PIPE_API_URL         $CI_API_V4_URL
+#     PIPE_PROJECT_ID      $CI_PROJECT_ID
+#     PIPE_TOKEN           bot token with api + write_repository (triage, MR author)
+#     PIPE_TRIGGER_TOKEN   pipeline trigger token (POST /projects/:id/pipeline)
+#   GitHub:
+#     PIPE_REPO            owner/repo (for `gh api`)
+#     GH_TOKEN             bot PAT (PIPE_BOT_TOKEN) with issues + contents + PR
+#     PIPE_CODE_WORKFLOW   filename of the code workflow to dispatch (default claude-issue-pipeline.yml)
+#
+# Blocking model (decision D1): GitHub has no native is_blocked_by. This loop
+# uses the text convention "Blocked by #N" in the issue description. GitLab uses
+# native issue links. See issue_blockers_open_count / issue_children.
+#
+# All functions print to stdout and never call `exit`.
+
+set -u
+
+# =============================================================================
+# GitLab helpers
+# =============================================================================
+
+_gli_api() { echo "$PIPE_API_URL/projects/$PIPE_PROJECT_ID"; }
+
+_gli_ensure_label() {
+  # $1=name $2=color $3=desc. Project-level (generic: no group-admin needed).
+  # The original used group-level labels shared across a group; the template keeps
+  # them project-level so any project works without namespace privileges.
+  local http
+  http=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+    -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$(_gli_api)/labels" \
+    -d "$(jq -n --arg n "$1" --arg c "$2" --arg d "$3" '{name:$n,color:$c,description:$d}')")
+  # 201 created, 409 already exists: both fine.
+  [ "$http" = "201" ] || [ "$http" = "409" ] || echo "[pipeline] WARNING: label '$1' ensure returned HTTP $http" >&2
+}
+
+_gli_issues_by_label() {
+  # $1=label. Returns JSON array of {iid,title,description,labels,milestone_id}.
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" \
+    "$(_gli_api)/issues?labels=$1&state=opened&per_page=${PIPE_ISSUE_SCAN:-20}" \
+    | jq '[.[] | {iid, title: (.title // ""), description: (.description // ""),
+                  labels: ((.labels // []) | join(",")),
+                  milestone_id: (.milestone.id // null)}]'
+}
+
+_gli_issues_closed_by_label() {
+  # $1=label. Closed issues still carrying a lifecycle label (janitor input).
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" \
+    "$(_gli_api)/issues?labels=$1&state=closed&per_page=${PIPE_ISSUE_SCAN:-20}" \
+    | jq '[.[] | {iid}]'
+}
+
+_gli_issue_notes() {
+  # $1=iid. Non-system notes, newest first. The caller (orchestrate.sh) caps
+  # the total volume and adds a visible truncation marker, so the newest and
+  # most relevant comment survives when a long discussion is trimmed.
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" \
+    "$(_gli_api)/issues/$1/notes?per_page=50&sort=desc" \
+    | jq -r '[.[] | select(.system == false) | "**" + .author.name + ":** " + .body] | join("\n\n")'
+}
+
+_gli_issue_body() {
+  # $1=iid. Description only.
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$(_gli_api)/issues/$1" | jq -r '.description // ""'
+}
+
+_gli_issue_meta() {
+  # $1=iid. Returns {iid,title,description,labels}.
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$(_gli_api)/issues/$1" \
+    | jq '{iid, title: (.title // ""), description: (.description // ""), labels: ((.labels // []) | join(","))}'
+}
+
+_gli_issue_state() {
+  # $1=iid. Prints "opened" or "closed".
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$(_gli_api)/issues/$1" | jq -r '.state // "opened"'
+}
+
+_gli_blockers_open_count() {
+  # $1=iid. Count of open issues that block this one (native links).
+  curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$(_gli_api)/issues/$1/links" \
+    | jq '[.[] | select(.link_type == "is_blocked_by" and .state == "opened")] | length' 2>/dev/null || echo 1
+}
+
+_gli_children_state() {
+  # $1=iid. Prints "<total> <open>". New installs keep native links when
+  # available; the comment marker fallback also supports already-decomposed
+  # parents and GitLab editions where issue-link behavior differs.
+  local links total open kids n
+  links=$(curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$(_gli_api)/issues/$1/links")
+  total=$(echo "$links" | jq '[.[] | select(.link_type == "blocks")] | length' 2>/dev/null || echo 0)
+  open=$(echo "$links" | jq '[.[] | select(.link_type == "blocks" and .state == "opened")] | length' 2>/dev/null || echo 1)
+  if [ "${total:-0}" = "0" ]; then
+    kids=$(curl -s -H "PRIVATE-TOKEN: $PIPE_TOKEN" \
+      "$(_gli_api)/issues/$1/notes?per_page=100&sort=desc" \
+      | jq -r '.[].body // empty' 2>/dev/null \
+      | grep -oE '<!-- pipe-children:[^>]*-->' \
+      | head -1 | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+    total=0; open=0
+    for n in $kids; do
+      total=$((total + 1))
+      [ "$(_gli_issue_state "$n")" = "opened" ] && open=$((open + 1))
+    done
+  fi
+  echo "$total $open"
+}
+
+_gli_create_issue() {
+  # $1=title $2=desc $3=labels(comma). Prints new iid or empty.
+  curl -s -X POST -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$(_gli_api)/issues" \
+    -d "$(jq -n --arg t "$1" --arg b "$2" --arg l "$3" '{title:$t,description:$b,labels:$l}')" \
+    | jq -r '.iid // empty'
+}
+
+_gli_link_blocked_by() {
+  # $1=blocked_iid $2=blocking_iid
+  curl -s -X POST -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$(_gli_api)/issues/$1/links" \
+    -d "$(jq -n --argjson t "$2" '{target_issue_iid:$t, link_type:"is_blocked_by"}')" > /dev/null 2>&1 || true
+}
+
+_gli_set_issue_labels() {
+  # $1=iid $2=add(comma) $3=remove(comma). Returns HTTP-independent (best effort).
+  curl -s -X PUT -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$(_gli_api)/issues/$1" \
+    -d "$(jq -n --arg a "$2" --arg r "$3" '{add_labels:$a, remove_labels:$r}')" > /dev/null
+}
+
+_gli_close_issue() {
+  curl -s -X PUT -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$(_gli_api)/issues/$1" -d '{"state_event":"close"}' > /dev/null || true
+}
+
+_gli_issue_comment() {
+  curl -s -X POST -H "PRIVATE-TOKEN: $PIPE_TOKEN" "$(_gli_api)/issues/$1/notes" \
+    --data-urlencode "body=$2" > /dev/null
+}
+
+_gli_code_trigger() {
+  # $1=iid $2=branch. Fires the coder via the Pipeline Trigger API. Returns 0/1.
+  # On failure the API response is logged so token/permission problems are
+  # visible in the job log instead of a bare "trigger failed".
+  # Trigger tokens (glptt-*) are only accepted as the `token` form field of
+  # POST /projects/:id/trigger/pipeline. Passing one as PRIVATE-TOKEN to
+  # /projects/:id/pipeline returns 401 (pilot 2 finding, P7).
+  local out
+  out=$(curl --fail-with-body -s -X POST \
+    --form "token=$PIPE_TRIGGER_TOKEN" \
+    --form "ref=$PIPE_TARGET_BRANCH" \
+    --form "variables[CODER_ISSUE]=$1" \
+    --form "variables[CODER_BRANCH]=$2" \
+    "$(_gli_api)/trigger/pipeline" 2>&1) || {
+    echo "[pipeline]   code trigger API error: $out" >&2
+    return 1
+  }
+}
+
+_gli_mr_create() {
+  # $1=source $2=target $3=title $4=desc $5=labels(comma). Prints web_url.
+  curl --fail-with-body -s -X POST -H "PRIVATE-TOKEN: $PIPE_TOKEN" -H "Content-Type: application/json" \
+    "$(_gli_api)/merge_requests" \
+    -d "$(jq -n --arg s "$1" --arg t "$2" --arg ti "$3" --arg d "$4" --arg l "$5" \
+        '{source_branch:$s, target_branch:$t, title:$ti, description:$d, labels:$l, remove_source_branch:true}')" \
+    | jq -r '.web_url // empty'
+}
+
+# =============================================================================
+# GitHub helpers (gh CLI, GH_TOKEN)
+# =============================================================================
+
+_ghi_ensure_label() {
+  # $1=name $2=color(hex, no #) $3=desc. Repo-level.
+  gh api -X POST "repos/$PIPE_REPO/labels" \
+    -f "name=$1" -f "color=${2#\#}" -f "description=$3" > /dev/null 2>&1 || true
+}
+
+_ghi_issues_by_label() {
+  # $1=label. Returns JSON array; filters out pull requests (they share the
+  # issues endpoint but carry a .pull_request field).
+  gh api --paginate "repos/$PIPE_REPO/issues?labels=$1&state=open&per_page=${PIPE_ISSUE_SCAN:-20}" \
+    | jq -s 'add // []' \
+    | jq '[.[] | select(has("pull_request") | not)
+            | {iid: .number, title: (.title // ""), description: (.body // ""),
+               labels: ((.labels // []) | map(.name) | join(",")),
+               milestone_id: (.milestone.number // null)}]'
+}
+
+_ghi_issues_closed_by_label() {
+  # $1=label. Closed issues still carrying a lifecycle label (janitor input).
+  # PRs share the issues endpoint; keep issues only, closed PR labels stay
+  # as history.
+  gh api "repos/$PIPE_REPO/issues?labels=$1&state=closed&per_page=${PIPE_ISSUE_SCAN:-20}" \
+    | jq '[.[] | select(has("pull_request") | not) | {iid: .number}]'
+}
+
+_ghi_issue_notes() {
+  # $1=iid. Comments newest first (GitHub returns them oldest first, so reverse).
+  # The caller (orchestrate.sh) caps the total volume and adds a visible
+  # truncation marker, so the newest comment survives when the discussion is long.
+  gh api --paginate "repos/$PIPE_REPO/issues/$1/comments?per_page=100" \
+    | jq -s -r 'add // [] | reverse | .[] | "**" + .user.login + ":** " + .body' || true
+}
+
+_ghi_issue_body() {
+  gh api "repos/$PIPE_REPO/issues/$1" --jq '.body // ""'
+}
+
+_ghi_issue_meta() {
+  # $1=iid. Returns {iid,title,description,labels}.
+  gh api "repos/$PIPE_REPO/issues/$1" \
+    | jq '{iid: .number, title: (.title // ""), description: (.body // ""), labels: ((.labels // []) | map(.name) | join(","))}'
+}
+
+_ghi_issue_state() {
+  # Prints "opened" or "closed" (normalised to the GitLab vocabulary).
+  local s; s=$(gh api "repos/$PIPE_REPO/issues/$1" --jq '.state // "open"' 2>/dev/null || echo open)
+  [ "$s" = "closed" ] && echo closed || echo opened
+}
+
+_ghi_link_blocked_by() {
+  # GitHub has no native blocking link. Persist the real issue number in the
+  # dependent issue body after all local decomposition keys have been mapped.
+  # The marker is visible and deliberately idempotent because the release poll
+  # parses the same "Blocked by #N" convention.
+  local blocked="$1" blocker="$2" body marker
+  body=$(_ghi_issue_body "$blocked")
+  marker="Blocked by #$blocker"
+  printf '%s\n' "$body" | grep -qiE "(^|[[:space:]])Blocked by #${blocker}([^0-9]|$)" && return 0
+  gh api -X PATCH "repos/$PIPE_REPO/issues/$blocked" \
+    -f "body=${body}${body:+$'\n\n'}$marker" > /dev/null
+}
+
+_ghi_create_issue() {
+  # $1=title $2=desc $3=labels(comma). Prints new number.
+  local args=() l
+  IFS=',' read -ra _labels <<< "$3"
+  for l in "${_labels[@]}"; do [ -n "$l" ] && args+=(-f "labels[]=$l"); done
+  gh api -X POST "repos/$PIPE_REPO/issues" -f "title=$1" -f "body=$2" "${args[@]}" \
+    --jq '.number // empty'
+}
+
+_ghi_set_issue_labels() {
+  # $1=iid $2=add(comma) $3=remove(comma)
+  local l
+  local IFS=','
+  for l in $2; do [ -n "$l" ] && gh api -X POST "repos/$PIPE_REPO/issues/$1/labels" -f "labels[]=$l" > /dev/null 2>&1 || true; done
+  for l in $3; do [ -n "$l" ] && gh api -X DELETE "repos/$PIPE_REPO/issues/$1/labels/$l" > /dev/null 2>&1 || true; done
+}
+
+_ghi_close_issue() {
+  gh api -X PATCH "repos/$PIPE_REPO/issues/$1" -f "state=closed" > /dev/null 2>&1 || true
+}
+
+_ghi_issue_comment() {
+  gh api -X POST "repos/$PIPE_REPO/issues/$1/comments" -f "body=$2" > /dev/null
+}
+
+_ghi_code_trigger() {
+  # $1=iid $2=branch. Dispatches the code workflow with explicit inputs. Uses
+  # the bot PAT (already in GH_TOKEN) so the coder's push and PR re-trigger
+  # downstream workflows. On failure the API response is logged so token
+  # permission problems (Actions write) are visible in the job log.
+  local out
+  out=$(gh api -X POST "repos/$PIPE_REPO/actions/workflows/${PIPE_CODE_WORKFLOW:-claude-issue-pipeline.yml}/dispatches" \
+    -f "ref=$PIPE_TARGET_BRANCH" \
+    -f "inputs[coder_issue]=$1" -f "inputs[coder_branch]=$2" 2>&1) || {
+    echo "[pipeline]   code dispatch API error: $out" >&2
+    return 1
+  }
+}
+
+_ghi_pr_create() {
+  # $1=source $2=target $3=title $4=desc $5=labels(comma). Prints html_url.
+  # Created as a draft and flipped to ready only after the labels are on
+  # (finding P5): GitHub cannot attach labels at PR creation, so a non-draft
+  # PR emits an `opened` + `labeled` event pair and the review workflow runs
+  # twice. Draft PRs do not trigger the review job, which makes the single
+  # `ready_for_review` event the only trigger. Falls back to a plain PR when
+  # the plan does not support drafts on this repo (free plan, private repo).
+  local url num
+  url=$(gh api -X POST "repos/$PIPE_REPO/pulls" \
+    -f "head=$1" -f "base=$2" -f "title=$3" -f "body=$4" -F "draft=true" --jq '.html_url // empty' 2>/dev/null || true)
+  if [ -z "$url" ]; then
+    url=$(gh api -X POST "repos/$PIPE_REPO/pulls" \
+      -f "head=$1" -f "base=$2" -f "title=$3" -f "body=$4" --jq '.html_url // empty' 2>/dev/null || true)
+  fi
+  num=$(echo "$url" | grep -oE '[0-9]+$' || true)
+  if [ -n "$num" ] && [ -n "$5" ]; then
+    # Labels go through the issues API (a PR is an issue on GitHub).
+    _ghi_set_issue_labels "$num" "$5" ""
+  fi
+  # Flip to ready (a no-op when the fallback already created a non-draft PR).
+  { [ -n "$num" ] && gh pr ready "$num" -R "$PIPE_REPO" > /dev/null 2>&1; } || true
+  echo "$url"
+}
+
+# =============================================================================
+# Public dispatch
+# =============================================================================
+
+issue_ensure_label()       { case "$PIPE_PLATFORM" in gitlab) _gli_ensure_label "$1" "$2" "$3" ;; github) _ghi_ensure_label "$1" "$2" "$3" ;; esac; }
+issues_by_label()          { case "$PIPE_PLATFORM" in gitlab) _gli_issues_by_label "$1" ;; github) _ghi_issues_by_label "$1" ;; esac; }
+issues_closed_by_label()   { case "$PIPE_PLATFORM" in gitlab) _gli_issues_closed_by_label "$1" ;; github) _ghi_issues_closed_by_label "$1" ;; esac; }
+issue_notes()              { case "$PIPE_PLATFORM" in gitlab) _gli_issue_notes "$1" ;; github) _ghi_issue_notes "$1" ;; esac; }
+issue_body()               { case "$PIPE_PLATFORM" in gitlab) _gli_issue_body "$1" ;; github) _ghi_issue_body "$1" ;; esac; }
+issue_meta()               { case "$PIPE_PLATFORM" in gitlab) _gli_issue_meta "$1" ;; github) _ghi_issue_meta "$1" ;; esac; }
+issue_state()              { case "$PIPE_PLATFORM" in gitlab) _gli_issue_state "$1" ;; github) _ghi_issue_state "$1" ;; esac; }
+issue_create()             { case "$PIPE_PLATFORM" in gitlab) _gli_create_issue "$1" "$2" "$3" ;; github) _ghi_create_issue "$1" "$2" "$3" ;; esac; }
+issue_set_labels()         { case "$PIPE_PLATFORM" in gitlab) _gli_set_issue_labels "$1" "$2" "$3" ;; github) _ghi_set_issue_labels "$1" "$2" "$3" ;; esac; }
+issue_close()              { case "$PIPE_PLATFORM" in gitlab) _gli_close_issue "$1" ;; github) _ghi_close_issue "$1" ;; esac; }
+issue_comment()            { case "$PIPE_PLATFORM" in gitlab) _gli_issue_comment "$1" "$2" ;; github) _ghi_issue_comment "$1" "$2" ;; esac; }
+code_trigger()             { case "$PIPE_PLATFORM" in gitlab) _gli_code_trigger "$1" "$2" ;; github) _ghi_code_trigger "$1" "$2" ;; esac; }
+mr_create()                { case "$PIPE_PLATFORM" in gitlab) _gli_mr_create "$1" "$2" "$3" "$4" "$5" ;; github) _ghi_pr_create "$1" "$2" "$3" "$4" "$5" ;; esac; }
+issue_link_blocked_by()    { case "$PIPE_PLATFORM" in gitlab) _gli_link_blocked_by "$1" "$2" ;; github) _ghi_link_blocked_by "$1" "$2" ;; esac; }
+
+# Count how many issues that block $1 are still open. GitLab uses native links,
+# GitHub parses "Blocked by #N" from the issue body (decision D1, text convention).
+issue_blockers_open_count() {
+  case "$PIPE_PLATFORM" in
+    gitlab) _gli_blockers_open_count "$1" ;;
+    github)
+      local body refs n open=0
+      body=$(_ghi_issue_body "$1")
+      # Match "Blocked by #12" / "blocked by #12, #13" case-insensitively.
+      refs=$(printf '%s' "$body" | grep -ioE 'blocked by[^\n]*' | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+      for n in $refs; do
+        [ "$(_ghi_issue_state "$n")" = "opened" ] && open=$((open + 1))
+      done
+      echo "$open"
+      ;;
+  esac
+}
+
+# Prints "<total> <open>" child count for a decomposed parent.
+# GitLab reads native links and falls back to the machine marker. GitHub parses
+# the machine marker from the decomposition comment. The marker lives in a
+# comment, not in the issue body, so both implementations query comments.
+issue_children_state() {
+  case "$PIPE_PLATFORM" in
+    gitlab) _gli_children_state "$1" ;;
+    github)
+      local kids n total=0 open=0
+      kids=$(gh api --paginate "repos/$PIPE_REPO/issues/$1/comments?per_page=100" \
+        --jq '.[].body // empty' 2>/dev/null \
+        | grep -oE '<!-- pipe-children:[^>]*-->' \
+        | tail -1 | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+      for n in $kids; do
+        total=$((total + 1))
+        [ "$(_ghi_issue_state "$n")" = "opened" ] && open=$((open + 1))
+      done
+      echo "$total $open"
+      ;;
+  esac
+}
+
+# =============================================================================
+# Decomposition validation (mechanical gate, runner side)
+# =============================================================================
+# Deterministic re-check of the decomposition JSON the triage-issue skill
+# produced, before the runner mutates the platform (creates sub-issues). The
+# skill is instructed to self-validate; this is the runner's defensive gate.
+# Written in jq (already a hard dependency everywhere in this pipeline), so it
+# needs no extra runtime such as python3.
+#
+# IMPORTANT: the 8 required section headers and the placeholder tokens below MUST
+# stay in sync with the spec template shipped in
+# templates/spec-issue.template.md. If you rename a section
+# header or change a placeholder token in the template, update both lists here.
+DECOMP_REJECT_REASON=""
+pipe_validate_decomposition() {
+  # Prints the first problem to stdout on failure (empty on success). Sets
+  # DECOMP_REJECT_REASON and returns 1 when invalid, 0 when valid.
+  local json="$1"
+  DECOMP_REJECT_REASON=""
+  local reason
+  reason=$(printf '%s' "$json" | jq -r '
+    def required: ["## 1. Outcome","## 2. Context","## 3. Acceptance Criteria",
+                   "## 4. Scope Envelope","## 5. Existing Code Anchors","## 6. Risk Flags",
+                   "## 7. Test Plan","## 8. Out of Scope"];
+    def placeholders: ["<one sentence","<why now","<at least one","<what will be tested","TODO"];
+
+    (.confidence // "") as $conf
+    | (.sub_issues // []) as $subs
+    | [ $subs[].key ] as $keys
+    | if ($conf != "high" and $conf != "low") then "confidence must be high or low, got: \($conf)"
+      elif (($subs | length) < 2 or ($subs | length) > 5) then "sub_issues count must be 2-5, got: \($subs | length)"
+      elif ($keys | any(. == null or . == "")) then "every sub_issue needs a non-empty key"
+      else
+        ( [ $subs[] | (.depends_on // [])[] as $d | select(($keys | index($d)) == null) | $d ] | first ) as $unknown
+        | if $unknown != null then "depends_on references unknown key: \($unknown)"
+          else
+            ( [ $subs[]
+                | . as $s
+                | (($s.spec_markdown // "")) as $md
+                | ( required | map(. as $r | select(($md | contains($r)) | not)) ) as $miss
+                | if ($miss | length) > 0 then "sub_issue \($s.key) missing sections: \($miss | join(", "))"
+                  elif (placeholders | any(. as $p | $md | contains($p))) then "sub_issue \($s.key) contains unfilled placeholder text"
+                  else empty end ] | first ) as $secfail
+            | if $secfail != null then $secfail
+              else
+                # Cycle check: iteratively drop nodes whose deps are all removed.
+                ( { rem: [ $subs[] | {key: .key, deps: (.depends_on // [])} ] }
+                  | reduce range(0; ($subs | length)) as $_ (.;
+                      (.rem | map(.key)) as $present
+                      | (.rem | map(. as $e
+                            | select(([ $e.deps[] as $d | select(($present | index($d)) != null) ] | length) == 0))) as $ready
+                      | ($ready | map(.key)) as $rk
+                      | if ($ready | length) == 0 then .
+                        else { rem: (.rem | map(. as $e | select(($rk | index($e.key)) == null))) } end)
+                  | if (.rem | length) > 0 then "depends_on graph contains a cycle" else "" end )
+              end
+          end
+      end
+  ' 2>/dev/null || echo "invalid JSON")
+  if [ -n "$reason" ]; then
+    # shellcheck disable=SC2034  # read by orchestrate.sh once this returns 1
+    DECOMP_REJECT_REASON="$reason"
+    return 1
+  fi
+  return 0
+}