framework tools/git: issue-reopen + pr-close R1/R4 conversions (P1)

Same contract as issue-close (7a38eed1): -b/--body canonical comment
flag with -c/--comment alias; usage errors stderr + exit 2 (unknown
option, missing required, value-less flags); GitHub-path provider
failures normalized to exit 1.

Both new suites enrolled in framework-shell CI (enumeration guard OK,
population 76). pr-close's suite uses FAILING provider stubs (exit 99):
its API fallback treats a successful curl as a closed PR, so exit-0
stubs let sandbox arms succeed (measured); post-sandbox contact
assertions are correspondingly scoped, parser arms remain zero-contact.
Mirrored to the brain tree; all usage-contract suites green in both.

packages/mosaic/framework/tools/git/issue-reopen.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-reopen.sh - Reopen a closed issue on GitHub or Gitea
-# Usage: issue-reopen.sh -i <issue_number> [-c <comment>]
+# Usage: issue-reopen.sh -i <issue_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -11,35 +12,49 @@ source "$SCRIPT_DIR/detect-platform.sh"
 ISSUE_NUMBER=""
 COMMENT=""
 
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             COMMENT="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-reopen.sh -i <issue_number> [-c <comment>]"
+            echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
             echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment to add when reopening (optional)"
+            echo "  -b, --body     Comment to add when reopening (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 detect_platform >/dev/null
@@ -80,10 +95,22 @@ gitea_issue_reopen_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub comment before reopen failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh issue reopen "$ISSUE_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub issue reopen failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh issue reopen "$ISSUE_NUMBER"
     echo "Reopened GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args || true)