Use default=True as a sentinel for non-boolean flags

Refs: #3111

Author: kdeldycke

src/click/core.py

@@ -2891,13 +2891,33 @@ def to_info_dict(self) -> dict[str, t.Any]:
     def get_default(
         self, ctx: Context, call: bool = True
     ) -> t.Any | t.Callable[[], t.Any] | None:
+        """For non-boolean flag options, ``default=True`` is treated as a
+        sentinel meaning "activate this flag by default" and is resolved to
+        :attr:`flag_value`. This resolution is performed lazily here (rather
+        than eagerly in :meth:`__init__`) to prevent callable ``flag_value``
+        values (like classes) from being instantiated prematurely
+        (:issue:`3121`, :pr:`3225`).
+
+        For example, with ``--upper/--lower`` feature switches where
+        ``flag_value="upper"`` and ``default=True``, the default resolves
+        to ``"upper"``.
+
+        .. caution::
+            This substitution only applies to **non-boolean** flags
+            (:attr:`is_bool_flag` is ``False``). For boolean flags, ``True`` is
+            not a sentinel but a legitimate Python value, so ``default=True`` is
+            returned as-is. Without this distinction, ``flag_value=False,
+            default=True`` would silently always return ``False``, regardless of
+            whether the flag was passed or not.
+
+        .. versionchanged:: 8.3
+            ``default=True`` is no longer substituted with ``flag_value`` for
+            boolean flags, fixing negative boolean flags like ``flag_value=False,
+            default=True``. :issue:`3111`
+        """
         value = super().get_default(ctx, call=False)
 
-        # Lazily resolve default=True to flag_value. Doing this here
-        # (instead of eagerly in __init__) prevents callable flag_values
-        # (like classes) from being instantiated by the callable check below.
-        # https://github.com/pallets/click/issues/3121
-        if value is True and self.is_flag:
+        if value is True and self.is_flag and not self.is_bool_flag:
             value = self.flag_value
         elif call and callable(value):
             value = value()