forgedock 1.1.6 → 1.1.8

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/refresh-bot-token.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# scripts/refresh-bot-token.sh — refresh the rapiercraft-forgedock[bot] installation token.
+#
+# Generates a JWT from the app's private key, exchanges it for a 1-hour
+# installation token, and re-auths the gh CLI. Idempotent — safe to run
+# on every session start or from cron.
+#
+# Supports two installations:
+#   RapierCraftStudios (org)  — installation 144998831 (default)
+#   RapierCraft (personal)   — installation 140233364
+#
+# Usage:  scripts/refresh-bot-token.sh [--pem /path/to/key.pem] [--personal]
+#
+# Env:    FORGEDOCK_APP_PEM — path to private key (default: secrets/rapiercraft-forgedock.pem)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+FORGE_HOME="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+APP_ID="4051319"
+ORG_INSTALLATION_ID="144998831"
+PERSONAL_INSTALLATION_ID="140233364"
+DEFAULT_PEM="$FORGE_HOME/secrets/rapiercraft-forgedock.pem"
+
+# --- Parse args ---
+PEM_PATH="${FORGEDOCK_APP_PEM:-$DEFAULT_PEM}"
+INSTALLATION_ID="$ORG_INSTALLATION_ID"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --pem) PEM_PATH="$2"; shift 2 ;;
+    --personal) INSTALLATION_ID="$PERSONAL_INSTALLATION_ID"; shift ;;
+    *) echo "Unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [[ ! -f "$PEM_PATH" ]]; then
+  echo "ERROR: Private key not found at $PEM_PATH" >&2
+  echo "  Set FORGEDOCK_APP_PEM or pass --pem /path/to/key.pem" >&2
+  exit 1
+fi
+
+# --- Generate JWT and exchange for installation token ---
+INSTALL_TOKEN=$(node -e "
+var crypto = require('crypto');
+var fs = require('fs');
+var https = require('https');
+var pem = fs.readFileSync(process.argv[1], 'utf8');
+var now = Math.floor(Date.now() / 1000);
+var h = Buffer.from(JSON.stringify({alg:'RS256',typ:'JWT'})).toString('base64url');
+var p = Buffer.from(JSON.stringify({iat:now-60,exp:now+(9*60),iss:process.argv[2]})).toString('base64url');
+var s = crypto.createSign('RSA-SHA256');
+s.update(h+'.'+p);
+var jwt = h+'.'+p+'.'+s.sign(pem,'base64url');
+var opts = {
+  hostname: 'api.github.com',
+  path: '/app/installations/'+process.argv[3]+'/access_tokens',
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer '+jwt,
+    'Accept': 'application/vnd.github+json',
+    'User-Agent': 'forgedock-refresh'
+  }
+};
+var req = https.request(opts, function(res) {
+  var body = '';
+  res.on('data', function(c) { body += c; });
+  res.on('end', function() {
+    var t = JSON.parse(body).token;
+    if (!t) { process.stderr.write('API error: '+body); process.exit(1); }
+    process.stdout.write(t);
+  });
+});
+req.end();
+" "$PEM_PATH" "$APP_ID" "$INSTALLATION_ID")
+
+if [[ -z "$INSTALL_TOKEN" ]]; then
+  echo "ERROR: Failed to obtain installation token" >&2
+  exit 1
+fi
+
+# --- Auth gh CLI ---
+echo "$INSTALL_TOKEN" | gh auth login --with-token 2>/dev/null
+
+# --- Clean up stale old bot if present ---
+if gh auth status 2>&1 | grep -q "rapiercraft-forge\[bot\]"; then
+  gh auth logout -h github.com -u "rapiercraft-forge[bot]" 2>/dev/null || true
+fi
+
+if [[ "$INSTALLATION_ID" == "$ORG_INSTALLATION_ID" ]]; then
+  echo "rapiercraft-forgedock[bot] token refreshed — org (RapierCraftStudios) ~1h"
+else
+  echo "rapiercraft-forgedock[bot] token refreshed — personal (RapierCraft) ~1h"
+fi

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,29 +2,122 @@
 # 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).
@@ -33,6 +126,7 @@ set -euo pipefail
 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 +159,7 @@ VALID_STATES=(
   "merged"
   "invalid"
   "decomposed"
+  "awaiting-merge"
 )
 
 # ---------------------------------------------------------------------------
@@ -161,9 +256,65 @@ 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
+else
+  echo "No stale workflow:* labels present on the issue — nothing to remove."
+fi
+
+# ---------------------------------------------------------------------------
+# Clear needs-human (best-effort)
+#
+# needs-human is NOT a workflow:* label, so it is never included in
+# VALID_STATES/REMOVE_LABELS above. Historically no code path ever cleared it
+# (forge#1809/#1810) — it was a write-only, sticky, terminal label even after
+# the pipeline made forward progress past the condition that set it.
+#
+# This script only runs at explicit forward-progress transition points (the
+# dispatcher STOPs on needs-human before ever reaching a transition-label.sh
+# call in normal operation — see commands/work-on.md's terminal-state checks),
+# so clearing needs-human here is safe: it only fires when something has
+# deliberately decided to move the issue/PR to a new state, most notably
+# workflow:awaiting-merge (a remediated + re-reviewed PR moving off
+# needs-human without yet meeting the auto-land bar — see #1809 Q1).
+# Best-effort: `|| true` so a missing label never fails the script under
+# `set -euo pipefail`.
 # ---------------------------------------------------------------------------
-echo "Removing stale workflow:* labels ($REMOVE_LABELS)..."
-gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "$REMOVE_LABELS" 2>/dev/null || true
+echo "Clearing needs-human (best-effort)..."
+gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "needs-human" 2>/dev/null || true
 
 echo "OK: $EFFECTIVE_LABEL set on issue #$ISSUE_NUMBER"