eslint-plugin-traceability 1.7.1 → 1.8.0

package/docs/functionality-coverage-2025-12-03.md

@@ -0,0 +1,250 @@
+# Functionality Coverage Assessment (2025-12-03)
+
+This document summarizes the current implementation status of the main traceability stories and their requirements, based on the existing rules, maintenance CLI, and automated tests.
+
+## Scope
+
+Stories reviewed:
+
+- 001.0-DEV-PLUGIN-SETUP
+- 002.0-DEV-ESLINT-CONFIG
+- 003.0-DEV-FUNCTION-ANNOTATIONS
+- 004.0-DEV-BRANCH-ANNOTATIONS
+- 005.0-DEV-ANNOTATION-VALIDATION
+- 006.0-DEV-FILE-VALIDATION
+- 007.0-DEV-ERROR-REPORTING
+- 008.0-DEV-AUTO-FIX
+- 009.0-DEV-MAINTENANCE-TOOLS
+- 010.0-DEV-DEEP-VALIDATION
+- 010.1-DEV-CONFIGURABLE-PATTERNS
+- 010.2-DEV-MULTI-STORY-SUPPORT
+- 010.3-DEV-MIGRATE-TO-IMPLEMENTS
+
+## Story-level implementation summary
+
+### 001.0-DEV-PLUGIN-SETUP
+
+**Status:** Substantially implemented; some checklist items in the story remain unchecked but are covered in code and tests.
+
+Evidence:
+
+- `src/index.ts` exports `rules`, `configs`, and `maintenance`, satisfying `REQ-PLUGIN-STRUCTURE`, `REQ-RULE-REGISTRY`, and `REQ-MAINTENANCE-API-EXPORT`.
+- `tests/plugin-setup.test.ts`, `tests/plugin-default-export-and-configs.test.ts`, `tests/plugin-setup-error.test.ts`, and `tests/integration/cli-integration.test.ts` validate plugin export shape, config presets, and error handling.
+- User-facing setup docs: `README.md`, `user-docs/eslint-9-setup-guide.md`, and `user-docs/examples.md` provide configuration guidance.
+
+Notable gaps vs. story checkboxes:
+
+- Story acceptance criteria checkboxes for **Core Functionality**, **Quality Standards**, **Integration**, **User Experience**, and **Documentation** are not explicitly marked as done in the story file, but the implementation and tests indicate they are effectively satisfied.
+
+### 002.0-DEV-ESLINT-CONFIG
+
+**Status:** Implemented via flat-config presets and documented, but story checkboxes remain unchecked.
+
+Evidence:
+
+- `src/index.ts` defines `configs.recommended` and `configs.strict` using `TRACEABILITY_RULE_SEVERITIES` mapping, satisfying `REQ-CONFIG-PRESETS`, `REQ-FLAT-CONFIG`, and `REQ-CONFIG-SYSTEM`.
+- `docs/config-presets.md` and `user-docs/eslint-9-setup-guide.md` document preset usage and flat config examples.
+- `tests/plugin-default-export-and-configs.test.ts` asserts rule presence and severity mapping, including `prefer-implements-annotation`.
+
+Notable gaps vs. story checkboxes:
+
+- Acceptance criteria in `002.0-DEV-ESLINT-CONFIG.story.md` are unchecked, but implemented behavior and tests demonstrate that configuration presets and flat-config integration work.
+- There are no targeted tests for configuration error handling beyond schema-based validation in individual rules (e.g., `require-branch-annotation` and `valid-annotation-format`).
+
+### 003.0-DEV-FUNCTION-ANNOTATIONS
+
+**Status:** Implemented and well tested.
+
+Evidence:
+
+- `src/rules/require-story-annotation.ts` and `src/rules/require-req-annotation.ts` implement function-level enforcement with shared detection logic via `require-story-helpers`.
+- Tests under `tests/rules/require-story-*.test.ts` and `tests/rules/require-req-annotation.test.ts` cover detection of supported node types, configurable scope, and `exportPriority`.
+- CLI integration tests (`tests/integration/cli-integration.test.ts`) confirm rule behavior via ESLint CLI.
+
+Gaps:
+
+- Story `003.0` DoD checklist has unchecked items for "Code reviewed", "Rule integrated into plugin configuration presets", and "Performance tested" even though presets include the rules and Jest coverage is high. There is no dedicated performance testing beyond normal CI, which matches the story note.
+
+### 004.0-DEV-BRANCH-ANNOTATIONS
+
+**Status:** Implemented and tested, but story acceptance criteria remain unchecked.
+
+Evidence:
+
+- `src/rules/require-branch-annotation.ts` with helpers in `src/utils/branch-annotation-helpers.ts` enforces `@story`/`@req` on configurable branch types.
+- `tests/rules/require-branch-annotation.test.ts` verifies behavior across branch types, configuration, error messaging, and auto-fix output.
+- Story requirements `REQ-BRANCH-DETECTION` and `REQ-CONFIGURABLE-SCOPE` are clearly covered by code and tests.
+
+Gaps:
+
+- Story-level checkboxes for **Core Functionality**, **Quality Standards**, etc. are not updated in the markdown.
+- No explicit performance testing beyond normal CI runs.
+
+### 005.0-DEV-ANNOTATION-VALIDATION
+
+**Status:** Implemented and heavily tested.
+
+Evidence:
+
+- `src/rules/valid-annotation-format.ts` and helpers implement syntax/format validation for `@story`, `@req`, and `@implements`, including multiline handling and configurable patterns.
+- `tests/rules/valid-annotation-format.test.ts` covers happy path and error cases, multiline annotations, custom patterns, and configuration error behavior.
+
+Gaps:
+
+- Story DoD items for "Code reviewed" and "Performance tested" remain unchecked, but behavior and coverage are complete.
+
+### 006.0-DEV-FILE-VALIDATION
+
+**Status:** Implemented and tested; some DoD items left unchecked.
+
+Evidence:
+
+- `src/rules/valid-story-reference.ts` and `src/utils/storyReferenceUtils.ts` implement existence checks, path resolution, security validation, project boundary enforcement, and configuration (`storyDirectories`, `allowAbsolutePaths`, `requireStoryExtension`).
+- `tests/rules/valid-story-reference.test.ts` validates core behavior, configuration variants, project boundary logic, and error handling for filesystem failures.
+
+Gaps:
+
+- Story DoD still marks "Code reviewed" and full performance testing as incomplete.
+
+### 007.0-DEV-ERROR-REPORTING
+
+**Status:** Implemented across rules with shared conventions; acceptance criteria and DoD fully checked in story.
+
+Evidence:
+
+- Messages in `require-story-annotation`, `require-req-annotation`, `require-branch-annotation`, `valid-annotation-format`, `valid-story-reference`, and `valid-req-reference` align with documented patterns.
+- `tests/rules/error-reporting.test.ts` and per-rule tests assert message contents and placeholders.
+
+Gaps:
+
+- None identified at functionality level.
+
+### 008.0-DEV-AUTO-FIX
+
+**Status:** Partially implemented according to story narrative; acceptance criteria in the story are mostly checked but not all DoD items are complete.
+
+Evidence:
+
+- Auto-fix for missing `@story` on functions is implemented in `require-story-annotation` and tested in `tests/rules/auto-fix-behavior-008.test.ts`.
+- Auto-fix for simple `@story` path suffix issues is implemented via `valid-annotation-format` helpers and covered in tests.
+
+Gaps:
+
+- Story DoD items for "Code reviewed", "Tests written and passing" (not ticked even though tests exist), and deployment/acceptance are left unchecked.
+- Configurable auto-fix templates and selective fix toggles are explicitly out of scope in the current implementation but still listed as future requirements in the story.
+
+### 009.0-DEV-MAINTENANCE-TOOLS
+
+**Status:** Core maintenance API and CLI behaviors are implemented and tested; story acceptance checkboxes are currently unchecked.
+
+Evidence:
+
+- Maintenance modules: `src/maintenance/detect.ts`, `src/maintenance/update.ts`, `src/maintenance/report.ts`, `src/maintenance/batch.ts`, and `src/maintenance/index.ts` implement `detectStaleAnnotations`, `updateAnnotationReferences`, `batchUpdateAnnotations`, `verifyAnnotations`, and `generateMaintenanceReport`.
+- CLI: `src/maintenance/cli.ts` exposes `detect`, `verify`, `report`, and `update` commands with documented flags; tests in `tests/maintenance/cli.test.ts` cover exit codes, dry-run, JSON output, and update behavior.
+- Additional tests in `tests/maintenance/*.test.ts` confirm behavior of individual operations.
+- User docs in `user-docs/api-reference.md` and README describe the CLI and API.
+
+Gaps:
+
+- Story acceptance checkboxes for **Core Functionality**, **Quality Standards**, **Integration**, **User Experience**, **Error Handling**, and **Documentation** have not been updated despite matching implementation.
+- Advanced features mentioned in implementation notes (e.g., file system watching) are not implemented and are treated as future enhancements.
+
+### 010.0-DEV-DEEP-VALIDATION
+
+**Status:** Partially implemented.
+
+Evidence:
+
+- `src/rules/valid-req-reference.ts` implements deep validation of `@req` and `@implements` references against story file content, including caching and path safety.
+- `tests/rules/valid-req-reference.test.ts` covers missing requirements, bullet-list formats, `@implements` references, and path security for both `@story` and `@implements`.
+
+Gaps:
+
+- Story acceptance criteria for handling varied requirement formats, sections, and error handling are only partially reflected in implementation; e.g., current regex-based extraction looks for `REQ-...` anywhere, which handles common formats but does not parse document sections explicitly.
+- Story DoD items for code review, testing, documentation, and deployment remain unchecked.
+
+### 010.1-DEV-CONFIGURABLE-PATTERNS
+
+**Status:** Implemented at the rule level, with tests and documentation; story checkboxes partially unchecked.
+
+Evidence:
+
+- `valid-annotation-format` supports nested and flat configuration for `story` and `req` patterns and examples via `valid-annotation-options` helpers.
+- `tests/rules/valid-annotation-format.test.ts` thoroughly covers nested vs. flat options, precedence, invalid regex handling, and example propagation into error messages.
+- `docs/rules/valid-annotation-format.md` documents configuration options and behavior.
+
+Gaps:
+
+- Story DoD fields for schema validation and integration testing are partially left unchecked, though tests indicate behavior is covered.
+
+### 010.2-DEV-MULTI-STORY-SUPPORT
+
+**Status:** Implemented at annotation and deep-validation levels; some DoD items still open.
+
+Evidence:
+
+- `valid-annotation-format` parses and validates `@implements` annotation syntax.
+- `valid-req-reference` validates `@implements` requirement IDs against referenced story files, allowing shared IDs across stories.
+- `tests/rules/valid-annotation-format.test.ts` and `tests/rules/valid-req-reference.test.ts` cover `@implements` syntax, error cases, and multi-story behavior.
+- `docs/rules/valid-annotation-format.md` describes `@implements` format and usage.
+
+Gaps:
+
+- Story `010.2` DoD items for code review, full test completion, backward-compat checks, and integration with a real codebase are not ticked.
+
+### 010.3-DEV-MIGRATE-TO-IMPLEMENTS
+
+**Status:** Implemented as an opt-in rule with auto-fix; several DoD items marked incomplete in story.
+
+Evidence:
+
+- `src/rules/prefer-implements-annotation.ts` implements detection, diagnostics, and conservative auto-fix transforming simple `@story` + `@req` blocks into `@implements`.
+- `tests/rules/prefer-implements-annotation.test.ts` validates basic recommendations, multi-story detection, mixed-usage behavior, and auto-fix outputs.
+- Rule documentation: `docs/rules/prefer-implements-annotation.md` and `user-docs/migration-guide.md`.
+
+Gaps:
+
+- Story DoD items for code review, applying auto-fix to a real repository (e.g., dry-aged-deps), and some validation bullets remain unchecked.
+
+## Cross-cutting observations
+
+- Many stories have acceptance criteria and Definition of Done checkboxes that are not aligned with the current implementation reality. Functionality and tests are generally ahead of the story metadata.
+- Core plugin rules and maintenance tools are wired into presets and CLI and covered by both unit tests and integration tests (via ESLint CLI and the `traceability-maint` CLI).
+- Deep validation (`valid-req-reference`) has a narrower implementation than the full aspirational scope of Story 010.0 but still satisfies the main user-visible goal of preventing references to non-existent requirement IDs.
+
+## High-level gaps and mismatches
+
+1. **Stories vs. Implementation Status**
+   - Several stories (001.0, 002.0, 004.0, 005.0, 006.0, 008.0, 009.0, 010.0, 010.1, 010.2, 010.3) show unchecked acceptance criteria or DoD items even though the corresponding functionality and tests exist.
+   - This is primarily a documentation/traceability misalignment rather than missing code.
+
+2. **Deep Validation Scope (010.0)**
+   - Implementation uses a regex-based extraction (`/REQ-[A-Z0-9-]+/g`) over the entire story file, which:
+     - Works for the common patterns in `docs/stories/*.story.md` and test fixtures.
+     - Does not explicitly parse sections or structured requirement blocks as described in the story.
+   - Story requirements about section-specific parsing and multiple requirement formats are only partially realized.
+
+3. **Maintenance Tools Advanced Features (009.0)**
+   - The story mentions file system watching and potential Git hook integration; current code exposes CLI and batch functions but does not implement watching or direct hook integration.
+   - From a functionality standpoint, the main user story about batch update and detection is satisfied, but advanced scenarios are left for future work.
+
+4. **Auto-fix Configurability (008.0, 010.3)**
+   - Auto-fix is implemented for specific, safe scenarios:
+     - Adding missing `@story` annotations.
+     - Correcting simple `.story.md` suffix issues.
+     - Migrating simple `@story` + `@req` blocks to `@implements`.
+   - Story mentions configurable templates and selective fix toggles that are not yet implemented.
+
+5. **ESLint Config Story (002.0)**
+   - While presets and docs exist, the story leaves acceptance criteria unchecked and there are no dedicated negative tests for misconfiguration at the plugin or preset level beyond per-rule schema checks.
+
+## Summary
+
+- **Core traceability rules (003.00.3) and maintenance tools (009.0) are functionally implemented and well tested.**
+- **Most remaining discrepancies are between story checklists and actual implementation, plus a few aspirational requirements (deep parsing, FS watching, configurable templates) that have been consciously scoped out.**
+- **No major gaps were found where a documented user-facing behavior is entirely missing from the code or tests.**
+
+This assessment should be used as a baseline for any future work that aims to either:
+
+- Bring the story markdown files up to date with the current implementation status, and/or
+- Extend implementation to cover the remaining aspirational requirements (deep markdown parsing, advanced maintenance automation, configurable auto-fix templates).

package/docs/jest-testing-guide.md

@@ -0,0 +1,100 @@
+# Jest Testing Guide
+
+This guide covers testing practices and configuration for the eslint-plugin-traceability project.
+
+## Traceability in Test Output
+
+### Viewing Story and Requirement References
+
+By default, Jest's standard output only shows file-level test results without displaying individual test descriptions or traceability annotations. To see the full traceability information including story references and requirement IDs, you must use the `--verbose` option.
+
+**Standard output (limited visibility):**
+
+```bash
+npm test
+```
+
+Shows only:
+
+```
+ PASS  tests/maintenance/batch.test.ts
+ PASS  tests/rules/require-branch-annotation.test.ts
+```
+
+**Verbose output (full traceability):**
+
+```bash
+npm test -- --verbose
+```
+
+Shows detailed test descriptions with traceability annotations:
+
+```
+ PASS  tests/maintenance/batch.test.ts
+  batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)
+    ✓ [REQ-MAINT-BATCH] should return 0 when no mappings applied (6 ms)
+  verifyAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)
+    ✓ [REQ-MAINT-VERIFY] should return true when annotations are valid
+
+ PASS  tests/rules/require-branch-annotation.test.ts
+  Require Branch Annotation Rule (Story 004.0-DEV-BRANCH-ANNOTATIONS)
+    require-branch-annotation
+      valid
+        ✓ [REQ-BRANCH-DETECTION] valid if-statement with annotations (4 ms)
+```
+
+### Test Structure Requirements
+
+All tests in this project follow a specific structure to support traceability:
+
+1. **File-level annotations** at the top of each test file:
+
+   ```typescript
+   /**
+    * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    * @req REQ-MAINT-BATCH - Perform batch updates
+    * @req REQ-MAINT-VERIFY - Verify annotation references
+    */
+   ```
+
+2. **Describe blocks** that reference the story:
+
+   ```typescript
+   describe('batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)', () => {
+   ```
+
+3. **Test cases** that reference specific requirements:
+   ```typescript
+   it('[REQ-MAINT-BATCH] should return 0 when no mappings applied', () => {
+   ```
+
+### Running Tests for Traceability Review
+
+When reviewing test coverage for specific stories or requirements:
+
+- **For development/debugging**: Use `npm test -- --verbose` to see all traceability information
+- **For CI/CD pipelines**: Standard `npm test` provides sufficient pass/fail information
+- **For coverage analysis**: Both modes provide the same coverage statistics
+
+### Best Practices
+
+1. **Always include story references** in describe blocks to make them visible in verbose output
+2. **Prefix test descriptions with requirement IDs** in square brackets (e.g., `[REQ-MAINT-BATCH]`)
+3. **Use meaningful test descriptions** that clearly indicate what requirement is being tested
+4. **Run with --verbose during development** to verify traceability annotations are properly displayed
+
+## Configuration
+
+The project's Jest configuration is defined in `jest.config.js` and includes:
+
+- Coverage reporting
+- TypeScript support via ts-jest
+- Test file patterns
+- CI-friendly options (--ci --bail --coverage)
+
+## Related Documentation
+
+- [Story Files](stories/) - User story definitions
+- [ESLint Plugin Development Guide](eslint-plugin-development-guide.md) - General development practices
+- [Decision Records](decisions/) - Architectural decisions including Jest adoption

package/docs/rules/prefer-implements-annotation.md

@@ -0,0 +1,219 @@
+# prefer-implements-annotation
+
+Optional migration rule that recommends converting legacy `@story` + `@req` annotations to the newer `@implements` format.
+
+@story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md  
+@req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+@req REQ-MULTI-STORY-DETECT - Detect multi-story patterns and mixed usage that cannot be auto-fixed yet
+@req REQ-AUTO-FIX - Provide safe auto-fix support for simple single-story @story + @req blocks
+@req REQ-SINGLE-STORY-FIX - Automatically convert single-story @story/@req blocks to @implements
+@req REQ-PRESERVE-FORMAT - Preserve surrounding comment structure and non-traceability tags during auto-fix
+@req REQ-VALID-OUTPUT - Ensure auto-fixed output always passes existing validation rules
+@req REQ-BACKWARDS-COMPAT-VALIDATION - Ensure legacy @story/@req annotations remain valid when the rule is disabled
+
+> Note: Auto-fix is intentionally conservative and only applies to simple, clearly single-story legacy blocks. More complex patterns (multi-story, mixed `@implements`, or unusual formatting) are detected but **not** auto-fixed and will still require manual migration.
+
+## Rule Details
+
+This rule is designed as an **opt-in migration aid** for teams that want to gradually standardize on the `@implements` annotation while keeping existing `@story` + `@req` annotations fully supported.
+
+When enabled, it scans block/JSDoc comments and:
+
+- Detects legacy blocks that contain both `@story` and `@req` but **no** `@implements` lines
+- Emits a `preferImplements` recommendation diagnostic for those blocks (and auto-fixes eligible ones to `@implements` when run with `--fix`)
+- Detects mixed usage where a single comment combines `@story`/`@req` and `@implements`
+- Detects multiple distinct `@story` paths in the same block (likely multi-story integration)
+
+It **does not** change how any of the validation rules behave:
+
+- `valid-annotation-format` continues to validate `@story`, `@req`, and `@implements` formats
+- `valid-req-reference` continues to perform deep validation of requirements against story files
+- `require-story-annotation` and `require-req-annotation` continue to enforce presence of annotations as before
+
+This separation ensures that turning the rule on/off only affects **recommendations**, not validation correctness.
+
+## Options
+
+The rule currently does not accept any options. You control its behavior with normal ESLint severity configuration:
+
+```js
+// eslint.config.js (flat config)
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  traceability.configs.recommended,
+  {
+    rules: {
+      // Default: off (no recommendations)
+      "traceability/prefer-implements-annotation": "off",
+
+      // Or enable as warnings
+      // "traceability/prefer-implements-annotation": "warn",
+
+      // Or enforce as errors
+      // "traceability/prefer-implements-annotation": "error",
+    },
+  },
+];
+```
+
+- `"off"` (default) – rule is disabled; no additional diagnostics
+- `"warn"` – surfaces recommendations without failing builds
+- `"error"` – treats recommendations as errors for strict migration phases
+
+## Behavior
+
+### Legacy `@story` + `@req` blocks
+
+When the rule encounters a block/JSDoc comment that contains **both** `@story` and `@req` lines and **no** `@implements` lines, it reports:
+
+- **Message ID:** `preferImplements`
+- **Text:**
+  > Consider using @implements instead of @story + @req for clearer traceability. Run ESLint with --fix to auto-convert.
+
+For simple single-story blocks, running ESLint with `--fix` will automatically rewrite the comment to use `@implements` while preserving the rest of the comment content.
+
+Example (will trigger `preferImplements` and is auto-fixable):
+
+```js
+/**
+ * Calculate age in days since publish date.
+ * @story docs/stories/002.0-DEV-FETCH-AVAILABLE-VERSIONS.story.md
+ * @req REQ-AGE-CALC
+ */
+export function calculateAgeInDays(publishDate) {}
+```
+
+Auto-fix output:
+
+```js
+/**
+ * Calculate age in days since publish date.
+ * @implements docs/stories/002.0-DEV-FETCH-AVAILABLE-VERSIONS.story.md REQ-AGE-CALC
+ */
+export function calculateAgeInDays(publishDate) {}
+```
+
+### Auto-fix limitations
+
+Auto-fix is deliberately limited to straightforward cases. It will **not** rewrite:
+
+- Comments with multiple distinct `@story` annotations (multi-story integration blocks)
+- Comments that already contain any `@implements` annotations (mixed legacy/modern usage)
+- Comments where `@story` or `@req` lines are unusually formatted or split across lines in ways that make the intent ambiguous
+
+In these cases the rule still reports diagnostics, but leaves the comment unchanged so you can migrate it manually.
+
+### Mixed `@story` / `@req` / `@implements` usage
+
+If the rule sees a comment that already contains `@implements` alongside legacy `@story` / `@req`, it cannot know the intended final layout. In this case it reports:
+
+- **Message ID:** `cannotAutoFix`
+- **Data:** `{ reason: "comment mixes @story/@req with existing @implements annotations" }`
+
+Example:
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
+ */
+function mixed() {}
+```
+
+The rule warns that this block requires **manual** restructuring into clear `@implements` lines.
+
+### Multiple `@story` annotations in a single block
+
+When a single comment block contains more than one distinct `@story` path, the rule treats it as a likely multi-story integration block and reports:
+
+- **Message ID:** `multiStoryDetected`
+- **Text:**
+  > Multiple @story annotations detected in the same comment block. Manually convert to separate @implements lines.
+
+Example:
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION
+ */
+function multiStory() {}
+```
+
+This is a strong indicator that the code should use separate `@implements` lines for each story.
+
+### What the rule intentionally ignores
+
+To preserve backward compatibility and avoid noisy diagnostics, the rule intentionally **does not** report on:
+
+- Comments that contain only `@story` or only `@req` (no migration opportunity)
+- Comments that contain only `@implements` (already in the target format)
+- Line comments with annotations (`// @story ...`) – the first iteration focuses on JSDoc/block comments, which are the primary migration targets
+
+Validation for all of these cases remains the responsibility of the existing rules (`valid-annotation-format`, `require-story-annotation`, `require-req-annotation`, `valid-req-reference`).
+
+## Examples
+
+### Correct (rule disabled or satisfied)
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
+function legacyButValid() {}
+
+/**
+ * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
+ */
+function alreadyMigrated() {}
+```
+
+### Reported: single-story legacy block
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
+function legacy() {}
+// -> preferImplements (eligible blocks will be auto-fixed to @implements when running with --fix)
+```
+
+### Reported: mixed legacy and `@implements`
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
+ */
+function mixed() {}
+// -> cannotAutoFix (manual intervention required)
+```
+
+### Reported: multiple distinct `@story` paths
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION
+ */
+function multiStory() {}
+// -> multiStoryDetected (multi-story integration needs manual @implements mapping)
+```
+
+## Relationship to other rules
+
+- Use `prefer-implements-annotation` to **guide migration** from legacy annotations to `@implements`.
+- Use `valid-annotation-format` to enforce syntax and format for `@story`, `@req`, and `@implements`.
+- Use `valid-req-reference` to validate that each `@req` and `@implements` requirement ID exists in the referenced story file.
+- Keep `require-story-annotation` and `require-req-annotation` enabled to ensure functions remain fully annotated during and after migration.
+
+Together, these rules support a smooth, incremental transition from purely `@story` + `@req` annotations to richer, multi-story `@implements` annotations without breaking existing projects.

package/docs/rules/require-branch-annotation.md

@@ -0,0 +1,71 @@
+# require-branch-annotation
+
+Ensures that significant code branches (if/else, switch cases, loops, try/catch) have `@story` and `@req` annotations for traceability.
+
+@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md  
+@req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations  
+@req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+
+## Rule Details
+
+This rule checks for JSDoc or inline comments immediately preceding significant code branches and ensures both `@story` and `@req` annotations are present.
+
+### Options
+
+Property: `branchTypes` (array of AST node type strings)  
+Default: `["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"]` (DEFAULT_BRANCH_TYPES)  
+Allowed values: `["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"]`  
+If an invalid branch type is provided, the rule will report a configuration error with a message: Value "<invalid>" should be equal to one of the allowed values.
+
+Example (.eslintrc.js):
+
+```js
+module.exports = {
+  rules: {
+    "traceability/require-branch-annotation": [
+      "error",
+      {
+        branchTypes: ["IfStatement", "ForStatement"],
+      },
+    ],
+  },
+};
+```
+
+### Examples
+
+#### Correct
+
+```js
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (error) {
+  handleError();
+}
+```
+
+#### Incorrect
+
+```js
+if (error) {
+  handleError();
+}
+```
+
+#### Invalid Configuration
+
+```js
+// .eslintrc.js
+module.exports = {
+  rules: {
+    "traceability/require-branch-annotation": [
+      "error",
+      {
+        branchTypes: ["IfStatement", "InvalidType"],
+      },
+    ],
+  },
+};
+
+// Error: Value "InvalidType" should be equal to one of the allowed values.
+```