eslint-plugin-traceability 1.7.0 → 1.8.0

package/docs/security-incidents/handling-procedure.md

@@ -0,0 +1,54 @@
+# Security Incident Handling Procedures
+
+This document outlines the standardized process for identifying, documenting, approving, and reviewing security incidents and manual dependency overrides within the project.
+
+## Scope
+
+This procedure applies to all security-related issues discovered in both production and development dependencies, with special focus on manual overrides configured in `package.json` under the `overrides` section.
+
+## Roles and Responsibilities
+
+- **Developer**: Identifies vulnerabilities, assesses impact, and proposes mitigations or overrides.
+- **Security Lead**: Reviews vulnerability assessments and approves residual risk decisions.
+- **Team Lead**: Ensures procedure compliance and schedules periodic reviews.
+
+## Procedure
+
+1. **Identification**  
+   - Discover vulnerabilities via automated tools (e.g., `npm audit`, `dry-aged-deps`) or external advisories.
+   - Log the finding in the issue tracker and reference the advisory (CVE or GHSA ID).
+
+2. **Initial Assessment**  
+   - Evaluate severity and exploitability in the project context.
+   - Determine if an automated patch or upgrade is available via `dry-aged-deps` or other tooling.
+   - If a safe version exists, prefer automated upgrades; do not use manual overrides.
+   - All changes merged into `main` are automatically scanned for secrets via the `npm run security:secrets` script in CI; any findings must be investigated and either remediated or explicitly documented as false positives in the issue tracker.
+
+3. **Decision to Override**  
+   - If no safe version is available (e.g., bundled dependency cannot be patched), propose a manual override in `package.json`.
+   - Document the rationale in `docs/security-incidents/dependency-override-rationale.md`.
+
+4. **Incident Report**  
+   - Create a security incident report by copying `docs/security-incidents/SECURITY-INCIDENT-TEMPLATE.md` and naming it `YYYY-MM-DD-<package>-<short-title>.md`.
+   - Populate the report with details (Date, Dependency, Vulnerability ID, Severity, Description, Remediation, Timeline, Impact Analysis, Testing).
+
+5. **Approval and Documentation**  
+   - Security Lead reviews and approves the incident report and override rationale.
+   - Include a link to the incident report in `dependency-override-rationale.md`.
+
+6. **Implementation**  
+   - Commit the manual override to `package.json` under `overrides`.
+   - Ensure the incident report and rationale documents are committed in the same PR.
+
+7. **Monitoring and Review**  
+   - Schedule a follow-up review within 7 days to re-assess availability of safe patches.
+   - Update or remove overrides and incident reports when safe upgrades become available.
+   - Document decision changes in the existing incident report with new timeline entries.
+
+8. **Escalation**  
+   - If a critical vulnerability remains unpatched beyond the tolerance period, escalate to the Security Lead and Team Lead for urgent action.
+
+## References
+
+- [Security Incident Template](SECURITY-INCIDENT-TEMPLATE.md)  
+- [Dependency Override Rationale](dependency-override-rationale.md)

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

@@ -0,0 +1,92 @@
+# 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
+- [x] **Error Handling**: Gracefully handles plugin loading errors and missing dependencies (covered by tests: tests/plugin-setup-error.test.ts, tests/cli-error-handling.test.ts)
+- [ ] **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
+- **REQ-ERROR-HANDLING**: Gracefully handles plugin loading errors and missing dependencies
+
+## 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:
+
+**Development Resources**:
+
+- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for comprehensive rule development patterns
+- 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
+
+**Key Guide Sections**:
+
+- [Rule Structure](../custom-rules-development-guide.md#rule-structure) - Basic rule anatomy and meta properties
+- [Testing Rules](../custom-rules-development-guide.md#testing-rules) - Using RuleTester for validation
+- [Best Practices](../custom-rules-development-guide.md#best-practices) - Performance and maintainability guidelines
+
+## 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

@@ -0,0 +1,82 @@
+# 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

@@ -0,0 +1,112 @@
+# 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 rules that validate 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 rules 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 ESLint rules that validate 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 - coordinated ESLint rules with defined behavior
+- **Small**: Can be completed within a single iteration/sprint
+- **Testable**: Rules can be thoroughly tested with ESLint's RuleTester
+
+## Acceptance Criteria
+
+Use checkbox format for clear completion tracking:
+
+- [x] **Core Functionality**: ESLint rules `require-story-annotation` and `require-req-annotation` both enforce their respective annotations on the same set of function-like constructs, ensuring @story and @req are applied consistently together
+- [x] **Quality Standards**: Rules follow ESLint rule development best practices
+- [x] **Integration**: Rules work with TypeScript, JavaScript, and mixed codebases
+- [x] **User Experience**: Clear, actionable error messages guide developers to fix issues
+- [x] **Error Handling**: Gracefully handles malformed JSDoc comments and edge cases
+- [x] **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 the following function-like constructs for annotation validation, shared by both rules:
+  - `FunctionDeclaration`
+  - `FunctionExpression`
+  - `MethodDefinition`
+  - `TSDeclareFunction`
+  - `TSMethodSignature`
+  - Arrow functions are excluded by default from traceability requirements
+- **REQ-JSDOC-PARSING**: Parse JSDoc comments to extract @story and @req annotations, using a common parsing strategy for both rules
+- **REQ-ANNOTATION-REQUIRED**:
+  - `require-story-annotation`: Require a @story annotation on all in-scope functions
+  - `require-req-annotation`: Require a @req annotation on all in-scope functions
+  - Together, these rules ensure functions carry both @story and @req annotations when both rules are enabled
+- **REQ-CONFIGURABLE-SCOPE**: Both rules support the same configurable scope semantics, including:
+  - Which function kinds require annotations (e.g., exported only vs. all detected kinds)
+  - Optional constraints based on configuration (e.g., complexity threshold, if applicable)
+- **REQ-EXPORT-PRIORITY**: Both rules support a shared `exportPriority`/equivalent option so that exported functions are prioritized for enforcement over internal ones, with consistent behavior across both rules
+- **REQ-ERROR-LOCATION**: Both rules report errors at the function name (or closest equivalent for anonymous constructs) for precise error location
+- **REQ-TYPESCRIPT-SUPPORT**: Support TypeScript-specific function syntax and decorators, including `TSDeclareFunction` and `TSMethodSignature`, with consistent handling across both rules
+
+## 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:
+
+**Development Resources**:
+
+- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for comprehensive patterns
+- Review [Working with the AST](../custom-rules-development-guide.md#working-with-the-ast) for visitor patterns
+- See [Accessing Source Code](../custom-rules-development-guide.md#accessing-source-code) for JSDoc comment parsing
+
+**Implementation Details**:
+
+- Use @typescript-eslint/utils for AST parsing to handle TypeScript syntax
+- Leverage ESLint's JSDoc utilities for comment parsing via `sourceCode.getCommentsBefore()`
+- Support function declarations and function expressions (excluding arrow functions), as well as `MethodDefinition`, `TSDeclareFunction`, and `TSMethodSignature`
+- 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 function expressions, IIFE, generator functions, async function declarations/expressions
+- Arrow functions are explicitly excluded from traceability requirements by default
+- Provide clear error messages that include function name and missing annotation type
+- Keep `require-story-annotation` and `require-req-annotation` implementations aligned so that any changes to detection or scoping logic remain consistent between both rules
+
+**Key Guide Sections**:
+
+- [The Context Object](../custom-rules-development-guide.md#the-context-object) - Accessing sourceCode and options
+- [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) - Using messageIds and context.report()
+- [Rule Options and Schema](../custom-rules-development-guide.md#rule-options-and-schema) - Defining configurable behavior
+
+## Definition of Done
+
+- [x] All acceptance criteria met
+- [ ] Code reviewed and approved
+- [ ] Tests written and passing (comprehensive RuleTester coverage)
+- [x] 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

@@ -0,0 +1,153 @@
+# 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:
+
+**Development Resources**:
+
+- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for comprehensive patterns
+- Review [Working with the AST](../custom-rules-development-guide.md#working-with-the-ast) for control flow node visitors
+- See [Accessing Source Code](../custom-rules-development-guide.md#accessing-source-code) for comment association
+
+**Implementation Details**:
+
+- Leverage patterns established in 003.0-DEV-FUNCTION-ANNOTATIONS for consistency
+- Use AST visitor pattern to identify significant control flow nodes (IfStatement, TryStatement, ForStatement, etc.)
+- Consider branch complexity/significance thresholds (configurable)
+- Handle inline comments vs. block comments for branch annotations
+- Support various comment styles (// and /\* \*/) for branch annotations using `sourceCode.getCommentsBefore()`
+- 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.)
+
+**Key Guide Sections**:
+
+- [Working with the AST](../custom-rules-development-guide.md#working-with-the-ast) - Visitor methods for control flow nodes
+- [Accessing Source Code](../custom-rules-development-guide.md#accessing-source-code) - Getting comments with includeComments option
+
+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);
+}
+```
+
+## Configuration (REQ-CONFIGURABLE-SCOPE)
+
+This ESLint rule can be configured to enforce annotations only on specific branch types. For example, to enforce only on `IfStatement` and `ForStatement`:
+
+```js
+// .eslintrc.js
+module.exports = {
+  rules: {
+    // @req REQ-CONFIGURABLE-SCOPE
+    "traceability/require-branch-annotation": [
+      "error",
+      { branchTypes: ["IfStatement", "ForStatement"] },
+    ],
+  },
+};
+```
+
+```js
+// .eslintrc.js
+module.exports = {
+  rules: {
+    // @req REQ-CONFIGURABLE-SCOPE
+    "traceability/require-branch-annotation": [
+      "error",
+      { branchTypes: ["IfStatement"] },
+    ],
+  },
+};
+```
+
+Invalid Configuration Behavior:
+
+- If an unsupported or misspelled branch type is provided in `branchTypes`, the rule reports a configuration error during ESLint initialization with a message like:  
+  `traceability/require-branch-annotation: Invalid branch type "InvalidType" in configuration. Supported branch types are: IfStatement, SwitchStatement, ForStatement, WhileStatement, DoWhileStatement, TryStatement, ForInStatement, ForOfStatement.`
+
+## 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

@@ -0,0 +1,138 @@
+# 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:
+
+- [x] **Core Functionality**: Validates @story and @req annotation format and syntax
+- [x] **Quality Standards**: Follows ESLint development best practices for validation rules
+- [x] **Integration**: Works with annotations found by function and branch validation rules
+- [x] **User Experience**: Clear, specific error messages for different format violations
+- [x] **Error Handling**: Gracefully handles edge cases and malformed comment structures
+- [x] **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:
+
+**Development Resources**:
+
+- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for validation patterns
+- Review [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) for error messaging with messageIds
+- See [Rule Options and Schema](../custom-rules-development-guide.md#rule-options-and-schema) for format configuration
+
+**Implementation Details**:
+
+- 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 using data placeholders
+- Consider allowing configuration of custom annotation formats
+
+**Key Guide Sections**:
+
+- [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) - Using message placeholders with data
+- [Rule Options and Schema](../custom-rules-development-guide.md#rule-options-and-schema) - JSON Schema validation for format options
+
+**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)
+
+// @story docs/stories/001.0-DEV-EXAMPLE   (missing .story.md extension)
+// @story ../docs/stories/001.0-DEV-EXAMPLE.story.md  (disallowed ../ traversal)
+// @req REQ-  (invalid identifier format)
+// @req       (no identifier at all)
+// @req       (only the @req token with whitespace, missing identifier)
+```
+
+## Definition of Done
+
+- [x] All acceptance criteria met
+- [ ] Code reviewed and approved
+- [x] Tests written and passing (comprehensive format validation coverage)
+- [x] Documentation updated (annotation format specification and examples)
+- [x] Validation utilities integrated with existing annotation rules
+- [ ] Performance tested with various annotation patterns
+- [ ] Ready for file validation logic (006.0-DEV-FILE-VALIDATION)
+
+---