P1b: read-only viewers join the R1/R4 usage contract (#1472)

Co-authored-by: marcie <[email protected]>

packages/mosaic/framework/tools/git/pr-metadata.sh

@@ -12,13 +12,23 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 OUTPUT_FILE=""
 
+# Usage-error contract (R4): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-metadata.sh -n <pr_number> [-o <output_file>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -o|--output)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             OUTPUT_FILE="$2"
             shift 2
             ;;
@@ -29,18 +39,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1" >&2
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)" >&2
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 write_metadata() {