framework tools/git: pr-create R1/R4 conversion (P1)

usage() default exit 2 (usage-error contract); value guards on all
seven value-taking options; -d/--draft stays boolean. Existing
fallback-default-base suite green (29/29). Usage-contract suite
enrolled (population 81); mirrored to the brain tree.

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

@@ -135,37 +135,51 @@ Examples:
     $(basename "$0") -i 42 -b "Implements the feature described in #42"
     $(basename "$0") -t "WIP: New feature" --draft
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             BODY="$2"
             shift 2
             ;;
         -B|--base)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             BASE_BRANCH="$2"
             shift 2
             ;;
         -H|--head)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             HEAD_BRANCH="$2"
             shift 2
             ;;
         -l|--labels)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             MILESTONE="$2"
             shift 2
             ;;
         -i|--issue)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             ISSUE="$2"
             shift 2
             ;;