eslint-plugin-traceability 1.15.0 → 1.16.0

package/user-docs/api-reference.md

@@ -11,19 +11,30 @@ Security and dependency hygiene for the published package are enforced by the sa
 
 Each rule enforces traceability conventions in your code. Below is a summary of each rule exposed by this plugin.
 
+For function-level traceability, new configurations should treat `traceability/require-traceability` as the **canonical** rule: it composes both story and requirement checks and understands both the newer `@supports` style and the legacy `@story` / `@req` pairing. The older keys `traceability/require-story-annotation` and `traceability/require-req-annotation` remain available as **backward-compatible aliases** so existing configs keep working, but they are no longer the primary entry points and are mainly useful when you need to tune severities independently. For new and multi-story scenarios, prefer `@supports` annotations; `@story` and `@req` remain valid and are still appropriate for simple single-story code paths where a consolidated `@supports` tag is not yet required.
+
 In addition to the core `@story` and `@req` annotations, the plugin also understands `@supports` for code that fulfills requirements from multiple stories—for example, a consuming project might use a path like
 `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`
 to indicate that a given function supports a particular requirement from a payments story document within that project’s own `docs/stories` tree. For a detailed explanation of `@supports` behavior and validation, see [Migration Guide](migration-guide.md) (section **3.1 Multi-story @supports annotations**). Additional background on multi-story semantics is available in the project’s internal rule documentation, which is intended for maintainers rather than end users.
 
 The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted for maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
+### Function-level rules overview
+
+For function-level traceability, the plugin exposes a unified rule and two legacy keys:
+
+- `traceability/require-traceability` is the **canonical function-level rule** for new configurations. It ensures functions and methods have both story coverage and requirement coverage, and it accepts either `@supports` (preferred) or legacy `@story` / `@req` annotations.
+- `traceability/require-story-annotation` and `traceability/require-req-annotation` are **backward-compatible aliases** that focus on the story and requirement aspects separately. They are retained for existing configurations and share the same underlying implementation model as the unified rule, but new ESLint configs should normally rely on `traceability/require-traceability` rather than enabling these legacy keys directly.
+
+All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed.
+
 ### traceability/require-traceability
 
 Description: Unified function-level traceability rule that composes the behavior of `traceability/require-story-annotation` and `traceability/require-req-annotation`. When enabled, it enforces that in‑scope functions and methods carry both a story reference (`@story` or an equivalent `@supports` tag) and at least one requirement reference (`@req` or, when configured, `@supports`). The recommended flat‑config presets in this plugin enable `traceability/require-traceability` by default alongside the legacy rule keys for backward compatibility, so that existing configurations referring to `traceability/require-story-annotation` or `traceability/require-req-annotation` continue to work without change.
 
 ### traceability/require-story-annotation
 
-Description: Ensures every function declaration has a JSDoc comment with an `@story` annotation referencing the related user story. When you adopt multi-story `@supports` annotations, this rule also accepts `@supports` as an alternative way to prove story coverage, so either `@story` or at least one `@supports` tag will satisfy the presence check. When run with `--fix`, the rule inserts a single-line placeholder JSDoc `@story` annotation above missing functions, methods, TypeScript declare functions, and interface method signatures using a built-in template aligned with Story 008.0. This template is now configurable on a per-rule basis, and the rule exposes an explicit auto-fix toggle so you can choose between diagnostic-only behavior and automatic placeholder insertion. The default template remains aligned with Story 008.0, but you can now customize it per rule configuration and optionally disable auto-fix entirely when you only want diagnostics without edits.
+Description: **Legacy function-level key:** This rule key is retained for backward compatibility and conceptually composes the same checks as `traceability/require-traceability`. New configurations should normally enable `traceability/require-traceability` instead and rely on this key only when you need to tune it independently. Ensures every function declaration has a traceability annotation, preferring `@supports` for story coverage while still accepting legacy `@story` annotations referencing the related user story. When you adopt multi-story `@supports` annotations, this rule also accepts `@supports` as an alternative way to prove story coverage, so either `@story` or at least one `@supports` tag will satisfy the presence check. When run with `--fix`, the rule inserts a single-line placeholder JSDoc `@story` annotation above missing functions, methods, TypeScript declare functions, and interface method signatures using a built-in template aligned with Story 008.0. This template is now configurable on a per-rule basis, and the rule exposes an explicit auto-fix toggle so you can choose between diagnostic-only behavior and automatic placeholder insertion. The default template remains aligned with Story 008.0, but you can now customize it per rule configuration and optionally disable auto-fix entirely when you only want diagnostics without edits.
 
 Options:
 
@@ -32,6 +43,7 @@ Options:
 - `annotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for functions and non-method constructs. When omitted or blank, the built-in template from Story 008.0 is used.
 - `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for class methods and TypeScript method signatures. When omitted or blank, falls back to `annotationTemplate` if provided, otherwise the built-in template.
 - `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode.
+- `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions (for example, Jest/Mocha/Vitest `describe`/`it`/`test`/`beforeEach`/`afterEach`/`beforeAll`/`afterAll`, plus focused/skipped/concurrent variants such as `fdescribe`, `xdescribe`, `fit`, `xit`, `test.concurrent`, `describe.concurrent`) from function-level annotation requirements. This assumes those test files are already covered by file-level `@supports` annotations and `traceability/require-test-traceability`. When set to `false`, these callbacks are treated like any other arrow function and must be annotated when in-scope.
 
 Default Severity: `error`
 Example:
@@ -46,9 +58,11 @@ function initAuth() {
 }
 ```
 
+Among the supported scopes, anonymous callbacks passed directly to common test framework functions are excluded from annotation requirements by default via `excludeTestCallbacks`; projects that prefer stricter enforcement for these callbacks can disable this exclusion by setting `excludeTestCallbacks: false` in their rule configuration.
+
 ### traceability/require-req-annotation
 
-Description: Ensures that function-like constructs consistently declare their linked requirement using an `@req` annotation in JSDoc. The rule targets the same function-like node types as `traceability/require-story-annotation` (standard function declarations, non-arrow function expressions used as callbacks or assignments, class/object methods, TypeScript declare functions, and interface method signatures), and enforces that each of them has at least one `@req` tag in the nearest associated JSDoc comment. When you adopt multi-story `@supports` annotations, this rule also treats `@supports story-path REQ-ID...` tags as satisfying the requirement coverage check, although deep verification of requirement IDs continues to be handled by `traceability/valid-req-reference`. Arrow functions (`ArrowFunctionExpression`) are not currently checked by this rule.
+Description: **Legacy function-level key:** This rule key is retained for backward compatibility and conceptually composes the same checks as `traceability/require-traceability`. New configurations should normally enable `traceability/require-traceability` instead and rely on this key only when you need to tune it independently. Ensures that function-like constructs consistently declare their linked requirements via traceability annotations, preferring `@supports` when possible while still accepting `@req`. The rule targets the same function-like node types as `traceability/require-story-annotation` (standard function declarations, non-arrow function expressions used as callbacks or assignments, class/object methods, TypeScript declare functions, and interface method signatures), and enforces that each of them has at least one `@req` tag in the nearest associated JSDoc comment. When you adopt multi-story `@supports` annotations, this rule also treats `@supports story-path REQ-ID...` tags as satisfying the requirement coverage check, although deep verification of requirement IDs continues to be handled by `traceability/valid-req-reference`. Arrow functions (`ArrowFunctionExpression`) are not currently checked by this rule.
 
 This rule is typically used alongside `traceability/require-story-annotation` so that each function-level traceability block includes both an `@story` and an `@req` annotation, but it can also be enabled independently if you only want to enforce requirement linkage. Unlike `traceability/require-story-annotation`, this rule does not currently provide an auto-fix mode for inserting placeholder `@req` annotations; it only reports missing or malformed requirement annotations on the configured scopes.
 
@@ -72,7 +86,7 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have both `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
+Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have traceability coverage, typically via a single `@supports` line, while still accepting legacy `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
 
 For most branches, the rule looks for annotations in comments immediately preceding the branch keyword (for example, the line above an `if` or `for` statement). For `catch` clauses and `else if` branches, the rule is formatter-aware and accepts annotations in additional positions that common formatters like Prettier use when they reflow code.
 
@@ -112,7 +126,7 @@ if (error) {
 
 ### traceability/valid-annotation-format
 
-Description: Validates that all traceability annotations (`@story`, `@req`) follow the correct JSDoc or inline comment format. When run with `--fix`, the rule limits changes to safe `@story` path suffix normalization only—for example, adding `.md` when the path ends with `.story`, or adding `.story.md` when the base path has no extension—using targeted replacements implemented in the `getFixedStoryPath` and `reportInvalidStoryFormatWithFix` helpers. It does not change directories, infer new story names, or modify any surrounding comment text or whitespace, in line with Story 008.0. Selective disabling of this suffix-normalization auto-fix behavior is available via the `autoFix` option, which defaults to `true` for backward compatibility.
+Description: Validates that all traceability annotations (`@supports` as the preferred form for new code, plus legacy `@story` and `@req`) follow the correct JSDoc or inline comment format. When run with `--fix`, the rule limits changes to safe `@story` path suffix normalization only—for example, adding `.md` when the path ends with `.story`, or adding `.story.md` when the base path has no extension—using targeted replacements implemented in the `getFixedStoryPath` and `reportInvalidStoryFormatWithFix` helpers. It does not change directories, infer new story names, or modify any surrounding comment text or whitespace, in line with Story 008.0. Selective disabling of this suffix-normalization auto-fix behavior is available via the `autoFix` option, which defaults to `true` for backward compatibility.
 
 Options:
 
@@ -150,21 +164,34 @@ The `valid-annotation-format` rule is intentionally **backward compatible** with
 Deep requirement checking for both `@req` and `@supports` is handled by the `valid-req-reference` rule in the plugin's internal docs. Advanced edge cases and internal semantics are mainly of interest to maintainers; typical end users can rely on the options and examples in this API reference when configuring the rule for their projects.
 
 Default Severity: `error`
-Example:
+
+Primary example (recommended `@supports` style):
+
+```javascript
+/**
+ * @supports docs/stories/005.0-DEV-VALIDATION.story.md#REQ-FORMAT-VALIDATION
+ */
+function example() {
+  // ...
+}
+```
+
+Legacy example (`@story` + `@req`, still valid but not preferred for new code):
 
 ```javascript
 /**
  * @story docs/stories/005.0-DEV-VALIDATION.story.md
  * @req REQ-FORMAT-VALIDATION
  */
-function example() {
+function legacyExample() {
   // ...
 }
 ```
 
 ### traceability/valid-story-reference
 
-Description: Checks that the file paths in `@story` annotations point to existing story markdown files.
+Description: Checks that the story file paths used by traceability annotations point to existing story markdown files in an `@supports`‑first world. Modern code typically encodes story paths in `@supports` tags (for example, `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-ID`), but this rule continues to operate on the underlying `@story` values for file‑existence checks, keeping legacy annotations and mixed blocks fully supported.
+
 Options:
 Configure rule behavior using an options object with these properties:
 
@@ -190,31 +217,57 @@ Example configuration:
 ```
 
 Default Severity: `error`
-Example:
+
+Primary example (recommended `@supports` style, with a companion `@story` used for existence checks):
+
+```javascript
+/**
+ * @supports docs/stories/006.0-DEV-STORY-EXISTS.story.md#REQ-STORY-EXISTS
+ * @story docs/stories/006.0-DEV-STORY-EXISTS.story.md // used for file-existence validation; kept for backward compatibility
+ */
+function example() {
+  // ...
+}
+```
+
+Legacy-only example (`@story` + `@req`, still supported as an input to this rule):
 
 ```javascript
 /**
  * @story docs/stories/006.0-DEV-STORY-EXISTS.story.md
  * @req REQ-STORY-EXISTS
  */
-function example() {
+function legacyExample() {
   // ...
 }
 ```
 
 ### traceability/valid-req-reference
 
-Description: Verifies that the IDs used in `@req` annotations match known requirement identifiers.
+Description: Verifies that the requirement IDs used in traceability annotations match known requirement identifiers, whether they appear in modern `@supports` tags or in legacy `@req` annotations.
+
 Options: None
 Default Severity: `error`
-Example:
+
+Primary example (recommended `@supports` style with requirement IDs):
+
+```javascript
+/**
+ * @supports docs/stories/007.0-DEV-REQ-REFERENCE.story.md#REQ-VALID-REFERENCE REQ-VALID-REFERENCE-EDGE
+ */
+function example() {
+  // ...
+}
+```
+
+Legacy example (`@story` + `@req`, still valid for backward compatibility):
 
 ```javascript
 /**
  * @story docs/stories/007.0-DEV-REQ-REFERENCE.story.md
  * @req REQ-VALID-REFERENCE
  */
-function example() {
+function legacyExample() {
   // ...
 }
 ```
@@ -296,12 +349,14 @@ Behavior notes:
 
 Default Severity: `warn`
 
-This rule is **not** enabled in the `recommended` or `strict` presets by default. To use it, add it explicitly to your ESLint configuration with an appropriate severity level:
+This rule is enabled at severity `warn` in both the `recommended` and `strict` presets. You can override its behavior in your own configuration — for example, by raising it to `error` for stricter enforcement, or by explicitly disabling it if you prefer to keep statement-level duplication.
+
+Configuration example (override preset severity from `warn` to `error`):
 
 ```jsonc
 {
   "rules": {
-    "traceability/no-redundant-annotation": "warn",
+    "traceability/no-redundant-annotation": "error",
   },
 }
 ```
@@ -327,7 +382,7 @@ Main behaviors:
 
    ```js
    /**
-    * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND REQ-PAYMENTS-EDGE
+    * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND REQ-PAYMENTS-REFUND-EDGE
     */
    ```
 
@@ -432,6 +487,7 @@ Core rules enabled by the `recommended` preset:
 - `traceability/valid-story-reference`: `error`
 - `traceability/valid-req-reference`: `error`
 - `traceability/require-test-traceability`: `error`
+- `traceability/no-redundant-annotation`: `warn`
 
 Usage:
 

package/user-docs/examples.md

@@ -43,7 +43,21 @@ npx eslint "src/**/*.js"
 
 ## 3. CLI Invocation Example
 
-You can use the plugin without a config file by specifying rules inline:
+You can use the plugin without a config file by specifying rules inline. The recommended approach for new setups is to use the unified `traceability/require-traceability` rule:
+
+```bash
+npx eslint --no-eslintrc \
+  --rule "traceability/require-traceability:error" \
+  sample.js
+```
+
+This unified function-level rule enforces both story and requirement coverage via `@supports` (preferred) or, for backward compatibility, via legacy `@story`/`@req` annotations.
+
+Replace `sample.js` with your JavaScript or TypeScript file.
+
+### 3.1 Legacy aliases (for existing configurations)
+
+If you have older configurations that already refer to the legacy keys `traceability/require-story-annotation` and `traceability/require-req-annotation`, you can still enable them explicitly to avoid breaking those setups:
 
 ```bash
 npx eslint --no-eslintrc \
@@ -53,9 +67,7 @@ npx eslint --no-eslintrc \
 ```
 
 - `--no-eslintrc` tells ESLint to ignore user configs.
-- `--rule` options enable the traceability rules you need.
-
-Replace `sample.js` with your JavaScript or TypeScript file.
+- `--rule` options enable either the unified rule (recommended for new configurations) or the legacy aliases when you must preserve older setups.
 
 ## 4. Linting a Specific Directory
 
@@ -103,6 +115,9 @@ describe("Story 021.0-DEV-TEST-TRACEABILITY", () => {
     // Act
     const result = performOperation(input);
 
+    // Assert
+    const result = performOperation(input);
+
     // Assert
     expect(result).toBe("edge-ok");
   });
@@ -125,13 +140,11 @@ In this version, annotations are placed immediately before each significant bran
 
 ```ts
 function pickCategory(score: number): string {
-  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-  // @req REQ-BRANCH-DETECTION
+  // @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION
   if (score >= 80) {
     return "high";
   }
-  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-  // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+  // @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF
   else if (score >= 50) {
     return "medium";
   }
@@ -156,13 +169,11 @@ Prettier may reflow your `else if` line, wrap the condition, or move comments in
 
 ```ts
 function pickCategory(score: number): string {
-  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-  // @req REQ-BRANCH-DETECTION
+  // @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION
   if (score >= 80) {
     return "high";
   } else if (score >= 50) {
-    // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-    // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+    // @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF
     return "medium";
   } else {
     return "low";
@@ -173,6 +184,6 @@ function pickCategory(score: number): string {
 Depending on your Prettier version and configuration, the exact layout of the `else if` line and braces may differ, but as long as your annotations are in one of the supported locations, the rule will accept them.
 
 - Notes:
-  - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch.
+  - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch. Branches can be annotated either with a single `@supports` line (preferred), or with the older `@story`/`@req` pair for backward compatibility. The rule treats a valid `@supports` annotation as satisfying both the story and requirement presence checks.
   - For `catch` clauses and `else if` branches, the rule is formatter-aware and also looks at comments between the condition and the block, as well as the first comment-only lines inside the block body, so you do not need to fight Prettier if it moves your annotations.
   - When annotations exist in more than one place around an `else if` branch, the rule prefers comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body, matching the behavior described in the API reference and stories `025.0` and `026.0`.

package/user-docs/migration-guide.md

@@ -46,7 +46,7 @@ The following diff shows a typical migration in **your own project**, where `doc
 
 ### 3.1 Multi-story `@supports` annotations
 
-Starting in v1.x, `eslint-plugin-traceability` supports an additional annotation form for integration code that implements requirements from multiple stories in a consuming project. The following snippet shows one example of how you might structure such an annotation in **your** codebase:
+Starting in v1.x, `eslint-plugin-traceability` introduces and prefers the `@supports` annotation for integration code that implements requirements from multiple stories in a consuming project. The following snippet shows one example of how you might structure such an annotation in **your** codebase:
 
 ```js
 /**
@@ -102,10 +102,20 @@ Aligned with the internal rule behavior, the key cases are:
   The following are **ignored** by this rule and remain valid:
   - Comments that contain only `@story` lines,
   - Comments that contain only `@req` lines,
-  - Comments that contain only `@supports` lines, and
-  - Line comments such as `// @story ...`.
+  - Comments that contain only `@supports` lines.
 
-  These forms are still supported by the plugin and are not modified by `traceability/prefer-supports-annotation`.
+  Line comments are treated more selectively:
+  - Simple, consecutive line comments such as:
+
+    ```js
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED
+    function initAuth() {}
+    ```
+
+    that are directly attached to a function, method, or branch and describe exactly one story path plus one or more requirement IDs can now be migrated automatically. When the rule is enabled and you run ESLint with `--fix`, these are consolidated into a single `// @supports ...` line that preserves the same story path and requirement IDs.
+
+  - More complex inline patterns — for example, mixed traceability and non-traceability content, multiple distinct `@story` paths, or interleaved unrelated comments between `@story` and `@req` lines — are still reported but are **not** auto-fixed. In these cases, the rule continues to treat unsupported inline shapes conservatively, emitting diagnostics and leaving the comments unchanged so you can adjust them manually.
 
 A typical migration path is:
 
@@ -133,6 +143,8 @@ export function initAuth() {
 }
 ```
 
+These `@story` and `@req` forms are treated as a legacy single-story style that remains valid for simple cases, while new multi-story integrations should prefer `@supports` as the primary format.
+
 #### When to introduce `@supports`
 
 Adopt `@supports` for **multi-story integration** code, especially when:
@@ -183,6 +195,7 @@ You can introduce `@supports` gradually without breaking existing code:
 
 1. Leave existing `@story` and `@req` annotations in place.
 2. Add `@supports` lines that group requirements by story file.
+   Over time, teams are encouraged to converge on `@supports` as the canonical format for multi-story integrations, keeping `@story`/`@req` primarily for simple, single-story cases.
 3. Run ESLint with `traceability/valid-annotation-format` and `traceability/valid-req-reference` enabled to confirm everything passes.
 4. Optionally, once you are comfortable, standardize on using `@supports` for multi-story integration functions while keeping `@story` + `@req` for simple, single-story code.
 
@@ -197,6 +210,116 @@ Versions 1.x of `eslint-plugin-traceability` extend the `traceability/require-br
 
 If you previously added suppressions or workaround comments around `else if` branches due to formatter conflicts, you can usually remove those workarounds after upgrading to 1.x as long as your annotations live in one of the supported locations. For new code, you can place annotations either directly above the `else if` or, when you know a formatter will wrap a long condition, on the first comment-only line inside the consequent block body, which is where the rule places auto-fix placeholders by default.
 
+### 3.3 Redundant traceability annotation cleanup
+
+As you move toward an **`@supports`-first** style while still supporting legacy `@story`/`@req`, v1.x adds `traceability/no-redundant-annotation` to help clean up redundant **statement-level** annotations that often accumulate during migration and refactoring.
+
+This rule is enabled as `"warn"` in the built-in recommended presets, so you automatically get guidance without breaking existing builds.
+
+At a high level, the rule targets common duplication patterns where multiple adjacent statements or branches repeat the **same story/requirement coverage**, for example:
+
+- **Branch + statement duplication** — the `if`/`else` branch is annotated, and the first statement inside the block repeats the exact same coverage.
+- **Sequential simple statements** — back‑to‑back statements each carry identical traceability, even though they form a single logical step.
+- **Trivial returns** — a branch and an immediately returning statement both repeat the same story/requirement pair.
+
+In all cases, the rule is conservative:
+
+- It **never removes the last annotation** that provides coverage for a given `(story path, requirement ID)` pair.
+- It prefers to keep annotations in the positions that are easiest to reason about (for example, on the controlling branch or on the first statement in a short sequence), and trims only clearly redundant copies.
+
+The rule operates over both `@supports` and legacy `@story`/`@req` style annotations, so it continues to work even in mixed codebases during a long-running migration.
+
+A simplified example, using an illustrative story path that represents a file in **your** documentation tree:
+
+Before (redundant duplication inside a branch):
+
+```js
+if (!user) {
+  // @supports docs/stories/010.0-AUTH-SESSION-MANAGEMENT.story.md REQ-UNAUTH-REDIRECT
+  // @supports docs/stories/010.0-AUTH-SESSION-MANAGEMENT.story.md REQ-UNAUTH-REDIRECT
+  return redirectToLogin();
+}
+```
+
+After (`no-redundant-annotation` auto-fix, coverage preserved but duplication removed):
+
+```js
+if (!user) {
+  // @supports docs/stories/010.0-AUTH-SESSION-MANAGEMENT.story.md REQ-UNAUTH-REDIRECT
+  return redirectToLogin();
+}
+```
+
+Another example where the branch and first statement are both annotated with the same coverage:
+
+Before:
+
+```js
+// @supports docs/stories/020.0-ORDERS-CHECKOUT.story.md REQ-CALCULATE-TOTAL
+if (cart.items.length === 0) {
+  // @supports docs/stories/020.0-ORDERS-CHECKOUT.story.md REQ-CALCULATE-TOTAL
+  return 0;
+}
+```
+
+After (keep coverage at the branch, drop the redundant inner statement annotation):
+
+```js
+// @supports docs/stories/020.0-ORDERS-CHECKOUT.story.md REQ-CALCULATE-TOTAL
+if (cart.items.length === 0) {
+  return 0;
+}
+```
+
+#### Safe migration workflow
+
+To use `traceability/no-redundant-annotation` safely during your v1.x migration:
+
+1. **Start from the recommended preset**
+
+   Make sure your ESLint flat config includes the plugin’s recommended config (which enables this rule as `"warn"`):
+
+   ```js
+   import traceability from "eslint-plugin-traceability";
+
+   export default [traceability.configs.recommended];
+   ```
+
+2. **Run ESLint without auto-fix**
+
+   Run ESLint without `--fix` to review the warnings:
+
+   ```bash
+   npm run lint
+   ```
+
+   Look for diagnostics from `traceability/no-redundant-annotation` and confirm that the suggested removals match your expectations.
+
+3. **Run with `--fix` once comfortable**
+
+   When you are satisfied with the behavior, re-run ESLint with auto-fix enabled to apply safe cleanups in bulk:
+
+   ```bash
+   npm run lint -- --fix
+   ```
+
+4. **Optionally tighten over time**
+
+   As your team gets comfortable:
+   - You can raise the rule severity to `"error"` for new code, and/or
+   - Increase strictness via configuration (see below) to catch more subtle forms of duplication.
+
+#### Key configuration knobs
+
+The full API reference documents all options, but the most important knobs for migration are:
+
+- **`strictness`** — controls how aggressively the rule interprets “redundant.” Lower settings only remove obvious duplication; higher levels consider more complex patterns across nearby statements and branches.
+- **`allowEmphasisDuplication`** — when `true`, allows an explicit “emphasis” annotation to repeat coverage (for example, keeping a second comment in a particularly critical spot) without being reported as redundant.
+- **`maxScopeDepth`** — limits how far into nested blocks the rule looks when deciding what is redundant, which can be useful if you want very local cleanups only.
+- **`alwaysCovered`** — a safety valve that forces the rule to preserve at least one annotation for each `(story, requirement)` pair within the relevant scope, even under stricter modes.
+
+For most teams, the defaults in the recommended preset are a good starting point; you can then tune these options incrementally as your traceability style and `@supports` usage stabilize.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes:

package/user-docs/traceability-overview.md

@@ -0,0 +1,116 @@
+# Traceability Overview and FAQ
+
+Created autonomously by [voder.ai](https://voder.ai).
+
+This page gives a high-level overview of how to use `eslint-plugin-traceability` in day-to-day development and answers common questions about annotations, rules, and their relationship to legacy aliases.
+
+For detailed rule and option descriptions, see the [API Reference](api-reference.md). For concrete code samples, see the [Examples](examples.md) document.
+
+## Which annotations should I use?
+
+The plugin understands three annotation forms:
+
+- `@supports` – **Preferred for new code and multi-story integrations.**  
+  Use this when a function, module, or branch implements requirements from one or more stories. A single `@supports` tag can express both the story path and the requirement IDs it implements.
+- `@story` – Legacy story-level tag.  
+  Still valid and useful when a function is tied to a single story file and you have not yet migrated to `@supports`.
+- `@req` – Legacy requirement-level tag.  
+  Pairs naturally with `@story` for simple, single-story scenarios.
+
+Recommended usage:
+
+- For **new or refactored code**, prefer `@supports` as your primary annotation.
+- For **simple, single-story functions** that already use `@story` + `@req`, you can keep that style; there is no forced cut-over.
+- During migration, you can temporarily have both `@story`/`@req` and `@supports` in the same block; the core rules and the optional `traceability/prefer-supports-annotation` rule are designed to support this.
+
+The [Migration Guide](migration-guide.md) explains when and how to introduce `@supports` in more detail, including conservative auto-fix behavior.
+
+## Which ESLint rule should I enable for functions?
+
+For function-level checks, think in terms of a single canonical rule plus a small set of supporting rules.
+
+- `traceability/require-traceability` – **Canonical function-level rule for new configurations.**  
+  Ensures that in-scope functions and methods have both story and requirement coverage. It understands both `@supports` (preferred) and legacy `@story` / `@req` annotations.
+
+Most users can choose one of these options:
+
+1. **Use the recommended preset** (simplest):
+
+   ```js
+   // eslint.config.js
+   import js from "@eslint/js";
+   import traceability from "eslint-plugin-traceability";
+
+   export default [js.configs.recommended, traceability.configs.recommended];
+   ```
+
+   This enables `traceability/require-traceability` and the other core rules with sensible defaults.
+
+2. **Manually enable the unified rule and common helpers** (when you need custom tuning):
+
+   ```js
+   // eslint.config.js
+   import traceability from "eslint-plugin-traceability";
+
+   export default [
+     {
+       plugins: { traceability },
+       rules: {
+         // Canonical function-level rule
+         "traceability/require-traceability": "error",
+
+         // Common supporting rules
+         "traceability/require-branch-annotation": "warn",
+         "traceability/valid-annotation-format": "error",
+         "traceability/valid-story-reference": "error",
+         "traceability/valid-req-reference": "error",
+
+         // Optional: enforce test traceability conventions
+         "traceability/require-test-traceability": "warn",
+       },
+     },
+   ];
+   ```
+
+The same guidance is summarized in the README under **"Canonical function-level rule and legacy aliases"**.
+
+## What about the legacy alias rules?
+
+Two additional rule keys exist for backward compatibility:
+
+- `traceability/require-story-annotation`
+- `traceability/require-req-annotation`
+
+Key points:
+
+- They are **legacy aliases** that share the same underlying engine as `traceability/require-traceability`.
+- They are kept so that older configurations continue to work without change.
+- New configurations should **not** rely on these keys directly unless you have a specific reason to tune their severities independently.
+
+If you are starting from scratch, you can safely ignore the legacy keys and use only `traceability/require-traceability` together with the supporting rules listed above.
+
+## Do I have to migrate existing `@story` / `@req` annotations to `@supports`?
+
+No. Existing `@story` + `@req` annotations remain valid and fully supported.
+
+Typical migration path:
+
+1. Keep your current `@story` + `@req` annotations for simple, single-story functions.
+2. Introduce `@supports` gradually for integration code that naturally spans multiple stories.
+3. Optionally enable `traceability/prefer-supports-annotation` at `"warn"` to get gentle guidance and conservative auto-fixes for straightforward single-story blocks.
+4. Once you are comfortable, you can tighten enforcement or standardize on `@supports` for new multi-story work.
+
+See the [Migration Guide](migration-guide.md#31-multi-story-supports-annotations) for concrete before/after examples.
+
+## Where can I see concrete examples?
+
+- **Quick start and minimal config:** See the main [README](../README.md#quick-start).
+- **Full rule list and options:** See the [API Reference](api-reference.md#rules).
+- **End-to-end examples:** See the [Examples](examples.md) document, including:
+  - Flat-config snippets using the recommended and strict presets.
+  - CLI usage with the unified rule and clearly labeled legacy-alias examples.
+  - Test traceability examples using `traceability/require-test-traceability`.
+  - Branch annotation patterns that work well with formatters such as Prettier.
+- **Migration guidance:** See the [Migration Guide](migration-guide.md).
+
+These resources are designed to be complementary: start with this overview to choose the right annotations and rules, then refer to the API reference and examples when you need exact configuration shapes or runnable code samples.