@salesforce/afv-skills 1.42.0 → 1.44.0

package/skills/dx-devops-conflict-resolve/scripts/detect-conflicts.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# detect-conflicts.sh — Non-destructively detect Git merge conflicts between a
+# DevOps Center work item feature branch and a target pipeline-stage branch.
+#
+# DevOps Center is Git-backed: it promotes the work item's feature branch into
+# the target stage branch. This script trial-merges the target INTO the feature
+# branch WITHOUT committing, records the conflicting files, then aborts the trial
+# so the working tree is left exactly as it was found.
+#
+# Usage:   detect-conflicts.sh <feature-branch> <target-branch> [remote]
+# Example: detect-conflicts.sh feature/WI-101 uat origin
+#
+# Exit codes:
+#   0  clean merge  — no conflicts, safe to promote
+#   2  conflicts    — the conflicting files are printed to stdout
+#   1  error        — dirty tree, unknown branch, or fetch failure (stderr)
+set -euo pipefail
+
+FEATURE="${1:?usage: detect-conflicts.sh <feature-branch> <target-branch> [remote]}"
+TARGET="${2:?usage: detect-conflicts.sh <feature-branch> <target-branch> [remote]}"
+REMOTE="${3:-origin}"
+
+# Must be inside a git work tree.
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "ERROR: not inside a git repository." >&2
+  exit 1
+fi
+
+# Refuse to run with a dirty working tree — a trial merge could clobber changes.
+if [ -n "$(git status --porcelain)" ]; then
+  echo "ERROR: working tree is not clean. Commit or stash changes before detecting conflicts." >&2
+  exit 1
+fi
+
+# Remember where to return to, so detection leaves the checkout untouched.
+ORIG_REF="$(git symbolic-ref --quiet --short HEAD || git rev-parse HEAD)"
+
+cleanup() {
+  git merge --abort >/dev/null 2>&1 || git reset --merge >/dev/null 2>&1 || true
+  git checkout --quiet "$ORIG_REF" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+if ! git fetch "$REMOTE" >/dev/null 2>&1; then
+  echo "ERROR: git fetch $REMOTE failed." >&2
+  exit 1
+fi
+
+# Check out the feature branch as a tracking branch if it is not local yet.
+if ! git checkout --quiet "$FEATURE" >/dev/null 2>&1; then
+  if ! git checkout --quiet -b "$FEATURE" "$REMOTE/$FEATURE" >/dev/null 2>&1; then
+    echo "ERROR: cannot check out feature branch '$FEATURE' (local or $REMOTE/$FEATURE)." >&2
+    exit 1
+  fi
+fi
+
+# Confirm the target branch exists on the remote.
+if ! git rev-parse --verify --quiet "$REMOTE/$TARGET" >/dev/null; then
+  echo "ERROR: target branch '$REMOTE/$TARGET' not found." >&2
+  exit 1
+fi
+
+# Trial-merge the target INTO the feature branch, without committing. Capture the
+# merge exit status explicitly — a non-zero status means either merge conflicts
+# (unmerged paths present) OR a non-conflict failure such as unrelated histories.
+set +e
+MERGE_OUT="$(git merge --no-commit --no-ff "$REMOTE/$TARGET" 2>&1)"
+MERGE_STATUS=$?
+set -e
+CONFLICTS="$(git diff --name-only --diff-filter=U || true)"
+
+# Trap-based cleanup aborts the trial merge and restores the original checkout.
+
+# Real merge conflicts: unmerged paths exist. Report them and signal "conflicts".
+if [ -n "$CONFLICTS" ]; then
+  echo "CONFLICTS: merging $REMOTE/$TARGET into $FEATURE conflicts on these files:"
+  printf '%s\n' "$CONFLICTS"
+  exit 2
+fi
+
+# No unmerged paths but the merge still failed — a non-conflict error (e.g.
+# unrelated histories). Never report CLEAN in this case; surface the error.
+if [ "$MERGE_STATUS" -ne 0 ]; then
+  echo "ERROR: git merge of $REMOTE/$TARGET into $FEATURE failed for a non-conflict reason:" >&2
+  printf '%s\n' "$MERGE_OUT" >&2
+  exit 1
+fi
+
+# Merge succeeded with no conflicts — safe to promote.
+echo "CLEAN: no merge conflicts between $FEATURE and $REMOTE/$TARGET."
+exit 0

package/skills/dx-devops-conflict-resolve/scripts/diagnose-deploy-failure.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# diagnose-deploy-failure.sh — Classify a DevOps Center promotion/deploy failure
+# and decide whether a FULL PROMOTION can fix it.
+#
+# DevOps Center promotes by deploying a work item's feature branch into the target
+# stage branch. A promotion can fail for two broad reasons:
+#   1. Merge conflict  — the branches conflict; re-promoting will not help. Resolve
+#      the conflict first (scripts/detect-conflicts.sh + the resolve workflow).
+#   2. Deploy error    — frequently a MISSING DEPENDENCY: the deployed set
+#      references a component it does not include. A FULL promotion (promote ALL
+#      pending changes for the work item, not a partial/selective set) can fix this
+#      ONLY if the missing component actually exists on the feature branch.
+#
+# This script parses the error text; when it finds a missing dependency it checks,
+# with `git show`, whether that component's source file is present on the branch.
+#
+# Usage:   diagnose-deploy-failure.sh <error-file|-> <feature-branch> [target-branch] [remote]
+#          Pass '-' as the first argument to read the error text from stdin.
+# Example: sf project deploy start ... 2>&1 \
+#            | scripts/diagnose-deploy-failure.sh - feature/WI-101 uat origin
+#
+# Output: key=value lines the agent parses —
+#   REASON, CAN_FULL_PROMOTION_FIX, RECOMMENDATION, and when a dependency is parsed
+#   MISSING_DEPENDENCY_TYPE / MISSING_DEPENDENCY_NAME / IN_FEATURE_BRANCH
+#   (+ IN_TARGET_BRANCH when a target branch is given).
+#
+# Exit codes:
+#   0  full promotion CAN fix   — missing component exists on the feature branch
+#   2  merge conflict           — resolve the conflict, do not just re-promote
+#   3  dependency not on branch  — component must be added before promoting
+#   4  no dependency parsed      — inspect the error; a full promotion likely won't help
+#   1  usage / environment error
+set -euo pipefail
+
+ERR_SRC="${1:?usage: diagnose-deploy-failure.sh <error-file|-> <feature-branch> [target-branch] [remote]}"
+FEATURE="${2:?usage: diagnose-deploy-failure.sh <error-file|-> <feature-branch> [target-branch] [remote]}"
+TARGET="${3:-}"
+REMOTE="${4:-origin}"
+
+# Read the error text from a file or stdin.
+if [ "$ERR_SRC" = "-" ]; then
+  ERR="$(cat)"
+elif [ -f "$ERR_SRC" ]; then
+  ERR="$(cat "$ERR_SRC")"
+else
+  echo "ERROR: error source '$ERR_SRC' is not a readable file (use '-' to read stdin)." >&2
+  exit 1
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "ERROR: not inside a git repository." >&2
+  exit 1
+fi
+
+shopt -s nocasematch
+
+# 1. Merge conflict? A full promotion cannot fix it — resolve the conflict instead.
+if [[ "$ERR" =~ (MERGE_CONFLICT|CONFLICTS:) ]]; then
+  echo "REASON=merge_conflict"
+  echo "CAN_FULL_PROMOTION_FIX=false"
+  echo "RECOMMENDATION=This is a merge conflict, not a missing dependency. Resolve it with the conflict workflow (scripts/detect-conflicts.sh, then merge/resolve/commit/push the feature branch), then re-promote."
+  exit 2
+fi
+
+# 2. Try to parse a missing dependency (type + name) from the error text.
+#    Order mirrors the DevOps Center provider: "Variable does not exist" first.
+DEP_TYPE=""
+DEP_NAME=""
+if [[ "$ERR" =~ Variable[[:space:]]+does[[:space:]]+not[[:space:]]+exist:[[:space:]]*([A-Za-z0-9_]+) ]]; then
+  DEP_TYPE="ApexClass"; DEP_NAME="${BASH_REMATCH[1]}"
+elif [[ "$ERR" =~ no[[:space:]]+(ApexClass|ApexTrigger|ApexPage|CustomObject|Flow)[[:space:]]+named[[:space:]]+([A-Za-z0-9_]+)[[:space:]]+found ]]; then
+  DEP_TYPE="${BASH_REMATCH[1]}"; DEP_NAME="${BASH_REMATCH[2]}"
+elif ! [[ "$ERR" =~ (Variable[[:space:]]does[[:space:]]not[[:space:]]exist|Problem:) ]] \
+     && [[ "$ERR" =~ Type:[[:space:]]*(ApexClass|ApexTrigger|ApexPage|Profile|CustomObject|Flow) ]]; then
+  DEP_TYPE="${BASH_REMATCH[1]}"
+  if [[ "$ERR" =~ Component:[[:space:]]*([A-Za-z0-9_]+) ]]; then
+    DEP_NAME="${BASH_REMATCH[1]}"
+  else
+    DEP_TYPE=""   # need both type and name to act
+  fi
+fi
+
+# Canonicalize the metadata type (nocasematch may capture any casing from the error).
+canon_type() {
+  case "$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" in
+    apexclass)    echo "ApexClass" ;;
+    apextrigger)  echo "ApexTrigger" ;;
+    apexpage)     echo "ApexPage" ;;
+    profile)      echo "Profile" ;;
+    customobject) echo "CustomObject" ;;
+    flow)         echo "Flow" ;;
+    *)            echo "" ;;
+  esac
+}
+
+CANON=""
+[ -n "$DEP_TYPE" ] && CANON="$(canon_type "$DEP_TYPE")"
+
+if [ -z "$CANON" ] || [ -z "$DEP_NAME" ]; then
+  echo "REASON=no_dependency_parsed"
+  echo "CAN_FULL_PROMOTION_FIX=false"
+  echo "RECOMMENDATION=Could not identify a missing component from the error. Inspect the full deploy error and fix the underlying metadata/test issue, then re-promote. A full promotion is unlikely to help unless the failure is a missing dependency."
+  exit 4
+fi
+
+# Candidate source paths for the component (standard SFDX layouts).
+paths_for() {
+  local t="$1" n="$2"
+  case "$t" in
+    ApexClass)    printf '%s\n' "force-app/main/default/classes/$n.cls" "main/default/classes/$n.cls" "classes/$n.cls" ;;
+    ApexTrigger)  printf '%s\n' "force-app/main/default/triggers/$n.trigger" "main/default/triggers/$n.trigger" ;;
+    ApexPage)     printf '%s\n' "force-app/main/default/pages/$n.page" "main/default/pages/$n.page" ;;
+    Profile)      printf '%s\n' "force-app/main/default/profiles/$n.profile-meta.xml" "main/default/profiles/$n.profile-meta.xml" ;;
+    CustomObject) printf '%s\n' "force-app/main/default/objects/$n/$n.object-meta.xml" "main/default/objects/$n/$n.object-meta.xml" ;;
+    Flow)         printf '%s\n' "force-app/main/default/flows/$n.flow-meta.xml" "main/default/flows/$n.flow-meta.xml" ;;
+  esac
+}
+
+# Is at least one candidate path present in the branch? Try the local ref, then the remote ref.
+present_in_branch() {
+  local branch="$1" t="$2" n="$3" p
+  while IFS= read -r p; do
+    [ -z "$p" ] && continue
+    if git show "$branch:$p" >/dev/null 2>&1 || git show "$REMOTE/$branch:$p" >/dev/null 2>&1; then
+      return 0
+    fi
+  done <<EOF
+$(paths_for "$t" "$n")
+EOF
+  return 1
+}
+
+IN_FEATURE=false
+if present_in_branch "$FEATURE" "$CANON" "$DEP_NAME"; then IN_FEATURE=true; fi
+
+IN_TARGET=""
+if [ -n "$TARGET" ]; then
+  if present_in_branch "$TARGET" "$CANON" "$DEP_NAME"; then IN_TARGET=true; else IN_TARGET=false; fi
+fi
+
+echo "MISSING_DEPENDENCY_TYPE=$CANON"
+echo "MISSING_DEPENDENCY_NAME=$DEP_NAME"
+echo "IN_FEATURE_BRANCH=$IN_FEATURE"
+[ -n "$IN_TARGET" ] && echo "IN_TARGET_BRANCH=$IN_TARGET"
+
+if [ "$IN_FEATURE" = true ]; then
+  echo "REASON=dependency_in_feature_branch"
+  echo "CAN_FULL_PROMOTION_FIX=true"
+  echo "RECOMMENDATION=The missing component $CANON '$DEP_NAME' exists on the feature branch but was not in the deployed set. A FULL promotion (promote all pending changes for this work item, not a partial set) should include it and fix the failure. Confirm with the user, then re-promote as a full promotion via dx-devops-promote."
+  exit 0
+fi
+
+echo "REASON=dependency_not_in_feature_branch"
+echo "CAN_FULL_PROMOTION_FIX=false"
+echo "RECOMMENDATION=The missing component $CANON '$DEP_NAME' is NOT on the feature branch, so promoting the branch cannot supply it. Add and commit the missing $CANON to the work item's feature branch (or include the work item that owns it), then re-promote."
+exit 3

package/skills/dx-devops-request-status/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: dx-devops-request-status
+description: "Use this skill to poll the status of an asynchronous DevOps Center request — a promotion or deploy operation. Provide the request token returned by dx-devops-promote (the promote response) to check completion, monitor progress, or verify success or failure via sf devops request status. TRIGGER when the user wants to check whether a promotion or deploy finished, monitor an in-flight async request, poll until a request completes, or confirm a request succeeded before finalizing. DO NOT TRIGGER for initiating a promotion or deploy (use dx-devops-promote), for work item creation or status transitions (use dx-devops-work-item-manage), or for conflict detection. Read-only status check — never mutates pipeline state."
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "58.0"
+  relatedSkills:
+    - "dx-devops-promote"
+    - "dx-devops-work-item-manage"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ALMDevopsCorePref"
+    - type: "userPerm"
+      value: "UserHasDevOpsCore"
+---
+
+# DevOps Center Request Status
+
+Polls the status of an asynchronous DevOps Center request — a promotion or deploy operation — by its request token via `sf devops request status`. Provides headless, `--json`-driven, read-only status checks for autonomous release workflows in CI. This skill never mutates pipeline state; it only reports the current status of an in-flight or completed request.
+
+## Scope
+
+- **In scope**: Check the status of a single async request by its request token; interpret the two-level outcome (request-processing `.result.status` vs. the `.result.errorDetails` failure oracle); poll with backoff until a request finishes or a caller-supplied timeout is reached; surface parsed error details on failure
+- **Out of scope**: Initiating a promotion or deploy (use `dx-devops-promote`), work item creation/status updates (use `dx-devops-work-item-manage`), conflict detection, running `sf devops promotion complete` (that is the caller's next step after this skill confirms success), pipeline or project setup
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Request token** (required): the request token returned in the `dx-devops-promote` promote response. Passed via `-i/--request-token`. Without it, this skill cannot proceed — ask for it or obtain it from the prior promote step's output
+- **Target org**: `-o/--target-org <alias>` (required unless the `target-org` config variable is set)
+
+Defaults unless specified:
+- Output format: `--json` for headless consumption
+- Polling interval: 10 seconds between checks; cap total wait at a caller-supplied timeout (default 30 minutes). Never poll faster than every 5 seconds — DOCe API rate limits apply
+
+If the user gives a clear request ("check request a0B…", "poll request a0B… until it finishes"), proceed once you have the request token.
+
+---
+
+## Workflow
+
+All operations use `sf devops request status` with `--json` output. This skill is **read-only** — it issues no mutations. The command's flags and JSON output schema are documented in `references/cli-commands.md`.
+
+### Phase 1 — Authenticate and confirm the request token
+
+1. **Verify org authentication** before any operation:
+   ```bash
+   sf org display --json
+   ```
+   - If it fails, instruct the user to run `sf org login web --set-default --alias <alias>`
+   - Pass `-o/--target-org <alias>` on every subsequent command (required unless the `target-org` config variable is set)
+
+2. **Confirm you have a request token.** If the user initiated a promotion in the same session, reuse the request token captured from the `dx-devops-promote` promote response. If no token is available, STOP and ask for it — do NOT guess or fabricate a token.
+
+### Phase 2 — Single status check (two-level semantics)
+
+> **CRITICAL:** `.result.status` (uppercase, e.g. `SUCCESS`) reports whether the async **request finished processing** — NOT whether the underlying deploy succeeded. A request can show `status: "SUCCESS"` while the deployment itself **failed**. The real outcome oracle is `.result.errorDetails`: **non-null `errorDetails` means the operation failed, even when `status == SUCCESS`.**
+
+3. **Run a single status check** with `scripts/poll-status.sh --once`, which queries the request once and derives the true outcome deterministically (glob-matches the operation-prefixed `.result.status` suffix, then applies the `.result.errorDetails` failure oracle). Do NOT hand-roll the JSON parsing in prose — the script owns the two-level rule so it stays consistent with the polling path:
+   ```bash
+   scripts/poll-status.sh --once <request-token> <target-org-alias>
+   ```
+   Interpret the exit code (the script prints a human-readable line to match):
+   - `0` — request finished and the operation **succeeded** (`errorDetails` null) → hand back to the caller
+   - `2` — request finished but the operation **FAILED** (status suffix `*FAILED*`/`*ERROR*`/`*CANCELED*`, or a `*SUCCESS*` status with non-null `errorDetails`) → the printed line carries the parsed `errorType`/`errorMessage`
+   - `4` — request is **still processing** (non-terminal suffix) → proceed to Phase 3 to poll, or report in-progress for a one-shot check
+   - `1` — query/usage error (bad token, auth, or missing dependency)
+
+### Phase 3 — Poll until terminal (only when asked to wait)
+
+4. **Poll with a bounded loop** when the user asks to wait for completion. Run `scripts/poll-status.sh` and report the final status it prints:
+   ```bash
+   scripts/poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]
+   ```
+   - The script polls every `interval-seconds` (default 10), never sleeps past `timeout-seconds`, stops on a terminal request state, and applies the same two-level outcome check as `--once`. Exit codes: `0` = finished + succeeded (`errorDetails` null), `2` = finished but the operation failed (`errorDetails` set, or status suffix `*FAILED*`/`*ERROR*`/`*CANCELED*`), `3` = timeout, `1` = query/usage error
+   - It is a read-only loop — it issues only `sf devops request status` queries, never mutations
+   - Do NOT hand-roll a polling loop in prose; the script enforces the interval floor, exact timeout, terminal-state detection, and the `errorDetails` outcome check deterministically
+
+### Phase 4 — Report
+
+5. **Report the outcome**:
+   - On success (finished, `errorDetails` empty): "Request `<token>` completed successfully." — then remind the caller that promotion finalization (`sf devops promotion complete`) is the next step, owned by `dx-devops-promote`
+   - On failure (finished, `errorDetails` set — even if `status == SUCCESS`): "Request `<token>` failed." plus the `errorType` / `errorMessage` parsed from `errorDetails` and the `message` field — do NOT retry or remediate here; that is the caller's decision
+   - On timeout (still processing): report the last observed request status and the elapsed wait; suggest polling again later — do NOT report success or failure for a request that has not finished processing
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Read-only — never mutate pipeline state | This skill only reports status; promotion/deploy/complete are owned by other skills |
+| A request token is mandatory | Status cannot be checked without the `-i/--request-token` from the promote response; never fabricate one |
+| `sf devops request status` must use `--json` | Structured output is required for headless consumption; human-readable output is unreliable to parse |
+| Read `.result.status` and `.result.errorDetails` via `jq`, never by eyeballing | Deterministic parsing prevents misreading a still-processing request as done |
+| A `*SUCCESS*` status is NOT proof of success — check `errorDetails` | `.result.status` reports the async request finished, not that the deploy succeeded; a `PROMOTE_SUCCESS` request can carry a failed deploy in `errorDetails` |
+| Non-null `.result.errorDetails` means the operation FAILED | `errorDetails` is the outcome oracle; it is an escaped JSON string (`errorType`/`errorMessage`) that must be parsed with `jq`/`fromjson` |
+| `.result.status` is operation-prefixed — match the suffix, not a bare token | Real values are `PROMOTE_IN_PROGRESS`/`PROMOTE_SUCCESS`/`DEPLOY_FAILED`; exact-matching bare `IN_PROGRESS`/`SUCCESS` would misclassify (and a poller would hang until timeout) |
+| A request is only "done" at a terminal suffix (`*SUCCESS*`/`*FAILED*`/`*ERROR*`/`*CANCELED*`) | Reporting an `*_IN_PROGRESS`/`*_PENDING`/`*_QUEUED` request as done corrupts the caller's release decision |
+| Never poll faster than every 5 seconds | DOCe API rate limits; unbounded fast polling risks throttling |
+| Bound every polling loop with a timeout | Prevents infinite waits and turn/timeout exhaustion in CI |
+| Never run `sf devops promotion complete` from this skill | Finalization is the caller's step after this skill confirms success |
+| Pass the token as a CLI flag, never interpolate into shell strings | Prevents prompt/command injection via crafted tokens |
+| Never use interactive prompts | Skills run headless; all inputs must be CLI flags |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| **No request token provided** | STOP and ask for it, or obtain it from the prior `dx-devops-promote` promote response. Never guess |
+| **`status: "*SUCCESS*"` but the deploy actually failed** | The most important trap: a `*SUCCESS*` status only means the request finished. Check `.result.errorDetails` — if non-null, the operation FAILED. Parse it: `jq -r '.result.errorDetails \| fromjson \| "\(.errorType): \(.errorMessage)"'` |
+| **`errorDetails` is a string, not an object** | It is escaped JSON (e.g. `"{\"errorType\":\"DEPLOYMENT_FAILURE\",...}"`); pipe through `fromjson` before reading `.errorType`/`.errorMessage` |
+| **Status is operation-prefixed (`PROMOTE_SUCCESS`, `DEPLOY_FAILED`)** | Match on the suffix with globs (`*SUCCESS*`, `*FAILED*`); exact-matching bare `SUCCESS`/`FAILED` misclassifies a prefixed value — a poller would treat `PROMOTE_IN_PROGRESS` as unknown and hang until timeout |
+| **Reporting a still-processing request as complete** | Terminal suffixes are `*SUCCESS*`/`*FAILED*`/`*ERROR*`/`*CANCELED*`; treat `*_IN_PROGRESS`/`*_PENDING`/`*_QUEUED`/`*_NEW`/`*_STARTED` as not done — keep polling or report in-progress |
+| **No default org set** | Run `sf org display --json`; if it fails, instruct the user to run `sf org login web --set-default` |
+| **Rate-limit / throttle errors while polling** | Increase the interval (back off); never poll below the 5-second floor |
+| **Infinite wait** | Always pass a timeout to `scripts/poll-status.sh`; on timeout, report the last status rather than blocking |
+| **Confusing request failure with skill failure** | A `Failed` request status is a valid result — report it clearly; do not treat it as a skill error or retry blindly |
+
+---
+
+## Output Expectations
+
+Deliverables vary by mode:
+
+- **Single check**: `.result.status` (request-processing state) plus the derived outcome — on failure, the `errorType`/`errorMessage` parsed from `.result.errorDetails` and the `.result.message` field
+- **Poll-to-completion**: the derived terminal outcome (succeeded or failed, per the `errorDetails` check) plus elapsed wait, or the last observed request status if the timeout was reached first
+
+Outputs are derived from `sf devops request status`. This skill produces no artifacts and mutates nothing.
+
+---
+
+## Cross-Skill Integration
+
+| When | Action |
+|------|--------|
+| A promotion or deploy must be initiated first to get a request token | Delegate to `dx-devops-promote` |
+| Outcome is success (finished, `errorDetails` null) and the promotion still needs finalizing | Hand back to `dx-devops-promote` to run `sf devops promotion complete` |
+| Status reports `Failed` due to a metadata conflict | Report the conflict from `errorDetails`; hand back to `dx-devops-promote` to resolve and re-promote |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/cli-commands.md` | When you need the `sf devops request status` flags, JSON output schema, status-value vocabulary, or error-handling patterns |
+| `examples/polling-workflows.md` | When the user's request matches a common pattern (one-shot check, poll-until-done after a promote, timeout handling, failure reporting) |
+| `scripts/poll-status.sh` | Phase 2 — invoke with `--once` for a single deterministic status check; Phase 3 — invoke without `--once` to poll a request token with a bounded interval and exact timeout until it reaches a terminal state |

package/skills/dx-devops-request-status/examples/polling-workflows.md

@@ -0,0 +1,101 @@
+# Request Status Polling Examples
+
+Common patterns for checking the status of an asynchronous DevOps Center request via `sf devops request status`. Every pattern is **read-only** — it issues only status queries and never mutates pipeline state. The request token is returned by `dx-devops-promote` in the promote response.
+
+---
+
+## Example 1 — One-shot status check (with the two-level outcome check)
+
+**User prompt:** "What's the status of request 708b2286-bbf3-4621-9531-6d94334ff763?"
+
+```bash
+# 1. Verify auth
+sf org display --json
+
+# 2. Single deterministic status check. --once queries once and derives the TRUE
+#    outcome (.result.status alone is not enough — the status is operation-prefixed
+#    and a *SUCCESS* status can carry a failed deploy in errorDetails). The script
+#    owns the two-level rule so it stays consistent with the polling path.
+scripts/poll-status.sh --once 708b2286-bbf3-4621-9531-6d94334ff763 my-devops-org
+# Exit codes: 0 succeeded · 2 operation failed · 4 still processing · 1 query error
+```
+
+For the real response above, `status` is a `*SUCCESS*` value but `errorDetails` is populated, so the script exits `2` and prints the derived failure: **`DEPLOYMENT_FAILURE: classes/HelloMCP.cls-meta.xml: Invalid api version:0.0`**.
+
+**Report:** "Request `708b2286…` finished but the deploy FAILED — `DEPLOYMENT_FAILURE`: invalid API version on `HelloMCP.cls-meta.xml`." Never report success from a `*SUCCESS*` status alone.
+
+---
+
+## Example 2 — Poll until the request completes
+
+**User prompt:** "Poll request a0B000000000200 until it finishes."
+
+```bash
+# scripts/poll-status.sh polls every 10s (default), caps at 30 min (default),
+# stops on a terminal state, and exits non-zero on failure or timeout.
+scripts/poll-status.sh a0B000000000200 my-devops-org
+# Custom interval/timeout: scripts/poll-status.sh a0B000000000200 my-devops-org 15 900
+```
+
+The script prints progress lines while polling and a final line. It applies the two-level outcome check (request-finished AND `errorDetails` null). Exit codes:
+- `0` — request finished and the operation succeeded (`errorDetails` null)
+- `2` — request finished but the operation FAILED (`errorDetails` set, or status suffix `*FAILED*`/`*ERROR*`/`*CANCELED*`) — reason printed to stderr
+- `3` — timeout reached, still processing
+
+**Report:** on exit `0`, "Request `a0B000000000200` completed successfully. Run `sf devops promotion complete` to finalize (owned by `dx-devops-promote`)."
+
+---
+
+## Example 3 — Hand-off from a promotion
+
+**Scenario:** `dx-devops-promote` initiated a promotion and returned a request token. Confirm completion before finalizing.
+
+```bash
+# REQUEST_TOKEN was captured by dx-devops-promote from the promote response.
+
+# Poll it to a terminal state.
+if scripts/poll-status.sh "$REQUEST_TOKEN" my-devops-org; then
+  echo "Request $REQUEST_TOKEN succeeded — ready to finalize."
+  # Finalization is the caller's step (dx-devops-promote), NOT this skill:
+  #   sf devops promotion complete --target-stage-id <target-stage-id> --target-org my-devops-org --json
+else
+  echo "Request $REQUEST_TOKEN did not succeed — see status output above." >&2
+fi
+```
+
+**Report:** relay the terminal status. Do not run `promotion complete` from this skill — hand back to `dx-devops-promote`.
+
+---
+
+## Example 4 — Timeout while still processing
+
+**User prompt:** "Check request a0B000000000300, wait up to 5 minutes."
+
+```bash
+# 300s timeout, 15s interval
+scripts/poll-status.sh a0B000000000300 my-devops-org 15 300
+# Exit code 3 means the request was still processing at the 5-minute cap.
+```
+
+**Report:** "Request `a0B000000000300` was still in progress (e.g. `PROMOTE_IN_PROGRESS`) after 5 minutes. It has not failed — poll again later to confirm completion." Do NOT report success or failure for a request that has not finished processing.
+
+---
+
+## Example 5 — Failed operation vs. failed query
+
+**Scenario:** distinguish a failed *query* (bad token / auth) from a failed *operation* (request finished, but `errorDetails` set).
+
+```bash
+# The exit code distinguishes the two failure modes: 1 = the QUERY failed (bad
+# token / auth), 2 = the query succeeded but the OPERATION failed (errorDetails
+# set, even when .result.status is a *SUCCESS* value).
+scripts/poll-status.sh --once a0B000000000400 my-devops-org
+case $? in
+  1) echo "Query itself failed — check the request token and org auth." >&2 ;;
+  2) echo "Operation failed — see the parsed errorType/errorMessage above." ;;
+  0) echo "Operation succeeded." ;;
+  4) echo "Still processing — poll to completion (Example 2)." ;;
+esac
+```
+
+**Report:** a failed operation (non-null `errorDetails`) is a valid result — report the parsed `errorType`/`errorMessage`. If it failed on a metadata conflict, hand back to `dx-devops-promote` to resolve and re-promote.