eslint-plugin-traceability 1.1.0 → 1.1.2

package/docs/rules/valid-annotation-format.md

@@ -1,52 +0,0 @@
-# valid-annotation-format
-
-Validates that `@story` and `@req` annotations follow the correct format and syntax rules to ensure traceability annotations are parseable and standardized.
-
-@story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-@req REQ-FORMAT-SPECIFICATION - Define clear format rules for @story and @req annotations
-@req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
-@req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
-@req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
-
-## Rule Details
-
-This rule scans all comments in the source code and checks each line that begins with `@story` or `@req`. It applies regular expressions to verify:
-
-- `@story` paths match the pattern `docs/stories/NN.N-DEV-<NAME>.story.md`
-- `@req` identifiers match the pattern `REQ-<UPPERCASE|NUMERIC|DASH>`
-
-Violations report specific messages for invalid story formats or invalid requirement ID formats.
-
-## Examples
-
-#### Correct
-
-```js
-/**
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @req REQ-FORMAT-SPECIFICATION
- */
-function example() {}
-
-// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-// @req REQ-SYNTAX-VALIDATION
-if (condition) {
-  /* ... */
-}
-```
-
-#### Incorrect
-
-```js
-// @story invalid-path
-// @req REQ-1234
-
-// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story
-// @req invalid-req-id
-
-/**
- * @story
- * @req REQ-EXAMPLE
- */
-function badExample() {}
-```

package/docs/rules/valid-req-reference.md

@@ -1,58 +0,0 @@
-# valid-req-reference
-
-Enforces that `@req` annotations reference existing requirements in story files and protects against invalid paths.
-
-@story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-@req REQ-DEEP-PARSE - Parse story files to extract requirement identifiers
-@req REQ-DEEP-MATCH - Validate `@req` references against story file content
-@req REQ-DEEP-PATH - Protect against path traversal in story paths
-
-## Rule Details
-
-This rule performs deep validation of `@req` annotations by:
-
-- Verifying the referenced story file exists and is within the project directory
-- Parsing the story file to extract requirement IDs (e.g., `REQ-XXX-YYY`)
-- Ensuring each `@req` annotation matches an extracted requirement ID
-- Reporting an `invalidPath` error for paths containing `..` or absolute paths
-- Reporting a `reqMissing` error when the requirement ID is not found in the story file
-
-### Options
-
-This rule does not accept any options (schema is `[]`).
-
-## Examples
-
-### Correct
-
-```js
-// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
-// @req REQ-PLUGIN-STRUCTURE
-function initPlugin() {}
-```
-
-### Incorrect: Missing Requirement
-
-```js
-// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
-// @req REQ-NON-EXISTENT
-function initPlugin() {}
-```
-
-### Incorrect: Path Traversal
-
-```js
-// @story ../docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
-// @req REQ-PLUGIN-STRUCTURE
-function initPlugin() {}
-```
-
-### Incorrect: Absolute Path
-
-```js
-// @story /absolute/path/docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
-// @req REQ-PLUGIN-STRUCTURE
-function initPlugin() {}
-```
-
-For more details, see the story: docs/stories/010.0-DEV-DEEP-VALIDATION.story.md

package/docs/rules/valid-story-reference.md

@@ -1,47 +0,0 @@
-# valid-story-reference
-
-Validates that `@story` annotation references refer to existing `.story.md` files within the project and prevents invalid path usage.
-
-@story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
-@req REQ-FILE-EXISTENCE - Verify that `@story` file paths reference existing files
-@req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
-@req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
-
-## Rule Details
-
-This rule inspects all comment nodes for lines starting with `@story`. It then:
-
-- Prevents absolute paths unless explicitly allowed
-- Prevents path traversal outside the project directory
-- Ensures `.story.md` extension when required
-- Resolves candidate file locations in configured story directories
-- Reports a `fileMissing`, `invalidExtension`, or `invalidPath` error for violations
-
-### Options
-
-Configure rule behavior using an options object:
-
-```json
-{
-  "storyDirectories": ["docs/stories", "stories"],
-  "allowAbsolutePaths": false,
-  "requireStoryExtension": true
-}
-```
-
-### Examples
-
-#### Correct
-
-```js
-// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
-```
-
-#### Incorrect
-
-```js
-// @story docs/stories/nonexistent.story.md        // @story fileMissing
-// @story docs/stories/001.0-DEV-PLUGIN-SETUP.md   // @story invalidExtension
-// @story ../outside.story.md                      // @story invalidPath
-// @story /etc/passwd.story.md                     // @story invalidPath
-```

package/docs/security-incidents/unresolved-vulnerabilities.md

@@ -1,11 +0,0 @@
-# Unresolved Vulnerabilities
-
-As of 2025-11-16, all moderate and higher severity vulnerabilities have been resolved in the project’s dependencies.
-
-## Resolution Details
-
-- **js-yaml (GHSA-mh29-5h37-fv8m)**: Prototype pollution vulnerability resolved by upgrading to `js-yaml` >= 4.1.1 via `npm audit fix` and package.json override.
-
-## Outstanding Issues
-
-_None._

package/docs/stories/001.0-DEV-PLUGIN-SETUP.story.md

@@ -1,82 +0,0 @@
-# 001.0-DEV-PLUGIN-SETUP: ESLint Plugin Structure Foundation
-
-## Release Goal
-
-_Release 0.1: Core Validation - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches_
-
-This story establishes the foundational structure for the ESLint plugin that will enforce code traceability annotations. It creates the basic plugin architecture that enables all subsequent validation rules and features in Release 0.1.
-
-## How This Story Contributes
-
-This story is critical as the foundation for the entire traceability enforcement system. Without a properly structured ESLint plugin, no validation rules can be implemented. It enables all other stories in Release 0.1 by providing the plugin architecture, rule registration system, and basic infrastructure that subsequent stories will build upon.
-
-## User Story
-
-**Format**: So that I can enforce code traceability standards across my project, as a Developer, I want an ESLint plugin structure that can validate @story and @req annotations on functions and code branches.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed independently - no dependencies on other stories
-- **Negotiable**: Plugin structure details can be refined during implementation
-- **Valuable**: Delivers the foundation needed for all traceability enforcement
-- **Estimable**: Scope is clear - standard ESLint plugin structure
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Plugin can be tested for proper registration and basic functionality
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [ ] **Core Functionality**: ESLint plugin properly registers and loads without errors
-- [ ] **Quality Standards**: Follows ESLint plugin development best practices and conventions
-- [ ] **Integration**: Works properly with ESLint v9 flat config
-- [ ] **User Experience**: Plugin can be installed and configured with clear setup instructions
-- [ ] **Error Handling**: Gracefully handles plugin loading errors and missing dependencies
-- [ ] **Documentation**: Plugin structure and development setup is properly documented
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-PLUGIN-STRUCTURE**: ESLint plugin follows standard Node.js module structure
-- **REQ-ESLINT-COMPAT**: Compatible with ESLint v9 flat configuration
-- **REQ-RULE-REGISTRY**: Provides mechanism to register multiple validation rules
-- **REQ-CONFIG-SYSTEM**: Supports plugin configuration options for customization
-- **REQ-NPM-PACKAGE**: Properly structured as publishable npm package
-- **REQ-TYPESCRIPT**: Written in TypeScript for type safety and developer experience
-- **REQ-TEST-SETUP**: Includes testing infrastructure for rule validation
-
-## Dependencies
-
-List other stories this story depends on, using numbered story references:
-
-- None (This is the foundational story)
-
-**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 official ESLint plugin template and conventions
-- Structure should support both CommonJS and ESM module systems
-- Consider using @typescript-eslint/utils for TypeScript AST parsing utilities
-- Plugin should be scoped (e.g., @eslint-plugin-traceability or similar)
-- Include proper package.json configuration for ESLint plugin discovery
-- Set up development environment with hot reloading for rule testing
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (plugin loads, registers rules)
-- [ ] Documentation updated (README with setup instructions)
-- [ ] Plugin can be installed locally and configured in test project
-- [ ] Ready for subsequent rule implementation stories
-
----

package/docs/stories/002.0-DEV-ESLINT-CONFIG.story.md

@@ -1,82 +0,0 @@
-# 002.0-DEV-ESLINT-CONFIG: ESLint Configuration Setup
-
-## Release Goal
-
-_Release 0.1: Core Validation - Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches_
-
-This story enables developers to easily configure the ESLint plugin in their projects with sensible defaults and customizable options. It builds upon the plugin foundation (001.0) to provide user-friendly configuration that integrates seamlessly with existing ESLint setups.
-
-## How This Story Contributes
-
-This story is essential for plugin adoption as it determines how easy it is for developers to start using the traceability enforcement. It provides the configuration layer that enables all validation rules to be applied effectively, with options to customize behavior for different project structures and requirements.
-
-## User Story
-
-**Format**: So that I can quickly integrate traceability validation into my project workflow, as a Developer, I want clear and flexible ESLint configuration options that work with my existing ESLint setup and project structure.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after plugin structure (depends on 001.0-DEV-PLUGIN-SETUP)
-- **Negotiable**: Configuration options and defaults can be refined during implementation
-- **Valuable**: Enables easy adoption and customization of the plugin
-- **Estimable**: Scope is clear - configuration system and presets
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Configuration can be tested with various ESLint setups
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [ ] **Core Functionality**: Plugin provides recommended and strict configuration presets
-- [ ] **Quality Standards**: Configuration follows ESLint v9 flat config best practices
-- [ ] **Integration**: Works seamlessly with existing ESLint configurations without conflicts
-- [ ] **User Experience**: Clear documentation for setup with common project types
-- [ ] **Error Handling**: Graceful handling of invalid configuration options
-- [ ] **Documentation**: Comprehensive configuration examples and troubleshooting guide
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-CONFIG-PRESETS**: Provide recommended and strict configuration presets
-- **REQ-FLAT-CONFIG**: Support ESLint v9 flat configuration format
-- **REQ-CUSTOMIZABLE-PATHS**: Allow customization of story file patterns and locations
-- **REQ-RULE-OPTIONS**: Support configurable options for individual rules
-- **REQ-PROJECT-INTEGRATION**: Easy integration with TypeScript, JavaScript, and mixed projects
-- **REQ-CONFIG-VALIDATION**: Validate configuration options with helpful error messages
-
-## Dependencies
-
-List other stories this story depends on, using numbered story references:
-
-- 001.0-DEV-PLUGIN-SETUP (requires plugin structure foundation)
-
-**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:
-
-- Follow ESLint v9 flat config patterns from the development guide
-- Provide migration examples from eslintrc to flat config
-- Consider different project structures (monorepos, TypeScript projects, etc.)
-- Include configuration validation with JSON Schema
-- Support both scoped and unscoped package installations
-- Document integration with popular ESLint config presets (Airbnb, Standard, etc.)
-- Provide configuration generator or CLI helper for initial setup
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (configuration loading, validation, rule application)
-- [ ] Documentation updated (configuration guide, migration examples)
-- [ ] Configuration tested with sample projects (TS, JS, mixed)
-- [ ] Ready for rule implementation stories (003.0, 004.0, etc.)
-
----

package/docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

@@ -1,85 +0,0 @@
-# 003.0-DEV-FUNCTION-ANNOTATIONS: Function Annotation 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 the core ESLint rule that validates functions have proper @story and @req annotations. It provides the fundamental traceability enforcement that ensures all functions can be traced back to their originating requirements and stories.
-
-## How This Story Contributes
-
-This story delivers the primary value proposition of the plugin by implementing the core validation rule for function annotations. It enables the "Write Code" journey phase by ensuring developers receive immediate feedback when they create functions without proper traceability annotations, establishing the foundation for bidirectional traceability.
-
-## User Story
-
-**Format**: So that I can ensure all functions in my codebase are traceable to requirements, as a Developer, I want an ESLint rule that validates functions have @story and @req annotations in their JSDoc comments.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after plugin foundation and configuration (depends on 001.0, 002.0)
-- **Negotiable**: Rule strictness and annotation format can be refined during implementation
-- **Valuable**: Delivers core traceability enforcement for functions
-- **Estimable**: Scope is clear - single ESLint rule with defined behavior
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Rule can be thoroughly tested with ESLint's RuleTester
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [ ] **Core Functionality**: ESLint rule detects functions missing @story or @req annotations
-- [ ] **Quality Standards**: Rule follows ESLint rule development best practices
-- [ ] **Integration**: Rule works with TypeScript, JavaScript, and mixed codebases
-- [ ] **User Experience**: Clear, actionable error messages guide developers to fix issues
-- [ ] **Error Handling**: Gracefully handles malformed JSDoc comments and edge cases
-- [ ] **Documentation**: Rule documentation with examples and configuration options
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-FUNCTION-DETECTION**: Detect all function declarations, expressions, and arrow functions
-- **REQ-JSDOC-PARSING**: Parse JSDoc comments to extract @story and @req annotations
-- **REQ-ANNOTATION-REQUIRED**: Require both @story and @req annotations on functions
-- **REQ-CONFIGURABLE-SCOPE**: Allow configuration of which functions require annotations
-- **REQ-EXPORT-PRIORITY**: Prioritize checking exported functions over internal ones
-- **REQ-ERROR-LOCATION**: Report errors at function name for precise error location
-- **REQ-TYPESCRIPT-SUPPORT**: Support TypeScript-specific function syntax and decorators
-
-## 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)
-
-**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 @typescript-eslint/utils for AST parsing to handle TypeScript syntax
-- Leverage ESLint's JSDoc utilities for comment parsing
-- Support multiple function declaration patterns (function, const fn = (), class methods)
-- Consider performance impact of JSDoc parsing on large codebases
-- Implement configurable options for function scope (exported only, all functions, complexity threshold)
-- Handle edge cases: anonymous functions, IIFE, generator functions, async functions
-- Provide clear error messages that include function name and missing annotation type
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (comprehensive RuleTester coverage)
-- [ ] Documentation updated (rule documentation with examples)
-- [ ] Rule integrated into plugin configuration presets
-- [ ] Performance tested with large codebases
-- [ ] Ready for branch annotation rule (004.0-DEV-BRANCH-ANNOTATIONS)
-
----

package/docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

@@ -1,107 +0,0 @@
-# 004.0-DEV-BRANCH-ANNOTATIONS: Code Branch Annotation 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 ESLint rules that validate significant code branches (if/else blocks, try/catch blocks, switch cases, loops) have proper traceability annotations. It extends traceability enforcement beyond functions to ensure complex logic paths can be traced back to their requirements.
-
-## How This Story Contributes
-
-This story completes the core annotation enforcement by ensuring not just functions, but also significant logical branches within functions are traceable. It enables comprehensive requirement validation by ensuring that every code path can be traced to its originating story and requirement, supporting the system prompt's emphasis on branch-level traceability.
-
-## User Story
-
-**Format**: So that I can trace complex logic and conditional code paths back to requirements, as a Developer, I want an ESLint rule that validates significant code branches have @story and @req annotations in comments.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after function annotations (depends on 001.0, 002.0, 003.0 patterns)
-- **Negotiable**: Branch significance criteria and annotation requirements can be refined
-- **Valuable**: Delivers comprehensive traceability coverage beyond function-level
-- **Estimable**: Scope is clear - ESLint rule for branch annotation validation
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Rule can be tested with various code branch patterns using RuleTester
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [ ] **Core Functionality**: ESLint rule detects significant code branches missing @story or @req annotations
-- [ ] **Quality Standards**: Rule follows ESLint development best practices and performance guidelines
-- [ ] **Integration**: Rule works with complex nested code structures and various programming patterns
-- [ ] **User Experience**: Clear error messages indicate which branch needs annotation and why
-- [ ] **Error Handling**: Gracefully handles edge cases like nested branches and complex conditionals
-- [ ] **Documentation**: Rule documentation with examples of annotated branches and configuration
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-BRANCH-DETECTION**: Detect significant code branches (if/else, try/catch, switch, loops)
-- **REQ-COMMENT-ASSOCIATION**: Associate inline comments with their corresponding code branches
-- **REQ-ANNOTATION-PARSING**: Parse @story and @req annotations from branch comments
-- **REQ-SIGNIFICANCE-CRITERIA**: Define criteria for which branches require annotations
-- **REQ-NESTED-HANDLING**: Handle nested branches and complex control flow structures
-- **REQ-CONFIGURABLE-SCOPE**: Allow configuration of which branch types require annotations
-- **REQ-PERFORMANCE-OPTIMIZATION**: Efficient processing of large files with many branches
-
-## 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 patterns from function annotation validation)
-
-**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:
-
-- Leverage patterns established in 003.0-DEV-FUNCTION-ANNOTATIONS for consistency
-- Use AST visitor pattern to identify significant control flow nodes
-- Consider branch complexity/significance thresholds (configurable)
-- Handle inline comments vs. block comments for branch annotations
-- Support various comment styles (// and /\* \*/) for branch annotations
-- Implement smart detection of "significant" vs. trivial branches
-- Consider performance impact on large files with many conditional statements
-- Provide clear guidance on where to place branch annotations (before branch, inline, etc.)
-
-Example annotation patterns:
-
-```javascript
-// @story docs/stories/001.0-DEV-EXAMPLE.story.md
-// @req REQ-ERROR-HANDLING
-if (error) {
-  // error handling logic
-}
-
-try {
-  // @story docs/stories/001.0-DEV-EXAMPLE.story.md
-  // @req REQ-API-CALL
-  await apiCall();
-} catch (error) {
-  // @story docs/stories/001.0-DEV-EXAMPLE.story.md
-  // @req REQ-ERROR-RECOVERY
-  handleError(error);
-}
-```
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (comprehensive branch pattern coverage)
-- [ ] Documentation updated (branch annotation examples and best practices)
-- [ ] Rule integrated into plugin configuration presets
-- [ ] Performance tested with files containing many branches
-- [ ] Ready for annotation validation logic (005.0-DEV-ANNOTATION-VALIDATION)
-
----

package/docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md

@@ -1,119 +0,0 @@
-# 005.0-DEV-ANNOTATION-VALIDATION: Annotation Format 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 ensures @story and @req annotations follow proper format and syntax rules. It provides the foundation for validating annotation structure before checking file references and requirement existence, enabling clear error reporting for malformed annotations.
-
-## How This Story Contributes
-
-This story enables the "Validate Annotations" journey phase by ensuring annotation syntax is correct and parseable before attempting to validate file references. It provides immediate feedback on annotation format issues, improving developer experience by catching syntax errors early in the validation pipeline and enabling more sophisticated validation in later stories.
-
-## User Story
-
-**Format**: So that I can ensure my traceability annotations are properly formatted and parseable, as a Developer, I want validation that checks @story and @req annotation syntax and provides helpful error messages for format violations.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after annotation detection rules (depends on 001.0, 002.0, 003.0, 004.0)
-- **Negotiable**: Format strictness and validation rules can be refined during implementation
-- **Valuable**: Delivers clear feedback on annotation syntax before file validation
-- **Estimable**: Scope is clear - annotation format validation with defined syntax rules
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Format validation can be thoroughly tested with various annotation patterns
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [ ] **Core Functionality**: Validates @story and @req annotation format and syntax
-- [ ] **Quality Standards**: Follows ESLint development best practices for validation rules
-- [ ] **Integration**: Works with annotations found by function and branch validation rules
-- [ ] **User Experience**: Clear, specific error messages for different format violations
-- [ ] **Error Handling**: Gracefully handles edge cases and malformed comment structures
-- [ ] **Documentation**: Format specification with examples of valid and invalid annotations
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-FORMAT-SPECIFICATION**: Define clear format rules for @story and @req annotations
-- **REQ-SYNTAX-VALIDATION**: Validate annotation syntax matches specification
-- **REQ-PATH-FORMAT**: Validate @story paths follow expected patterns (relative paths, .story.md extension)
-- **REQ-REQ-FORMAT**: Validate @req identifiers follow expected patterns (REQ-\* format)
-- **REQ-MULTILINE-SUPPORT**: Handle annotations split across multiple lines
-- **REQ-FLEXIBLE-PARSING**: Support reasonable variations in whitespace and formatting
-- **REQ-ERROR-SPECIFICITY**: Provide specific error messages for different format violations
-
-## 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)
-
-**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:
-
-- Build shared validation utilities used by both function and branch annotation rules
-- Define annotation format specification as part of plugin configuration
-- Support configurable format strictness levels
-- Implement regex patterns for common annotation formats
-- Handle various JSDoc comment styles and formatting
-- Provide clear error messages with suggestions for fixing format issues
-- Consider allowing configuration of custom annotation formats
-
-**Annotation Format Examples:**
-
-Valid formats:
-
-```javascript
-/**
- * @story docs/stories/001.0-DEV-EXAMPLE.story.md
- * @req REQ-FUNCTION-VALIDATION
- */
-function example() {}
-
-// @story docs/stories/001.0-DEV-EXAMPLE.story.md
-// @req REQ-BRANCH-LOGIC
-if (condition) {
-}
-```
-
-Invalid formats requiring validation:
-
-```javascript
-// @story missing-extension
-// @req invalid-format
-
-// @story ../../../outside-project.story.md  (path traversal)
-// @req (missing identifier)
-
-/**
- * @story
- * @req REQ-EXAMPLE
- */  (missing story path)
-```
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (comprehensive format validation coverage)
-- [ ] Documentation updated (annotation format specification and examples)
-- [ ] Validation utilities integrated with existing annotation rules
-- [ ] Performance tested with various annotation patterns
-- [ ] Ready for file validation logic (006.0-DEV-FILE-VALIDATION)
-
----