Migrate PRD to OpenSpec format

documentation/architecture/openspec/specs/attribute-concealment/spec.md

@@ -0,0 +1,29 @@
+# Attribute Concealment
+
+## Purpose
+This capability provides mechanisms to conceal non-public attributes from `dir()` output, reducing API noise and clearly communicating public interfaces.
+
+## Requirements
+
+### Requirement: Default Concealment
+By default, only public attributes (those not starting with `_`) SHALL be visible in `dir()` output.
+
+Priority: High
+
+#### Scenario: Inspect Object with dir()
+- **WHEN** `dir()` is called on a standard class or instance
+- **THEN** attributes starting with `_` are not included in the output
+- **BUT** attributes starting with `_` are still accessible if referenced directly
+
+### Requirement: Selective Visibility
+Users SHALL be able to customize visibility rules using names, regexes, or custom predicates.
+
+Priority: Medium
+
+#### Scenario: Custom Visibility Rules
+- **WHEN** a user defines `class_visibles` or `instances_visibles` with specific rules
+- **THEN** attributes matching the rules are included in `dir()` output regardless of their name
+
+#### Scenario: Full Visibility
+- **WHEN** a user sets `class_visibles` or `instances_visibles` to `'*'`
+- **THEN** all attributes (including those starting with `_`) are visible in `dir()` (standard Python behavior)

documentation/architecture/openspec/specs/attribute-immutability/spec.md

@@ -0,0 +1,34 @@
+# Attribute Immutability
+
+## Purpose
+This capability provides mechanisms to make class and instance attributes immutable after initialization, preventing accidental state modification and enabling safer concurrent access. It also allows for selective mutability where specific attributes need to remain mutable.
+
+## Requirements
+
+### Requirement: Immutable Attributes
+Classes and instances SHALL have immutable attributes after initialization is complete.
+
+Priority: Critical
+
+#### Scenario: Modify Immutable Attribute
+- **WHEN** a user attempts to modify an attribute on a standard class or instance after initialization
+- **THEN** an `AttributeImmutability` exception is raised
+- **AND** the attribute value remains unchanged
+
+#### Scenario: Delete Immutable Attribute
+- **WHEN** a user attempts to delete an attribute on a standard class or instance after initialization
+- **THEN** an `AttributeImmutability` exception is raised
+- **AND** the attribute remains present
+
+### Requirement: Selective Mutability
+Users SHALL be able to specify exceptions to immutability rules using names, regexes, or custom predicates.
+
+Priority: High
+
+#### Scenario: Define Mutable Attributes
+- **WHEN** a user defines `class_mutables` or `instances_mutables` with specific names, regexes, or predicates
+- **THEN** matching attributes can be modified or deleted without raising an exception
+
+#### Scenario: Disable Immutability
+- **WHEN** a user sets `class_mutables` or `instances_mutables` to `'*'`
+- **THEN** all attributes on the class or instance are mutable

documentation/architecture/openspec/specs/dataclass-integration/spec.md

@@ -0,0 +1,39 @@
+# Dataclass Integration
+
+## Purpose
+This capability integrates immutability and concealment features with Python's standard `dataclasses`, ensuring seamless operation and preserving dataclass functionality.
+
+## Requirements
+
+### Requirement: Dataclass Support
+The library SHALL provide metaclasses and decorators to create dataclasses with standard behaviors.
+
+Priority: Critical
+
+#### Scenario: Define Standard Dataclass
+- **WHEN** a class uses the `Dataclass` metaclass or `DataclassObject` base
+- **THEN** it is automatically converted to a dataclass
+- **AND** standard immutability and concealment behaviors are applied
+
+#### Scenario: Post-Init Modification
+- **WHEN** `__post_init__` is defined in a standard dataclass
+- **THEN** it can modify attributes
+- **BUT** attributes become immutable after `__post_init__` completes
+
+### Requirement: Dataclass Configuration
+The integration SHALL support standard dataclass arguments such as `frozen`, `slots`, and `kw_only`.
+
+Priority: High
+
+#### Scenario: Custom Dataclass Arguments
+- **WHEN** a standard dataclass is defined with arguments like `slots=True`
+- **THEN** the resulting class honors these arguments while maintaining standard behaviors
+
+### Requirement: Type Checker Recognition
+Classes produced by the library SHALL be recognized as dataclasses by static type checkers.
+
+Priority: High
+
+#### Scenario: Type Checking
+- **WHEN** a static type checker (e.g., Pyright, MyPy) analyzes a standard dataclass
+- **THEN** it correctly infers dataclass fields and behavior (via `dataclass_transform`)

documentation/architecture/openspec/specs/extensibility/spec.md

@@ -0,0 +1,33 @@
+# Extensibility
+
+## Purpose
+This capability provides hooks and factory functions for users to create custom behaviors and metaclasses, allowing the core machinery to be reused for custom implementations.
+
+## Requirements
+
+### Requirement: Factory Functions
+The library SHALL provide factory functions for creating custom metaclasses and decorators.
+
+Priority: Medium
+
+#### Scenario: Create Custom Metaclass
+- **WHEN** a user invokes `class_factory` with custom arguments
+- **THEN** a new metaclass is produced that incorporates the specified behaviors
+
+### Requirement: Custom Hooks
+The library SHALL support hooks for class construction, initialization, and decoration.
+
+Priority: Medium
+
+#### Scenario: Custom Class Construction
+- **WHEN** a user provides a custom preprocessor or postprocessor
+- **THEN** it is executed during the class creation process
+
+### Requirement: Core Function Replacement
+Users SHALL be able to replace core behavior functions (assigner, deleter, surveyor).
+
+Priority: Low
+
+#### Scenario: Custom Assigner
+- **WHEN** a user provides a `instances_assigner_core` argument
+- **THEN** that function is used to handle attribute assignment instead of the default implementation

documentation/architecture/openspec/specs/module-security/spec.md

@@ -0,0 +1,36 @@
+# Module Security
+
+## Purpose
+This capability allows applying immutability and concealment to module objects to protect module namespaces from accidental modification and pollution.
+
+## Requirements
+
+### Requirement: Module Reclassification
+The library SHALL provide functions to reclassify modules to use a custom module class with standard behaviors.
+
+Priority: Medium
+
+#### Scenario: Reclassify Module
+- **WHEN** `reclassify_module` or `finalize_module` is called on a module
+- **THEN** the module's class is changed to `Module` (or a subclass)
+- **AND** module attributes become immutable (unless exempted)
+- **AND** non-public module attributes are concealed from `dir()`
+
+### Requirement: Recursive Application
+Users SHALL be able to apply reclassification recursively to submodules.
+
+Priority: Low
+
+#### Scenario: Recursive Reclassification
+- **WHEN** `finalize_module` is called with `recursive=True`
+- **THEN** all submodules within the same package are also reclassified
+
+### Requirement: Documentation Integration
+`finalize_module` SHALL integrate with Dynadoc to apply docstrings and reclassification in one step.
+
+Priority: Low
+
+#### Scenario: Finalize Module
+- **WHEN** `finalize_module` is called
+- **THEN** the module's docstring is generated/assigned
+- **AND** the module is reclassified

documentation/architecture/openspec/specs/protocol-support/spec.md

@@ -0,0 +1,34 @@
+# Protocol Support
+
+## Purpose
+This capability provides protocol classes with immutability and concealment that work with structural subtyping, enabling type-safe interfaces with guaranteed stability.
+
+## Requirements
+
+### Requirement: Protocol Definition
+The library SHALL provide metaclasses and base classes for defining protocols with standard behaviors.
+
+Priority: High
+
+#### Scenario: Define Standard Protocol
+- **WHEN** a class uses the `Protocol` metaclass or `ProtocolObject` base
+- **THEN** it functions as a `typing.Protocol`
+- **AND** it has standard immutability and concealment behaviors
+
+### Requirement: Structural Subtyping
+Protocol functionality SHALL be preserved, including structural subtyping and runtime checks.
+
+Priority: Critical
+
+#### Scenario: Runtime Check
+- **WHEN** `isinstance()` is used with a standard protocol
+- **THEN** it correctly identifies objects that implement the protocol
+
+### Requirement: Implementation Inheritance
+Immutability and concealment behaviors SHALL be inherited by protocol implementations where appropriate.
+
+Priority: Medium
+
+#### Scenario: Implement Protocol
+- **WHEN** a class implements a standard protocol
+- **THEN** it behaves according to the protocol's defined behaviors