forgedock 1.1.7 → 1.1.9

package/scripts/doctor-pipeline-state.sh

@@ -29,9 +29,11 @@
 # are silently disabled and warrants investigating the underlying `gh` failure.
 #
 # Exit codes:
-#   0 = no findings (pipeline healthy)
+#   0 = no findings (pipeline healthy — all checks ran and passed)
 #   1 = findings present
 #   2 = error (missing deps, bad args)
+#   3 = inconclusive — checks were skipped due to gh API failures (total=0 but checks_skipped>0);
+#       pipeline health cannot be confirmed; treat as UNKNOWN, not healthy
 #
 # Depends on: gh (GitHub CLI), jq, date
 #
@@ -43,6 +45,8 @@
 #   I5  Issues in workflow:in-review with no open PR
 #   I6  PRs open without a FORGE:CONTRACT or FORGE:BUILDER annotation
 #   I7  Orphaned worktree branches (local branches fix/* with no open PR)
+#   I8  FORGE-referenced gists with public visibility (KNOWLEDGE_GIST, MILESTONE_INDEX,
+#       PRIOR_GIST annotations in recent issue comments)
 #
 # /pipeline-health should consume this script's JSON output rather than
 # re-discovering state from scratch.
@@ -401,6 +405,79 @@ while IFS= read -r row; do
   fi
 done < <(echo "$OPEN_PRS" | jq -c '.[]')
 
+# ---------------------------------------------------------------------------
+# I8: FORGE-referenced gists with public visibility
+#
+# Scan the last 100 issues (open + closed) for comments containing
+# FORGE:KNOWLEDGE_GIST, FORGE:MILESTONE_INDEX, or FORGE:PRIOR_GIST annotations.
+# Extract the gist ID from each URL and query gh api gists/{id} --jq .public.
+# A "true" result means a pipeline memory gist is world-readable — CRITICAL finding.
+#
+# Fail-open on gh API errors: a network blip or rate-limit must NOT be reported
+# as a confirmed public gist. Uses add_skip (same pattern as I4/I5) so persistent
+# API degradation surfaces in --json degraded[] without inflating CRITICAL count.
+# ---------------------------------------------------------------------------
+RECENT_ISSUES=$(gh issue list $GH_FLAG \
+  --state all \
+  --limit 100 \
+  --json number \
+  --jq '.[].number' 2>"$GH_STDERR_TMP" || true)
+
+I8_FETCH_ERR=$(cat "$GH_STDERR_TMP")
+if [ -z "$RECENT_ISSUES" ] && [ -n "$I8_FETCH_ERR" ]; then
+  echo "WARNING: gh issue list failed for I8 gist-visibility scan — check inconclusive, skipping: $I8_FETCH_ERR" >&2
+  add_skip "I8" "all" "gh issue list failed: $(bounded_reason "$I8_FETCH_ERR")"
+fi
+
+for issue_num in $RECENT_ISSUES; do
+  # Fetch comments and extract FORGE gist annotation URLs
+  if ! ISSUE_COMMENTS=$(gh issue view "$issue_num" $GH_FLAG \
+    --json comments \
+    --jq '[.comments[].body] | join("\n")' 2>"$GH_STDERR_TMP"); then
+    echo "WARNING: gh issue view failed for #$issue_num (I8) — skipping: $(cat "$GH_STDERR_TMP")" >&2
+    add_skip "I8" "$issue_num" "gh issue view failed: $(bounded_reason "$(cat "$GH_STDERR_TMP")")"
+    continue
+  fi
+
+  # Extract gist URLs from all three FORGE annotation types.
+  # The character class [^\s >]+ matches any non-whitespace, non-space, non-> char,
+  # which covers standard usernames, bot accounts (e.g. rapiercraft-forge[bot]),
+  # and gist hashes — all valid in a gist URL before the closing ' -->'.
+  GIST_URLS=$(echo "$ISSUE_COMMENTS" \
+    | grep -oE '<!-- FORGE:(KNOWLEDGE_GIST|PRIOR_GIST): https://gist\.github\.com/[^ >]+ -->' \
+    | grep -oE 'https://gist\.github\.com/[^ >]+' || true)
+  # FORGE:MILESTONE_INDEX may appear in milestone description, not comments, but
+  # some pipelines also post it as a comment — include it in the scan.
+  MILESTONE_GIST_URLS=$(echo "$ISSUE_COMMENTS" \
+    | grep -oE '<!-- FORGE:MILESTONE_INDEX: https://gist\.github\.com/[^ >]+ -->' \
+    | grep -oE 'https://gist\.github\.com/[^ >]+' || true)
+  ALL_GIST_URLS=$(printf '%s\n%s\n' "$GIST_URLS" "$MILESTONE_GIST_URLS" | grep -v '^$' | sort -u || true)
+
+  for gist_url in $ALL_GIST_URLS; do
+    # Extract gist ID: last path component after the username segment
+    gist_id=$(echo "$gist_url" | sed 's|.*/||')
+    if [ -z "$gist_id" ]; then
+      continue
+    fi
+
+    # Query gist visibility — fail-open on API error (rate limit, auth, network)
+    if ! IS_PUBLIC=$(gh api "gists/${gist_id}" --jq '.public' 2>"$GH_STDERR_TMP"); then
+      echo "WARNING: gh api gists/${gist_id} failed (I8) — skipping: $(cat "$GH_STDERR_TMP")" >&2
+      add_skip "I8" "$issue_num" "gh api gists/${gist_id} failed: $(bounded_reason "$(cat "$GH_STDERR_TMP")")"
+      continue
+    fi
+
+    if [ "$IS_PUBLIC" = "true" ]; then
+      add_finding \
+        "public_forge_gist" "critical" \
+        "$issue_num" "gist_visibility" "0" \
+        "FORGE:KNOWLEDGE_GIST/FORGE:MILESTONE_INDEX/FORGE:PRIOR_GIST" \
+        "gh api gists/${gist_id} --jq '.public'" \
+        "Issue #${issue_num} references a public FORGE gist: ${gist_url} — gist ID: ${gist_id}. Pipeline memory gists (FORGE:KNOWLEDGE_GIST, FORGE:MILESTONE_INDEX, FORGE:PRIOR_GIST) MUST be secret. Public gists expose root causes, file paths, and security findings to the open internet. Invariant I8 broken. Migration: gh gist view ${gist_id} > /tmp/gist_migrate.md && gh gist delete ${gist_id} --yes && gh gist create /tmp/gist_migrate.md --desc '<original description>' (no --public). Then update the annotation URL on issue #${issue_num}."
+    fi
+  done
+done
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------
@@ -429,6 +506,12 @@ if $JSON_MODE; then
     --argjson findings "$FINDINGS_JSON" \
     --argjson summary "$SUMMARY_JSON" \
     '{findings:$findings,summary:$summary}'
+  # WIRE:PROVEN — reachable when gh API fails during a doctor run with no prior findings:
+  # all I1/I2/I3/I6 checks fail and add_skip() is called; CHECKS_SKIPPED > 0; TOTAL stays 0.
+  # Verified by the scenario in #1590: total gh outage → all list checks skipped → previously exit 0.
+  if [ "$TOTAL" -eq 0 ] && [ "$CHECKS_SKIPPED" -gt 0 ]; then
+    exit 3  # INCONCLUSIVE — checks skipped due to gh failures; cannot confirm healthy
+  fi
   [ "$TOTAL" -eq 0 ] && exit 0 || exit 1
 fi
 
@@ -443,11 +526,14 @@ if [ "$CHECKS_SKIPPED" -gt 0 ]; then
 fi
 
 if [ "$TOTAL" -eq 0 ]; then
+  # WIRE:PROVEN — same trigger as JSON mode branch above: TOTAL=0 and CHECKS_SKIPPED>0.
+  # This branch executes when the outer 'if [ "$TOTAL" -eq 0 ]' block is entered
+  # and CHECKS_SKIPPED > 0, i.e., at least one gh API call failed during the run.
   if [ "$CHECKS_SKIPPED" -gt 0 ]; then
     echo "  No stalls detected in checks that ran, but $CHECKS_SKIPPED check(s) were skipped"
     echo "  due to gh API failures — pipeline health is INCONCLUSIVE, not confirmed healthy."
     echo ""
-    exit 0
+    exit 3  # INCONCLUSIVE — cannot confirm healthy when checks were skipped
   fi
   echo "  No stalls detected. Pipeline is healthy."
   echo ""

package/scripts/select-fix-targets.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# select-fix-targets.sh — Deterministic priority-ranked issue selection for autopilot
+#
+# Usage:
+#   select-fix-targets.sh [-R <owner/repo>] [--limit <n>] [--fixture-test]
+#
+#   -R <owner/repo>   : GitHub repository (optional, defaults to current repo)
+#   --limit <n>       : Maximum number of issues to output (optional, default: 10)
+#   --fixture-test    : Run against synthetic fixture data instead of GitHub API.
+#                       Exits 0 if output matches expected ranking, 1 otherwise.
+#                       Use this for wire-through proof per #1731.
+#
+# Output:
+#   One issue number per line, in priority order (highest priority first).
+#   Suitable for: for ISSUE_NUM in $(select-fix-targets.sh); do ... done
+#
+# Ranking algorithm (deterministic — no LLM required):
+#   1. P0 issues first (priority:P0 label)
+#   2. P1 issues second (priority:P1 label)
+#   3. P2 issues third (priority:P2 label)
+#   4. Unlabeled issues (no priority:P* label) are EXCLUDED — never selected autonomously
+#
+#   Tie-breaker within each priority band: oldest createdAt wins.
+#   This ensures fresh self-filed findings (from /autopilot recon) never outrank
+#   older human-filed issues at the same priority level. See: #1752.
+#
+# Exclusions (issues never selected, regardless of priority):
+#   - Issues with needs-human label
+#   - Issues with a milestone (feature-lane issues — autopilot handles these in Phase 3)
+#   - Issues with terminal workflow labels (workflow:merged, workflow:invalid, workflow:decomposed)
+#   - Issues with active workflow labels (workflow:building, workflow:in-review) — already in flight
+#
+# Exit codes: 0 = success (or fixture test passed), 1 = error (or fixture test failed)
+#
+# Added: forge#1752
+
+set -euo pipefail
+
+GH_REPO_ARGS=()
+LIMIT=10
+FIXTURE_TEST=false
+
+# Parse arguments
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R)
+      if [ $# -lt 2 ]; then
+        echo "ERROR: -R requires a value <owner/repo>" >&2
+        echo "Usage: select-fix-targets.sh [-R <owner/repo>] [--limit <n>] [--fixture-test]" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+        echo "ERROR: -R value must be owner/repo format, got: $2" >&2
+        exit 1
+      fi
+      GH_REPO_ARGS=(-R "$2")
+      shift 2
+      ;;
+    --limit)
+      if [ $# -lt 2 ] || ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "ERROR: --limit requires a positive integer" >&2
+        exit 1
+      fi
+      LIMIT="$2"
+      shift 2
+      ;;
+    --fixture-test)
+      FIXTURE_TEST=true
+      shift
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1" >&2
+      echo "Usage: select-fix-targets.sh [-R <owner/repo>] [--limit <n>] [--fixture-test]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Fixture test mode (wire-through proof per #1731)
+# ---------------------------------------------------------------------------
+# Runs the ranking logic against synthetic JSON that exercises every edge case:
+#   - P0 issue (should be first)
+#   - P1 issue (should be second)
+#   - Unlabeled issue (should be excluded)
+#   - Fresh P2 self-filed finding (should be last among selected, after P0 and P1)
+#   - Older P2 issue (should appear before fresh P2 within the P2 band)
+# Expected output order: 100 (P0), 101 (P1, older), 103 (P2, older), 104 (P2, newer)
+# Issues 102 (unlabeled) and 105 (needs-human) must be absent from output.
+#
+# This test does NOT make GitHub API calls — it validates the jq pipeline directly.
+# ---------------------------------------------------------------------------
+if [ "$FIXTURE_TEST" = "true" ]; then
+  FIXTURE_JSON='[
+    {
+      "number": 100,
+      "createdAt": "2026-01-01T00:00:00Z",
+      "milestone": null,
+      "labels": [{"name": "priority:P0"}, {"name": "bug"}]
+    },
+    {
+      "number": 101,
+      "createdAt": "2026-01-02T00:00:00Z",
+      "milestone": null,
+      "labels": [{"name": "priority:P1"}]
+    },
+    {
+      "number": 102,
+      "createdAt": "2026-01-03T00:00:00Z",
+      "milestone": null,
+      "labels": [{"name": "bug"}]
+    },
+    {
+      "number": 103,
+      "createdAt": "2026-03-01T00:00:00Z",
+      "milestone": null,
+      "labels": [{"name": "priority:P2"}]
+    },
+    {
+      "number": 104,
+      "createdAt": "2026-07-08T01:30:00Z",
+      "milestone": null,
+      "labels": [{"name": "priority:P2"}, {"name": "bug"}]
+    },
+    {
+      "number": 105,
+      "createdAt": "2026-01-01T00:00:00Z",
+      "milestone": null,
+      "labels": [{"name": "priority:P0"}, {"name": "needs-human"}]
+    },
+    {
+      "number": 106,
+      "createdAt": "2026-01-01T00:00:00Z",
+      "milestone": {"title": "v2.0"},
+      "labels": [{"name": "priority:P0"}]
+    }
+  ]'
+
+  # Expected order: 100, 101, 103, 104
+  # Excluded: 102 (no priority label), 105 (needs-human), 106 (has milestone)
+  EXPECTED="100
+101
+103
+104"
+
+  ACTUAL=$(echo "$FIXTURE_JSON" | jq -r '
+    # Step 1: Filter out exclusions
+    [.[] | select(
+      .milestone == null and
+      (.labels | map(.name) | any(. == "needs-human" or
+        . == "workflow:merged" or . == "workflow:invalid" or
+        . == "workflow:decomposed" or . == "workflow:building" or
+        . == "workflow:in-review") | not) and
+      # Only include issues with an explicit priority:P* label (unlabeled = excluded)
+      (.labels | map(.name) | any(startswith("priority:P")))
+    )] |
+    # Step 2: Assign numeric priority rank (lower = higher priority)
+    # P0 → 0, P1 → 1, P2 → 2, any other priority:P* → 9 (future-proof)
+    map(. + {
+      "_rank": (
+        .labels | map(.name) |
+        if any(. == "priority:P0") then 0
+        elif any(. == "priority:P1") then 1
+        elif any(. == "priority:P2") then 2
+        else 9
+        end
+      )
+    }) |
+    # Step 3: Sort by rank ASC, then by createdAt ASC (oldest wins within same band)
+    sort_by([._rank, .createdAt]) |
+    # Step 4: Output issue numbers
+    .[].number
+  ')
+
+  if [ "$ACTUAL" = "$EXPECTED" ]; then
+    echo "FIXTURE TEST PASSED — ranking: $(echo "$ACTUAL" | tr '\n' ' ')"
+    echo "Excluded correctly: 102 (unlabeled), 105 (needs-human), 106 (has milestone)"
+    exit 0
+  else
+    echo "FIXTURE TEST FAILED" >&2
+    echo "Expected order: $(echo "$EXPECTED" | tr '\n' ' ')" >&2
+    echo "Actual order:   $(echo "$ACTUAL" | tr '\n' ' ')" >&2
+    echo "" >&2
+    echo "Diff:" >&2
+    diff <(echo "$EXPECTED") <(echo "$ACTUAL") >&2
+    exit 1
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Live mode: query GitHub and apply ranking
+# ---------------------------------------------------------------------------
+
+# Fetch open issues — get all candidates in one API call.
+# JSON fields: number, createdAt, milestone (null or object), labels (array of name objects).
+# Limit to 200 issues to match the rest of autopilot's queries; ranking is applied in jq.
+ISSUES_JSON=$(gh issue list "${GH_REPO_ARGS[@]}" \
+  --state open \
+  --limit 200 \
+  --json number,createdAt,milestone,labels \
+  2>/dev/null || echo '[]')
+
+if [ "$ISSUES_JSON" = "[]" ] || [ -z "$ISSUES_JSON" ]; then
+  echo "" # No issues — empty output is valid (caller loops over nothing)
+  exit 0
+fi
+
+echo "$ISSUES_JSON" | jq -r --argjson limit "$LIMIT" '
+  # Step 1: Filter out exclusions (same logic as fixture test)
+  [.[] | select(
+    .milestone == null and
+    (.labels | map(.name) | any(. == "needs-human" or
+      . == "workflow:merged" or . == "workflow:invalid" or
+      . == "workflow:decomposed" or . == "workflow:building" or
+      . == "workflow:in-review") | not) and
+    # Only include issues with an explicit priority:P* label (unlabeled = excluded)
+    (.labels | map(.name) | any(startswith("priority:P")))
+  )] |
+  # Step 2: Assign numeric priority rank
+  map(. + {
+    "_rank": (
+      .labels | map(.name) |
+      if any(. == "priority:P0") then 0
+      elif any(. == "priority:P1") then 1
+      elif any(. == "priority:P2") then 2
+      else 9
+      end
+    )
+  }) |
+  # Step 3: Sort by rank ASC, then by createdAt ASC (oldest wins within same priority band)
+  sort_by([._rank, .createdAt]) |
+  # Step 4: Apply limit and output issue numbers
+  .[:$limit] | .[].number
+'

package/scripts/transition-label.sh

@@ -2,37 +2,138 @@
 # transition-label.sh — Workflow label state machine for ForgeDock pipeline
 #
 # Usage: transition-label.sh <ISSUE_NUMBER> <GH_FLAG...> <TARGET_STATE>
+#   OR:  transition-label.sh --validate <VERDICT> <ISSUE_NUMBER> [GH_FLAG...]
 #
 #   ISSUE_NUMBER  GitHub issue number (e.g. 674)
 #   GH_FLAG       Repository flag passed to gh (e.g. -R RapierCraftStudios/forgedock)
 #                 May be multiple tokens — pass before TARGET_STATE
 #   TARGET_STATE  One of: investigating, ready-to-build, building, in-review,
-#                         merged, invalid, decomposed
+#                         merged, invalid, decomposed, awaiting-merge
+#
+#   --validate    Sub-command mode: translate an investigation verdict into a
+#                 finding-lifecycle label (needs-validation → validated/false-positive).
+#   VERDICT       One of: CONFIRMED, NOT-CONFIRMED, INVALID, PARTIAL
+#                 CONFIRMED → validated; all others → false-positive
 #
 # Examples:
 #   transition-label.sh 674 -R RapierCraftStudios/forgedock investigating
 #   transition-label.sh 674 -R owner/repo ready-to-build
+#   transition-label.sh --validate CONFIRMED 674 -R owner/repo
+#   transition-label.sh --validate NOT-CONFIRMED 674 -R owner/repo
 #
-# Behavior:
+# Behavior (workflow mode):
 #   1. Validates ISSUE_NUMBER and TARGET_STATE
 #   2. Verifies the issue exists (exits 1 if not)
 #   3. Adds workflow:{TARGET_STATE} label
 #   4. Removes all other workflow:* labels atomically
 #
+# Behavior (--validate mode):
+#   1. Validates VERDICT and ISSUE_NUMBER
+#   2. Verifies issue exists and has needs-validation label (exits 0 silently if not)
+#   3. Adds validated (CONFIRMED) or false-positive (all other verdicts) label
+#   4. Removes needs-validation label
+#   5. Idempotent: if already labeled validated/false-positive, exits 0 silently
+#
 # Exit codes: 0 = success, 1 = error (bad args, issue not found, gh failure)
 
 set -euo pipefail
 
 # ---------------------------------------------------------------------------
-# Argument parsing
+# --validate sub-command: finding lifecycle label transition
+# Signature: --validate <VERDICT> <ISSUE_NUMBER> [GH_FLAG...]
+# Separate from the workflow state machine — operates on needs-validation,
+# validated, false-positive labels only; never touches workflow:* labels.
+# ---------------------------------------------------------------------------
+if [ "${1:-}" = "--validate" ]; then
+  shift
+
+  if [ "$#" -lt 2 ]; then
+    echo "ERROR: Usage: transition-label.sh --validate <VERDICT> <ISSUE_NUMBER> [GH_FLAG...]" >&2
+    echo "       VERDICT: CONFIRMED | NOT-CONFIRMED | INVALID | PARTIAL" >&2
+    echo "       Example: transition-label.sh --validate CONFIRMED 674 -R owner/repo" >&2
+    exit 1
+  fi
+
+  VERDICT="$1"
+  shift
+  ISSUE_NUMBER="$1"
+  shift
+  GH_ARGS=("$@")
+
+  # Validate verdict
+  case "$VERDICT" in
+    CONFIRMED|NOT-CONFIRMED|INVALID|PARTIAL) ;;
+    *)
+      echo "ERROR: Unknown verdict: '$VERDICT'" >&2
+      echo "       Valid verdicts: CONFIRMED, NOT-CONFIRMED, INVALID, PARTIAL" >&2
+      exit 1
+      ;;
+  esac
+
+  # Validate issue number
+  if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+    echo "ERROR: ISSUE_NUMBER must be a positive integer, got: '$ISSUE_NUMBER'" >&2
+    exit 1
+  fi
+
+  # Verify issue exists
+  if ! gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json number >/dev/null 2>&1; then
+    echo "ERROR: Issue #$ISSUE_NUMBER not found (GH_FLAG: ${GH_ARGS[*]:-<none>})" >&2
+    exit 1
+  fi
+
+  # Check if issue carries needs-validation (idempotent gate)
+  CURRENT_LABELS=$(gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json labels \
+    --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+  if ! echo "$CURRENT_LABELS" | grep -q "needs-validation"; then
+    echo "OK: Issue #$ISSUE_NUMBER does not have needs-validation — no action taken (idempotent)"
+    exit 0
+  fi
+
+  # Check if already resolved (idempotent)
+  if echo "$CURRENT_LABELS" | grep -qE "validated|false-positive"; then
+    echo "OK: Issue #$ISSUE_NUMBER already has a resolved verdict label — no action taken (idempotent)"
+    exit 0
+  fi
+
+  # Map verdict to label
+  if [ "$VERDICT" = "CONFIRMED" ]; then
+    TARGET_VERDICT_LABEL="validated"
+    echo "Verdict CONFIRMED → adding 'validated' to issue #$ISSUE_NUMBER..."
+  else
+    TARGET_VERDICT_LABEL="false-positive"
+    echo "Verdict $VERDICT → adding 'false-positive' to issue #$ISSUE_NUMBER..."
+  fi
+
+  # Add verdict label
+  gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --add-label "$TARGET_VERDICT_LABEL"
+
+  # Remove needs-validation
+  gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "needs-validation" 2>/dev/null || true
+
+  echo "OK: needs-validation → $TARGET_VERDICT_LABEL on issue #$ISSUE_NUMBER"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Argument parsing (workflow state machine mode)
 # Signature: <ISSUE_NUMBER> [GH_FLAG...] <TARGET_STATE>
 # We consume ISSUE_NUMBER as $1, TARGET_STATE as the last arg, everything
 # in between is GH_FLAG (e.g. -R RapierCraftStudios/forgedock).
 # ---------------------------------------------------------------------------
 
+# Deferred exit code (forge#1929) — set to 1 by the persistent stale-label
+# removal failure branch below instead of exiting immediately, so that the
+# unconditional needs-human clear step (scoped to awaiting-merge) always
+# gets a chance to run before the script actually exits. Initialized here,
+# before any conditional logic, so `set -u` never sees it unbound.
+TRANSITION_EXIT_CODE=0
+
 if [ "$#" -lt 2 ]; then
   echo "ERROR: Usage: transition-label.sh <ISSUE_NUMBER> [GH_FLAG...] <TARGET_STATE>" >&2
   echo "       Example: transition-label.sh 674 -R RapierCraftStudios/forgedock investigating" >&2
+  echo "       OR:      transition-label.sh --validate CONFIRMED 674 -R owner/repo" >&2
   exit 1
 fi
 
@@ -65,6 +166,7 @@ VALID_STATES=(
   "merged"
   "invalid"
   "decomposed"
+  "awaiting-merge"
 )
 
 # ---------------------------------------------------------------------------
@@ -161,9 +263,146 @@ echo "Adding $EFFECTIVE_LABEL to issue #$ISSUE_NUMBER..."
 gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --add-label "$EFFECTIVE_LABEL"
 
 # ---------------------------------------------------------------------------
-# Remove all other workflow:* labels (best-effort — labels may not all exist)
+# Remove all other workflow:* labels currently on the issue (best-effort)
+#
+# IMPORTANT: `gh issue edit --remove-label` is atomic across its whole
+# comma-separated argument — if ANY label in the list is not a valid label
+# on the repo (e.g. a newly added VALID_STATES entry like awaiting-merge
+# whose repo-side `gh label create` / bootstrap hasn't run yet), the ENTIRE
+# call fails with "not found" and — under `set -euo pipefail` without the
+# `|| true` this used to silently swallow — no labels are removed at all,
+# including ones that DO exist and SHOULD have been cleared (forge#1810
+# follow-up: this exact bug was caught by dogfooding this script against
+# the live repo before `workflow:awaiting-merge` had been bootstrapped).
+#
+# Fix: only ask to remove labels that are BOTH (a) in REMOVE_LABELS (valid
+# states other than the target) AND (b) actually present on the issue right
+# now. A label that was never applied to this issue can't be "not found" on
+# the repo without failing the whole call, and a label the issue doesn't
+# have doesn't need removing anyway — so intersecting against the issue's
+# current labels sidesteps the all-or-nothing failure mode entirely instead
+# of relying on `|| true` to mask it.
+# ---------------------------------------------------------------------------
+CURRENT_ISSUE_LABELS=$(gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json labels \
+  --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+TO_REMOVE=""
+IFS=',' read -ra REMOVE_CANDIDATES <<< "$REMOVE_LABELS"
+for candidate in "${REMOVE_CANDIDATES[@]}"; do
+  case ",$CURRENT_ISSUE_LABELS," in
+    *",$candidate,"*)
+      TO_REMOVE="${TO_REMOVE:+$TO_REMOVE,}$candidate"
+      ;;
+  esac
+done
+
+if [ -n "$TO_REMOVE" ]; then
+  echo "Removing stale workflow:* labels present on the issue ($TO_REMOVE)..."
+  gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "$TO_REMOVE" 2>/dev/null || true
+
+  # -------------------------------------------------------------------------
+  # Post-condition verification + single retry (forge#1915)
+  #
+  # The intersection fix above (forge#1810) already prevents the "unbootstrapped
+  # label 404" all-or-nothing failure — every candidate in $TO_REMOVE is known
+  # to exist on the issue at the time it was computed. But the removal call
+  # itself can still fail for reasons unrelated to label existence (a transient
+  # `gh`/GitHub API hiccup, rate limiting, a dropped connection), and that
+  # failure was previously swallowed unconditionally by `2>/dev/null || true`
+  # with no verification — leaving stale workflow:* labels stacked alongside
+  # the newly-added terminal label with no diagnostic trail. Live evidence:
+  # issue #1892 closed with both workflow:in-review and workflow:merged applied
+  # simultaneously because this exact removal call silently failed once.
+  #
+  # Fix: re-fetch the issue's labels after the removal call. If any label in
+  # $TO_REMOVE is still present, retry the removal once. If it's *still*
+  # present after the retry, this is a real, persistent failure — surface it
+  # loudly (stderr ERROR + non-zero exit) instead of the unconditional "OK".
+  #
+  # forge#1929: the non-zero exit is DEFERRED (via $TRANSITION_EXIT_CODE)
+  # rather than immediate. This block runs before the needs-human clear step
+  # further down, which is scoped to TARGET_STATE=awaiting-merge and must
+  # run regardless of this failure — it is unrelated to stale-label removal.
+  # An immediate `exit 1` here would silently skip that unrelated cleanup
+  # step in the one case (persistent removal failure) it's most important
+  # for the caller to see a consistent, fully-applied label state.
+  # -------------------------------------------------------------------------
+  POST_REMOVE_LABELS=$(gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json labels \
+    --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+  STILL_PRESENT=""
+  IFS=',' read -ra TO_REMOVE_CHECK <<< "$TO_REMOVE"
+  for candidate in "${TO_REMOVE_CHECK[@]}"; do
+    case ",$POST_REMOVE_LABELS," in
+      *",$candidate,"*)
+        STILL_PRESENT="${STILL_PRESENT:+$STILL_PRESENT,}$candidate"
+        ;;
+    esac
+  done
+
+  if [ -n "$STILL_PRESENT" ]; then
+    echo "WARNING: label removal did not take effect for ($STILL_PRESENT) — retrying once..." >&2
+    gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "$STILL_PRESENT" 2>/dev/null || true
+
+    POST_RETRY_LABELS=$(gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json labels \
+      --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+    STILL_PRESENT_AFTER_RETRY=""
+    IFS=',' read -ra RETRY_CHECK <<< "$STILL_PRESENT"
+    for candidate in "${RETRY_CHECK[@]}"; do
+      case ",$POST_RETRY_LABELS," in
+        *",$candidate,"*)
+          STILL_PRESENT_AFTER_RETRY="${STILL_PRESENT_AFTER_RETRY:+$STILL_PRESENT_AFTER_RETRY,}$candidate"
+          ;;
+      esac
+    done
+
+    if [ -n "$STILL_PRESENT_AFTER_RETRY" ]; then
+      echo "ERROR: failed to remove stale label(s) ($STILL_PRESENT_AFTER_RETRY) from issue #$ISSUE_NUMBER after retry — label state machine now inconsistent (issue carries both '$EFFECTIVE_LABEL' and the stale label(s) above)." >&2
+      TRANSITION_EXIT_CODE=1
+    else
+      echo "Retry succeeded — stale label(s) removed."
+    fi
+  fi
+else
+  echo "No stale workflow:* labels present on the issue — nothing to remove."
+fi
+
 # ---------------------------------------------------------------------------
-echo "Removing stale workflow:* labels ($REMOVE_LABELS)..."
-gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "$REMOVE_LABELS" 2>/dev/null || true
+# Clear needs-human (best-effort) — SCOPED to workflow:awaiting-merge only
+#
+# needs-human is NOT a workflow:* label, so it is never included in
+# VALID_STATES/REMOVE_LABELS above. It is a write-only, sticky, terminal
+# label: once a human flags an issue/PR as needing attention, no routine
+# forward-progress transition (investigating, ready-to-build, building,
+# in-review, merged, invalid, decomposed) should silently clear it.
+#
+# The ONE deliberate exception is workflow:awaiting-merge (forge#1809/#1810):
+# a remediated + re-reviewed PR that has moved off needs-human without yet
+# meeting the auto-land bar. That is the single code path allowed to clear
+# needs-human — every other TARGET_STATE must leave a pre-existing
+# needs-human label untouched.
+#
+# Best-effort: `|| true` so a missing label never fails the script under
+# `set -euo pipefail`.
+# ---------------------------------------------------------------------------
+if [ "$TARGET_STATE" = "awaiting-merge" ]; then
+  echo "Clearing needs-human (best-effort, scoped to awaiting-merge)..."
+  gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "needs-human" 2>/dev/null || true
+else
+  echo "Skipping needs-human clear — TARGET_STATE is '$TARGET_STATE', not 'awaiting-merge'."
+fi
+
+# ---------------------------------------------------------------------------
+# Final exit (forge#1929) — honor any deferred failure from the persistent
+# stale-label removal check above. The needs-human clear step just above
+# always ran first, regardless of that failure, so the caller-visible exit
+# code still surfaces the same "fail loud" signal introduced by forge#1915,
+# just after the unrelated cleanup step has had a chance to run.
+# ---------------------------------------------------------------------------
+if [ "$TRANSITION_EXIT_CODE" -ne 0 ]; then
+  echo "FAILED: $EFFECTIVE_LABEL set on issue #$ISSUE_NUMBER, but persistent stale-label removal failure occurred (see ERROR above)." >&2
+  exit "$TRANSITION_EXIT_CODE"
+fi
 
 echo "OK: $EFFECTIVE_LABEL set on issue #$ISSUE_NUMBER"