framework tools/git: provider-normalization arms on issue-close and milestone-list (codex should-fix)

gh stub exiting 2 on the close/api path -> wrapper exit 1 with the normalized stderr message; mirrors the issue-assign 6b arm. All touched suites green; brain mirror updated.
framework tools/git: lookup-pipeline pipefail + provider-normalization test arm (codex round on PR #1464 )
2026-08-28 18:33:32 -05:00 · 2026-08-28 18:31:18 -05:00 · 2026-08-28 18:28:28 -05:00 · 2026-08-28 18:26:10 -05:00 · 2026-08-28 18:17:30 -05:00 · 2026-08-28 18:14:57 -05:00
38 changed files with 2717 additions and 141 deletions
@@ -3,6 +3,7 @@
 # Usage: issue-assign.sh -i ISSUE_NUMBER [-a assignee] [-l labels] [-m milestone]

 set -e
+set -o pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -33,25 +34,36 @@ Examples:
    $(basename "$0") -i 42 -l "in-progress" -m "0.2.0"
    $(basename "$0") -i 42 -a @me
 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 >&2
 }

 # Parse arguments
 while [[ $# -gt 0 ]]; do
    case $1 in
        -i|--issue)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ISSUE="$2"
            shift 2
            ;;
        -a|--assignee)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ASSIGNEE="$2"
            shift 2
            ;;
        -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LABELS="$2"
            shift 2
            ;;
        -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            MILESTONE="$2"
            shift 2
            ;;
@@ -79,20 +91,35 @@ PLATFORM=$(detect_platform)
 case "$PLATFORM" in
    github)
        if [[ -n "$ASSIGNEE" ]]; then
-            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE"
+            prov_rc=0
+            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        fi
        if [[ "$REMOVE_ASSIGNEE" == true ]]; then
            # Get current assignees and remove them
-            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',')
+            # pipefail preserves the provider status through the pipeline;
+            # a FAILED lookup exits here instead of reading as a silent
+            # no-assignees skip (codex PR #1464). A successful lookup with
+            # zero assignees still skips the edit below.
+            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',') || {
+                echo "Error: could not read current assignees (provider lookup failed)" >&2
+                exit 1
+            }
            if [[ -n "$CURRENT" ]]; then
-                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}"
+                prov_rc=0
+                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}" || prov_rc=$?
+                [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
            fi
        fi
        if [[ -n "$LABELS" ]]; then
-            gh issue edit "$ISSUE" --add-label "$LABELS"
+            prov_rc=0
+            gh issue edit "$ISSUE" --add-label "$LABELS" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        fi
        if [[ -n "$MILESTONE" ]]; then
-            gh issue edit "$ISSUE" --milestone "$MILESTONE"
+            prov_rc=0
+            gh issue edit "$ISSUE" --milestone "$MILESTONE" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        fi
        echo "Issue #$ISSUE updated successfully"
        ;;
@@ -131,7 +158,9 @@ case "$PLATFORM" in
        fi

        if [[ "$NEEDS_EDIT" == true ]]; then
-            "${CMD[@]}"
+            prov_rc=0
+            "${CMD[@]}" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
            echo "Issue #$ISSUE updated successfully"
        else
            echo "No changes specified"
@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-close.sh - Close an issue on GitHub or Gitea
-# Usage: issue-close.sh -i <issue_number> [-c <comment>]
+# Usage: issue-close.sh -i <issue_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)

 set -e

@@ -12,35 +13,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-close.sh -i <issue_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
    case $1 in
        -i|--issue)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            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 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            COMMENT="$2"
            shift 2
            ;;
        -h|--help)
-            echo "Usage: issue-close.sh -i <issue_number> [-c <comment>]"
+            echo "Usage: issue-close.sh -i <issue_number> [-b <comment>]"
            echo ""
            echo "Options:"
            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment to add before closing (optional)"
+            echo "  -b, --body     Comment to add before closing (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 and close issue
@@ -82,10 +97,22 @@ gitea_issue_close_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 close failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh issue close "$ISSUE_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub issue close failed (gh exit $gh_rc)" >&2
+        exit 1
    fi
-    gh issue close "$ISSUE_NUMBER"
    echo "Closed GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    GITEA_LOGIN_NAME=$(get_gitea_login || true)
@@ -107,7 +134,9 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                exit 1
            }
        fi
-        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
+        prov_rc=0
+        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    else
        echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
        if [[ -n "$COMMENT" ]]; then
@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-comment.sh - Add a comment to an issue on GitHub or Gitea
-# Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]
+# Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1, 2026-08-28)
 #
 # tea v0.11.1 defines no `comment` subcommand under `tea issue` (or `tea pr`);
 # the non-existent `tea issue comment ...` form does not error — tea silently
@@ -32,45 +33,61 @@ ISSUE_NUMBER=""
 COMMENT=""
 LOGIN_OVERRIDE=""

+# 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
+# (CONSTITUTION gate 8 as amended; E2E-DELIVERY).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
    case $1 in
        -i|--issue)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ISSUE_NUMBER="$2"
            shift 2
            ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag, matching
+            # issue-create/issue-edit/pr-create/pr-edit; -c/--comment stays a
+            # backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            COMMENT="$2"
            shift 2
            ;;
        -l|--login)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LOGIN_OVERRIDE="$2"
            shift 2
            ;;
        -h|--help)
-            echo "Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]"
+            echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]"
            echo ""
            echo "Options:"
            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment text (required)"
+            echo "  -b, --body     Comment text (required; canonical)"
+            echo "  -c, --comment  Alias for --body"
            echo "  -l, --login    Override the detected Gitea tea login for this call"
            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

 if [[ -z "$COMMENT" ]]; then
-    echo "Error: Comment is required (-c)"
-    exit 1
+    usage_error "comment is required (-b/--body, or the -c/--comment alias)"
 fi

 detect_platform >/dev/null
@@ -340,7 +357,15 @@ PY
 }

 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+    # R4 exit-code contract: normalize provider failures to exit 1. gh's own
+    # usage errors exit 2, which would collide with this wrapper's reserved
+    # usage-error status if propagated raw (codex review of 08a00149).
+    gh_rc=0
+    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub comment write failed (gh exit $gh_rc; provider/credential failure — usage errors are exit 2)" >&2
+        exit 1
+    fi
    echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    # A --login override selects a NAMED tea credential and is the only way to
@@ -74,26 +74,39 @@ Examples:
    $(basename "$0") -t "Fix login bug" -l "bug,priority-high"
    $(basename "$0") -t "Add dark mode" -b "Implement theme switching" -m "0.2.0"
    $(basename "$0") -i
+
+Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure.
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }

 # 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
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
    case $1 in
        -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            TITLE="$2"
            shift 2
            ;;
        -b|--body)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            BODY="$2"
            shift 2
            ;;
        -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LABELS="$2"
            shift 2
            ;;
        -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            MILESTONE="$2"
            shift 2
            ;;
@@ -131,7 +144,9 @@ case "$PLATFORM" in
        [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
        [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        ;;
    gitea)
        if command -v tea >/dev/null 2>&1; then
@@ -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 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ISSUE_NUMBER="$2"
            shift 2
            ;;
        -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            TITLE="$2"
            shift 2
            ;;
        -b|--body)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            BODY="$2"
            shift 2
            ;;
        -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LABELS="$2"
            shift 2
            ;;
        -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            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
@@ -68,7 +82,9 @@ if [[ "$PLATFORM" == "github" ]]; then
    [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
    [[ -n "$LABELS" ]] && CMD+=(--add-label "$LABELS")
    [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    "${CMD[@]}"
+    prov_rc=0
+    "${CMD[@]}" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    echo "Updated GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    REPO_SLUG=$(get_repo_slug) || {
@@ -84,7 +100,9 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
    [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
    [[ -n "$LABELS" ]] && CMD+=(--add-labels "$LABELS")
    [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    "${CMD[@]}"
+    prov_rc=0
+    "${CMD[@]}" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    echo "Updated Gitea issue #$ISSUE_NUMBER"
 else
    echo "Error: Unknown platform"
@@ -36,33 +36,46 @@ Examples:
    $(basename "$0") -m "0.2.0"               # Issues in milestone 0.2.0
    $(basename "$0") --repo ddk/ai-bma         # List issues from anywhere
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }

 # 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
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
    case $1 in
        -s|--state)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            STATE="$2"
            shift 2
            ;;
        -l|--label)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LABEL="$2"
            shift 2
            ;;
        -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            MILESTONE="$2"
            shift 2
            ;;
        -a|--assignee)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ASSIGNEE="$2"
            shift 2
            ;;
        -n|--limit)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LIMIT="$2"
            shift 2
            ;;
        -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            REPO_OVERRIDE="$2"
            shift 2
            ;;
@@ -95,7 +108,9 @@ case "$PLATFORM" in
        [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
        [[ -n "$ASSIGNEE" ]] && CMD+=(--assignee "$ASSIGNEE")
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        ;;
    gitea)
        if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -114,7 +129,9 @@ case "$PLATFORM" in
        [[ -n "$MILESTONE" ]] && CMD+=(--milestones "$MILESTONE")
        # Note: tea may not support assignee filter directly in all versions.
        [[ -n "$ASSIGNEE" ]] && echo "Note: Assignee filtering may require manual review for Gitea" >&2
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        ;;
    *)
        echo "Error: Could not detect git platform" >&2
@@ -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 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            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 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            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,18 +95,34 @@ 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)
    if [[ -n "$REPO_ARGS" ]]; then
        if [[ -n "$COMMENT" ]]; then
-            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS
+            prov_rc=0
+            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        fi
-        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS
+        prov_rc=0
+        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    else
        echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
        if [[ -n "$COMMENT" ]]; then
@@ -8,6 +8,14 @@ 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: issue-view.sh -i <issue_number> (see --help)" >&2
+    exit 2
+}
+
 ISSUE_NUMBER=""

 # get_remote_host and get_gitea_token are provided by detect-platform.sh
@@ -74,6 +82,7 @@ if comments:
 while [[ $# -gt 0 ]]; do
    case $1 in
        -i|--issue)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ISSUE_NUMBER="$2"
            shift 2
            ;;
@@ -88,21 +97,21 @@ while [[ $# -gt 0 ]]; do
            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"
 fi

 detect_platform >/dev/null

 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue view "$ISSUE_NUMBER"
+    prov_rc=0
+    gh issue view "$ISSUE_NUMBER" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 elif [[ "$PLATFORM" == "gitea" ]]; then
    if command -v tea >/dev/null 2>&1; then
        # --comments is what makes tea print the comment bodies (#1357 F3).
@@ -28,18 +28,25 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"

 REPO="" MILESTONE="" LABEL="" LOGIN="" LIMIT=100
-while getopts "r:m:l:L:n:h" opt; do
-  case "$opt" in
-    r) REPO="$OPTARG" ;;
-    m) MILESTONE="$OPTARG" ;;
-    l) LABEL="$OPTARG" ;;
-    L) LOGIN="$OPTARG" ;;
-    n) LIMIT="$OPTARG" ;;
-    h) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
-    *) echo "see -h" >&2; exit 2 ;;
+# R2 (2026-08-28): long-flag aliases with the same usage-error contract the
+# wrapper family shares (rc 2, stderr). getopts could not take long flags.
+usage_error() {
+  echo "Error: $*" >&2
+  echo "Usage: lane-brief.sh -r <owner/repo> [-m milestone] [-l label] [-L login] [-n limit]" >&2
+  exit 2
+}
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO="$2"; shift 2 ;;
+    -m|--milestone) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; MILESTONE="$2"; shift 2 ;;
+    -l|--label|--labels) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LABEL="$2"; shift 2 ;;
+    -L|--login) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LOGIN="$2"; shift 2 ;;
+    -n|--limit) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LIMIT="$2"; shift 2 ;;
+    -h|--help) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) usage_error "unknown option: $1" ;;
  esac
 done
-[[ -n "$REPO" ]] || { echo "FATAL: -r <owner/repo> required" >&2; exit 2; }
+[[ -n "$REPO" ]] || usage_error "-r/--repo <owner/repo> required"

 # Resolve login: explicit -L, then $GITEA_LOGIN, then owner inference, then the
 # shared default-login resolver. Owner inference comes before the shared fallback
@@ -72,7 +79,7 @@ if [[ -z "$LOGIN" ]]; then
    fi
  fi
 fi
-[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 2; }
+[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 1; }

 command -v tea >/dev/null || { echo "FATAL: tea not found" >&2; exit 1; }
 command -v jq  >/dev/null || { echo "FATAL: jq not found" >&2; exit 1; }
@@ -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-close.sh -t <title> (see --help)" >&2
+    exit 2
+}
+
 TITLE=""

 while [[ $# -gt 0 ]]; do
    case $1 in
        -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            TITLE="$2"
            shift 2
            ;;
@@ -25,28 +34,30 @@ while [[ $# -gt 0 ]]; do
            exit 0
            ;;
        *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
            ;;
    esac
 done

 if [[ -z "$TITLE" ]]; then
-    echo "Error: Milestone title is required (-t)"
-    exit 1
+    usage_error "Milestone title is required"
 fi

 detect_platform >/dev/null

 if [[ "$PLATFORM" == "github" ]]; then
-    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed
+    prov_rc=0
+    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    echo "Closed GitHub milestone: $TITLE"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    REPO_ARGS=$(get_gitea_repo_args) || {
        echo "Error: Could not resolve Gitea repo/login for remote host" >&2
        exit 1
    }
-    tea milestone close "$TITLE" $REPO_ARGS
+    prov_rc=0
+    tea milestone close "$TITLE" $REPO_ARGS || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    echo "Closed Gitea milestone: $TITLE"
 else
    echo "Error: Unknown platform"
@@ -3,6 +3,7 @@
 # Usage: milestone-create.sh -t "Title" [-d "Description"] [--due "YYYY-MM-DD"]

 set -e
+set -o pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -37,21 +38,31 @@ Examples:
    $(basename "$0") -t "0.0.1" -d "Pre-MVP Foundation Sprint"
    $(basename "$0") -t "0.1.0" -d "MVP Release" --due "2025-03-01"
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }

 # 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
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
    case $1 in
        -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            TITLE="$2"
            shift 2
            ;;
        -d|--desc)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            DESCRIPTION="$2"
            shift 2
            ;;
        --due)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            DUE_DATE="$2"
            shift 2
            ;;
@@ -74,14 +85,18 @@ PLATFORM=$(detect_platform)
 if [[ "$LIST_ONLY" == true ]]; then
    case "$PLATFORM" in
        github)
-            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"'
+            prov_rc=0
+            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"' || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
            ;;
        gitea)
            REPO_ARGS=$(get_gitea_repo_args) || {
                echo "Error: Could not resolve Gitea repo/login for remote host" >&2
                exit 1
            }
-            tea milestones list $REPO_ARGS
+            prov_rc=0
+            tea milestones list $REPO_ARGS || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
            ;;
        *)
            echo "Error: Could not detect git platform" >&2
@@ -92,8 +107,7 @@ if [[ "$LIST_ONLY" == true ]]; then
 fi

 if [[ -z "$TITLE" ]]; then
-    echo "Error: Title is required (-t) for creating milestones" >&2
-    usage
+    usage_error "Title is required (-t) for creating milestones"
 fi

 case "$PLATFORM" in
@@ -109,7 +123,9 @@ case "$PLATFORM" in
             + (if $d != "" then {"description": $d} else {} end)
             + (if $due != "" then {"due_on": ($due + "T00:00:00Z")} else {} end)')

-        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD"
+        prov_rc=0
+        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        echo "Milestone '$TITLE' created successfully"
        ;;
    gitea)
@@ -120,7 +136,9 @@ case "$PLATFORM" in
        CMD=(tea milestones create --title "$TITLE")
        [[ -n "$DESCRIPTION" ]] && CMD+=(--description "$DESCRIPTION")
        [[ -n "$DUE_DATE" ]] && CMD+=(--deadline "$DUE_DATE")
-        "${CMD[@]}" $REPO_ARGS
+        prov_rc=0
+        "${CMD[@]}" $REPO_ARGS || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        echo "Milestone '$TITLE' created successfully"
        ;;
    *)
@@ -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 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            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
@@ -34,13 +42,17 @@ done
 detect_platform >/dev/null

 if [[ "$PLATFORM" == "github" ]]; then
-    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"'
+    prov_rc=0
+    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"' || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 elif [[ "$PLATFORM" == "gitea" ]]; then
    REPO_ARGS=$(get_gitea_repo_args) || {
        echo "Error: Could not resolve Gitea repo/login for remote host" >&2
        exit 1
    }
-    tea milestone list $REPO_ARGS
+    prov_rc=0
+    tea milestone list $REPO_ARGS || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 else
    echo "Error: Unknown platform"
    exit 1
@@ -1,6 +1,7 @@
 #!/bin/bash
 # pr-close.sh - Close a pull request without merging on GitHub or Gitea
-# Usage: pr-close.sh -n <pr_number> [-c <comment>]
+# Usage: pr-close.sh -n <pr_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)

 set -e

@@ -11,50 +12,80 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_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: pr-close.sh -n <pr_number> [-b <comment>] (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
            ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            COMMENT="$2"
            shift 2
            ;;
        -h|--help)
-            echo "Usage: pr-close.sh -n <pr_number> [-c <comment>]"
+            echo "Usage: pr-close.sh -n <pr_number> [-b <comment>]"
            echo ""
            echo "Options:"
            echo "  -n, --number   PR number (required)"
-            echo "  -c, --comment  Comment before closing (optional)"
+            echo "  -b, --body     Comment before closing (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 "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi

 detect_platform >/dev/null

 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 pr comment "$PR_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh pr comment "$PR_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub PR comment before close failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh pr close "$PR_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub PR close failed (gh exit $gh_rc)" >&2
+        exit 1
    fi
-    gh pr close "$PR_NUMBER"
    echo "Closed GitHub PR #$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    if [[ -n "$COMMENT" ]]; then
-        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+        prov_rc=0
+        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args) || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    fi
-    tea pr close "$PR_NUMBER" $(get_gitea_repo_args)
+    prov_rc=0
+    tea pr close "$PR_NUMBER" $(get_gitea_repo_args) || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
    echo "Closed Gitea PR #$PR_NUMBER"
 else
    echo "Error: Unknown platform"
@@ -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 >&2
 }

 # Parse arguments
 while [[ $# -gt 0 ]]; do
    case $1 in
        -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            TITLE="$2"
            shift 2
            ;;
        -b|--body)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            BODY="$2"
            shift 2
            ;;
        -B|--base)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            BASE_BRANCH="$2"
            shift 2
            ;;
        -H|--head)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            HEAD_BRANCH="$2"
            shift 2
            ;;
        -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LABELS="$2"
            shift 2
            ;;
        -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            MILESTONE="$2"
            shift 2
            ;;
        -i|--issue)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ISSUE="$2"
            shift 2
            ;;
@@ -266,7 +280,9 @@ case "$PLATFORM" in
        [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
        [[ "$DRAFT" == true ]] && CMD+=(--draft)
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        ;;
    gitea)
        # tea pull create syntax. Always pass --repo because tea repo inference
@@ -50,38 +50,45 @@ Options:
    -H, --host HOST        Explicit Gitea host (required with --repo off-host)
    -h, --help             Show this help message
 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 >&2
 }

 while [[ $# -gt 0 ]]; do
    case "$1" in
-        -n|--number) PR_NUMBER="${2:-}"; shift 2 ;;
-        -t|--title) TITLE="${2:-}"; shift 2 ;;
-        -b|--body) BODY="${2:-}"; shift 2 ;;
-        -B|--base) BASE_BRANCH="${2:-}"; shift 2 ;;
+        -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 ;;
+        -t|--title) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; TITLE="${2:-}"; shift 2 ;;
+        -b|--body) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BODY="${2:-}"; shift 2 ;;
+        -B|--base) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BASE_BRANCH="${2:-}"; shift 2 ;;
        --draft)
-            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
            DRAFT_MODE="draft"; shift ;;
        --ready)
-            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
            DRAFT_MODE="ready"; shift ;;
-        -l|--login) LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
-        -r|--repo) REPO_OVERRIDE="${2:-}"; shift 2 ;;
-        -H|--host) HOST_OVERRIDE="${2:-}"; shift 2 ;;
+        -l|--login) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
+        -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO_OVERRIDE="${2:-}"; shift 2 ;;
+        -H|--host) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; HOST_OVERRIDE="${2:-}"; shift 2 ;;
        -h|--help) usage 0 ;;
        *) echo "Unknown option: $1" >&2; usage ;;
    esac
 done

-[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 1; }
-[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 1; }
+[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 2; }
+[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 2; }
 if [[ -z "$TITLE" && -z "$BODY" && -z "$BASE_BRANCH" && -z "$DRAFT_MODE" ]]; then
    echo "Error: At least one edit option is required" >&2
-    exit 1
+    exit 2
 fi
 [[ -z "$REPO_OVERRIDE" || "$REPO_OVERRIDE" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]] || {
    echo "Error: --repo must be OWNER/REPO" >&2
-    exit 1
+    exit 2
 }

 if [[ -n "$HOST_OVERRIDE" || -n "$REPO_OVERRIDE" ]]; then
@@ -92,18 +99,24 @@ fi

 case "$PLATFORM" in
    github)
-        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 1; }
+        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 2; }
        if [[ -n "$TITLE" || -n "$BODY" || -n "$BASE_BRANCH" ]]; then
            CMD=(gh pr edit "$PR_NUMBER")
            [[ -n "$TITLE" ]] && CMD+=(--title "$TITLE")
            [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
            [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
-            "${CMD[@]}"
+            prov_rc=0
+            "${CMD[@]}" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        fi
        if [[ "$DRAFT_MODE" == "draft" ]]; then
-            gh pr ready "$PR_NUMBER" --undo
+            prov_rc=0
+            gh pr ready "$PR_NUMBER" --undo || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        elif [[ "$DRAFT_MODE" == "ready" ]]; then
-            gh pr ready "$PR_NUMBER"
+            prov_rc=0
+            gh pr ready "$PR_NUMBER" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
        fi
        ;;
    gitea)
@@ -43,60 +43,92 @@ LOGIN_OVERRIDE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""

+# 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: pr-review.sh -n <pr_number> -a <action> [-b <comment>] (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
            ;;
        -a|--action)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            ACTION="$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 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            COMMENT="$2"
            shift 2
            ;;
        -l|--login)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            LOGIN_OVERRIDE="$2"
            shift 2
            ;;
        -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            REPO_OVERRIDE="$2"
            shift 2
            ;;
        -H|--host)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
            HOST_OVERRIDE="$2"
            shift 2
            ;;
        -h|--help)
-            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>] [-r owner/repo] [-H host]"
+            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] [--login <name>] [-r owner/repo] [-H host]"
            echo ""
            echo "Options:"
            echo "  -n, --number   PR number (required)"
            echo "  -a, --action   Review action: approve, request-changes, comment (required)"
-            echo "  -c, --comment  Review comment (required for request-changes)"
+            echo "  -b, --body     Review comment (required for request-changes; canonical)"
+            echo "  -c, --comment  Alias for --body"
            echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
            echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
            echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
            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 "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi

 if [[ -z "$ACTION" ]]; then
-    echo "Error: Action is required (-a): approve, request-changes, comment"
-    exit 1
+    usage_error "Action is required (-a/--action): approve, request-changes, comment"
+fi
+
+# Validate the action BEFORE any provider contact (codex review of PR #1464:
+# an unsupported --action previously reached platform detection and could
+# touch the provider before failing with a provider-class status).
+case "$ACTION" in
+    approve|request-changes|comment) ;;
+    *) usage_error "unknown action '$ACTION': approve, request-changes, comment" ;;
+esac
+
+# Body-required actions fail fast too (codex follow-up on PR #1464):
+# request-changes and comment both require a body; validate before any
+# provider contact.
+if [[ ( "$ACTION" == "request-changes" || "$ACTION" == "comment" ) && -z "$COMMENT" ]]; then
+    usage_error "comment required for $ACTION (-b/--body)"
 fi

 if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -679,15 +711,18 @@ PY
 if [[ "$PLATFORM" == "github" ]]; then
    case $ACTION in
        approve)
-            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"}
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"} || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub approve failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
            echo "Approved GitHub PR #$PR_NUMBER"
            ;;
        request-changes)
            if [[ -z "$COMMENT" ]]; then
-                echo "Error: Comment required for request-changes"
-                exit 1
+                usage_error "comment required for request-changes (-b/--body)"
            fi
-            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT"
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT" || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub request-changes failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
            echo "Requested changes on GitHub PR #$PR_NUMBER"
            ;;
        comment)
@@ -695,12 +730,13 @@ if [[ "$PLATFORM" == "github" ]]; then
                echo "Error: Comment required"
                exit 1
            fi
-            gh pr review "$PR_NUMBER" --comment --body "$COMMENT"
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --comment --body "$COMMENT" || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub review comment failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
            echo "Added review comment to GitHub PR #$PR_NUMBER"
            ;;
        *)
-            echo "Error: Unknown action: $ACTION"
-            exit 1
+            usage_error "unknown action: $ACTION"
            ;;
    esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
@@ -738,8 +774,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
            ;;
        request-changes)
            if [[ -z "$COMMENT" ]]; then
-                echo "Error: Comment required for request-changes"
-                exit 1
+                usage_error "comment required for request-changes (-b/--body)"
            fi
            # Best-effort host for credential resolution only (gitea_resolve_api_for_login
            # below re-derives the real host from HOST_OVERRIDE/remote independently and
@@ -794,8 +829,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
            echo "Added and verified comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
            ;;
        *)
-            echo "Error: Unknown action: $ACTION"
-            exit 1
+            usage_error "unknown action: $ACTION"
            ;;
    esac
 else
@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-assign.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-assign-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-assign.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-assign.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-assign.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "Issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -a -l -m --issue --assignee --labels --milestone; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -a --help
+expect_rc 2 "short flag value rejected" -i 5 -a -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -a; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
+# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+cat > "$BIN_DIR/gh" <<GHSTUB
+#!/usr/bin/env bash
+echo "gh \$*" >> "$PROBE_LOG"
+if [[ "\$1 \$2" == "issue edit" ]]; then exit 2; fi
+exit 0
+GHSTUB
+chmod +x "$BIN_DIR/gh"
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-assign.sh" -i 5 -a someone >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
+
+echo "issue-assign.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-close.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-close-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-close.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-close.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-close.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -b -c --issue --body --comment; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Sandbox arms may issue DETECTION reads only (tea login list via the
+# stub); no gh/curl write or read may occur.
+if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
+    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
+    exit 1
+fi
+if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
+    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
+    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-close.sh usage-contract regression passed (R1/R4)"
@@ -42,6 +42,8 @@
 #  10. leaves NO temp files behind (POST/GET bodies + metadata) on either the
 #      success or the failure path — nested function-scoped RETURN traps do not
 #      clobber each other and every scratch file is removed on all exit paths.
+#  11. accepts the canonical -b/--body flag exactly like the -c/--comment alias
+#      (R1, 2026-08-28): a full verified write via -b alone.

 set -euo pipefail

@@ -409,11 +411,28 @@ run_comment() {
    seed_state "$mode"
    (
        cd "$REPO_DIR"
+        # Provisioned seats export MOSAIC_GIT_IDENTITY and MOSAIC_BRAIN_HOME
+        # seat-wide (launcher), and both escape this harness's sandboxed HOME:
+        # detect-platform.sh consults MOSAIC_GIT_IDENTITY BEFORE the repo-local
+        # mosaic.gitIdentity pin, and resolves the brain home (whose
+        # fleet/agents presence arms the no-identity fail-loud branch) from
+        # MOSAIC_BRAIN_HOME before $HOME. Without these explicit empties the
+        # wrapper either resolves the REAL seat-slot token (stub curl rejects
+        # it: the documented HTTP 401) or fails loud before any request.
+        # Set-but-empty reads as unset to detect-platform's "${VAR:-}" forms.
+        # NOTE: keep this comment block ABOVE the assignment chain — a comment
+        # inside a backslash-continued prefix chain terminates the command and
+        # silently demotes every earlier assignment to an unexported subshell
+        # assignment (measured 2026-08-28: the wrapper then ran without
+        # MOSAIC_CREDENTIALS_FILE and the suite died at credential resolution
+        # with zero diagnostic output).
        PATH="$BIN_DIR:$PATH" \
        TMPDIR="$TMP_SCRATCH" \
        HOME="$HOME_DIR" \
        XDG_CONFIG_HOME="$XDG_DIR" \
        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+        MOSAIC_GIT_IDENTITY="" \
+        MOSAIC_BRAIN_HOME="" \
        ISSUE_COMMENT_TEA_LOG="$TEA_LOG" \
        ISSUE_COMMENT_CURL_LOG="$CURL_LOG" \
        ISSUE_COMMENT_CURL_ARGV_LOG="$CURL_ARGV_LOG" \
@@ -430,7 +449,7 @@ run_comment() {
        ISSUE_COMMENT_REPO_SLUG="$REPO_SLUG" \
        ISSUE_COMMENT_API_BASE="$API_BASE" \
        ISSUE_COMMENT_API_ROOT="$API_ROOT" \
-        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" -c "$BODY" "$@"
+        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" "${BODY_FLAG:--c}" "$BODY" "$@"
    ) > "$OUTPUT_FILE" 2>&1
 }

@@ -614,4 +633,21 @@ done
 # issue_url (already exercised by Case 1's fresh-success), so the tightened check
 # is not rejecting genuine writes.

+# Case 11 (R1, 2026-08-28): -b/--body is the canonical comment flag and must
+# drive a full verified write exactly like the -c/--comment alias. BODY_FLAG
+# swaps only the flag spelling; every assertion below is case 1's contract.
+BODY_FLAG="-b"
+run_comment fresh-success
+grep -q 'Added and verified comment on Gitea issue #7 (comment ID 51)' "$OUTPUT_FILE"
+grep -q "^POST $API_BASE/issues/7/comments$" "$CURL_LOG"
+if grep -Eq '^comment |^issue comment ' "$TEA_LOG"; then
+    echo "FAIL: --body write went through tea instead of REST" >&2
+    exit 1
+fi
+grep -q "^GET $API_BASE/issues/comments/51$" "$CURL_LOG"
+grep -q "^POST $API_BASE/issues/7/comments $ACTING_LOGIN$" "$AUTH_LOG"
+assert_no_temp_leak "fresh-success-body-flag"
+assert_token_not_in_argv "fresh-success-body-flag"
+unset BODY_FLAG
+
 echo "issue-comment.sh REST create + exact-id read-back regression passed"
@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-comment.sh (R1/R4 remediation, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1), so a caller (or a stop gate)
+# can tell an invocation defect from a delivery blocker. Before this contract
+# the wrapper exited 1 for usage errors with messages on STDOUT, and a
+# value-less flag (-c with no value) died SILENTLY at rc=1 because set -e
+# killed the failed `shift 2`. That silent shape is what full-stopped a fleet
+# seat: a caller could not distinguish "I invoked it wrong" from "delivery is
+# blocked".
+#
+# R1: -b/--body is the canonical comment flag (matching issue-create,
+# issue-edit, pr-create, pr-edit); -c/--comment remains a backward-compatible
+# alias.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. Missing required comment exits 2 (stderr).
+#   5. A value-less flag (-i -b -c -l and long forms) exits 2 with a
+#      "requires a value" message on stderr (the former silent-death class).
+#   6. -b and -c both pass parsing (the run then fails at platform detection
+#      in this non-repo fixture, nonzero and NOT 2), proving alias acceptance
+#      without any provider fixture.
+#   7. No arm performs any provider request: PATH shims for gh/tea/curl
+#      record every invocation and the probe log must stay empty.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-comment-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Provider shims: any invocation is recorded and fails the run at the end.
+# Usage-error arms must exit during argument parsing, before detect_platform,
+# so these prove "no provider request on parser failure".
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+# gh doubles as platform probe AND write path in arm 6b: probes exit 0; the
+# comment write exits 2 (gh's own usage-error status) to prove the wrapper
+# normalizes provider failures to exit 1 instead of propagating 2.
+if [[ "\$1 \$2" == "issue comment" ]]; then exit 2; fi
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-comment.sh" "$@" )
+}
+
+# Hermetic variant for parse-acceptance arms: neutralizes every identity/
+# credential source the wrapper consults (seat env vars, HOME, XDG tea config)
+# so the arm fails at credential resolution in ANY cwd repo, never reading a
+# real token or contacting a provider. Measured 2026-08-28: without this, the
+# arm's outcome depended on incidental URL-resolution state (brain cwd died at
+# URL-not-found; a stack worktree cwd resolved a configured URL, read the real
+# seat token, and invoked the curl stub — the suite then failed its own
+# no-provider-contact check, correctly).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-comment.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage on stdout.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-comment.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, message on stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Missing required comment: rc 2, stderr.
+expect_rc 2 "missing comment exits 2" -i 5
+expect_stderr "comment is required" "missing comment message on stderr"
+
+# 5. Value-less flags: rc 2 with "requires a value" on stderr. The old parser
+# died here silently (set -e on the failed shift 2).
+for flag in -i -b -c -l --issue --body --comment --login; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 6. Alias acceptance at parse level: both -b and -c carry a value past
+# parsing; the wrapper then fails at platform detection (not a git repo)
+# nonzero but NOT as a usage error (rc must not be 2).
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "some text" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6b. GitHub-path exit normalization (codex blocker on 08a00149): gh's own
+# usage errors exit 2; the wrapper must NOT propagate that status (reserved
+# for the wrapper's usage-error contract). With a github remote and a gh stub
+# whose comment write exits 2, the wrapper must exit 1 with the normalized
+# error on stderr.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+git -C "$GH_REPO" config mosaic.gitIdentity ""
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-comment.sh" -i 5 -b "text" >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "GitHub comment write failed" "$ERR_FILE" || fail "GitHub path: normalized error missing from stderr"
+grep -q "^gh issue comment" "$PROBE_LOG" || fail "GitHub path: gh write was not invoked"
+
+# 7. No provider contact from any usage-error arm (arm 6b's deliberate gh
+# invocation is the only permitted entry in the probe log).
+if grep -v '^gh issue comment' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    grep -v '^gh issue comment' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-comment.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-create.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-create-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-create.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-create.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-create.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -b -l -m --title --body --labels --milestone; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t smoke -b --help
+expect_rc 2 "short flag value rejected" -t smoke -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-create.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-edit.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-edit-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-edit.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-edit.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-edit.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -t -b -l -m --issue --title --body --labels --milestone; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-edit.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-list.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-list-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-list.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-list.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-list.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -s -l -m -a -n -r --state --label --milestone --assignee --limit --repo; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -s --help
+expect_rc 2 "short flag value rejected" -s -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -s; do
+    rc=0
+    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-list.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-reopen.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-reopen-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-reopen.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-reopen.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-reopen.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -b -c --issue --body --comment; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Sandbox arms may issue DETECTION reads only (tea login list via the
+# stub); no gh/curl write or read may occur.
+if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
+    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
+    exit 1
+fi
+if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
+    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
+    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-reopen.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-view.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-view-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-view.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-view.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-view.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "Issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i --issue; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i --help
+expect_rc 2 "short flag value rejected" -i -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -i; do
+    rc=0
+    run_wrapper_sandboxed -i 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-view.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for lane-brief.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/lane-brief-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/lane-brief.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/lane-brief.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "owner/repo" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -r exits 2"
+expect_stderr "required" "missing -r message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -r -m -l -L -n --repo --milestone --label --login --limit; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -r owner/repo -m --help
+expect_rc 2 "short flag value rejected" -r owner/repo -m -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -r; do
+    rc=0
+    run_wrapper_sandboxed -r owner/repo >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "lane-brief.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-close.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-close-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-close.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/milestone-close.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: milestone-close.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Milestone title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t --title; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t --help --help
+expect_rc 2 "short flag value rejected" -t --help -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -t; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "milestone-close.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-create.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-create-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-create.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/milestone-create.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: milestone-create.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -d --due --title --desc; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t smoke -d --help
+expect_rc 2 "short flag value rejected" -t smoke -d -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -t; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "milestone-create.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-list.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-list-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-list.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/milestone-list.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: milestone-list.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -s --state; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -s --help
+expect_rc 2 "short flag value rejected" -s -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -s; do
+    rc=0
+    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
+# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+cat > "$BIN_DIR/gh" <<GHSTUB
+#!/usr/bin/env bash
+echo "gh \$*" >> "$PROBE_LOG"
+if [[ "\$1" == "api" ]]; then exit 2; fi
+exit 0
+GHSTUB
+chmod +x "$BIN_DIR/gh"
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/milestone-list.sh" >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
+
+echo "milestone-list.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-close.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-close-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-close.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-close.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-close.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "PR number is required" "missing -n message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -b -c --number --body --comment; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n 5 -b --help
+expect_rc 2 "short flag value rejected" -n 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -n 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-close.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-create.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-create.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-create.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-create.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -b -B -H -l -m -i --title --body --base --head --labels --milestone --issue; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t smoke -b --help
+expect_rc 2 "short flag value rejected" -t smoke -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-create.sh usage-contract regression passed (R1/R4)"
@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-edit.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-edit-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-edit.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-edit.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-edit.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "Pull request number is required" "missing -n message on stderr"
+expect_rc 2 "no edit option exits 2" -n 5
+expect_stderr "At least one edit option is required" "no-edit-option message on stderr"
+expect_rc 2 "non-integer PR number exits 2" -n abc -t x
+expect_stderr "positive integer" "integer check on stderr"
+expect_rc 2 "mutually exclusive draft/ready exits 2" -n 5 --draft --ready
+expect_stderr "mutually exclusive" "mutual exclusion on stderr"
+expect_rc 2 "bad repo format exits 2" -n 5 -t x -r not-a-slug
+expect_stderr "OWNER/REPO" "repo format on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -t -b -B -l -r -H --number --title --body --base --login --repo --host; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n 5 -t smoke -b --help
+expect_rc 2 "short flag value rejected" -n 5 -t smoke -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -n 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-edit.sh usage-contract regression passed (R1/R4)"
@@ -218,7 +218,7 @@ if grep -q 'Unknown option' "$OUTPUT_FILE"; then
    cat "$OUTPUT_FILE" >&2
    exit 1
 fi
-grep -q 'Unknown action: bogus-action' "$OUTPUT_FILE"
+grep -q "unknown action 'bogus-action'" "$OUTPUT_FILE"

 # --- Case 2: -h/--help documents both overrides.
 HELP_TEXT="$("$SCRIPT_DIR/pr-review.sh" -h)"
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-review.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# Required: -n AND -a. The comment is required only for the
+# request-changes action (semantic usage check, also rc 2).
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-review-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-review.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-review.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-review.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "PR number is required" "missing -n message on stderr"
+expect_rc 2 "missing -a exits 2" -n 5
+expect_stderr "Action is required" "missing -a message on stderr"
+expect_rc 2 "request-changes without comment exits 2" -n 5 -a request-changes
+expect_stderr "comment required for request-changes" "request-changes message on stderr"
+expect_rc 2 "comment without body exits 2 pre-detection" -n 5 -a comment
+expect_stderr "comment required for comment" "comment-without-body message on stderr"
+expect_rc 2 "invalid action exits 2 pre-detection" -n 5 -a bogus
+expect_stderr "unknown action" "invalid action message on stderr"
+# Invalid-action arms must not contact any provider (validation precedes
+# detect_platform): probe log empty at this point.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: an invalid-action arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -a -b -c -l -r --number --action --body --comment --login --repo; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n 5 -a comment -b --help
+expect_rc 2 "short flag value rejected" -n 5 -a comment -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -n 5 -a comment "$flag" "review note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-review.sh usage-contract regression passed (R1/R4)"
@@ -14,7 +14,6 @@
 packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix (git -C scoping)
 packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
 packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh | resolves real credentials (#1007 census, fourth entry via family-grep); joins CI after the wrapper-half hermeticity fix
-packages/mosaic/framework/tools/git/test-issue-comment-readback.sh | resolves real credentials (#1007 census, fifth entry); joins CI after the wrapper-half hermeticity fix

 # --- tools/git: push guards — measured green locally, CI-image fitness unverified ---
 packages/mosaic/framework/tools/git/test-push-guard.sh | measured green at 826a8b3b (46 passed / 0 failed, one run, 2026-07-31); CI-image fitness unverified; #1017 burndown
@@ -25,7 +25,7 @@
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-issue-comment-usage-contract.sh && bash framework/tools/git/test-issue-comment-readback.sh && bash framework/tools/git/test-issue-close-usage-contract.sh && bash framework/tools/git/test-issue-reopen-usage-contract.sh && bash framework/tools/git/test-pr-close-usage-contract.sh && bash framework/tools/git/test-pr-review-usage-contract.sh && bash framework/tools/git/test-issue-edit-usage-contract.sh && bash framework/tools/git/test-issue-create-usage-contract.sh && bash framework/tools/git/test-pr-edit-usage-contract.sh && bash framework/tools/git/test-pr-create-usage-contract.sh && bash framework/tools/git/test-issue-assign-usage-contract.sh && bash framework/tools/git/test-milestone-close-usage-contract.sh && bash framework/tools/git/test-milestone-list-usage-contract.sh && bash framework/tools/git/test-issue-view-usage-contract.sh && bash framework/tools/git/test-issue-list-usage-contract.sh && bash framework/tools/git/test-milestone-create-usage-contract.sh && bash framework/tools/git/test-lane-brief-usage-contract.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
Author	SHA1	Message	Date
marcie	34e56f242e	framework tools/git: provider-normalization arms on issue-close and milestone-list (codex should-fix) ci/woodpecker/pr/ci Pipeline was successful Details gh stub exiting 2 on the close/api path -> wrapper exit 1 with the normalized stderr message; mirrors the issue-assign 6b arm. All touched suites green; brain mirror updated.	2026-08-28 18:33:32 -05:00
marcie	7db25b8820	framework tools/git: lookup-pipeline pipefail + provider-normalization test arm (codex round on PR #1464 ) ci/woodpecker/pr/ci Pipeline was canceled Details - issue-assign + milestone-create: set -o pipefail; the remove-assignee lookup pipeline now fails loud on provider failure instead of reading an empty result as a silent no-assignees skip (codex blocker). A successful lookup with zero assignees still skips the edit. - test-issue-assign-usage-contract: 6b arm proves provider-exit normalization end to end (gh stub exiting 2 on issue edit -> wrapper exit 1 with the normalized stderr message; codex should-fix). - Battery: 23/23 suites green.	2026-08-28 18:31:18 -05:00
marcie	90f982afaa	framework tools/git: guards reject all option-shaped values; usage_error routes usage to stderr (codex round on PR #1464 ) ci/woodpecker/pr/ci Pipeline is pending Details - Option-like value = any token starting with '-' followed by an alphanumeric (-h, -ab, --help); multi-character short clusters were still accepted (codex blocker). Bare '-' is reserved (future stdin). - usage_error now prints the usage text to stderr as well (codex should-fix): usage output belonged to stdout only on the help path. - 16/16 usage-contract suites green.	2026-08-28 18:28:28 -05:00
marcie	d326e6572a	framework tools/git: strict value guards + provider-failure normalization family-wide (codex blockers on PR #1464 ) ci/woodpecker/pr/ci Pipeline is pending Details - Value guards now reject option-like values: --anything always, and single-dash flag shapes (-h, -i). Previously -b --help consumed --help as the body and performed the write (codex example: issue-close -i --help proceeding to 'Closed GitHub issue #--help'). Multi-char dash-leading text (-start of a list) stays a legal value. - Every remaining direct provider exec (gh/tea/CMD arrays across issue-create/edit/assign/list/view, milestone-*, pr-create/edit, pr-close, issue-close/reopen) wrapped with rc capture and normalized to exit 1 with a stderr message — provider exit 2 no longer collides with the reserved usage-error status. - All 16 usage-contract suites gained option-like and short-flag arms (16/16 green). Existing suites re-verified; test-pr-edit and test-issue-create-interactive-auth fail identically with these changes stashed (environment-coupled, not regressions; documented).	2026-08-28 18:26:10 -05:00
marcie	ca91586222	framework tools/git: pr-review body-required actions fail fast (codex suggestion on PR #1464 ) ci/woodpecker/pr/ci Pipeline was canceled Details request-changes and comment both validate their required body immediately after argument parsing (rc 2, stderr, zero provider contact). The repo-host-override suite's action-message expectation updated to the new wording; suite green.	2026-08-28 18:17:30 -05:00
marcie	da4a5b2f19	framework tools/git: pr-review validates --action before provider contact (codex blocker on PR #1464 ) ci/woodpecker/pr/ci Pipeline was canceled Details An unsupported --action previously reached platform detection (and could touch the provider) before failing with a provider-class status; comment-without-body exited 1 mid-switch. Both now fail fast with usage_error (rc 2, stderr) immediately after argument parsing. Test arms added including the zero-provider-contact assertion for invalid-action runs.	2026-08-28 18:14:57 -05:00
marcie	e15e7fe822	framework tools/git: restore exec bit on test-lane-brief-pr-linkage.sh (stash cycle side effect) ci/woodpecker/pr/ci Pipeline was canceled Details	2026-08-28 18:12:32 -05:00
marcie	c8b4af59c3	framework tools/git: issue-list, milestone-create, lane-brief R1/R4 conversions (P1 complete) - issue-list + milestone-create: usage() default exit 2, value guards, missing-title via usage_error. - lane-brief: getopts replaced with a while/case parser carrying R2 long-flag aliases (--repo --milestone --label/--labels --login --limit) beside the short forms; login-resolution failure reclassified from exit 2 to exit 1 (credential class, not an invocation defect). - Three suites enrolled (population 88); lane-brief pr-linkage suite still ALL PASS; green in both trees; mirrored to the brain tree. With this, every agent-facing wrapper in tools/git carries the R1/R4 usage-error contract (22/22 non-guard wrappers; guards keep their own contracts).	2026-08-28 18:10:27 -05:00
marcie	bb23cb6feb	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.	2026-08-28 18:08:15 -05:00
marcie	0467d28191	framework tools/git: issue-assign R1/R4 conversion (P1) usage() default exit 2; value guards on -i/-a/-l/-m; -r stays boolean. Suite enrolled (population 82); mirrored to the brain tree.	2026-08-28 18:06:42 -05:00
marcie	cf971f93f8	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.	2026-08-28 18:05:17 -05:00
marcie	b8b396d9f5	framework tools/git: pr-edit R1/R4 conversion (P1) usage() default exit 2; semantic invocation checks (mutual exclusion, integer/format validation, missing edit option, --login-only-for-Gitea) exit 2; value guards on all value-taking options; existing pr-edit suite still green; usage-contract suite enrolled (population 80); mirrored to the brain tree.	2026-08-28 18:03:29 -05:00
marcie	c43b1a1293	framework tools/git: issue-create R1/R4 conversion + template bug fix (P1) - issue-create: usage() default exit is now 2 (usage-error contract); unknown option, missing title, and value-less -t/-b/-l/-m land there with stderr messages; exit-code line added to help. Interactive -i/--interactive unchanged (boolean, no value arm). Existing body-safety and interactive-auth suites still green. - Template bug fixed across ALL seven usage-contract suites: expect_stderr referenced an unbound $desc (should be $2); latent until issue-create's capitalized 'Unknown option' missed the case-sensitive grep and fired it. All seven re-verified green. - Suite enrolled (population 79); mirrored to the brain tree.	2026-08-28 18:01:12 -05:00
marcie	dff486b43a	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
marcie	31a447a46f	framework tools/git: pr-review R1/R4 conversion (P1) -b/--body canonical review comment flag with -c/--comment alias; usage errors stderr + exit 2 (unknown option, missing -n/-a, value-less flags including -a/-l/-r/-H, and the semantic check: request-changes without a comment). Existing pr-review suites still green. Suite enrolled in framework-shell CI (enumeration guard OK); mirrored to the brain tree.	2026-08-28 17:57:29 -05:00
marcie	7e4de270dc	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.	2026-08-28 17:55:09 -05:00
marcie	7a38eed18a	framework tools/git: issue-close R1/R4 conversion (P1 first wrapper) Same contract as issue-comment (PR #1462): -b/--body canonical comment flag with -c/--comment alias; usage errors stderr + exit 2 (unknown option, missing -i, value-less flags); provider failures normalized to exit 1 on the GitHub path (gh's own usage errors exit 2 and would collide with the reserved status). New suite test-issue-close-usage-contract.sh, enrolled in framework-shell CI (enumeration guard OK, population 74). Probe assertions split: parser arms must contact zero providers; sandbox arms may issue detection reads only (tea login list), never gh/curl. Existing fail-closed suite still green. Mirrored to the brain tree.	2026-08-28 17:53:02 -05:00
marcie	41f1bc0d37	framework tools/git: enroll issue-comment suites in framework-shell CI ci/woodpecker/pr/ci Pipeline was successful Details Codex review of `a27b7dc9` (blocker): check-test-enumeration.sh rejects unenumerated test files. - test-issue-comment-usage-contract.sh enrolled in test:framework-shell (hermetic by construction: PATH stubs, sandboxed runner, no network). - test-issue-comment-readback.sh enrolled and its stale exclusion removed. The exclusion's own note anticipated this: 'joins CI after the wrapper-half hermeticity fix' - that fix (neutralizing seat-exported MOSAIC_GIT_IDENTITY / MOSAIC_BRAIN_HOME that escape the sandboxed HOME) landed in `a27b7dc9`. Suite green in brain and worktree trees tonight. Enumeration guard: OK (population 73, enumerated 60, excluded 14).	2026-08-28 16:59:45 -05:00
marcie	a27b7dc9be	framework tools/git: sync issue-comment R1/R4 + hermeticity hardening from brain ci/woodpecker/pr/ci Pipeline failed Details Upstream of brain commits 08a00149 + 971586ef + the arm-6 sandbox fix (brain 5th commit of 2026-08-28 series): - R1: -b/--body is the canonical comment flag (matches issue-create, issue-edit, pr-create, pr-edit); -c/--comment stays a compatible alias. - R4: usage errors print to stderr and exit 2, distinct from provider, credential, and verification failures (exit 1). Value-less flags fail loudly (previously -c with no value died silently at rc=1 via set -e on the failed shift 2). gh failures on the GitHub path normalize to exit 1 (gh's own usage errors exit 2 and would collide with the reserved code). - Tests: new usage-contract suite (help rc, unknown/missing/value-less rc=2 on stderr, alias parse acceptance under a sandboxed runner, GitHub-path exit normalization with a stubbed gh, zero provider contact on parser failure); readback suite gains case 11 (full verified write via -b) and neutralizes seat-exported MOSAIC_GIT_IDENTITY / MOSAIC_BRAIN_HOME that escape the sandboxed HOME (documented HTTP 401 / fail-loud shapes). Driver: a fleet seat full-stopped on an issue-comment usage error because usage failures were indistinguishable from provider failures and the stop gate treated every wrapper failure as blocking.	2026-08-28 16:45:07 -05:00