feat(bmad): support alphanumeric IDs and introduce agile timeline dashboard

[magalz]

Overview

This PR enhances the BMAD artifact parser to support alphanumeric IDs (e.g., DI-1, HK-1.2), allowing teams to use semantic prefixes for Epics and Stories. It also includes UI component updates to display this tracking data correctly.

Issue

The dashboard and parser rigidly expected numeric-only IDs (e.g., 1-1-title). If teams created epics "on the fly" using semantic acronyms or names (like DI for DevOps/Infra or HK for Housekeeping), the parser failed to recognize them. Consequently, these non-numeric epics and their associated stories were completely ignored and hidden from the dashboard.

Proposed Change

The system natively understands and extracts alphanumeric identifiers (e.g., DI-1, HK-1). This ensures that epics created outside the standard numeric sequence are correctly tracked, correlated with their stories, and fully visible on the dashboard, preventing blind spots in project visibility.

Changes Made & Flow

1. Alphanumeric Parsing & Normalization

Flow: The core regex patterns in the parsers were updated to accept alphanumeric strings (e.g., [a-z][a-z0-9_-]*). When an alphanumeric ID is found (like DevOps/Infra), a new normalization utility safely converts it to a standard slug format (e.g., devops-infra). This guarantees that semantic prefixes from both filenames and frontmatter are cleanly extracted while remaining backward compatible with purely numeric IDs.

• Modified Files:
  • src/lib/bmad/parser.ts
  • src/lib/bmad/parse-epic-file.ts
  • src/lib/bmad/parse-story.ts
  • src/lib/bmad/parse-sprint-status.ts
  • src/lib/bmad/parse-epics.ts
  • src/lib/bmad/utils.ts

2. Enhanced Correlation & Strict Filtering

Flow: The linking engine was upgraded with a two-way "backfill" strategy. If a story's inferred epic ID (e.g., DI) does not strictly match any existing epic ID (e.g., devops-infra), the system performs a reverse lookup. It scans the list of stories extracted directly from the Epic's markdown body. If the Epic explicitly lists that story, the engine confidently links them together and updates the story's epicId. Furthermore, this logic enforces strict declaration checks: story artifacts are now only correlated and displayed if they are explicitly declared within an Epic's markdown body or the sprint plan. This actively prevents stale or duplicate orphan story files (e.g., an abandoned 1.5 artifact) from accidentally surfacing on the dashboard and causing rendering errors.

• Modified Files:
  • src/lib/bmad/correlate.ts
  • src/lib/bmad/types.ts

3. UI & Agile Dashboard Updates

Flow: Dashboard components were upgraded to gracefully render the new alphanumeric data. A new getEpicShortId utility dynamically derives a clean, abbreviated prefix for Epics by reverse-engineering it from its child stories (e.g., looking at story DI-1.2 to label the Epic as DI). For Stories, the UI splits the full identifier to display only the order/numbering (e.g., extracting 1.2). This allows badges and headers to remain visually compact on the board, while keeping the full ID (like devops-infra) accessible via hover tooltips. Sorting mechanisms were also updated to use natural alphanumeric sorting.

• Modified Files:
  • src/components/dashboard/epics-list.tsx
  • src/components/dashboard/sprint-summary-card.tsx
  • src/components/epics/epic-timeline-card.tsx
  • src/components/epics/epics-browser.tsx
  • README.md (Added documentation for naming conventions)

4. Cross-Platform Security Bugfix

Flow: Fixed a silent path resolution bug that caused security validations to fail on Windows machines. The code now actively sanitizes native Windows path separators (\) to POSIX-style slashes (/) before verifying if the files belong to the authorized _bmad directory, preventing false "Access denied" errors locally.

• Modified Files:
  • src/lib/content-provider/local-provider.ts

Testing & Validation

• Unit Tests (+30 tests): Added comprehensive coverage for mixed ID parsing, backfill correlation logic, and path validations.
  • Files: All files within src/lib/bmad/__tests__/*
• pnpm lint, pnpm test, and pnpm build pass locally on both POSIX and native Windows environments.

Closes #[Issue_Number]