Bundle/Spec Mapping Strategy

[djm81]

Objective

Implement intelligent spec-to-bundle assignment with confidence scoring and user confirmation to prevent mis-bundled specs. This addresses the current manual or heuristic-based bundle assignment that leads to specs landing in wrong bundles and makes conflict detection unreliable.

This change implements Plan C from the SpecFact Backlog & OpenSpec Implementation Roadmap (2026-01-18), providing intelligent bundle mapping with three confidence signals (explicit labels, historical patterns, content similarity) and interactive review for ambiguous mappings.

Technical Approach

• NEW: BundleMapper engine (src/specfact_cli/backlog/bundle_mapper.py) - Confidence-based mapping with three signals
• NEW: BundleMapping model (src/specfact_cli/models/bundle_mapping.py) - Result model with bundle_id, confidence, candidates, explanation
• NEW: Mapping history persistence (.specfact/config.yaml) - Auto-learned rules from user confirmations
• NEW: Interactive mapping UI (src/specfact_cli/cli/backlog_commands.py) - User prompts with confidence visualization
• EXTEND: --auto-bundle flag for backlog refine and backlog import commands
• EXTEND: SourceTracking model - Add mapping metadata fields (bundle_id, mapping_confidence, mapping_method, mapping_timestamp)
• EXTEND: OpenSpec generation pipeline - Accept BundleMapping parameter and record mapping decisions

Success Criteria

• Bundle mapping uses three confidence signals (explicit labels, historical patterns, content similarity)
• Interactive review for ambiguous mappings
• Auto-learned rules from user confirmations
• Integration with Plan A (Template-Driven Refinement) and Plan B (Generic Backlog Abstraction)
• OpenSpec generation pipeline records mapping decisions in source tracking

Dependencies

• Plan A (Template-Driven Refinement) - Uses mapping for --auto-bundle flag
• Plan B (Generic Backlog Abstraction) - Works with any adapter output
• OpenSpec generation pipeline - Records mapping decisions in source tracking

Risks

• Mapping accuracy depends on quality of historical data
• User confirmation workflow may slow down batch operations

---

OpenSpec Change Proposal: add-bundle-mapping-strategy

[djm81]

OpenSpec Change Proposal Reference

This backlog item was refined using SpecFact CLI template-driven refinement.

• Change ID: add-bundle-mapping-strategy
• Template: enabler_v1
• Confidence: 0.80
• Refined: 2026-01-21T09:04:31Z

Note: Original body preserved. This comment provides OpenSpec reference for cross-sync.