eslint-plugin-traceability 1.1.0 → 1.1.2

package/docs/stories/006.0-DEV-FILE-VALIDATION.story.md

@@ -1,127 +0,0 @@
-# 006.0-DEV-FILE-VALIDATION: Story File Reference Validation
-
-## Release Goal
-
-_Release 0.1: Core Validation - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches_
-
-This story implements validation logic that verifies @story annotations reference actual story files that exist in the project and have the correct .story.md extension. It completes the core file reference validation needed to ensure traceability annotations point to valid, accessible story files.
-
-## How This Story Contributes
-
-This story completes the "Validate Annotations" journey phase by ensuring @story references point to actual files that exist and follow the required naming convention. It prevents broken traceability links and enables confident requirement validation, bridging the gap between code annotations and their corresponding story documentation.
-
-## User Story
-
-**Format**: So that I can ensure my @story annotations reference valid story files, as a Developer, I want validation that checks @story file paths exist, are accessible, and follow the .story.md naming convention.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after annotation format validation (depends on 001.0-005.0)
-- **Negotiable**: File validation strictness and path resolution can be refined during implementation
-- **Valuable**: Delivers confidence that traceability links point to valid documentation
-- **Estimable**: Scope is clear - file system validation with defined path requirements
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: File validation can be tested with various file system scenarios
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [ ] **Core Functionality**: Validates @story file paths reference existing .story.md files
-- [ ] **Quality Standards**: Follows ESLint development best practices and handles file system operations safely
-- [ ] **Integration**: Works with annotations validated by format validation (005.0)
-- [ ] **User Experience**: Clear error messages indicate which files are missing or invalid
-- [ ] **Error Handling**: Gracefully handles file system permissions, network drives, and edge cases
-- [ ] **Documentation**: File validation specification with path resolution rules and examples
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-FILE-EXISTENCE**: Verify @story file paths reference existing files
-- **REQ-PATH-RESOLUTION**: Resolve relative paths from project root or current file location
-- **REQ-SECURITY-VALIDATION**: Prevent path traversal attacks and access to restricted directories
-- **REQ-PERFORMANCE-OPTIMIZATION**: Efficient file system access with caching for repeated checks
-- **REQ-PROJECT-BOUNDARY**: Validate files are within project boundaries
-- **REQ-CONFIGURABLE-PATHS**: Support configurable story file directories and search patterns
-
-## Dependencies
-
-List other stories this story depends on, using numbered story references:
-
-- 001.0-DEV-PLUGIN-SETUP (requires plugin structure foundation)
-- 002.0-DEV-ESLINT-CONFIG (requires configuration system)
-- 003.0-DEV-FUNCTION-ANNOTATIONS (uses annotations detected by function validation)
-- 004.0-DEV-BRANCH-ANNOTATIONS (uses annotations detected by branch validation)
-- 005.0-DEV-ANNOTATION-VALIDATION (requires properly formatted annotations)
-
-**Dependency Rules**:
-
-- Story numbers MUST be greater than all dependency story numbers
-- Dependencies should be from in-scope stories when possible
-- Cross-release dependencies should be clearly justified
-- No circular dependencies allowed
-
-## Implementation Notes (Optional)
-
-Additional context for developers:
-
-- Use Node.js fs/promises for async file system operations
-- Implement path resolution relative to project root (where package.json/eslint.config.js exists)
-- Support configurable story directories (e.g., docs/stories/, stories/, etc.)
-- Cache file existence checks during single linting run for performance
-- Implement security checks to prevent path traversal (../) outside project
-- Handle various file system scenarios (case sensitivity, symbolic links, network drives)
-- Provide helpful error messages with suggestions for fixing path issues
-
-**Path Resolution Examples:**
-
-Valid story file references:
-
-```javascript
-// @story docs/stories/001.0-DEV-EXAMPLE.story.md
-// @story stories/feature.story.md
-// @story ./local-story.story.md
-```
-
-Invalid references that should trigger validation errors:
-
-```javascript
-// @story ../outside-project.story.md  (path traversal)
-// @story docs/stories/missing.story.md  (file doesn't exist)
-// @story docs/stories/wrong-extension.md  (wrong extension)
-// @story /absolute/path.story.md  (absolute path not allowed)
-```
-
-**Configuration Integration:**
-
-```javascript
-// eslint.config.js
-export default [
-  {
-    plugins: { traceability },
-    rules: {
-      "traceability/valid-story-reference": [
-        "error",
-        {
-          storyDirectories: ["docs/stories", "stories"],
-          allowAbsolutePaths: false,
-          requireStoryExtension: true,
-        },
-      ],
-    },
-  },
-];
-```
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (file system scenarios, path resolution, security)
-- [ ] Documentation updated (file validation rules and configuration options)
-- [ ] Performance tested with large numbers of story files
-- [ ] Security reviewed for path traversal and access control
-- [ ] Ready for error reporting enhancement (007.0-DEV-ERROR-REPORTING)
-
----

package/docs/stories/007.0-DEV-ERROR-REPORTING.story.md

@@ -1,89 +0,0 @@
-# 007.0-DEV-ERROR-REPORTING: Clear Error Messages for Annotation Violations
-
-## Release Goal
-
-**Release 0.1: Core Validation** - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches, with validation that referenced files exist and contain the referenced requirements.
-
-This story ensures developers receive clear, actionable feedback when traceability violations are detected, enabling quick resolution of annotation issues and supporting the overall goal of reliable traceability enforcement.
-
-## How This Story Contributes
-
-Clear error messages are critical for developer adoption and productivity. When annotation validation fails, developers need to understand exactly what's wrong and how to fix it. This story transforms technical validation failures into helpful guidance, reducing friction in maintaining traceability annotations and ensuring developers can quickly resolve issues without extensive debugging.
-
-This story enables successful completion of the "Fix Issues" journey phase by providing the foundation for all error communication in the plugin.
-
-## User Story
-
-**Format**: So that I can quickly understand and fix traceability violations without wasting time debugging, as a Developer, I want the ESLint plugin to provide clear, specific error messages that explain what's wrong and suggest how to fix annotation issues.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed using the validation logic from previous stories without blocking dependencies
-- **Negotiable**: Error message formats and content can be refined based on developer feedback during implementation
-- **Valuable**: Delivers clear value by reducing time spent debugging annotation issues
-- **Estimable**: Scope is well-defined - enhance existing validation rules with improved messaging
-- **Small**: Focused on message enhancement rather than new validation logic
-- **Testable**: Error messages can be verified through unit tests and developer feedback
-
-## Acceptance Criteria
-
-- [ ] **Core Functionality**: All validation rules provide specific, actionable error messages instead of generic failures
-- [ ] **Quality Standards**: Error messages follow ESLint best practices for clarity and consistency
-- [ ] **Integration**: Error messages work properly with existing validation rules and ESLint reporting
-- [ ] **User Experience**: Messages clearly identify the problem, location, and suggested fix
-- [ ] **Error Handling**: Gracefully handles edge cases where error context is incomplete
-- [ ] **Documentation**: Error message formats are documented for consistency across rules
-
-## Requirements (Current Implementation or To Be Implemented)
-
-- **REQ-ERROR-SPECIFIC**: Each validation failure provides specific details about what annotation is missing or invalid
-- **REQ-ERROR-LOCATION**: Error messages include precise location information (function name, line number, file path)
-- **REQ-ERROR-SUGGESTION**: Messages suggest concrete steps to fix the issue (e.g., "Add @story annotation" or "Fix file path")
-- **REQ-ERROR-CONTEXT**: Error messages include relevant context (expected annotation format, available story files)
-- **REQ-ERROR-CONSISTENCY**: All plugin rules use consistent error message format and terminology
-- **REQ-ERROR-SEVERITY**: Error severity levels are appropriate (error for missing annotations, warning for format issues)
-
-## Dependencies
-
-- 003.0-DEV-FUNCTION-ANNOTATIONS (error reporting needs function annotation validation logic)
-- 004.0-DEV-BRANCH-ANNOTATIONS (error reporting needs branch annotation validation logic)
-- 005.0-DEV-ANNOTATION-VALIDATION (error reporting needs annotation format validation results)
-- 006.0-DEV-FILE-VALIDATION (error reporting needs file validation results)
-
-**Dependency Rules**:
-
-- Story numbers MUST be greater than all dependency story numbers
-- Dependencies should be from in-scope stories when possible
-- Cross-release dependencies should be clearly justified
-- No circular dependencies allowed
-
-## Implementation Notes (Optional)
-
-**Technical Considerations**:
-
-- Use ESLint's context.report() method for consistent error reporting
-- Implement error message templates for common validation failures
-- Consider internationalization support for error messages
-- Include suggestions using ESLint's suggest API where appropriate
-
-**Integration Points**:
-
-- Enhance existing validation rules from stories 003.0-006.0
-- Integrate with ESLint's built-in error reporting and formatting
-- Ensure compatibility with different ESLint output formats (stylish, json, etc.)
-
-**Testing Strategy**:
-
-- Unit tests for each error message scenario
-- Integration tests with various code patterns
-- Manual testing with developers for message clarity
-- Verify error messages work in different IDEs and editors
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing
-- [ ] Documentation updated
-- [ ] Deployed to appropriate environment
-- [ ] Stakeholder acceptance confirmed

package/docs/stories/008.0-DEV-AUTO-FIX.story.md

@@ -1,104 +0,0 @@
-# 008.0-DEV-AUTO-FIX: Simple Auto-Fixes for Annotation Issues
-
-## Release Goal
-
-**Release 0.1: Core Validation** - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches, with validation that referenced files exist and contain the referenced requirements.
-
-This story enables developers to automatically fix common annotation issues through ESLint's auto-fix functionality, reducing manual effort and accelerating the adoption of traceability practices by making compliance as frictionless as possible.
-
-## How This Story Contributes
-
-Auto-fix capabilities transform the "Fix Issues" experience from manual correction to automated resolution for common problems. This dramatically reduces the friction of maintaining traceability annotations, especially when introducing the plugin to existing codebases with many annotation violations. By providing safe, automated fixes, this story enables teams to quickly achieve compliance and focus on higher-value activities.
-
-This story completes the core "Fix Issues" journey phase by providing both clear error messages (007.0) and automated resolution capabilities.
-
-## User Story
-
-**Format**: So that I can quickly resolve common annotation issues without manual editing, as a Developer, I want the ESLint plugin to automatically fix standard annotation violations when I run ESLint with the --fix option.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed using existing validation logic and error reporting from previous stories
-- **Negotiable**: The set of auto-fixable issues and fix strategies can be refined during implementation
-- **Valuable**: Delivers clear value by reducing manual work and speeding up compliance
-- **Estimable**: Scope is well-defined - implement ESLint auto-fix for specific validation rules
-- **Small**: Focused on a subset of fixable issues rather than all possible violations
-- **Testable**: Auto-fixes can be verified through before/after code comparisons
-
-## Acceptance Criteria
-
-- [ ] **Core Functionality**: ESLint --fix automatically resolves common annotation violations
-- [ ] **Quality Standards**: Auto-fixes are safe and preserve code functionality and formatting
-- [ ] **Integration**: Auto-fix works properly with existing validation rules and ESLint toolchain
-- [ ] **User Experience**: Fixes are applied consistently and predictably across different code patterns
-- [ ] **Error Handling**: Gracefully handles edge cases where auto-fix cannot be applied safely
-- [ ] **Documentation**: Auto-fix capabilities are documented with examples of fixable issues
-
-## Requirements (Current Implementation or To Be Implemented)
-
-- **REQ-AUTOFIX-MISSING**: Automatically add missing @story annotations to functions using template format
-- **REQ-AUTOFIX-FORMAT**: Fix common annotation format issues (spacing, syntax, casing)
-- **REQ-AUTOFIX-SAFE**: Only apply fixes that are guaranteed to be safe and non-destructive
-- **REQ-AUTOFIX-PRESERVE**: Preserve existing code formatting, indentation, and comment structure
-- **REQ-AUTOFIX-TEMPLATE**: Use configurable annotation templates for consistent formatting
-- **REQ-AUTOFIX-SELECTIVE**: Allow developers to choose which types of fixes to enable/disable
-
-## Dependencies
-
-- 003.0-DEV-FUNCTION-ANNOTATIONS (auto-fix needs to understand function annotation requirements)
-- 004.0-DEV-BRANCH-ANNOTATIONS (auto-fix needs to understand branch annotation requirements)
-- 005.0-DEV-ANNOTATION-VALIDATION (auto-fix needs validation logic to identify fixable issues)
-- 007.0-DEV-ERROR-REPORTING (auto-fix should integrate with error reporting for unfixable issues)
-
-**Dependency Rules**:
-
-- Story numbers MUST be greater than all dependency story numbers
-- Dependencies should be from in-scope stories when possible
-- Cross-release dependencies should be clearly justified
-- No circular dependencies allowed
-
-## Implementation Notes (Optional)
-
-**Technical Considerations**:
-
-- Use ESLint's fix API to provide automated corrections
-- Implement fixer functions for each auto-fixable rule
-- Consider code formatting preservation using AST manipulation
-- Provide configuration options for auto-fix behavior
-
-**Integration Points**:
-
-- Enhance existing validation rules with fix capabilities
-- Integrate with ESLint's --fix command line option
-- Ensure compatibility with IDE auto-fix on save features
-- Work with existing code formatters (Prettier, etc.)
-
-**Safe Auto-Fix Scenarios**:
-
-- Adding missing @story annotations with placeholder content
-- Fixing annotation comment syntax (@story vs // @story)
-- Correcting annotation format spacing and structure
-- Standardizing annotation placement (before function vs inline)
-
-**Non-Auto-Fixable Scenarios** (require manual intervention):
-
-- Choosing appropriate story file references
-- Adding specific requirement annotations
-- Resolving file path issues that require developer knowledge
-- Complex formatting conflicts with existing code style
-
-**Testing Strategy**:
-
-- Unit tests for each auto-fix scenario with before/after comparisons
-- Integration tests with various code patterns and existing formatting
-- Edge case testing for complex code structures
-- Manual testing with real codebases to verify safety and effectiveness
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing
-- [ ] Documentation updated
-- [ ] Deployed to appropriate environment
-- [ ] Stakeholder acceptance confirmed

package/docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

@@ -1,104 +0,0 @@
-# 009.0-DEV-MAINTENANCE-TOOLS: Update Helpers for Annotation Maintenance
-
-## Release Goal
-
-**Release 0.1: Core Validation** - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches, with validation that referenced files exist and contain the referenced requirements.
-
-This story provides developers with helper tools and utilities to maintain traceability annotations as their codebase evolves, ensuring annotations remain accurate and up-to-date when story files are moved, renamed, or restructured.
-
-## How This Story Contributes
-
-As codebases grow and evolve, maintaining traceability annotations becomes an ongoing challenge. This story bridges the gap between initial compliance (achieved through validation and auto-fix) and long-term maintainability. By providing tools to update annotations when story files change, this story ensures that traceability systems remain valuable over time rather than becoming maintenance burdens.
-
-This story initiates the "Maintain Quality" journey phase by providing foundational tools for ongoing annotation maintenance.
-
-## User Story
-
-**Format**: So that I can keep annotations accurate when story files are moved or renamed without manually hunting through code, as a Developer, I want helper tools that can batch update annotation references and detect when annotations become stale.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed using existing validation logic and file system operations
-- **Negotiable**: The specific maintenance tools and their interfaces can be refined during implementation
-- **Valuable**: Delivers clear value by reducing manual maintenance work as projects evolve
-- **Estimable**: Scope is well-defined - implement specific maintenance utilities
-- **Small**: Focused on core maintenance scenarios rather than comprehensive project management
-- **Testable**: Maintenance operations can be verified through before/after file comparisons
-
-## Acceptance Criteria
-
-- [ ] **Core Functionality**: Tools can detect and update annotation references when story files are moved or renamed
-- [ ] **Quality Standards**: Maintenance operations preserve code functionality and formatting
-- [ ] **Integration**: Tools work with existing project structure and ESLint configuration
-- [ ] **User Experience**: Maintenance operations provide clear feedback about what was changed
-- [ ] **Error Handling**: Gracefully handles edge cases like circular references or missing files
-- [ ] **Documentation**: Maintenance tools are documented with usage examples and best practices
-
-## Requirements (Current Implementation or To Be Implemented)
-
-- **REQ-MAINT-DETECT**: Detect stale annotation references that point to moved or deleted story files
-- **REQ-MAINT-UPDATE**: Update annotation references when story files are moved or renamed
-- **REQ-MAINT-BATCH**: Perform batch updates across multiple files and annotations
-- **REQ-MAINT-VERIFY**: Verify annotation references are still valid after maintenance operations
-- **REQ-MAINT-REPORT**: Generate reports showing what annotations were updated and why
-- **REQ-MAINT-SAFE**: Ensure maintenance operations are reversible and don't break existing functionality
-
-## Dependencies
-
-- 005.0-DEV-ANNOTATION-VALIDATION (maintenance tools need to understand annotation format)
-- 006.0-DEV-FILE-VALIDATION (maintenance tools need file existence validation logic)
-- 007.0-DEV-ERROR-REPORTING (maintenance tools should use consistent error reporting)
-
-**Dependency Rules**:
-
-- Story numbers MUST be greater than all dependency story numbers
-- Dependencies should be from in-scope stories when possible
-- Cross-release dependencies should be clearly justified
-- No circular dependencies allowed
-
-## Implementation Notes (Optional)
-
-**Technical Considerations**:
-
-- Implement CLI tools for common maintenance operations
-- Use file system watching to detect when story files are moved or renamed
-- Provide programmatic APIs for integration with project tooling
-- Consider integration with Git hooks for automatic maintenance
-
-**Integration Points**:
-
-- Work with existing ESLint plugin infrastructure
-- Integrate with project build and development workflows
-- Provide hooks for custom maintenance automation
-- Support various project structures and story file organization
-
-**Common Maintenance Scenarios**:
-
-- Story files moved to new directories (reorganization)
-- Story files renamed for consistency or clarity
-- Story files deleted (need to flag dependent annotations)
-- Bulk updates when story numbering scheme changes
-- Project restructuring that affects story file paths
-
-**Maintenance Tool Types**:
-
-- **Detection Tools**: Scan codebase for stale or invalid annotation references
-- **Update Tools**: Batch update annotations to reflect file system changes
-- **Verification Tools**: Validate that all annotations still point to valid story files
-- **Migration Tools**: Help migrate from old annotation formats to new ones
-
-**Testing Strategy**:
-
-- Unit tests for each maintenance operation with various file scenarios
-- Integration tests with real project structures and story file layouts
-- Performance tests for large codebases with many annotations
-- Manual testing with common maintenance workflows
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing
-- [ ] Documentation updated
-- [ ] Deployed to appropriate environment
-- [ ] Stakeholder acceptance confirmed

package/docs/stories/010.0-DEV-DEEP-VALIDATION.story.md

@@ -1,110 +0,0 @@
-# 010.0-DEV-DEEP-VALIDATION: Requirement Content Validation
-
-## Release Goal
-
-**Release 0.1: Core Validation** - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches, with validation that referenced files exist and contain the referenced requirements.
-
-This story completes the validation framework by ensuring that @req annotations not only point to existing story files, but that the referenced requirements actually exist within those files. This provides complete end-to-end traceability validation from code annotations to actual requirement content.
-
-## How This Story Contributes
-
-While basic file validation (006.0) ensures story files exist, deep validation goes further to verify that the specific requirements referenced in @req annotations are actually present in the story files. This prevents broken traceability links where annotations point to valid files but non-existent requirements, ensuring the traceability system maintains integrity as requirements evolve.
-
-This story completes the "Maintain Quality" journey phase and Release 0.1 by providing the most comprehensive validation possible, ensuring annotations remain meaningful and accurate.
-
-## User Story
-
-**Format**: So that I can trust that @req annotations point to actual requirements and not just valid files, as a Developer, I want the ESLint plugin to validate that referenced requirements exist within the target story files.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed using existing file validation and annotation parsing logic
-- **Negotiable**: The specific requirement matching strategies and formats can be refined during implementation
-- **Valuable**: Delivers clear value by ensuring annotation accuracy and preventing broken traceability
-- **Estimable**: Scope is well-defined - parse story files to validate requirement existence
-- **Small**: Focused on requirement content validation rather than broader file analysis
-- **Testable**: Requirement validation can be verified through story file parsing and matching tests
-
-## Acceptance Criteria
-
-- [ ] **Core Functionality**: Plugin validates that @req annotations reference requirements that actually exist in the target story files
-- [ ] **Quality Standards**: Validation handles various requirement formats and story file structures
-- [ ] **Integration**: Works with existing file validation and annotation parsing logic
-- [ ] **User Experience**: Provides clear error messages when requirements are not found in story files
-- [ ] **Error Handling**: Gracefully handles malformed story files, missing sections, or parsing errors
-- [ ] **Documentation**: Requirement validation behavior is documented with examples of supported formats
-
-## Requirements (Current Implementation or To Be Implemented)
-
-- **REQ-DEEP-PARSE**: Parse story file content to identify available requirements
-- **REQ-DEEP-MATCH**: Match @req annotation references against actual requirements in story files
-- **REQ-DEEP-FORMAT**: Support multiple requirement formats (REQ-XXX-YYY, bullet points, numbered lists)
-- **REQ-DEEP-SECTION**: Handle requirements in different story file sections (Requirements, Acceptance Criteria, etc.)
-- **REQ-DEEP-CACHE**: Cache parsed story file content to avoid re-parsing on every validation
-- **REQ-DEEP-ERROR**: Provide specific error messages when requirements are not found in story files
-
-## Dependencies
-
-- 005.0-DEV-ANNOTATION-VALIDATION (deep validation needs annotation format parsing)
-- 006.0-DEV-FILE-VALIDATION (deep validation builds on file existence validation)
-- 007.0-DEV-ERROR-REPORTING (deep validation needs clear error reporting for requirement mismatches)
-
-**Dependency Rules**:
-
-- Story numbers MUST be greater than all dependency story numbers
-- Dependencies should be from in-scope stories when possible
-- Cross-release dependencies should be clearly justified
-- No circular dependencies allowed
-
-## Implementation Notes (Optional)
-
-**Technical Considerations**:
-
-- Implement robust markdown parsing to extract requirements from story files
-- Support multiple requirement identification patterns (REQ-XXX-YYY, numbered bullets, etc.)
-- Consider performance implications of parsing story files during linting
-- Provide caching mechanisms to avoid repeated file parsing
-
-**Integration Points**:
-
-- Extend existing file validation logic to include content parsing
-- Integrate with annotation parsing to extract requirement references
-- Work with error reporting system to provide detailed mismatch information
-- Support various story file formats and structures
-
-**Requirement Identification Strategies**:
-
-- **Explicit Requirements**: Lines starting with "REQ-" or "\*\*REQ-"
-- **Acceptance Criteria**: Checkbox items in acceptance criteria sections
-- **Numbered Requirements**: Numbered list items in requirements sections
-- **Custom Patterns**: Configurable regex patterns for project-specific formats
-
-**Content Parsing Approach**:
-
-- Parse markdown structure to identify sections
-- Extract requirement identifiers using multiple strategies
-- Build searchable index of requirements per story file
-- Cache parsing results with file modification time tracking
-
-**Performance Considerations**:
-
-- Parse story files only when @req annotations reference them
-- Cache parsed content with file modification timestamps
-- Use incremental parsing for large story files
-- Provide configuration options to disable deep validation for performance
-
-**Testing Strategy**:
-
-- Unit tests for markdown parsing with various story file formats
-- Integration tests with real story files and annotation patterns
-- Performance tests with large story files and many annotations
-- Edge case testing with malformed markdown and unusual requirement formats
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing
-- [ ] Documentation updated
-- [ ] Deployed to appropriate environment
-- [ ] Stakeholder acceptance confirmed

package/docs/stories/developer-story.map.md

@@ -1,118 +0,0 @@
-# Developer User Story Map - ESLint Plugin Traceability
-
-## Journey Steps (Columns)
-
-| **Setup Plugin**                                                                           | **Write Code**                                                              | **Validate Annotations**                                    | **Fix Issues**                                            | **Maintain Quality**                          |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------- |
-| _Install and configure the ESLint plugin in their project to start enforcing traceability_ | _Write functions and code branches with proper @story and @req annotations_ | _Run linting to check that annotations exist and are valid_ | _Address any traceability violations found by the linter_ | _Keep annotations up-to-date as code evolves_ |
-| **Installation**                                                                           | **Function Annotations**                                                    | **Annotation Validation**                                   | **Error Resolution**                                      | **Ongoing Maintenance**                       |
-| **Configuration**                                                                          | **Branch Annotations**                                                      | **File Reference Validation**                               | **Quick Fixes**                                           | **Ongoing Maintenance**                       |
-
-## Personas
-
-- 🎯 **PRIMARY**: Developer - _A software developer who needs to maintain bidirectional traceability between code and requirements to ensure code quality and enable requirement validation through test execution_
-- 👥 **Team Lead** - _A technical lead who needs to ensure team compliance with traceability standards across the codebase_
-- 🔧 **QA Engineer** - _A quality assurance engineer who needs to validate that requirements are properly implemented and traceable through code_
-
----
-
-# User Story Map with Releases
-
-| **Release 0.1 (Core Validation)** (Planned) | **Setup Plugin**        | **Write Code**                 | **Validate Annotations**        | **Fix Issues**            | **Maintain Quality**        |
-| ------------------------------------------- | ----------------------- | ------------------------------ | ------------------------------- | ------------------------- | --------------------------- |
-| **Plugin Foundation**                       | 001.0-DEV-PLUGIN-SETUP  | 003.0-DEV-FUNCTION-ANNOTATIONS | 005.0-DEV-ANNOTATION-VALIDATION | 007.0-DEV-ERROR-REPORTING | 009.0-DEV-MAINTENANCE-TOOLS |
-| **Basic Rules**                             | 002.0-DEV-ESLINT-CONFIG | 004.0-DEV-BRANCH-ANNOTATIONS   | 006.0-DEV-FILE-VALIDATION       | 008.0-DEV-AUTO-FIX        | 010.0-DEV-DEEP-VALIDATION   |
-|                                             | -                       | -                              | -                               | -                         | -                           |
-
-| **Release 0.2 (Enhanced Features)** (Future) | **Setup Plugin**            | **Write Code**               | **Validate Annotations**     | **Fix Issues**              | **Maintain Quality**      |
-| -------------------------------------------- | --------------------------- | ---------------------------- | ---------------------------- | --------------------------- | ------------------------- |
-| **Advanced Validation**                      | 011.0-DEV-IDE-INTEGRATION   | 013.0-DEV-SMART-SUGGESTIONS  | 015.0-DEV-REAL-TIME-FEEDBACK | 016.0-DEV-BULK-FIXES        | 018.0-DEV-QUALITY-METRICS |
-| **Developer Experience**                     | 012.0-DEV-PROJECT-TEMPLATES | 014.0-DEV-ANNOTATION-HELPERS | -                            | 017.0-DEV-GUIDED-RESOLUTION | 019.0-DEV-DASHBOARD       |
-|                                              | -                           | -                            | -                            | -                           | -                         |
-
----
-
-## Release Details
-
-### Release 0.1: Core Validation (Planned)
-
-**Goal**: Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches, with validation that referenced files exist and contain the referenced requirements.
-**Success Metric**: Developers can run ESLint and receive clear feedback when traceability annotations are missing, incorrect, or point to non-existent files/requirements.
-**Scope**: Basic plugin setup, core validation rules, error reporting, and simple auto-fix capabilities for common issues.
-
-**Stories by Category:**
-
-- **Plugin Foundation**: 001.0-DEV-PLUGIN-SETUP (ESLint plugin structure), 002.0-DEV-ESLINT-CONFIG (configuration setup)
-- **Core Annotations**: 003.0-DEV-FUNCTION-ANNOTATIONS (validate @story/@req on functions), 004.0-DEV-BRANCH-ANNOTATIONS (validate annotations on branches)
-- **Validation Logic**: 005.0-DEV-ANNOTATION-VALIDATION (check annotation format), 006.0-DEV-FILE-VALIDATION (verify story files exist)
-- **Developer Support**: 007.0-DEV-ERROR-REPORTING (clear error messages), 008.0-DEV-AUTO-FIX (simple auto-fixes)
-- **Ongoing Maintenance**: 009.0-DEV-MAINTENANCE-TOOLS (update helpers)
-- **Deep Validation**: 010.0-DEV-DEEP-VALIDATION (requirement content validation)
-
-**Total**: 10 stories covering complete basic traceability enforcement workflow
-
-### Release 0.2: Enhanced Features (Future)
-
-**Goal**: Enhance developer experience with IDE integration, intelligent suggestions, advanced validation, and quality metrics to make traceability maintenance effortless and valuable.
-**Success Metric**: Developers proactively maintain traceability annotations with minimal friction, and teams can track and improve their traceability coverage over time.
-**Scope**: IDE extensions, smart auto-completion, deep requirement validation, bulk fixing tools, and traceability quality dashboards.
-
-**Stories by Category:**
-
-- **Developer Integration**: 011.0-DEV-IDE-INTEGRATION (VS Code extension), 012.0-DEV-PROJECT-TEMPLATES (starter templates)
-- **Smart Features**: 013.0-DEV-SMART-SUGGESTIONS (intelligent annotation suggestions), 014.0-DEV-ANNOTATION-HELPERS (auto-completion)
-- **Advanced Validation**: 015.0-DEV-REAL-TIME-FEEDBACK (live validation)
-- **Productivity Tools**: 016.0-DEV-BULK-FIXES (mass update tools), 017.0-DEV-GUIDED-RESOLUTION (fix wizards)
-- **Quality Management**: 018.0-DEV-QUALITY-METRICS (coverage tracking), 019.0-DEV-DASHBOARD (team dashboard)
-
-**Total**: 9 stories covering advanced developer experience and team quality management
-
----
-
-## Key Questions for Developer
-
-### **Release 0.1 Questions:**
-
-**Plugin Foundation:**
-
-- How easy is it to add the ESLint plugin to an existing project without disrupting current workflow?
-- What configuration options are needed to accommodate different project structures and story file locations?
-- How should the plugin handle different story file naming conventions (.story.md vs other formats)?
-
-**Core Annotations:**
-
-- What types of functions should require @story annotations (all functions, only exported functions, only functions above certain complexity)?
-- Which code branches need traceability annotations (if/else, try/catch, switch cases, loops)?
-- How should the plugin handle generated code or third-party code that can't have annotations?
-
-**Validation Logic:**
-
-- How strict should annotation format validation be (exact format vs flexible parsing)?
-- Should the plugin validate that @req annotations point to actual requirements within the referenced story file?
-- How should the plugin handle story files that exist but are empty or malformed?
-
-**Developer Support:**
-
-- What information should be included in error messages to help developers fix annotation issues quickly?
-- Which annotation errors can be auto-fixed safely (missing @story template, broken file paths)?
-- How should the plugin integrate with existing ESLint configurations and other rules?
-
-### **Release 0.2 Questions:**
-
-**Developer Integration:**
-
-- What IDE features would make maintaining traceability annotations feel natural and effortless?
-- How can the plugin provide intelligent suggestions for @story references based on file context?
-- What project templates would help new teams adopt traceability practices from the start?
-
-**Advanced Validation:**
-
-- Should the plugin parse story files to validate that referenced requirements actually exist in the content?
-- How can the plugin detect when story files are updated but code annotations become stale?
-- What real-time feedback mechanisms would help developers maintain traceability as they code?
-
-**Quality Management:**
-
-- What metrics help teams understand and improve their traceability coverage?
-- How can teams track traceability quality trends over time?
-- What visualization tools would help identify areas of the codebase with poor traceability?