feat: Core Contracts and Module Interface Formalization

[djm81]

Description

Implements OpenSpec change arch-04-core-contracts-interfaces with contract-first module interfaces, core/module isolation checks, schema-versioned module metadata, and documentation updates.

Fixes #206

Cross-repo reference #206

New Features #206

Contract References

• src/specfact_cli/contracts/module_interface.py (ModuleIOContract)
• src/specfact_cli/models/validation.py (ValidationReport)
• src/specfact_cli/registry/module_packages.py (_check_protocol_compliance, _check_schema_compatibility)
• src/specfact_cli/modules/{backlog,sync,plan,generate,enforce}/src/commands.py (module IO contract operations)

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 📚 Documentation update
• 🔒 Contract enforcement (adding/updating @icontract decorators)
• 🧪 Test enhancement (scenario tests, property-based tests)
• 🔧 Refactoring (code improvement without functionality change)

How Has This Been Tested?

Automated Testing

• hatch run pytest tests/unit/contracts/test_module_io_contract.py -v
• hatch run pytest tests/unit/test_core_module_isolation.py -v
• hatch run pytest tests/unit/models/test_project_bundle_schema.py -v
• hatch run pytest tests/unit/models/test_module_package_metadata.py -v
• hatch run pytest tests/unit/registry/test_module_protocol_validation.py -v
• hatch run pytest tests/unit/modules/ -k test_module_io_contract -v
• hatch run contract-test
• hatch test --cover -v (1 flaky failure observed in full-suite run; targeted rerun passed)
• openspec validate arch-04-core-contracts-interfaces --strict

Deliverables

• ModuleIOContract protocol and ValidationReport model
• AST-based core-module isolation test + CI workflow enforcement step
• ProjectBundle schema_version field
• Module package metadata extensions (schema_version, protocol_operations)
• Module discovery protocol/schema compatibility checks and logging
• Module IO contract functions for backlog/sync/plan/generate/enforce
• New docs: ProjectBundle schema + module contracts; architecture/nav/README updates