eslint-plugin-traceability 1.8.0 → 1.8.2

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

@@ -1,144 +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:
-
-- [x] **Core Functionality**: Validates @story file paths reference existing .story.md files
-- [x] **Quality Standards**: Follows ESLint development best practices and handles file system operations safely
-- [x] **Integration**: Works with annotations validated by format validation (005.0)
-- [x] **User Experience**: Clear error messages indicate which files are missing or invalid
-- [x] **Error Handling**: Gracefully handles file system permissions, network drives, and edge cases
-- [x] **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-ERROR-HANDLING**: Gracefully handles filesystem and path validation errors and provides clear diagnostics
-- **REQ-ANNOTATION-VALIDATION**: Parse and validate @story annotation lines so that file paths can be extracted reliably for validation
-- **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:
-
-**Development Resources**:
-
-- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for implementation patterns
-- Review [The Context Object](../custom-rules-development-guide.md#the-context-object) for accessing cwd and filename
-- See [Best Practices](../custom-rules-development-guide.md#best-practices) for performance optimization
-
-**Implementation Details**:
-
-- Use Node.js fs/promises for async file system operations (note: ESLint rules are synchronous, cache during plugin initialization)
-- Implement path resolution relative to project root using `context.cwd` (where package.json/eslint.config.js exists); the rule now prefers `context.cwd` when available and falls back to `process.cwd` as a safe default.
-- Support configurable story directories (e.g., docs/stories/, stories/, etc.) via rule options
-- Resolved story paths discovered via absolute references or via `storyDirectories` must still reside within the project root; any existing file resolved outside the project is reported as an `invalidPath` error.
-- 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
-
-**Key Guide Sections**:
-
-- [The Context Object](../custom-rules-development-guide.md#the-context-object) - Using context.cwd for path resolution
-- [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) - Providing helpful error messages
-- [Best Practices](../custom-rules-development-guide.md#best-practices) - Caching for performance
-
-**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
-
-- [x] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [x] Tests written and passing (file system scenarios, path resolution, security)
-- [x] Documentation updated (file validation rules and configuration options)
-- [ ] Performance tested with large numbers of story files
-- [x] Security reviewed for path traversal and access control
-- [x] Ready for error reporting enhancement (007.0-DEV-ERROR-REPORTING)
-
----

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

@@ -1,163 +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
-
-- [x] **Core Functionality**: All validation rules provide specific, actionable error messages instead of generic failures
-- [x] **Quality Standards**: Error messages follow ESLint best practices for clarity and consistency
-- [x] **Integration**: Error messages work properly with existing validation rules and ESLint reporting
-- [x] **User Experience**: Messages clearly identify the problem, location, and suggested fix
-- [x] **Error Handling**: Gracefully handles edge cases where error context is incomplete
-- [x] **Documentation**: Error message formats are documented for consistency across rules
-
-## Requirements (Implemented & Verified)
-
-All of the following requirements are implemented in the current ruleset and verified by automated tests and manual review:
-
-- **REQ-ERROR-SPECIFIC**: Each validation failure provides specific details about what annotation is missing or invalid. Verified across:
-  - `traceability/require-story-annotation`
-  - `traceability/require-req-annotation`
-  - `traceability/require-branch-annotation`
-  - `traceability/valid-annotation-format`
-  - `traceability/valid-story-reference`
-  - `traceability/valid-req-reference`
-- **REQ-ERROR-LOCATION**: Error messages include precise location information (function name, line number, file path) via ESLint’s standard location reporting and message data fields (e.g., `functionName`, `filePath`).
-- **REQ-ERROR-SUGGESTION**: Messages suggest concrete steps to fix the issue (e.g., "Add @story annotation" or "Fix file path"), including ESLint suggestions where implemented (notably in `traceability/require-story-annotation`).
-- **REQ-ERROR-CONTEXT**: Error messages include relevant context (expected annotation format, available story files) via `details`, `reqId`, `storyId`, and `storyPath` placeholders where applicable.
-- **REQ-ERROR-CONSISTENCY**: All plugin rules now conform to the shared error message conventions defined in this story, using common patterns and placeholders via `meta.messages` and shared `messageId` values where appropriate.
-- **REQ-ERROR-SEVERITY**: Error severity levels are appropriate (error for missing annotations, warning for format issues) and aligned with ESLint’s `severity` configuration and rule defaults.
-
-## Error Message Conventions
-
-Cross-rule error messages follow these shared patterns for consistency and clarity:
-
-- **Function-related errors**
-  - Use `{{functionName}}` to identify the affected function or method.
-  - Typical pattern:
-    - `"Function '{{functionName}}' is missing a required @story annotation."`
-    - `"Function '{{functionName}}' has an invalid @req annotation: {{details}}."`
-
-- **Branch-related errors**
-  - Use a generic `missingAnnotation`-style message with a `{{missing}}` placeholder to describe what is absent.
-  - Typical pattern:
-    - `"Branch is missing required annotation: {{missing}}."`
-
-- **Format / validation details**
-  - Use a `{{details}}` placeholder for human-readable validation output, such as expected formats or concrete problems.
-  - Typical pattern:
-    - `"Invalid annotation format: {{details}}."`
-
-- **File / reference errors**
-  - Use `{{filePath}}` (and when applicable, `{{storyId}}` / `{{reqId}}`) to indicate problematic references.
-  - Typical pattern:
-    - `"Referenced story file '{{filePath}}' could not be found."`
-    - `"Requirement '{{reqId}}' was not found in '{{filePath}}'."`
-
-- **Severity conventions**
-  - **Errors** (`severity: 2`):
-    - Missing required annotations (e.g., missing `@story` or `@req`).
-    - Missing or unresolved referenced files or requirement IDs.
-  - **Warnings** (`severity: 1`):
-    - Annotation format or style issues that do not break traceability, e.g., spacing, optional fields, or non-critical structure problems.
-
-All rules expose these messages through `meta.messages` with `messageId` values that are reused where appropriate, ensuring consistent wording and behavior across function, branch, and file validation rules.
-
-## 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)
-
-**Development Resources**:
-
-- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for error reporting patterns
-- Review [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) for context.report() usage
-- See [Providing Suggestions](../custom-rules-development-guide.md#providing-suggestions) for suggestion API
-
-A dedicated error-reporting test suite exists at `tests/rules/error-reporting.test.ts`, which verifies that the implemented rules conform to the shared error message conventions and produce the expected messages and suggestions (including for `traceability/require-story-annotation`).
-
-**Current Rule Implementations**
-
-- `traceability/require-story-annotation`
-  - Uses `meta.messages.missingStory` with pattern `Function '{{name}}' must have an explicit @story annotation. Add a JSDoc or line comment with @story that points to the implementing story file (for example, docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md).` and provides ESLint suggestions via `suggest` in `context.report()`.
-- `traceability/require-req-annotation`
-  - Uses `meta.messages.missingReq` with pattern `Function '{{name}}' is missing a required @req annotation. Add a JSDoc or line comment with @req (for example, '@req REQ-EXAMPLE') ...` and reports the function name via both `name` and `functionName` data fields.
-- `traceability/require-branch-annotation`
-  - Uses `meta.messages.missingAnnotation` with pattern `Branch is missing required annotation: {{missing}}.` for branch-level errors.
-- `traceability/valid-annotation-format`
-  - Uses `meta.messages.invalidStoryFormat` and `meta.messages.invalidReqFormat` with pattern `Invalid annotation format: {{details}}.` where `details` contains the more specific validation message (missing path, invalid ID, etc.).
-- `traceability/valid-story-reference`
-  - Uses `meta.messages.fileMissing`, `invalidExtension`, `invalidPath`, and `fileAccessError` to distinguish missing files from filesystem errors and invalid paths.
-- `traceability/valid-req-reference`
-  - Uses `meta.messages.reqMissing` and `invalidPath` to report missing requirement IDs and unsafe story paths, including both `reqId` and `storyPath` in the message data.
-
-**Technical Considerations**:
-
-- Use ESLint's context.report() method for consistent error reporting
-- Implement error message templates in meta.messages using messageIds (recommended approach)
-- Use data placeholders for dynamic error information (e.g., `{{functionName}}`, `{{filePath}}`)
-- Consider internationalization support for error messages
-- Include suggestions using ESLint's suggest API where appropriate for manual fixes
-
-**Key Guide Sections**:
-
-- [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) - Complete guide to context.report() and messageIds
-- [Providing Suggestions](../custom-rules-development-guide.md#providing-suggestions) - Using hasSuggestions and suggest array
-
-**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
-
-- [x] All acceptance criteria met
-- [x] Code reviewed and approved
-- [x] Tests written and passing
-- [x] Documentation updated
-- [x] Deployed to appropriate environment
-- [x] Stakeholder acceptance confirmed
-
-All requirements in this story are now verified by automated tests that match the implemented rules and error message templates.

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

@@ -1,150 +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
-
-- [x] **Core Functionality**: ESLint --fix automatically resolves common annotation violations
-  - Implemented for missing `@story` on functions/methods via `require-story-annotation` and safe `@story` path suffix normalization via `valid-annotation-format`, both verified by dedicated tests (including `tests/rules/auto-fix-behavior-008.test.ts`)
-- [x] **Quality Standards**: Auto-fixes are safe and preserve code functionality and formatting
-  - Implemented for function/method `@story` auto-insertion and simple path suffix normalization with conservative, non-destructive edits
-- [x] **Integration**: Auto-fix works properly with existing validation rules and ESLint toolchain
-  - Implemented and integrated for function/method `@story` validation and basic `.story`/`.md` path suffix normalization in existing rules
-- [x] **User Experience**: Fixes are applied consistently and predictably across different code patterns
-  - Implemented for supported function/method patterns and simple path suffix normalization, with consistent before/after behavior validated by tests
-- [x] **Error Handling**: Gracefully handles edge cases where auto-fix cannot be applied safely
-  - Implemented so unfixable or ambiguous cases report validation errors without attempting a fix, focusing only on clearly safe scenarios
-- [x] **Documentation**: Auto-fix capabilities are documented with examples of fixable issues
-  - Implemented documentation in `user-docs/api-reference.md` for `traceability/require-story-annotation` and `traceability/valid-annotation-format`, including what `--fix` does for each rule and the safety constraints on applied fixes
-
-## Requirements (Current Implementation or To Be Implemented)
-
-- **REQ-AUTOFIX-MISSING**: Automatically add missing @story annotations to functions and methods using a simple built-in template via the `require-story-annotation` rule
-  - Implemented for function and method annotations in this story; behavior is covered by `require-story-annotation` and verified by dedicated auto-fix tests in `tests/rules/auto-fix-behavior-008.test.ts`. The template content and formatting are currently fixed but designed for future configurability, implemented via the rule and helper functions in `src/rules/helpers/require-story-helpers.ts` and `src/rules/helpers/require-story-core.ts`.
-- **REQ-AUTOFIX-FORMAT**: Fix common annotation format issues (spacing, syntax, casing) for simple, clearly identifiable cases via the `valid-annotation-format` rule
-  - Implemented for simple `@story` path suffix normalization where the correct suffix (e.g., `.story.md`) can be inferred safely. Behavior is implemented via the `getFixedStoryPath` helper and the `reportInvalidStoryFormatWithFix` helper in `src/rules/valid-annotation-format.ts`, providing safe `.story`/`.md` suffix adjustments and verified by dedicated auto-fix tests in `tests/rules/auto-fix-behavior-008.test.ts`.
-- **REQ-AUTOFIX-SAFE**: Only apply fixes that are guaranteed to be safe and non-destructive
-  - Implemented for:
-    - Adding missing `@story` annotations above functions and methods using a conservative placeholder template (`require-story-annotation`)
-    - Correcting simple, unambiguous story path suffix issues limited to `.story`/`.md` suffix normalization (`valid-annotation-format`)
-  - More complex or ambiguous fixes (e.g., changing directories, inferring new story names, or altering runtime code) remain explicitly out of scope for this iteration.
-- **REQ-AUTOFIX-PRESERVE**: Preserve existing code formatting, indentation, and comment structure
-  - Implemented for current fixes by:
-    - Inserting new `@story` comments immediately above the relevant function/method without reformatting surrounding code or altering existing comments
-    - Applying minimal text changes to append or correct only the `.story`/`.md` suffixes on existing path strings, preserving surrounding formatting, whitespace, and string content
-  - Broader formatting or structural adjustments remain out of scope to avoid unintended changes.
-- **REQ-AUTOFIX-TEMPLATE**: Use configurable annotation templates for consistent formatting
-  - Not yet implemented; current behavior uses a simple, built-in placeholder template for missing `@story` annotations on functions and methods. Template configurability is planned as a future enhancement.
-- **REQ-AUTOFIX-SELECTIVE**: Allow developers to choose which types of fixes to enable/disable
-  - Not yet implemented; selective enable/disable of specific fix behaviors (e.g., missing-annotation vs. path-format fixes) remains future work.
-
-## 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)
-
-**Development Resources**:
-
-- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for fix implementation patterns
-- Review [Applying Fixes](../custom-rules-development-guide.md#applying-fixes) for comprehensive fixer API documentation
-- See [Best Practices](../custom-rules-development-guide.md#best-practices) for safe fix guidelines
-
-**Technical Considerations**:
-
-- Use ESLint's fix API to provide automated corrections
-- Implement fixer functions in context.report() using fix(fixer) callback
-- Set meta.fixable to "code" or "whitespace" (required for fixable rules)
-- Use fixer methods: insertTextBefore(), insertTextAfter(), replaceText(), etc.
-- Consider code formatting preservation using AST manipulation
-- Provide configuration options for auto-fix behavior
-  - NOTE: Template configurability and selective enable/disable of fix types are not yet implemented; current behavior uses a simple, built-in placeholder template for missing `@story` on functions and methods, and always applies safe, simple path suffix fixes when `valid-annotation-format` is enabled and run with `--fix`.
-- Follow fix best practices: don't change runtime behavior, make minimal changes, ensure fixes are safe
-
-**Current Auto-Fix Capabilities (This Iteration)**:
-
-- Adding missing `@story` annotations to functions and methods with a basic placeholder template placed immediately above the function/method, implemented via the `require-story-annotation` rule
-- Fixing simple story path suffix issues (e.g., adding `.story.md` when clearly missing) and other minimal, safe format corrections related to `@story` path suffixes, implemented via the `valid-annotation-format` rule
-
-**Planned / Future Enhancements**:
-
-- Configurable annotation templates for different project conventions
-- Selective enable/disable for specific auto-fix behaviors (e.g., path fixes vs. missing-annotation fixes) beyond standard ESLint rule-level enable/disable
-- Broader pattern coverage for functions and branches while maintaining safety guarantees
-
-**Key Guide Sections**:
-
-- [Applying Fixes](../custom-rules-development-guide.md#applying-fixes) - Complete fixer API reference and examples
-- [Best Practices](../custom-rules-development-guide.md#best-practices) - Fix safety and performance guidelines
-
-**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 for functions and methods (`require-story-annotation`)
-- Fixing simple, unambiguous story path suffix issues (e.g., missing `.story.md`) and related minor format fixes for @story paths (`valid-annotation-format`)
-- Fixing annotation comment syntax (@story vs // @story) where safe and unambiguous through `valid-annotation-format`
-- Correcting annotation format spacing and structure in simple, well-understood cases
-- Standardizing annotation placement (before function vs inline) for supported function/method patterns
-
-**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
-  - Currently focused on missing-function/method-`@story` and simple path suffix issues, with dedicated coverage in `tests/rules/auto-fix-behavior-008.test.ts` alongside existing rule-specific tests
-- 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,117 +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)
-
-**Development Resources**:
-
-- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for rule implementation patterns
-- While this story focuses on CLI tools rather than ESLint rules, the guide's patterns for accessing source code and AST manipulation are applicable
-- Review [Accessing Source Code](../custom-rules-development-guide.md#accessing-source-code) for parsing and modifying annotations
-
-**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
-- Leverage ESLint's SourceCode API patterns for finding and updating annotations
-- Consider integration with Git hooks for automatic maintenance
-- Use AST manipulation for safe code updates (similar to auto-fix but in standalone tools)
-
-**Key Guide Sections**:
-
-- [Accessing Source Code](../custom-rules-development-guide.md#accessing-source-code) - Techniques for finding annotations in code
-- [Applying Fixes](../custom-rules-development-guide.md#applying-fixes) - Patterns for code modification
-
-**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