Jonah/omn 1297 remove ai slop patterns from codebase

CLAUDE.md

@@ -356,6 +356,86 @@ poetry run ruff check --fix src/ tests/  # Auto-fix
 pre-commit run --all-files               # Run all hooks
 ```
 
+### Docstring Guidelines
+
+Follow these guidelines to avoid "AI slop" - docstrings that add noise without value.
+
+#### Docstrings to AVOID (Tautological)
+
+Do NOT write docstrings that simply restate the method name:
+
+```python
+# BAD - These add no value
+def get_name(self):
+    """Get the name."""  # Just restates method name
+
+def set_status(self, value):
+    """Set the status."""  # Obvious from signature
+
+def validate_input(self):
+    """Validate input."""  # No new information
+
+def is_active(self) -> bool:
+    """Check if active."""  # Obvious from name and return type
+```
+
+#### Docstrings to WRITE (Valuable)
+
+Write docstrings that explain WHY, describe non-obvious behavior, or document edge cases:
+
+```python
+# GOOD - These add value
+def get_name(self) -> str:
+    """Return canonical name, falling back to id if name is None."""
+
+def set_status(self, value: str) -> None:
+    """Update status and emit StatusChanged event to all subscribers."""
+
+def validate_input(self) -> bool:
+    """
+    Validate against schema v2 rules.
+
+    Raises:
+        ValidationError: If required fields are missing or malformed.
+    """
+
+def is_active(self) -> bool:
+    """Check activation considering both enabled flag and expiry timestamp."""
+```
+
+#### When to Write Docstrings
+
+| Situation | Docstring Needed? | Example |
+|-----------|-------------------|---------|
+| Complex logic | Yes | Algorithms, state machines, multi-step processes |
+| Non-obvious behavior | Yes | Side effects, event emission, caching |
+| Public API | Yes | Module/class/function interfaces |
+| Edge cases | Yes | Error conditions, boundary values |
+| Simple getter/setter | No | `get_id()`, `set_name()` |
+| Obvious from signature | No | `def add(a: int, b: int) -> int` |
+| Private helpers | Usually no | `_parse_line()`, `_normalize()` |
+
+#### Module and Class Docstrings
+
+Keep module docstrings concise (3-6 lines max for simple modules):
+
+```python
+# GOOD - Concise module docstring
+"""Enumeration for node execution status.
+
+Defines lifecycle states for node execution from pending to completed.
+"""
+
+# BAD - Verbose module docstring (avoid)
+"""
+Enumeration for node execution status.
+
+This module provides a comprehensive enumeration of all possible
+execution states that a node can be in during its lifecycle...
+[18 more lines of obvious information]
+"""
+```
+
 ### Type Annotation Style (PEP 604)
 
 **Always use PEP 604 union syntax** (enforced by ruff UP007):
@@ -518,6 +598,24 @@ Some files are excluded from single-class-per-file validation due to architectur
 
 These exclusions are documented in `.pre-commit-config.yaml` under `validate-single-class-per-file`.
 
+### Enum String Serialization
+
+All string-based enums should use `StrValueHelper` for consistent `__str__` behavior:
+
+```python
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
+
+class EnumStatus(StrValueHelper, str, Enum):
+    """Status values for workflow execution."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+
+# StrValueHelper provides __str__ that returns self.value
+str(EnumStatus.PENDING)  # Returns: "pending"
+```
+
+**Note**: `StrValueHelper` is a utility mixin for enums, not a node mixin. It is located in `omnibase_core.utils`, not `omnibase_core.mixins`.
 ### Pydantic Model Configuration Standards
 
 Every Pydantic model MUST have an explicit `model_config`. Empty `ConfigDict()` is not allowed - it has ambiguous intent and provides no explicit policy for model behavior (extra fields, mutability, etc.). Models must declare their configuration explicitly.

pyproject.toml

@@ -77,7 +77,6 @@ python = "^3.12"
 pydantic = "^2.12.5"
 pyyaml = "^6.0.2"
 dependency-injector = "^4.48.3"
-deepdiff = "^8.0.0"
 
 # CLI Dependencies
 click = "^8.3.1"

src/omnibase_core/decorators/decorator_error_handling.py

@@ -80,6 +80,7 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
             except ModelOnexError:
                 # Always re-raise ModelOnexError as-is to preserve error context
                 raise
+            # boundary-ok: converts unhandled exceptions to structured ModelOnexError at function boundary
             except Exception as e:
                 # Convert generic exceptions to ModelOnexError with proper chaining
                 msg = f"{operation_name} failed: {e!s}"

src/omnibase_core/enums/enum_acknowledgment_type.py

@@ -5,10 +5,13 @@
 and registration processes.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
 
-class EnumAcknowledgmentType(str, Enum):
+
+@unique
+class EnumAcknowledgmentType(StrValueHelper, str, Enum):
     """Canonical acknowledgment types for ONEX discovery."""
 
     BOOTSTRAP_ACK = "bootstrap_ack"

src/omnibase_core/enums/enum_action_category.py

@@ -4,9 +4,10 @@
 Categories for organizing different types of actions across tools.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumActionCategory(str, Enum):
     """
     Categories for organizing different types of actions across tools.

src/omnibase_core/enums/enum_activation_reason.py

@@ -14,9 +14,11 @@
 
 from enum import Enum, unique
 
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
+
 
 @unique
-class EnumActivationReason(str, Enum):
+class EnumActivationReason(StrValueHelper, str, Enum):
     """
     Reason for capability activation or skip.
 
@@ -98,10 +100,6 @@ class EnumActivationReason(str, Enum):
     TIMEOUT_EXCEEDED = "timeout_exceeded"
     """Activation window expired before capability could be activated."""
 
-    def __str__(self) -> str:
-        """Return the string value for serialization."""
-        return self.value
-
     def is_activation_reason(self) -> bool:
         """
         Check if this reason indicates successful activation.

src/omnibase_core/enums/enum_agent_capability.py

@@ -4,9 +4,10 @@
 Defines capabilities that agents can have for task routing and selection.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumAgentCapability(str, Enum):
     """Agent capabilities for intelligent task routing."""
 

src/omnibase_core/enums/enum_agent_status_type.py

@@ -5,9 +5,10 @@
 Strongly-typed enumeration for agent status types.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumAgentStatusType(str, Enum):
     """Agent status enumeration."""
 

src/omnibase_core/enums/enum_analysis_status.py

@@ -4,9 +4,10 @@
 ONEX-compatible enum for standardized analysis status values.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumAnalysisStatus(str, Enum):
     """Enumeration for analysis status values."""
 

src/omnibase_core/enums/enum_architecture.py

@@ -7,6 +7,7 @@
 import enum
 
 
+@enum.unique
 class EnumArchitecture(enum.StrEnum):
     """Supported CPU architectures."""
 

src/omnibase_core/enums/enum_argument_type.py

@@ -4,9 +4,10 @@
 Defines the available types for CLI command arguments.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumArgumentType(str, Enum):
     """
     Enumeration of CLI argument types.

src/omnibase_core/enums/enum_artifact_type.py

@@ -1,8 +1,9 @@
 """Artifact type enumeration for ONEX core."""
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumArtifactType(str, Enum):
     """Artifact types for ONEX ecosystem."""
 

src/omnibase_core/enums/enum_assembly_strategy.py

@@ -5,9 +5,10 @@
 with proper ONEX enum naming conventions.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumAssemblyStrategy(str, Enum):
     """LLM result assembly strategies."""
 

src/omnibase_core/enums/enum_audit_action.py

@@ -1,6 +1,9 @@
-from enum import Enum
+"""Audit action types for logging and compliance tracking."""
 
+from enum import Enum, unique
 
+
+@unique
 class EnumAuditAction(str, Enum):
     """Common audit actions."""
 

src/omnibase_core/enums/enum_auth_type.py

@@ -4,10 +4,13 @@
 Authentication types for webhook notifications in ONEX infrastructure.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
 
-class EnumAuthType(str, Enum):
+
+@unique
+class EnumAuthType(StrValueHelper, str, Enum):
     """Enumeration for authentication types used in webhook communications."""
 
     # No authentication
@@ -24,10 +27,6 @@ class EnumAuthType(str, Enum):
     DIGEST = "digest"  # Digest authentication
     CUSTOM = "custom"  # Custom authentication method
 
-    def __str__(self) -> str:
-        """Return the string value of the authentication type."""
-        return self.value
-
     @classmethod
     def requires_credentials(cls, auth_type: "EnumAuthType") -> bool:
         """

src/omnibase_core/enums/enum_authentication_method.py

@@ -1,7 +1,12 @@
-from enum import Enum
+"""Authentication method types for session and identity contexts."""
 
+from enum import Enum, unique
 
-class EnumAuthenticationMethod(str, Enum):
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
+
+
+@unique
+class EnumAuthenticationMethod(StrValueHelper, str, Enum):
     """Authentication methods supported for session and identity contexts."""
 
     # No authentication
@@ -26,10 +31,6 @@ class EnumAuthenticationMethod(str, Enum):
     # Enhanced security methods
     MULTI_FACTOR = "multi_factor"  # Multi-factor authentication (MFA)
 
-    def __str__(self) -> str:
-        """Return the string value of the authentication method."""
-        return self.value
-
     @classmethod
     def is_federated(cls, method: "EnumAuthenticationMethod") -> bool:
         """

src/omnibase_core/enums/enum_backend_type.py

@@ -4,11 +4,12 @@
 This enum defines the supported secret backend types in the system.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 from omnibase_core.enums.enum_core_error_code import EnumCoreErrorCode
 
 
+@unique
 class EnumBackendType(Enum):
     """Supported secret backend types."""
 

src/omnibase_core/enums/enum_backoff_strategy.py

@@ -4,9 +4,10 @@
 Retry backoff strategies for infrastructure resilience in ONEX systems.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumBackoffStrategy(str, Enum):
     """Enumeration for retry backoff strategies used in infrastructure components."""
 

src/omnibase_core/enums/enum_business_logic_pattern.py

@@ -1,6 +1,9 @@
-from enum import Enum
+"""Business logic pattern classifications for node categorization."""
 
+from enum import Enum, unique
 
+
+@unique
 class EnumBusinessLogicPattern(str, Enum):
     """Business logic pattern classifications."""
 

src/omnibase_core/enums/enum_cache_eviction_policy.py

@@ -5,9 +5,10 @@
 Defines eviction strategies for cache management.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumCacheEvictionPolicy(str, Enum):
     """
     Cache eviction policy enumeration for ONEX caching systems.

src/omnibase_core/enums/enum_case_mode.py

@@ -4,9 +4,10 @@
 This module defines the case modes available for CASE_CONVERSION transformations.
 """
 
-from enum import Enum
+from enum import Enum, unique
 
 
+@unique
 class EnumCaseMode(str, Enum):
     """
     Case transformation modes.