[Bug] Enrichment parser not merging stories into existing features

[djm81]

Bug Description

When using specfact import from-code --enrichment, stories from LLM enrichment reports are not being correctly merged into existing features. The enrichment parser only adds stories when creating new features, but fails to merge stories when updating existing features that were already present in the plan bundle.

Steps to Reproduce

1. Run specfact import from-code to create an initial plan bundle with features
2. Generate an LLM enrichment report that includes stories for existing features
3. Run specfact import from-code --enrichment <enrichment-report.md>
4. Observe that stories from the enrichment report are not added to existing features

Expected Behavior

Stories from enrichment reports should be merged into existing features:

• New stories (by key) should be added to existing features
• Existing stories should be preserved
• Feature titles should be updated if they were empty

Actual Behavior

• Stories are only added when creating new features
• Existing features do not receive stories from enrichment reports
• This breaks the dual-stack enrichment workflow (CLI grounding → LLM enrichment → CLI artifact creation)

Impact

• User Impact: High - Breaks core enrichment workflow
• Severity: Critical - Prevents proper feature enrichment
• Workflow: Blocks dual-stack enrichment pattern for brownfield analysis

Example

With DjangoGoat validation:

• Initial CLI import: 1 feature, 2 stories
• LLM enrichment report: 8 features with 24 stories total
• After applying enrichment: Stories not merged into existing features
• Expected: 8 features with 24 stories correctly populated

Related

This affects the dual-stack enrichment workflow documented in docs/guides/dual-stack-enrichment.md.

[djm81]

Analysis

After investigating the enrichment parser code in src/specfact_cli/utils/enrichment_parser.py, we identified the root cause:

Problem

The apply_enrichment function had logic to add stories when creating new features, but when updating existing features, it only updated confidence and business context - it did not merge stories from the enrichment report.

Root Cause

In the apply_enrichment function:

1. When a feature already existed in the bundle, the code would:

   • Update confidence if provided
   • Update business context if provided
   • Skip story merging entirely

2. The story merging logic was only executed for new features being created, not for existing features being updated.

Impact

This broke the dual-stack enrichment workflow:

• CLI grounding phase: Creates initial features (often minimal)
• LLM enrichment phase: Generates comprehensive stories for those features
• CLI artifact creation: Stories were lost because they weren't merged into existing features

Verification

Tested with DjangoGoat validation:

• Initial import: 1 feature, 2 stories
• Enrichment report: 8 features with 24 stories
• Before fix: Stories not merged (only 2 stories total)
• After fix: All 24 stories correctly merged into 8 features

[djm81]

Fix Implementation

Solution

Modified apply_enrichment function in src/specfact_cli/utils/enrichment_parser.py to merge stories into existing features:

1. Story Merging Logic: Added logic to merge stories when updating existing features:

   • Iterate through stories from enrichment report
   • Check if story already exists by key
   • Add new stories that don't exist yet
   • Preserve existing stories

2. Feature Title Update: Also added logic to update feature title if it was empty:

   • If existing feature has empty title and enrichment report provides one, update it

3. Preservation: Ensured existing stories are preserved:

   • Only add stories that don't already exist (by key)
   • Maintain all existing feature metadata

Code Changes

• Enhanced apply_enrichment function to handle story merging for existing features
• Added story key checking to prevent duplicates
• Updated feature title from enrichment if empty
• Preserved all existing feature data

Testing

• Added comprehensive unit tests for story merging scenarios
• Added integration tests for end-to-end enrichment workflow
• Verified with DjangoGoat validation: 24 stories now correctly added across 8 features
• All tests passing

Version

Fixed in v0.20.4 (enrichment parser story merging fix)

[djm81]

Fixed in PR #58 (includes the enrichment parser fix from v0.20.4).

The fix ensures that stories from LLM enrichment reports are correctly merged into existing features, enabling the full dual-stack enrichment workflow.

[djm81]

Fixed in v0.20.4 and included in PR #58. The enrichment parser now correctly merges stories into existing features, enabling the full dual-stack enrichment workflow. Verified with DjangoGoat validation: 24 stories correctly added across 8 features.