diff --git a/packages/mosaic/framework/tools/git/issue-assign.sh b/packages/mosaic/framework/tools/git/issue-assign.sh
index 48d5c04b..a899eec0 100755
--- a/packages/mosaic/framework/tools/git/issue-assign.sh
+++ b/packages/mosaic/framework/tools/git/issue-assign.sh
@@ -33,25 +33,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
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             ISSUE="$2"
             shift 2
             ;;
         -a|--assignee)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             ASSIGNEE="$2"
             shift 2
             ;;
         -l|--labels)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             MILESTONE="$2"
             shift 2
             ;;
diff --git a/packages/mosaic/framework/tools/git/test-issue-assign-usage-contract.sh b/packages/mosaic/framework/tools/git/test-issue-assign-usage-contract.sh
new file mode 100755
index 00000000..c7e537a6
--- /dev/null
+++ b/packages/mosaic/framework/tools/git/test-issue-assign-usage-contract.sh
@@ -0,0 +1,125 @@
+#!/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
+
+# 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).
+
+echo "issue-assign.sh usage-contract regression passed (R1/R4)"
diff --git a/packages/mosaic/package.json b/packages/mosaic/package.json
index 78d2a85a..9339f310 100644
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -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-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-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-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:*",