sead-method-core/sead-core/tasks/catalog-external-integration.md

Specification Enforced Agentic Agile Development - A hybrid methodology preventing AI agent drift through catalog-based constraints with comprehensive external asset integration

# Catalog External Integration Task

## Purpose
Merge transformed external patterns with existing catalog structure, ensuring conflict resolution, pattern deduplication, and catalog integrity preservation.

## Inputs
- Transformed external assets from previous transformation tasks
- Current `sead-catalog/` structure
- `docs/external-asset-analysis.md` - Original analysis
- `docs/integration-architecture.md` - Integration strategy

## Outputs
- Unified `sead-catalog/` with external patterns integrated
- Conflict resolution documentation
- Integration decision log
- Updated catalog index and cross-references

## Constitutional Compliance
Enforced by external integration constitutional rules and catalog structure constraints.

## Mode Behavior
- **Prototype**: Basic merge with simple conflict resolution
- **Development**: Comprehensive integration with documented decisions
- **Build-to-Deploy**: Strict validation with full conflict resolution and documentation

## Workflow Steps

### 1. Pre-Integration Validation
```yaml
constitutional_check:
  - Verify all transformation tasks completed successfully
  - Confirm integration-architecture.md provides merge strategy
  - Validate existing catalog structure integrity
  - Check mode-appropriate integration requirements
```

### 2. Catalog Structure Analysis
```yaml
structure_analysis:
  existing_catalog_inventory:
    - scan_current_catalog_domains
    - identify_existing_patterns
    - map_pattern_dependencies
    - assess_catalog_maturity_level
  
  external_assets_inventory:
    - catalog_transformed_patterns
    - identify_new_domains_needed
    - map_external_pattern_relationships
    - assess_integration_complexity
  
  conflict_identification:
    naming_conflicts:
      - duplicate_pattern_names
      - conflicting_type_definitions
      - overlapping_component_interfaces
    
    structural_conflicts:
      - incompatible_catalog_organization
      - conflicting_domain_boundaries
      - mismatched_pattern_hierarchies
    
    semantic_conflicts:
      - different_pattern_purposes
      - conflicting_usage_constraints
      - incompatible_dependencies
```

### 3. Conflict Resolution Strategy
```yaml
conflict_resolution:
  naming_conflicts:
    resolution_strategies:
      - namespace_segregation (external.ButtonComponent vs ButtonComponent)
      - version_differentiation (ButtonV1 vs ButtonV2)  
      - purpose_qualification (LoginButton vs ActionButton)
      - domain_prefixing (AuthButton vs UIButton)
    
    decision_criteria:
      - preserve_existing_catalog_patterns
      - maintain_semantic_clarity
      - minimize_developer_confusion
      - support_gradual_migration

  structural_conflicts:
    reorganization_strategies:
      - create_external_subdomain_structure
      - merge_compatible_domains
      - establish_pattern_hierarchies
      - maintain_cross_reference_integrity
    
    integration_approaches:
      - side_by_side_coexistence
      - gradual_replacement_strategy
      - hybrid_pattern_composition
      - legacy_pattern_deprecation

  semantic_conflicts:
    resolution_methods:
      - pattern_purpose_clarification
      - usage_constraint_harmonization
      - dependency_reconciliation
      - documentation_enhancement
```

### 4. Pattern Integration Process
```yaml
integration_execution:
  domain_by_domain_integration:
    design_system:
      - merge_design_tokens
      - integrate_component_patterns
      - resolve_styling_conflicts
      - update_usage_documentation
    
    api_contracts:
      - merge_endpoint_definitions
      - integrate_type_definitions
      - resolve_schema_conflicts
      - update_integration_patterns
    
    shared_types:
      - merge_type_hierarchies
      - resolve_interface_conflicts
      - integrate_validation_schemas
      - update_export_mappings
    
    auth_patterns:
      - integrate_authentication_flows
      - merge_authorization_patterns
      - resolve_security_conflicts
      - update_implementation_guides

  cross_domain_integration:
    - establish_pattern_relationships
    - create_dependency_mappings
    - update_catalog_indexes
    - validate_cross_references
```

### 5. Catalog Index Updates
```yaml
index_management:
  catalog_structure_updates:
    - update_domain_readme_files
    - refresh_pattern_inventories
    - create_integration_markers
    - establish_migration_pathways
  
  cross_reference_updates:
    - update_pattern_dependencies
    - create_external_pattern_markers
    - establish_usage_relationships
    - document_migration_strategies
  
  search_and_discovery:
    - update_catalog_search_indexes
    - create_pattern_categorization
    - establish_tagging_systems
    - enhance_discoverability
```

### 6. Integration Validation
```yaml
integration_validation:
  structural_validation:
    - verify_catalog_structure_integrity
    - validate_pattern_organization
    - check_cross_reference_consistency
    - test_catalog_navigation
  
  functional_validation:
    - test_pattern_usability
    - verify_integration_patterns
    - validate_dependency_resolution
    - check_constraint_enforcement
  
  documentation_validation:
    - verify_integration_documentation
    - validate_usage_examples
    - check_migration_guidance
    - test_adoption_pathways
```

### 7. Integration Documentation
```yaml
documentation_creation:
  integration_decision_log:
    - document_all_conflict_resolutions
    - record_integration_strategies
    - capture_architectural_decisions
    - maintain_change_rationale
  
  catalog_evolution_documentation:
    - document_catalog_structure_changes
    - record_new_domain_additions
    - capture_pattern_relationships
    - maintain_version_history
  
  migration_documentation:
    - create_adoption_pathways
    - document_breaking_changes
    - provide_migration_scripts
    - establish_support_resources
```

## Mode-Specific Requirements

### Prototype Mode
- Basic pattern merging with simple conflict resolution
- Minimal documentation of integration decisions
- Simple validation checks for structural integrity
- Basic catalog index updates

### Development Mode
- Comprehensive conflict resolution with documented strategies
- Complete integration validation across all domains
- Thorough documentation of all decisions and changes
- Full catalog index updates with cross-references

### Build-to-Deploy Mode
- Strict conflict resolution with formal approval processes
- Complete validation including security and performance
- Comprehensive documentation with audit trails
- Full catalog compliance verification and testing

## Integration Principles
- Preserve existing catalog patterns where possible
- Minimize breaking changes to existing usage
- Maintain semantic clarity and purpose distinction
- Support gradual migration from existing to new patterns
- Ensure catalog structural integrity throughout process
- Document all decisions for future maintainability

## Error Handling
- Unresolvable conflicts: Escalate with detailed conflict analysis
- Structural integrity violations: Block with remediation requirements
- Documentation gaps: Warning with documentation enhancement needs
- Validation failures: Block with specific remediation steps
- Cross-reference breaks: Error with dependency resolution guidance

## Success Criteria
- All external patterns successfully integrated into catalog
- All conflicts resolved with documented strategies
- Catalog structural integrity maintained
- Complete integration documentation created
- Validation passing for all integrated patterns
- Clear migration pathways established for teams

## Integration Points
- Requires completed transformation tasks for all external assets
- Requires `integration-architecture.md` from sead-architect
- Feeds into `external-asset-validation.md` for final validation
- Supports `external-adoption-strategy.md` creation
- Updates all existing catalog domain structures
- Creates foundation for ongoing catalog evolution