framework tools/git: milestone-close, milestone-list, issue-view R1/R4 conversions (P1)

usage_error contract (stderr + exit 2) with value guards on every
value-taking option and the missing-required checks (milestone-close
-t, issue-view -i). Three suites enrolled (population 85); green in
both trees; mirrored to the brain tree.

packages/mosaic/framework/tools/git/milestone-list.sh

@@ -8,11 +8,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# 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
+    echo "Usage: milestone-list.sh [-s <state>] (see --help)" >&2
+    exit 2
+}
+
 STATE="open"
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             STATE="$2"
             shift 2
             ;;
@@ -25,8 +34,7 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done