framework tools/git: issue-edit R1/R4 conversion (P1)

issue-edit already used long-flag-first parsing; this adds the rc=2 usage-error contract (unknown option, missing -i, value-less flags across all five options), the exit-code line in help, and the enrolled usage-contract suite (population 78). Mirrored to the brain tree.
2026-08-28 17:59:18 -05:00
parent 31a447a46f
commit dff486b43a
3 changed files with 144 additions and 5 deletions
@@ -14,25 +14,39 @@ BODY=""
 LABELS=""
 MILESTONE=""

+# 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-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>] (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
            ;;
        -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
            ;;
        -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
            ;;
@@ -46,18 +60,18 @@ while [[ $# -gt 0 ]]; do
            echo "  -l, --labels     Labels (comma-separated, replaces existing)"
            echo "  -m, --milestone  Milestone name"
            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